Model Serving
Tích hợp API & Xử lý sự cố (Serving)
Giới thiệu
Sau khi Endpoint chuyển sang trạng thái 🟢 Running, bạn có thể bắt đầu tích hợp vào ứng dụng thông qua các giao thức REST API tiêu chuẩn.
Điều kiện tiên quyết
- Bạn đã đăng nhập vào hệ thống
- Bạn có quyền truy cập vào Project và policy Serving Endpoints
Tích hợp API và sử dụng Endpoint
Dưới đây là các phương thức phổ biến để tương tác với mô hình đang phục vụ.
Cách 1: Gọi API bằng cURL
Sử dụng dòng lệnh để kiểm tra nhanh kết nối và hiệu năng phản hồi.
# Thiết lập các tham số môi trường
ENDPOINT_URL="<YOUR_ENDPOINT_URL>" # Lấy tại tab Basic Info
ACCESS_KEY="<YOUR_ACCESS_KEY>" # Giá trị Access Key thực tế
MODEL_NAME="<YOUR_ENDPOINT_NAME>" # Tên định danh của endpoint
# Gọi API theo chuẩn OpenAI
curl -sS -X POST $ENDPOINT_URL/openai/v1/chat/completions \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '$ACCESS_KEY \
-d '{
"model": "'$MODEL_NAME'",
"messages": [
{"role": "user", "content": "<YOUR_PROMPT>"}
]
}'
Cách 2: Gọi API bằng Python
Tích hợp trực tiếp vào ứng dụng backend bằng thư viện requests.
import requests
# Cấu hình tham số
ENDPOINT_URL = "<YOUR_ENDPOINT_URL>"
ACCESS_KEY = "<YOUR_ACCESS_KEY>"
MODEL_NAME = "<YOUR_MODEL_NAME>"
# Thực thi yêu cầu POST
response = requests.post(
f"{ENDPOINT_URL}/openai/v1/chat/completions",
headers={
"Authorization": f"Bearer {ACCESS_KEY}",
"Content-Type": "application/json",
},
json={
"model": MODEL_NAME,
"messages": [{"role": "user", "content": "<YOUR_PROMPT>"}],
},
)
print(response.json())
Cách 3: Gọi qua AI Gateway (Quản lý tập trung)
Đối với các mô hình đã được gán nhãn OpenAI compatible và quảng bá lên AI Gateway, người dùng có thể thực hiện gọi qua một điểm truy cập duy nhất.
- Xác thực bằng Virtual Key: Khác với Access Key của từng endpoint, khi gọi qua AI Gateway, bạn sử dụng Virtual Key (Khóa ảo). Khóa này được quản lý tập trung và cho phép bạn theo dõi hạn mức (Quota), giới hạn số lượt gọi (Rate limit) một cách linh hoạt cho nhiều mô hình khác nhau.
- Tham số Header: Sử dụng
Authorization: Bearer <YOUR_VIRTUAL_KEY>. - Ưu điểm: Giấu đi địa chỉ vật lý của các endpoint thật, tăng cường bảo mật và khả năng quản soát lưu lượng tập trung của hệ sinh thái AI trong dự án.
Cấu trúc Request Body
Hệ thống hỗ trợ cấu hình linh hoạt cho kết quả đầu ra thông qua các tham số sau:
{
"model": "<tên-endpoint>",
"messages": [
{"role": "system", "content": "<SYSTEM_INSTRUCTION>"},
{"role": "user", "content": "<USER_INPUT>"}
],
"max_tokens": 512, // Giới hạn độ dài câu trả lời
"temperature": 0.7, // Độ sáng tạo của mô hình (0.0 - 1.0)
"stream": false // Bật/tắt chế độ truyền phát (streaming)
}
Bảng xử lý sự cố thường gặp
| Sự cố | Nguyên nhân phổ biến | Hướng xử lý |
|---|---|---|
| Endpoint báo Failed | Sai cấu hình, thiếu tài nguyên Cluster, hoặc Image model lỗi. | Xem tab Logs, tìm dòng ERROR để xác định nguyên nhân chi tiết -> Xóa và tạo lại với cấu hình tài nguyên cao hơn. |
| Lỗi 401 Unauthorized | Thiếu hoặc sai giá trị Access Key trong Header. | Kiểm tra tên Access Key trong tab Basic Info và đảm bảo giá trị key trong header Authorization là chính xác. |
| Lỗi 403 Forbidden | Access Key đã bị thu hồi (Revoked) hoặc không có quyền truy cập endpoint này. | Truy cập menu Access Keys để kiểm tra trạng thái hoặc tạo/gán một khóa mới. |
| Phản hồi rất chậm | Thiếu tài nguyên (CPU/Memory) so với độ lớn của mô hình. | Kiểm tra tab Metrics, nếu biểu đồ CPU Throttling cao -> Xem xét tăng tài nguyên (CPU/RAM) cho endpoint. |
| Log hiển thị trống | Pod đang trong quá trình khởi động hoặc chọn sai Pod trong menu. | Chờ 1-2 phút sau khi tạo, đảm bảo chọn đúng Pod trong dropdown Select pod để xem nhật ký. |
| Không tìm thấy mô hình khi tạo | Chưa đăng ký mô hình hoặc chọn sai nguồn (MLflow source). | Kiểm tra lại trong Model Registry, đảm bảo mô hình đã được đăng ký thành công vào đúng nguồn máy chủ. |
| Trạng thái kẹt ở Starting | Cluster hết tài nguyên (Resource quota exceeded) hoặc lỗi tải Image. | Xem tab Logs ngay sau khi tạo. Nếu không có dòng Log nào xuất hiện, hãy liên hệ Quản trị viên hệ thống để kiểm tra hạn mức tài nguyên Cluster. |
💡 Mẹo: Luôn test API bằng lệnh cURL trước khi tích hợp vào code phức tạp để đảm bảo Endpoint URL và Access Key hoạt động chính xác.