2024 年我给一个客服系统接入 AI 助手,想让它能"动手干活"——不只是聊天,还能帮用户查订单、查物流、算运费。我用的是大模型的 Function Calling(函数调用)能力:把我写好的几个函数"告诉"模型,让它在需要的时候自己调。Demo 那天效果惊艳:用户问"我的订单 A2024 到哪了",AI 准确地查出了状态,产品经理当场鼓掌。可推广之后,各种诡异的问题接连冒出来。有时模型调函数时给的参数类型是错的——该传数字它传了一段文字,函数当场崩溃;有一次模型信誓旦旦地说要调用一个叫 get_logistics_detail 的函数,可我压根没写过这个函数,它是模型自己"想象"出来的;还有一次,模型陷入了一种诡异的状态,反复调用工具、调用工具、调用工具,就是不给最终答案,白白烧掉一大把 token;而最让我后背发凉的一次,是模型把一个用户问句里出现的订单号,直接拿去查了——那个订单根本不属于这个用户。我一开始以为是模型不够聪明,后来盯着请求日志看了很久才彻底想明白:我对 Function Calling 的理解从根上就错了。我以为"函数调用"是模型帮我把函数调用了,而真相是——模型从来没有、也不可能真正执行任何一个函数。它做的全部事情,只是输出一句"我建议你调用 X 函数、参数是 Y"。真正执行那个函数的,从头到尾都是我自己的代码。Function Calling 不是模型的一个魔法按钮,而是我和模型之间一来一回的协议,而这个协议里执行、校验、纠错、终止的每一步,责任都在我这边。那次之后我才认真把它从头搞明白。这篇文章就把它梳理一遍:为什么需要 Function Calling、它到底怎么工作、工具怎么定义、调用循环怎么转,以及把 AI 工具调用真正做稳要避开的那些坑。
问题背景
先把那次的现象和我的误判讲清楚,后面所有的设计都是冲着纠正这个误判去的。
现象:给客服 AI 接入 Function Calling 后,Demo 正常,推广后频繁出问题:模型给的函数参数类型错误导致函数崩溃、模型"幻觉"出一个根本不存在的函数名、模型反复调用工具陷入死循环烧 token、模型拿着一个不属于当前用户的订单号去查了数据。
我当时的错误认知:"Function Calling 就是模型帮我自动调用函数,我把函数告诉它,它需要时就会调,我等结果就行。"
真相:模型永远不会真正执行你的任何一个函数。它能做的,只是基于你给的"工具说明书",输出一个结构化的请求——"我想调用名为 X 的函数,参数是 Y"。这个请求可能是错的:函数名可能是它编的,参数可能类型不对、可能缺失、可能是恶意诱导出来的。真正去执行的、并且必须在执行前把这个请求当作不可信输入来校验的,是你的代码。Function Calling 是一个多轮往返的协议,模型负责"提议",你负责"决策、校验、执行、兜底"。
要把 AI 工具调用做稳,需要几块认知:
- 模型本身的能力边界在哪,为什么需要工具;
- Function Calling 的真实工作机制——模型"提议",你"执行";
- 工具怎么用 JSON Schema 定义,调用循环怎么一轮轮转;
- 为什么模型给的参数一个字都不能信;
- 死循环、并行调用、工具报错这些工程坑怎么处理。
一、为什么需要 Function Calling:模型的能力边界
先看清大模型不能做什么,才知道工具是来补什么的。
大模型很强,但它有两个清晰的边界。第一,它不知道实时的、私有的数据。它的知识停在训练截止那一刻,你公司数据库里"订单 A2024 现在的状态",它无从知晓。第二,它不擅长精确执行。它是个语言模型,做几位数的精确运算、严格的逻辑判断,并不可靠。下面这段代码,就是直接拿这两件它做不到的事去问它:
from openai import OpenAI
client = OpenAI()
# 反面教材:直接问模型一个需要"实时私有数据"和"精确计算"的问题。
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user",
"content": "订单 A2024 现在什么状态?商品价加运费一共多少?"}],
)
print(resp.choices[0].message.content)
# 问题:模型根本不知道"订单 A2024"是什么 —— 它不在训练数据里。
# 它也算不准两个具体数字的和。于是它会"一本正经地编":
# 编一个看起来很合理的订单状态,编一个总价。
# 模型缺的不是智力,是两样东西:实时/私有数据,和精确执行能力。
而这两样东西,恰恰是程序最擅长的:查数据库、调 API、做精确计算,这些代码做得又快又准。所以一个自然的想法就出现了:让模型负责它擅长的"理解意图、组织语言",让程序负责它擅长的"取数据、做计算",两者协作。
Function Calling 就是这个协作的标准接口。它让你能把一组函数"注册"给模型,模型在回答问题时,如果发现自己需要某个函数才能答,就会"提议"调用它。模型于是从一个"闭门造车的回答者",变成了一个"会指挥工具的协调者"——它不再硬编一个订单状态,而是会说:"这个问题我需要查订单,请帮我调用 get_order 函数。"
二、它到底怎么工作:模型只是"提议",不是"执行"
这一节是全文的地基,务必理解透:Function Calling 这个名字其实有点误导,因为模型从头到尾没有"调用"任何东西。
真实的流程是一个多轮对话。第一轮:你把用户的问题,连同一份"工具说明书"(有哪些函数、各自叫什么、要什么参数)一起发给模型。模型的回应有两种可能:要么它觉得自己能直接答,就返回一段文字;要么它觉得需要工具,就返回一个特殊的结构——tool_calls,里面写着"我想调用 get_order,参数是 {"order_id": "A2024"}"。
关键就在这里:这个 tool_calls 只是一个请求、一个提议。模型把它交给你,然后就停下了,它没有、也没有能力去真正执行 get_order。第二轮:轮到你的代码上场——你解析这个提议,真正地去调用你那个 get_order 函数,拿到结果(比如订单状态),再把这个结果作为一条新消息发回给模型。第三轮:模型这下拿到了它要的数据,就能组织出最终的回答了。
所以整件事的本质,是一场你和模型之间的"接力":模型提议 → 你执行 → 你回传结果 → 模型继续。模型负责"想",你负责"做"。把这个机制刻进脑子里,后面所有的坑——参数为什么不可信、为什么会死循环——你就都能想明白:因为"做"这一侧的所有责任,都在你身上。
三、定义工具:JSON Schema 是给模型的说明书
既然要把工具"说明书"发给模型,那这份说明书长什么样?它用的是 JSON Schema 格式——结构化地描述每个函数的名字、用途、以及它需要哪些参数、每个参数是什么类型。
这份 schema 极其重要,因为它是模型唯一能看到的关于你的函数的信息。模型不会读你的源码,它只读这份 schema。description 写得含糊,模型就会在不该调的时候调、或该调的时候不调;参数描述不清,模型就会传错参数。下面是一个工具定义:
# 工具定义:用 JSON Schema 告诉模型"有哪些函数、各自要什么参数"。
# 这段 schema 是模型唯一能看到的"说明书"—— 描述写不清,模型就用不对。
tools = [
{
"type": "function",
"function": {
"name": "get_order",
"description": "根据订单号查询订单的状态、商品价格和运费",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单号,形如 A2024",
},
},
"required": ["order_id"],
},
},
},
]
注意:这份 schema 描述的只是函数的"长相",函数真正的实现是另一回事——那是一段普通的、由你的程序执行的代码。我们还需要一张"函数名到真实函数"的对照表,这样模型说要调哪个名字,我们就能从表里找到对应的代码去执行:
# 工具的真实实现 —— 这才是真正干活的代码,由你的程序执行,不是模型。
def get_order(order_id: str) -> dict:
# 真实场景这里会查数据库;示例用一份固定数据代替
db = {"A2024": {"status": "已发货", "price": 199, "shipping": 12}}
if order_id not in db:
return {"error": f"订单 {order_id} 不存在"}
return db[order_id]
# 一张"函数名 -> 真实函数"的分发表:模型说调哪个,就从这里找对应代码
TOOL_REGISTRY = {
"get_order": get_order,
}
到这里,"说明书"(tools)和"真实代码"(TOOL_REGISTRY)就备齐了。前者发给模型让它知道能调什么,后者留在你手里负责真正执行。下一节,就是把这两者用一个循环串起来。
四、完整的调用循环:一来一回直到拿到答案
现在把"提议—执行—回传"这条接力跑起来。先看清模型"提议"时,它到底返回了个什么东西。
当模型决定要用工具,它返回的 message 里 content 是空的,取而代之的是一个 tool_calls 数组。每一项长这样:
# 模型"提议调用工具"时,返回的 message 结构(已简化)
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_order",
"arguments": "{\"order_id\": \"A2024\"}"
}
}
]
}
# 注意 arguments 是一个【字符串】,不是对象 —— 它是模型"写"出来的一段
# JSON 文本。所以你必须先 json.loads 它,而这段文本完全可能不合法。
看清这个结构里有两个要命的细节:第一,function.name 是模型填进去的一个字符串,它可以填任何东西,包括一个你根本没注册过的名字;第二,arguments 不是一个对象,而是模型当作文本生成出来的一段 JSON 字符串,它可能语法不合法、可能字段缺失、可能类型全错。先记住这两点,下一节全靠它。
而把整件事串起来的,是一个循环:发消息给模型 → 看它是返回答案还是返回 tool_calls → 如果是 tool_calls 就执行、把结果塞回对话历史、再发一轮 → 直到模型不再要工具、给出最终答案。这个循环必须有个硬上限,否则模型一旦抽风反复要工具,就会无限转下去:
def run_agent(user_message: str, max_iterations: int = 5):
messages = [{"role": "user", "content": user_message}]
# 硬上限:模型最多来回 max_iterations 轮,跑满就强制收尾
for _ in range(max_iterations):
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tools, # 每轮都把"说明书"带上
)
msg = resp.choices[0].message
messages.append(msg) # 模型这轮的回复(含 tool_calls)也要入历史
# 模型没要工具 —— 它直接给出了最终答案,循环结束
if not msg.tool_calls:
return msg.content
# 模型提议了若干工具调用:逐个执行,把结果作为新消息回传
for call in msg.tool_calls:
result = dispatch_tool(call.function.name,
call.function.arguments)
messages.append({
"role": "tool",
"tool_call_id": call.id, # 必须带:告诉模型这是哪次调用的结果
"content": json.dumps(result, ensure_ascii=False),
})
# 跑满还没出最终答案 —— 强制终止,绝不让它无限烧 token
return "抱歉,这个问题处理超时,请换个问法。"
这个循环就是 Function Calling 的"心脏"。注意两件容易漏的事:其一,模型每轮的回复(那条带 tool_calls 的 assistant 消息)必须也加进 messages,否则下一轮模型就"不记得"自己提过什么;其二,回传结果的 role 是 tool,而且必须带上 tool_call_id,模型靠它把结果和它当初的某次提议对上号。循环骨架有了,但里面那行 dispatch_tool 我一直没展开——它正是整个系统最危险的地方。
五、模型给的参数,一个字都不能信
这一节是开头那几个事故的真正答案。请先建立一个心智模型:模型返回的 tool_calls,本质上和用户在输入框里敲进来的文本是同一类东西——不可信的外部输入。
这听起来反直觉:模型不是"我们这边"的吗?不是。模型是个概率系统,它生成的函数名和参数,是它猜出来的最像那么回事的字符串,没有任何机制保证它合法、正确、安全。可下面这种写法,恰恰把模型的输出当成了可信的、确定的东西:
# 反面教材:拿到模型给的函数名和参数,直接信、直接用。
def dispatch_tool_unsafe(name: str, arguments: str):
func = TOOL_REGISTRY[name] # 雷 1:name 是模型编的,可能 KeyError
args = json.loads(arguments) # 雷 2:arguments 可能不是合法 JSON,崩
return func(**args) # 雷 3:参数类型/字段可能对不上签名,崩
# 三行代码埋了三颗雷,开头那些事故全在这里:
# 模型幻觉出 get_logistics_detail(雷 1)、参数类型给错(雷 3)……
正确的做法,是在模型的输出和你的真实函数之间,架一道校验闸机。每一项可能出错的地方都要被挡一次:函数名必须在注册表里、arguments 必须能解析成 JSON、解析出来的参数必须通过类型和字段校验。用 pydantic 给每个工具的参数定义一个 schema,校验这件事就变得很干净:
from pydantic import BaseModel, ValidationError
# 给每个工具的参数定义一个 schema,它就是模型输出进入你代码前的"闸机"
class GetOrderArgs(BaseModel):
order_id: str
TOOL_ARGS = {"get_order": GetOrderArgs}
def dispatch_tool(name: str, arguments: str):
# 闸机一:函数名必须在注册表里 —— 挡掉模型幻觉出来的函数名
if name not in TOOL_REGISTRY:
return {"error": f"未知函数 {name},无法调用"}
# 闸机二:arguments 必须能解析成合法 JSON
try:
raw = json.loads(arguments)
except json.JSONDecodeError:
return {"error": "函数参数不是合法 JSON"}
# 闸机三:参数必须通过 schema 校验 —— 类型对、必填字段不缺
try:
args = TOOL_ARGS[name](**raw)
except ValidationError as e:
return {"error": f"参数校验失败: {e}"}
# 三道闸机都过了,才真正执行
return TOOL_REGISTRY[name](**args.model_dump())
注意一个关键设计:校验失败时,我没有抛异常、也没有让程序崩,而是 return 了一个 {"error": ...}。这个 error 会作为"工具结果"回传给模型,模型看到"参数校验失败"往往能自己纠正,下一轮换个正确的参数重试。校验,不只是为了不崩,更是给了模型一个改错的机会。
但还有一类校验,pydantic 管不了——权限。开头那个"查了不属于该用户的订单",参数 order_id 类型完全正确、订单也真实存在,它就是过得了上面三道闸机。问题在于:参数合法,不等于当前用户有权访问它。模型只是从用户的问句里抓了个订单号,它既不知道、也没义务知道这个订单归谁。归属校验,必须由你的代码、用会话里那个可信的当前用户身份来做:
# 业务级校验:参数合法 ≠ 有权访问。current_user_id 来自你的会话/鉴权
# 系统,是可信的;绝不能让模型从对话内容里"猜"出当前用户是谁。
def get_order_secure(order_id: str, current_user_id: str) -> dict:
db = {"A2024": {"owner": "u_001", "status": "已发货",
"price": 199, "shipping": 12}}
order = db.get(order_id)
if order is None:
return {"error": f"订单 {order_id} 不存在"}
# 关键一步:校验这张订单到底归不归当前用户,越权就拒绝
if order["owner"] != current_user_id:
return {"error": "无权查看该订单"}
return {k: v for k, v in order.items() if k != "owner"}
把这一节总结成一句话:凡是模型给的,函数名、参数、还有它字里行间暗示的"身份",全都不可信。函数名要查注册表,参数要过 schema,权限要用你自己掌握的会话身份去判。模型负责"想调什么",而"能不能调、调得对不对、有没有资格调",每一道都是你的代码的责任。
六、工程坑:工具报错、死循环、并行调用
校验做对了,还有几个把 AI 工具调用真正做稳绕不开的工程坑。
坑 1:工具函数自己会报错,异常不能炸穿调用循环。就算参数全部合法,你的真实函数在执行时照样可能出事——数据库超时、下游服务返回 500、第三方 API 限流。如果让这个异常直接抛出来,它会把整个 run_agent 循环中断,用户得到的是一个冷冰冰的 500。正确的做法和参数校验一样:把异常包装成一条工具结果回传给模型,让模型自己决定是换个参数重试,还是如实告诉用户"这个功能暂时不可用":
# 工程实践:工具函数执行时自己也会抛异常。这些异常绝不能直接抛出、
# 中断整个 agent —— 要包装成一条"工具结果"喂回模型,由模型决定下一步。
def dispatch_tool_safe(name: str, arguments: str):
try:
return dispatch_tool(name, arguments)
except Exception as e:
# 把异常变成结构化结果回传,而不是让它炸穿调用循环
return {"error": f"工具执行出错: {type(e).__name__}: {e}"}
坑 2:模型会陷入工具调用死循环。开头那个"反复调用工具就是不给答案",是个真实且常见的现象。诱因通常有两个:一是工具一直返回 error,模型不死心反复重试;二是你给的工具描述有歧义,模型在两个工具之间反复横跳。两道防线缺一不可:其一,就是第四节那个 max_iterations 硬上限,这是兜底,保证再坏也会停;其二,是让每次工具结果都带来实质进展——error 信息要写得具体到模型能据此改对(写"参数校验失败:order_id 字段缺失"而不是干巴巴一个"失败"),工具的 description 要清晰到模型不会选错。兜底防失控,清晰防发生。
坑 3:模型可能一轮提议多个工具调用。现代模型支持并行工具调用——用户问"订单 A2024 和 B2025 分别到哪了",模型可能在一个 tool_calls 数组里塞进两次 get_order。第四节的循环里那个 for call in msg.tool_calls 正是为此而写:你必须把这一轮的每一个 tool_call 都执行掉、并且把每一条结果都按对应的 tool_call_id 回传。少回传一条,模型就会因为"有一次提议没收到结果"而困惑甚至报错。记住:一轮里有几个 tool_call,就必须有几条 role: tool 的结果消息。
下面这张图,把一次完整的 Function Calling 调用循环串起来:
关键概念速查
| 概念 / 手段 | 说明 |
|---|---|
| Function Calling | 模型只输出"调用提议",真正执行函数的始终是你的代码 |
| tool_calls | 模型返回的结构化提议:含函数名与 arguments(一段 JSON 字符串) |
| JSON Schema | 工具的"说明书",模型唯一能看到的函数信息,描述写清才调得对 |
| TOOL_REGISTRY | 函数名到真实函数的分发表,执行时按模型给的名字查找 |
| 调用循环 | 模型提议→你执行→回传结果→模型继续,直到不再返回 tool_calls |
| max_iterations | 给循环设硬上限,防止模型反复调工具陷入死循环、无限烧 token |
| 参数校验 | 函数名、参数都不可信,用注册表 + schema(如 Pydantic)做入口闸机 |
| 越权校验 | 参数合法不等于有权访问,要用会话里可信的当前用户身份校验归属 |
| tool_call_id | 回传结果时必须带上,模型靠它把结果和当初的提议对上号 |
| 错误回传 | 校验失败、工具报错都包装成 error 结果喂回模型,而非抛异常中断 |
避坑清单
- 模型永远不会真正执行你的函数,它只输出"我建议调用 X、参数 Y"的提议,执行的责任全在你的代码。
- 大模型的两个能力边界——不知道实时/私有数据、不擅长精确执行——正是工具要补的;Function Calling 是这个协作的标准接口。
- 工具用 JSON Schema 定义,它是模型唯一能看到的函数信息;description 和参数描述写含糊,模型就会调错或传错参数。
- tool_calls 里的 arguments 是一段模型"写"出来的 JSON 字符串,可能语法非法、字段缺失、类型全错。
- 调用循环必须设 max_iterations 硬上限,否则模型反复要工具会无限转下去、白烧 token。
- 模型每轮带 tool_calls 的回复要加进 messages,结果回传用 role=tool 且必须带 tool_call_id,否则模型对不上号。
- 模型给的函数名不可信,先查 TOOL_REGISTRY 挡掉幻觉出来的函数;参数不可信,用 Pydantic 等 schema 校验类型与必填字段。
- 参数合法不等于有权访问,越权校验要用会话里可信的 current_user 身份做,绝不能让模型从对话里猜身份。
- 校验失败、工具执行报错都要包装成 {"error": ...} 回传给模型,既不崩,又给模型一个自我纠错的机会。
- 模型一轮可能并行提议多个 tool_call,必须逐个执行、逐条按 tool_call_id 回传,少一条模型就会困惑或报错。
总结
回头看那次客服 AI 接入 Function Calling 后接二连三的事故,最该记住的不是某一段校验代码,而是我动手前那个想当然的判断——"Function Calling 就是模型帮我把函数调用了"。这句话错在它把模型当成了一个会替你干活的执行者。可模型从头到尾只做一件事:输出文本。它输出的 tool_calls,看起来像一次函数调用,本质上还是一段它猜出来的文本——猜得像不像那么回事,和它对不对、合不合法、安不安全,是两件完全不同的事。
所以做 AI 工具调用,真正的工程量根本不在"让模型会调工具"。把 tools 传进去、模型就会返回 tool_calls,Demo 里它也确实能准确地查出订单状态。真正的工程量在模型提议之后:它编了个不存在的函数名你怎么挡、它给的参数类型错了你怎么校验、它拿了个不属于当前用户的订单号你怎么拦、它陷入死循环你怎么终止、工具自己报错了你怎么不让它炸穿整个流程。这篇文章的几节,其实就是顺着一次工具调用的生命周期展开的:先想清楚为什么需要工具、它到底怎么工作;再看工具怎么定义、循环怎么转;然后是那个最核心的认知——模型的输出全都不可信;最后是报错、死循环、并行调用这几个把它真正做稳的工程细节。
你会发现,这套思路和我们处理任何"外部输入"的工程经验是完全相通的。用户表单提交的数据,我们从不直接信,要校验;第三方 API 返回的结果,我们从不假设它一定合法,要做防御;上游传来的参数,我们总要先验明正身再用。Function Calling 只是把这种"不信任外部输入"的纪律,用在了一个新的、容易让人放松警惕的输入源上——大模型。它聪明、它语气笃定、它看起来站在你这边,但它生成的每一个函数名、每一个参数,在进入你的代码之前,都和一个匿名用户敲进输入框的字符串享受同等待遇:先校验,再放行。
最后想说,Function Calling 做没做稳,差距永远不会在 Demo 里暴露——Demo 里你问的都是设计好的问题,模型不会幻觉、参数不会错、也不会有人去查别人的订单。它只在真实用户五花八门的提问、真实的模型抽风、真实的下游故障面前才显形。那时候它会用最难堪的方式给你结账:一个编造出来的函数名让程序崩在生产环境,一次越权查询让用户看到了别人的隐私。所以别等产品经理拿着事故报告来找你,在你把第一个函数 tools 注册给模型的时候就该想清楚:它要是编个函数名我挡得住吗?它参数给错了我校验了吗?它查的东西用户有权看吗?它转不停了我能让它停吗?这几个问题都有了答案,你的 AI 助手才不只是 Demo 里那个赢得掌声的惊艳演示,而是一个能在真实世界里既能干活、又不闯祸的可靠系统。
—— 别看了 · 2026