TokenLab

Hướng dẫn cốt lõi

Structured Outputs & Tool Calling

Trả về JSON hoặc để model gọi các hàm trong ứng dụng của bạn

Structured output yêu cầu model trả về định dạng JSON. Tool calling cho phép model yêu cầu một hàm mà ứng dụng của bạn sẽ thực thi. Các trường khả dụng phụ thuộc vào định dạng API và model, vì vậy hãy giữ nguyên một định dạng trong suốt cuộc hội thoại và xác thực mọi giá trị do model tạo ra trong ứng dụng của bạn.

Chọn định dạng API

Nhu cầuAPICác trường
Phản hồi đối tượng JSON di động/v1/chat/completionsresponse_format: {"type": "json_object"}
Gọi hàm tương thích với OpenAI/v1/chat/completionstools: [{ "type": "function", "function": ... }]
Các công cụ phản hồi OpenAI/v1/responsesCác trường tools, tool_choice, và text của Responses
Sử dụng công cụ hoặc tư duy gốc của Claude/v1/messagesLược đồ công cụ Anthropic Messages
Khai báo hàm hoặc công cụ tích hợp của Gemini/v1beta/models/:model:generateContenttools và các phần nội dung gốc của Gemini

Chỉ sử dụng các công cụ tích hợp với định dạng API có tài liệu hướng dẫn cho chúng; TokenLab không chuyển đổi các công cụ đó giữa các định dạng.

Chế độ JSON

Đối với một đối tượng JSON hoạt động trên nhiều model chat, hãy sử dụng chế độ JSON của Chat Completions:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

Các model hỗ trợ chế độ JSON sẽ liệt kê json-mode trong phần capabilities tại GET /v1/models. Chat Completions chấp nhận text và json_object. json_schema và strict là các tham số cụ thể theo model và định dạng; chỉ sử dụng chúng khi model được chọn có tài liệu hỗ trợ.

Luôn phân tích cú pháp và xác thực JSON được trả về trên máy chủ của bạn. Chế độ JSON không thay thế việc xác thực lược đồ ở cấp độ ứng dụng.

Hoàn thành một tool call

TokenLab trả về tên hàm và các đối số; ứng dụng của bạn sẽ thực thi nó:

  1. Gửi các tin nhắn kèm theo định nghĩa công cụ.
  2. Đọc phản hồi của model để lấy tool_calls, function_call, tool_use của Anthropic, hoặc các phần gọi hàm của Gemini.
  3. Thực thi công cụ trong backend của riêng bạn.
  4. Đính kèm kết quả công cụ theo cùng định dạng API.
  5. Tiếp tục cuộc hội thoại cho đến khi model trả về câu trả lời cuối cùng.

Giữ nguyên định dạng API cho đến khi việc gọi công cụ và câu trả lời cuối cùng hoàn tất. Bốn định dạng này thể hiện trạng thái công cụ theo các cách khác nhau.

Ví dụ về Chat Completions

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

Viết lược đồ hữu ích

  • Giữ cho các lược đồ nhỏ gọn và rõ ràng. Các lược đồ lồng nhau lớn sẽ làm tăng số lượng token và giảm độ tin cậy.
  • Ưu tiên các trường bắt buộc (required) cho những giá trị mà sản phẩm của bạn không thể tiếp tục nếu thiếu chúng.
  • Sử dụng enum cho các tập hợp đóng mà UI hoặc backend của bạn phụ thuộc vào.
  • Bao gồm các ví dụ trong prompt khi model gặp khó khăn với cấu trúc dữ liệu.
  • Nếu một trường không được hỗ trợ, hãy xóa nó hoặc sử dụng định dạng API có tài liệu hỗ trợ trường đó.

Trước khi thực thi công cụ

  • Ghi lại định dạng API, model, tên công cụ và tên các trường trong lược đồ.
  • Xác thực các đối số của công cụ trước khi thực hiện bất kỳ tác dụng phụ (side effect) nào.
  • Áp dụng các kiểm tra quyền hạn của riêng bạn trước khi thực thi công cụ.
  • Đảm bảo việc thực thi công cụ là idempotent (lũy đẳng) khi client thử lại có thể lặp lại cùng một lệnh gọi công cụ.
  • Không ghi nhật ký (log) các bí mật do công cụ trả về vào các tin nhắn mà model có thể nhìn thấy.

Tài liệu tham khảo API

Chủ đềTham khảo
API đa định dạngMulti-Format API
Tạo Chat CompletionTạo Chat Completion
Tạo ResponseTạo Response
Tạo MessageTạo Tin nhắn
Tạo nội dung GeminiGenerate Gemini Content

Trên trang này