工具调用设计:让模型一次就选对函数
一、学完这一节能交出的四样东西
先看一个数字:get_order 这个工具上线第一周,调用成功率是 61%。
那周我们收到的用户抱怨全是「答非所问」,但看日志,模型每次都规规矩矩地调了工具,参数也合法。问题出在它调的那个工具,和用户想问的事根本不是一回事。
这一节要解决的就是这件事:你写了五个工具,模型每次能不能挑对那个,参数能不能填对。跟模型聪不聪明没关系,跟你把工具描述成什么样有关系。
学完你应该能交出:
- 一份模型看得懂的工具描述,并说得出它为什么比函数名重要
- 一个在 strict 模式下不会被打回来的参数 schema
- 一次请求该不该开并行调用的判断,以及并行之后消息怎么拼回去
- 一套让失败变成「模型能自愈的信息」的重试路径,而不是一个 500
版本基线先摆清楚。截至 2026 年 11 月,三家 SDK 的主线分别是 OpenAI Python SDK 3.x、Anthropic Python SDK 2.x、MCP Python SDK 2.x;模型侧的代号一两个月换一轮(OpenAI 的 GPT-6.1 系列、Anthropic 的 Claude 5.5 系列、国内的 Qwen3.8 系列、GLM-5.x、Kimi K3 系列、DeepSeek 的 flash 档)。这些名字引用前必须复核各家文档,本文只保证截至 2026 年 11 月的写法,官方入口见 OpenAI 函数调用文档、Anthropic 工具使用文档、DeepSeek 函数调用文档。凡本文出现具体价格、上下文长度与基准分数的地方,一律不给数字,原因在第七节说明。
一个贯穿全文的坐标先说:模型不执行任何函数,它只输出「函数名 + 一段 JSON 字符串」,执行权在你手里。所有设计约束都从这一句推出来。
二、工具调用在链路里的位置
一张图能省掉一半解释。
三个推论,每个都能变成一条设计规则。
模型能看见的只有 name、description 和 parameters 三样东西。你的注释、你的 README、你在群里说的「这个接口别乱调」,它都看不到。
执行错误必须由你翻译。数据库抛的 psycopg.errors.UndefinedColumn 对模型没有信息量,改成「status 只能是 pending/shipped/cancelled,你传的 'unshipped' 不在其中」它才知道怎么改。
工具是花钱的上下文。每个工具定义都占 token,二十个工具塞进 system 之后,光列表就吃掉几千 token,而且选择难度随数量上升。
三、导入案例:一个查订单工具的三次改版
去年秋天我们做一个客服侧的助手,第一个工具长这样:
{
"type": "function",
"function": {
"name": "get_order",
"description": "查询订单",
"parameters": {
"type": "object",
"properties": {"id": {"type": "string"}},
"required": ["id"],
},
},
}上线第一周,get_order 的调用成功率大概六成。失败分三类:模型把「我上个月买的那双鞋」整个塞进 id;模型传 "订单号:DD20261015001",前缀是它自己加的;还有一类是用户问退款,模型硬调 get_order 去猜。
第二版我们只改描述,不动代码:
{
"name": "get_order_by_no",
"description": (
"按订单号精确查询单个订单的状态与物流。"
"只在用户已提供形如 DD+11位数字 的订单号时使用。"
"若用户描述的是商品、时间范围或手机号,改用 list_orders_by_phone。"
"退款进度、发票、售后工单不在此工具范围内。"
),
"parameters": {
"type": "object",
"properties": {
"order_no": {
"type": "string",
"pattern": "^DD\\d{11}$",
"description": "订单号,格式 DD 加 11 位数字,例如 DD20261015001",
}
},
"required": ["order_no"],
"additionalProperties": False,
},
}调用成功率到了八成五左右。剩下的问题不是描述能解的:有些人只有一个手机号。于是第三版拆成两个工具,list_orders_by_phone 负责模糊入口,get_order_by_no 只负责精确查询,两个描述互相指向。
这里有个反直觉的地方:把描述写长、写清「什么时候别用」,效果比拆工具更稳。拆工具是在扩大选择空间,而模型的选择能力不是线性增长的。先穷尽描述,再考虑拆分。
四、四件事决定调用对不对
描述写「何时用」,不是写「做了什么」
四种写法排在一起看,越往下越省事。我们实测从第一行走到第三行,误调用率砍掉了大约一半。
| 写法 | 例子 | 模型读到的信号 |
|---|---|---|
| 只写功能 | 「查询订单」 | 凡是跟订单有关都可能命中 |
| 写功能 + 触发条件 | 「用户已提供订单号时使用」 | 命中有前提 |
| 写功能 + 触发条件 + 排除项 | 「退款进度不在此工具范围」 | 排除掉一整类误调用 |
| 写功能 + 示例值 | 「格式 DD 加 11 位数字,如 DD20261015001」 | 参数形态有锚点 |
排除项比触发条件更值钱。因为模型犯的错八成是「过度使用」,而不是「不敢用」。
schema 用 enum 收窄,别用自然语言约束
description: "状态只能是 pending 或 shipped" 是句请求,enum: ["pending", "shipped"] 是道闸门。前者在 strict 关闭时全凭模型自觉,后者在解码阶段就被约束住。日期用 format: "date",邮箱用 format: "email",取值的正则用 pattern。
但 enum 有代价。我们试过把一个 300 多 SKU 的商品目录塞进 enum,模型开始选到相邻项,而且工具定义的 token 直接涨了四倍。这种情况应该改成「模型选分类,代码查明细」。
并行调用:什么时候开,什么时候必须关
OpenAI 的 parallel_tool_calls 默认是 true,一次响应里可以回来多个 tool_calls。判断标准很简单:这几个调用之间有没有依赖。
互相独立的(查三个城市的天气、读四个文件)该开,能把串行等待压成一次等待。有依赖的(先查订单拿到 user_id,再查用户画像)必须关,否则模型会基于猜的 user_id 并发去查,四条结果全错,而且错得很难查。
拼消息时有个硬约束:每个 tool_call_id 都要有一条对应的 role="tool" 消息,缺一条下一次请求就 400。我们线上有过一次这样的故障,模型并发发了三个调用,其中一个超时被我们的代码 continue 掉了,结果整个会话卡死,报错长这样:
openai.BadRequestError: Error code: 400 - {'error': {'message': "An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. The following tool_call_ids did not have response messages: call_8fQ2..."}}所以并发执行可以,但结果的拼装必须补全,失败的那个也要写一条 is_error 语义的 tool 消息回去。
失败重试:先把错误分类
工具失败分两种,处理方式完全不同。
协议级失败(工具名不存在、参数不符合 schema)应该重试,而且要在提示里告诉模型「你刚才传的 X 不合法,合法值是什么」。业务级失败(订单不存在、余额不足)不该重试,直接把事实写回给模型,让它换路径或告诉用户。
import json
from pydantic import ValidationError
def call_model_with_tools(messages, tools, max_rounds=4):
for round_no in range(max_rounds):
resp = client.chat.completions.create(
model=MODEL_ID, # 从配置读,别写死在代码里(见第一节的版本基线)
messages=messages, tools=tools,
parallel_tool_calls=True,
)
msg = resp.choices[0].message
if not msg.tool_calls:
return msg.content
messages.append(msg)
for tc in msg.tool_calls:
try:
out = dispatch(tc.function.name, json.loads(tc.function.arguments))
messages.append({"role": "tool", "tool_call_id": tc.id, "content": out})
except ValidationError as e:
# 协议级:把合法取值写回去,让模型自纠
messages.append({"role": "tool", "tool_call_id": tc.id,
"content": f"参数不合法:{e}. 状态只能是 pending/shipped/cancelled。"})
except BusinessError as e:
# 业务级:陈述事实,不建议重试
messages.append({"role": "tool", "tool_call_id": tc.id,
"content": f"查询失败:{e}. 请换一种方式或告知用户。"})
return "工具调用轮次超限,请人工介入"预期输出:正常情况下第 2 轮就返回自然语言;参数错的那条会在第 3 轮被模型自己修正;轮次超限时会看到那句兜底文案出现在日志里。
五、动手任务:给 schema 做一次 strict 体检
strict 模式是省钱的东西,但它对 schema 很挑。截至 2026 年 11 月,三家口径可直接对照官方文档:OpenAI 的 structured outputs 要求所有字段进 required、additionalProperties 为 false,只接受 JSON Schema 的一个子集,带默认值的可选参数会被打回;Anthropic 的 strict tool use 同为 opt-in,用了不支持的特性会拿到 400;DeepSeek 的 strict 走 beta 路径(base_url="https://api.deepseek.com/beta"),每个 function 都要显式 strict: true,服务端先校验 schema,minLength、maxLength、minItems、maxItems 这几个不支持。这三家的共同点是「宁可拒绝你的请求,也不在你不知情时放松校验」,所以体检脚本的价值在于把报错提前到本地。
写个小脚本先自检,比等线上报错便宜:
def strict_audit(schema, path="$"):
problems = []
if schema.get("type") == "object":
if schema.get("additionalProperties") is not False:
problems.append(f"{path}: 缺 additionalProperties=false")
props = set(schema.get("properties", {}))
req = set(schema.get("required", []))
if props - req:
problems.append(f"{path}: 这些字段没进 required → {sorted(props - req)}")
for k, v in schema.get("properties", {}).items():
problems += strict_audit(v, f"{path}.{k}")
if "default" in schema:
problems.append(f"{path}: 带 default 的字段在 strict 下会被拒")
return problems
# 运行结果(对上一节的 get_order_by_no 执行)
print(strict_audit(get_order_by_no["parameters"]))
# []体检过了再打开 strict=True,参数类型错误基本绝迹。代价是「可选参数」这个概念消失了:想要可选行为,只能用 enum 加一个 "unspecified" 成员,或者拆成两个工具。
六、三家模型的差异,落在四行上
差异不在「谁会调用」,而在边界条件。这张表是 2026 年 11 月对着各家文档核的,只写能确认的部分。
| 维度 | OpenAI | Anthropic | DeepSeek / GLM |
|---|---|---|---|
| 强制调用某个工具 | tool_choice 取 none/auto/required,或指定函数名 | tool_choice 取 auto/any/tool/none | DeepSeek 兼容 OpenAI 写法;GLM 文档写明 tool_choice 默认且仅支持 auto |
| 关闭并行 | 顶层 parallel_tool_calls=false | 放在 tool_choice 对象里的 disable_parallel_tool_use | 依各家兼容层而定,GLM 侧无法通过 tool_choice 强制 |
| 严格 schema | strict: true,全字段必填 | strict: true,限制见其 structured outputs 文档 | DeepSeek 走 /beta,schema 白名单式校验 |
| 工具名约束 | 字母数字下划线短横,最长 64 字符 | 命名较宽松,但同一请求内不能重名 | 遵循各自兼容层 |
最后一行容易翻车:工具名里带中文、带点号、超过 64 字符,OpenAI 侧直接拒绝整个请求,而不是忽略那个工具。我们有个团队用 订单.查询V2 做名字,本地 mock 全过,切到线上第一分钟就 400。
表里没有「哪个模型更聪明」这一行,是故意的。这类对比在网上每个月都有新版本,写进教材第二天就过期,而且读者拿它做决策的方式通常是错的——真正决定调用成功的往往是你那二十个工具的描述质量,不是模型的档位。如果要测,测你自己那批 query。
七、四个流传很广的错误认知
很多人以为工具越多能力越强。实际上是选择空间越大误调用越多,二十个工具的成功率通常低于八个精心命名的工具。
很多人以为 description 是给人看的注释。实际上它是模型唯一的决策依据,写「查询订单」等于什么都没写。
很多人以为并行调用一定能提速。实际上只要有依赖关系就会放大错误,而且结果拼装少一条就整轮失败。
很多人以为 strict 打开就万事大吉。实际上 strict 只管「格式对不对」,不管「该不该调这个工具」,选错工具它一样安静地返回合法 JSON。
这里给一个明确的否定判断:不建议把枚举型取值塞进工具参数去解决「模型选错分类」这类问题。我们试过一个 300 多 SKU 的目录直接做 enum,工具定义 token 涨了近四倍,模型开始稳定地选到相邻项。正确做法是让工具接收一个自由文本,返回候选列表和置信度,由代码做最后的匹配——把选择题交回给确定性逻辑,别交给解码器。
关于本文刻意不给数字这件事,要补一句解释。价格、上下文上限、基准分数这三类数字是全网转载最快的,也是最容易在转载中失真的。更麻烦的是它们会诱导错误决策:看到某模型标价便宜三成就换过去,结果发现自己那批 query 上调用成功率掉了十二个点,账反而更贵。我的做法是只在两个地方看数字——usage 里自己账户的真实消耗,和自家评估集上的通过率。这两个数字不会骗你,别人给的会。
八、工具数量的预算:二十个为什么就多了
工具定义是要进上下文的,进上下文就要付钱,而且占的是每一轮都重发的位置。按一份中等复杂度的工具定义 150–250 token 估,二十个工具就是 3000–5000 token 的固定开销,出现在每一次模型调用里。一个八轮的任务,光工具列表就重发八遍。
这件事在账单上的表现很隐蔽:单次调用看不出来,月度总和才会让你注意到。我们第一次发现它,是因为把工具数从 8 个加到 19 个之后,同样的会话量账单涨了 41%,而功能上只用到了其中 3 个新工具。
三个可行的收窄办法,按代价从低到高排:
| 办法 | 做法 | 代价 |
|---|---|---|
| 按场景切分工具集 | 每次请求只带当前意图相关的工具子集 | 需要意图分类器,分类错就调不到对的工具 |
| 合并同族工具 | 三个查询工具合成一个带 mode 参数的 | 描述变长,mode 取值错误率上升 |
| 二级路由 | 先调一个「工具目录」工具,再按返回结果调具体工具 | 多一次往返,延迟增加约一倍 |
我们最后选的是第一种,因为它对延迟友好,而且意图分类器本来就有。但要说清楚它的失效条件:用户一句话里跨两个意图时(「查订单顺便把发票寄了」),分类器只能选一个,另一个会被静默丢掉。我们在提示词里加了「如果发现跨意图,请先告知用户」,把这种兜底变成显式行为。
九、留给你自己环境的两道题
两道要动手的:把你们线上某个工具的描述改成「触发条件 + 排除项」两段式,用同一批 30 条 query 跑前后对比,看误调用率变化;给一个带三个可选参数的工具做 strict 化改造,记录你为了消掉可选性付出的接口代价。
三句话想清楚再动手:什么时候该拆工具、什么时候该加工具?并行调用的结果里有一条超时,剩下的应该怎么回填?如果模型连续两轮传错同一个参数,你的重试逻辑该怎么停?
名词对照放这里,方便回头查:
| 术语 | 英文 | 一句话解释 |
|---|---|---|
| 工具调用 | Function Calling / Tool Use | 模型输出结构化调用意图,由应用执行 |
| 参数模式 | parameters schema | 用 JSON Schema 描述参数类型与取值 |
| 严格模式 | strict mode | 解码阶段强制符合 schema,牺牲可选性换稳定 |
| 并行调用 | parallel tool calls | 一次响应返回多个互不依赖的调用 |
| 调用编号 | tool_call_id | 把工具结果与某次调用绑定的唯一键 |
| 工具描述 | description | 模型判断「何时用、何时不用」的唯一依据 |
| 协议错误 | protocol error | 工具名或参数结构不合法,可重试 |
| 执行错误 | tool execution error | 业务失败,通常不该重试 |