工具调用

工具调用允许模型请求你的程序执行函数。模型只生成结构化参数，真正的数据库查询、网络请求或写操作仍由你的代码负责。

声明工具

curl https://sprelaytoken.com/v1/chat/completions \
  -H "Authorization: Bearer $SPRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "查询上海今天的天气。"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "查询指定城市的天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string", "description": "城市名称"}
            },
            "required": ["city"],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

标准执行循环

1. 发送用户消息和工具定义。
2. 检查模型是否返回工具调用。
3. 按 JSON Schema 验证参数。
4. 在服务端执行允许的工具。
5. 把工具结果连同调用 ID 回传模型。
6. 读取模型的最终答复。

安全边界

不信任模型参数

模型生成的工具名称和参数都属于不可信输入。必须使用允许列表、Schema 校验、权限检查和超时。不要直接拼接 SQL、Shell 命令或任意 URL。

• 写操作应要求业务确认或幂等键。
• 为工具设置独立超时和结果大小限制。
• 不把数据库凭证和内部错误堆栈返回给模型。
• 日志记录调用名称、耗时和结果状态，不记录敏感结果全文。
• 限制单轮最大工具调用次数，避免失控循环。

模型兼容性

并非所有模型都支持工具调用，支持程度也可能不同。先用一个简单、无副作用的工具验证；模型不支持时，移除 tools 后确认普通文本请求仍然正常。