1. 项目概述与原理拆解

1.1 为什么需要Function Calling

先从一个最让人头疼的场景说起。你让大模型帮你查一下某地明天的天气，模型确实会答得头头是道，但内容大概率是编的。因为训练数据里根本不可能包含“此刻”的实时天气。再比如你要让模型执行select * from orders where user_id = 1024这种数据库查询，模型能写出SQL，但它连不上你的数据库，更不知道你库里的表结构。

传统的解决办法是让模型输出一段结构化JSON，然后你在程序里解析这段JSON、再自己去调接口。听起来可行，但实际用过的朋友都知道这日子不好过：模型输出的JSON经常少个括号、多个逗号，字段名一长就容易拼错，一旦嵌套层级深一点，轻则解析报错，重则静默丢字段。你为了健壮性写的那些重试、修复逻辑，往往比业务代码还复杂。

Function Calling（函数调用）解决的就是这个衔接问题。它把“模型生成文本”和“程序执行动作”之间的这条鸿沟，用一套标准协议填平了。模型不再是输出一段需要你去猜的文本或JSON，而是明确输出“我要调用哪个函数、参数是什么”，格式由协议保证，程序拿到后直接执行即可。

这个机制之所以叫Function Calling，是因为它本质上是在模拟编程里的“函数调用”概念：模型扮演调用方的角色，你的本地代码扮演被调用方，中间的消息协议就是参数传递和返回值。模型负责“决定调什么、传什么”，你的代码负责“真正执行、返回结果”。

1.2 一次完整的函数调用生命周期

要理解Function Calling，我建议把一次完整交互拆成四个阶段来看。

第一阶段是“告知意图”。你在请求里带上tools参数，里面包含一个或多个函数的描述信息：函数名叫什么、作用是干什么的、参数有哪些、每个参数的类型和约束是什么。这些描述不是给人看的，是给模型看的，模型会把这些函数当成它“可选用的工具清单”。

第二阶段是“模型决策”。用户发来一句“帮我查一下北京明天的天气”，模型读取你的函数清单后，发现get_weather这个函数最匹配，于是它在回复里不再直接写天气结果，而是生成一个结构化的tool_calls对象，里面写清楚函数名和参数：

{ "name": "get_weather", "arguments": {"city": "北京", "date": "2025-01-10"} }

注意，模型在这一步并没有真正去查天气，它只是表达了“我想调用这个函数，并且我这样理解用户的意图”。

第三阶段是“执行与回填”。你的程序收到tool_calls后，解析出函数名和参数，调用本地真实函数，拿到结果，再通过role: "tool"的消息结构把结果回传给模型。这个回传消息必须带上tool_call_id，用于和上一步的调用请求一一对应。

第四阶段是“归纳回答”。模型看到工具执行结果后，基于真实数据生成最终的自然语言回复：“北京明天晴，气温3到12度，注意早晚温差。”整个流程用户完全无感，他只觉得AI“真的会查天气了”。

这四步看起来简单，但每一步都有不少坑。我后面会详细展开，尤其第三阶段回填消息的格式，很多人第一次搞Function Calling就在这栽跟头。

1.3 这套机制能解决哪些实际问题

Function Calling的威力不在单个函数调用，而在它把大模型改造成了一个“调度中枢”。模型本身不掌握数据、不拥有权限、不真正执行操作，但它能理解用户的复杂意图，并将其拆解为可执行的函数调用序列。

典型的应用场景包括但不限于：智能客服中查询订单状态、物流信息；数据分析助手中根据自然语言生成SQL并执行查询；内容创作工具中调用搜索接口获取素材；智能家居场景里解析“把客厅空调调到26度”这样的指令并触发设备动作；企业内部的文档检索系统里，先调用一个函数获取用户权限，再调用另一个函数做语义搜索。

我在实际项目里最看重的其实是三点：第一，参数结构标准化，省掉大量解析容错代码；第二，决策与执行分离，模型永远不直接触碰真实系统和数据，安全边界可控；第三，函数可以无限扩展，每条业务能力封装成一个函数，模型自动感知并调用。这也是我为什么说“让AI更强大”——它不再是聊天机器人，而是一个能使用工具的智能体。

2. 核心要素拆解：函数定义、请求格式与响应解析

2.1 函数定义文档：模型理解你工具的唯一天窗

很多刚接触Function Calling的人有一个误区：觉得函数定义就是写参数的类型和默认值。实际上，模型对函数意图的理解，完全取决于你写的函数描述文本质量。

一个标准的函数描述长这样：

{ "type": "function", "function": { "name": "get_weather", "description": "查询指定城市在指定日期的天气情况，包括温度、天气现象、风力等信息", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，必须是中文，例如：北京、上海、广州" }, "date": { "type": "string", "description": "日期，格式为YYYY-MM-DD，默认当天" } }, "required": ["city"] } } }

需要格外注意的是description字段。模型不会去读你的代码，它只能通过这段文字理解“什么时候该用这个函数”。写得太笼统，模型会在不该调用的时候乱调用；写得太窄，模型又容易漏调用。我试过的经验是，描述里应该包含三个信息：触发条件、执行内容、关键限制。

比如get_weather的描述如果我写成“查询天气”，模型很可能连“用户聊到明天出门是否要带伞”都会触发它。但如果我写成“仅当用户明确要求查询某城市某日天气时调用，闲聊时不要触发”，准确性会明显提升。

parameters里的每个属性也要带上详细的description。模型需要知道city这个参数应该填“北京”而不是“beijing”或“BJ”。这些约束写不写，直接决定你后续要花多少精力去清洗参数。

参数类型方面我提醒一句：底层API是支持number、integer、string、boolean、array、object这些JSON Schema类型的，但绝大多数情况下你只需要用string和object两种就够了。原因很简单：模型生成“结构化字符串”比生成“精确数值”稳健得多。比如年龄字段，与其让模型生成integer然后可能给出一个奇怪的数字，不如让它生成字符串你再用代码去转。

2.2 请求结构与关键参数

定义好函数清单后，请求参数里要额外带上tools和tool_choice。

完整请求体核心部分是这样的：

{ "model": "model-name", "messages": [ {"role": "system", "content": "你是智能客服助手，使用工具回答用户问题"}, {"role": "user", "content": "北京明天天气怎么样？"} ], "tools": [...上面的函数定义...], "tool_choice": "auto" }

tool_choice有三个可选值，区别很大：auto表示模型自行判断是否调用工具、调用哪个；none表示禁用工具调用，纯文本回答；required表示强制模型必须调用某个工具。另外还可以指定具体的函数名，比如{"type": "function", "function": {"name": "get_weather"}}，强制模型只能调用这一个函数。

我自己的习惯是：大多数轮对话场景用auto，把决定权交给模型，因为模型对语义的理解往往比你预设的规则更灵活。但如果你明确知道当前这一步就是要走工具，比如“先查库存再回复”，那用required可以避免模型在关键环节掉链子。还有一种特殊情况，模型已经连续两轮不调用工具且回答错误时，我会临时把tool_choice切换为required做一次纠正。

2.3 返回结果与tool_calls解析

当模型决定调用函数时，返回的message里会出现tool_calls字段。结构如下：

"message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_123456", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\": \"北京\", \"date\": \"2025-01-10\"}" } } ] }

这里有两个反直觉的点。

第一，arguments是一个字符串，而不是JSON对象。你拿到后必须先json.loads再使用。我见过不少人忘了这层转换，直接把字符串当字典用，结果报类型的错。第二，content此时是null，因为模型没有直接生成答案，它选择了调用工具。这个content为null的状态是判断“本轮需要执行工具”的信号，很多框架代码就是靠检查tool_calls是否存在来分支的。

再强调一点：一条assistant消息里可能有多个tool_calls，模型可以在一次回复中同时调用多个函数。每个tool_calls元素都有独立的id，后续回填结果时必须一一配对。

下面是我常用的解析逻辑：

import json def parse_tool_calls(message): if not message.get("tool_calls"): return [] calls = [] for call in message["tool_calls"]: calls.append({ "id": call["id"], "name": call["function"]["name"], "arguments": json.loads(call["function"]["arguments"]) }) return calls

这段代码返回一个列表，每个元素包含调用ID、函数名和解析后的参数字典。后续执行函数、回填结果都会用到这三样东西。

3. 从零搭建一个可运行的Function Calling Demo

3.1 环境准备与调用方式选择

我建议第一次跑通时直接用requests库发HTTP请求，先不要用各种封装好的SDK。原因很简单——封装层帮你把很多细节隐藏了，一旦出错你根本不知道是协议问题还是SDK问题。自己裸调HTTP能让你把每个字段的真实形态看清。

需要准备的东西：Python 3.8以上环境、requests库、一个支持Function Calling的大模型API密钥。如果你用的是兼容 OpenAI 协议的服务，请求URL统一为/v1/chat/completions。

要注意的是，不同服务商对工具调用的字段名可能略有差异，有的用tools，有的用functions，有的返回tool_calls，有的返回function_call。动手前务必去看对应服务的文档，我这里以最通用的格式为例讲解。

3.2 本地模拟函数：查询天气

为了让demo可运行且不依赖外部API，我先写一个模拟查询天气的函数。真实场景里这个函数会去请求气象接口，demo阶段直接返回硬编码数据即可。

import datetime def get_weather(city: str, date: str) -> dict: weather_map = { "北京": {"condition": "晴", "temp_high": 12, "temp_low": 3}, "上海": {"condition": "小雨", "temp_high": 15, "temp_low": 9}, "广州": {"condition": "多云", "temp_high": 22, "temp_low": 15}, } data = weather_map.get(city, {"condition": "未知", "temp_high": 0, "temp_low": 0}) data["city"] = city data["date"] = date return data

这个函数接收两个字符串参数，返回一个字典。它对应前面的get_weather函数定义。为了让模型学会调用它，函数定义的description和parameters要和这个本地函数保持一一对应。

接下来定义一个函数注册表，把函数名映射到真实的Python函数：

function_registry = { "get_weather": get_weather, }

这样后面执行tool_calls时，我只需要通过函数名去注册表里查找并调用即可，不需要写一堆if-else。

3.3 完整对话循环：从提问到执行再到回答

核心逻辑是一个轮询循环。每次把完整的messages列表发给模型，检查返回的message中是否有tool_calls。如果有，就执行工具、回填结果、继续请求；如果没有，说明模型已经生成了最终答案，循环结束。

import requests import json API_URL = "https://api.example.com/v1/chat/completions" API_KEY = "sk-your-key" def chat_once(messages, tools): resp = requests.post(API_URL, headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }, json={ "model": "your-model-name", "messages": messages, "tools": tools, "tool_choice": "auto" }) resp.raise_for_status() return resp.json() def run_agent(user_query): messages = [ {"role": "system", "content": "你是一个天气助手，请使用工具查询天气"}, {"role": "user", "content": user_query}, ] 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"] } } }] for _ in range(5): # 最多循环5次防止死循环 data = chat_once(messages, tools) message = data["choices"][0]["message"] messages.append(message) if message.get("tool_calls"): for call in message["tool_calls"]: func_name = call["function"]["name"] func_args = json.loads(call["function"]["arguments"]) print(f"[工具调用] {func_name}({func_args})") func = function_registry[func_name] result = func(**func_args) messages.append({ "role": "tool", "tool_call_id": call["id"], "content": json.dumps(result, ensure_ascii=False) }) else: return message["content"] return "已达到最大循环次数，未能完成回答" if __name__ == "__main__": print(run_agent("北京明天天气如何？"))

这段代码运行时，你会看到完整的过程：模型先返回tool_calls，程序打印“[工具调用] get_weather({'city': '北京', 'date': '2025-01-10'})”，执行本地函数后把结果回填，模型最后基于结果给出自然语言回答。

这里有个细节值得展开：我把模型的返回消息直接append进messages，再把工具的返回结果也append进去，下一次请求时模型能看到完整的历史。这个顺序不能乱——必须是“模型的tool_calls消息”紧跟在后，再跟上“若干条tool消息”。

3.4 多函数场景下的路由与执行

单个函数demo跑通后，你很快会发现真实场景里一个Agent往往需要十多个函数。这时候的核心问题变成：如何根据模型返回的函数名快速路由到正确的本地函数。

我用过两种方案。方案一是前面提到的字典注册表，简单直接，但如果函数多了，需要手动维护注册表项目。方案二是用Python的装饰器自动收集函数，代码更优雅：

FUNCTIONS = {} def register(func): FUNCTIONS[func.__name__] = func return func @register def get_weather(city, date): ... @register def get_flight(city_from, city_to, date): ...

这样每个新函数只需要加装饰器，自动进入注册表。工具定义的JSON也可以从函数签名自动生成，但前提是你把类型注解和docstring写规范。强烈建议从第一天就用这种模式，否则十来个函数之后，你会迷失在手动列表里。

执行时还需要考虑异常处理：函数内部可能抛异常，不能让它中断整个Agent循环。我通常在调用处包一层try-except，把错误信息作为字符串回传给模型，让模型自行判断下一步策略。比如“查询失败：城市不存在”回传后，模型可能会追问用户“你指的是哪个城市”，而不是直接硬答。

4. 工具选型与Function Calling进阶用法

4.1 基础工具链对比

看过原理和demo后，很多人会问：生产环境里应该用裸HTTP、官方SDK，还是LangChain这类大模型应用框架？

三者各有适用场景，我直接说结论。如果你只是单机脚本或小工具，裸HTTP就够，灵活、没有额外依赖。如果项目里已经用了某个大模型服务商的SDK，用SDK封装好的方法会省不少事，前提是你了解背后的协议细节。如果你在做多步骤、多工具的复杂Agent，我建议引入框架，但不是为了省几个请求代码，而是为了拿到现成的上下文管理、工具注册、重试策略。

选了框架也要有心理准备：框架帮你封装的越多，出问题时越难排查。我见过有人用框架跑Function Calling报错，翻源码翻了一下午才知道是框架往messages里注入了额外的字段。权衡之后，我的建议是：核心链路自己写，走裸协议；外围的编排逻辑可以交给框架。

4.2 用Agent模式实现复杂任务拆解

单个Function Calling只是“模型+工具”的原子操作，而Agent模式才是Function Calling真正发威的地方。Agent模式的核心逻辑是：模型不再止步于调用一个函数，而是持续迭代——调用一个函数、看结果、再调用下一个、再看结果，直到任务完成。

我用一个企业数据查询的案例来说明。假设有一个Agent，注册了三个函数：get_user_by_name(name)返回用户基本信息、get_orders_by_user(user_id)返回订单列表、calc_total(orders)计算金额合计。用户说“帮我查一下张三这个月一共消费了多少钱”。

第一个回合，模型发现需要用户ID才能查订单，于是调用get_user_by_name("张三")。程序返回用户IDU1234。回填后，第二个回合，模型看到有了用户ID，接着调用get_orders_by_user("U1234")，程序返回一批订单数据。第三个回合，模型计算出总金额，生成最终回答“张三6月消费总额为8,720元”。

整个过程完全不需要代码预定义流程。模型会根据每一回合的实际结果，自主决定下一步调哪个函数。这就像一个人拿到工具后自己摸索着完成任务，而不是照着写好的剧本一步步执行。

这种模式带来的架构变化是：你的代码不再以“业务流程”为中心，而是以“能力清单”为中心。每新增一种数据源或操作能力，只需要注册一个新函数，模型的可用范围就扩大了。函数越多，Agent能力越强，但你可控性也越需要关注，我后面会专门讲安全风险。

4.3 并行调用与批量执行

很多模型支持在一次响应中返回多个tool_calls。比如用户问“北京和上海的天气哪个更适合出门”，模型可能会同时发起两个get_weather调用，分别查询两个城市。这正是并行调用的用武之地。

处理并行调用时，代码逻辑和单调用基本相同，唯二需要注意的：第一，多个tool_calls应该可以并行执行，如果你的工具之间没有依赖关系，不要写成一个串行for循环；用线程池或异步并发可以把延迟从“多个函数时间之和”降到“最慢的那个函数时间”。第二，消息回填顺序要和tool_calls一致——严格按tool_calls里的顺序逐条回填，不要乱序。

我自己实测过，两个HTTP接口函数，串行可能要3秒，并行只需要1.5秒。在Agent多轮循环场景里，这个优化很值得做。

from concurrent.futures import ThreadPoolExecutor def execute_tool_call(call): func_name = call["function"]["name"] func_args = json.loads(call["function"]["arguments"]) return call["id"], func_name, function_registry[func_name](**func_args) with ThreadPoolExecutor() as executor: results = list(executor.map(execute_tool_call, message["tool_calls"]))

每个结果是一个(call_id, name, result)元组，依次回填到messages里即可。

4.4 高级技巧：函数定义缓存与动态注册

Function Calling有个容易忽略的成本问题：函数定义和描述文本是要随每个请求发送给模型的，而这些token也要计费。如果你定义了十几个函数，每个函数描述一两百字，光tools就能占掉几百上千token。多轮对话里每轮都要重复发送，成本累积可观。

一种缓解办法是把“固定不变”的函数定义缓存起来，在请求时直接复用。另一个思路是“分级暴露”：不是所有函数在所有对话里都需要。比如客服机器人，如果用户当前聊的是售后问题，你就只暴露售后相关的函数，完全不把售前函数发过去。这样既省成本，也减少模型选错函数的概率。

动态注册函数还可以做成权限分级：普通用户只能调用查询类函数，管理员才能调用写入类函数。在请求组装阶段根据登录态决定tools里放哪些函数。这个设计的效果非常明显，模型根本看不到自己没权限用的函数，你等于从源头上杜绝了越权调用。

5. 常见问题排查与避坑指南

5.1 模型不调用函数或乱调用函数

这是遇到最多的问题。具体分两种情况：该调时不调，不该调时乱调。

该调时不调，多半是函数定义没写清楚。模型不知道什么情况下用这个函数，你把description改成包含触发条件和用户意图的描述就能明显改善。例如“当用户询问某个具体城市的天气或气温时调用该函数，如果只是作者闲聊不要调用”。

乱调函数，通常是路径匹配问题。用户说“帮我订张去上海的机票”，模型却查了上海天气——因为get_weather的描述里写了“上海”这个词，模型被误导了。解决办法是：函数描述里避免堆砌和本函数无关的城市和场景词，保持精准。

如果频繁出现选择性失明，还可以检查tool_choice设置。在明确了必须走工具的时候直接设为required，别指望模型每次都聪明。但注意required模式下模型依然可能选错函数，必要时用上“指定函数名”的模式。

5.2 参数类型与格式错误

模型返回的arguments是JSON字符串，解析后字段类型可能和你预期不一致。最常见的几种：把"2025-01-10"传成"2025年1月10日"、把城市名传成拼音、把数字传成字符串。

这类问题和训练数据强相关，通常无法完全通过提示词消除。我的做法是在函数入口统一做一层“参数清洗器”：

def clean_arguments(func_name, args): # 规则清洗：日期格式统一、城市名映射、枚举值校验 if func_name == "get_weather": args["date"] = normalize_date(args.get("date", "")) args["city"] = city_alias_map.get(args.get("city"), args.get("city")) return args

还有一个思路是放宽函数定义的类型约束。比如日期字段在schema里定义成string，但在description里给出严格的格式示例：“仅支持YYYY-MM-DD格式，例如2025-01-10，不要包含其他文字。”加上示例后，模型出错率会显著下降。

终极方案是让本地函数本身具有韧性：即使接到非标准格式的参数也能做容错解析，而不是直接抛异常。在真实项目中，我经常把参数解析做成多级回退，例如先按ISO格式parse，失败再正则提取数字。

5.3 上下文无限膨胀与循环死锁

Agent模式最大的隐患是多轮循环停不下来。模型可能一直调用同一个函数，哪怕结果已经拿到了。比如查天气功能，模型回答完“北京晴”之后，下一轮又生成了一个tool_calls去查上海天气，然后再下一轮又查广州——因为没有人告诉它“用户的问题已经回答完了”。

两种防守策略我很推荐。第一是轮次上限：就像我前面demo里for _ in range(5)那样，一旦超过最大轮次就强制终止，返回已生成的内容或一个兜底文案。第二是结果完整性检测：回填工具结果时，把函数执行状态（成功或失败）和关键返回值都作为文本传给模型，并加一句“如果你已经获得了回答用户问题所需的全部信息，请直接生成最终答复，不要继续调用工具”。这个系统提示在阻止循环上非常有效。

另外有个隐藏循环源：函数本身返回了不完整数据。比如get_orders_by_user分了页，第一页只返回10条，模型以为查完了，实际没有。这类问题需要函数设计者在返回结构里带上has_more字段，让模型有机会决定是否继续翻页。

5.4 兼容性与字段差异

不同大模型厂商对Function Calling的协议实现并非完全一致，字段名和交互逻辑常有出入。有的用functions而不是tools，有的返回function_call而不是tool_calls，有的不支持tool_choice: required。

如果你在项目中同时接入了多家模型，建议在中间层做一次“协议适配器”，把各家请求参数和返回字段统一成你自己的内部结构。不要写业务代码时直接引用厂商的字段名，否则换模型等于重写业务逻辑。

我自己常用的做法是：定义一个统一接口，内部根据厂商类型做请求转换，外部永远暴露一致的tools和message结构。适配层代码虽然啰嗦，但后续好处很大——模型升级、厂商替换、本地模型部署，都只改适配层，不碰业务代码。

5.5 成本与延迟优化技巧

Function Calling看似只多了几轮对话，实际token消耗比普通聊天高不少。函数定义文本每轮都要重发，工具执行结果也每轮都要回传，历史消息还在持续累积。

省成本的第一招是精简函数定义，把description中的废话去掉，保留最核心的触发条件。第二招是裁剪历史：多轮工具调用后，早期的函数返回数据对最终回答往往已无价值，可以把较早的tool消息截断，只保留摘要。第三招是让工具函数返回精简数据：比如查询订单，只返回id、金额、状态，不要把数据库整行都塞给模型。

延迟方面，如果函数本身要耗时几秒，建议用流式响应让用户先看到部分反馈。Function Calling和流式是兼容的，只是流式返回时tool_calls是分片到达的，需要在代码里做增量拼接，直到收到结束信号才能解析完整参数。这个细节我在第一次做流式工具调用时踩过坑，写出来提醒大家。

6. 安全边界与大实话

最后必须聊聊安全问题，这是Function Calling项目上线前一定要过的关卡。

Function Calling把大模型从“只会聊天的文本生成器”变成了“能够触达真实系统的手和脚”。这个能力越强，风险也越大。模型可能因提示词注入被引导调用危险函数，比如delete_user、transfer_money、send_email。所以在架构设计时，一定要把模型当作一个“不可信的外部输入源”来看待，而不是当作系统的一部分。

我的安全基线是三条：第一，任何不可逆操作必须加人工确认；第二，函数权限和用户权限分开管理，模型只有在你赋予的函数列表内选择的空间，函数内部再做二次校验；第三，所有函数执行都要有审计日志，谁在什么时候通过什么话术触发了什么操作，完整记录下来。

还有一点很少有人提：函数里的错误信息不要原样返回给模型。比如函数报错时把数据库异常堆栈传回去，模型可能会把它当成上下文向用户复述。正确的做法是，函数内部捕获异常、转成业务友好的错误描述，再传给模型。例如“查询失败，该用户不存在”和“查询失败，SQL执行异常，错误码1045”这两种返回内容，前者安全得多。

写到这里，我可以把话说得更透一点。Function Calling让AI变得强大，但强大的前提是“可控”。很多人第一次上手时被它的能力惊艳，真正做生产系统时才发现，大量工作不是让模型学会调用函数，而是让系统在模型犯错时依然稳定、安全、可审计。函数定义可以越写越熟练，Agent编排可以越来越花哨，但边界意识才是这个领域真正分高下的地方。工具是给AI用的，最后拍板的按钮还是得握在你手里。