Triển khai hy4 với GGUF: mức quantization, tính bộ nhớ và lệnh llama.cpp / Ollama
Triển khai hy4 với GGUF: mức quantization, tính bộ nhớ và lệnh llama.cpp / Ollama
hy4 là model dễ tự triển khai nhất trong gia đình Hunyuan: model dense 4 tỷ tham số, nguồn cung cấp FP8, GPTQ-Int4 và AWQ-Int4 chính thức, và cộng đồng còn có nhiều tác giả chuyển đổi GGUF. Việc làm thực sự phức tạp không phải model mà là ba quyết định bạn phải tự đưa ra: chọn mức quantization nào, dành bao nhiêu bộ nhớ, và chạy trên framework nào. Bài này đi theo thứ tự quyết định, đo, triển khai và xử lý sự cố; mọi lệnh đều chép lại được.
Tóm tắt 30 giây
Tổ hợp khuyến nghị cho lần chạy đầu: GGUF Q4_K_M từ cộng đồng kết hợp llama.cpp (llama-server để mở điểm cuối tương thích OpenAI). Ước tính bộ nhớ là 2.5GB cho trọng số, 0.5GB cho KV cache và 0.5GB cho chi phí chạy, nên card 6GB là đủ. Người dùng Mac thì đổi sang bản chuyển đổi 4bit của mlx-community cho gọn.
Bước một: chọn mức quantization
| Mức | Kích thước (đo trên kho bartowski) | Chất lượng | Phù hợp |
|---|---|---|---|
| IQ4_XS | 2.37 GB | gần Q4 | đường Q4 khi bộ nhớ chật |
| Q3_K_M | 2.17 GB | mất mát cảm nhận được | vừa đúng trên card 4GB |
| Q4_K_M | 2.61 GB | gần như không mất | lựa chọn mặc định, đủ cho hầu hết công việc |
| Q5_K_M | 3.03 GB | gần bản gốc | chọn khi bộ nhớ còn dư |
| Q6_K | 3.47 GB | gần như tương đương gốc | lựa chọn bảo thủ cho sinh văn bản dài |
| Q8_0 | 4.49 GB | cơ bản tương đương gốc | dùng làm mức đối chiếu độ chính xác |
| FP16 (bản gốc) | khoảng 8.4 GB | bản gốc | chỉ khi cần stack suy luận FP16 |
Kích thước bản gốc dựa trên tham số trên model card: Hunyuan-4B-Instruct có 4.22 tỷ tham số, lưu BF16 khoảng 8.4GB.
Thứ tự chọn thực tế
Hãy bắt đầu với Q4_K_M và kiểm tra xem dòng lệnh, độ dài ngữ cảnh và phục vụ đã chạy trọn vẹn chưa. Nếu công việc của bạn nhạy cảng với độ chính xác, chẳng hạn trích xuất có cấu trúc hoặc sinh mã, hãy so sánh kết quả với Q5_K_M. Chỉ khi cần thiết lập đường cơ sở để đo mức quantization làm giảm bao nhiêu, bạn mới dùng Q8_0 hoặc FP16. Bắt đầu ở FP16 thường chỉ là lãng phí bộ nhớ.
Các tác giả GGUF cộng đồng cho hy4:
| Tác giả | Đặc điểm kho |
|---|---|
| bartowski | đủ mức, lượt tải cao nhất, nguồn mặc định an toàn |
| mradermacher | cung cấp quantization chuẩn và bộ i1 |
| gabriellarson | chủ yếu quantization chuẩn |
| DevQuasar | chủ yếu quantization chuẩn |
| Disya | chủ yếu Q8_0, phù hợp đối chiếu chính xác cao |
| Edge-Quant | một mức Q4_K_M, lựa chọn tối giản |
Khi tải, hãy đọc kỹ nhãn quantization trong tên file (Q4_K_M, Q5_K_M, Q8_0) và kho nguồn, đừng coi các file cùng tên từ các tác giả khác nhau là một.
Bước hai: tính bộ nhớ, đừng chỉ tính trọng số
Tổng bộ nhớ là ba phần cộng lại:
Tổng bộ nhớ ≈ Trọng số + KV cache + Chi phí chạy
Trọng số: 4.22 tỷ tham số nhân số byte mỗi tham số. Q4_K_M khoảng 0.65 byte mỗi tham số, Q8_0 khoảng 1.06, FP16 là 2.
KV cache: tăng tuyến tính theo độ dài ngữ cảnh. Cấu hình chính thức của hy4 là 36 lớp, 8 KV head, head dimension 128, tương đương khoảng 144KB cho mỗi token ở BF16:
KV cache ≈ 2 × 36 lớp × 8 KV head × 128 head dim × độ dài ngữ cảnh × 2 byte
≈ 144KB × độ dài ngữ cảnh
Đối chiếu: ngữ cảnh 4K khoảng 0.56GB, ngữ cảnh 32K khoảng 4.6GB. Độ dài vị trí tối đa chính thức của hy4 là 262144 (256K), nhưng mở đầy cửa sổ đồng nghĩa KV cache ăn hàng chục GB, nên số ngữ cảnh thực tế dùng được phải suy ngược từ bộ nhớ, không phải chép lại con số trên nhãn.
Một bảng tra nhanh
Q4_K_M (2.61GB) cộng ngữ cảnh 4K: khoảng 2.6 + 0.6 + 0.5 = 3.7GB, chật nhưng khả thi trên card 4GB. Q4_K_M cộng ngữ cảnh 32K: khoảng 2.6 + 4.6 + 0.5 = 7.7GB, cần card 8GB trở lên mới vững. Q5_K_M cộng ngữ cảnh 8K: khoảng 3.0 + 1.1 + 0.5 = 4.6GB, vừa đúng trên card 6GB. Q8_0 (4.49GB) đã ăn mất phần lớn một card. Các con số là khoảng ước tính; con số thật là thứ nvidia-smi báo ngay sau lần nạp đầu.
Bước ba: chạy bằng llama.cpp
# 1. Tải GGUF cộng đồng (ví dụ kho bartowski; điều chỉnh tên file theo danh sách trong kho)
huggingface-cli download bartowski/tencent_Hunyuan-4B-Instruct-GGUF \
Q4_K_M.gguf --local-dir ./hunyuan4b
# 2. Hội thoại trực tiếp để kiểm tra weight nạp được không
./llama-cli -m ./hunyuan4b/Q4_K_M.gguf -p "Giải thích MoE trong ba câu" -n 256
# 3. Mở dịch vụ tương thích OpenAI
./llama-server -m ./hunyuan4b/Q4_K_M.gguf \
--host 127.0.0.1 --port 8080 \
--ctx-size 32768 \
--jinja
Khi dịch vụ đã chạy, client hiện tại chỉ cần đổi hai tham số:
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8080/v1",
api_key="not-needed",
)
resp = client.chat.completions.create(
model="local-model",
messages=[{"role": "user", "content": "Xin chào, hãy tự giới thiệu"}],
)
print(resp.choices[0].message.content)
Tên model có thể đặt tuỳ ý, nhưng đừng dùng id API thật
llama-server không kiểm tra chặt tên model, nên dịch vụ tại chỗ dùng local-model là đủ. Nếu client của bạn lấy tên model đi tra danh mục từ xa, hãy tách bạch điểm cuối tại chỗ và điểm cuối cloud.
Bước bốn: chạy bằng Ollama để tương thích công cụ tốt nhất
Giá trị của Ollama nằm ở việc nó tự mang theo quản lý model và hệ sinh thái API, nên các công cụ như Open WebUI, Dify hay Cursor hiểu nó ngay.
# 1. Tạo model từ GGUF tại chỗ qua Modelfile
cat > Modelfile <<'EOF'
FROM ./hunyuan4b/Q4_K_M.gguf
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""
PARAMETER num_ctx 8192
PARAMETER temperature 0.7
EOF
ollama create hy4-local -f Modelfile
# 2. Kiểm tra
ollama run hy4-local "Viết một hàm Python phân tích thời gian ISO 8601"
# 3. Xem và xoá
ollama list
ollama show hy4-local
ollama rm hy4-local
TEMPLATE phải chép theo model card
Đây là bẫy tàng hình nhất khi tự triển khai: model nạp được, sinh được chữ, nhưng chất lượng trả lời kém, trông như model yếu. Nguyên nhân gần như luôn là template hội thoại không khớp — template của Hunyuan khác nhau giữa các thế hệ. Hãy chép từ phần Usage của model card tương ứng và nhớ thêm tham số stop, nếu không model sẽ không dừng lại.
Bước năm: đường Mac và thiết bị biên
| Nền tảng | Đường đi | Ghi chú |
|---|---|---|
| Apple Silicon | mlx-community/Hunyuan-4B-Instruct-4bit | nạp trực tiếp qua mlx-lm, bộ nhớ thống nhất nên lợi ích quantization rõ rệt |
| Thiết bị biên, nhúng | taobao-mnn/Hunyuan-4B-Instruct-MNN | engine suy luận MNN của Alibaba, hướng tới di động và nhúng |
| CPU cũ | GGUF Q4/Q5 cộng đồng | backend CPU của llama.cpp, 4B là trần thực tế |
# Kiểm tra nhanh bằng MLX
pip install mlx-lm
python -m mlx_lm.generate --model mlx-community/Hunyuan-4B-Instruct-4bit \
--prompt "Giải thích cơ sở dữ liệu vector trong một câu" --max-tokens 128
Để có ước tính tốc độ đáng tin
Đừng tin con số token/s của người khác. CPU, băng thông bộ nhớ, độ dài ngữ cảnh và bản dựng engine đều làm thay đổi kết quả. Cách đúng là đo trên máy của bạn: cố định prompt, cố định độ dài sinh, chạy ba vòng lấy trung vị, đồng thời ghi lại mức bộ nhớ cao nhất. Lưu con số này lại để lần đổi mức quantization sau có đường cơ sở so sánh.
Bảng xử lý sự cố: theo triệu chứng tìm nguyên nhân
| Hiện tượng | Nguyên nhân khả dĩ nhất | Cách xử lý |
|---|---|---|
| Không nạp được vì kiến trúc không được hỗ trợ | bản dựng llama.cpp quá cũ | nâng cấp engine và biên dịch lại |
| Nạp được nhưng kết quả ra ký tự lạ | template hội thoại sai | sửa TEMPLATE hoặc --jinja theo model card |
| Bị đóng vì hết bộ nhớ | chỉ tính trọng số, bỏ qua KV cache | hạ độ dài ngữ cảnh hoặc xuống mức quantization thấp hơn |
| Mỗi token chậm cực | một phần lớp bị tràn sang bộ nhớ hệ thống | dùng quantization nhỏ hơn hoặc model nhỏ hơn |
| Token đầu rất chậm, sau đó bình thường | weight nạp vào bộ nhớ ở lượt đầu | hiện tượng bình thường, hãy làm nóng |
| Định dạng gọi công cụ không có hiệu lực | template thiếu phần công cụ | bổ sung phần tool theo model card hoặc đổi template |
| Kết quả lặp và không kết thúc | tham số lấy mẫu quá cực đoan | chỉnh temperature và top_p, xác nhận có EOS token |
FAQ
hy4 có GGUF chính thức không?
Lần triển khai đầu nên chọn mức quantization nào?
Làm sao biết cần bao nhiêu bộ nhớ?
Nên chọn llama.cpp hay Ollama?
Kết quả kém, liệu model có yếu không?
Người dùng Mac nên đi đường nào cho hy4?
Gọi Hunyuan qua API được không?
Đọc tiếp
- Trang model hy4 — thông số, ma trận quantization và cách tính bộ nhớ
- Ghi chú kênh hy4-preview — kênh ngữ cảnh 1M
- Tổng quan gia đình Tencent Hunyuan — mọi dòng sản phẩm của Hunyuan
- Hướng dẫn chọn model hy4 — các kích thước và vị trí của A13B
- Kết nối hy4 với Ollama — đưa điểm cuối tại chỗ vào công cụ phát triển
- Open WebUI với Hunyuan tại chỗ — giao diện trò chuyện tự lưu trữ
- Hướng dẫn tính bộ nhớ VRAM — phép tính bộ nhớ tổng quát
- Sổ tay triển khai tại chỗ — từ kiểm tra phần cứng tới kết nối công cụ
Nguồn dữ liệu
Danh sách mức quantization và kho sẽ thay đổi theo cộng đồng cập nhật; bài viết phản ánh trạng thái lúc lấy mẫu. Các con số bộ nhớ là ước tính kinh nghiệm, và phép đo trên máy của bạn mới là quyết định.