BroadRouter
开始使用

开源模型的工具调用:schema、并行调用与重试

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 · 更新于

OpenAI 兼容 API 上的开源模型使用与 OpenAI 相同的 tools 和 tool_calls 格式。schema 要小而扁平,把参数当作 JSON 字符串解析,执行任何操作前先校验,并把错误作为工具结果返回给模型,让它重试。限制总步数。在 BroadNet 上,GLM 5.3 和 Qwen3.8 27B 列明支持工具。

工具调用是让模型变成智能体的关键。在 OpenAI 兼容 API 上使用开源模型时,请求格式与 OpenAI 完全相同。不同的是出错的频率,以及服务器为防止出错做了什么。本文介绍这种格式、如何编写开源模型容易处理的 schema、并行调用、你实际会遇到的五种失败,以及一个能扛住这些失败的 Python 循环。

OpenAI 兼容 API 上的工具调用是怎么工作的?

  1. 你发送 messages 和一个 tools 列表。每个工具都有名称、描述,以及描述其参数的 JSON Schema。
  2. 模型回复 finish_reason: "tool_calls" 和一个 tool_calls 列表。每一项都包含 id、函数名,以及 JSON 字符串形式的 arguments。
  3. 你的代码执行每个调用,并为每个调用追加一条 role: "tool" 消息,带上对应的 tool_call_id。
  4. 你再次调用 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")

这里有三个关键的设计选择:

  1. **错误作为工具结果返回给模型。**模型能看到哪里错了,通常会在下一轮修正。直接抛出异常就白白丢掉了这个机会。
  2. 循环有上限。max_steps 能让一个不断调用工具却毫无进展的模型停下来。
  3. **传输层重试单独处理。**客户端上的 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 能可靠地调用你的工具,再决定是否买一个月。

常见问题

开源模型支持函数调用吗?

很多都支持,但取决于模型本身以及服务商如何部署它。在 BroadNet Inference 上,文档为 GLM 5.3 和 Qwen3.8 27B 列出了工具调用,没有为 DeepSeek V4.1 Flash 或 Gemma 4 VL 26B 列出。

为什么工具调用的参数不是合法 JSON?

除非服务器约束了解码,参数是先作为文本生成、事后再解析的。vLLM 的文档说,从原始文本中提取的参数偶尔可能格式错误。捕获解析错误,并把它作为工具结果发回去,让模型自行纠正。

怎么关闭并行工具调用?

在 OpenAI 格式中,把 parallel_tool_calls 设为 false。这样模型每轮最多只会发起一次工具调用(也可能不调用)。请确认你的服务商支持这个字段。

为什么模型直接用文字回答,而不调用工具?

tool_choice 为 auto 时,由模型自己决定。必须调用时,把 tool_choice 设为 required,或指定某个函数。还要检查工具描述里有没有写明何时使用它。

为什么工具调用被截断了?

思考模型的思考过程计入 max_tokens。上限太小,回复可能在参数写到一半时就结束。检查 finish_reason 并提高 max_tokens。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity