> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 結構化輸出與工具調用

> 使用 JSON 模式、功能工具和原生工具路由，而不假設每個模型都支持相同的合約。

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

## 選擇路由

| 需求               | 路由                                      | 使用此形狀                                              |
| ---------------- | --------------------------------------- | -------------------------------------------------- |
| 可攜帶的 JSON 對象響應   | `/v1/chat/completions`                  | `response_format: {"type": "json_object"}`         |
| OpenAI 兼容的功能調用   | `/v1/chat/completions`                  | `tools: [{ "type": "function", "function": ... }]` |
| OpenAI 響應工具      | `/v1/responses`                         | 響應 `tools`、`tool_choice` 和 `text` 字段               |
| Claude 原生工具使用或思考 | `/v1/messages`                          | Anthropic Messages 工具架構                            |
| Gemini 功能聲明或內置工具 | `/v1beta/models/:model:generateContent` | Gemini 原生 `tools` 和內容部分                            |

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

## JSON 模式

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

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

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

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

## 工具調用循環

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

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

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

## Chat Completions 範例

```bash theme={null}
curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "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"]
          }
        }
      }
    ]
  }'
```

## 架構設計

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

## 生產檢查清單

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

## API 參考

| 主題           | 參考                                                             |
| ------------ | -------------------------------------------------------------- |
| 多格式 API      | [多格式 API](/zh-Hant/guides/api-formats)                         |
| 創建聊天完成       | [創建聊天完成](/zh-Hant/api-reference/chat/create-completion)        |
| 創建響應         | [創建響應](/zh-Hant/api-reference/responses/create-response)       |
| 創建消息         | [創建消息](/zh-Hant/api-reference/messages/create-message)         |
| 生成 Gemini 內容 | [生成 Gemini 內容](/zh-Hant/api-reference/gemini/generate-content) |