EN ID MS TH TL VI ZH

Tích hợp hy4 với Ollama: nối Hunyuan tại chỗ vào Dify, Cursor và mọi client tương thích OpenAI

Sau khi chạy hy4, câu hỏi hằng ngày là công cụ của bạn có gọi được nó không. Hướng dẫn này đề cập tới nhập GGUF tại chỗ vào Ollama bằng Modelfile, phục vụ nó, cấu hình Dify, Cursor, Open WebUI và các plugin trình soạn thảo, chạy song song máy trạm và cloud, cùng các lỗi thường gặp.

Tích hợp hy4 với Ollama: nối Hunyuan tại chỗ vào Dify, Cursor và mọi client tương thích OpenAI

Chạy hy4 được chỉ giải quyết một nửa vấn đề, vì điều ảnh hưởng tới trải nghiệm hằng ngày là công cụ của bạn có gọi được nó không. Giá trị của Ollama nằm ở chỗ nó tự mang theo quản lý model và điểm cuối tương thích OpenAI, nên Dify, Cursor, Open WebUI và các plugin trình soạn thảo hiểu nó ngay, không cần viết code chuyển tiếp. Bài này đi theo các bước: từ nhập GGUF tại chỗ, tới phục vụ, tới cấu hình client, và tới xử lý sự cố.

Tóm tắt 30 giây

Nhập GGUF tại chỗ vào Ollama bằng ollama create với một Modelfile, phục vụ ở cổng 11434, rồi trỏ client về http://127.0.0.1:11434/v1 với api_key tuỳ ý, và kiểm tra bằng danh sách model. Dify, Cursor và Open WebUI đều nói giao thức tương thích OpenAI, nên đây là công việc cấu hình chứ không phải tích hợp.

Bước một: chuẩn bị trọng số GGUF

bash

mkdir -p ~/models && cd ~/models
huggingface-cli download bartowski/tencent_Hunyuan-4B-Instruct-GGUF \
  Q4_K_M.gguf --local-dir .
ls -lh

Vì sao nên dùng GGUF cộng đồng thay vì quantization chính thức

Bản chính thức là FP8, GPTQ-Int4 và AWQ-Int4, các định dạng này cần một stack phục vụ kiểu vLLM. Ollama và llama.cpp đi theo đường GGUF, nên triển khai máy trạm dùng bản chuyển đổi cộng đồng là đường ngắn nhất. bartowski có phủ các mức quantization rộng nhất và lượt tải cao nhất, nên là lựa chọn mặc định an toàn.

Bước hai: tạo model trong Ollama

bash

cat > ~/models/Modelfile <<'EOF'
FROM ./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
PARAMETER top_p 0.8
PARAMETER stop "<|im_end|>"
EOF

cd ~/models && ollama create hy4-local -f Modelfile
ollama list

TEMPLATE phải chép theo model card

Đây là lỗi tàng hính nhất khi triển khai máy trạm: model nạp được, sinh ra token, nhưng chất lượng trả lờ ngày càng tồi và 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, vì 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. Tham số stop cũng phải có, nếu không model sẽ không dừng lại.

Bước ba: phục vụ và kiểm tra

bash

# chạy ở chế độ foreground, mở terminal khác cho các lệnh kiểm tra
ollama serve

# kiểm tra giao diện gốc ở terminal thứ hai
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Giải thích cơ sở dữ liệu vector trong một câu"}],
  "stream": false
}'

Kiểm tra giao diện tương thích OpenAI:

bash

# danh sách model
curl http://127.0.0.1:11434/v1/models

# hội thoại
curl http://127.0.0.1:11434/v1/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Viết một hàm Python phân tích thời gian ISO 8601"}]
}'

Hai giao diện, hai việc khác nhau

/api/chat là điểm cuối gốc của Ollama, hỗ trợ các trường mở rộng như think và images. /v1/* là mặt tương thích OpenAI dành cho công cụ của bên thứ ba. Khi nối công cụ, chỉ cần dùng /v1; chỉ khi cần các khả năng riêng của Ollama, chẳng hạn gửi ảnh cho model đa phương tiện, bạn mới dùng giao diện gốc.

Bước bốn: nối client tương thích OpenAI

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama",           # giá trị tượng trưng, Ollama không kiểm tra
)
resp = client.chat.completions.create(
    model="hy4-local",
    messages=[{"role": "user", "content": "Xin chào"}],
)
print(resp.choices[0].message.content)

Bước năm: nối vào các công cụ cụ thể

Dify

Trong Settings, Model Providers, OpenAI-API-compatible, điền API Base URL http://127.0.0.1:11434/v1, API Key ollama, và tên model hy4-local. Lưu ý: khi Dify chạy trong Docker, 127.0.0.1 trỏ tới chính container, nên phải dùng IP hoặc tên dịch vụ của máy chủ.

Cursor

Mở khu vực Models trong cài đặt Cursor, thêm model qua nhà cung cấp OpenAI, đặt Base URL thành địa chỉ máy trạm, và dùng hy4-local làm tên model. Hỗ trợ điểm cuối máy trạm của Cursor thay đổi theo phiên bản, và việc nhập tên model thủ công vẫn hoạt động khi việc khám phá tự động thất bại.

Open WebUI

Trong Admin Settings, Connections, OpenAI, điền cùng địa chỉ, sau đó bật hy4-local trong phần Models. Lưu ý rằng Open WebUI chạy trong container phải gọi máy chủ qua host.docker.internal thay vì 127.0.0.1.

Plugin trình soạn thảo như Continue và Cline

Trong cấu hình model của plugin, chọn nhà cung cấp OpenAI và điền base URL cùng tên model máy trạm. Hầu hết các plugin ini có tùy chọn model cục bộ hoặc nhà cung cấp tuỳ chỉnh, và dùng nó sạch hơn là sửa cài đặt toàn cục.

Mạng Docker là chỗ vấp ngã phổ biến nhất

Khi công cụ chạy trong container, localhost trỏ tới chính container đó. Có hai cách xử lý: thêm extra_hosts: ["host.docker.internal:host-gateway"] vào tệp compose rồi dùng host.docker.internal:11434, hoặc để Ollama lắng nghe 0.0.0.0:11434 bằng OLLAMA_HOST=0.0.0.0 ollama serve. Lựa chọn thứ hai khiến model của bạn truy cập được từ toàn bộ mạng nội bộ, nên hãy thêm kiểm soát truy cập trước khi dùng.

Bước sáu: máy trạm và cloud chạy song song

Nhiều đội vận hành hy4 máy trạm và model cloud cùng lúc. Cách làm là cấu hình điểm cuối khác nhau cho các công cụ, hoặc định tuyến bên trong client:

python

import os

def pick_client(task: str):
    if task in {"classify", "rewrite", "summarize"}:
        return OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
    return OpenAI(base_url="https://exaiv.com/api/ai/v1", api_key=os.environ["EXAIV_KEY"])

Đừng trộn lẫn tên model

Tên model máy trạm là hy4-local, do bạn đặt, còn ID model cloud là một ID thật tồn tại trong thư mục, chẳng hạn kimi-k3. Khi gõ sai tên model, biểu hiện thường là "model không tồn tại" chứ không phải "không kết nối được", nên khi gỡ lỗi hãy kiểm tra tên trước, rồi mới tới mạng.

Bảng xử lý sự cố

Hiện tượng	Nguyên nhân	Cách xử lý
Kết quả lạ hoặc không đúng câu hỏi	template hội thoại sai	sửa TEMPLATE và stop theo model card
Kết nối bị từ chối	dịch vụ chưa chạy, hoặc không phải cổng 11434	chạy `ollama serve` rồi kiểm tra cổng bằng curl
Không kết nối được từ Docker	cô lập mạng container	dùng host.docker.internal hoặc lắng nghe 0.0.0.0
Trả lờ ngắt giữa chừng	ngữ cảnh không đủ hoặc max_tokens quá nhỏ	tăng num_ctx và max_tokens
Lỗi tên model	dùng ID cloud hoặc gõ sai	xem `ollama list` để lấy tên thật
Lượt đầu rất chậm	model đang nạp vào bộ nhớ	hiện tượng bình thường, các lượt sau sẽ nhanh
Không đủ bộ nhớ	num_ctx quá lớn	giảm ngữ cảnh, vì KV cache tăng tuyến tính

FAQ

Nên chọn Ollama hay llama.cpp?

Cần hiệu năng tối đa và tinh chỉnh tham số thì dùng llama.cpp; cần khả năng tương thích hệ sinh thái, vì Open WebUI, Dify và Cursor chạy ngay, thì dùng Ollama. Cả hai đều cung cấp điểm cuối tương thích OpenAI và có thể dùng chung tệp model.

Lấy TEMPLATE cho Modelfile ở đâu?

Từ phần Usage của model card tương ứng. Template của Hunyuan khác nhau giữa các thế hệ, và template sai vẫn cho ra token thông nhưng chất lượng kém, đây là nguồn gốc chẩn đoán sai phổ biến nhất khi triển khai máy trạm.

Dify chạy trong Docker gọi Ollama trên máy chủ thế nào?

Trong container, 127.0.0.1 trỏ tới chính container. Thêm extra_hosts ánh xạ host.docker.internal tới cổng ra của máy chủ trong tệp compose, rồi dùng tên máy chủ đó cùng cổng 11434 làm Base URL.

Có thể cho Ollama cung cấp dịch vụ ra ngoài không?

Được, bằng OLLAMA_HOST=0.0.0.0 ollama serve để nó lắng nghe mọi giao diện. Nhưng Ollama mặc định không có xác thực, nên ai trong mạng cũng có thể gọi model của bạn; trước khi để ra ngoài mạng công cộng, hãy đặt proxy ngược và kiểm soát truy cập phía trước.

Gọi Hunyuan qua API của EXAIV được không?

Danh mục cloud EXAIV hiện chưa có Hunyuan, hãy xem danh sách model thời gian thực. Hunyuan đi theo đường triển khai máy trạm, và bài này chính là hướng dẫn nối nó vào chuỗi công cụ của bạn.

Đọc tiếp

hy4 GGUF local deployment — quantization, phép tính bộ nhớ và lệnh llama.cpp
Open WebUI với Hunyuan tại chỗ — cấu hình giao diện trò chuyện tự lưu trữ
RAG với hy4 — nối điểm cuối máy trạm vào kho tri thức
Tích hợp Dify — kết nối model cloud vào Dify
Tích hợp Open WebUI — kết nối model cloud vào giao diện tự lưu trữ
Hướng dẫn chọn model hy4 — các kích thước và vị trí của A13B

Nguồn dữ liệu

Danh sách kho và mức quantization 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.

Một key duy nhất cho các model mở nguồn Trung Quốc

EXAIV phục vụ Qwen, DeepSeek, Kimi và GLM qua một endpoint tương thích OpenAI. Đăng ký là gọi được ngay

Xem gói credit

← Back to Integrations

EN ID MS TH TL VI ZH

Tích hợp hy4 với Ollama: nối Hunyuan tại chỗ vào Dify, Cursor và mọi client tương thích OpenAI

Tóm tắt 30 giây

Bước một: chuẩn bị trọng số GGUF

bash

mkdir -p ~/models && cd ~/models
huggingface-cli download bartowski/tencent_Hunyuan-4B-Instruct-GGUF \
  Q4_K_M.gguf --local-dir .
ls -lh

Vì sao nên dùng GGUF cộng đồng thay vì quantization chính thức

Bước hai: tạo model trong Ollama

bash

cat > ~/models/Modelfile <<'EOF'
FROM ./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
PARAMETER top_p 0.8
PARAMETER stop "<|im_end|>"
EOF

cd ~/models && ollama create hy4-local -f Modelfile
ollama list

TEMPLATE phải chép theo model card

Bước ba: phục vụ và kiểm tra

bash

# chạy ở chế độ foreground, mở terminal khác cho các lệnh kiểm tra
ollama serve

# kiểm tra giao diện gốc ở terminal thứ hai
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Giải thích cơ sở dữ liệu vector trong một câu"}],
  "stream": false
}'

Kiểm tra giao diện tương thích OpenAI:

bash

# danh sách model
curl http://127.0.0.1:11434/v1/models

# hội thoại
curl http://127.0.0.1:11434/v1/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Viết một hàm Python phân tích thời gian ISO 8601"}]
}'

Hai giao diện, hai việc khác nhau

Bước bốn: nối client tương thích OpenAI

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama",           # giá trị tượng trưng, Ollama không kiểm tra
)
resp = client.chat.completions.create(
    model="hy4-local",
    messages=[{"role": "user", "content": "Xin chào"}],
)
print(resp.choices[0].message.content)

Bước năm: nối vào các công cụ cụ thể

Dify

Cursor

Open WebUI

Plugin trình soạn thảo như Continue và Cline

Mạng Docker là chỗ vấp ngã phổ biến nhất

Bước sáu: máy trạm và cloud chạy song song

Nhiều đội vận hành hy4 máy trạm và model cloud cùng lúc. Cách làm là cấu hình điểm cuối khác nhau cho các công cụ, hoặc định tuyến bên trong client:

python

import os

def pick_client(task: str):
    if task in {"classify", "rewrite", "summarize"}:
        return OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
    return OpenAI(base_url="https://exaiv.com/api/ai/v1", api_key=os.environ["EXAIV_KEY"])

Đừng trộn lẫn tên model

Bảng xử lý sự cố

Hiện tượng	Nguyên nhân	Cách xử lý
Kết quả lạ hoặc không đúng câu hỏi	template hội thoại sai	sửa TEMPLATE và stop theo model card
Kết nối bị từ chối	dịch vụ chưa chạy, hoặc không phải cổng 11434	chạy `ollama serve` rồi kiểm tra cổng bằng curl
Không kết nối được từ Docker	cô lập mạng container	dùng host.docker.internal hoặc lắng nghe 0.0.0.0
Trả lờ ngắt giữa chừng	ngữ cảnh không đủ hoặc max_tokens quá nhỏ	tăng num_ctx và max_tokens
Lỗi tên model	dùng ID cloud hoặc gõ sai	xem `ollama list` để lấy tên thật
Lượt đầu rất chậm	model đang nạp vào bộ nhớ	hiện tượng bình thường, các lượt sau sẽ nhanh
Không đủ bộ nhớ	num_ctx quá lớn	giảm ngữ cảnh, vì KV cache tăng tuyến tính

FAQ

Nên chọn Ollama hay llama.cpp?

Lấy TEMPLATE cho Modelfile ở đâu?

Dify chạy trong Docker gọi Ollama trên máy chủ thế nào?

Có thể cho Ollama cung cấp dịch vụ ra ngoài không?

Gọi Hunyuan qua API của EXAIV được không?

Đọc tiếp

hy4 GGUF local deployment — quantization, phép tính bộ nhớ và lệnh llama.cpp
Open WebUI với Hunyuan tại chỗ — cấu hình giao diện trò chuyện tự lưu trữ
RAG với hy4 — nối điểm cuối máy trạm vào kho tri thức
Tích hợp Dify — kết nối model cloud vào Dify
Tích hợp Open WebUI — kết nối model cloud vào giao diện tự lưu trữ
Hướng dẫn chọn model hy4 — các kích thước và vị trí của A13B

Nguồn dữ liệu

Danh sách kho và mức quantization 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.

Một key duy nhất cho các model mở nguồn Trung Quốc

EXAIV phục vụ Qwen, DeepSeek, Kimi và GLM qua một endpoint tương thích OpenAI. Đăng ký là gọi được ngay

Xem gói credit

← Back to Integrations