工具调用、结构化输出和流式响应是三项独立能力。先用同一模型跑通普通文本，再逐项验证，不要用一次成功推断其余能力也可用。
工具调用
下面的请求只让模型选择工具，不会真的执行函数：
curl https://router-api.xiu.ai/v1/chat/completions \
-H "Authorization: Bearer $XIUROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [
{
"role": "user",
"content": "台北现在几点？请使用工具。"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_time",
"description": "读取指定时区的当前时间",
"parameters": {
"type": "object",
"properties": {
"utc_offset": {
"type": "string"
}
},
"required": ["utc_offset"],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}'成功时，模型会在 choices[0].message.tool_calls 中返回工具名和参数。你的应用仍需：
- 校验工具名和参数。
- 在受控环境执行工具。
- 把结果作为
role: "tool"消息发回。 - 读取模型的最终回答。
普通文本成功但没有 tool_calls 时，先确认所选模型和当前服务分组支持工具调用，不要在客户端伪造工具结果。
结构化输出
Chat Completions 请求可以携带 response_format。下面示例要求返回固定 JSON 结构：
curl https://router-api.xiu.ai/v1/chat/completions \
-H "Authorization: Bearer $XIUROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [
{
"role": "user",
"content": "把北京归类为一个城市。"
}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "city",
"strict": true,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"country": {"type": "string"}
},
"required": ["name", "country"],
"additionalProperties": false
}
}
}
}'网关会解析 response_format，但目标模型可能只支持 json_object、不支持严格 Schema，或完全不支持结构化输出。生产代码仍要解析并校验返回值，不能因为请求带了 Schema 就跳过验证。
流式响应
使用 curl -N 避免本地缓冲：
curl -N https://router-api.xiu.ai/v1/chat/completions \
-H "Authorization: Bearer $XIUROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [
{
"role": "user",
"content": "用三句话说明什么是 API 网关。"
}
],
"stream": true,
"stream_options": {
"include_usage": true
}
}'Chat Completions 流通常以 SSE data: 事件返回，并以结束事件收口。Responses API 使用另一组事件类型；客户端要按实际协议解析，不要把两种流格式混在一起。
验证
- 工具：收到结构正确的
tool_calls，并完成一次只读工具往返。 - 结构化输出：返回值通过你的 JSON Schema 校验。
- 流式：收到多个事件、完整结束信号，并在“使用记录”中看到“流式”标记和最终费用。
常见失败
| 现象 | 处理 |
|---|---|
| 返回普通文本而不是工具调用 | 更换已验证工具能力的模型，或把 tool_choice 改为指定工具测试 |
response_format 被拒绝 |
降级为 json_object 或普通文本后自行校验 |
| 流在中途断开 | 确认使用 router-api.xiu.ai；保留请求 ID 并先查使用记录 |
| 流结束但没有用量事件 | 上游可能不支持 include_usage；以使用记录为最终核对入口 |
| 工具参数不是合法 JSON | 拒绝执行，记录原始参数并让模型重新生成 |
来源与核对日期
本文按 XiuRouter 当前 Chat Completions 请求结构、流式处理代码和控制台使用记录核对，日期为 2026-08-19。本轮没有使用真实 Key 对每个模型执行工具或结构化输出测试。