---
title: Tienhiep Backend
emoji: 📚
colorFrom: indigo
colorTo: purple
sdk: docker
dockerfile: Dockerfile.hf
app_port: 7860
pinned: false
---

# 📚 Tiên Hiệp AI (TienHiepAI) — Nền Tảng Đọc Truyện & Dịch Offline

Chào mừng bạn đến với kho lưu trữ mã nguồn của dự án **Tiên Hiệp AI**. Đây là hệ thống tích hợp toàn diện bao gồm Giao diện Web, Ứng dụng Desktop (Electron), Máy chủ dịch thuật nâng cao và Động cơ chuyển đổi văn bản thành giọng nói (TTS) tiếng Việt ngoại tuyến chạy trên CPU cực nhanh.

---

## 📂 Cấu Trúc Thư Mục Dự Án

* 🖥️ **`frontend-web/`**: Mã nguồn giao diện chính viết bằng React + Vite. Hỗ trợ chạy chế độ Web và đóng gói Electron Desktop.
* 🎙️ **`TTS_ONNX_Deploy/`**: Động cơ chuyển giọng đọc (TTS) offline tiếng Việt đã được tối ưu hóa `int8` chạy trên CPU bằng ONNX Runtime (Matcha-TTS + Vocos).
* ⚙️ **`backend/`** & **`viewer_server.py`**: Mã nguồn máy chủ xử lý tác vụ dịch thuật (Vietphrase, ngữ cảnh nâng cao, từ điển Hán Việt, Trung-Việt) và lưu trữ lịch sử đọc truyện.
* 🛠️ **`scratch/`**: Các kịch bản phụ trợ để kiểm thử, vá lỗi động cơ, tự động hóa đóng gói và nạp cơ sở dữ liệu.

---

## ⚡ Hướng Dẫn Chạy & Cài Đặt Nhanh (Quick Start)

### 1. Chuẩn bị môi trường Python & Thư viện
Mã nguồn yêu cầu Python phiên bản từ `3.8` đến `3.10`.
Cài đặt toàn bộ các thư viện cần thiết bằng lệnh:
```bash
pip install -r requirements.txt
```

### 2. Tải các tệp Checkpoint mô hình ONNX
Các mô hình ONNX đã được lưu trữ trên Hugging Face. Để chạy động cơ TTS, hãy tải hai file sau về và đặt vào thư mục `TTS_ONNX_Deploy/`:
* 📥 [matcha_tts_int8.onnx](https://huggingface.co/datasets/Cong123779/Local-TTS-Engine/resolve/main/matcha_tts_int8.onnx) (19.23 MB)
* 📥 [vocos_decoupled_int8.onnx](https://huggingface.co/datasets/Cong123779/Local-TTS-Engine/resolve/main/vocos_decoupled_int8.onnx) (13.03 MB)

Lệnh tải nhanh qua `curl` (chạy từ thư mục `TTS_ONNX_Deploy/`):
```bash
curl -L https://huggingface.co/datasets/Cong123779/Local-TTS-Engine/resolve/main/matcha_tts_int8.onnx --output matcha_tts_int8.onnx
curl -L https://huggingface.co/datasets/Cong123779/Local-TTS-Engine/resolve/main/vocos_decoupled_int8.onnx --output vocos_decoupled_int8.onnx
```

### 3. Chạy các máy chủ phát triển (Dev Mode)

* **Chạy máy chủ Dịch thuật & Dữ liệu:**
  ```bash
  python viewer_server.py
  ```
* **Chạy máy chủ TTS Offline:**
  ```bash
  cd TTS_ONNX_Deploy
  python api_server.py
  ```
* **Chạy giao diện Web (React):**
  ```bash
  cd frontend-web
  npm install
  npm run dev
  ```

---

## 📦 Hướng Dẫn Đóng Gói Ứng Dụng (Release & Packaging)

### A. Đóng gói ứng dụng Desktop (Electron Setup EXE / AppImage)
Sử dụng công cụ tự động hóa đóng gói và phát hành `release.py` (tự động tăng version, biên dịch giao diện, đóng gói đa nền tảng và đồng bộ lên database):
```bash
python release.py patch
```

### B. Đóng gói động cơ TTS chạy độc lập (`App_Doc_Truyen_Engine.exe`)
Sử dụng cấu hình PyInstaller đã được tối ưu hóa dung lượng (lọc bỏ PyTorch và các dependency cồng kềnh) để biên dịch động cơ TTS thành một file chạy duy nhất trên Windows:
```bash
cd TTS_ONNX_Deploy
pip install pyinstaller
pyinstaller App_Doc_Truyen_Engine.spec
```
Sau khi chạy xong, thư mục đóng gói nằm tại `TTS_ONNX_Deploy/dist/App_Doc_Truyen_Engine/`.

---

## 🛠️ Tính Năng Tự Động Vá Lỗi Vừa Được Cập Nhật
* **Isolate Espeak (Lazy Import)**: Đã cô lập hoàn toàn lõi espeak-ng. Ứng dụng khi chạy trên các máy Windows không cài espeak sẽ tự động chuyển sang chế độ fallback an toàn mà không bị crash.
* **Auto Engine Extract**: Ứng dụng Electron khi khởi động lần đầu sẽ tự động tải tệp nén động cơ `windows_cpu.zip` từ Hugging Face, giải nén và tự cấu hình kết nối.