---
title: HachimiMT — Dịch Trung Việt
emoji: 📜
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 6.18.0
app_file: app.py
pinned: false
short_description: Dịch truyện Trung → Việt
---

# HachimiMT — Dịch Trung Việt

Công cụ dịch truyện tiếng Trung sang tiếng Việt, dùng các model MarianMT trên Hugging Face:

- [HachimiMT-60-zh-vi](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi)
- [HachimiMT-30-zh-vi](https://huggingface.co/ngocdang83/HachimiMT-30-zh-vi)
- [MoxhiMT-60](https://huggingface.co/DanVP/MoxhiMT-60)
- [MoxhiMT-30](https://huggingface.co/DanVP/MoxhiMT-30)
- [HirashibaMT-Medium](https://huggingface.co/Moleys/hirashiba-mt-medium) (CT2 mirror: [ngungodan/hirashiba-mt-medium-ct2](https://huggingface.co/ngungodan/hirashiba-mt-medium-ct2))
- [HirashibaMT-Tiny](https://huggingface.co/chi-vi/hirashiba-mt-tiny-zh-vi) (CT2 mirror: [ngungodan/hirashiba-mt-tiny-zh-vi-ct2](https://huggingface.co/ngungodan/hirashiba-mt-tiny-zh-vi-ct2))

> Có script sẵn cho **Windows** (`setup.bat` / `start.bat`) và **macOS** (`setup_macos.sh` / `start_macos.sh`). Linux có thể dùng gần giống macOS.

## Tính năng

- Chọn model dịch (HachimiMT / MoxhiMT / HirashibaMT)
- Dịch văn bản trực tiếp với **đối chiếu song song** theo từng câu/đoạn
- Dịch file `.txt` và tải bản dịch
- **CTranslate2 INT8** (mặc định) — nhanh hơn nhiều so với PyTorch, hỗ trợ batch inference
- Tuỳ chọn hậu kỳ xưng hô:
  - Hán-Việt hoá thân tộc/đại từ theo nguồn (`tỷ/muội/ca ca`, `ngươi/hắn/nàng/ta`)
  - Ổn định ngôi xưng hiện đại V9 beta (`thầy/em`, `mẹ/con`, `anh/em`, phỏng vấn/nhà trường, giữ `ta/ngươi` ở đoạn tiên hiệp/độc thoại)
- **Tự nhận cấu hình máy**: CPU/GPU, số luồng, VRAM → tự chọn batch/thread phù hợp. Máy yếu hay mạnh đều chạy được, chỉ khác tốc độ.
- Tự nhận GPU NVIDIA khi có sẵn thư viện CUDA (qua torch CUDA); nếu không thì chạy CPU an toàn, không crash. Xem mục "Chạy bằng GPU NVIDIA".

## Về model (tải từ Hugging Face)

Repo **không kèm sẵn model** (quá nặng cho git). Model tự tải từ Hugging Face vào thư mục `models/` **theo nhu cầu** (lazy):

- `setup.py` chỉ tải sẵn **1 model mặc định** (HachimiMT-60, bản CT2 ~57 MB) để dùng được ngay.
- Các model khác trong danh sách **chỉ tải khi bạn chọn dịch lần đầu** — nên thêm bao nhiêu model vào app cũng không làm setup nặng thêm.
- Trên giao diện, mỗi model có **badge trạng thái**: "✓ Đã tải — dịch được ngay" hoặc "⬇ Chưa có (~XX MB) — sẽ tự tải...". Khi bấm Dịch model chưa có, thanh tiến trình báo rõ "Đang tải … từ Hugging Face".
- Mỗi model tải **một lần duy nhất**; lần sau dùng lại từ `models/`, không tải lại.
- Đổi sang **engine PyTorch** thì cần cài thêm nhóm dependency PyTorch; app sẽ tự tải weights PyTorch (nặng hơn) ở lần dịch đầu với engine đó.
- Cần **internet** khi tải model lần đầu. Sau đó chạy offline được.

> Mẹo: muốn mang sang máy không có internet thì copy luôn thư mục `models/` đã tải sang — các model đã tải sẽ chạy ngay.

### Thêm model mới vào app

Mở `src/translator.py`, thêm một mục vào dict `MODELS` (xem 2 model có sẵn làm mẫu). Lưu ý:
- `model_id`: đường dẫn repo HF (vd `DanVP/MoxhiMT-60`).
- `ct2_model_id`: chỉ cần khai khi bản CT2 nằm ở repo khác với model gốc.
- `ct2_subdir`: tên thư mục chứa bản CT2 trên repo — **mặc định `ct2-int8_float32`**; nếu repo dùng tên khác (vd `ct2-int8`) thì khai lại.
- `ct2_size_mb`: dung lượng bản CT2 (để badge hiện "~XX MB"); để trống cũng được.
- `use_marian_class`: `True` nếu config.json của model ghi `MarianMTModel`.

Không cần sửa gì thêm — model mới sẽ tự xuất hiện trong dropdown và lazy-download khi dùng.

## Cài đặt (Windows)

**Cách nhanh:** chạy `setup.bat` rồi `start.bat`. Script sẽ cài các thư viện mặc định cho CTranslate2, tải model CT2 mặc định, và mở trình duyệt. Mặc định **không cài torch**.

**Cách thủ công** (nếu muốn dùng virtual environment — khuyến khích):

```bat
cd D:\Projects\qt2
python -m venv .venv
.venv\Scripts\activate

:: 1) Cài phần mặc định: CTranslate2 + Gradio + tokenizer tooling
pip install -r requirements.txt

:: 2) Tải model lần đầu (~57 MB — chỉ model CT2 mặc định, một lần duy nhất)
cd src
python setup.py
```

### Chạy bằng GPU NVIDIA (nhanh hơn nhiều)

Engine mặc định là **CTranslate2** và chạy CPU. Để CTranslate2 dùng GPU NVIDIA, máy cần có **thư viện CUDA (cuBLAS/cuDNN)** — thường đi kèm khi bạn cài bản **torch CUDA**. Sau đó app tự nhận GPU, không cần đổi gì khác. GPU nhanh hơn CPU **nhiều lần** với văn bản dài (đo thực tế: gấp ~16× khi dịch hàng nghìn câu).

**Cách dễ nhất — nút ngay trong app (không cần terminal):** nếu máy có GPU NVIDIA mà app đang chạy CPU, giao diện sẽ hiện khối **"⚡ Phát hiện GPU… Cài torch để bật GPU"**. Bấm nút đó, app tự chọn đúng bản torch CUDA theo driver và cài (tải ~2–3 GB, cần ~5 GB ổ trống, một lần). App **tự kiểm tra** cả torch CUDA lẫn CTranslate2 CUDA sau khi cài; xong thì **tắt và mở lại app** (`stop.bat` rồi `start.bat`) là chạy GPU. Nếu thích cài tay thì xem lệnh bên dưới.

> ⚠️ **Lưu ý quan trọng (lỗi `cublas64_12.dll not found`):** CTranslate2 tự dò GPU NVIDIA **độc lập với torch**. Nếu máy **có GPU NVIDIA nhưng chưa cài torch CUDA**, CT2 sẽ cố dùng GPU rồi crash vì thiếu `cublas64_12.dll` (DLL này do torch CUDA cung cấp). Để tránh, app **tự động ép CT2 chạy CPU** khi không tìm thấy torch CUDA — nên mặc định bạn sẽ **không** gặp lỗi này, chỉ là chạy CPU.
>
> - Muốn GPU: cài **torch CUDA** (lệnh bên dưới) → app tự bật GPU.
> - Đã có cuBLAS sẵn (vd cài CUDA Toolkit riêng) và muốn ép CT2 dùng GPU dù không có torch: đặt biến môi trường `HACHIMIMT_FORCE_CT2_CUDA=1` trước khi chạy (tự chịu trách nhiệm nếu thiếu DLL).

Torch chỉ cần khi bạn muốn GPU cho CT2 (như trên) hoặc đổi sang backend **PyTorch** thử nghiệm. Backend PyTorch nặng hơn và thường chậm hơn CT2. Nếu muốn dùng PyTorch:

```bat
:: CPU-only PyTorch
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements-pytorch.txt

:: hoặc PyTorch CUDA cho NVIDIA, chọn đúng bản tại pytorch.org
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements-pytorch.txt
```

Lệnh chính xác cho từng cấu hình lấy tại <https://pytorch.org/get-started/locally/>.

## Cài đặt (macOS)

Yêu cầu Python 3.10+. Trên macOS, app chạy mặc định bằng **CTranslate2 CPU**. CTranslate2 hiện không dùng Apple GPU/Metal/MPS, nên Mac M-series vẫn chạy bằng CPU.

```bash
cd /path/to/qt2
chmod +x setup_macos.sh start_macos.sh stop_macos.sh
./setup_macos.sh
./start_macos.sh
```

Script macOS tạo `.venv`, cài dependencies mặc định **không có torch**, tải model CT2 mặc định, rồi chạy Gradio tại `http://127.0.0.1:7860`.

Nếu muốn thử backend PyTorch trên macOS, cài thêm torch trong venv:

```bash
source .venv/bin/activate
pip install torch
pip install -r requirements-pytorch.txt
```

Lưu ý: backend PyTorch hiện chưa được tối ưu riêng cho MPS/Apple GPU trong app này.

## Chạy

```bat
start.bat
```

hoặc thủ công:

```bat
cd src
python app.py
```

Mở trình duyệt tại `http://127.0.0.1:7860` (app chỉ chạy nội bộ trên máy, không mở ra mạng).

## Gợi ý sử dụng

- **Engine CTranslate2** (mặc định): bản INT8 có sẵn trên HF, dịch batch nhiều chunk cùng lúc.
- **Engine PyTorch**: tùy chọn thử nghiệm, cần cài thêm `torch` và `requirements-pytorch.txt`; thường chậm hơn CT2.
- **HachimiMT-30**: nhẹ nhất (~35 MB), phù hợp thử nghiệm hoặc máy yếu.
- **HirashibaMT-Medium**: model tham khảo không phải do repo này train; CT2 INT8 nằm ở repo phụ `ngungodan/hirashiba-mt-medium-ct2`.
- **HirashibaMT-Tiny**: model tham khảo rất nhẹ; CT2 phải dùng bản `ct2-int8-keeppad` vì stock converter không giữ đúng `<pad>` decoder-start của Marian tiny. App đặt beam mặc định 1 để tránh lặp nhẹ ở beam cao.
- Chia **theo câu** giúp giảm drift tên riêng trên văn bản dài (theo khuyến nghị của tác giả model).
- Model được train trên **giản thể** (简体). App mặc định chuyển **phồn thể → giản thể** trước khi dịch; có thể đổi về "Giữ nguyên" trong phần cấu hình.
- `Chuẩn hóa xưng hô thân tộc` xử lý lỗi kiểu `chị em` ↔ `tỷ muội` khi nguồn có `姐妹/姐姐/哥哥...`.
- `Ổn định ngôi xưng hiện đại V9 (beta)` là option riêng, tắt mặc định; dùng khi chương hiện đại bị nhảy `ta/tôi`, `ngươi/cậu`, `thầy/em`, `mẹ/con`, `anh/em`. V9 ưu tiên quan hệ có tín hiệu rõ như phỏng vấn/nhà trường, giáo viên-học sinh, mẹ-con, anh-em, khoản vay; các đoạn tiên hiệp/độc thoại vẫn có thể giữ `ta/ngươi` để tránh sửa quá tay.
- Route hậu kỳ dùng quyết định cấp chương: route hiện đại do V9 sở hữu đại từ, route cổ trang do normalizer Hán-Việt sở hữu đại từ, route mixed/unknown sẽ guard để tránh tự sửa sai.
- File `.txt` đầu vào hỗ trợ UTF-8/UTF-8 BOM/GB18030/GBK/Big5; bản dịch xuất ra UTF-8.

## Cấu hình tốc độ (tuỳ chọn)

App tự nhận CPU/GPU và chọn batch/thread theo máy. Có thể override bằng biến môi trường trước khi chạy:

```bat
set HACHIMIMT_BATCH_SIZE=72
set HACHIMIMT_THREADS=12
set HACHIMIMT_TOKENIZE_WORKERS=16
set HACHIMIMT_TOKENIZE_JOB_SIZE=32
set HACHIMIMT_CT2_WINDOW_MULTIPLIER=4
set HACHIMIMT_CT2_BATCH_TYPE=tokens
set HACHIMIMT_INTER_THREADS=1
set HACHIMIMT_COMPUTE_TYPE=int8_float16
set HACHIMIMT_PROGRESS_SECONDS=0.5
start.bat
```

- `HACHIMIMT_COMPUTE_TYPE`: mặc định GPU dùng `int8_float16`, CPU dùng `int8_float32`.
- `HACHIMIMT_BATCH_SIZE`: tăng nếu GPU còn rảnh VRAM; giảm nếu dịch lỗi/OOM.
- `HACHIMIMT_THREADS`: ngân sách thread CT2 tổng; khi có nhiều CT2 worker/replica, app tự chia `intra_threads` để tránh oversubscribe CPU.
- `HACHIMIMT_TOKENIZE_WORKERS`: tăng khi CPU còn rảnh và GPU chờ dữ liệu.
- `HACHIMIMT_TOKENIZE_JOB_SIZE`: số chunk mỗi tokenizer job; mặc định `32`.
- `HACHIMIMT_CT2_WINDOW_MULTIPLIER`: số batch đưa vào mỗi lần gọi CT2; mặc định `4`. Khi dùng multi-GPU + `batch_type=tokens`, app tự tăng window hiệu dụng để CT2 có đủ sub-batch chia việc cho các GPU.
- `HACHIMIMT_CT2_BATCH_TYPE`: mặc định `tokens`; đổi về `examples` nếu cần so sánh/fallback.
- `HACHIMIMT_INTER_THREADS`: mặc định `1`; chỉ tăng nếu benchmark chứng minh nhanh hơn.
- `HACHIMIMT_GPU_INDICES`: chọn GPU CT2, ví dụ `0`, `1`, hoặc `0,1`. Nếu không đặt, local PC mặc định dùng GPU `0`; Kaggle/Colab tự dùng toàn bộ GPU.
- `HACHIMIMT_AUTO_ALL_GPUS=1`: ép auto dùng toàn bộ GPU khi không đặt `HACHIMIMT_GPU_INDICES`; hữu ích khi chắc các GPU đồng cấu hình.
- `HACHIMIMT_PROGRESS_SECONDS`: giãn nhịp cập nhật UI progress; mặc định `0.5`.

## Linux (gõ lệnh tay)

Các bước tương đương macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd src && python setup.py        # tải model lần đầu
python app.py                    # chạy app
```

## Benchmark file

```bat
cd D:\Projects\qt2
python src\benchmark_file.py path\to\file.txt --model HachimiMT-60 --backend ct2 --beam 2 --chunk-mode sentence
```

Mặc định benchmark cũng chuẩn hóa phồn thể → giản thể như UI. Muốn tắt:

```bat
python src\benchmark_file.py path\to\file.txt --normalize none
```