工具调用是让模型变成智能体的关键。在 OpenAI 兼容 API 上使用开源模型时,请求格式与 OpenAI 完全相同。不同的是出错的频率,以及服务器为防止出错做了什么。本文介绍这种格式、如何编写开源模型容易处理的 schema、并行调用、你实际会遇到的五种失败,以及一个能扛住这些失败的 Python 循环。
OpenAI 兼容 API 上的工具调用是怎么工作的?
- 你发送
messages和一个tools列表。每个工具都有名称、描述,以及描述其参数的 JSON Schema。 - 模型回复
finish_reason: "tool_calls"和一个tool_calls列表。每一项都包含id、函数名,以及 JSON 字符串形式的arguments。 - 你的代码执行每个调用,并为每个调用追加一条
role: "tool"消息,带上对应的tool_call_id。 - 你再次调用 API。模型给出回答,或者请求调用更多工具。
模型本身从不执行任何东西。执行什么由你的代码决定。
工具 schema 应该怎么写?
开源模型对简单的 schema 遵循得更可靠。下面这些规则来自 OpenAI 的指南,以及实践中容易出问题的地方:
- 按动作给工具命名,比如
read_file或search_code,并在描述中说明何时使用它。 - **工具列表要短。**OpenAI 的指南把“一轮开始时少于 20 个函数”作为一条软性建议。每个 schema 还会在每次调用时都发送一遍,见智能体的 token 预算。
- **参数尽量扁平。**字符串、数字、布尔值和枚举。避免深层嵌套和自由格式的对象。
- 固定选项用枚举,这样模型就编不出新值。JSON schema 生成器可以把一个参数示例对象转换成扁平的 schema,直接粘贴到
parameters里。 - **标明必填字段。**OpenAI 的严格模式要求
additionalProperties: false,所有字段都列入required,可选字段的类型里加上null。服务商是否强制执行strict各不相同,所以无论如何都要校验。
并行工具调用怎么处理?
模型可能在一轮中返回多个 tool_calls 条目,比如读取三个文件。互相独立的调用可以并发执行,每个 tool_call_id 返回一个结果,顺序不限。如果你的工具有相互依赖的副作用,就设置 parallel_tool_calls: false;OpenAI 的指南说,这会把模型限制为每轮最多一次调用(也可能不调用)。请测试你的服务商是否支持。
工具调用为什么会失败?
| 失败类型 | 你看到的 | 修复方法 |
|---|---|---|
| 参数格式错误 | json.loads 抛出异常 |
把解析错误作为工具结果返回;重试 |
| 不符合 schema | 缺字段、类型错误、编造的枚举值 | 校验;返回校验错误 |
| 未知工具 | 一个你从未定义过的名称 | 返回“unknown tool, available: …” |
| 该调用时没调用 | 直接用文字回答 | tool_choice: "required" 或指定函数 |
| 调用被截断 | finish_reason: "length" |
提高 max_tokens;思考与回答共用这个上限 |
前两种是意料之中的,并不罕见。vLLM 的工具调用文档说,在 auto 模式下,除非某个工具设置了 strict: true(或服务器强制了最低严格度)且该模型的解析器支持约束,否则 “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.”(译文:vLLM 从原始文本中提取工具调用,因此参数偶尔可能格式错误或违反函数的参数 schema。)指定函数时会使用 vLLM 的结构化输出后端。你的服务商部署模型的方式可能不同,所以要把校验当作必需步骤。
最后一行常常让使用思考模型的人中招。GLM 5.3 和 Qwen3.8 27B 会先思考再回答,而思考计入 max_tokens。为什么回复为空或被截断说明了要预留多少空间。
一个会校验并重试的工具循环
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up one order by its ID. Use when the user asks where an order is.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}
def run_call(call):
name = call.function.name
if name not in IMPL:
return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
try:
args = json.loads(call.function.arguments or "{}")
validate(args, SCHEMAS[name])
except (json.JSONDecodeError, ValidationError) as e:
return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
return str(IMPL[name](**args))
def agent(messages, max_steps=8):
for _ in range(max_steps):
r = client.chat.completions.create(model=MODEL, messages=messages,
tools=TOOLS, max_tokens=4000)
msg = r.choices[0].message
if r.choices[0].finish_reason == "length":
raise RuntimeError("Output limit reached; raise max_tokens")
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": call.id,
"content": run_call(call)})
raise RuntimeError("Step limit reached")
这里有三个关键的设计选择:
- **错误作为工具结果返回给模型。**模型能看到哪里错了,通常会在下一轮修正。直接抛出异常就白白丢掉了这个机会。
- 循环有上限。
max_steps能让一个不断调用工具却毫无进展的模型停下来。 - **传输层重试单独处理。**客户端上的
max_retries处理 429 和 5xx。错误的参数在循环里处理。不要把两者混在一起,见错误与重试。
对于有副作用的工具(比如发送邮件),要加上幂等键,这样重试的步骤不会执行两次。长时间运行的智能体一文讲到了这一点。
BroadNet 的哪些模型支持工具调用?
| 模型 | 是否列出工具 | 上下文 | 说明 |
|---|---|---|---|
| GLM 5.3 | 是 | 1,048,576 | 也支持结构化输出 |
| Qwen3.8 27B | 是 | 262,144 | 也支持图像输入 |
| DeepSeek V4.1 Flash | 未列出 | 1,048,576 | 支持图像输入;依赖工具前先测试 |
| Gemma 4 VL 26B | 未列出 | 32,768 | 不适合工具循环 |
要在两个支持工具的模型之间做选择,见 GLM 5.3 与 Qwen3.8 27B 对比。如果最终答案只需要符合某种结构、并不需要执行函数,结构化输出比工具更简单。
BroadNet Inference 适合什么场景
BroadNet Inference 通过标准的 chat completions 格式提供 GLM 5.3 和 Qwen3.8 27B,并列明支持工具调用,所以上面的循环无需修改就能用 OpenAI Python SDK 运行。按 token 的价格见价格页面。它不提供网页搜索或代码执行这类服务端工具,文档也没有为不限量套餐所用的模型 DeepSeek V4.1 Flash 列出工具调用。工具调用频繁的智能体,请按 token 使用 GLM 5.3 或 Qwen3.8 27B。如果你仍想用固定价格套餐,请先花 $1 买一个 Meteor 小时,确认 DeepSeek V4.1 Flash 能可靠地调用你的工具,再决定是否买一个月。
