Gọi endpoint

Chỉ bắt đầu khi model ở trạng thái Running, trang chi tiết có endpoint và Sao chép cURL chứa request đầy đủ.

Gửi request đầu tiên

1. Tạo Inference API key.

   Mở Khóa API → Tạo khóa API. Chọn thời hạn, đặt Loại thành Self-hosted, rồi tick model cần gọi.

   Chọn một model sẽ authorize Served Model Name của model đó, không chỉ riêng resource này. Replacement trong cùng tenant tiếp tục dùng cùng Served Model Name sẽ dùng chung access; các Served Model Name khác đều bị từ chối. Xóa model không thay thế cho việc revoke key.

   Platform key là credential sai ở bước này: key không gọi được self-hosted model của tenant.

   Copy secret trong success dialog. Secret không thể hiển thị lại.

   

   Danh sách model chỉ xuất hiện khi Type là Self-hosted. Platform key không có danh sách này, vì nó không thể thu hẹp scope.

2. Copy tenant endpoint và Served Model Name.

   Mở model, copy Endpoint phía trên trang chi tiết và model string trong Sao chép cURL; string đó phải khớp chính xác với Served Model Name của model đó.

   Không dùng resource name của model, Hugging Face repository hoặc Public model ID của Platform catalog, trừ khi generated cURL cũng dùng đúng string đó.

   

   Hai giá trị trên cùng một màn hình: endpoint ở trên, và string model nằm trong lệnh được sinh ra.

3. Đặt local environment variable.

   Thay cả hai placeholder bằng giá trị đã copy. ONX_ENDPOINT là tenant endpoint hiển thị trên detail page của model, chưa nối thêm /v1.

   Bash hoặc zsh

   Terminal

   export ONX_ENDPOINT="<copied-endpoint>"
   export ONX_SERVED_MODEL="<served-model-name>"

   Chạy key prompt riêng rồi paste secret khi được hỏi:

   Terminal

   printf "OneNexus Inference API key: "; IFS= read -rs ONX_INFERENCE_API_KEY </dev/tty && export ONX_INFERENCE_API_KEY && printf "\n"

   PowerShell

   PowerShell

   $env:ONX_ENDPOINT = "<copied-endpoint>"
   $env:ONX_SERVED_MODEL = "<served-model-name>"
   $secret = Read-Host "OneNexus Inference API key" -AsSecureString
   $env:ONX_INFERENCE_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
   Remove-Variable secret

4. Chạy generated request trước.

   Command Sao chép cURL của model là source of truth cho endpoint, path và giá trị model. Không paste raw key vào command vì key có thể bị lưu trong shell history. Với Bash hoặc zsh, giữ environment variable đã được đọc an toàn ở bước 3 và thay toàn bộ authorization header của generated command bằng -H "Authorization: Bearer $ONX_INFERENCE_API_KEY". Giữ nguyên các giá trị khác.

   Request Bash/zsh sau khi thay:

   cURL

   curl "$ONX_ENDPOINT/v1/chat/completions" \
     -H "Authorization: Bearer $ONX_INFERENCE_API_KEY" \
     -H "Content-Type: application/json" \
     -d "{
       \"model\": \"$ONX_SERVED_MODEL\",
       \"messages\": [{\"role\": \"user\", \"content\": \"Hãy chào bằng một câu.\"}]
     }"

   API success là response 2xx có Chat Completions envelope hợp lệ; final-answer result hoàn chỉnh có choices array không rỗng và assistant content tại choices[0].message.content. Nếu final text rỗng, hãy kiểm tra full response trước khi retry; một số model có thể trả reasoning mà không có final content.

5. Gọi cùng endpoint bằng Python.

   Cài SDK:

   Terminal

   python -m pip install openai

   Lưu đoạn sau thành endpoint_call.py, rồi chạy python endpoint_call.py:

   endpoint_call.py

   import os
   
   from openai import OpenAI
   
   endpoint = os.environ["ONX_ENDPOINT"].rstrip("/")
   client = OpenAI(
       base_url=f"{endpoint}/v1",
       api_key=os.environ["ONX_INFERENCE_API_KEY"],
   )
   
   response = client.chat.completions.create(
       model=os.environ["ONX_SERVED_MODEL"],
       messages=[{"role": "user", "content": "Hãy chào bằng một câu."}],
   )
   
   print("Success:", response.choices[0].message.content)

   Khi thành công, terminal in message do model tạo với prefix Success:.

Luôn giữ ba giá trị cùng nhau

Coi ba giá trị sau là một configuration unit:

1. tenant endpoint hiển thị trên detail page của model;
2. Inference API key authorize Served Model Name của model đó; và
3. Served Model Name chính xác.

Lỗi thường gặp là ghép hai giá trị đúng của một model với giá trị thứ ba từ Platform catalog hoặc model khác.

Trước khi tích hợp application

• Lưu key trong server-side secret store hoặc environment variable được bảo vệ, không đặt trong browser bundle hay repository.
• Đặt application timeout.
• Không retry 401, 403, validation 4xx hoặc 404 nguyên trạng.
• Với transient 429 hoặc 503, chỉ retry số lần hữu hạn bằng exponential backoff và jitter.
• Nếu stream đã phát data, không tự động replay toàn bộ request.

Xem Tham chiếu API để biết request contract, hoặc troubleshooting nếu generated cURL không thành công.