API Keural

Gọi các mô hình đã đăng ký trên Keural theo định dạng OpenAI Chat Completions.

Base URL có dạng https://<tên miền API công khai của bạn>/llm/v1. Tên miền API công khai khác nhau tùy theo môi trường; hãy hỏi quản trị viên.

Không hỗ trợ đường dẫn cho embeddings, tạo ảnh, giọng nói hay Responses API. Gửi yêu cầu tới các đường dẫn này sẽ nhận 404.

Quy trình sử dụngSao chép liên kết mục

Chuẩn bịSao chép liên kết mục

Cấp khóa APISao chép liên kết mục

1. Ở menu tài khoản góc dưới bên trái, mở Cài đặt → API. Trên ứng dụng máy tính và di động, mục này nằm trong nhóm Công cụ.
2. Ở tab API keys, chọn không gian làm việc mà khóa thuộc về (cá nhân hoặc tổ chức) và Model ID.
3. Nếu cần, đặt New key expiration (optional, Korea time). Nếu để trống, khóa không hết hạn cho đến khi bị thu hồi.
4. Nhấn Issue key, rồi sao chép khóa bằng Copy key và lưu lại ở nơi an toàn. Khóa đầy đủ chỉ hiển thị một lần tại thời điểm này.

• Khóa được gắn với không gian làm việc đã chọn và một mô hình. Mức sử dụng được ghi cho người đã cấp khóa.
• Mỗi cặp không gian làm việc và mô hình chỉ có một khóa dùng được. Nếu đã có khóa, không thể cấp thêm; hãy cấp lại (Rotate) hoặc thu hồi (Revoke) khóa hiện có.
• Nếu mất khóa, không có cách nào xem lại. Hãy cấp lại; khi đó khóa cũ ngừng hoạt động ngay lập tức.
• Nếu thấy thông báo không có mô hình nào khả dụng, hãy kiểm tra với quản trị viên về cài đặt hiển thị mô hình, gói dịch vụ và quyền API của tổ chức.

Quyền API của thành viên tổ chứcSao chép liên kết mục

Chỉ chủ sở hữu và quản trị viên tổ chức mới quản lý mục này. Để thành viên cấp khóa trong không gian làm việc của tổ chức, quản trị viên phải cho phép trước. Mặc định, tất cả thành viên đều bị chặn.

Quản lý tổ chức → Organization API gồm ba phần sau. Nếu không thấy menu này, tính năng API đang tắt hoặc tài khoản của bạn không có quyền quản trị tổ chức.

Khi thành viên rời tổ chức hoặc bị xóa khỏi tổ chức, các khóa họ nhận được trong tổ chức sẽ tự động bị thu hồi.

Kết nối với clientSao chép liên kết mục

Nhập ba giá trị sau vào các ứng dụng tương thích OpenAI API (ứng dụng chat, tiện ích IDE, công cụ tự động hóa, v.v.).

1. Trong cài đặt ứng dụng, chọn thêm kết nối tương thích OpenAI (Connection).
2. Nhập Base URL và API Key, rồi lưu.
3. Chọn một mô hình trong danh sách. Danh sách chỉ hiển thị mô hình được kết nối với khóa.
4. Gửi một tin nhắn ngắn để kiểm tra có nhận được phản hồi không.

Định dạng yêu cầu như sau.

Yêu cầu đầu tiênSao chép liên kết mục

export KEURAL_API_KEY='khóa_đã_cấp_của_bạn'
export KEURAL_BASE_URL='https://<tên-miền-api-của-bạn>/llm/v1'
export MODEL_ID='ID_mô_hình_trên_màn_hình_cấp_khóa'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Xin chào.\"}]}"

model trong nội dung yêu cầu phải khớp với mô hình được kết nối với khóa. Nếu có tiền tố đường dẫn như provider/ID_mô_hình, hệ thống so khớp phần sau dấu / cuối cùng. Nếu không khớp, API trả về 403. Phản hồi luôn chứa ID mô hình của khóa trong trường model.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Xin chào."}],
)
print(res.choices[0].message.content)

Các trường yêu cầu được hỗ trợSao chép liên kết mục

API chỉ nhận 18 trường cấp cao nhất sau. Nếu gửi trường khác, API trả về 400. Trường tùy chọn có giá trị null được xử lý như không gửi.

Tin nhắnSao chép liên kết mục

• Tin nhắn tool chỉ trả lời một lần cho mỗi id trong tool_calls trước đó.
• Phần hình ảnh (image_url) chỉ đặt trong tin nhắn user của mô hình hỗ trợ hình ảnh. Dùng địa chỉ http hoặc https, hoặc data URI base64 của PNG, JPEG, GIF hoặc WebP. detail có thể là auto, low hoặc high.

Nội dung yêu cầuSao chép liên kết mục

Vi phạm quy tắc nội dung sẽ trả về 400, với param là body.

StreamingSao chép liên kết mục

Nếu có "stream": true trong yêu cầu, phản hồi được gửi qua SSE. Mỗi đoạn được gửi dưới dạng sự kiện data: ..., và kết thúc bằng data: [DONE]. Nếu có "stream_options": {"include_usage": true}, một đoạn chứa mức sử dụng token được gửi thêm ngay trước [DONE].

Với include_usage, mọi đoạn đều chứa usage: null, và đoạn sử dụng cuối cùng có choices là mảng rỗng. Phản hồi không streaming chỉ có usage khi số token đầu vào và đầu ra đều đã được xác nhận.

id của phản hồi có dạng chatcmpl-<x-request-id>. Mọi phản hồi đều có header x-request-id.

Nếu lỗi xảy ra trong lúc streaming, sự kiện data: chứa JSON lỗi được gửi, rồi kết nối đóng mà không có [DONE]. Nếu một đoạn vượt quá 1 MiB hoặc phản hồi vượt quá 16 MiB, kết nối kết thúc với 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Xin chào.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Giới hạn sử dụngSao chép liên kết mục

Yêu cầu bị giới hạn theo người dùng, tổ chức và mô hình: số yêu cầu đồng thời, số yêu cầu mỗi phút (RPM) và số token mỗi phút (TPM). Giá trị thực tế khác nhau theo môi trường.

Token mỗi phút được trừ ngay khi nhận yêu cầu. Đầu vào tính 1 token cho mỗi 4 ký tự tiếng Anh, các ký tự khác tính 1 token mỗi ký tự; mỗi hình ảnh tính 2.000 token. Đầu ra được trừ theo max_tokens (tối đa 4.096), vì vậy nếu giới hạn đầu ra ở mức cần thiết, bạn sẽ còn nhiều dư địa trong hạn mức.

Quản lý khóaSao chép liên kết mục

Ở tab API keys trong Cài đặt → API, bạn xem được trạng thái các khóa đã cấp (hợp lệ, hết hạn hoặc đã thu hồi), cấp lại hoặc thu hồi khóa.

Khóa là chuỗi 51 ký tự bắt đầu bằng krl_llm_. Mỗi không gian cấp chỉ có một khóa dùng được; nếu đã có khóa, hệ thống cấp lại chứ không cấp mới. Ngày hết hạn chỉ đặt được từ hôm nay trở đi.

Xem mức sử dụngSao chép liên kết mục

Các yêu cầu gửi qua API và số token đã dùng được xem ở hai nơi.

Điều kiện truy vấnSao chép liên kết mục

Đặt điều kiện rồi nhấn Truy vấn. Để phản ánh các yêu cầu gần đây, nhấn Làm mới.

Giá trị hiển thị trên màn hìnhSao chép liên kết mục

• Khoảng thời gian truy vấn đã áp dụng: khoảng thời gian thực tế được truy vấn. Nếu bạn để trống thời gian bắt đầu hoặc kết thúc, hoặc vượt quá 90 ngày, màn hình hiển thị khoảng thời gian đã được máy chủ điều chỉnh.
• Số yêu cầu và tổng token đầu vào · token đầu ra · tổng token: chỉ cộng các giá trị đã xác nhận. Token chưa xác nhận không được tính là 0 mà hiển thị là Chưa xác nhận.
• Danh sách yêu cầu: mỗi yêu cầu là một dòng gồm thời điểm, Model ID, trạng thái và token đầu vào, đầu ra, tổng. Mỗi trang hiển thị 20 dòng; dùng Trước và Tiếp để chuyển trang.

Khi nhấn Chi tiết yêu cầu trên một dòng, các giá trị sau sẽ hiển thị.

Yêu cầu streaming vẫn ghi nhận mức sử dụng ngay cả khi không có stream_options.include_usage. Nếu yêu cầu bị ngắt giữa chừng, nó có thể ở trạng thái Xác nhận một phần hoặc Chưa xác nhận.

Định dạng lỗiSao chép liên kết mục

Lỗi được trả về theo định dạng tương thích OpenAI.

{
  "error": {
    "message": "Mô tả lỗi dễ hiểu cho người đọc",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type được xác định theo mã trạng thái, còn code cho biết nguyên nhân cụ thể.

Xử lý sự cốSao chép liên kết mục

Nếu vẫn không khắc phục được, hãy liên hệ quản trị viên và gửi kèm các thông tin dưới đây. Không gửi nội dung khóa và nội dung prompt.

• Thời điểm xảy ra
• Model ID đã dùng
• Tên và phiên bản ứng dụng client
• Giá trị x-request-id trong header phản hồi
• Thông báo lỗi hiển thị trên màn hình