377 lines
15 KiB
Markdown
377 lines
15 KiB
Markdown
# Function Call 是什么？LLM 如何学会使用工具
|
||
|
||
> 本文以 [OpenClaw](https://github.com/openclaw/openclaw) 开源源码为例（基于 2026.6.2 版本），结合实际代码说明 Function Call 的工作原理。涉及源码路径均可在仓库中直接查阅。
|
||
|
||
如果你用过 ChatGPT 的联网功能，或者让 AI 帮你查股票、操作文件，你已经在使用 Function Call 的成果了。但它背后是怎么运作的？模型是怎么"调用"工具的？本文从头说清楚。
|
||
|
||
---
|
||
|
||
## 从一个问题开始
|
||
|
||
> "今天北京天气怎么样？"
|
||
|
||
把这个问题丢给 LLM，它大概率会回答：
|
||
|
||
> "抱歉，我的训练数据有截止日期，无法获取实时天气信息。"
|
||
|
||
这暴露了 LLM 的本质局限：**它只能生成文本，没有任何与外部世界交互的能力**。它不能查数据库、不能调 API、不能执行代码——所有"知识"都封存在训练时的权重里。
|
||
|
||
Function Call（也叫 Tool Use）就是为了解决这个问题而生的。
|
||
|
||
---
|
||
|
||
## Function Call 是什么
|
||
|
||
一句话：**让开发者提前告诉模型"有哪些工具可以用"，模型在需要时决定调用哪个工具、传什么参数，再由代码来真正执行它。**
|
||
|
||
有一个关键细节值得提前说清楚：**模型本身不执行任何工具**。它只是输出一段结构化的"调用请求"，真正的执行发生在你的代码里。这个区别很重要，后面会反复提到。
|
||
|
||
---
|
||
|
||
## 一个完整的例子
|
||
|
||
还是那个天气问题，看看有了 Function Call 之后发生了什么。
|
||
|
||
**第一步：开发者注册工具**
|
||
|
||
在调用 LLM 之前，把可用的工具告诉模型：
|
||
|
||
```json
|
||
{
|
||
"name": "get_weather",
|
||
"description": "获取指定城市的实时天气",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"location": { "type": "string", "description": "城市名称" }
|
||
},
|
||
"required": ["location"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**第二步：用户提问，模型决定调用工具**
|
||
|
||
模型收到"北京今天天气怎么样"后，意识到自己没有实时数据，但有 `get_weather` 工具可以用。于是它不直接回答，而是输出一个调用请求：
|
||
|
||
```json
|
||
{
|
||
"type": "tool_use",
|
||
"name": "get_weather",
|
||
"input": { "location": "北京" }
|
||
}
|
||
```
|
||
|
||
**第三步：代码执行工具，结果还给模型**
|
||
|
||
你的程序接收到这个请求，真正去调天气 API，拿到结果后告诉模型：
|
||
|
||
```json
|
||
{
|
||
"type": "tool_result",
|
||
"content": "北京今天晴，气温 28℃，东南风 3 级"
|
||
}
|
||
```
|
||
|
||
**第四步：模型拿到结果，给出最终回答**
|
||
|
||
> "北京今天天气不错，晴天，气温 28℃，东南风 3 级，适合出门。"
|
||
|
||
整个过程对用户是透明的，感觉就像模型"知道"天气一样。
|
||
|
||
---
|
||
|
||
## 工作原理
|
||
|
||
理解了"是什么"，再看"怎么做到的"。
|
||
|
||
### 工具的定义与注册
|
||
|
||
在 OpenClaw 里，一个工具用 TypeBox schema 描述参数，并提供一个 `execute` 函数负责实际执行（`packages/agent-core/src/types.ts`）：
|
||
|
||
```ts
|
||
const weatherTool: AgentTool = {
|
||
name: "get_weather",
|
||
label: "获取天气",
|
||
description: "获取指定城市的实时天气信息",
|
||
parameters: Type.Object({
|
||
location: Type.String({ description: "城市名称，如「北京」" }),
|
||
}),
|
||
execute: async (toolCallId, args) => {
|
||
const data = await fetchWeatherApi(args.location);
|
||
return { content: [{ type: "text", text: data }] };
|
||
},
|
||
};
|
||
```
|
||
|
||
三个核心字段：`name` 是模型调用时用的名字，`description` 是**模型决定"要不要用它"的唯一依据**，`parameters` 是模型生成参数时要遵守的 JSON Schema。
|
||
|
||
工具注册到 `AgentContext.tools` 后，每次请求 LLM 前经过 provider 的 `convertTools()` 转换，写入请求 body 的 `tools` 字段。
|
||
|
||
### 各家 API 的格式差异
|
||
|
||
不同厂商的格式不统一，是接入多个 provider 时最头疼的地方：
|
||
|
||
| | 工具声明字段 | 调用响应格式 | 结果角色 |
|
||
|---|---|---|---|
|
||
| **Anthropic** | `input_schema` | `{ type: "tool_use", input: {...} }` | `tool_result`（role: user） |
|
||
| **OpenAI** | `parameters` | `{ function: { arguments: "字符串" } }` | role: `tool` |
|
||
| **Google** | `parametersJsonSchema` | `{ functionCall: { args: {...} } }` | `functionResponse` |
|
||
| **Mistral** | `parameters` | 同 OpenAI，但字段名 camelCase | role: `tool` |
|
||
|
||
几个容易踩的坑：
|
||
|
||
- **OpenAI 的 `arguments` 是字符串**，不是对象，需要 `JSON.parse()` 才能用
|
||
- **Anthropic 的工具结果 role 是 `user`**，不是独立角色，多个工具结果会合并进同一条 user 消息
|
||
- **Google 不保证 tool call 有稳定 id**，需要在缺失时自动生成
|
||
|
||
### 完整请求体长什么样
|
||
|
||
把上面这些拼在一起，实际发给 Anthropic 的请求体是这样的（`src/llm/providers/anthropic.ts`）：
|
||
|
||
```json
|
||
{
|
||
"model": "claude-sonnet-4-6",
|
||
"max_tokens": 8096,
|
||
"stream": true,
|
||
"system": [
|
||
{
|
||
"type": "text",
|
||
"text": "You are a helpful assistant...",
|
||
"cache_control": { "type": "ephemeral" }
|
||
}
|
||
],
|
||
"messages": [
|
||
{ "role": "user", "content": "北京今天天气怎么样？" }
|
||
],
|
||
"tools": [
|
||
{
|
||
"name": "get_weather",
|
||
"description": "获取指定城市的实时天气信息",
|
||
"input_schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"location": { "type": "string", "description": "城市名称" }
|
||
},
|
||
"required": ["location"]
|
||
},
|
||
"cache_control": { "type": "ephemeral" }
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
注意 `cache_control` 只加在 tools 数组的**最后一个工具**上——这是 Anthropic 的 prompt cache 标记方式，缓存整个 tools 块，下次相同前缀的请求直接命中。
|
||
|
||
### Provider 返回体与 transcript 拼接
|
||
|
||
请求发出后，Anthropic 以 SSE 流式返回。一次含 tool call 的响应，事件序列大致如下：
|
||
|
||
```
|
||
// 1. 消息开始，返回 token 用量（含 prompt cache 命中数）
|
||
event: message_start
|
||
data: { "message": { "id": "msg_01xxx", "usage": { "input_tokens": 312, "cache_read_input_tokens": 280 } } }
|
||
|
||
// 2. 文本块流式输出
|
||
event: content_block_start → data: { "index": 0, "content_block": { "type": "text" } }
|
||
event: content_block_delta → data: { "index": 0, "delta": { "type": "text_delta", "text": "我来查一下。" } }
|
||
event: content_block_stop → data: { "index": 0 }
|
||
|
||
// 3. tool_use 块开始（携带 id 和 name，input 为空）
|
||
event: content_block_start
|
||
data: { "index": 1, "content_block": { "type": "tool_use", "id": "toolu_01xxx", "name": "get_weather", "input": {} } }
|
||
|
||
// 4. 参数以 JSON 字符串碎片流式输出，需要本地拼接
|
||
event: content_block_delta → data: { "index": 1, "delta": { "type": "input_json_delta", "partial_json": "{\"loc" } }
|
||
event: content_block_delta → data: { "index": 1, "delta": { "type": "input_json_delta", "partial_json": "ation\": \"北京\"}" } }
|
||
event: content_block_stop → data: { "index": 1 }
|
||
|
||
// 5. 消息结束，stop_reason 说明停止原因
|
||
event: message_delta → data: { "delta": { "stop_reason": "tool_use" }, "usage": { "output_tokens": 42 } }
|
||
event: message_stop
|
||
```
|
||
|
||
三个值得注意的细节：
|
||
|
||
- **tool 参数是字符串碎片**，需要在本地逐片拼接后解析，解析失败就暂时返回 `{}`，等待更多碎片
|
||
- **`stop_reason: "tool_use"`** 告诉框架这轮因调工具而停止，agent loop 据此进入执行流程
|
||
- **`cache_read_input_tokens: 280`** 说明 system + tools 部分命中了 prompt cache，跳过了 prefill 计算
|
||
|
||
工具执行完毕后，结果带着原始的 `tool_use_id` 写回 transcript，下一轮整段重发给 LLM：
|
||
|
||
```json
|
||
[
|
||
{ "role": "user", "content": "北京今天天气怎么样？" },
|
||
{
|
||
"role": "assistant",
|
||
"content": [
|
||
{ "type": "text", "text": "我来查一下。" },
|
||
{ "type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": { "location": "北京" } }
|
||
]
|
||
},
|
||
{
|
||
"role": "user",
|
||
"content": [
|
||
{
|
||
"type": "tool_result",
|
||
"tool_use_id": "toolu_01",
|
||
"content": [{ "type": "text", "text": "北京今天晴，28℃，东南风 3 级" }],
|
||
"is_error": false
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
`tool_use_id` 的作用是让模型把"这个结果"和"那次调用"对应起来——一次响应里可能有多个 tool call，每个 result 都要通过 id 说明自己是哪次调用的答复。
|
||
|
||
### 模型实际"看到"的是什么
|
||
|
||
API 接收到结构化 JSON 后，服务端会把它展平成一段带特殊 token 的连续文本序列，才是真正喂进 transformer 的内容。各家格式没有完整公开，但大致规律如下。
|
||
|
||
**Anthropic**：tools 被序列化成 XML 追加在 system 末尾，含 tool call 的完整对话在 token 层面长这样：
|
||
|
||
```
|
||
[SYSTEM]
|
||
You are a helpful assistant...
|
||
<tools><tool_description>...</tool_description></tools>
|
||
[/SYSTEM]
|
||
|
||
[HUMAN]北京今天天气怎么样？[/HUMAN]
|
||
|
||
[ASSISTANT]我来查一下。
|
||
<tool_use>{"name": "get_weather", "input": {"location": "北京"}}</tool_use>
|
||
[/ASSISTANT] ← 模型生成到这里停止
|
||
|
||
[HUMAN]
|
||
<tool_result tool_use_id="toolu_01">北京今天晴，28℃，东南风 3 级</tool_result>
|
||
[/HUMAN]
|
||
|
||
[ASSISTANT] ← 服务端追加，模型从这里继续生成
|
||
```
|
||
|
||
**OpenAI**：使用 ChatML 格式（`<|im_start|>` / `<|im_end|>`），tools 序列化为类 JSON 文本追加进 system，tool result 作为 `tool` 角色注入。
|
||
|
||
从模型视角看，它每次看到的都是一段完整历史，**完全不知道中间发生过"执行工具"这件事**——工具执行是框架层的行为，对模型透明。
|
||
|
||
这也解释了两件事：**`description` 写得好不好直接影响模型判断**（它就是模型读到的那段文字）；以及对话越长首 token 延迟越高（每次都要从头 prefill 整段历史），prompt cache 缓存不变的前缀正是为了解决这个问题。
|
||
|
||
### Agent Loop 与执行调度
|
||
|
||
真实场景中，模型往往不是调一次工具就结束，而是经历多轮。OpenClaw 的 agent loop 核心是一个双层循环（`packages/agent-core/src/agent-loop.ts`）：
|
||
|
||
```ts
|
||
while (true) { // 外层：等待用户追加消息
|
||
let hasMoreToolCalls = true;
|
||
|
||
while (hasMoreToolCalls) { // 内层：处理 tool call 批次
|
||
const message = await streamAssistantResponse(context);
|
||
|
||
const toolCalls = message.content.filter(c => c.type === "toolCall");
|
||
if (toolCalls.length === 0) {
|
||
hasMoreToolCalls = false; // 没有 tool call，本轮结束
|
||
break;
|
||
}
|
||
|
||
const results = await executeToolCalls(toolCalls);
|
||
context.messages.push(...results); // 带着结果进入下一轮请求
|
||
}
|
||
}
|
||
```
|
||
|
||
模型可以**一次输出多个 tool call**，框架默认并行执行以节省时间。比如"帮我查北京和上海的天气"，模型同时发出两个 `get_weather` 调用，结果都回来后再统一回答。
|
||
|
||
**并行还是串行，由开发者在定义工具时决定，不是 LLM 控制的：**
|
||
|
||
```ts
|
||
const weatherTool: AgentTool = {
|
||
name: "get_weather",
|
||
executionMode: "parallel", // 查询类，并发没问题
|
||
};
|
||
|
||
const writeFileTool: AgentTool = {
|
||
name: "write_file",
|
||
executionMode: "sequential", // 有副作用，强制串行
|
||
};
|
||
```
|
||
|
||
框架降级规则：同一批里**只要有一个**工具标了 `sequential`，整批立即降为串行。
|
||
|
||
| 工具类型 | 推荐模式 | 原因 |
|
||
|---|---|---|
|
||
| 查询、读取、幂等操作 | `parallel` | 并发安全，节省时间 |
|
||
| 写文件、发消息、调支付 | `sequential` | 有副作用，避免竞态 |
|
||
| 有依赖关系的操作 | LLM 跨轮次自然处理 | 模型看不到上一步结果就不会发下一步调用 |
|
||
|
||
---
|
||
|
||
## 如果模型"没调对"怎么办
|
||
|
||
Function Call 依赖模型生成结构化输出，但模型并不总是完美的，实际上有三种失败情形。
|
||
|
||
**情形一：调用了工具，但参数不符合 schema**
|
||
|
||
OpenClaw 的处理分两步：先尝试自动类型转换（比如 schema 要求数字，模型给了字符串 `"28"`，会尝试自动转成 `28`）；转换后仍然不通过，才把详细错误信息作为 tool result 还给模型：
|
||
|
||
```
|
||
Validation failed for tool "get_weather":
|
||
- /location: Expected string
|
||
Received arguments: { "city": "北京" }
|
||
```
|
||
|
||
模型通常能读懂并修正参数重新调用，整个过程用户无感知。
|
||
|
||
**情形二：模型把 tool call 写成了普通文本**
|
||
|
||
部分模型（尤其是较早版本或上下文过长时）会退化，不输出结构化的 `tool_use`，而是直接在回复文本里写：
|
||
|
||
```
|
||
[get_weather]
|
||
{"location": "北京"}
|
||
```
|
||
|
||
或者 XML 风格：
|
||
|
||
```
|
||
<function=get_weather>
|
||
<parameter=location>北京</parameter>
|
||
</function>
|
||
```
|
||
|
||
OpenClaw 有专门的 `tool-call-repair` 模块识别这些格式，解析成功后提升为正式的结构化调用继续执行，同时把这段文本从用户可见的回复里抹掉。
|
||
|
||
**情形三：模型完全没有识别到需要调工具**
|
||
|
||
没有任何 tool call，agent loop 当普通文本回复处理，直接返回给用户。没有报错，但用户可能拿到的是一个不准确的答案——这正是为什么工具的 `description` 要写清楚。
|
||
|
||
| 情形 | 处理方式 |
|
||
|---|---|
|
||
| 参数类型小错误 | 自动类型转换，尽量容忍 |
|
||
| 参数不符合 schema | 错误信息还给模型，让模型重试 |
|
||
| 模型输出纯文本 tool call | 解析并提升为结构化调用 |
|
||
| 模型完全没调工具 | 当普通文本回复，loop 结束 |
|
||
|
||
---
|
||
|
||
## 几个常见误区
|
||
|
||
**误区一：`description` 随便写就行**
|
||
|
||
`description` 是模型决定"要不要用这个工具"的唯一依据，也是它真实读到的文本。写得模糊，模型就可能在不该调用时调用，或者该调用时放弃。工具描述和参数说明值得认真打磨。
|
||
|
||
**误区二：一次只能调一个工具**
|
||
|
||
现代模型支持在一次响应里输出多个 tool call，框架可以并行执行。这对"分头查询再汇总"的任务（比如同时搜索多个关键词）效率提升很大。
|
||
|
||
**误区三：有顺序依赖的操作需要开发者干预**
|
||
|
||
"先创建文件再写入"这类有依赖的操作，LLM 会自然地分轮次处理——它看不到上一步的结果，就不会发出下一步的调用。开发者只需要处理**同批次内的并发安全**（用 `sequential`），跨轮次的逻辑顺序不需要干预。
|
||
|
||
---
|
||
|
||
## 小结
|
||
|
||
Function Call 的本质是一个**协议**：开发者用 schema 描述工具，模型用结构化输出表达"想调哪个"，代码执行并返回结果，模型用结果继续生成。这个循环让 LLM 从"知识库"变成了"能行动的 agent"。
|
||
|
||
你现在看到的各种 AI 助手能查天气、写代码、操作文件、发邮件，背后都是这套机制在支撑。如果你对 agent 如何管理多轮工具调用的完整循环感兴趣，可以进一步了解 agent loop 的设计；如果想知道工具列表如何按需过滤，可以看 tool planner 的实现。
|