---
title: "开源模型工具调用（Function Calling）：schema、重试与代码 | BroadRouter"
description: "OpenAI 兼容开源模型上的函数调用：schema 编写要点、并行工具调用、工具调用失败的五种情况，以及一个会校验并重试的 Python 循环。"
url: https://broadrouter.com/zh/blog/tool-calling-open-models/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。 [阅读英文原文](https://broadrouter.com/blog/tool-calling-open-models/) (2026-11-16 更新).

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

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 2026-11-14 · 更新于 2026-11-16

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

## 要点

-   传输格式与 OpenAI 相同：请求里传 tools 列表，回复里返回 tool\_calls，然后每个 tool\_call\_id 对应一条 role 为 tool 的消息。
-   参数以 JSON 字符串的形式返回。vLLM 的文档提醒，从原始文本中提取工具调用时，它们 "may occasionally be malformed or violate the function's parameter schema"（译文：偶尔可能格式错误或违反函数的参数 schema）。
-   校验每一次调用，把错误作为工具结果发回去，并限制重试次数和总步数。
-   工具越少、越扁平，效果越好。OpenAI 建议一轮开始时少于 20 个函数。
-   在 BroadNet Inference 上，工具调用请用 GLM 5.3 或 Qwen3.8 27B；DeepSeek V4.1 Flash 要先测试再依赖。

**本页内容**

1.  OpenAI 兼容 API 上的工具调用是怎么工作的？
2.  工具 schema 应该怎么写？
3.  并行工具调用怎么处理？
4.  工具调用为什么会失败？
5.  一个会校验并重试的工具循环
6.  BroadNet 的哪些模型支持工具调用？
7.  BroadNet Inference 适合什么场景

[工具调用](https://broadrouter.com/zh/glossary/tool-calling/)是让模型变成智能体的关键。在 [OpenAI 兼容 API](https://broadrouter.com/zh/glossary/openai-compatible-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 预算](https://broadrouter.com/zh/blog/agent-token-budget/)。
-   \*\*参数尽量扁平。\*\*字符串、数字、布尔值和枚举。避免深层嵌套和自由格式的对象。
-   **固定选项用枚举**，这样模型就编不出新值。[JSON schema 生成器](https://broadrouter.com/tools/json-schema-generator/)可以把一个参数示例对象转换成扁平的 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 的结构化输出后端。你的服务商部署模型的方式可能不同，所以要把校验当作必需步骤。

最后一行常常让使用[思考模型](https://broadrouter.com/zh/glossary/reasoning-tokens/)的人中招。GLM 5.3 和 Qwen3.8 27B 会先思考再回答，而思考计入 [`max_tokens`](https://broadrouter.com/zh/glossary/max-tokens/)。[为什么回复为空或被截断](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)说明了要预留多少空间。

## 一个会校验并重试的工具循环

```python
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。错误的参数在循环里处理。不要把两者混在一起，见[错误与重试](https://broadrouter.com/zh/guides/errors-and-retries/)。

对于有副作用的工具（比如发送邮件），要加上幂等键，这样重试的步骤不会执行两次。[长时间运行的智能体](https://broadrouter.com/zh/blog/long-running-agents-timeouts-retries/)一文讲到了这一点。

## BroadNet 的哪些模型支持工具调用？

| 模型 | 是否列出工具 | 上下文 | 说明 |
| --- | --- | --- | --- |
| [GLM 5.3](https://broadrouter.com/zh/models/glm-5.3/) | 是 | 1,048,576 | 也支持结构化输出 |
| [Qwen3.8 27B](https://broadrouter.com/zh/models/qwen3.8-27b/) | 是 | 262,144 | 也支持图像输入 |
| [DeepSeek V4.1 Flash](https://broadrouter.com/zh/models/deepseek-v4.1-flash/) | 未列出 | 1,048,576 | 支持图像输入；依赖工具前先测试 |
| [Gemma 4 VL 26B](https://broadrouter.com/zh/models/gemma-4-vl-26b/) | 未列出 | 32,768 | 不适合工具循环 |

要在两个支持工具的模型之间做选择，见 [GLM 5.3 与 Qwen3.8 27B 对比](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)。如果最终答案只需要符合某种结构、并不需要执行函数，[结构化输出](https://broadrouter.com/zh/blog/structured-output-json-schema/)比工具更简单。

## BroadNet Inference 适合什么场景

BroadNet Inference 通过标准的 chat completions 格式提供 GLM 5.3 和 Qwen3.8 27B，并列明支持工具调用，所以上面的循环无需修改就能用 [OpenAI Python SDK](https://broadrouter.com/zh/guides/openai-python-sdk/) 运行。按 token 的价格见[价格页面](https://broadrouter.com/zh/pricing/)。它不提供网页搜索或代码执行这类服务端工具，文档也没有为不限量套餐所用的模型 DeepSeek V4.1 Flash 列出工具调用。工具调用频繁的智能体，请按 token 使用 GLM 5.3 或 Qwen3.8 27B。如果你仍想用固定价格套餐，请先花 $1 买一个 Meteor 小时，确认 DeepSeek V4.1 Flash 能可靠地调用你的工具，再决定是否买一个月。

相关免费工具 （英文）

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[免费工具 （英文）](https://broadrouter.com/tools/)

## 本文涉及的术语

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

[vLLM](https://broadrouter.com/zh/glossary/vllm/)

vLLM 是一个用于 LLM 推理和服务部署的开源库，最初由加州大学伯克利分校 Sky Computing Lab 开发。它用 PagedAttention 管理 KV 缓存内存，对请求做连续批处理，支持多种量化格式，并提供 OpenAI 兼容的 HTTP 服务器。

[结构化输出（structured output）](https://broadrouter.com/zh/glossary/structured-output/)

结构化输出是大模型 API 的一项功能，它把模型的回复约束为开发者指定的格式（通常是 JSON Schema），让代码能可靠地解析。它比 JSON mode 更严格：JSON mode 只保证输出是合法 JSON，不保证特定结构。

[开放权重模型（open-weight model）](https://broadrouter.com/zh/glossary/open-weight-model/)

开放权重模型是公开发布训练好的权重、任何人都可以下载和运行的机器学习模型，通常附带有条件的许可证。它不同于完全开源的 AI，后者还会公开训练代码和训练数据的详细信息，让其他人能够研究并复现模型。

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

[JSON Schema](https://broadrouter.com/zh/glossary/json-schema/)

JSON Schema 是一套用 JSON 编写的词汇，用于描述和校验 JSON 数据的结构：类型、必填字段、允许的取值和嵌套。当前版本是 2020-12。大模型 API 用它来定义工具参数，以及结构化输出必须遵循的确切结构。

[并行工具调用（parallel tool calls）](https://broadrouter.com/zh/glossary/parallel-tool-calls/)

并行工具调用是指模型在一次响应中返回多个工具调用，例如同时读取三个文件。在 OpenAI 格式中，它们表现为 tool\_calls 里的多个条目；把 parallel\_tool\_calls 设为 false，可把模型限制为每轮调用零个或一个工具。

## 常见问题

### 开源模型支持函数调用吗？

很多都支持，但取决于模型本身以及服务商如何部署它。在 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。

## 继续阅读

-   [OpenClaw 和 Hermes Agent 接便宜模型：配置与 token 账](https://broadrouter.com/zh/blog/openclaw-hermes-agent-cheap-model/)
-   [JSON 模式与 json\_schema：靠得住的结构化输出](https://broadrouter.com/zh/blog/structured-output-json-schema/)
-   [用 OpenAI 兼容模型接入 MCP 服务器（任意服务商）](https://broadrouter.com/zh/blog/mcp-with-openai-compatible-models/)
-   [长时间运行的智能体：可靠的超时、重试与检查点](https://broadrouter.com/zh/blog/long-running-agents-timeouts-retries/)
-   [智能体 token 预算：智能体循环的 token 都花在哪里](https://broadrouter.com/zh/blog/agent-token-budget/)
-   [BroadNet 的 GPU 硬件与推理部署方式（据 BroadNet 自述）](https://broadrouter.com/zh/blog/broadnet-gpu-fleet-and-serving/)
-   [缓存大模型 API 响应以降低成本：用 Python 实现精确匹配缓存](https://broadrouter.com/zh/blog/cache-llm-responses-cut-cost/)
-   [指南：用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)
-   [指南：在 BroadNet Inference 上运行 OpenAI Agents SDK](https://broadrouter.com/zh/guides/openai-agents-sdk-custom-provider/)
-   [指南：推理模型为什么返回空回答](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)
-   [指南：BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/)

用你的真实业务负载试一试。 新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-tool-calling-open-models&utm_content=page-cta) ·

**来源**

-   [OpenAI 函数调用指南（2026-11-14 查阅）](https://developers.openai.com/api/docs/guides/function-calling)
-   [vLLM 文档：工具调用（2026-11-14 查阅）](https://docs.vllm.ai/en/latest/features/tool_calling/)
-   [BroadNet Inference API 参考：模型 （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-tool-calling-open-models&utm_content=sources#models)
