Khắc phục sự cố self-hosted model
Trước tiên, hãy xác định lỗi nằm ở giai đoạn nào: sự cố triển khai xảy ra trước khi route public sẵn sàng; sự cố request xảy ra sau khi client đã kết nối tới endpoint.
Sự cố khi triển khai
Mục “Sự cố khi triển khai”| Hiện tượng | Nguyên nhân có thể | Kiểm tra tiếp theo |
|---|---|---|
Màn hình Thiết lập workspace (Set up your workspace) hiện ra thay cho nội dung trang | Tenant chưa có workspace trong region này | Tạo workspace ngay trên màn hình đó, hoặc từ Tổng quan (Overview) hay Workspace |
Nút Triển khai mô hình (Deploy model) hoặc các thao tác GPU ở trạng thái read-only | Chưa có Inference GPU quota trong region đã chọn | Kiểm tra mục Hạn mức (Quotas) và tên region trên thanh tiêu đề (header) |
Phiên bản model trong registry không xuất hiện ở tab Mô hình của bạn (Your models) | Phiên bản chưa hoàn thiện hoặc không phải artifact đủ trọng số (full-weight) có thể phục vụ | Kiểm tra trạng thái của phiên bản trong mục Mô hình (Models) |
| Model chưa có địa chỉ endpoint hoặc chưa có lệnh cURL khả dụng | Route phục vụ chưa sẵn sàng | Chờ trạng thái chuyển sang Running; kiểm tra mục Nhật ký (Logs) và số lượng ready replica |
Model báo trạng thái Failed | Quá trình cấp phát hoặc thao tác vòng đời đã thử hết cách tự phục hồi | Đọc lý do trạng thái và mục Nhật ký (Logs) → Chẩn đoán triển khai (Deploy diagnostics) trước khi đổi cấu hình |
Sau khi chỉnh sửa, model vẫn ở trạng thái Deploying | Revision mới vẫn đang rollout | So sánh số lượng ready/desired replica và kiểm tra Nhật ký (Logs); đừng vội gửi chồng thêm chỉnh sửa khi chưa rõ tình hình |
Thao tác xóa kết thúc với trạng thái Delete failed | Quá trình giải phóng tài nguyên (teardown) chưa hoàn tất | Đọc thông báo lỗi và thử lại thao tác Xóa (Delete) — đây là hành động phục hồi cho trạng thái này |
Thời gian cấp phát tài nguyên không có một mốc cố định chung cho mọi model. Kích thước model, thời gian tải asset, Flavor phần cứng và thời gian khởi động runtime đều có ảnh hưởng. Thông báo tạo thành công chưa có nghĩa là model đã sẵn sàng.
Nhật ký (Logs) chứa cả chẩn đoán triển khai lẫn log phục vụ thực tế. Hãy đọc kỹ trước khi thay đổi bất kỳ cấu hình nào.
Sự cố khi gửi request
Mục “Sự cố khi gửi request”Hãy sử dụng tab Sao chép cURL (Copy as cURL) làm nguồn chuẩn xác nhất cho endpoint, path và giá trị model. Giữ API key trong biến môi trường theo hướng dẫn tại call guide, thay toàn bộ authorization header của lệnh cURL mẫu thành -H "Authorization: Bearer $ONX_INFERENCE_API_KEY", sau đó chạy thử. Nhờ vậy, chuỗi key không bị lưu lại trong shell history. Nếu lệnh cURL mẫu chạy thành công, hãy so sánh từng giá trị trong ứng dụng của bạn với câu lệnh đó.
| Kết quả | Ý nghĩa | Cách xử lý |
|---|---|---|
| Lỗi DNS hoặc lỗi kết nối | Request chưa gửi tới được API phục vụ | Sao chép lại endpoint; kiểm tra cấu hình DNS cục bộ, proxy và chính sách mạng nội bộ |
401 | Thiếu bearer token xác thực hoặc header gửi sai định dạng | Gửi kèm header Authorization: Bearer <key>; tạo key thay thế nếu đã làm mất secret |
403 | Credential bị từ chối hoặc Served Model Name hiện chưa được định tuyến | Kiểm tra key còn active, thuộc đúng tenant và có quyền truy cập host cùng Served Model Name này. Đảm bảo model dùng tên đó đang Running, sau đó kiểm tra lại lệnh cURL mẫu |
404 | URL hoặc path bị sai | Sử dụng chính xác đường dẫn <Endpoint>/v1/chat/completions như trong lệnh cURL mẫu |
Validation 4xx | Cấu trúc request hoặc tham số gửi kèm không được chấp nhận | Rút gọn request về đúng như lệnh cURL mẫu, sau đó bổ sung từng trường tùy chọn một |
429 | Request đã xác thực nhưng vượt giới hạn tần suất (rate limit) | Thử lại có giới hạn, kèm exponential backoff và jitter |
503 | Hệ thống phục vụ tạm thời không khả dụng | Kiểm tra trạng thái model, ready replica, Chỉ số (Metrics) và Nhật ký (Logs); chỉ thử lại có giới hạn |
| HTTP thành công nhưng không có câu trả lời cuối | Response có thể chỉ chứa phần reasoning hoặc client đọc sai trường dữ liệu | Kiểm tra toàn bộ response và đọc trường choices[0].message.content; chỉ thử lại hoặc điều chỉnh request sau khi xác nhận cấu trúc trả về |
Không thử lại nguyên trạng đối với các mã lỗi 401, 403, validation 4xx hoặc 404. Nếu luồng streaming đã bắt đầu phát dữ liệu, không tự động gửi lại toàn bộ request từ đầu.
Kiểm tra bộ ba giá trị cấu hình
Mục “Kiểm tra bộ ba giá trị cấu hình”Phần lớn lỗi phân quyền và định tuyến là do dùng lẫn lộn một trong ba giá trị sau:
- Endpoint hiển thị trên trang chi tiết của model;
- Inference API key đã cấp quyền cho Served Model Name của model đó; và
- Served Model Name chính xác của chính model đó.
Với Platform catalog thì khác: host của catalog dùng chung cần Platform key và đúng giá trị model trong lệnh cURL của dòng đã mở rộng. Đừng dùng Public model ID thay cho giá trị này. Xem chi tiết tại Tham chiếu API.
Khi tạo Inference key, chọn một model nghĩa là cấp quyền cho Served Model Name của model đó, chứ không chỉ riêng tài nguyên này. Một bản replacement trong cùng tenant tiếp tục dùng cùng Served Model Name cũng sẽ dùng được key này. Thao tác xóa model không revoke ủy quyền này; hãy chủ động thu hồi (revoke) key khi cần dừng quyền truy cập.
Giới hạn và lưu ý kỹ thuật
Mục “Giới hạn và lưu ý kỹ thuật”- Luồng Mô hình mở (
Open model) hỗ trợ các public repository trên Hugging Face theo dạngowner/name. Private hoặc gated repository nằm ngoài phạm vi này. - Mỗi self-hosted model được gắn với một nguồn model duy nhất lúc khởi tạo. Luồng Chỉnh sửa (
Edit) hiện tại không hỗ trợ đổi model nguồn, Served Model Name hoặc Flavor. - Giao diện Console hỗ trợ điều chỉnh replica thủ công cùng các thao tác vòng đời rõ ràng như Dừng (
Stop) và Khởi động lại (Restart). Đừng giả định hệ thống tự co giãn theo lưu lượng (autoscaling) hay tự scale-to-zero. - Nền tảng OneNexus công bố chuẩn giao tiếp
POST /v1/chat/completions; mức độ hỗ trợ các trường tùy chọn có thể khác nhau tùy theo model recipe và serving engine. Hãy luôn bắt đầu từ lệnh cURL mẫu do hệ thống tự động sinh ra. - Hệ thống không công bố giá trị chung cho mọi model về context, output token, concurrency, tần suất request, kích thước payload hay timeout. Hãy lấy model recipe và response thực tế của API làm chuẩn, đồng thời xác nhận các giới hạn riêng cho workload của bạn trong quá trình onboarding.
Cung cấp thông tin khi cần hỗ trợ kỹ thuật
Mục “Cung cấp thông tin khi cần hỗ trợ kỹ thuật”Khi liên hệ hỗ trợ, hãy cung cấp:
- Tên tenant và region;
- Tên tài nguyên của model và trạng thái hiện tại;
- Hostname của endpoint (không kèm thông tin xác thực);
- Served Model Name;
- Mốc thời gian UTC và mã trạng thái HTTP;
- Lý do trạng thái, các dòng chẩn đoán liên quan và mã định danh request nếu response có cung cấp; và
- Lệnh trong tab Sao chép cURL có chạy thành công hay không.
Tuyệt đối không gửi kèm API key, câu lệnh cURL chứa credential, prompt có nội dung nhạy cảm hoặc dữ liệu của khách hàng. Liên hệ đầu mối onboarding của bạn hoặc gửi email tới data-center@onemount.com.