TokenLab

核心指南

結構化輸出與工具呼叫

回傳 JSON 或讓模型呼叫您應用程式中的函式

結構化輸出要求模型回傳 JSON。工具呼叫則讓模型請求由您的應用程式執行的函式。可用的欄位取決於 API 格式與模型,因此請在整個對話過程中保持使用同一種格式,並在您的應用程式中驗證模型產生的每一個值。

選擇 API 格式

需求API欄位
可攜式 JSON 物件回應/v1/chat/completionsresponse_format: {"type": "json_object"}
相容於 OpenAI 的函式呼叫/v1/chat/completionstools: [{ "type": "function", "function": ... }]
OpenAI 回應工具/v1/responsesResponses tools、tool_choice 與 text 欄位
Claude 原生工具使用或思考/v1/messagesAnthropic Messages 工具架構
Gemini 函式宣告或內建工具/v1beta/models/:model:generateContentGemini 原生 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 會回傳函式名稱與參數;由您的應用程式執行它:

  1. 發送訊息以及工具定義。
  2. 讀取模型回應中的 tool_calls、function_call、Anthropic tool_use 或 Gemini 函式呼叫部分。
  3. 在您自己的後端執行該工具。
  4. 以相同的 API 格式附加工具執行結果。
  5. 繼續對話,直到模型回傳最終答案。

在工具呼叫與最終答案完成之前,請保持使用相同的 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 內容

本頁內容