跳转至

工具调用与结构化输出

模型从不"执行"工具——它只是输出一段约定格式的 JSON，真正干活的是你的代码。这个分工是 agent 一切能力与安全设计的根。 🟡 半稳定（机制稳定，API 细节随版本演进）｜ 对位 W2 ｜ 最后核实：2026-09-08

为什么要懂

工具调用是 agent 的发动机：没有它，模型只能纸上谈兵；有了它，模型才能查词表、读文件、跑代码。W2 你要手写 dispatch 循环，这一页是它的原理底稿。

核心解释：四步循环

① 声明：请求里附上工具清单（每个工具的 name / description / 参数 JSON Schema）
② 决策：模型输出「调用意图」——一段结构化 JSON（调哪个工具、传什么参数）
③ 执行：你的代码解析 JSON，真正执行工具，拿到结果
④ 回填：结果作为 tool 角色的消息追加到对话历史，再次请求模型 → 回到 ② 或给出最终回答

关键点有三个，每个都值得停下来想一遍：

  1. 模型只生成意图，从不执行。它输出的 {"city": "北京"} 只是一段文本，是你的 execute() 让它变成了真实的数据库查询。所以：权限控制的最后一道闸门永远在你的代码里，不在模型里——这是 W5 安全周的全部前提。
  2. description 是写给模型看的"文档"。模型选择工具的唯一依据就是你写的名称和描述。写得含糊（search：搜索东西），模型就乱调；写得像 SAP 一样精确（search_ct：在 CDISC 受控术语表中按 codelist 编码查询允许值，返回 submission value 列表），模型就能用对。工具描述 = prompt 工程的工程化。
  3. 工具定义占上下文。每次请求都带着全部工具的 schema——工具不是越多越好，20 个含糊工具不如 3 个精确工具（还省钱，见 token 页）。

结构化输出（structured outputs）：同一个机制的"反向"用法——不让模型调工具，而是强制它的回答本身符合你给的 JSON Schema。应用场景直接对口你的工作：让模型把 aCRF 变量提取成固定字段的 JSON、把 SAP 分析人群定义提取成结构化条件。比「求你了请输出 JSON」可靠得多。

动手试试（W2 预演）

设计 search_ct 工具的 schema，先写在纸上（这就是 W2 的任务之一）：

  • name：search_ct
  • description：查 CDISC 受控术语表。什么时候该用、什么时候不该用，写清楚
  • 参数：codelist_code（如 SEX、NY）、extensible（是否可扩展，布尔）——想想缺了哪个参数模型会怎么猜

然后对照 OpenAI Function Calling 官方指南 检查：你的 schema 和官方推荐格式差在哪？

常见误解

  • ❌「模型自己会调工具」→ 不，模型只生成 JSON，你的代码执行。网上说的"模型支持 function calling"意思是"模型被训练得能可靠地生成这种 JSON"
  • ❌「参数校验是多余的」→ 模型会生成格式正确但语义离谱的参数（比如 codelist_code: "AE 严重程度"）。schema 约束格式，你的代码必须校验语义（白名单、范围检查）——和 W2 的 read_file 路径白名单是同一原则
  • ❌「工具报错就完了」→ 错误信息回填给模型，它常常能自我修复（换参数重试）。W2 加餐有专门实验

现状与深挖

  • 各家 API 已趋同到 OpenAI 格式（DeepSeek 兼容）；新动向是「并行工具调用」（模型一次决策调多个工具）和 MCP 协议统一工具接入（阶段 2）。
  • 深挖：官方指南为主线，HuggingFace Agents Course 为加餐，中文参考《深入理解 AI Agent》第 1、4 章——均在 resources.md。