核心指南
結構化輸出與工具呼叫
回傳 JSON 或讓模型呼叫您應用程式中的函式
結構化輸出要求模型回傳 JSON。工具呼叫則讓模型請求由您的應用程式執行的函式。可用的欄位取決於 API 格式與模型,因此請在整個對話過程中保持使用同一種格式,並在您的應用程式中驗證模型產生的每一個值。
選擇 API 格式
| 需求 | API | 欄位 |
|---|---|---|
| 可攜式 JSON 物件回應 | /v1/chat/completions | response_format: {"type": "json_object"} |
| 相容於 OpenAI 的函式呼叫 | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| OpenAI 回應工具 | /v1/responses | Responses tools、tool_choice 與 text 欄位 |
| Claude 原生工具使用或思考 | /v1/messages | Anthropic Messages 工具架構 |
| Gemini 函式宣告或內建工具 | /v1beta/models/:model:generateContent | Gemini 原生 tools 與內容部分 |
請僅在記錄了該工具的 API 格式中使用內建工具;TokenLab 不會在不同格式之間轉換這些工具。
JSON 模式
若要取得適用於多種聊天模型的 JSON 物件,請使用 Chat Completions JSON 模式:
{
"model": "gpt-5.6-terra",
"messages": [
{
"role": "user",
"content": "Return a JSON object with city and weather."
}
],
"response_format": { "type": "json_object" }
}支援 JSON 模式的模型會在 GET /v1/models 的 capabilities 中列出 json-mode。Chat Completions 接受 text 與 json_object。json_schema 與 strict 是模型與格式專屬的;請僅在所選模型的文件中註明支援時才使用它們。
請務必在您的伺服器上解析並驗證回傳的 JSON。JSON 模式無法取代應用程式層級的架構驗證。
完成工具呼叫
TokenLab 會回傳函式名稱與參數;由您的應用程式執行它:
- 發送訊息以及工具定義。
- 讀取模型回應中的
tool_calls、function_call、Anthropictool_use或 Gemini 函式呼叫部分。 - 在您自己的後端執行該工具。
- 以相同的 API 格式附加工具執行結果。
- 繼續對話,直到模型回傳最終答案。
在工具呼叫與最終答案完成之前,請保持使用相同的 API 格式。這四種格式對工具狀態的呈現方式各不相同。
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"]
}
}
}
]
}'編寫實用的架構
- 保持架構簡潔且明確。大型巢狀架構會增加 token 消耗並降低可靠性。
- 對於產品運作不可或缺的值,請優先使用必要欄位 (required fields)。
- 對於您的 UI 或後端依賴的封閉集合,請使用列舉 (enums)。
- 當模型難以理解格式時,請在提示詞 (prompt) 中包含範例。
- 如果某個欄位不被支援,請將其移除或使用有記錄該欄位的 API 格式。
執行工具前
- 記錄 API 格式、模型、工具名稱與架構欄位名稱。
- 在執行任何副作用 (side effect) 前,請先驗證工具參數。
- 在執行工具前,請套用您自己的權限檢查。
- 當客戶端重試可能導致重複呼叫同一個工具時,請確保工具執行具有冪等性 (idempotent)。
- 請勿將工具回傳的機密資訊記錄到模型可見的訊息中。
API 參考
| 主題 | 參考 |
|---|---|
| 多格式 API | 多格式 API |
| 建立聊天完成 (Create Chat Completion) | 建立聊天完成 |
| 建立回應 (Create Response) | 建立回應 |
| 建立訊息 (Create Message) | 建立訊息 |
| 生成 Gemini 內容 (Generate Gemini Content) | 生成 Gemini 內容 |