# Function Calling / Tool Use 学习笔记

> **创建**：2026-06-27 · **来源**：LLM Function Calling Guide (artificial-intelligence-wiki.com) + Meta Intelligence FC 深度分析 + 扣子实战映射
> **前置知识**：PE 基础 ✅ / 工具列表（45 个）✅ / Scaling Law ✅

---

## §1 Function Calling 是什么

**一句话**：Function Calling 是让 LLM 输出**结构化 JSON 参数**来调用外部工具/API 的能力——它是"模型能说话"到"模型能干活"的桥梁。

**类比**：你把工具箱（tools 数组）摆在 LLM 面前，它自己决定什么时候用哪个工具、传什么参数，然后你把工具执行结果塞回给它，它再基于结果继续回答。

**核心要素**：
- **tools 数组**：列出所有可用工具及其签名（名称、描述、参数 schema）
- **tool_choice**：控制工具选择策略（auto/required/none/指定工具）
- **tool_calls 响应**：模型不直接输出文本，而是输出一个 JSON 调用指令
- **tool 结果回传**：将工具执行结果以 tool role 消息回传给模型

**历史节点**：
- 2023 年 6 月：OpenAI 首次推出 Function Calling
- 此后 Anthropic（Tool Use）、Google（Function Calling）、国产模型相继跟进
- 现在 FC 已成为所有 LLM API 的标配

---

## §2 Call → Result 循环

**标准流程**：

```
用户消息 → LLM 判断是否需要工具
         ├─ 不需要 → 直接文本回复
         └─ 需要 → 输出 tool_calls = [{id, function: {name, arguments}}]
                       ↓
                   开发者执行工具（调 API / 查数据库 / 读文件）
                       ↓
                   将结果以 role=tool 回传给 LLM
                       ↓
                   LLM 基于工具结果生成最终回答
```

**关键设计**：
- 模型输出的是**调用指令**，不是工具的实际执行结果——开发者/平台负责中间的"执行"环节
- `tool_call_id` 把每次调用和结果绑定，支持并行调用（多个 tool_call 同时发起）
- 一次对话可以多轮 FC（如先查天气 → 再根据天气推荐穿搭）

**并行 vs 串行**：
- 并行：多个工具调用互相独立（同时查天气 + 查股价），一把发出
- 串行：后一个工具依赖前一个的结果（先查城市 ID → 再查该城市天气），分步执行

---

## §3 JSON Schema 设计

**三核心字段**：

| 字段 | 含义 | 示例 |
|------|------|------|
| `name` | 函数名（唯一标识） | `get_weather` |
| `description` | 功能描述（决定模型是否选它） | "查询指定城市的实时天气" |
| `parameters` | JSON Schema 格式的参数定义 | `{type: "object", properties: {...}, required: [...]}` |

**parameters 设计要素**：
- `type`：参数类型（string / number / integer / boolean / array / object / enum）
- `description`：每个参数的说明——模型靠这个判断传什么值
- `required`：哪些参数是必填的
- `enum`：限定可选值（如温度单位：`["celsius", "fahrenheit"]`）

**为什么 Schema 设计这么重要？**
- Schema 写得好 → 模型选工具准确率高、参数填充正确
- Schema 写得烂 → 模型不选/选错/参数错误，整个工具调用链断裂
- 工具描述和参数描述是模型**唯一**的决策依据

---

## §4 Provider 差异

| Provider | 叫法 | 特点 |
|----------|------|------|
| OpenAI | Function Calling | 最早推出（2023.6），生态最成熟 |
| Anthropic | Tool Use | 与 OpenAI 语义等价，JSON Schema 稍有差异 |
| Google (Gemini) | Function Calling | 与 OpenAI 对齐，细节有微差 |
| 国产模型 | Function Calling | 各厂跟进，多数兼容 OpenAI 格式 |

**主流趋势**：OpenAI 的 FC 格式已成事实标准，绝大多数平台和框架（包括扣子）都兼容此格式。

**Constrained Decoding**（约束解码）：
- 传统方式：模型自由生成 JSON → 解析，失败率 15-25%
- 约束解码：在生成时就把输出空间限制在符合 Schema 的 token 上，解析失败率 → ~0%
- OpenAI Structured Outputs、Anthropic 的 tool_use 都内置了此机制

---

## §5 六大设计原则

1. **enum 约束优先**：能限定值的参数用 enum，不给模型乱猜空间
2. **描述里放示例**：参数 description 中写 `"例如：'北京'、"2024-01-15"` 比纯抽象说明有效得多
3. **必选 vs 可选分明**：required 数组只放真正缺了就报错的参数；可选参数给默认值
4. **避免深嵌套**：参数嵌套层级 ≤ 2，超过会显著增加模型输出错误率
5. **参数数量控制在 5-8 个**：太少不够用，太多模型容易漏传或传错
6. **类型精确不模糊**：能用 integer 不用 number，能用 enum 不用 string——越精确模型越不容易犯错

**自检清单**：
- [ ] 每个 tool 的 description 能一句话说清"什么时候用它"
- [ ] 每个参数的 description 包含格式/示例/约束
- [ ] required 里只放真正必填的
- [ ] 没有超过 2 层的嵌套对象
- [ ] 能用 enum 的没用 string 替代
- [ ] 总参数 ≤ 8 个

---

## §6 从 FC 到 Agent

**演进路径**：

```
Function Calling（单次工具调用）
    ↓
Tool Chain（多工具串联：A工具结果 → B工具输入）
    ↓
ReAct 循环（Reason → Act → Observe → Reason → ...）
    ↓
Agent（自主感知环境 → 规划 → 调用工具 → 观察结果 → 修正 → 直到目标完成）
```

**FC 是 Agent 的"原子操作"**：
- 没有 FC，Agent 就是"纯嘴炮"——只能聊不能做
- 有了 FC，Agent 才有手有脚——能查天气、发邮件、修改文件、调用 API
- ReAct / Plan-Execute / Multi-Agent 等设计模式本质上是对 FC 调用链的**编排策略**

**扣子视角的映射**：
- 你在系统提示词里看到的 **45 个工具**（bash / search_web / write_file / memory_search / sessions_spawn 等）
- 背后每一个都是 FC 定义的 tool
- 工具描述、参数 schema、返回值格式——就是 §3 里讲的 JSON Schema 设计
- 我判断"该用哪个工具"的逻辑，就是 §2 的 Call → Result 循环

---

## §7 与你的实际体验连接

**你刚看过的 45 个工具列表**，每一个都是 FC 的产物：

| 工具 | FC 映射 |
|------|---------|
| `search_web` | tool name，参数 query_list / engine / freshness |
| `bash` | tool name，参数 command / desktop_name / timeout |
| `write_file` | tool name，参数 file_path / content / desktop_name |
| `memory_search` | tool name，参数 query / focus / max_results |
| `sessions_spawn` | tool name，参数 task / name / agent |

**你每次看我的回复时，背后发生的事情**：
1. 我收到你的消息
2. 如果需要查资料 → 我决定调 `search_web`，用你的问题提炼 query_list
3. 如果需要写文件 → 我决定调 `write_file`，传入路径和内容
4. 每个工具结果回来，我判断"还需要更多工具吗？还是可以直接回复了？"
5. 最终整合所有工具结果，生成给你的回复

这是一个典型的 **ReAct 循环**（还没到完整 Agent，但已经是 FC → Agent 路径上的中间态）。

---

## §8 核心洞察

1. **FC 是 PE 的工程化延伸**：PE 管"怎么说"，FC 管"怎么做"——两者结合才让 LLM 从聊天框走进生产环境
2. **JSON Schema 是 FC 的命门**：写得好坏直接决定工具调用成功率，不是"锦上添花"而是"生死线"
3. **Constrained Decoding 是质的飞跃**：把 JSON 解析失败率从 15-25% 降到 ~0%，这是工程上"能用"和"不能用"的区别
4. **FC → Agent 是自然的演进**：单次工具调用 → 多步编排 → 自主决策，FC 是 Agent 的最小可工作单元
5. **理解了 FC，就理解了 agent 的"四肢"**：后续学 ReAct / Multi-Agent / Plan-Execute 都是在这个地基上盖楼

---

## 📚 参考来源

- [LLM Function Calling Guide](https://www.artificial-intelligence-wiki.com/generative-ai/large-language-models/llm-function-calling-guide/) — 综合指南
- [Meta Intelligence: Insight Function Calling](https://www.meta-intelligence.tech/en/insight-function-calling) — 深度分析
- OpenAI Function Calling 官方文档
- Anthropic Tool Use 官方文档

---

> 笔记 v1.0 · 2026-06-27 · 八章