Khắc phục sự cố self-hosted model
Trước tiên hãy xác định failure boundary. Deployment problem xảy ra trước khi public route sẵn sàng; request problem xảy ra sau khi client đã tới endpoint.
Deployment problem
Phần tiêu đề “Deployment problem”| Symptom | Boundary thường gặp | Kiểm tra tiếp |
|---|---|---|
| Thiết lập workspace thay thế nội dung trang | Tenant chưa có workspace trong region này | Tạo workspace từ màn hình đó, Tổng quan hoặc Workspace |
Triển khai mô hình (Deploy model) hoặc GPU action ở trạng thái read-only | Chưa có Inference GPU quota trong region đã chọn | Kiểm tra Hạn mức (Quotas) và region trên header |
| Registry model version không có trong Mô hình của bạn | Version chưa finalize hoặc không phải servable full-weight artifact | Kiểm tra version status trong Mô hình (Models) |
| Model chưa có endpoint hoặc usable cURL | Route chưa sẵn sàng | Đợi Running; kiểm tra Nhật ký (Logs) và ready replica |
Model ở Failed | Provisioning hoặc lifecycle operation đã hết recovery path | Đọc status reason và Nhật ký (Logs) → Chẩn đoán triển khai (Deploy diagnostics) trước khi đổi configuration |
Một edit vẫn ở Deploying | Revision mới còn đang rollout | So sánh ready/desired replica và Nhật ký (Logs); không tiếp tục chồng thêm edit |
Delete kết thúc ở Delete failed | Teardown chưa hoàn tất | Đọc error rồi retry Xóa (Delete), đây là recovery action của status này |
Không có một provisioning duration chung cho mọi model. Model size, asset download, Flavor và runtime startup đều ảnh hưởng. Không coi create success notification là readiness signal.
Nhật ký (Logs) chứa cả deploy diagnostics lẫn serving output. Đọc nó trước khi đổi bất kỳ configuration nào.
Request problem
Phần tiêu đề “Request problem”Dùng Sao chép cURL làm source of truth cho endpoint, path và giá trị model. Giữ key trong environment variable theo call guide, thay toàn bộ authorization header của generated command bằng -H "Authorization: Bearer $ONX_INFERENCE_API_KEY", rồi chạy. Cách này không để raw key trong shell history. Nếu command chạy được, so sánh application với nó từng giá trị một.
| Kết quả | Ý nghĩa | Cách xử lý |
|---|---|---|
| DNS hoặc connection failure | Request chưa tới serving API | Copy lại endpoint; kiểm tra local DNS, proxy và network policy |
401 | Bearer credential bị thiếu hoặc sai format | Gửi Authorization: Bearer <key>; tạo key thay thế nếu mất secret |
403 | Credential bị từ chối hoặc Served Model Name hiện không được route | Kiểm tra key còn active, thuộc đúng tenant và authorize host cùng Served Model Name này. Xác nhận một model dùng name đó đang Running, rồi kiểm tra lại generated request. |
404 | URL hoặc path sai | Dùng chính xác <Endpoint>/v1/chat/completions như generated sample |
Validation 4xx | Request shape hoặc option không được chấp nhận | Thu request về generated example, rồi thêm optional field từng cái một |
429 | Đã chạm request-rate ceiling sau authentication | Retry số lần hữu hạn bằng exponential backoff và jitter |
503 | Serving path tạm thời không khả dụng | Kiểm tra status, ready replica, Chỉ số (Metrics) và Nhật ký (Logs); chỉ retry số lần hữu hạn |
| HTTP success nhưng không có final text | Response có thể chỉ chứa reasoning hoặc client đọc sai field | Kiểm tra full response và đọc choices[0].message.content; chỉ retry hoặc chỉnh request sau khi xác nhận response shape |
Không retry 401, 403, validation 4xx hoặc 404 nguyên trạng. Nếu stream đã phát data, không tự động replay toàn bộ request.
Kiểm tra tuple ba giá trị
Phần tiêu đề “Kiểm tra tuple ba giá trị”Phần lớn lỗi authorization và routing đến từ việc trộn một trong ba giá trị:
- Endpoint từ trang chi tiết của model;
- Inference API key authorize Served Model Name của model đó; và
- Served Model Name chính xác của chính model đó.
Platform catalog dùng giá trị khác: shared catalog host yêu cầu Platform key và đúng giá trị model trong cURL request của dòng đã mở rộng. Không thay bằng Public model ID. Xem API reference.
Chọn một model khi tạo Inference key sẽ authorize Served Model Name tương ứng, không chỉ riêng resource này. Replacement trong cùng tenant tiếp tục dùng cùng Served Model Name cũng dùng được key. Delete không revoke authorization này; hãy revoke key trực tiếp khi cần dừng access.
Known boundary
Phần tiêu đề “Known boundary”- Mô hình mở (
Open model) document public Hugging Face repository theo dạngowner/name. Private hoặc gated repository nằm ngoài flow này. - Mỗi self-hosted model bind một model source lúc create. Chỉnh sửa (
Edit) flow hiện tại không đổi model, Served Model Name hoặc Flavor. - Console expose manual replica count cùng lifecycle action Dừng (
Stop) và Khởi động lại (Restart). Không giả định có traffic-based autoscaling hoặc scale-to-zero. - OneNexus document
POST /v1/chat/completions; optional field support có thể khác theo model recipe và serving engine. Hãy bắt đầu bằng generated cURL. - Không có một context, output-token, concurrency, request-rate, payload-size hoặc timeout value được publish chung cho mọi model. Dùng model recipe và API response quan sát được làm contract, rồi xác nhận workload-specific limit trong onboarding.
Escalate với context hữu ích
Phần tiêu đề “Escalate với context hữu ích”Hãy gửi:
- tenant và region;
- resource name của model và status hiện tại;
- endpoint hostname, không kèm credential;
- Served Model Name;
- UTC timestamp và HTTP status;
- status reason, diagnostic line liên quan và request identifier nếu response có cung cấp; và
- kết quả Sao chép cURL có thành công hay không.
Không bao giờ gửi API key, cURL chứa credential, sensitive prompt hoặc customer data. Liên hệ onboarding owner hoặc data-center@onemount.com.