結構化輸出與工具調用

結構化輸出和工具調用是路由特定的合約。TokenLab 轉發幾種公共 API 格式，因此最安全的生產模式是將每個供應商原生工具的形狀保留在擁有它的路由上，並在您自己的應用程序中驗證模型輸出。

選擇路由Copy Anchor Link

不要通過不同的路由發送供應商原生的內置工具，並期望 TokenLab 靜默地將它們轉換。

JSON 模式Copy Anchor Link

對於可攜帶的結構化響應，從 Chat Completions JSON 模式開始：

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "返回一個包含城市和天氣的 JSON 對象。"
    }
  ],
  "response_format": { "type": "json_object" }
}

Chat Completions 的穩定共享驗證接受 text 和 json_object。某些兼容路径或轉換路徑可能存在 json_schema、strict 和供應商特定的架構強制，但這並不是對每個 TokenLab 路由和模型的普遍承諾。在依賴它們之前，請根據所選模型進行驗證。

始終在您的伺服器上解析和驗證返回的 JSON。JSON 模式改善了形狀，但並不取代應用層級的架構驗證。

工具調用循環Copy Anchor Link

TokenLab 不執行您的函數。您的應用程序擁有循環：

1. 發送消息加上工具定義。
2. 讀取模型響應中的 tool_calls、function_call、Anthropic tool_use 或 Gemini 功能調用部分。
3. 在您自己的後端執行工具。
4. 以相同路由所需的格式附加工具結果。
5. 繼續對話，直到模型返回最終答案。

在工具循環中保持相同的路由。在一次對話中混合 Chat Completions、Responses、Messages 和 Gemini 格式通常會產生微妙的狀態和架構錯誤。

Chat Completions 範例Copy Anchor Link

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": "提取姓名和電子郵件作為 JSON。如果需要，查找客戶。"
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "通過電子郵件查找客戶",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

架構設計Copy Anchor Link

• 保持架構小而明確。大型嵌套架構會增加令牌並降低可靠性。
• 優先使用必需字段，對於您的產品無法繼續的值。
• 對於您的 UI 或後端依賴的封閉集合使用枚舉。
• 當模型在形狀上掙扎時，在提示中包含示例。
• 將不支持字段錯誤視為請求格式提示。刪除該字段或使用記錄它的原生路由。

生產檢查清單Copy Anchor Link

• 在日誌中記錄路由、模型、工具名稱和清理過的架構形狀。
• 在執行任何副作用之前驗證工具參數。
• 在工具執行之前應用您自己的權限檢查。
• 當客戶端重試可以重複相同的工具調用時，確保工具執行是冪等的。
• 不要將工具返回的秘密記錄到模型可見的消息中。

API 參考Copy Anchor Link