# Hy-MT2: dịch đa ngôn ngữ nhanh — hướng dẫn cài đặt và dùng

> Hy-MT2 là họ mô hình dịch máy đa ngôn ngữ của Tencent Hunyuan, gồm bản 1.8B, 7B và 30B-A3B. Mô hình phù hợp để dịch văn bản thường, nội dung nghiệp vụ, dữ liệu có cấu trúc và yêu cầu giữ nguyên định dạng. Cài đặt cần Python cùng thư viện suy luận phù hợp; người mới có thể bắt đầu bằng Transformers.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-01 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/hy-mt2-dich-da-ngon-ngu-huong-dan

Hy-MT2 là họ mô hình dịch máy đa ngôn ngữ của Tencent Hunyuan, được thiết kế cho các tình huống dịch thực tế và các yêu cầu dịch có hướng dẫn rõ ràng. Repo có ba kích thước chính: 1.8B, 7B và 30B-A3B dạng MoE. Các bản này hỗ trợ dịch giữa 33 ngôn ngữ.

Điểm đáng chú ý là Hy-MT2 không chỉ dịch câu thông thường. Bạn có thể đưa thêm thuật ngữ tham chiếu, yêu cầu văn phong, quy tắc giữ nguyên dấu phân cách hoặc cấu trúc dữ liệu. Repo hiện có khoảng 1.748 sao và 185 fork, đồng thời vẫn còn được cập nhật. Đây là lựa chọn đáng xem nếu bạn muốn tự chạy mô hình dịch thay vì gửi toàn bộ nội dung lên một API thương mại.

```repo
- repo | Tencent-Hunyuan/Hy-MT2
- kind | Mô hình
- desc | Hy-MT2 là họ mô hình dịch máy đa ngôn ngữ, hỗ trợ 33 ngôn ngữ và nhiều kiểu dịch có ràng buộc.
- stars | 1.7k
- lang | Python
```

## Hy-MT2 làm được gì

- **Dịch giữa 33 ngôn ngữ.** Danh sách gồm tiếng Việt, tiếng Anh, tiếng Trung giản thể và phồn thể, tiếng Nhật, Hàn, Thái, Pháp, Đức, Tây Ban Nha, Ả Rập cùng nhiều ngôn ngữ khác. Điều này phù hợp với shop bán hàng xuyên biên giới, nhóm chăm sóc khách hàng và đội ngũ làm nội dung quốc tế.

- **Xử lý các yêu cầu dịch phức tạp.** Bạn có thể yêu cầu chỉ xuất bản dịch, không giải thích thêm; thêm bối cảnh; hoặc yêu cầu bản dịch theo một phong cách cụ thể. Cách dùng này giúp kết quả gần với quy trình biên tập thật hơn.

- **Giữ thuật ngữ nhất quán.** Prompt có thể chứa các cặp thuật ngữ mẫu, chẳng hạn tên sản phẩm hoặc cách dịch tên tính năng. Mô hình sẽ dùng phần tham chiếu đó khi dịch nội dung mới.

- **Bảo toàn dữ liệu có cấu trúc.** Repo đưa ra mẫu prompt cho JSON, HTML hoặc các định dạng tương tự. Bạn có thể yêu cầu chỉ dịch phần nội dung hiển thị, giữ nguyên khóa, thuộc tính, thẻ và biến thay thế.

- **Giữ dấu phân cách.** Với tài liệu có ký hiệu đặc biệt, bạn có thể yêu cầu giữ đúng số lượng, vị trí và nguyên dạng của dấu phân cách. Tính năng này hữu ích khi dịch phụ đề, mẫu biểu, chuỗi giao diện hoặc dữ liệu cần xử lý tự động.

- **Có nhiều lựa chọn kích thước và định dạng.** Bản 1.8B phù hợp hơn với máy hạn chế tài nguyên. Bản 7B cân bằng giữa chất lượng và tài nguyên. Bản 30B-A3B dành cho nhu cầu chất lượng cao hơn và có thể chạy qua Transformers, vLLM hoặc SGLang.

- **Có bản lượng tử hóa cho thiết bị.** Bản 1.8B dùng AngelSlim 1.25-bit có dung lượng lưu trữ được giới thiệu là khoảng 440 MB và tốc độ suy luận tăng 1,5 lần. Repo cũng cung cấp các bản GGUF để chạy với llama.cpp.

- **Hỗ trợ tinh chỉnh mô hình.** Pipeline huấn luyện có cả fine-tuning toàn bộ tham số và LoRA, cùng nhiều cấu hình DeepSpeed ZeRO và tích hợp LLaMA-Factory. Phần hướng dẫn huấn luyện chi tiết nằm ở tài liệu riêng trong repo.

## Cần chuẩn bị gì

Bạn cần một máy có môi trường Python để chạy các ví dụ. README ghi rõ Transformers cần phiên bản `transformers>=5.6.0`. Ví dụ Transformers dùng thư viện `torch`, tải mô hình từ đường dẫn `tencent/Hy-MT2-30B-A3B` và dùng `trust_remote_code=True`.

Nếu dùng vLLM, README hướng dẫn tạo môi trường bằng `uv`, dùng Python 3.12, sau đó xây vLLM từ mã nguồn. Nếu dùng SGLang, bạn cần Git, Python và pip để cài các gói từ mã nguồn.

Nếu dùng llama.cpp, bạn cần Git và CMake để biên dịch. Bản GGUF của Hy-MT2 phụ thuộc vào STQ kernel được phát hành trong một pull request của llama.cpp. Vì vậy, không nên mặc định rằng mọi bản llama.cpp có sẵn đều chạy được bản GGUF này.

README không nêu yêu cầu hệ điều hành cụ thể, không nêu dung lượng RAM hoặc VRAM tối thiểu, và cũng không nêu yêu cầu GPU bắt buộc. Ví dụ dùng `device_map="auto"`, nên thiết bị thực tế sẽ phụ thuộc vào bản mô hình và cách bạn chạy.

Bạn không thấy README yêu cầu API key. Các model link trỏ tới Hugging Face, còn README cũng đề cập ModelScope. Phần tư liệu được cung cấp chưa nói rõ điều kiện tải model, chi phí sử dụng hay giấy phép của repo; trường giấy phép cũng không ghi rõ.

## Cài đặt từng bước

```steps
- Chọn cách chạy | Chọn Transformers, vLLM, SGLang hoặc llama.cpp theo máy và định dạng model
- Lấy mã nguồn | Clone repo Hy-MT2 và mở terminal trong thư mục làm việc
- Chuẩn bị runtime | Cài Transformers, PyTorch, vLLM, SGLang hoặc biên dịch llama.cpp
- Chạy bản dịch thử | Dùng prompt yêu cầu dịch và kiểm tra kết quả đầu ra
- Tối ưu triển khai | Chọn model nhỏ hơn, bản lượng tử hóa hoặc server suy luận phù hợp
```

### Chọn model và cách chạy

Nếu bạn mới bắt đầu, Transformers là cách dễ đọc và dễ sửa nhất vì README có sẵn một chương trình Python hoàn chỉnh. Bản mẫu dùng `Hy-MT2-30B-A3B`, nhưng repo cũng liệt kê các model 1.8B và 7B, các bản FP8, GGUF và 1.25-bit.

Bản 1.8B phù hợp khi ưu tiên nhẹ và có nhu cầu chạy trên thiết bị. Bản 7B là lựa chọn ở giữa. Bản 30B-A3B phù hợp khi bạn có hạ tầng mạnh hơn. Hãy tải đúng model với cách chạy: Transformers dùng model Transformers, còn llama.cpp dùng model GGUF.

### Lấy repo về máy

README không yêu cầu phải clone repo để tải model và chạy ví dụ suy luận. Tuy nhiên, nếu muốn xem pipeline huấn luyện, benchmark hoặc tài liệu trong repo, bạn có thể clone bằng lệnh phổ thông sau:

```bash
git clone https://github.com/Tencent-Hunyuan/Hy-MT2.git
cd Hy-MT2
```

Lệnh đầu tiên tải mã nguồn về thư mục `Hy-MT2`. Lệnh thứ hai đưa terminal vào thư mục đó. Trên Windows, bạn có thể mở PowerShell rồi chạy các lệnh này; riêng những lệnh bắt đầu bằng `source` trong phần vLLM là cú pháp shell kiểu Unix, không phải cú pháp PowerShell.

### Chạy bằng Transformers

README ghi yêu cầu `transformers>=5.6.0` và cung cấp mã Python sau. Bạn cần có Python, PyTorch và quyền tải model từ đường dẫn model tương ứng.

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_path = "tencent/Hy-MT2-30B-A3B"

# Load tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)

# Load model
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

model.eval()

# Example inference
prompt = "将以下文本翻译成英语,注意只需要输出翻译后的结果,不要额外解释:\n\n今天天气真好。"
messages = [{"role": "user", "content": prompt}]
inputs = tokenizer.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=4096,
    )
response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True)
print(response)
```

Đoạn mã tải tokenizer, tải model, tạo prompt, sinh kết quả rồi in phần văn bản mới. `trust_remote_code=True` xuất hiện trong ví dụ chính thức, vì vậy bạn không nên tự bỏ qua nếu muốn bám đúng cách chạy của README.

README cũng khuyến nghị tham số suy luận. Với bản 1.8B và 7B, dùng `temperature` 0.7, `top_p` 0.6, `top_k` 20, `repetition_penalty` 1.05 và `max_tokens` 4096. Với bản 30B-A3B, dùng `temperature` 0.7, `top_p` 1.0, `top_k` -1, `repetition_penalty` 1.0 và `max_tokens` 4096. Các model không có `system_prompt` mặc định, nên phần hướng dẫn cần được đưa vào prompt người dùng.

### Chạy server bằng vLLM

README hướng dẫn xây vLLM từ mã nguồn bằng các lệnh sau:

```bash
uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate
git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install --editable . --torch-backend=auto
```

Lệnh đầu tạo môi trường ảo với Python 3.12. Lệnh thứ hai kích hoạt môi trường đó trong shell Unix. Hai lệnh sau tải mã nguồn vLLM, đi vào thư mục vLLM và cài bản đang phát triển với backend Torch tự động.

Sau đó khởi động server bằng:

```bash
vllm serve tencent/Hy-MT2-30B-A3B --tensor-parallel-size 1
```

`--tensor-parallel-size 1` yêu cầu chạy song song tensor trên một phần. README không cung cấp ví dụ client gọi API hoặc thông tin cổng trong phần tư liệu này, nên bạn cần xem hướng dẫn vLLM nếu muốn nối server vào ứng dụng khác.

### Chạy server bằng SGLang

README đưa ra quy trình xây SGLang từ mã nguồn:

```bash
git clone https://github.com/sgl-project/sglang
cd sglang
pip3 install pip --upgrade
pip3 install "transformers>=5.6.0"
pip3 install -e "python"
```

Sau khi cài xong, khởi động server bằng:

```bash
python3 -m sglang.launch_server --model tencent/Hy-MT2-30B-A3B --tp 1
```

`--model` chỉ model cần chạy, còn `--tp 1` đặt mức tensor parallel là một. Nếu terminal báo không tìm thấy `python3` hoặc `pip3`, README chưa cung cấp biến thể dành riêng cho môi trường đó.

### Chạy bản GGUF bằng llama.cpp

README lưu ý bản GGUF phụ thuộc STQ kernel. Trước hết clone và biên dịch llama.cpp:

```bash
git clone https://github.com/ggml-org/llama.cpp.git
```

```bash
cd llama.cpp
```

```bash
cmake -B build
cmake --build build --config Release
```

Sau khi biên dịch, thay `model.gguf` bằng đường dẫn tới file model GGUF rồi chạy:

```bash
./build/bin/llama-completion \
  --model model.gguf  \
  -p "Translate the following segment into Chinese, without additional explanation：Hello" \
  --jinja \
  -ngl 0 \
  -n 64 -st
```

Bạn cũng có thể chạy benchmark:

```bash
./build/bin/llama-bench -m model_zoo/model.gguf  -ngl 0
```

Các đường dẫn `model.gguf` và `model_zoo/model.gguf` trong README là vị trí minh họa. Tư liệu không nói lệnh tải file model cụ thể, nên bạn cần đặt đúng file GGUF đã tải vào vị trí tương ứng trước khi chạy.

## Kiểm tra đã chạy được chưa

Với ví dụ Transformers, nếu chương trình tải được tokenizer và model, không lỗi ở bước `from_pretrained`, sau đó in ra một câu dịch tiếng Anh từ câu tiếng Trung mẫu thì suy luận đã chạy thành công.

Với vLLM hoặc SGLang, dấu hiệu đầu tiên là server khởi động thành công sau lệnh `vllm serve` hoặc `python3 -m sglang.launch_server`. README chưa đưa lệnh gọi thử tới endpoint, nên chưa thể xác định chính xác màn hình phản hồi HTTP mong đợi chỉ từ tư liệu này.

Với llama.cpp, lệnh `llama-completion` phải đọc được file GGUF và in bản dịch của câu `Hello` sang tiếng Trung. Lệnh `llama-bench` phải chạy được chương trình benchmark với file model đã chỉ định.

Nếu chỉ muốn kiểm tra prompt, hãy yêu cầu mô hình “chỉ xuất bản dịch, không giải thích thêm”. Kết quả đạt yêu cầu khi phần trả lời không kèm lời dẫn, nhận xét hoặc giải thích ngoài bản dịch.

## Dùng vào việc thật

### Chủ shop dịch mô tả sản phẩm

Chủ shop có thể dùng bản 1.8B hoặc 7B để dịch mô tả từ tiếng Việt sang tiếng Anh, tiếng Thái hoặc tiếng Indonesia. Prompt nên ghi rõ ngôn ngữ đích, yêu cầu chỉ xuất bản dịch và thêm thuật ngữ cố định cho tên sản phẩm.

Ví dụ prompt:

```text
Translate the following text into English. Note that you should only output the translated result without any additional explanation.
Reference the following translations:
"áo chống nắng" translates to "sun-protective jacket"
"màu be" translates to "beige"

Source Text:
Áo chống nắng màu be, chất liệu nhẹ và phù hợp cho đi lại hằng ngày.
```

Kết quả nhận được là bản mô tả tiếng Anh có cách dịch thuật ngữ nhất quán, thuận tiện để đưa vào gian hàng.

### Nhân viên văn phòng dịch tài liệu có định dạng

Khi cần dịch dữ liệu JSON hoặc mẫu giao diện, nhân viên có thể yêu cầu mô hình chỉ dịch nội dung hiển thị. Prompt cần nói rõ phải giữ nguyên khóa, thuộc tính, biến thay thế, cấu trúc và thụt đầu dòng.

Ví dụ prompt:

```text
Translate the user-facing text within the following JSON data into Vietnamese.
Preserve the original JSON structure, nesting, hierarchy, and indentation exactly.
Translate only visible text values. Never alter keys, properties, object names, or placeholders such as {{var}}, ${var}, %s, and %d.

Source Data:
{source_text}
```

Cách này giúp giảm nguy cơ làm hỏng dữ liệu khi bản dịch được đưa trở lại ứng dụng.

### Đội nội dung chuẩn hóa văn phong

Một nhóm marketing có thể đưa vào vài bản dịch tham chiếu và yêu cầu văn phong cụ thể, chẳng hạn trang trọng, ngắn gọn hoặc phù hợp với tài liệu hướng dẫn. Hy-MT2 hỗ trợ dạng prompt có mục “Style” và “Personalization”.

Ví dụ:

```text
Please translate the following text into Vietnamese. Note that the translation style must strictly conform to [professional and concise].

Reference preferences:
1. Use clear language for office workers.
2. Keep product names in English.
3. Output only the translation.

Source Text:
{source_text}
```

Kết quả phù hợp khi nội dung giữ được phong cách đã yêu cầu và không thêm phần giải thích ngoài nhiệm vụ.

### Dev dịch phụ đề hoặc chuỗi giao diện

Dev có thể dùng bản GGUF với llama.cpp khi muốn chạy cục bộ và kiểm soát dữ liệu. Với chuỗi có dấu phân cách, hãy yêu cầu giữ nguyên số lượng, vị trí và nguyên dạng ký hiệu.

Ví dụ prompt:

```text
Please accurately translate the following text into Vietnamese.
You must retain the exact same number of delimiters in the translation. Strictly do not omit, escape, or translate these symbols, and pay close attention to their placement.

Source Text:
Hello || Welcome to our store || Thank you
```

Cách này phù hợp với nội dung cần xử lý tự động, nhưng dev vẫn nên kiểm tra đầu ra bằng test trước khi đưa vào hệ thống.

> Tự chạy mô hình giúp bạn kiểm soát dữ liệu, nhưng chất lượng dịch vẫn cần được kiểm tra theo từng lĩnh vực.
>
> — Ông T

```note
Không đưa dữ liệu nhạy cảm vào quy trình thử nghiệm nếu bạn chưa hiểu rõ nơi model được tải và nơi suy luận đang chạy. README chưa nêu chính sách lưu dữ liệu, chi phí hoặc điều kiện giấy phép; hãy kiểm tra các thông tin đó trước khi dùng cho tài liệu khách hàng.
```

## Lỗi hay gặp và cách xử lý

### Không tải được model

Tên model trong mã phải khớp với model bạn muốn dùng, chẳng hạn `tencent/Hy-MT2-30B-A3B`. Nếu dùng file cục bộ, đường dẫn phải trỏ đúng tới file hoặc thư mục model. README không cung cấp quy trình xử lý quyền truy cập hay lỗi tải từ Hugging Face, nên hãy kiểm tra lại đường dẫn và quyền truy cập trước khi đổi cấu hình.

### Thiếu phiên bản Transformers phù hợp

README yêu cầu `transformers>=5.6.0`. Nếu phiên bản quá cũ, các lớp model hoặc chat template có thể không hoạt động. Hãy kiểm tra môi trường Python đang chạy đúng môi trường đã cài thư viện.

### Hết RAM hoặc VRAM

Các bản 7B và 30B-A3B cần nhiều tài nguyên hơn bản 1.8B. README không nêu mức RAM hoặc VRAM tối thiểu, vì vậy không nên coi `device_map="auto"` là bảo đảm chạy được trên mọi máy. Bạn có thể cân nhắc bản nhỏ hơn hoặc bản lượng tử hóa được repo liệt kê.

### Lệnh `source .venv/bin/activate` không chạy trong PowerShell

Đây là lệnh được README viết cho shell Unix. README không đưa lệnh kích hoạt tương đương cho PowerShell, nên không nên tự thay bằng một cú pháp chưa kiểm chứng. Bạn có thể dùng shell phù hợp với lệnh trong tài liệu hoặc xem tài liệu môi trường của mình.

### GGUF không chạy với llama.cpp

README cảnh báo bản GGUF phụ thuộc STQ kernel. Nếu llama.cpp biên dịch được nhưng model không chạy, hãy kiểm tra đúng phiên bản và phần hỗ trợ kernel liên quan trước khi kết luận file model bị hỏng. Cũng cần thay `model.gguf` trong lệnh bằng đường dẫn thật tới file model.

### Kết quả có thêm giải thích

Các model không có `system_prompt` mặc định. Hãy ghi rõ trong prompt rằng chỉ được xuất bản dịch và không được giải thích thêm. Với nhiệm vụ giữ cấu trúc, cần nêu riêng các quy tắc không được sửa khóa, thẻ, thuộc tính và biến thay thế.

## Có nên dùng không

Hy-MT2 đáng dùng nếu bạn cần dịch đa ngôn ngữ, muốn chạy model riêng, hoặc phải xử lý các yêu cầu như giữ thuật ngữ, giữ định dạng và tuân thủ văn phong. Repo cung cấp nhiều kích thước model, bản FP8, GGUF và bản lượng tử hóa, đồng thời có hướng dẫn cho Transformers, vLLM, SGLang và llama.cpp. Nó cũng có pipeline fine-tuning và LoRA cho đội ngũ muốn tùy chỉnh sâu hơn.

Giới hạn lớn nhất là phần tư liệu chưa nêu yêu cầu phần cứng tối thiểu, quy trình cài đặt đầy đủ cho Windows, cách gọi API sau khi server khởi động, chính sách dữ liệu, chi phí và giấy phép rõ ràng. Người mới cũng có thể gặp độ khó cao khi phải tự biên dịch vLLM, SGLang hoặc llama.cpp.

Bạn nên chọn Hy-MT2 khi ưu tiên quyền kiểm soát dữ liệu và có người phụ trách môi trường Python hoặc hạ tầng model. Nếu chỉ cần dịch vài đoạn văn nhanh, không muốn tải model lớn hoặc không có máy đủ mạnh, một dịch vụ dịch sẵn có thể đơn giản hơn. Nếu cần đưa vào sản phẩm, hãy benchmark trên chính tài liệu của bạn, kiểm tra thuật ngữ và đánh giá riêng các trường hợp JSON, phụ đề hoặc dữ liệu có cấu trúc.

## Câu hỏi thường gặp

### Hy-MT2 có miễn phí không?

README được cung cấp không nêu rõ chính sách miễn phí, chi phí sử dụng hoặc giấy phép của repo. Trường giấy phép cũng không ghi rõ, nên bạn cần kiểm tra thêm thông tin cấp phép trước khi dùng cho sản phẩm thương mại.

### Hy-MT2 có cần GPU không?

README không nói GPU là bắt buộc và cũng không nêu cấu hình RAM hoặc VRAM tối thiểu. Ví dụ dùng `device_map="auto"`, còn khả năng chạy thực tế phụ thuộc vào kích thước model và cách triển khai.

### Có thể chạy Hy-MT2 trên Windows không?

Tư liệu không nêu hệ điều hành được hỗ trợ hoặc quy trình riêng cho Windows. Một số lệnh như `source .venv/bin/activate` dùng cú pháp shell Unix, nên người dùng Windows cần tự đối chiếu với môi trường shell của mình.

### Hy-MT2 hỗ trợ những ngôn ngữ nào?

Hy-MT2 hỗ trợ 33 ngôn ngữ, trong đó có tiếng Việt, tiếng Anh, tiếng Trung, tiếng Nhật, tiếng Hàn, tiếng Thái, tiếng Pháp, tiếng Đức, tiếng Tây Ban Nha và nhiều ngôn ngữ khác. README có bảng đầy đủ kèm mã ngôn ngữ.

### Dữ liệu gửi vào Hy-MT2 có an toàn không?

README không cung cấp chính sách lưu trữ, truyền dữ liệu hoặc quyền riêng tư. Nếu tự chạy model cục bộ, dữ liệu được xử lý trong môi trường bạn kiểm soát, nhưng cần tự xác minh cấu hình triển khai và các thành phần tải từ bên ngoài.

### Hy-MT2 khác gì một API dịch thương mại?

Hy-MT2 là model có thể tải và triển khai qua Transformers, vLLM, SGLang hoặc llama.cpp, nên bạn có thể tự kiểm soát hạ tầng. README không cung cấp bảng so sánh chi tiết với từng API; tài liệu chỉ nêu kết quả đánh giá của các kích thước model trong các nhiệm vụ dịch khác nhau.

### Có thể tinh chỉnh Hy-MT2 cho dữ liệu riêng không?

Có. Repo nói rằng pipeline huấn luyện hỗ trợ fine-tuning toàn bộ tham số, LoRA, nhiều cấu hình DeepSpeed ZeRO và tích hợp LLaMA-Factory. Hướng dẫn chi tiết nằm ở Model Training Guide, nhưng phần tư liệu được cung cấp không chép nội dung cài đặt cụ thể.
