结构化输出与工具调用

结构化输出用于让模型返回 JSON；工具调用用于让模型提出函数调用，再由你的应用执行。可用字段取决于 API 格式和模型。同一段对话请保持一种格式，并在应用里校验模型生成的所有参数。

选择 API 格式Copy Anchor Link

内置工具只能配合对应的 API 格式使用；TokenLab 不会在不同格式之间转换这些工具。

JSON 模式Copy Anchor Link

需要返回 JSON 对象时，可以使用 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 是否可用取决于模型和 API 格式，只有模型文档明确支持时才能使用。

返回的 JSON 必须在服务端重新解析和校验。JSON 模式不能代替应用自己的 schema 校验。

完成一次工具调用Copy Anchor Link

TokenLab 会返回函数名和参数，真正执行函数的是你的应用：

1. 发送消息和工具定义。
2. 从响应中读取 tool_calls、function_call、Anthropic tool_use 或 Gemini 函数调用内容。
3. 在你自己的后端执行工具。
4. 用同一种 API 格式追加工具结果。
5. 继续对话，直到模型返回最终答案。

工具调用和最终回答完成前，请保持同一种 API 格式。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"]
          }
        }
      }
    ]
  }'

写好工具 schemaCopy Anchor Link

• Schema 尽量小而明确。层级过深会增加 tokens，也更容易生成错误参数。
• 产品没有某个值就无法继续时，把它设为必填字段。
• 值只允许固定选项时使用 enum。
• 模型经常填错格式时，在提示词里加入一个示例。
• 字段不受支持时，删除它，或换成明确支持它的 API 格式。

执行工具前Copy Anchor Link

• 日志中保存 API 格式、模型、工具名和 schema 字段名。
• 写入数据、发消息或付款前，必须校验工具参数。
• 工具仍要通过应用自己的权限检查。
• 同一次工具调用可能因重试重复执行时，使用幂等设计。
• 工具返回的密钥和隐私信息不能再发给模型。

API 参考Copy Anchor Link