Function Calling 这个词最近在 AI 应用开发圈子里出现频率很高但说实话很多人一开始看到它都是一头雾水——它到底是个什么机制模型凭什么能调用我的函数我自己的业务代码怎么跟大模型接上这些疑问如果不解决看官方文档就像看天书。我自己是踩了不少坑才把整个链路跑通的。这篇就当是一份手把手笔记从最底层的原理讲起带你把 Function Calling 从零开始完整落地。文章里不会有太虚的理论基本都是我实际敲过、跑过、调试过的代码和流程尤其适合刚接触大模型应用开发、想给自己的系统接入工具调用能力的开发者。我会用大量生活化的类比把复杂概念讲清楚每一步都给出能直接改用的示例。1. 先搞清楚一个核心问题模型凭什么能调用函数1.1 大模型的本质只懂文字不懂执行想要真正理解 Function Calling第一步得接受一个事实大模型本质上是一个“文本生成器”。它做的事情只有一个——根据你给它的上下文预测下一个最合理的 token可以简单理解成一个词或片段。它确实知识量很大能写文案、能解释代码、能陪你聊天但所有这些能力都发生在“文本世界”里。举个例子你问它“现在北京几度”它如果没接实时数据源根本不可能知道真实温度。它也许会编一个“今天 22 度晴转多云”给你而且说得头头是道——但这只是它在做文字接龙并不是在查询气象站。同理你让它“计算一下公司这个季度的总营收”如果只是把一串数字贴在对话里它大概率也会给你一个看着合理、实际上算错的结果。用一个好记的类比大模型像一位博览群书但从不联网、也不会动手算账的顾问。你问知识性问题他能给你讲得明明白白但你要他帮你办一件需要实时数据的实事他就只能干瞪眼然后硬着头皮编一个答案交差。Function Calling 就是给这位顾问配上“手脚”让他能够真正去执行操作。1.2 Function Calling 是给模型加一副“手脚”Function Calling 的核心思路并不复杂在发请求给模型的时候除了普通的对话消息你额外给模型一份“工具清单”清单里写明每个函数叫什么、是干什么的、需要哪些参数、参数是什么类型。模型看完用户的问题后会自己判断“这个问题需要调用某个工具”然后在回复里输出一段结构化的内容大致意思是我建议调用get_weather这个函数入参是{city: 北京}。关键点在这里模型只是“建议调用”它本身并不会真的去执行你的函数。真正执行的人是你——你的代码收到模型的这个结构化建议后自己去调用真实的天气接口、数据库查询或内部服务然后把执行结果以一条新消息的形式送回给模型。模型结合这个结果再生成最终的、面向用户的回答。我把这个过程总结成一句话模型负责决策应用层负责执行结果再回流给模型做总结。这样设计的好处很明显你的业务逻辑、数据权限、安全校验都可以牢牢把控在自己手里模型永远不直接触碰你的系统和数据。1.3 它帮助解决的具体痛点在没有 Function Calling 之前想把大模型接入实际业务通常要写一堆正则表达式去解析用户意图再从夹缝里提取实体比如城市名、日期、订单号然后自己决定调哪个接口绕了一大圈。Function Calling 把这一整条链路大大压缩了模型直接输出“要调哪个函数、传什么参数”。它适合解决的场景大致包括查询实时数据天气、股价、物流、操作业务系统查订单、建工单、改配置、调用计算工具做数学计算、单位换算、以及需要把非结构化自然语言转成精确参数的场景比如“帮我订一张后天下午三点的票”。凡是需要把用户的自然语言和内部系统连接起来的地方Function Calling 基本都是目前最顺手的方案。2. 完整看清一次函数调用的生命周期2.1 从一次“查订单”讲起假设你正在做一个小助手用户可以问“我的订单估计什么时候能到”系统里其实有一个查物流的接口但模型自己不知道这个接口的存在。你需要在请求里额外带上这样一份“功能卡片”query_logistics参数是订单号order_id。模型拿到用户消息和这张卡片后会在内部做一次推理判断然后输出一段与普通聊天完全不同的内容——它不会直接说“你的订单明天到”而是先返回一个工具调用请求。这通常表现为一个tool_calls字段里面包含函数名和参数 JSON。你的程序看到这个字段就知道“模型想把球踢给我了”。2.2 模型返回的结构长什么样我们看一下模型返回的关键部分大概长什么样不同实现细节略有差异主体结构基本一致{ choices: [ { message: { role: assistant, content: null, tool_calls: [ { id: call_abc123, type: function, function: { name: query_logistics, arguments: {\order_id\: \20250114001\} } } ] } } ] }注意arguments是一个字符串不是 JSON 对象。你需要自己用json.loads()把它解析成 Python 字典。id字段也很重要后面你回传工具结果时要用它来配对。2.3 为什么模型“光说不做”需要应用层执行这是很多第一次接触 Function Calling 的人最容易疑惑的地方“为什么模型不直接把结果告诉我非要让我自己执行”答案可以归结为三点。首先是安全与权限。模型生成的代码或操作指令如果直接执行风险不可控。比如你让模型调用一个“删除用户”的函数它可能会因为理解偏差而误操作。把执行权留在应用层你就可以在执行前加权限校验、参数白名单、人工确认等保护机制。其次是确定性与可审计性。模型每次调用函数时参数怎么生成有一定随机性。你在应用层执行可以记录完整的调用日志出了问题能追踪能复现。模型输出只是“建议”你才是最终的决策执行者。第三是工程上的解耦。函数真正跑在什么环境、读哪个数据库、对接哪个第三方服务这些都是你的事。模型只需要知道“有这个函数、大概做什么、接受什么参数”就够了。两边各管一段后续维护起来也清爽。2.4 工具描述给模型看的说明书模型之所以能“理解”你的函数全靠你传给它的那组工具描述通常叫tools参数。这玩意儿本质上就是一份“给模型看的说明书”。你描述得越清楚模型就越能准确地在合适的时候调用它。我自己的体会是写工具描述时要把模型想象成一个完全不了解你业务的新人。你告诉他“这个函数用来干啥”他才知道什么时候该用你告诉他“这个参数是什么意思”他才不会把日期填进城市名里。后面我会专门讲怎么写好这份说明书。3. 从零开始5 步搭建一个可运行的 Function Calling Demo理论说了不少下面直接动手。我会用最常见的 Python 加 HTTP 请求方式走一遍完整流程。这个例子里没有引入重量级框架你只要装了 Python 环境把代码粘贴进去换上自己的 API Key 就能跑通。3.1 准备工作与环境你需要三样东西一个 Python 3.9 以上的环境、一个支持 Function Calling 的大模型 API 访问权限、以及requests库没有就先执行pip install requests。为了演示方便我会把 API 地址抽象成一个通用变量。你在实际项目里替换成自己用的模型服务地址和 Key 即可请求结构大体是通用的。3.2 定义一个真实的查询函数先在我们自己的应用层写一个函数它模拟查询天气。真实项目里这个函数内部会去调国家气象服务的 API这里为了让你看清流程先用静态数据替代。import json def get_weather(city: str, date: str None): 真实的项目里这里会去调天气服务的API。 data { city: city, date: date or 今天, condition: 晴, temperature: 26, humidity: 40, } return json.dumps(data, ensure_asciiFalse)注意这个函数必须能接受模型可能传进来的所有参数否则后面执行时会爆TypeError。3.3 把函数翻译成模型能读懂的 Schema这一步是 Function Calling 的关键。我们要把上面的函数描述成下面这个 JSON Schema 格式tools [ { type: function, function: { name: get_weather, description: 查询指定城市在某一天的天气情况包括天气现象、温度和湿度。当用户询问天气时使用。, parameters: { type: object, properties: { city: { type: string, description: 城市名例如北京、上海、广州 }, date: { type: string, description: 查询日期格式为 YYYY-MM-DD不传表示今天 } }, required: [city] } } } ]这里有几个细节值得注意。name就是函数名建议全小写加下划线不要带特殊字符。description要清楚地说明函数用途以及适用的场景比如“当用户询问天气时使用”这能帮模型判断什么时候触发。parameters里每个字段都要有清晰的description尤其是参数含义可能产生歧义的时候。required数组里列的是必填项模型在调用时无论如何都会带上这些字段。3.4 带上工具发起第一次请求接下来我们封装一个通用的请求函数把对话消息和工具列表一起发给模型。import requests API_KEY YOUR_API_KEY API_URL https://api.your-llm-service.example/v1/chat/completions def chat(messages, toolsNone): payload { model: demo-model, messages: messages, tools: tools or [], } headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } resp requests.post(API_URL, headersheaders, jsonpayload, timeout60) resp.raise_for_status() return resp.json()构造第一轮用户消息并发送messages [ {role: user, content: 北京今天天气怎么样} ] response chat(messages, tools) assistant_message response[choices][0][message] messages.append(assistant_message) print(json.dumps(assistant_message, ensure_asciiFalse, indent2))此时如果一切正常你会看到assistant_message里出现了tool_calls字段内容大致是建议调用get_weather参数是{city: 北京}。3.5 解析返回值并真正执行函数看到tool_calls之后你的应用层就该干活了。逐条解析工具调用根据函数名分发给对应的真实函数去执行if assistant_message.get(tool_calls): for tool_call in assistant_message[tool_calls]: fn_name tool_call[function][name] fn_args json.loads(tool_call[function][arguments]) if fn_name get_weather: result get_weather(**fn_args) else: raise ValueError(fUnknown function: {fn_name}) # 把执行结果以 tool 角色消息回传给模型 messages.append({ role: tool, tool_call_id: tool_call[id], content: result, })这里提醒一个新手很容易踩的坑json.loads解析出来的参数有可能不是合法的 JSON。模型虽然大部分时候输出正确但你一定要做异常捕获。后面我会专门讲这个问题如何处理。3.6 把结果送回对话拿到最终答案执行完函数后把所有回传的消息再发给模型一次让它基于函数结果生成最终回复。final_response chat(messages, tools) final_message final_response[choices][0][message] print(final_message[content])这次模型会正常输出回答例如“北京今天晴气温 26 度湿度 40%。” 至此一次完整的 Function Calling 流程就闭环了用户提问 → 模型建议调用工具 → 应用层执行 → 结果回传 → 模型生成最终回答。这个模式一旦跑通后面要扩展的其实就是函数数量和参数复杂度了。4. 参数设计进阶怎么让模型听话不乱传跑通 Demo 只是第一步真正到了生产环境你会发现参数设计才是决定体验的上限。同样的函数描述写得好与差模型调用时的准确率可能差出好几个档次。4.1 必填、类型和描述都不能含糊先说required。如果你没有把某个参数标为必填模型调用时可能会不传它你的函数就必须处理参数缺失的情况。反过来如果你标了必填但模型没有足够信息去填充它有时候会瞎编一个值。比如用户问“上海天气”没给日期你的日期参数却设成了必填且没有默认值模型就有可能编造一个“2025-01-14”这样的日期塞进来。我的建议是只有用户不提供就无法执行判断的字段才设为必填可有可无的字段统统给默认值并在描述里写明“不传时默认为...”。这样既能降低模型胡编的概率也能减少执行层报错。4.2 用枚举值和默认值限制发挥空间有些参数看起来是自由文本实际上取值范围很有限。比如单位、状态、渠道这些就应该用enum明确限定让模型只能在你的选项里选不能自由发挥。parameters: { type: object, properties: { city: { type: string, description: 城市名例如北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位celsius 表示摄氏度fahrenheit 表示华氏度 } }, required: [city] }这么做带来的好处非常直接函数执行时不需要再对自由文本做各种兼容处理模型传过来的值一定是合法值。另外给参数设置合理的默认值也很有用模型没传时你直接用默认值逻辑更稳定。4.3 多参数案例加上日期和温度单位我们把天气函数扩展一下带上更多参数你看完整结构长什么样tools [ { type: function, function: { name: get_weather, description: 查询指定城市在指定日期的天气情况包括天气现象、温度和湿度。, parameters: { type: object, properties: { city: { type: string, description: 城市名例如北京、上海、广州。 }, date: { type: string, description: 日期格式为 YYYY-MM-DD。不传表示今天。 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位。不传默认为 celsius。 } }, required: [city] } } } ]模型在收到“北京明天多少度用华氏度告诉我”这样的问题时就应该输出类似{city: 北京, date: 明天日期, unit: fahrenheit}的调用参数。你会发现参数名、描述和枚举值之间的配合直接影响模型的选择精准度。4.4 参数描述里的话术很重要写参数描述时我建议遵循“先说含义再说格式最后给示例”的顺序。比如日期格式为 YYYY-MM-DD例如 2025-03-20比单纯写日期要好得多。因为模型理解“含义”靠名字理解“格式”靠描述里的具体说明理解“怎么填”靠示例。三层信息都齐全它犯错的概率才会最低。5. 多工具与平行调用从“单工具”走向“工具超市”实际项目里不太可能只让模型调用一个函数。更常见的情况是你有一个工具列表里面有查天气的、查日历的、算加班的、发邮件的模型要根据用户问题自己选择合适的工具。这一节说多工具场景。5.1 一次递多个工具模型如何选择用法上没有变化就是把多个工具对象放进同一个tools列表。模型会根据用户问题的语义、每个工具的description、参数匹配度综合判断该调哪个。一个很有用的技巧给工具的description写清楚“什么时候用、什么时候不要用”。比如你有一个send_email工具就可以写“当用户明确要求发送邮件时使用仅用于发送邮件不用于草拟邮件内容”。这样能显著减少模型误调用的次数。说白了工具描述就是模型的“使用手册”手册写得越细模型就越不容易用错。5.2 平行调用一次返回多个函数调用的场景某些大模型的接口支持平行调用也就是说模型可以在一次回复里同时输出多个tool_calls。举个例子用户问“北京和上海今天天气怎么样”模型可能会在一条消息里返回两个工具调用一个查北京一个查上海。这样你不用跟模型来回对话两轮直接并行执行两个查询再一次性把结果都回传效率和体验都会好很多。要注意的是你的代码必须做好多工具调用循环的兼容——不能假设tool_calls只有一条。前面的示例里我已经用了for tool_call in assistant_message[tool_calls]就是为了兼容这种情况。5.3 工具列表膨胀时防止选错的思路当工具数量超过十个模型的“选择准确率”会开始下降。我实际测下来工具一多就会偶发选错或者该调不调的情况。有几个缓解办法把相似的函数合并成一个函数用内部参数区分在描述里使用用户通常会说的自然语言关键词比如用户会说“查快递”那描述里就写上“查快递 / 查物流”最严重的时候可以考虑先让模型做一个粗分类再进入精服务模式把工具拆分到不同的模块里。6. 三种循环模式覆盖日常开发的大多数场景代码层面Function Calling 的实现往往不是跑一次就结束而是循环处理。根据业务需求不同循环方式可以分成三种下面分别说。6.1 单轮直出查询一次就结束单轮模式最简单适合“一次调用、一次回传”的场景比如天气查询、单点计算。代码逻辑就是前面演示的那样发请求 → 看有没有tool_calls→ 有则执行回传 → 没有则直接输出最终内容。很多内部工具站点的函数调用都可以用这个模式实现代码短易调试也足够满足需求。6.2 多轮工具链连续调用多个工具有些需求自然需要多步操作。比如用户问“北京适合穿什么衣服出门”模型需要先调用get_weather拿到天气再基于温度判断穿衣建议。这时你就需要用循环来处理只要模型返回的message带tool_calls就不断执行工具并回传直到模型不再请求调用工具为止。这是一个简单的 while 循环while True: response chat(messages, tools) assistant_message response[choices][0][message] messages.append(assistant_message) if not assistant_message.get(tool_calls): break for tool_call in assistant_message[tool_calls]: # 执行工具回传结果代码同上 pass print(messages[-1][content])这个模式能应付绝大多数复杂应用包括智能客服、数据分析助手、操作类机器人。它本质上让模型在“思考—调用—观察—再思考”的循环里逐步解决问题非常接近人类使用工具的过程。6.3 终止条件设计防止死循环多轮循环最大的隐患是死循环模型反复要求调用同一个函数或者两个函数互相调用个没完白白消耗你的 API 额度。我的经验是加两重保险。第一重轮次上限比如最多允许 5 轮循环超过就强制退出返回“我暂时无法完成你的请求”。第二重重复检测如果连续两次出现完全相同的函数调用和相同参数就主动中断。这两个机制都不复杂但能避免绝大多数线上的资源浪费。6.4 对话历史的清理与回归多轮循环里messages列表会越积越长。如果不加控制很快就可能顶到模型的上下文窗口上限。一个务实的办法是在进入工具循环前后压缩或截断历史消息。比如用户的原始提问必须保留但早期的冗余内容可以裁剪工具返回的结果如果很长也可以只取摘要或关键字段再放回对话。上下文管理是生产环境里真正拉开工程质量差距的地方很多人只在 Demo 里跑通上线后才发现上下文撑不住。7. 常见问题与排查技巧实录这里整理一下我实际开发中踩过比较多的坑按症状、原因和解决办法列出来你可以对照自查。7.1 模型就是不肯调用工具症状你明明传了tools但用户问的问题显然应该触发工具调用模型却直接编了一个答案。通常原因有两个一是工具描述写得模糊模型不知道这个工具什么时候适用二是模型温度参数设置偏高输出过于发散。解决办法是先把temperature调低到 0.2 以下再把工具描述里补上“当用户询问 XXX 时调用”。另外一个容易被忽视的原因是请求里没正确传tools有些封装库会要求你显式置空或者重复传最好在日志里确认一下实际发出的请求体。7.2 arguments 是字符串解析报错怎么办模型返回的arguments偶尔会包含一些不规范内容比如多余的逗号、换行或者把布尔值写成了字符串。json.loads直接解析失败工具直接报错。我建议做两层处理先用json.loads严格解析失败后用正则提取{...}片段尝试二次解析还失败就直接返回给模型一条斗篷消息告诉它“你生成的参数无法解析请重新调用”。与其在解析上反复折腾不如让模型自己“回炉重造”效果往往最好。7.3 工具返回结果很长上下文爆炸工具函数返回的数据经常是一大段 JSON 或日志文本如果原封不动塞回对话几个来回就把上下文塞满了。两个办法一是工具内部做汇总能返回摘要就不返回全文比如查物流不要返回所有轨迹只返回最新一条二是回传前截断把超过一定长度的内容裁剪掉加上省略号。模型只需知道关键结果就能生成回复细节数据如果你需要展示给用户可以另外走接口。7.4 流式输出的 Function Calling 适配如果你用了流式输出SSE处理逻辑会稍有变化tool_calls里的arguments会被分片推送你需要自己在客户端按index组装字符串等流结束才能拿到完整的参数再执行函数。这里最容易犯的错是在流还没有结束时就开始解析arguments结果必然是格式错误。稳妥的做法是先收集、后解析、再执行不要收到第一片就急着处理。8. 踩坑总结几个让我印象深刻的教训8.1 描述要像给新人写任务说明我最初写工具描述时很偷懒比如只写“查询天气函数”结果模型经常在用户问“明天带不带伞”的时候不调用它理由可能是它觉得“带伞”跟“天气”关系不够直接。后来我把描述改成“根据城市和日期查询天气包括天气现象、温度、湿度。可用于判断是否需要带伞、穿衣建议、出行安排等”调用准确率立刻上来了。模型不是人不会自己脑补工具的适用场景你必须把可能的使用场景直接写进去。8.2 工具数量不是越多越好手里的函数多到一定程度真正的问题不是“模型能不能都学会”而是“模型会不会选错”。每新增一个工具都会引入新的选择空间和错误概率。我后来习惯给工具做分组像订单类和用户类分开服务即便接口允许一次传 30 个工具我也会按业务场景把它们拆分到不同请求里。少而精准永远比多而全更可靠。8.3 对模型返回结果做一层校验模型不是你同事它不会百分之百遵守你的描述。函数名拼错、参数类型不对、传了非必填字段、甚至调用了你没有注册的函数——这些情况我都遇到过。所以应用层的分发逻辑一定不能裸奔要做一层兜底校验函数名不在白名单里就拒绝执行参数强校验之后再传给目标函数。宁可拦截下来让模型重来也不要让一个非法调用打穿你的业务。这次从原理到实战把 Function Calling 从头梳理了一遍核心其实就一句话模型负责给出调用工具的“意图和参数”真正的执行始终掌握在你手里。按照这个思路你就能从最简单的单工具查询开始逐步搭建起复杂的多工具应用。我最后再给你一个实用建议先跑通一个最简单用例再扩展参数、多工具和循环千万别一上来就想做一个全能的智能体循序渐进才是最快路径。