从只会聊天到真的办事我把大模型接进工单系统后才搞懂Function Calling的实战价值做过大模型应用的同学应该都有同感模型再能说会道不接上业务系统本质上就是个高级聊天框。我接手过一个内部工单系统的智能化改造最初的目标很简单——让用户用自然语言查工单、查物流、提退单。最开始我用纯Prompt让模型输出JSON再解析结果字段格式飘忽不定稍微复杂的请求就崩。后来切换到面向目标架构的Function Calling方案整套流程才真正稳定下来。Function Calling说人话就是让大模型在对话里决定调用哪个工具、传什么参数然后由你的代码去真正执行这个函数再把结果交还给模型生成最终回复。这套机制特别适合做工具调用型Agent、业务助手、数据查询类应用比如我做的客服工单系统、智能助手、报表问答等等。这篇文章就把我在实际项目里踩过的坑、总结出来的调试套路以及一份可以直接抄作业的完整实现一次性讲清楚。1. 为什么要用Function Calling——目标架构的起点1.1 从对话式Hack到目标式执行传统的做法是把动作都塞给Prompt你在系统提示词里写当用户要求查询工单时请输出{action: query_order, order_id: xxx}然后程序去解析这个JSON。这套思路在Demo阶段完全能跑但一旦业务变复杂问题就来了。模型会偶尔在JSON里加注释、换行错位、字段名漂移甚至把布尔值输出成字符串。更麻烦的是你无法让模型严格区分它自己编的答案和系统返回的数据。Function Calling的思路完全不同。它相当于给模型发了一张工具栏清单每项工具都写清了名称、用途、参数格式。模型不再自己生成JSON结构而是从你给定的工具列表里选一个把参数填好返回给你。你的代码拿到这个结构化的调用请求去执行真实函数再回传结果。模型的角色从编造者变成了调度者可控性一下就上来了。我在工单项目里的体会是Function Calling不是技术选型层面的小技巧而是整个目标架构的关键支柱。所谓面向目标架构就是让每个用户请求最终落到一个明确的业务目标上——查数据、改状态、发起流程。模型负责理解意图、抽取参数、决定调用哪个工具而真正的数据操作和状态变更都掌握在你的业务代码手里。1.2 哪些场景值得上Function Calling不是所有项目都需要这套机制。判断标准很简单你的应用是否存在要动数据、要查系统、要触发动作的需求。纯闲聊、纯文本润色、纯内容生成用不着。但我实际接触的多数业务场景都很适合数据查询类查订单、查库存、查工单状态、查报表。这类任务参数定义清晰返回结果结构化Function Calling几乎是标准答案。业务操作类创建工单、提交审批、发起退款、修改配置。这类任务要严格控制参数和权限Function Calling把参数抽取交给模型、把执行控制权留给你安全边界非常清晰。混合任务类比如帮我查一下上个月的销售额顺便对比一下这个月。模型需要决定调用一次还是多次工具再把多次结果组织成最终答案。我当时选的第一个POC案例就是工单状态查询。原因是参数少、逻辑直、结果好验证适合把整套链路跑通之后再横向扩展其他函数。1.3 为什么不直接微调模型这里有个常见的误解很多人觉得让模型学会调用函数是不是得微调一个专用模型。实际完全不需要。当前主流的大模型在预训练和指令微调阶段已经见过大量工具调用数据你只需要把工具定义写清楚、格式写规范模型就能在推理时自己学会用工具。微调一个模型成本高、迭代慢而且每次函数变更都要重新训练非常不划算。我做过一个对比同一套工具定义分别用纯Prompt正则解析和Function Calling跑同样的20条测试请求。前者有7条输出格式不规范需要额外写容错逻辑后者只出现1次参数抽取偏差后面讲怎么排查整体稳定度高了不止一个量级。更重要的是加了新函数之后Function Calling方案只需要在工具列表里多注册一项而Prompt方案则要重新设计提示词格式、调整解析逻辑维护成本完全不同。2. 核心细节解析函数定义是写作题不是编程题2.1 一个完整的函数Schema长什么样Function Calling里最关键的不是代码而是你提交给模型的函数说明书。绝大多数SDK无论是官方还是兼容接口支持的格式都是JSON Schema风格。我以一个最常用的查询工单状态函数为例{ type: function, function: { name: query_work_order_status, description: 查询工单当前的处理状态包括待处理、处理中、已完成、已关闭。当用户询问工单进度、处理结果或状态时使用。, parameters: { type: object, properties: { work_order_id: { type: string, description: 用户的工单编号格式为WO后跟8位数字例如WO20240001 } }, required: [work_order_id] } } }这里面最容易被忽略的是顶层那个type: function。不同云厂商的接口在这个字段上略有差异有的SDK会自动帮你在函数定义里补上这一层有的则要求你在tools数组里手动包一次。我的建议是写代码前先打印一次最终提交给接口的payload确认结构长什么样否则很容易在本地看着对、线上疯狂报错里浪费时间。2.2 description才是决定成败的隐藏引擎我重点想说description。很多人把description当成给人类看的注释随手写一句查询工单状态就完事这是最大的误解。模型在决定要不要调用某个函数时主要依据就是description的语义匹配度。描述写得越具体模型就越能判断当前这句话该不该用这个工具。举个实际例子。我的工具列表里同时存在query_work_order_status查状态和query_work_order_log查流转记录两个函数。最开始我写的描述分别是查询工单状态和查询工单日志结果用户说帮我看看这个工单怎么回事模型经常调用错。后来我把描述改成状态查询查询工单当前的处理状态包括待处理、处理中、已完成、已关闭。适用于用户询问进展如何处理到哪一步完成没有等情况。日志查询查询工单的历史操作记录包括每次流转、操作人、操作时间、备注内容。适用于用户询问发生了什么为什么状态变了谁改过这个工单等情况。改完之后同样的测试集准确率提升非常明显。描述里的触发场景举例特别重要模型对自然语言场景的理解远比对功能名字段名的理解更准确。你可以把description想象成给一个没见过你系统的新同事写工作手册——写清楚什么时候该用这个工具、这个工具能查到什么远比只写一句查工单有用得多。2.3 参数设计枚举、格式与必填项的坑参数设计里我总结出几条硬经验参数类型不要用宽松类型。比如工单编号有的人喜欢定义成integer但工单编号往往以0开头用integer会丢前导零正确姿势是string并在description里注明格式。库存数量这类确实只有整数的字段再用integer。宽松类型容易让模型在抽取参数时产生幻觉例子里你定义了string模型可能把数字格式也传进去所以要在description里写格式为字符串形式的数字。能用枚举约束就用枚举约束。比如我有个函数要指定操作类型只有create、update、close三个值。在enum里写死之后模型基本不会输出这四个之外的脏值。required字段要克制。只把缺了就无法执行的字段放进required。其他可选项放required里会导致模型在用户没提相关信息时自行猜测填充。比如查工单时用户只给了工单号你却在required里放了用户的姓名模型就会编一个姓名出来严重了还会导致查询结果张冠李戴。真实做法是非必需参数设为可选代码里做默认值处理。2.4 函数多了怎么整理命名前缀与描述收敛当工具数量超过8~10个时会出现一个新的挑战模型开始搞混相近函数。我自己的经验是函数命名用动词业务对象的格式比如query_work_order_statusquery_work_order_logcreate_work_order_feedbackupdate_work_order_priority这样命名不仅清晰还能变相提升模型的语义匹配准确率。另一个技巧是控制描述的口径层级——查询类的描述重点写返回什么信息操作类的描述重点写什么时候触发、有什么影响。两条线不要混在一起模型内部对查和做的区分会变得更稳定。另外一个细节工具列表越长每次请求的token消耗也越高。我在40多个函数时测过一次光tools定义就占掉了约1500个token。如果对话轮次多成本会线性上升。建议把不常用的函数拆到不同的工具分桶里按场景动态组装比如订单域、售后域分开加载。3. 实操过程从零做一个工单查询助手3.1 环境准备与模型选型我用的方案是基于某主流云厂商的大模型API服务SDK本身提供chat.completions接口和tools参数。你要先确认三件事你的账号已开通模型服务且有可用的API Key。所选模型版本支持Function Calling。当前主流的商用和开源模型基本都支持但不排除个别早期版本不支持建议先从官方文档确认。SDK版本不要太旧。tools参数是后加的老版本可能没有对应字段直接升级到当前稳定版就行。我的本地环境是Python 3.10 官方SDK代码全部跑在内部测试服务器上。连接时设了个基础超时避免网络抖动导致整次请求卡死。3.2 业务函数定义查询工单、查物流、提交退单我在POC阶段定义了三个函数。第一个是查询工单状态。第二个是查询物流轨迹。第三个是提交退单申请。物流轨迹函数的设计里有一个值得借鉴的点物流单号和工单编号是两个不同的体系用户在问物流时往往只给订单号。我没法保证用户给的那个号一定是物流单号所以函数里同时接收两个可选参数一个tracking_no、一个order_no在代码内部做兼容优先按tracking_no查查不到再按order_no关联查询。模型在description的引导下能根据用户给的原始信息自动选择填哪个参数。第三个提交退单申请是典型的操作型函数。我特意加了reason必填参数并且使用enum约束退单类型。执行前我会让代码二次确认避免模型自作主张输出一个不存在的类型。def submit_refund_request( work_order_id: str, refund_type: str, reason: str ): 真实业务代码校验工单状态、写入退单申请记录、通知售后人员 # 这里只做演示真实项目需要接入数据库操作 return { success: True, refund_no: RF work_order_id, message: 退单申请已受理预计1个工作日内审核 }所有函数实现都保持一个约定返回给模型的都是纯Python结构dict/list不打印日志、不做多余格式包装。这样后续拼接上下文时最省事。3.3 完整请求链路从工具注册到结果回传Function Calling的请求流程有很多版本但核心链路是固定的第一次调用让模型决定该不该调工具、调哪个、传什么参数如果模型返回了tool_calls代码去执行函数然后把函数结果以tool消息追加进对话再进行第二次调用让模型基于真实结果组织最终回复。我在代码里封装了一个核心循环def run_conversation(messages, tools, max_rounds3): client get_client() for _ in range(max_rounds): resp client.chat.completions.create( modelMODEL_NAME, messagesmessages, toolstools, tool_choiceauto ) msg resp.choices[0].message # 模型决定调用工具 if getattr(msg, tool_calls, None): messages.append(msg) # 把带有tool_calls的消息放进历史 for tc in msg.tool_calls: # 这里把函数结果以tool角色追加回去 result dispatch_tool(tc.function.name, tc.function.arguments) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) continue # 继续调用模型生成最终回答 # 没有工具调用说明模型给出了答复 return msg.content return 处理轮数超过上限请稍后再试这段代码有好几个关键点。第一tool_calls里的arguments是个字符串不是对象。我在dispatch_tool里用json.loads解析解析失败就用{}兜底让函数的默认参数逻辑去处理。第二tool_call_id一定要原样保存在追加的tool消息里这个ID把函数的返回结果和某一次工具调用关联起来丢了会直接报错。第三continue这个逻辑很关键因为一次回复里可能有多个工具调用请求必须让模型在拿到所有执行结果之后再做最终汇总。3.4 多轮对话状态别把历史消息弄丢单轮调用很简单但真实用户不会只问一次。用户第一句帮我查一下WO20240001的工单状态第二句物流到哪了第三句帮我提交退单。这三句之间是有上下文的。我的做法是把所有消息包括系统提示词、用户消息、带tool_calls的助手消息、tool结果消息统一维护在一个list里每次新请求时追加用户新输入再全量发给模型。关键坑点有两个tool结果消息一定要放在对应助手消息之后。顺序乱了模型就看不到是什么请求得到的这个结果容易答非所问。不要把函数执行的敏感字段放进messages。比如退单申请里包含用户手机号如果直接以原样丢回给模型那么后续模型在总结时可能会复述这些隐私信息甚至有泄漏风险。稳妥做法是只把必要字段、脱敏后的字段返给模型。我还处理过一个细节当某轮函数执行失败时不要把异常堆栈直接拼回给模型。模型看不懂Python traceback反而会编段安慰话。正确的姿势是返回一个标准错误结构{success: false, error: 工单不存在请检查编号是否正确}并配合description里的语气要求让模型用自然语言向用户解释错误。3.5 参数抽取模型填错参数怎么办参数错误是Function Calling里最高发的问题我实测中大概有5%~10%的请求参数会有小问题。分为三种第一种是用户没提某个必填参数但函数定义里写了required。模型在极端情况下会强行编一个值。应对办法除了required字段克制外还可以在description里写明如果用户没有提供工单编号请明确询问用户不要猜测。我在query_work_order_status的description末尾加了一句若工单编号缺失或不确定请先向用户索要之后参数幻觉明显减少。第二种是用户给的参数是自然语言与函数定义里的枚举值对不上。比如用户说我要紧急处理一下但我定义的priority只有high和normal。这时模型可能输出紧急。解决思路是不要指望模型翻译业务词而是调整descriptionpriority字段只接受high或normal若用户表达为紧急加急等请转换为high。我实测这种显式映射比让模型自由发挥要稳得多。第三种是参数根本不是这个函数该接收的。比如用户问物流模型却调了查工单函数。这种情况往往是description之间区分度不够或者命名前缀不清晰。排查思路是先看模型调用链路的日志检查工具列表里相近函数的description调整触发场景举例。4. 常见问题与排查技巧实录4.1 模型死活不调用函数只会用对话回答这个问题的高发期在刚接入Function Calling时。排查思路按顺序走先确认模型版本是否支持tools参数。有的旧版模型在接口层面忽略了tools字段模型根本看不到工具。再看tools数组是否真的传进去了。在代码里打印payload[tools]确认数组不为空、JSON序列化正常。我曾经因为字典键名大小写写错SDK没报错但模型没收到工具。最后看用户输入是否很像需要查数据的表述。如果用户说你好模型当然不会调函数。但我遇到过用户说工单号是WO0001你能帮我查一下吗模型却回答了好的我帮你查的假动作。这种时候十有八九是description里缺少触发场景示例模型不知道这个工具能用来干嘛。还有一个trick排查阶段临时把tool_choice设为required或{type: function, function: {name: query_work_order_status}}强制模型必须调用指定函数。如果强制调用成功说明工具链路没问题问题出在模型的自主判断上如果强制也失败问题多半在函数定义格式上。4.2 参数里多出来一个奇怪字段有段时间模型对同一个查询工单状态函数偶尔会在返回的arguments里多塞一个order_no字段但我定义里根本没这个参数。排查后发现description里我写了一句也可根据订单号查询模型在理解上把这句当成了允许传order_no。函数定义里没定义这个字段但模型的工具调用输出并不严格受JSON Schema约束它有时会自由发挥。我当时的解决方式是一是把description里的可用订单号关联查询这种功能描述删除或改写二是代码在解析时增加一层字段白名单过滤。到现在我所有工具的dispatch逻辑里都有这一步allowed_keys {work_order_id, tracking_no, order_no} args {k: v for k, v in raw_args.items() if k in allowed_keys}看着简单但能挡住一大批模型善意越权。4.3 模型返回结果后二次回答开始胡说八道当我把函数执行结果拼回messages后模型在第二轮的总结回复中有时会把函数返回的数据原文复述得乱七八糟甚至自己推测用户的女朋友也下了单。我复盘后的结论是system prompt里的语气约束不够明确。我在system prompt里加了一段固定要求当函数调用返回结果后直接依据结果中的事实回答用户。不要推测不存在的信息不要虚构任何数字或状态。如果结果中包含缺失字段如实说明该字段未记录。另外有一个小技巧函数返回给模型时嵌套数据结构别太深。模型对嵌套list dict的临场理解没有人类那么强很多胡编乱造恰恰发生在总结深层嵌套数据的时候。我做一个平整化处理把关键字段以key: value的形式平铺在返回文本中。实测下来二次回答的准确率提升了一个台阶。4.4 多轮对话里工具调用的上下文物件错位这个坑我一开始没意识到。我用简化版维护历史消息时发现第三轮对话时模型报错tool_call_id不存在或者收到的tool消息没有对应的函数调用。排查后确认某次请求返回了两个tool_calls我循环里用了同一个消息对象追加两次Python的对象引用导致第二条tool消息的tool_call_id被覆盖。所以上面那段代码里我特意在循环内用原始msg对象追加并逐条配置tc.id。强烈建议在封装API时对messages做一次深度拷贝避免对象引用被后续循环修改。这个bug排查得非常费劲最终是在日志里打印了完整messages结构才找到的。4.5 同一批请求里多个函数调用执行顺序与依赖模型在一次回复里有时会同时要求两个函数比如查工单状态和查物流信息。这两个函数相互独立可以并行执行。我在代码里实现了简单的并发from concurrent.futures import ThreadPoolExecutor with ThreadPoolExecutor(max_workers3) as pool: futures [ pool.submit(dispatch_tool, tc.function.name, tc.function.arguments) for tc in msg.tool_calls ] results [f.result() for f in futures]但有个业务陷阱如果两个函数有依赖关系比如先查订单号、再根据订单号查物流模型虽然会在一次回复里连续发起两轮调用但代码里单纯并发是不行的必须先执行第一个拿结果、回传后再让模型决定第二次调用。我的建议是依赖型调用不要并发独立型调用可以并发并且每次运行都要设置轮数上限防止模型连环调工具死循环。4.6 实测下来最好用的调试方法Function Calling是一个黑盒调试难度在于看不到模型内部决策过程。我分享一个自己用得很顺的调试方法论给所有工具调用链路加上结构化日志。每一次请求记录下用户原始输入模型返回的工具调用function name和arguments原文函数执行的真实结果模型最终回复然后把这四段拼成一个文本逐条对照。绝大多数问题都能在这个过程中发现因为你会发现模型其实调对了函数但函数本身的返回结构不好、模型参数抽对了但你的业务代码把结果过滤错了等等。业务代码的错误和模型调用的错误排查方向完全不同不分开记录非常容易互相干扰。顺便说一句我在测试环境里手动模拟参数时特别喜欢用极端输入来测空字符串、超长文本、中文数字混排、表情符号。模型对这些边缘输入的参数抽取能力波动很大提前测一遍能避免不少线上事故。最后的实操心得做完这个工单系统再往后走我最大的感受是Function Calling的重点根本不在调用而在定义。谁把函数描述写得好、参数边界设计得干净、返回数据组织得扁平谁就能在前端少写一堆容错逻辑。踩过几次坑之后我现在的习惯是先写函数定义文档再写代码先在小范围POC上验证工具召回率再接入完整业务。后续要扩展的话可以往工具函数自动编排方向走比如让模型先把任务拆解成DAG再逐步执行那就是另一层复杂度了。建议你先从一个函数、一条链路开始把日志打全、把范式跑稳再慢慢加工具这条路是最稳妥的。
从只会聊天到真的办事我把大模型接进工单系统后才搞懂Function Calling的实战价值做过大模型应用的同学应该都有同感模型再能说会道不接上业务系统本质上就是个高级聊天框。我接手过一个内部工单系统的智能化改造最初的目标很简单——让用户用自然语言查工单、查物流、提退单。最开始我用纯Prompt让模型输出JSON再解析结果字段格式飘忽不定稍微复杂的请求就崩。后来切换到面向目标架构的Function Calling方案整套流程才真正稳定下来。Function Calling说人话就是让大模型在对话里决定调用哪个工具、传什么参数然后由你的代码去真正执行这个函数再把结果交还给模型生成最终回复。这套机制特别适合做工具调用型Agent、业务助手、数据查询类应用比如我做的客服工单系统、智能助手、报表问答等等。这篇文章就把我在实际项目里踩过的坑、总结出来的调试套路以及一份可以直接抄作业的完整实现一次性讲清楚。1. 为什么要用Function Calling——目标架构的起点1.1 从对话式Hack到目标式执行传统的做法是把动作都塞给Prompt你在系统提示词里写当用户要求查询工单时请输出{action: query_order, order_id: xxx}然后程序去解析这个JSON。这套思路在Demo阶段完全能跑但一旦业务变复杂问题就来了。模型会偶尔在JSON里加注释、换行错位、字段名漂移甚至把布尔值输出成字符串。更麻烦的是你无法让模型严格区分它自己编的答案和系统返回的数据。Function Calling的思路完全不同。它相当于给模型发了一张工具栏清单每项工具都写清了名称、用途、参数格式。模型不再自己生成JSON结构而是从你给定的工具列表里选一个把参数填好返回给你。你的代码拿到这个结构化的调用请求去执行真实函数再回传结果。模型的角色从编造者变成了调度者可控性一下就上来了。我在工单项目里的体会是Function Calling不是技术选型层面的小技巧而是整个目标架构的关键支柱。所谓面向目标架构就是让每个用户请求最终落到一个明确的业务目标上——查数据、改状态、发起流程。模型负责理解意图、抽取参数、决定调用哪个工具而真正的数据操作和状态变更都掌握在你的业务代码手里。1.2 哪些场景值得上Function Calling不是所有项目都需要这套机制。判断标准很简单你的应用是否存在要动数据、要查系统、要触发动作的需求。纯闲聊、纯文本润色、纯内容生成用不着。但我实际接触的多数业务场景都很适合数据查询类查订单、查库存、查工单状态、查报表。这类任务参数定义清晰返回结果结构化Function Calling几乎是标准答案。业务操作类创建工单、提交审批、发起退款、修改配置。这类任务要严格控制参数和权限Function Calling把参数抽取交给模型、把执行控制权留给你安全边界非常清晰。混合任务类比如帮我查一下上个月的销售额顺便对比一下这个月。模型需要决定调用一次还是多次工具再把多次结果组织成最终答案。我当时选的第一个POC案例就是工单状态查询。原因是参数少、逻辑直、结果好验证适合把整套链路跑通之后再横向扩展其他函数。1.3 为什么不直接微调模型这里有个常见的误解很多人觉得让模型学会调用函数是不是得微调一个专用模型。实际完全不需要。当前主流的大模型在预训练和指令微调阶段已经见过大量工具调用数据你只需要把工具定义写清楚、格式写规范模型就能在推理时自己学会用工具。微调一个模型成本高、迭代慢而且每次函数变更都要重新训练非常不划算。我做过一个对比同一套工具定义分别用纯Prompt正则解析和Function Calling跑同样的20条测试请求。前者有7条输出格式不规范需要额外写容错逻辑后者只出现1次参数抽取偏差后面讲怎么排查整体稳定度高了不止一个量级。更重要的是加了新函数之后Function Calling方案只需要在工具列表里多注册一项而Prompt方案则要重新设计提示词格式、调整解析逻辑维护成本完全不同。2. 核心细节解析函数定义是写作题不是编程题2.1 一个完整的函数Schema长什么样Function Calling里最关键的不是代码而是你提交给模型的函数说明书。绝大多数SDK无论是官方还是兼容接口支持的格式都是JSON Schema风格。我以一个最常用的查询工单状态函数为例{ type: function, function: { name: query_work_order_status, description: 查询工单当前的处理状态包括待处理、处理中、已完成、已关闭。当用户询问工单进度、处理结果或状态时使用。, parameters: { type: object, properties: { work_order_id: { type: string, description: 用户的工单编号格式为WO后跟8位数字例如WO20240001 } }, required: [work_order_id] } } }这里面最容易被忽略的是顶层那个type: function。不同云厂商的接口在这个字段上略有差异有的SDK会自动帮你在函数定义里补上这一层有的则要求你在tools数组里手动包一次。我的建议是写代码前先打印一次最终提交给接口的payload确认结构长什么样否则很容易在本地看着对、线上疯狂报错里浪费时间。2.2 description才是决定成败的隐藏引擎我重点想说description。很多人把description当成给人类看的注释随手写一句查询工单状态就完事这是最大的误解。模型在决定要不要调用某个函数时主要依据就是description的语义匹配度。描述写得越具体模型就越能判断当前这句话该不该用这个工具。举个实际例子。我的工具列表里同时存在query_work_order_status查状态和query_work_order_log查流转记录两个函数。最开始我写的描述分别是查询工单状态和查询工单日志结果用户说帮我看看这个工单怎么回事模型经常调用错。后来我把描述改成状态查询查询工单当前的处理状态包括待处理、处理中、已完成、已关闭。适用于用户询问进展如何处理到哪一步完成没有等情况。日志查询查询工单的历史操作记录包括每次流转、操作人、操作时间、备注内容。适用于用户询问发生了什么为什么状态变了谁改过这个工单等情况。改完之后同样的测试集准确率提升非常明显。描述里的触发场景举例特别重要模型对自然语言场景的理解远比对功能名字段名的理解更准确。你可以把description想象成给一个没见过你系统的新同事写工作手册——写清楚什么时候该用这个工具、这个工具能查到什么远比只写一句查工单有用得多。2.3 参数设计枚举、格式与必填项的坑参数设计里我总结出几条硬经验参数类型不要用宽松类型。比如工单编号有的人喜欢定义成integer但工单编号往往以0开头用integer会丢前导零正确姿势是string并在description里注明格式。库存数量这类确实只有整数的字段再用integer。宽松类型容易让模型在抽取参数时产生幻觉例子里你定义了string模型可能把数字格式也传进去所以要在description里写格式为字符串形式的数字。能用枚举约束就用枚举约束。比如我有个函数要指定操作类型只有create、update、close三个值。在enum里写死之后模型基本不会输出这四个之外的脏值。required字段要克制。只把缺了就无法执行的字段放进required。其他可选项放required里会导致模型在用户没提相关信息时自行猜测填充。比如查工单时用户只给了工单号你却在required里放了用户的姓名模型就会编一个姓名出来严重了还会导致查询结果张冠李戴。真实做法是非必需参数设为可选代码里做默认值处理。2.4 函数多了怎么整理命名前缀与描述收敛当工具数量超过8~10个时会出现一个新的挑战模型开始搞混相近函数。我自己的经验是函数命名用动词业务对象的格式比如query_work_order_statusquery_work_order_logcreate_work_order_feedbackupdate_work_order_priority这样命名不仅清晰还能变相提升模型的语义匹配准确率。另一个技巧是控制描述的口径层级——查询类的描述重点写返回什么信息操作类的描述重点写什么时候触发、有什么影响。两条线不要混在一起模型内部对查和做的区分会变得更稳定。另外一个细节工具列表越长每次请求的token消耗也越高。我在40多个函数时测过一次光tools定义就占掉了约1500个token。如果对话轮次多成本会线性上升。建议把不常用的函数拆到不同的工具分桶里按场景动态组装比如订单域、售后域分开加载。3. 实操过程从零做一个工单查询助手3.1 环境准备与模型选型我用的方案是基于某主流云厂商的大模型API服务SDK本身提供chat.completions接口和tools参数。你要先确认三件事你的账号已开通模型服务且有可用的API Key。所选模型版本支持Function Calling。当前主流的商用和开源模型基本都支持但不排除个别早期版本不支持建议先从官方文档确认。SDK版本不要太旧。tools参数是后加的老版本可能没有对应字段直接升级到当前稳定版就行。我的本地环境是Python 3.10 官方SDK代码全部跑在内部测试服务器上。连接时设了个基础超时避免网络抖动导致整次请求卡死。3.2 业务函数定义查询工单、查物流、提交退单我在POC阶段定义了三个函数。第一个是查询工单状态。第二个是查询物流轨迹。第三个是提交退单申请。物流轨迹函数的设计里有一个值得借鉴的点物流单号和工单编号是两个不同的体系用户在问物流时往往只给订单号。我没法保证用户给的那个号一定是物流单号所以函数里同时接收两个可选参数一个tracking_no、一个order_no在代码内部做兼容优先按tracking_no查查不到再按order_no关联查询。模型在description的引导下能根据用户给的原始信息自动选择填哪个参数。第三个提交退单申请是典型的操作型函数。我特意加了reason必填参数并且使用enum约束退单类型。执行前我会让代码二次确认避免模型自作主张输出一个不存在的类型。def submit_refund_request( work_order_id: str, refund_type: str, reason: str ): 真实业务代码校验工单状态、写入退单申请记录、通知售后人员 # 这里只做演示真实项目需要接入数据库操作 return { success: True, refund_no: RF work_order_id, message: 退单申请已受理预计1个工作日内审核 }所有函数实现都保持一个约定返回给模型的都是纯Python结构dict/list不打印日志、不做多余格式包装。这样后续拼接上下文时最省事。3.3 完整请求链路从工具注册到结果回传Function Calling的请求流程有很多版本但核心链路是固定的第一次调用让模型决定该不该调工具、调哪个、传什么参数如果模型返回了tool_calls代码去执行函数然后把函数结果以tool消息追加进对话再进行第二次调用让模型基于真实结果组织最终回复。我在代码里封装了一个核心循环def run_conversation(messages, tools, max_rounds3): client get_client() for _ in range(max_rounds): resp client.chat.completions.create( modelMODEL_NAME, messagesmessages, toolstools, tool_choiceauto ) msg resp.choices[0].message # 模型决定调用工具 if getattr(msg, tool_calls, None): messages.append(msg) # 把带有tool_calls的消息放进历史 for tc in msg.tool_calls: # 这里把函数结果以tool角色追加回去 result dispatch_tool(tc.function.name, tc.function.arguments) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) continue # 继续调用模型生成最终回答 # 没有工具调用说明模型给出了答复 return msg.content return 处理轮数超过上限请稍后再试这段代码有好几个关键点。第一tool_calls里的arguments是个字符串不是对象。我在dispatch_tool里用json.loads解析解析失败就用{}兜底让函数的默认参数逻辑去处理。第二tool_call_id一定要原样保存在追加的tool消息里这个ID把函数的返回结果和某一次工具调用关联起来丢了会直接报错。第三continue这个逻辑很关键因为一次回复里可能有多个工具调用请求必须让模型在拿到所有执行结果之后再做最终汇总。3.4 多轮对话状态别把历史消息弄丢单轮调用很简单但真实用户不会只问一次。用户第一句帮我查一下WO20240001的工单状态第二句物流到哪了第三句帮我提交退单。这三句之间是有上下文的。我的做法是把所有消息包括系统提示词、用户消息、带tool_calls的助手消息、tool结果消息统一维护在一个list里每次新请求时追加用户新输入再全量发给模型。关键坑点有两个tool结果消息一定要放在对应助手消息之后。顺序乱了模型就看不到是什么请求得到的这个结果容易答非所问。不要把函数执行的敏感字段放进messages。比如退单申请里包含用户手机号如果直接以原样丢回给模型那么后续模型在总结时可能会复述这些隐私信息甚至有泄漏风险。稳妥做法是只把必要字段、脱敏后的字段返给模型。我还处理过一个细节当某轮函数执行失败时不要把异常堆栈直接拼回给模型。模型看不懂Python traceback反而会编段安慰话。正确的姿势是返回一个标准错误结构{success: false, error: 工单不存在请检查编号是否正确}并配合description里的语气要求让模型用自然语言向用户解释错误。3.5 参数抽取模型填错参数怎么办参数错误是Function Calling里最高发的问题我实测中大概有5%~10%的请求参数会有小问题。分为三种第一种是用户没提某个必填参数但函数定义里写了required。模型在极端情况下会强行编一个值。应对办法除了required字段克制外还可以在description里写明如果用户没有提供工单编号请明确询问用户不要猜测。我在query_work_order_status的description末尾加了一句若工单编号缺失或不确定请先向用户索要之后参数幻觉明显减少。第二种是用户给的参数是自然语言与函数定义里的枚举值对不上。比如用户说我要紧急处理一下但我定义的priority只有high和normal。这时模型可能输出紧急。解决思路是不要指望模型翻译业务词而是调整descriptionpriority字段只接受high或normal若用户表达为紧急加急等请转换为high。我实测这种显式映射比让模型自由发挥要稳得多。第三种是参数根本不是这个函数该接收的。比如用户问物流模型却调了查工单函数。这种情况往往是description之间区分度不够或者命名前缀不清晰。排查思路是先看模型调用链路的日志检查工具列表里相近函数的description调整触发场景举例。4. 常见问题与排查技巧实录4.1 模型死活不调用函数只会用对话回答这个问题的高发期在刚接入Function Calling时。排查思路按顺序走先确认模型版本是否支持tools参数。有的旧版模型在接口层面忽略了tools字段模型根本看不到工具。再看tools数组是否真的传进去了。在代码里打印payload[tools]确认数组不为空、JSON序列化正常。我曾经因为字典键名大小写写错SDK没报错但模型没收到工具。最后看用户输入是否很像需要查数据的表述。如果用户说你好模型当然不会调函数。但我遇到过用户说工单号是WO0001你能帮我查一下吗模型却回答了好的我帮你查的假动作。这种时候十有八九是description里缺少触发场景示例模型不知道这个工具能用来干嘛。还有一个trick排查阶段临时把tool_choice设为required或{type: function, function: {name: query_work_order_status}}强制模型必须调用指定函数。如果强制调用成功说明工具链路没问题问题出在模型的自主判断上如果强制也失败问题多半在函数定义格式上。4.2 参数里多出来一个奇怪字段有段时间模型对同一个查询工单状态函数偶尔会在返回的arguments里多塞一个order_no字段但我定义里根本没这个参数。排查后发现description里我写了一句也可根据订单号查询模型在理解上把这句当成了允许传order_no。函数定义里没定义这个字段但模型的工具调用输出并不严格受JSON Schema约束它有时会自由发挥。我当时的解决方式是一是把description里的可用订单号关联查询这种功能描述删除或改写二是代码在解析时增加一层字段白名单过滤。到现在我所有工具的dispatch逻辑里都有这一步allowed_keys {work_order_id, tracking_no, order_no} args {k: v for k, v in raw_args.items() if k in allowed_keys}看着简单但能挡住一大批模型善意越权。4.3 模型返回结果后二次回答开始胡说八道当我把函数执行结果拼回messages后模型在第二轮的总结回复中有时会把函数返回的数据原文复述得乱七八糟甚至自己推测用户的女朋友也下了单。我复盘后的结论是system prompt里的语气约束不够明确。我在system prompt里加了一段固定要求当函数调用返回结果后直接依据结果中的事实回答用户。不要推测不存在的信息不要虚构任何数字或状态。如果结果中包含缺失字段如实说明该字段未记录。另外有一个小技巧函数返回给模型时嵌套数据结构别太深。模型对嵌套list dict的临场理解没有人类那么强很多胡编乱造恰恰发生在总结深层嵌套数据的时候。我做一个平整化处理把关键字段以key: value的形式平铺在返回文本中。实测下来二次回答的准确率提升了一个台阶。4.4 多轮对话里工具调用的上下文物件错位这个坑我一开始没意识到。我用简化版维护历史消息时发现第三轮对话时模型报错tool_call_id不存在或者收到的tool消息没有对应的函数调用。排查后确认某次请求返回了两个tool_calls我循环里用了同一个消息对象追加两次Python的对象引用导致第二条tool消息的tool_call_id被覆盖。所以上面那段代码里我特意在循环内用原始msg对象追加并逐条配置tc.id。强烈建议在封装API时对messages做一次深度拷贝避免对象引用被后续循环修改。这个bug排查得非常费劲最终是在日志里打印了完整messages结构才找到的。4.5 同一批请求里多个函数调用执行顺序与依赖模型在一次回复里有时会同时要求两个函数比如查工单状态和查物流信息。这两个函数相互独立可以并行执行。我在代码里实现了简单的并发from concurrent.futures import ThreadPoolExecutor with ThreadPoolExecutor(max_workers3) as pool: futures [ pool.submit(dispatch_tool, tc.function.name, tc.function.arguments) for tc in msg.tool_calls ] results [f.result() for f in futures]但有个业务陷阱如果两个函数有依赖关系比如先查订单号、再根据订单号查物流模型虽然会在一次回复里连续发起两轮调用但代码里单纯并发是不行的必须先执行第一个拿结果、回传后再让模型决定第二次调用。我的建议是依赖型调用不要并发独立型调用可以并发并且每次运行都要设置轮数上限防止模型连环调工具死循环。4.6 实测下来最好用的调试方法Function Calling是一个黑盒调试难度在于看不到模型内部决策过程。我分享一个自己用得很顺的调试方法论给所有工具调用链路加上结构化日志。每一次请求记录下用户原始输入模型返回的工具调用function name和arguments原文函数执行的真实结果模型最终回复然后把这四段拼成一个文本逐条对照。绝大多数问题都能在这个过程中发现因为你会发现模型其实调对了函数但函数本身的返回结构不好、模型参数抽对了但你的业务代码把结果过滤错了等等。业务代码的错误和模型调用的错误排查方向完全不同不分开记录非常容易互相干扰。顺便说一句我在测试环境里手动模拟参数时特别喜欢用极端输入来测空字符串、超长文本、中文数字混排、表情符号。模型对这些边缘输入的参数抽取能力波动很大提前测一遍能避免不少线上事故。最后的实操心得做完这个工单系统再往后走我最大的感受是Function Calling的重点根本不在调用而在定义。谁把函数描述写得好、参数边界设计得干净、返回数据组织得扁平谁就能在前端少写一堆容错逻辑。踩过几次坑之后我现在的习惯是先写函数定义文档再写代码先在小范围POC上验证工具召回率再接入完整业务。后续要扩展的话可以往工具函数自动编排方向走比如让模型先把任务拆解成DAG再逐步执行那就是另一层复杂度了。建议你先从一个函数、一条链路开始把日志打全、把范式跑稳再慢慢加工具这条路是最稳妥的。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
