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ầu | API | Các trường |
|---|---|---|
| Phản hồi đối tượng JSON di động | /v1/chat/completions | response_format: {"type": "json_object"} |
| Gọi hàm tương thích với OpenAI | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| Các công cụ phản hồi OpenAI | /v1/responses | Cá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/messages | Lượ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:generateContent | tools 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ó:
- Gửi các tin nhắn kèm theo định nghĩa công cụ.
- Đọc phản hồi của model để lấy
tool_calls,function_call,tool_usecủa Anthropic, hoặc các phần gọi hàm của Gemini. - Thực thi công cụ trong backend của riêng bạn.
- Đính kèm kết quả công cụ theo cùng định dạng API.
- 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ạng | Multi-Format API |
| Tạo Chat Completion | Tạo Chat Completion |
| Tạo Response | Tạo Response |
| Tạo Message | Tạo Tin nhắn |
| Tạo nội dung Gemini | Generate Gemini Content |