Open WebUI với Hunyuan tại chỗ: đặt hy4 sau một giao diện tự lưu trữ
Kết nối hy4 đang chạy tại chỗ vào Open WebUI: triển khai Docker, trỏ tới điểm cuối Ollama hoặc llama.cpp, kích hoạt model, cấu hình danh sách model của quản trị viên, truy cập mạng LAN và xác thực, cùng hai phương án cấu hình và bảng xử lý sự cố.
Open WebUI với Hunyuan tại chỗ: đặt hy4 sau một giao diện tự lưu trữ
Open WebUI là giao diện trò chuyện tự lưu trữ phổ biến nhất và có đường tới model máy trạm ngắn nhất: hỗ trợ Ollama là bản định nghĩa sẵn, còn kết nối llama.cpp chỉ cần một địa chỉ tương thích OpenAI. Khi model máy trạm là hy4, kết quả là nhật ký trò chuyện, trọng số model và toàn bộ dữ liệu đều ở trên máy bạn, kèm một giao diện cảm giác gần giống sản phẩm chat lưu trữ. Bài này đưa cấu hình đầy đủ và bảng xử lý sự cố.
Tóm tắt 30 giây
Khởi động Open WebUI trong Docker, thêm một kết nối OpenAI trong Admin Settings, Connections, với Base URL trỏ về http://host.docker.internal:8080/v1 cho llama.cpp, hoặc dùng kết nối Ollama tích hợp sẵn, rồi kích hoạt hy4-local trong Models và bắt đầu trò chuyện. Trong container, đừng dùng 127.0.0.1.
Phương án một: dùng thẳng Ollama (gọn nhất)
Open WebUI có sẵn kết nối Ollama, chỉ cần một địa chỉ:
docker run -d -p 3000:8080 \
-e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
Mở http://localhost:3000, đăng ký tài khoản đầu tiên (tài khoản đầu tiên đăng ký tự động thành quản trị viên), rồi:
Xác nhận Ollama đang chạy
Trên máy chủ, chạyollama listvà đảm bảo thấyhy4-local; nếu chưa có, hãy tạo trước bằngollama create hy4-local -f Modelfile.Kiểm tra trạng thái kết nối
Vào Admin Settings → Connections và xác nhận kết nối Ollama hiển thị đã kết nối.Kích hoạt model
Tới Admin Settings → Models, tìmhy4-localvà bật công tắc kích hoạt.Bắt đầu trò chuyện
Tạo hội thoại mới và chọnhy4-localtrong danh sách model.
Trong container, 127.0.0.1 là chính container
Lỗi thường gặp nhất là đặt OLLAMA_BASE_URL thành http://127.0.0.1:11434 và giao diện báo chưa kết nối. 127.0.0.1 trong container trỏ tới không gian mạng của container, không phải máy chủ. Hãy dùng host.docker.internal; nếu bản Docker của bạn không phân giải tên này, hãy thêm --add-host=host.docker.internal:host-gateway khi khởi động.
Phương án hai: kết nối tới dịch vụ llama.cpp
Nếu bạn dùng llama-server thay vì Ollama, hãy thêm một kết nối OpenAI trong Open WebUI:
Xác nhận llama-server đang chạy
Trên máy chủ chạy./llama-server -m ./Q4_K_M.gguf --host 0.0.0.0 --port 8080 --ctx-size 32768 --jinja; lưu ý lắng nghe 0.0.0.0 thay vì 127.0.0.1, nếu không container không truy cập được.Thêm kết nối OpenAI
Admin Settings → Connections → OpenAI, nhấn thêm, đặt Base URL làhttp://host.docker.internal:8080/v1, API Key là một giá trị tượng trưng bất kỳ.Thêm model thủ công
Nếu danh sách model không tải được, hãy thêm tên model trong Admin Settings → Models và giữ tên khớp với tên llama-server khởi động.Xác nhận và kích hoạt
Quay lại danh sách model để kích hoạt, rồi kiểm tra trong một hội thoại mới.
Vì sao nên dùng llama-server thay vì vLLM cho Open WebUI
llama-server không kiểm tra chặt tên model, dùng ít bộ nhớ hơn và khởi động nhanh, rất hợp với giao diện máy trạm cá nhân hoặc nhóm nhỏ. vLLM phù hợp hơn cho dịch vụ concurrency cao, nhưng nó kiểm tra chặt danh sách model, nên tên phải khớp hoàn toàn khi nối giao diện. Cả hai đều dùng được; chọn theo concurrency.
Phương án ba: cấu hình qua biến môi trường
Khi triển khai container, việc đưa cấu hình qua biến môi trường ổn định hơn:
docker run -d -p 3000:8080 \
-e OPENAI_API_BASE_URL="http://host.docker.internal:8080/v1" \
-e OPENAI_API_KEY="ollama" \
-e OLLAMA_BASE_URL="http://host.docker.internal:11434" \
-e WEBUI_AUTH=true \
-v open-webui:/app/backend/data \
--add-host=host.docker.internal:host-gateway \
--name open-webui \
ghcr.io/open-webui/open-webui:main
Tên biến môi trường theo tài liệu của bản bạn đang dùng
Tên biến môi trường của Open WebUI đã từng thay đổi giữa các phiên bản, chẳng hạn khác biệt lịch sử giữa OPENAI_API_BASE_URL và OPENAI_API_BASE. Bài này đưa cách viết phổ biến hiện tại; trước khi áp dụng, hãy đối chiếu tài liệu của bản bạn đang triển khai.
Bảng đối chiếu cấu hình
| Tình huống | Phía máy chủ | Cấu hình phía Open WebUI | Base URL |
|---|---|---|---|
| Gọn nhất | Ollama | kết nối Ollama tích hợp | http://host.docker.internal:11434 |
| Tinh chỉnh tham số | llama.cpp | thêm kết nối OpenAI | http://host.docker.internal:8080/v1 |
| Model cloud | EXAIV cloud | thêm kết nối OpenAI | https://exaiv.com/api/ai/v1 |
| Dùng cả hai | cả hai | thêm cả hai kết nối | theo từng dòng trên |
Máy trạm và cloud có thể cùng tồn tại
Open WebUI hỗ trợ nhiều kết nối cùng lúc. Trong danh sách model, hy4 máy trạm và model cloud sẽ xuất hiện cạnh nhau, nên bạn chuyển đổi theo độ nhạy dữ liệu của từng nhiệm vụ. Cách này thường thực dụng hơn là "tất cả đi máy trạm" hoặc "tất cả đi cloud".
Truy cập LAN và ra ngoài
Theo mặc định Open WebUI chỉ lắng nghe cổng 8080 bên trong container, ánh xạ ra máy chủ qua -p 3000:8080. Để các thiết bị khác trong mạng vào được:
docker run -d -p 3000:8080 \
-e WEBUI_AUTH=true \
-e WEBUI_URL=http://192.168.1.10:3000 \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
Trước khi ra ngoài mạng, hãy làm ba việc này
Thứ nhất, bật WEBUI_AUTH và đặt mật khẩu mạnh cho mọi tài khoản, vì tài khoản đầu tiên của Open WebUI không có mật khẩu và tự động là quản trị viên. Thứ hai, đừng để cổng Ollama truy cập trực tiếp ra mạng công cộng; nó không có xác thực, nên ai cũng có thể tiêu tốn khả năng tính toán của bạn. Thứ ba, nếu thật sự cần truy cập công cộng, hãy đặt một tầng proxy ngược phía trước để làm TLS và kiểm soát truy cập.
Bảng xử lý sự cố
| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| Kết nối Ollama hiển thị chưa kết nối | trong container dùng 127.0.0.1 | đổi sang host.docker.internal và thêm ánh xạ host-gateway |
| Danh sách model trống | dịch vụ chưa chạy hoặc sai đường dẫn | kiểm tra cổng máy chủ bằng curl, rồi thêm tên model thủ công trong giao diện |
| Kết quả lạ | template hội thoại không khớp | sửa TEMPLATE hoặc --jinja theo model card |
| Trả lờ ngày càng chậm | model đang chạy trên CPU | xác nhận GPU có hiệu lực, hoặc dùng mức quantization nhỏ hơn |
| Lần đầu mở rất chậm | model đang nạp vào bộ nhớ | hiện tượng bình thường |
| Giao diện xoay vòng liên tục | ngữ cảnh quá lớn gây tràn bộ nhớ | hạ num_ctx hoặc đổi sang mức quantization nhỏ hơn |
| Trò chuyện bị xuyên qua người dùng | cấu hình lưu phiên bị chia sẻ sai | kiểm tra gắn volume dữ liệu và thiết lập quyền người dùng |
FAQ
Cấu hình model máy trạm và model cloud trong Open WebUI có khác gì nhau?
Vì sao danh sách model không tải được?
Tại sao trong container không dùng được 127.0.0.1?
Open WebUI có thể dùng chung với model cloud không?
Gọi Hunyuan qua API của EXAIV được không?
Đọc tiếp
- Tích hợp hy4 với Ollama — đưa Hunyuan máy trạm vào Dify, Cursor và các công cụ khác
- Tích hợp Open WebUI với EXAIV — cấu hình kết nối model cloud (là một đường khác với bài này)
- hy4 GGUF local deployment — chuẩn bị quantization và bộ nhớ trước khi phục vụ
- Tích hợp Dify — cách nối nền tảng ứng dụng tự lưu trữ khác
- RAG với hy4 — cho model máy trạm một kho tri thức
- Tổng quan gia đình Tencent Hunyuan — bức tranh toàn cảnh của gia đình Hunyuan
Nguồn dữ liệu
Tên biến môi trường và mục cấu hình theo tài liệu của bản bạn đang triển khai; bài viết phản ánh trạng thái lúc lấy mẫu.