以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。
模型本身只会生成 token。所谓 Function Calling,是把“调用哪个工具、传什么参数”编码成一段结构化文本,让运行时能够解析并执行。模型没有真的“调用”函数;它只是生成了一个名字和一组参数,真正执行的是外部代码。
这个区分很重要,因为它决定了能力边界:工具调用能力是生成能力加约束解码加运行时校验的组合,不是模型内部多了一个执行器。 模型可能生成不存在的工具名、漏掉必填参数、传入多余字段,甚至在参数里编造事实。运行时必须把这些问题挡在执行之前。
训练路径:示范轨迹教会模型“何时调用”
Function Calling 的训练通常仍以监督微调为主。示范数据不是普通问答,而是带有工具调用的完整轨迹:
- 系统提示里给出工具清单、用途和参数 Schema。
- 用户提出请求。
- 模型输出一个结构化调用:工具名 + 参数。
- 运行时执行工具,把结果回填到上下文。
- 模型基于结果继续生成,直到给出最终回答。
训练信号来自第 3 步和第 5 步:模型要学会在什么条件下发起调用、选择哪个工具、参数如何对齐 Schema,以及拿到结果后如何组织回答。只训练第 3 步,模型会“会调用但不会用结果”;只训练第 5 步,模型会“会总结但不会发起”。
示范数据的质量比数量更关键。一个常见的坏数据模式是:所有示范都只包含一次调用,且都成功。模型于是学到“调用一次就会成功”,遇到工具报错、参数缺失、需要重试时没有行为可模仿。
推理路径:生成、校验、执行、回填
推理时的控制流可以写成四步:
| 步骤 | 谁负责 | 失败后果 |
|---|---|---|
| 生成调用 | 模型 | 选错工具、漏参数、编造参数 |
| 校验 | 运行时 | 非法调用进入执行,产生副作用 |
| 执行 | 工具服务 | 超时、权限错误、部分成功 |
| 回填 | 运行时 + 模型 | 模型误读结果或忽略错误 |
四步里,只有第一步是模型能力,后三步都是架构责任。很多“工具调用不稳定”的问题,其实不是模型不会选,而是运行时没有校验、没有超时、没有把错误结构化地回填给模型。
模型看到的工具描述也会显著影响选择。工具名、描述、参数说明和示例共同构成一个“检索索引”;描述写得含糊,模型就只能靠名字猜。把工具描述当成 API 文档来写,是提升调用准确率最便宜的手段之一。
最小实验:关键词选择与参数校验
下面的实验把工具选择简化成关键词匹配,把参数校验简化成必填/多余字段检查。它不是真实模型,但把三个关键量暴露出来:选不选得中、缺不缺参数、能不能修复。
# file: agp_lab/function_calling.py | write
# tier: 3
# verify: python3 -m unittest tests.test_function_calling
"""工具选择与参数校验:Function Calling 的最小推理路径。"""
from __future__ import annotations
from dataclasses import dataclass
@dataclass(frozen=True)
class Tool:
name: str
keywords: tuple[str, ...]
required: tuple[str, ...]
optional: tuple[str, ...] = ()
TOOLS = (
Tool("weather", ("weather", "rain", "temperature"), ("city",), ("unit",)),
Tool("search", ("search", "find", "document"), ("query",)),
Tool("calculator", ("calculate", "sum", "average"), ("expression",)),
)
def score_tool(query: str, tool: Tool) -> int:
lowered = query.lower()
return sum(1 for keyword in tool.keywords if keyword in lowered)
def select_tool(query: str, tools: tuple[Tool, ...] = TOOLS) -> str | None:
scored = [(score_tool(query, tool), tool.name) for tool in tools]
best = max(scored, default=(0, ""))
if best[0] == 0:
return None
return best[1]
def missing_args(tool: Tool, args: dict[str, object]) -> list[str]:
return [name for name in tool.required if name not in args]
def extra_args(tool: Tool, args: dict[str, object]) -> list[str]:
allowed = set(tool.required) | set(tool.optional)
return sorted(set(args) - allowed)
def repair_args(tool: Tool, args: dict[str, object],
defaults: dict[str, object] | None = None) -> dict[str, object]:
defaults = defaults or {}
repaired = dict(args)
for name in tool.required:
if name not in repaired and name in defaults:
repaired[name] = defaults[name]
for name in tool.optional:
repaired.setdefault(name, defaults.get(name))
return repaired
def validate_call(tool: Tool, args: dict[str, object]) -> dict[str, object]:
missing = missing_args(tool, args)
extra = extra_args(tool, args)
return {
"ok": not missing and not extra,
"missing": missing,
"extra": extra,
}
if __name__ == "__main__":
for query in ("weather in Shanghai", "search the manual", "what is 2+2"):
print(f"query={query!r} tool={select_tool(query)}")
weather = TOOLS[0]
print("valid:", validate_call(weather, {"city": "Shanghai"}))
print("missing:", validate_call(weather, {"unit": "c"}))
print("extra:", validate_call(weather, {"city": "Shanghai", "date": "tomorrow"}))
print("repaired:", repair_args(weather, {"unit": "c"}, {"city": "Shanghai"}))
运行:
cd private/labs/agp-lab
python3 -m agp_lab.function_calling
输出:
query='weather in Shanghai' tool=weather
query='search the manual' tool=search
query='what is 2+2' tool=None
valid: {'ok': True, 'missing': [], 'extra': []}
missing: {'ok': False, 'missing': ['city'], 'extra': []}
extra: {'ok': False, 'missing': [], 'extra': ['date']}
repaired: {'unit': 'c', 'city': 'Shanghai'}
前两行说明选择可以工作:查询里出现工具的关键词,就选中对应工具。第三行是更值得注意的情况:what is 2+2 没有命中 calculator 的关键词,返回 None。这不是说模型“不会算术”,而是说工具描述和用户表达之间没有建立映射。真实系统里,这类查询可能被路由到通用回答,也可能被误选成 search;两种都比“明确不调用”更危险。
后三行展示参数校验的三种状态:合法、缺必填字段、带多余字段。valid 只说明结构合法,不说明参数内容正确;city 是否存在、unit 是否支持,需要工具服务自己校验。repaired 展示了运行时的修复策略:用默认值补齐必填字段。修复必须显式记录,不能悄悄发生,否则审计时无法区分“模型填对了”和“系统替它填了”。
这个实验的边界也要说清楚:关键词匹配没有语义理解,what is 2+2 失败是设计使然。真实模型靠语义选择,但同样会遇到“工具描述没覆盖用户说法”的问题。实验把这个问题从模型能力里剥离出来,方便单独观察。
三个失败点
| 失败点 | 典型表现 | 防线 |
|---|---|---|
| 选择 | 选了不该选的工具,或该选时不选 | 工具描述、候选排序、选择评测 |
| 参数 | 漏必填、类型错、编造值 | Schema 校验、默认值、二次确认 |
| 结果解释 | 工具报错但模型说成功 | 结构化错误、外部验证、状态机 |
第三个失败点最容易被低估。工具返回 {"error": "timeout"},模型可能在总结时写成“已经完成,但有一点延迟”。这不是模型故意撒谎,而是它把“有返回”当成了“成功”。运行时必须把成功/失败编码成模型无法混淆的结构,并在关键动作上要求外部验证。
架构含义
Function Calling 对架构有四个直接约束:
- 工具清单要可检索。 名称、描述、参数说明和示例都要为“被选中”服务,而不是只为人阅读。
- 校验必须在执行前。 Schema、权限、参数范围、幂等键,任何一项缺失都可能把错误调用变成副作用。
- 结果要结构化回填。 成功、失败、部分成功、可重试错误,应该有明确的字段,而不是一段自然语言。
- 关键调用要二次确认。 不可逆或高风险的调用,不能只依赖模型的选择;需要审批或 dry-run。
第 2 条是底线。模型生成的是“建议调用”,运行时才是“决定执行”。把两者混在一起,等于把安全责任交给了一个概率模型。
架构判据
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 工具描述完整 | 名称、用途、参数、示例齐全 | 只有函数名 |
| 调用前校验 | Schema + 权限 + 范围检查 | 模型输出直接执行 |
| 错误可区分 | 超时、拒绝、部分成功有独立状态 | 统一返回“失败” |
| 修复有记录 | 默认值与补全都进入审计 | 静默补参数 |
| 选择有评测 | 按工具、查询类型分层统计 | 只看总成功率 |
这些判据里,“调用前校验”和“修复有记录”是一对。只校验不记录,出了问题无法归因;只记录不校验,错误照样会执行。两者必须同时存在。
工具描述怎么写
一个可用的工具描述至少包含四部分:
- 做什么:一句话说明能力边界,避免和相邻工具混淆。
- 什么时候用:给出触发条件和不适用条件。
- 参数含义:每个字段的类型、范围、默认值和示例。
- 失败语义:哪些错误可重试,哪些需要人工处理。
把“什么时候用”写清楚,往往比增加工具数量更能提升选择准确率。工具越多,候选越相似,描述的重要性越高。
一次调用的完整生命周期
把一次工具调用展开,至少有八个状态:
- 识别意图:用户是否在请求一个需要工具的动作。
- 候选生成:从工具清单里筛出可能相关的几个。
- 选择:确定一个工具,或在多个工具间澄清。
- 参数生成:按 Schema 生成参数。
- 校验:类型、必填、范围、权限、幂等键。
- 执行:调用工具,处理超时与部分成功。
- 回填:把结构化结果放回上下文。
- 收口:判断任务是否完成,是否需要重试或升级。
大多数团队只监控第 3 步和第 6 步,因为这两步最容易看到错误。但第 5 步和第 7 步才是副作用和误判的主要来源:校验缺失会把错误调用变成真实操作,回填不清会让模型把失败当成功。
工具数量增多时怎么办
工具从 3 个增长到 30 个,选择难度不是线性增加的。候选越多,描述越容易重叠,模型越容易选一个“看起来差不多”的工具。可用的策略有三类:
| 策略 | 做法 | 代价 |
|---|---|---|
| 分层路由 | 先选类别,再选具体工具 | 多一次模型调用 |
| 检索候选 | 用查询检索工具描述,只给前 k 个 | 检索漏召回 |
| 合并工具 | 把相似职责合并成一个带动作参数的工具 | 参数复杂度上升 |
没有一种策略适合所有规模。工具少时,全量给出最简单;工具多时,分层或检索更稳;职责高度重叠时,合并往往比继续加描述更有效。
小结
- Function Calling 是受约束的结构化生成,不是模型内部的函数执行器。
- 训练靠示范轨迹:何时调用、调用哪个、参数怎么填、结果怎么用;只覆盖成功路径的数据会教出脆弱策略。
- 推理路径分四步:生成、校验、执行、回填;只有第一步是模型能力,后三步是架构责任。
- 三个失败点是选择、参数和结果解释;结果解释最容易被低估。
- 调用前必须校验 Schema、权限、范围和幂等性;修复和默认值必须进入审计。
- 工具描述是选择准确率的一部分,应按 API 文档标准来写。
阅读导航:上一节:5.3 对齐给了什么、没给什么 · 下一节:6.2 Schema、约束解码与结构化输出 。
常见错误与边界
- 把模型输出当执行指令。 模型生成的是调用建议;校验、权限和幂等必须在运行时完成。
- 只训练成功轨迹。 没有错误恢复示范,模型遇到超时或参数缺失时没有可模仿的行为。
- 工具描述只写名字。 描述是选择索引;缺少用途和触发条件会让相邻工具互相混淆。
- 静默补参数。 默认值修复必须记录,否则无法区分模型能力和系统兜底。
- 把有返回当成功。 工具错误需要结构化回填,关键动作还要外部验证。
- 工具越多越好。 候选越多,选择越难;应合并职责重叠的工具,并做分层路由。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。