1. 工具调用到底在解决什么问题第一次接触“工具调用”这个概念很多人会以为它是个新框架或者新协议。其实不是。它本质上是大模型能力边界的一次外延——模型本身只会输出文本但通过工具调用它能在对话过程中主动“喊”一个外部函数把参数传出去拿到结果再继续往下推理。我最早在项目里用这个能力是因为一个很具体的痛点让模型回答“今天北京天气怎么样”它要么编一个温度要么说“我无法获取实时信息”。这两种结果对业务来说都是废的。工具调用就是把这个死结解开的钥匙——模型不再假装自己什么都知道而是学会说“我需要调用 get_weather 这个函数参数是 city北京”。从技术定义上讲工具调用Function Calling是一套约定开发者用 JSON Schema 描述一组可用的函数模型在对话中判断是否需要调用、调用哪个、参数填什么然后以结构化的 JSON 返回调用意图。注意模型本身不执行函数它只负责“决定调用什么”真正的执行发生在你的代码里。这个分工非常关键很多人一开始会误以为模型把函数也跑了结果调试半天找不到执行入口。这套机制解决的核心问题是让模型的输出从自由文本变成可编程的结构化指令。以前你要从模型回复里用正则抠参数现在直接拿到一个 JSON 对象字段名、类型、嵌套结构都是你事先定义好的。对工程来说这意味着可靠性从“祈祷模型格式别乱”变成了“schema 校验兜底”。适合谁来学如果你在做 AI 应用、智能体、自动化流程或者只是想让模型帮你查数据库、调接口、操作文件工具调用是绕不过去的一环。哪怕你只是用现成的客户端理解它的工作原理也能让你在配置出错时知道该看哪里。2. 工具调用的整体设计与核心思路拆解2.1 为什么是 JSON Schema 而不是自然语言描述工具调用最核心的设计决策是用 JSON Schema 来描述函数而不是用一段自然语言告诉模型“我有个函数能查天气”。这个选择背后有很实在的工程考量。自然语言描述的问题是歧义和不可校验。你写“这个函数接收城市名”模型可能传{city: 北京}也可能传{城市: 北京}甚至传{location: 北京}。每次格式不一样你的解析代码就得写一堆兼容分支。JSON Schema 把参数名、类型、是否必填、枚举值全部锁死模型输出的参数必须符合这个结构不符合就是模型的问题你可以直接重试或报错。我实测下来用 schema 约束后参数格式错误率能从自然语言描述时的百分之十几降到百分之一以内。这个差距在批量调用场景下是致命的——一百次调用错十几次整个流程就没法自动化。2.2 模型只做决策执行权在你手里这是新手最容易踩的认知坑。工具调用的完整链路是这样的你发消息给模型附带工具定义模型返回一个tool_calls数组里面是它想调用的函数名和参数你的代码解析这个数组真正去执行函数把执行结果作为一条tool角色的消息再发回给模型模型基于结果生成最终回复。模型在整个过程中没有执行任何东西它只是“提议”。这个设计的好处是安全——模型不能直接删你的数据库它只能提议“我想调用 delete_record”你的代码可以选择拒绝、可以加权限校验、可以要求人工确认。把执行权留在自己手里是工具调用能用在生产环境的前提。2.3 多轮工具调用的循环结构单次调用很简单但真实场景往往是多轮的。比如用户问“帮我查下订单 A123 的物流如果超过三天没更新就发个提醒”模型可能需要先调查订单拿到状态后再调查物流判断超时后再调发提醒。这是一个循环模型返回 tool_calls → 执行 → 结果回传 → 模型可能再返回新的 tool_calls → 再执行直到模型不再请求工具、直接给出文本回复为止。这个循环必须有终止条件否则模型可能陷入“调了又调”的死循环。常见的做法是设最大轮数比如 10 轮超过就强制结束。我在项目里一般设 5 到 8 轮因为超过这个数通常意味着工具定义有问题或者任务本身不适合用工具调用。2.4 工具数量与描述质量的权衡工具不是越多越好。我见过有人一口气定义三十个工具结果模型选择准确率断崖式下跌。原因是每个工具的定义都会占用上下文工具太多时模型在“选哪个”这件事上会分心而且相似功能的工具容易混淆。我的经验是单次对话暴露的工具控制在 10 个以内超过就做分组或路由——先用一个轻量模型判断该用哪组工具再只把那组工具的定义传给主模型。另外工具描述要写清楚“什么时候用”而不只是“这个函数做什么”。比如search_flights的描述里要写“当用户询问航班、机票、出行方式时使用”这样模型判断触发时机的准确率会明显提升。3. 核心细节解析与实操要点3.1 工具定义的字段结构一个标准的工具定义包含三部分类型、函数名、函数详情。函数详情里又有描述和参数 schema。参数 schema 遵循 JSON Schema 规范常用的字段有 type、properties、required、enum、description。{ type: function, function: { name: get_weather, description: 查询指定城市的当前天气当用户询问天气、气温、是否下雨时使用, parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认摄氏度 } }, required: [city] } } }这里有几个细节值得说。description要写得像给同事交代任务把触发场景写进去。required只放真正必需的参数可选参数给默认值处理。enum能极大降低模型乱填的概率凡是取值有限的参数都应该用 enum 约束。3.2 参数校验与容错处理模型再聪明也会犯错参数校验是必须的。我一般做三层校验第一层是 JSON 解析确认返回的是合法 JSON第二层是 schema 校验用 jsonschema 这类库检查字段类型和必填项第三层是业务校验比如城市名是否在支持列表里。校验失败时不要直接崩而是把错误信息作为 tool 结果回传给模型让它自己修正。比如模型传了{city: 123}你回传“参数 city 必须是字符串请重新调用”模型下一轮通常能改对。这个“错误回传自愈”的机制能显著提升鲁棒性我实测能救回八成以上的参数错误。3.3 工具结果的格式设计工具执行完返回什么直接影响模型能不能正确理解。我的原则是返回结构化数据但用自然语言包装关键信息。比如查天气返回{temp: 25, condition: 晴}但回传给模型时写成“北京当前气温 25 摄氏度天气晴”。纯 JSON 模型也能读但加一层自然语言描述后模型生成最终回复时更自然也更不容易漏掉关键字段。结果长度也要控制。如果工具返回一个几百行的列表直接塞回去会挤爆上下文。我一般做截断或摘要只回传最相关的部分并在描述里说明“共 200 条显示前 10 条”。注意工具结果里不要包含任何可能被模型误当成指令的内容。如果工具返回的是用户生成的文本要明确标注这是数据而非指令避免提示注入。3.4 并行工具调用的处理现代模型支持一次返回多个 tool_calls比如同时查天气和查航班。这时候你的代码要能并行执行这些调用再把所有结果一起回传。并行能省时间但要注意结果顺序——回传时要按 tool_call_id 对应不能乱序否则模型会把结果张冠李戴。我踩过的坑是并行调用里有一个失败了我直接把整个批次报错结果模型以为所有调用都失败了。正确做法是每个调用独立处理成功的回传结果失败的回传错误信息让模型自己决定下一步。4. 实操过程与核心环节实现4.1 从零搭建一个工具调用流程我用一个查天气加发提醒的例子把完整流程走一遍。假设你要做一个“如果明天下雨就提醒我带伞”的功能。第一步定义两个工具get_weather和send_reminder。前者接收城市和日期后者接收提醒内容。第二步构造请求。消息列表里放用户的问题tools 字段放两个工具定义tool_choice 设为 auto 让模型自己决定。messages [ {role: user, content: 帮我看看明天北京天气如果下雨提醒我带伞} ] response client.chat.completions.create( modelyour-model, messagesmessages, tools[weather_tool, reminder_tool], tool_choiceauto )第三步解析响应。如果response.choices[0].message.tool_calls不为空说明模型要调工具。遍历这个数组按函数名分发到对应的执行函数。tool_calls response.choices[0].message.tool_calls for call in tool_calls: name call.function.name args json.loads(call.function.arguments) if name get_weather: result get_weather(args[city], args[date]) elif name send_reminder: result send_reminder(args[content]) messages.append({ role: tool, tool_call_id: call.id, content: str(result) })第四步把带 tool 结果的消息列表再发给模型让它生成最终回复。如果模型又返回了 tool_calls就重复第三步直到它返回纯文本。这个循环我封装成了一个run_tool_loop函数设最大轮数 8每轮打印日志方便调试。日志里记录调用了哪个工具、参数是什么、返回什么出问题时一眼能看出是哪一环断了。4.2 参数计算与选择过程工具调用里有些参数需要计算不能全靠模型。比如日期模型对“明天”的理解可能不准我一般让模型传相对描述代码里再转成具体日期。再比如分页模型不知道每页多少条我在工具定义里写死默认值模型只传页码。还有一个容易忽略的点是超时。工具执行可能很慢比如调外部接口要几秒。我会给每个工具设超时超时就回传“调用超时请稍后重试”而不是让整个流程卡死。超时时间根据工具类型定查数据库设 2 秒调外部 API 设 5 秒发消息设 3 秒。4.3 实操现场记录与调试技巧调试工具调用最有效的方法是打印完整消息列表。每次循环前后都把 messages 打出来看模型到底收到了什么、返回了什么。我见过很多“模型不调工具”的问题最后发现是工具定义没传进去或者 tool_choice 设成了 none。另一个技巧是用一个简单的工具先跑通链路比如echo函数接收什么返回什么。链路通了再加真实工具这样能把“链路问题”和“工具问题”分开排查。我刚开始做的时候一上来就接复杂工具结果报错都不知道是模型没调还是工具执行挂了白白浪费一下午。5. 常见问题与排查技巧实录5.1 模型不调用工具怎么办这是最高频的问题。排查顺序是这样的先确认 tools 字段真的传了且格式正确再确认 tool_choice 不是 none然后看工具描述是否清晰有没有写触发场景最后看用户问题是否真的需要工具——有时候模型判断不需要调直接回答了这其实是正确行为。如果都正常还是不调可以试试在系统提示里加一句“当需要实时信息或执行操作时优先使用提供的工具”。这句话能明显提升调用意愿。我实测在描述模糊的场景下加这句话后调用率能从六成提到九成。5.2 参数格式错误的处理模型传的参数不符合 schema常见的有类型错误、缺必填项、枚举值乱填。处理方式前面提过把错误回传让它自愈。但要注意如果同一个错误连续出现三次说明工具定义有问题别再让模型重试了直接报错人工介入。我整理了一个常见错误对照表错误类型典型表现处理方式类型错误数字传成字符串回传类型要求让模型重试缺必填项没传 city回传缺失字段名让模型补枚举越界unit 传了 C回传合法取值列表JSON 解析失败arguments 不是合法 JSON回传格式要求重试一次参数幻觉传了 schema 里没有的字段忽略多余字段继续执行5.3 多轮调用陷入死循环模型反复调同一个工具或者调了 A 又调 B 又调回 A。这种情况通常是工具返回的结果没有让模型获得新信息它以为没成功就再试。解决方法是让工具结果更明确比如成功时返回“查询成功结果如下”失败时返回具体原因别返回空对象。另外设最大轮数是硬保险。我一般设 8 轮超过就中断并返回“任务过于复杂请拆分后重试”。这个提示对用户也有用让他知道不是系统坏了而是任务需要拆小。5.4 工具结果太长挤爆上下文工具返回大列表时直接塞回去会让上下文迅速膨胀后续轮次的模型表现会下降。我的做法是在工具执行层做摘要只回传前 N 条加总数。N 根据模型上下文窗口定一般 10 到 20 条。如果用户需要更多让他明确说“显示更多”再调一次带分页参数的工具。提示工具结果的 token 消耗要计入成本。一个返回 5000 token 的工具调十次就是 5 万 token成本很可观。设计工具时就要考虑返回精简。5.5 不同模型的工具调用差异不同模型对工具调用的支持程度不一样。有的模型返回的 tool_calls 结构略有差异比如参数是字符串还是对象、id 字段叫什么。做多模型适配时我一般写一层适配器把各家返回统一成内部格式上层逻辑不感知差异。还有一个差异是并行调用的支持。有的模型一次只返回一个 tool_call有的能返回多个。如果你的代码假设了并行遇到只支持串行的模型就会出问题。稳妥做法是先判断 tool_calls 长度长度为 1 就走串行逻辑大于 1 再并行。6. 工具调用在真实项目中的落地经验6.1 工具粒度的设计原则工具粒度太粗模型要填很多参数容易出错太细工具数量爆炸模型选择困难。我的原则是“一个工具做一件完整的事”。比如“查订单”是一个工具不要拆成“查订单基本信息”和“查订单物流”两个因为用户问订单时通常两个都要。但也不要做一个“查所有东西”的万能工具参数里塞个 type 字段区分那样模型很难填对。判断粒度是否合适有个简单方法看工具描述能不能用一句话说清楚“什么时候用它”。说不清楚就说明粒度有问题要么太粗要么和其他工具重叠。6.2 权限与安全边界工具调用给了模型“动手”的能力安全边界必须划清楚。我的做法是分三级只读工具查询类可以直接执行写工具创建、修改要加参数校验和频率限制危险工具删除、转账必须人工确认模型只能生成待确认的调用请求不能直接执行。另外工具执行环境要隔离。查数据库用只读账号调外部接口用受限的 key别让工具能碰到核心系统。我见过有人把生产数据库的写权限直接给了工具结果模型误调了一次批量更新教训很深刻。6.3 监控与日志工具调用上线后监控是必须的。我关注几个指标调用成功率、平均轮数、参数错误率、超时率。成功率低于九成就要查工具定义平均轮数超过 5 轮说明任务设计有问题参数错误率高说明 schema 描述不清。日志要记录完整的调用链路用户输入、每轮的工具调用和结果、最终输出。出问题时能完整回放。我一般把日志存成 JSON 行格式方便后续分析和做数据集。6.4 成本控制的实际做法工具调用会显著增加 token 消耗因为每轮都要把工具定义和之前的调用结果重新发一遍。控制成本有几个实用做法工具定义精简description 别写太长工具结果做摘要能并行就并行减少轮数简单任务用便宜模型复杂任务再上贵模型。我算过一笔账一个带 5 个工具、平均 3 轮调用的流程token 消耗是纯对话的 4 到 6 倍。所以工具调用适合用在真正需要外部能力的场景别为了用而用。7. 从工具调用到智能体的演进思路工具调用是智能体的基础能力但智能体还需要规划、记忆、反思。我实际做项目时工具调用层和智能体层是分开的工具调用负责“把一次函数调用做可靠”智能体层负责“决定调哪些工具、按什么顺序、失败了怎么办”。这个分层的好处是工具调用层可以独立测试和优化不用管上层逻辑。我一般先保证单个工具调用稳定再往上搭多步规划。很多项目失败是因为两层混在一起出了问题不知道是工具定义的问题还是规划逻辑的问题。如果你已经跑通了工具调用下一步可以试试加一个简单的规划步骤让模型先输出一个步骤列表再逐步执行。这个改动不大但能让复杂任务的成功率明显提升。我在几个项目里用这个思路把多步任务的成功率从五成提到了八成左右。最后分享一个我常用的调试技巧把工具调用的完整消息列表存下来做成一个可回放的数据集。每次改工具定义或提示词都拿这个数据集跑一遍对比成功率变化。这样优化有依据不会凭感觉改来改去。这个习惯帮我省了很多反复试错的时间。 大模型工具调用实战：从原理到智能体落地
1. 工具调用到底在解决什么问题第一次接触“工具调用”这个概念很多人会以为它是个新框架或者新协议。其实不是。它本质上是大模型能力边界的一次外延——模型本身只会输出文本但通过工具调用它能在对话过程中主动“喊”一个外部函数把参数传出去拿到结果再继续往下推理。我最早在项目里用这个能力是因为一个很具体的痛点让模型回答“今天北京天气怎么样”它要么编一个温度要么说“我无法获取实时信息”。这两种结果对业务来说都是废的。工具调用就是把这个死结解开的钥匙——模型不再假装自己什么都知道而是学会说“我需要调用 get_weather 这个函数参数是 city北京”。从技术定义上讲工具调用Function Calling是一套约定开发者用 JSON Schema 描述一组可用的函数模型在对话中判断是否需要调用、调用哪个、参数填什么然后以结构化的 JSON 返回调用意图。注意模型本身不执行函数它只负责“决定调用什么”真正的执行发生在你的代码里。这个分工非常关键很多人一开始会误以为模型把函数也跑了结果调试半天找不到执行入口。这套机制解决的核心问题是让模型的输出从自由文本变成可编程的结构化指令。以前你要从模型回复里用正则抠参数现在直接拿到一个 JSON 对象字段名、类型、嵌套结构都是你事先定义好的。对工程来说这意味着可靠性从“祈祷模型格式别乱”变成了“schema 校验兜底”。适合谁来学如果你在做 AI 应用、智能体、自动化流程或者只是想让模型帮你查数据库、调接口、操作文件工具调用是绕不过去的一环。哪怕你只是用现成的客户端理解它的工作原理也能让你在配置出错时知道该看哪里。2. 工具调用的整体设计与核心思路拆解2.1 为什么是 JSON Schema 而不是自然语言描述工具调用最核心的设计决策是用 JSON Schema 来描述函数而不是用一段自然语言告诉模型“我有个函数能查天气”。这个选择背后有很实在的工程考量。自然语言描述的问题是歧义和不可校验。你写“这个函数接收城市名”模型可能传{city: 北京}也可能传{城市: 北京}甚至传{location: 北京}。每次格式不一样你的解析代码就得写一堆兼容分支。JSON Schema 把参数名、类型、是否必填、枚举值全部锁死模型输出的参数必须符合这个结构不符合就是模型的问题你可以直接重试或报错。我实测下来用 schema 约束后参数格式错误率能从自然语言描述时的百分之十几降到百分之一以内。这个差距在批量调用场景下是致命的——一百次调用错十几次整个流程就没法自动化。2.2 模型只做决策执行权在你手里这是新手最容易踩的认知坑。工具调用的完整链路是这样的你发消息给模型附带工具定义模型返回一个tool_calls数组里面是它想调用的函数名和参数你的代码解析这个数组真正去执行函数把执行结果作为一条tool角色的消息再发回给模型模型基于结果生成最终回复。模型在整个过程中没有执行任何东西它只是“提议”。这个设计的好处是安全——模型不能直接删你的数据库它只能提议“我想调用 delete_record”你的代码可以选择拒绝、可以加权限校验、可以要求人工确认。把执行权留在自己手里是工具调用能用在生产环境的前提。2.3 多轮工具调用的循环结构单次调用很简单但真实场景往往是多轮的。比如用户问“帮我查下订单 A123 的物流如果超过三天没更新就发个提醒”模型可能需要先调查订单拿到状态后再调查物流判断超时后再调发提醒。这是一个循环模型返回 tool_calls → 执行 → 结果回传 → 模型可能再返回新的 tool_calls → 再执行直到模型不再请求工具、直接给出文本回复为止。这个循环必须有终止条件否则模型可能陷入“调了又调”的死循环。常见的做法是设最大轮数比如 10 轮超过就强制结束。我在项目里一般设 5 到 8 轮因为超过这个数通常意味着工具定义有问题或者任务本身不适合用工具调用。2.4 工具数量与描述质量的权衡工具不是越多越好。我见过有人一口气定义三十个工具结果模型选择准确率断崖式下跌。原因是每个工具的定义都会占用上下文工具太多时模型在“选哪个”这件事上会分心而且相似功能的工具容易混淆。我的经验是单次对话暴露的工具控制在 10 个以内超过就做分组或路由——先用一个轻量模型判断该用哪组工具再只把那组工具的定义传给主模型。另外工具描述要写清楚“什么时候用”而不只是“这个函数做什么”。比如search_flights的描述里要写“当用户询问航班、机票、出行方式时使用”这样模型判断触发时机的准确率会明显提升。3. 核心细节解析与实操要点3.1 工具定义的字段结构一个标准的工具定义包含三部分类型、函数名、函数详情。函数详情里又有描述和参数 schema。参数 schema 遵循 JSON Schema 规范常用的字段有 type、properties、required、enum、description。{ type: function, function: { name: get_weather, description: 查询指定城市的当前天气当用户询问天气、气温、是否下雨时使用, parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认摄氏度 } }, required: [city] } } }这里有几个细节值得说。description要写得像给同事交代任务把触发场景写进去。required只放真正必需的参数可选参数给默认值处理。enum能极大降低模型乱填的概率凡是取值有限的参数都应该用 enum 约束。3.2 参数校验与容错处理模型再聪明也会犯错参数校验是必须的。我一般做三层校验第一层是 JSON 解析确认返回的是合法 JSON第二层是 schema 校验用 jsonschema 这类库检查字段类型和必填项第三层是业务校验比如城市名是否在支持列表里。校验失败时不要直接崩而是把错误信息作为 tool 结果回传给模型让它自己修正。比如模型传了{city: 123}你回传“参数 city 必须是字符串请重新调用”模型下一轮通常能改对。这个“错误回传自愈”的机制能显著提升鲁棒性我实测能救回八成以上的参数错误。3.3 工具结果的格式设计工具执行完返回什么直接影响模型能不能正确理解。我的原则是返回结构化数据但用自然语言包装关键信息。比如查天气返回{temp: 25, condition: 晴}但回传给模型时写成“北京当前气温 25 摄氏度天气晴”。纯 JSON 模型也能读但加一层自然语言描述后模型生成最终回复时更自然也更不容易漏掉关键字段。结果长度也要控制。如果工具返回一个几百行的列表直接塞回去会挤爆上下文。我一般做截断或摘要只回传最相关的部分并在描述里说明“共 200 条显示前 10 条”。注意工具结果里不要包含任何可能被模型误当成指令的内容。如果工具返回的是用户生成的文本要明确标注这是数据而非指令避免提示注入。3.4 并行工具调用的处理现代模型支持一次返回多个 tool_calls比如同时查天气和查航班。这时候你的代码要能并行执行这些调用再把所有结果一起回传。并行能省时间但要注意结果顺序——回传时要按 tool_call_id 对应不能乱序否则模型会把结果张冠李戴。我踩过的坑是并行调用里有一个失败了我直接把整个批次报错结果模型以为所有调用都失败了。正确做法是每个调用独立处理成功的回传结果失败的回传错误信息让模型自己决定下一步。4. 实操过程与核心环节实现4.1 从零搭建一个工具调用流程我用一个查天气加发提醒的例子把完整流程走一遍。假设你要做一个“如果明天下雨就提醒我带伞”的功能。第一步定义两个工具get_weather和send_reminder。前者接收城市和日期后者接收提醒内容。第二步构造请求。消息列表里放用户的问题tools 字段放两个工具定义tool_choice 设为 auto 让模型自己决定。messages [ {role: user, content: 帮我看看明天北京天气如果下雨提醒我带伞} ] response client.chat.completions.create( modelyour-model, messagesmessages, tools[weather_tool, reminder_tool], tool_choiceauto )第三步解析响应。如果response.choices[0].message.tool_calls不为空说明模型要调工具。遍历这个数组按函数名分发到对应的执行函数。tool_calls response.choices[0].message.tool_calls for call in tool_calls: name call.function.name args json.loads(call.function.arguments) if name get_weather: result get_weather(args[city], args[date]) elif name send_reminder: result send_reminder(args[content]) messages.append({ role: tool, tool_call_id: call.id, content: str(result) })第四步把带 tool 结果的消息列表再发给模型让它生成最终回复。如果模型又返回了 tool_calls就重复第三步直到它返回纯文本。这个循环我封装成了一个run_tool_loop函数设最大轮数 8每轮打印日志方便调试。日志里记录调用了哪个工具、参数是什么、返回什么出问题时一眼能看出是哪一环断了。4.2 参数计算与选择过程工具调用里有些参数需要计算不能全靠模型。比如日期模型对“明天”的理解可能不准我一般让模型传相对描述代码里再转成具体日期。再比如分页模型不知道每页多少条我在工具定义里写死默认值模型只传页码。还有一个容易忽略的点是超时。工具执行可能很慢比如调外部接口要几秒。我会给每个工具设超时超时就回传“调用超时请稍后重试”而不是让整个流程卡死。超时时间根据工具类型定查数据库设 2 秒调外部 API 设 5 秒发消息设 3 秒。4.3 实操现场记录与调试技巧调试工具调用最有效的方法是打印完整消息列表。每次循环前后都把 messages 打出来看模型到底收到了什么、返回了什么。我见过很多“模型不调工具”的问题最后发现是工具定义没传进去或者 tool_choice 设成了 none。另一个技巧是用一个简单的工具先跑通链路比如echo函数接收什么返回什么。链路通了再加真实工具这样能把“链路问题”和“工具问题”分开排查。我刚开始做的时候一上来就接复杂工具结果报错都不知道是模型没调还是工具执行挂了白白浪费一下午。5. 常见问题与排查技巧实录5.1 模型不调用工具怎么办这是最高频的问题。排查顺序是这样的先确认 tools 字段真的传了且格式正确再确认 tool_choice 不是 none然后看工具描述是否清晰有没有写触发场景最后看用户问题是否真的需要工具——有时候模型判断不需要调直接回答了这其实是正确行为。如果都正常还是不调可以试试在系统提示里加一句“当需要实时信息或执行操作时优先使用提供的工具”。这句话能明显提升调用意愿。我实测在描述模糊的场景下加这句话后调用率能从六成提到九成。5.2 参数格式错误的处理模型传的参数不符合 schema常见的有类型错误、缺必填项、枚举值乱填。处理方式前面提过把错误回传让它自愈。但要注意如果同一个错误连续出现三次说明工具定义有问题别再让模型重试了直接报错人工介入。我整理了一个常见错误对照表错误类型典型表现处理方式类型错误数字传成字符串回传类型要求让模型重试缺必填项没传 city回传缺失字段名让模型补枚举越界unit 传了 C回传合法取值列表JSON 解析失败arguments 不是合法 JSON回传格式要求重试一次参数幻觉传了 schema 里没有的字段忽略多余字段继续执行5.3 多轮调用陷入死循环模型反复调同一个工具或者调了 A 又调 B 又调回 A。这种情况通常是工具返回的结果没有让模型获得新信息它以为没成功就再试。解决方法是让工具结果更明确比如成功时返回“查询成功结果如下”失败时返回具体原因别返回空对象。另外设最大轮数是硬保险。我一般设 8 轮超过就中断并返回“任务过于复杂请拆分后重试”。这个提示对用户也有用让他知道不是系统坏了而是任务需要拆小。5.4 工具结果太长挤爆上下文工具返回大列表时直接塞回去会让上下文迅速膨胀后续轮次的模型表现会下降。我的做法是在工具执行层做摘要只回传前 N 条加总数。N 根据模型上下文窗口定一般 10 到 20 条。如果用户需要更多让他明确说“显示更多”再调一次带分页参数的工具。提示工具结果的 token 消耗要计入成本。一个返回 5000 token 的工具调十次就是 5 万 token成本很可观。设计工具时就要考虑返回精简。5.5 不同模型的工具调用差异不同模型对工具调用的支持程度不一样。有的模型返回的 tool_calls 结构略有差异比如参数是字符串还是对象、id 字段叫什么。做多模型适配时我一般写一层适配器把各家返回统一成内部格式上层逻辑不感知差异。还有一个差异是并行调用的支持。有的模型一次只返回一个 tool_call有的能返回多个。如果你的代码假设了并行遇到只支持串行的模型就会出问题。稳妥做法是先判断 tool_calls 长度长度为 1 就走串行逻辑大于 1 再并行。6. 工具调用在真实项目中的落地经验6.1 工具粒度的设计原则工具粒度太粗模型要填很多参数容易出错太细工具数量爆炸模型选择困难。我的原则是“一个工具做一件完整的事”。比如“查订单”是一个工具不要拆成“查订单基本信息”和“查订单物流”两个因为用户问订单时通常两个都要。但也不要做一个“查所有东西”的万能工具参数里塞个 type 字段区分那样模型很难填对。判断粒度是否合适有个简单方法看工具描述能不能用一句话说清楚“什么时候用它”。说不清楚就说明粒度有问题要么太粗要么和其他工具重叠。6.2 权限与安全边界工具调用给了模型“动手”的能力安全边界必须划清楚。我的做法是分三级只读工具查询类可以直接执行写工具创建、修改要加参数校验和频率限制危险工具删除、转账必须人工确认模型只能生成待确认的调用请求不能直接执行。另外工具执行环境要隔离。查数据库用只读账号调外部接口用受限的 key别让工具能碰到核心系统。我见过有人把生产数据库的写权限直接给了工具结果模型误调了一次批量更新教训很深刻。6.3 监控与日志工具调用上线后监控是必须的。我关注几个指标调用成功率、平均轮数、参数错误率、超时率。成功率低于九成就要查工具定义平均轮数超过 5 轮说明任务设计有问题参数错误率高说明 schema 描述不清。日志要记录完整的调用链路用户输入、每轮的工具调用和结果、最终输出。出问题时能完整回放。我一般把日志存成 JSON 行格式方便后续分析和做数据集。6.4 成本控制的实际做法工具调用会显著增加 token 消耗因为每轮都要把工具定义和之前的调用结果重新发一遍。控制成本有几个实用做法工具定义精简description 别写太长工具结果做摘要能并行就并行减少轮数简单任务用便宜模型复杂任务再上贵模型。我算过一笔账一个带 5 个工具、平均 3 轮调用的流程token 消耗是纯对话的 4 到 6 倍。所以工具调用适合用在真正需要外部能力的场景别为了用而用。7. 从工具调用到智能体的演进思路工具调用是智能体的基础能力但智能体还需要规划、记忆、反思。我实际做项目时工具调用层和智能体层是分开的工具调用负责“把一次函数调用做可靠”智能体层负责“决定调哪些工具、按什么顺序、失败了怎么办”。这个分层的好处是工具调用层可以独立测试和优化不用管上层逻辑。我一般先保证单个工具调用稳定再往上搭多步规划。很多项目失败是因为两层混在一起出了问题不知道是工具定义的问题还是规划逻辑的问题。如果你已经跑通了工具调用下一步可以试试加一个简单的规划步骤让模型先输出一个步骤列表再逐步执行。这个改动不大但能让复杂任务的成功率明显提升。我在几个项目里用这个思路把多步任务的成功率从五成提到了八成左右。最后分享一个我常用的调试技巧把工具调用的完整消息列表存下来做成一个可回放的数据集。每次改工具定义或提示词都拿这个数据集跑一遍对比成功率变化。这样优化有依据不会凭感觉改来改去。这个习惯帮我省了很多反复试错的时间。