Skip to content

工具调用设计:让模型一次就选对函数 ​

一、学完这一节能交出的四样东西 ​

先看一个数字: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,而且选择难度随数量上升。

三、导入案例:一个查订单工具的三次改版 ​

去年秋天我们做一个客服侧的助手,第一个工具长这样:

python
{
    "type": "function",
    "function": {
        "name": "get_order",
        "description": "查询订单",
        "parameters": {
            "type": "object",
            "properties": {"id": {"type": "string"}},
            "required": ["id"],
        },
    },
}

上线第一周,get_order 的调用成功率大概六成。失败分三类:模型把「我上个月买的那双鞋」整个塞进 id;模型传 "订单号:DD20261015001",前缀是它自己加的;还有一类是用户问退款,模型硬调 get_order 去猜。

第二版我们只改描述,不动代码:

python
{
    "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 不合法,合法值是什么」。业务级失败(订单不存在、余额不足)不该重试,直接把事实写回给模型,让它换路径或告诉用户。

python
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 这几个不支持。这三家的共同点是「宁可拒绝你的请求,也不在你不知情时放松校验」,所以体检脚本的价值在于把报错提前到本地。

写个小脚本先自检,比等线上报错便宜:

python
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 月对着各家文档核的,只写能确认的部分。

维度OpenAIAnthropicDeepSeek / GLM
强制调用某个工具tool_choice 取 none/auto/required,或指定函数名tool_choice 取 auto/any/tool/noneDeepSeek 兼容 OpenAI 写法;GLM 文档写明 tool_choice 默认且仅支持 auto
关闭并行顶层 parallel_tool_calls=false放在 tool_choice 对象里的 disable_parallel_tool_use依各家兼容层而定,GLM 侧无法通过 tool_choice 强制
严格 schemastrict: 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业务失败,通常不该重试