本文是《Java 后端 + AI 落地（Spring AI 主线）》系列第 5 篇。上一篇解决"让模型知道"，这一篇解决"让模型做事"。RAG 把知识递给了模型，但模型仍然只能"说"，不能"做"——它没法查这笔订单的真实状态、没法算这个月的实际毛利、没法把工单派给正确的人。函数调用（Function Calling，现在官方术语叫 Tool Calling）就是那道接口：把你的 Java 方法注册成模型可以主动请求调用的工具。这篇会讲透三件事：为什么模型其实从不真正调用你的代码（那它到底做了什么）、工具描述写得差为什么直接决定模型会不会用它，以及为什么"工具的循环"必须交给框架而不是自己手写——这是第 1 篇埋下的"手写派终点"的解药。
📌 版本声明：本文基于 2026-09-27 的版本线撰写：Spring AI 2.0.1 + Spring Boot 4.1.x + Java 21。这是一个需要特别提示的版本分界点：Spring AI 2.0 对工具调用的内部实现做了较大重构（工具执行从 ChatModel 内部上移到 Advisor 链，由 ToolCallingAdvisor 默认托管），1.1.x 的写法在 2.0 上部分已不适用。文中凡涉及 API 差异处都会标注。模型侧示例使用第 2 篇的 OpenAI 兼容端点（通义千问），工具调用能力与模型强相关，换模型前请先用本文 5.7 节的测试方法验证工具选择是否可靠。
文章目录
1️⃣ 为什么模型需要"工具"：从"知道"到"做到"
1.1 一个所有团队都会撞上的墙
这是在我参与的项目里真实出现过的对话。 第 4 篇的 RAG 上线两周后，业务方提出新需求："能不能让它直接告诉我，张三这个月的报销还剩多少额度？"团队按第 4 篇的方法建了索引、把《费用报销管理办法》切片入库，然后测试——模型很流利地回答了制度："差旅住宿标准为每人每晚上限 400 元，超标部分需部门负责人审批。"但对"张三还剩多少额度"这个问题，它答不出来。
原因一点都不神秘：额度是数据库里的一行数据，不是文档里的一段文字。 制度文件里写着"每年报销上限 2 万元"，但张三今年已经报了 18763 元这件事，只存在于 expense_record 表里，任何人都没有把它写成文档，它每分钟都在变。
这一类问题的共同特征是：答案不在"知识"里，而在"系统"里。 我把它们整理成四类，因为它们的解法完全不同，而混为一类就会得出"RAG 不好用"的错误结论：
| 问题类型 | 例子 | 答案在哪 | 正确的解法 |
|---|---|---|---|
| 语义型 | “住宿标准是多少”“这个流程分几步” | 文档里 | RAG（第 4 篇） |
| 数据型 | “张三还剩多少额度”“这笔订单到哪一步了” | 业务数据库里 | 工具调用（本文） |
| 计算型 | “上季度华东区毛利多少”“按这个方案三年回本吗” | 需要按规则实时计算 | 工具调用（本文） |
| 动作型 | “帮我把这张工单转给运维组”“取消这个预约” | 需要在业务系统里执行写操作 | 工具调用 + 强权限约束（本文 5.6） |
这张表的意义在于，它把第 4 篇 1.4 节埋的那条线接通了。 第 4 篇讲过一个反例：让 RAG 去做"算某个数"的任务是架构层面的错误。本节要把这个判断扩展成一条更完整的选型纪律：
语义问题走 RAG，数据与计算问题走工具，动作问题走工具 + 权限闸门。让模型当"路由器"决定走哪条——但路由的边界必须由你划定，不能交给它自由发挥。
为什么边界必须由你划定？ 因为模型对"自己能不能算对"这件事的判断是不可靠的。你问它"帮我算一下这个月毛利"，它会很乐意地直接给你算一个数，而不是去调用你提供的方法。 我见过一次真实的翻车：一个内部报表问答，模型凭上下文里的几个数字心算出了"毛利率 32.7%"，而实际值是 41.2%——它把"成本"当成了"销售额减去运费"，因为没有人明确告诉它"这类问题必须查"。后来我们在系统提示词里加了一行硬约束才稳住：“任何涉及金额、数量、比率、时间差的问题，一律不允许自行计算，必须调用工具。” 这一行约束是本文后面所有工程细节的前提。
1.2 三个必须提前破除的误解
在讲机制之前，我要先拆掉三个流传很广的误解。它们每一个都会导致工程上的错误设计，而且都很自然，所以必须提前说清。
误解一：模型会"调用"你的 Java 方法。 这是最根本的一个。模型从头到尾没有能力执行任何代码——它只是生成文本，只不过在工具场景下，它生成的是一段符合约定格式的结构化文本，形状是"我要调用 getOrderStatus，参数是 orderId=20260927001"。真正执行 getOrderStatus 的是你进程里的框架代码。 这个区别不是学究式的：它意味着**"模型说它调用了"和"代码真的执行了"是两件可以分别出错的事**，也意味着所有权限校验必须在框架这一侧做，不能指望模型"自己知道不该调"（5.6 节展开）。
误解二：工具调用是"一次请求里模型顺手做的事"。 不是。它天然是一个多轮往返的循环：你发请求给模型 → 模型返回"我要调用 X" → 你的进程执行 X → 把执行结果作为一条新消息再发给模型 → 模型基于结果生成自然语言回答（也可能再要求调用下一个工具）。一轮工具调用最少是两次模型请求，而不是一次。 这个事实直接推出两个工程后果：成本至少翻倍（5.5 节的 token 账要按这个算），以及每一轮都要做超时与轮次上限控制（4.7 节）。
误解三：工具越多，能力越强。 这是一个非常贵的直觉。工具数量和模型选对工具的概率是反比关系——从 5 个工具加到 30 个以后，"选错工具"和"该调而不调"的比例会明显上升，而且这类失败在监控上表现得很隐蔽（请求成功、有回答、只是答的是别的数据）。所以工具设计的第一原则不是"多多益善"，而是"少而清晰"，工具多到一定程度必须做分层路由（5.3 节）。
1.3 一次工具调用的完整循环
把上面三个误解反过来，就是工具调用的真实机制。下面这张图是本文的地基，后面每一个工程细节都挂在这条循环的某个位置上：
（图 1：一次工具调用的完整循环——注意三点：模型只生成"要调用什么"、结果会以工具消息追加进对话、整轮最少两次模型请求）
这张图里有四个容易被忽略、但每一个都对应一类线上问题的细节：
第一，工具的"描述"是随请求一起发出去的，它是模型唯一的决策依据。 模型看不到你的 Java 方法体、看不到 SQL、看不到注释——它只看得到方法名、@Tool 里的描述、以及参数的描述。所以我在 4.2 节会把"怎么描述"当成核心工程技能来讲，而不是当成写注释这种附带工作。
第二，模型返回的是一个"请求"，不是一个"结果"。 这中间有一层必须由框架完成的校验：name 是不是我们注册过的工具？参数类型对不对？缺参数怎么办？这些校验手写极容易漏，而漏掉的后果可能是让模型往一个不存在的参数里塞进一段提示注入文本。
第三，执行结果是"追加进对话"的。 这意味着工具返回的内容会永久占用这一轮的上下文（直到这轮结束）。一个返回 200KB JSON 的工具，会把它之后所有轮次的成本抬高一个数量级——这是 5.2 节讲"返回值必须瘦身"的原因。
第四，也是最重要的：整个循环在 Spring AI 2.0 里由框架托管，你的业务代码只看到最后一行回答。 这在 90% 的场景下是好事（少写 bug），但在需要精细控制的场景下会成为障碍——这也是为什么 2.0 保留了 internalToolExecutionEnabled(false) 这个口子（4.7 节）。
1.4 自己写循环 vs 交给框架：那条"手写派的终点"
第 1 篇 1.2 节留了一个悬念：手写 HTTP 调用模型的路线，终点在哪。工具调用就是那个终点，而且我认为这是整个系列里"必须交给框架"最没有争议的一处。
理由不是"框架写得更短"，而是循环里有六件事你必须做对，其中至少三件在没有框架的情况下几乎必然做错：
（图 2：手写循环必须自己实现的六件事——下方标注的三件是"第一轮全过、第二轮才开始随机出问题"的根源）
我要强调的是这张图的结论部分。 手写循环的代码量其实不大（第一版大概 200 行），真正的问题在于它的失败模式：字段名不一致、角色配对错误、流式下 tool_calls 分片拼装——这三类错误的共同点是"第一轮测试全过、上线后第二轮开始随机出问题"，且报错位置不在你的代码里。 我在一个项目上花过将近三天排查一个"偶发 400"，最后发现是手写代码在第二轮请求里漏掉了 tool_call_id 的配对。这种时间成本，折算成框架的学习时间要划算得多。
所以本文的实际立场是：不要把"实现工具循环"当作你的技术难点，要把"设计好工具"当作你的技术难点。 后者才是模型会不会用对工具的决定因素，也是接下来四章的主要内容。
2️⃣ 核心概念：Spring AI 的工具调用模型
2.1 三组核心抽象：Tool / ToolCallback / ToolCallingManager
Spring AI 的工具调用 API 只有三组概念，但它们的职责边界必须分清，否则很容易把"给模型看的描述"和"给框架用的执行逻辑"混在一起，从而写出"模型能调但调不对"的工具。
| 抽象 | 对应代码 | 职责 | 谁在看它 |
|---|---|---|---|
| Tool 定义 | @Tool + @ToolParam 标注的 Java 方法 | 声明"有这么个能力"，含名称、描述、参数 Schema | 模型（描述是它唯一的决策依据） |
| ToolCallback | ToolCallback / MethodToolCallbackProvider | 把方法包装成"可解析、可校验、可执行"的回调对象 | 框架（负责 name→方法 的绑定与参数校验） |
| ToolCallingManager | ToolCallingManager（默认 DefaultToolCallingManager） | 驱动整个循环：解析 tool_calls、执行、回填、决定是否继续下一轮 | 框架内部（2.0 由 ToolCallingAdvisor 托管） |
这张表我特意把"谁在看它"单列一栏，因为它是理解工具调用最关键的一把钥匙。 一个常见的错误是把给框架看的信息写进了给模型看的描述里——比如在 @Tool 描述里写"内部实现走的是 ES 检索"、“这个方法很慢，慎用”。模型看到这些会做出奇怪的决策（比如因为"很慢"而回避使用本该用的工具），而框架根本不读描述。反过来，把给模型看的业务语义漏掉（比如只写"查询订单"，没写"仅支持最近 90 天的订单"），模型就会在 100 天前的订单上反复调用它、失败、再调用，转成用户可见的"它一直转圈"。
所以工具描述的正确写法只有一种：站在模型的角度写"什么时候该用它、用了能得到什么、有什么前提限制"，一个字都不写实现细节。
2.2 @Tool 与 @ToolParam：把方法变成工具的注解
先看一段最小可运行的代码。我会刻意把"为什么这么写"逐条说清，因为这几行里的每一个选择都有对应的失败模式。
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
@Component
public class ExpenseTools {
private final ExpenseQueryService expenseQueryService;
public ExpenseTools(ExpenseQueryService expenseQueryService) {
this.expenseQueryService = expenseQueryService;
}
/**
* 为什么返回值用 record 而不是 String？
* 见 4.4 节：结构化返回既省 token，又让模型能可靠引用具体字段。
*/
public record QuotaResult(
String userId,
BigDecimal yearlyLimit,
BigDecimal usedAmount,
BigDecimal remainingAmount,
boolean exceeded
) {}
/**
* 工具描述只写三件事：什么时候用、返回什么、有什么前提。
* 绝不写实现细节（走哪个表、用了什么索引）——模型不关心，还会被误导。
*/
@Tool(name = "get_expense_quota",
description = """
查询某员工本年度费用报销额度使用情况。
适用：用户询问"某人还剩多少额度/已报多少/是否超额"。
不适用：查询历史报销单明细（请用 query_expense_records）；
查询制度标准（请用知识库检索）。
前提：userId 必须是系统内的员工工号，形如 "zhangsan"。
""")
public QuotaResult getExpenseQuota(
@ToolParam(description = "员工工号，例如 zhangsan。不是姓名、不是手机号")
String userId) {
return expenseQueryService.queryQuota(userId);
}
}
这段代码里有四个刻意的设计，每一个都值得展开：
第一，name 显式指定，用下划线命名。 不指定的话框架会用方法名（getExpenseQuota），而模型在英文工具名上的表现通常比驼峰更稳（get_expense_quota 更接近它在训练数据里见过的工具命名习惯）。更重要的是显式命名让你以后能安全地重构 Java 方法名，而不动模型的工具契约——这是一条很实际的收益，我在 5.8 节会再提。
第二，描述用文本块写了"适用 / 不适用 / 前提"三段。 这是我在多个项目上试出来最有效的结构。其中"不适用"这一段最容易被省略，但它的收益最大——因为它解决的是"工具选错"的问题。模型在多个相似工具之间做选择时，最有用的信息不是"这个工具能干什么"，而是"这件事不该用这个工具"。
第三，@ToolParam 的描述里主动写了"不是什么"。 "员工工号，例如 zhangsan。不是姓名、不是手机号" 这后半句看起来啰嗦，但它消掉的是最高频的一类参数错误：用户说"查一下张三的额度"，模型手里只有"张三"两个字，它会倾向于把"张三"直接塞进 userId。加上"不是姓名"之后，模型的行为变成了"先调用一个 find_user_by_name 工具把人名转成工号"——这个连锁调用正是我们想要的行为。参数描述的作用不只是"说明格式"，更是"阻止误填"。
第四，返回值是 record 而不是拼接好的中文字符串。 这一点争议最大，因为返回一个人话字符串在某些场景下确实效果更好（模型不用"翻译"JSON）。我的判断是按场景分：
| 返回形态 | 优点 | 缺点 | 建议场景 |
|---|---|---|---|
| POJO / record | 省 token、字段明确、模型能精确引用、便于二次加工 | 模型需要"读懂"字段名 | 默认选择：数值、状态、列表类查询 |
| 拼接好的自然语言 | 模型零加工直接可用，格式可控 | 字段信息被压平、难以引用、字符串模板要维护 | 结果本身就是一段解释性文本 |
| 原始 JSON 字符串 | 最省事 | 字段名啰嗦会放大 token；模型可能照抄出不对的格式 | 不推荐，除非是透传第三方响应 |
注意一个反直觉的点：POJO 序列化出来的 JSON 字段名会占 token。 上面那个 QuotaResult 如果字段名叫 yearlyLimitAmountInCents，一次调用就要多花十几个 token，而在多轮循环里这个成本会累积。所以工具返回结构里的字段名要短，同时保持可读——这是 5.2 节"返回值瘦身"的第一条。
2.3 ChatModel 与 ChatClient：工具注册的两条路
工具定义好了，接下来是"怎么让模型知道它存在"。Spring AI 提供了两个层级，选错了会在后期改造时付出代价。
（图 3：ChatModel 与 ChatClient 两条注册路径——2.0 里工具执行被上移到 Advisor 链，忘记挂 ToolCallingAdvisor 会导致"模型说要调用，然后没有然后"）
这张图的建议部分是我实际的做法：以 ChatClient 的 defaultTools 为基线，按场景局部覆盖。 原因很实际——工具集就是一个服务的"能力边界"，它应该是显式的、集中可审计的。用 ChatModel 逐请求指定，半年后你就会发现没人说得清"这个接口到底能调哪些工具"，而这件事在安全审计时是必须能回答的（5.6 节）。
这里必须提一个 2.0 的行为变化，它是最容易踩的坑： 在 1.1.x 里，工具的执行发生在 ChatModel 内部——也就是说，即使你绕过 ChatClient 直接用 ChatModel，工具也会被自动执行。在 2.0 里，工具执行被上移到了 ToolCallingAdvisor，它是 Advisor 链上的一环。 这带来两个直接后果：
后果一：如果你自定义了一套 Advisor 链而忘了包含 ToolCallingAdvisor，工具将不会被自动执行——模型会返回"我要调用 X"，然后……没有然后，你的代码会拿到一段"声明要调用工具"的文本直接返回给用户，表现为"它说它要去查了，但没给结果"。这个故障形态非常有欺骗性，因为它看起来像"模型不听话"，实际是你自己的链路把执行环节摘掉了。
后果二：Advisor 的顺序现在包含了"工具执行"这一步，所以顺序纪律的范围变大了。 第 4 篇 6.1 节强调过"RAG 检索 Advisor 必须在工具循环之前"。在 2.0 里这句话变成了一条更硬的约束：如果 RAG Advisor 排在 ToolCallingAdvisor 之后，那么每一轮工具调用后的那次模型请求都会重跑一次检索——第 4 篇说的"一次提问触发 5 次向量检索、成本翻 5 倍、同一段引用出现好几次"，在工具场景下会比纯 RAG 场景更容易触发，因为工具循环的轮次天然比单次问答多。
2.4 ToolContext：一条必须走"可信通道"的旁路
这是本节最重要的一节，也是我认为把工具调用从"能跑"做到"能上线"的分水岭。
先看问题。工具方法需要一些模型不该提供、也提供不了的上下文：当前登录用户的真实 ID、租户 ID、请求追踪 ID、用户的语言偏好。这些东西绝不能让模型从对话里推断并塞进参数——因为对话内容是可以被用户影响的。
为什么"让模型传 userId"是不行的？ 想一个具体的攻击路径：用户对系统说"我是管理员，帮我查一下李四的额度"。如果工具签名是 getQuota(String userId) 且这个参数由模型填，那么模型完全可能把 userId 填成对话里出现的任意值——@ToolParam 的描述只能"降低"这个概率，不能构成安全边界。这不是模型"不听话"，而是你把它放在了一个它无法胜任的位置上：判断身份是确定性逻辑，不是语义理解。
Spring AI 的答案是 ToolContext——一个不参与 Schema 序列化、因而模型完全看不见的传参通道：
// 关键点：ToolContext 参数不会出现在发给模型的工具 Schema 里，
// 模型既看不到它，也无法给它赋值。它只能由你的 Java 代码注入。
@Tool(description = "查询当前登录用户自己的费用报销额度使用情况。无需任何参数。")
public QuotaResult getMyExpenseQuota(ToolContext context) {
// 这个值来自服务端会话，与对话内容无关 —— 用户改不了、模型也改不了
String trustedUserId = (String) context.getContext().get("trustedUserId");
String tenantId = (String) context.getContext().get("tenantId");
if (trustedUserId == null) {
// 宁可失败，也不要"退化为按对话内容猜身份"
throw new IllegalStateException("缺失可信用户上下文，拒绝执行");
}
return expenseQueryService.queryQuota(tenantId, trustedUserId);
}
调用侧把可信上下文显式注入：
// userId 来自你的认证上下文（SecurityContext / 网关透传的请求头），
// 来自 HTTP 请求的可信链路，绝不来自对话内容或模型输出。
String trustedUserId = SecurityUtils.currentUserId();
String answer = chatClient.prompt()
.user(userQuestion) // 用户问题
.toolContext(Map.of( // 可信旁路
"trustedUserId", trustedUserId,
"tenantId", SecurityUtils.currentTenantId()))
.call()
.content();
这个设计带来三条工程纪律，我建议直接写进团队规范：
第一，凡是"我是谁"类信息，一律走 ToolContext，绝不作为工具参数。 判断标准很简单：如果一个参数的值会影响权限判定，它就绝不能由模型填。 这条规则的适用面比想象中广——不只是 userId，还包括租户 ID、角色、数据范围（“只能看本部门”）、以及任何"用户可见范围"的标记。
第二，"无参工具"在权限敏感场景下是更安全的形态。 注意上面 getMyExpenseQuota 被设计成了零参数——描述里明确写了"查询当前登录用户自己的……无需任何参数"。这样做的好处是模型完全没有机会构造越权查询：它能做的只有"调用"或"不调用"，没有第三个选项。相比之下 getQuota(userId) 这种形态，即使有 ToolContext 兜底，也仍然需要额外写一层"请求的 userId 必须在当前用户的数据范围内"的校验。能用零参数工具表达的场景，就不要给参数。
第三，缺失可信上下文时必须"硬失败"，不能"降级猜测"。 上面代码里那个 IllegalStateException 是刻意的。一个常见的"聪明做法"是：拿不到 trustedUserId 就退回去让模型从对话里提取——这等于把安全边界交给了用户输入。 宁可让这次请求失败并报警，也不要让它以不确定的身份执行。
我要把这条纪律的严重性讲透，因为它的失败后果是不可逆的。 第 4 篇 5.2 节讲过 RAG 的权限过滤必须写在检索请求里。工具调用的权限问题比 RAG 更危险：RAG 的越权最多是"看到了不该看的文字"，而工具的越权是"读到了不该读的数据"甚至"改动了不该改的记录"——后者没有"撤回"这个选项。所以工具调用的权限模型必须是"以认证身份为唯一依据"，而不是"以对话内容为依据"。
3️⃣ 环境准备
3.1 版本矩阵与依赖
工具调用对版本比较敏感，因为它是 2.0 重构的重点。我建议按下面的组合起步：
| 组件 | 版本 | 说明 |
|---|---|---|
| JDK | 21 | Spring AI 2.0 的最低要求；record + 文本块用起来也舒服 |
| Spring Boot | 4.1.x | 2.0 强制要求 Boot 4.x / Framework 7；Boot 3.5 已于 2026-06-30 EOL |
| Spring AI | 2.0.1 | 工具执行走 ToolCallingAdvisor（2.0 的架构变化） |
| Jackson | 3.x | Boot 4 的默认线，与 Spring AI 2.0 对齐 |
| 模型 | 通义千问（OpenAI 兼容端点） | 教程用第 2、3 篇已跑通的配置，工具调用能力用 5.7 节方法验证 |
如果你现在还在 Spring Boot 3.5 / Spring AI 1.1.x 上，这一段必须看清： 1.1.x 的工具调用写法与 2.0 有实质差异（工具执行位置、部分配置键名、以及 2.0 移除的 .options 中间段）。我的建议是不要在 1.1.x 上开始学工具调用——你会学到一套明年要重写的写法。要么直接升到 2.0（代价是 Boot 大版本升级），要么先按第 2 篇的两条路线之一把工程搭好再升级。
<!-- pom.xml：工具调用不需要额外 starter，它在 spring-ai-starter-model-* 里 -->
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
<!-- 用 OpenAI 兼容端点接通义千问，见第 2 篇路线 B -->
</dependency>
<!-- 可观测性：工具调用的入参/出参是否记录（5.7 节，生产建议打开） -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
3.2 配置与一个必须加的保险
spring:
ai:
openai:
base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
api-key: ${DASHSCOPE_API_KEY} # 第 2 篇：绝不进配置文件明文
chat:
options:
model: qwen-plus # 工具调用的稳定性与模型强相关
temperature: 0.1 # 关键：工具场景要低温度
tools:
observations:
# 生产建议打开：把工具名、参数、耗时、结果大小记入观测
# 注意：开启内容记录会把入参/出参写进日志，涉及敏感数据时需评估
include-content: true
这里有一处必须解释的配置：temperature: 0.1。 工具调用场景对温度比普通对话敏感得多，因为工具选择和参数构造都是"结构化决策"，而不是"创作"。温度高会带来两类具体问题：一是同一句话在两个请求里选了不同工具（表现为"有时候能查、有时候答不知道"），二是参数值出现无意义的轻微变体（日期格式一会儿 2026-09-27、一会儿 2026/09/27，而你的解析器只认前者）。这一点在 5.7 节的测试里会非常明显。
另外提前埋一个"保险"——启动时自检工具注册结果。 这是从第 2 篇"配置静默失效"那条教训直接推出来的：@Tool 方法写错了（比如同一个 name 注册了两次、或者 ToolContext 参数位置放错）不会在编译期报错，运行时也可能只是"这个工具永远不被调用"。 所以加一段启动自检：
@Component
public class ToolRegistryHealthCheck {
private static final Logger log = LoggerFactory.getLogger(ToolRegistryHealthCheck.class);
// 为什么要在启动时做？因为"工具没被注册上"这个故障在运行期
// 的表现是"模型从来不用它"，而不会抛任何异常 —— 属于静默失效。
@EventListener(ApplicationReadyEvent.class)
public void reportRegisteredTools(ApplicationContext ctx) {
String[] toolBeans = ctx.getBeanNamesForAnnotation(Tool.class);
Map<String, Integer> nameCount = new HashMap<>();
for (String beanName : toolBeans) {
Object bean = ctx.getBean(beanName);
for (Method m : bean.getClass().getDeclaredMethods()) {
Tool t = m.getAnnotation(Tool.class);
if (t == null) continue;
String toolName = t.name().isEmpty() ? m.getName() : t.name();
nameCount.merge(toolName, 1, Integer::sum);
log.info("[工具自检] 已注册 {} -> {}.{}",
toolName, bean.getClass().getSimpleName(), m.getName());
}
}
// 重名会导致只有一个生效（另一个被静默覆盖），必须报警而不是静默继续
nameCount.forEach((name, cnt) -> {
if (cnt > 1) {
log.error("[工具自检] 工具名重复 {} 次，存在被覆盖风险：{}", cnt, name);
}
});
}
}
这段代码的价值不在于它多优雅，而在于它把一类"静默故障"变成了启动期可见的信息。 我在项目上遇到过真实的一次：两个开发者各自写了一个"查订单"的 @Tool，方法名不同但 name 都写了 query_order，结果只有后注册的那个生效，前一个工具的所有测试用例都通过（因为测试直接用服务层，不走工具注册），上线后表现为"用户问某类订单查不到"。这个 bug 追溯了两天才定位到。
4️⃣ 核心功能详解：从注册到循环
4.1 注册工具：三种粒度，各用在哪
工具注册的粒度选择看起来是小事，但它决定了半年后你能不能回答"这个接口能调哪些工具"。我把三种粒度和适用场景整理如下：
| 粒度 | 写法 | 适用场景 | 风险 |
|---|---|---|---|
| 全局默认 | ChatClient.builder(m).defaultTools(orderTools, expenseTools) | 单一业务域的 ChatClient | 工具集随业务膨胀后会变"万能" |
| 构建期覆盖 | client.prompt().tools(new ReportTools()) | 少数接口需要特殊能力 | 容易被滥用成"随手加一个" |
| 按名选择（子集） | ToolCallingChatOptions.builder().toolNames("get_expense_quota","query_expense_records") | 同一批工具按接口裁剪 | 需要维护工具名清单，改名会漏 |
我的实践建议是"默认集 + 按名裁剪"，尽量不用"构建期覆盖"。 原因在于可审计性：默认集和按名裁剪都能在代码里一眼看出"这个接口的能力集合"，而 .tools(...) 散布在各个业务方法里之后，能力边界就变成了一个需要全项目 grep 才能回答的问题。
@Configuration
public class ChatClientConfig {
// 统一的系统提示词里必须写死"什么时候必须查、不允许自行计算"
// —— 这是 1.1 节那条教训的固化形式，比散落在业务代码里可靠
private static final String SYSTEM_PROMPT = """
你是企业费用助手。严格遵守以下规则：
1. 任何涉及金额、数量、比率、时间差的问题，一律调用工具获取，禁止自行计算。
2. 工具返回的数据是唯一事实来源；工具调用失败时如实说明"暂时查不到"，
不要用你的常识推测具体数值。
3. 用户询问制度、流程、标准时，使用知识库检索能力，不要凭记忆回答。
""";
@Bean
ChatClient expenseChatClient(ChatModel chatModel,
ExpenseTools expenseTools,
OrderTools orderTools) {
return ChatClient.builder(chatModel)
.defaultSystem(SYSTEM_PROMPT)
.defaultTools(expenseTools, orderTools) // 默认能力集，集中可审计
.build();
}
}
这段配置里最值得注意的是 SYSTEM_PROMPT 的第 1 条和第 2 条。 很多人会把这类约束写在业务方法里、或者指望模型"自己懂"，但它在提示词里的位置很关键：默认系统提示词是所有请求都会带上的，是最稳定的约束承载位置。 第 2 条"工具返回的数据是唯一事实来源"同样重要——它堵的是"工具返回空结果时模型用常识补一个数字"这条路径，这是我在真实项目上见过的、最容易被当成"模型幻觉"处理、实际却是提示词缺约束的一类问题。
4.2 工具描述：决定模型"会不会用"的唯一变量
如果这一篇只能记住一件事，我会选这一节。 因为在工具调用里，代码逻辑正确只是必要条件，模型愿不愿意调、能不能调对，全看描述。
先把"描述写坏了会怎样"讲清楚，因为它比"怎么写好"更有说服力：
| 描述缺陷 | 具体写法 | 模型的实际行为 | 用户看到的现象 |
|---|---|---|---|
| 描述太笼统 | description = "查询订单" | 只要问题里带"订单"就调它，不管是不是要改状态 | 答非所问、答了个不相干的订单 |
| 不写"不适用" | 只写能干什么 | 在相似工具间随机选（尤其两个工具名都含"query"） | 时好时坏、无法复现 |
| 写实现细节 | "内部走 ES 检索，响应约 800ms" | 因为"800ms 很慢"而回避使用本该用的工具 | “它明明有这个能力却不用” |
| 参数无描述 | @ToolParam String date | 传 "上个月"、"9月" 这类自然语言 | 参数解析失败，报错回给用户 |
| 参数不写"不是什么" | @ToolParam String userId | 把人名、手机号填进 userId | 查不到数据，或查到别人的数据 |
| 描述里没有单位 | @ToolParam BigDecimal amount | 传 "1万" 或 10000.00（分/元不分） | 金额差 100 倍 |
这张表的最后两行是安全级别的缺陷，不是体验问题。 我在 2.4 节讲过权限不能靠模型判断，但"参数描述写全"是同一件事的第一道防线——它降低的是"模型误把用户输入的身份信息当作可信参数"的概率。注意这只是"降低概率"，不是边界（真正的边界是 ToolContext），但在实际项目里，描述写得清楚能挡掉绝大多数无心之失，而真正的攻击路径交给 5.6 节的三层防御。
下面是我在项目上定下来的描述模板，四条一起写，缺一条都不完整：
@Tool(name = "query_expense_records",
description = """
【何时使用】用户要查询某员工的历史报销单明细，
例如"张三上个月报了哪些""有几笔被驳回了"。
【何时不用】① 只问"还剩多少额度"→ 用 get_expense_quota；
② 问报销标准/流程制度 → 用知识库检索；
③ 问公司整体报销总额 → 用 aggregate_expense。
【返回什么】按提交时间倒序的报销单列表，含单号、金额（单位：元）、
状态（APPROVED/REJECTED/PENDING）、驳回原因。
【前提与限制】userId 必须是工号；仅支持查询最近 12 个月，
更早的数据需走归档流程（本工具会返回空列表并说明）。
""")
public List<ExpenseRecord> queryExpenseRecords(
@ToolParam(description = "员工工号，例如 zhangsan。不是姓名、不是手机号、不是邮箱")
String userId,
@ToolParam(description = """
时间范围，必须转换为 yyyy-MM-dd 格式的起止日期。
例如"上个月"要换算成具体日期，不要直接传"上个月"这个词。
""")
String startDate,
@ToolParam(description = "时间范围结束日期，格式 yyyy-MM-dd，含当天")
String endDate) {
return expenseQueryService.query(validateUserId(userId), startDate, endDate);
}
这个模板里，我认为价值最高的两处是"何时不用"和"必须转换为 yyyy-MM-dd"。
"何时不用"这一段的价值，是它把"选择问题"从模型手里收回来了一部分。 注意它写的不是"不能用于 X"这种模糊否定，而是**“X 场景请用 Y 工具”——给了明确的替代项，模型的行为才会从"随便挑一个"变成"跳到正确的那个"。 这个技巧是我从一个失败案例里总结的：当时有三个查询类工具（额度、明细、汇总），模型在"上个月总共报了多少钱"这个问题上有一半概率选了明细工具**（因为它确实"能"返回明细，模型自己再求和）。加上"问公司整体报销总额 → 用 aggregate_expense"这行之后，选对率从约 50% 提升到 95% 以上。 注意这里的根因不是模型笨，而是"总额"这个词在语义上确实同时匹配"明细+求和"和"汇总"两条路径——是描述没有把语义边界划清。
"必须转换为 yyyy-MM-dd 格式"的价值，是把"格式转换"这件确定性工作从模型手里拿过来又还给它——但带着明确指令。 这里有个取舍要讲清：你可以让工具接受自然语言日期（在 Java 侧做解析），也可以强制模型输出标准格式。 我的选择是后者，理由是：Java 侧的日期解析库对"上个月"这种相对表述的语义是有歧义的（是自然月还是"距今 30 天"？含不含当天？），而这个语义只有模型能从上下文里判断。确定性的事情（格式化）交给代码，语义判断交给模型——这条分工原则在工具设计里反复出现。
4.3 工具变多以后：分层路由
先给一个实测的量级感，因为这个直觉很容易搞错。 我在一个内部系统上做过对照：同一批 40 个工具，全量注册给模型和按场景分成 5 组、每轮只给 8~10 个，在 100 条测试问题上的表现差异如下：
| 方案 | 选对工具率 | 该调而不调率 | 单轮平均输入 token |
|---|---|---|---|
| 40 个工具全量注册 | 约 82% | 约 9% | 高（工具 Schema 本身约 3.5k token） |
| 分组后 8~10 个 | 约 95% | 约 2% | 低（约 0.9k token） |
两个数字都值得看：准确率提升 13 个百分点，同时每轮输入 token 降到约四分之一。 后者是因为工具清单本身就是提示词的一部分——40 个工具的 JSON Schema，每一轮请求都要重新发一遍，在 1.2 节说的"一轮至少两次模型请求"之下，这笔开销要乘二。这就是"工具越多越贵"的机制。
分层的做法不复杂，关键是想清楚"按什么分组"：
（图 4：工具分层路由——规则优先、模型兜底；命中即收窄、未命中即放宽，让规则的副作用只有一个方向）
这张图的第一个判断是"规则优先，模型兜底"，这一点我要特别强调。 很多人的第一反应是"让模型做意图分类，决定走哪组工具"——问题是这样一来，你就要为"路由"再多付一次模型调用，而且路由本身也会错。 我实践下来的顺序是：
- 能从业务上下文确定路由的，绝不给模型选择权。比如这个接口本身就是"费用报销页"调用的，那就只挂费用域工具——这是零成本、零错误率的路由。
- 上下文只能部分确定的，用规则关键词做预筛（“订单”"单号"→订单域）。规则会漏，但漏掉的会落到兜底路径，不会答错。
- 确实无法判定的，才走全量 + 低温度兜底，并把这个比例作为监控指标（兜底率上升说明分层粒度划错了，是设计信号，不是运行故障）。
第二步里"规则会漏但不会答错"这一点值得解释： 我的路由规则设计成**“命中即收窄，未命中即放宽”**——也就是说，规则只负责"把范围缩小到某个域"，而不负责"排除其他域"。这样规则的副作用只有一个方向：命中时更准，未命中时退回到和现在一样。反过来设计（规则命中就只给这组、未命中就不给任何工具）会把"规则漏判"放大成"功能不可用"。
4.4 返回值设计：工具的输出会永久占用上下文
这一节讲一个几乎所有人都低估的成本项。 回到 1.3 节那张时序图的第三条：工具的执行结果会以"工具消息"的角色追加进对话历史。 这意味着它不只是"这一次请求的输入"，而是这一轮对话里后续每一次模型请求的输入。
把账算清楚： 假设一个工具返回 60KB 的 JSON（约 20000 token，按中文/JSON 混合估算），一轮工具调用是两次模型请求——第二次请求要把这 20000 token 全部带上。 如果这一轮里还有第二次工具调用，那么第三次请求要带上前两次的结果。这就是"单个工具返回值失控 → 整轮成本爆炸"的传导路径。
（图 5：工具返回值的瘦身路径——字段裁剪 / 条数截断 / 长文本截断，以及那条容易被忽略的纪律：截断必须显式告知模型）
这张图右侧的三件事有明确顺序，而且第三点是一条容易犯错的纪律。
① 字段裁剪：查询服务返回的实体往往有 30 个字段，模型真正需要的可能只有 6 个。 做法是不要直接把 ExpenseRecord 实体当返回值，而是定义一个专门给模型用的视图对象：
// 反面做法：直接把数据库实体返回给模型
// public List<ExpenseRecord> query(...) // 含 createdAt/updatedAt/operatorId/
// // version/tenantId/remarkInternal... 30+ 字段
// 正确做法：为"给模型看"定义一个精简视图
public record ExpenseRecordView(
String no, // 单号（模型引用它时需要精确，保留原格式）
BigDecimal amount, // 金额，单位：元（在描述里说明单位，避免分/元混淆）
String status, // APPROVED / REJECTED / PENDING
String rejectReason // 冗长字段，必要时截断
) {}
// 转换写在一处，便于审计"到底泄了哪些字段给模型"
private ExpenseRecordView toView(ExpenseRecord r) {
return new ExpenseRecordView(
r.getNo(),
// 分 → 元，在代码里做确定性换算，不要交给模型
r.getAmountInCents() == null ? null
: BigDecimal.valueOf(r.getAmountInCents(), 2),
r.getStatus(),
truncate(r.getRejectReason(), 200));
}
这段代码里有两个刻意的决定，都值得说。
第一，金额在代码里从"分"换算成"元"。 上面注释里说"不要交给模型"——原因是模型做单位换算这件事不可靠，而且失败得很隐蔽（它可能把 123456 分算成 1234.56 元，也可能算成 12345.6 元，取决于上下文里有没有提示）。凡是可以确定性完成的换算、格式化、聚合，一律在 Java 侧做完再给模型。 这条原则我会在 5.1 节列进十条原则里。
第二，rejectReason 用 truncate 截断到 200 字。 这个数字是经验值：驳回原因是模型最可能引用的字段之一，太短会丢关键信息，太长会推高 token。 200 字大致能覆盖"哪一条制度不符 + 需要补什么"的完整表述。
② 条数截断——而且截断必须显式告知模型。 这一点是 4.4 节里最容易被忽略的：如果你把一个 500 条的结果静默截断成 20 条返回，模型会认为"总共就这 20 条"，然后在回答里写"共 20 笔"——这是最危险的一类错误，因为它的输出看起来完全正常、数字也不假、只是漏了。
@Tool(description = "查询某员工的报销明细。最多返回 20 条；若总数超过 20 条，"
+ "返回值中的 totalCount 会大于 records 的长度，此时应在回答中说明"
+ "「已展示最近 20 条，共 N 条」，并提示用户可以缩小时间范围。")
public ExpensePage queryExpenseRecords(...) {
List<ExpenseRecordView> all = service.query(...);
return new ExpensePage(
all.size(),
all.stream().limit(20).map(this::toView).toList());
}
public record ExpensePage(int totalCount, List<ExpenseRecordView> records) {}
注意这里的做法：不是"截断了事"，而是"把截断这件事本身设计成返回结构的一部分"。 totalCount 与 records.size() 的差异是模型可以自己发现的信号，再配合描述里"此时应在回答中说明……"的指令，模型就能给出"已展示最近 20 条，共 N 条"这种诚实的回答。 这个模式的通用性是很好的：凡是"我给的只是子集"的场景，都要把"总量"作为显式字段一起给出去。
4.5 工具报错：不要回抛原始异常
工具在运行期失败是常态（下游超时、参数查不到、权限不足、数据为空）。这里有一个反直觉的判断：工具抛出的异常不应该被直接回传给模型。
为什么不回传？因为原始异常里混着两类信息：模型能用的、和绝对不能给模型看的。 一个 Java 异常栈里可能包含数据库表名、内网 IP、SQL 片段、甚至连接串。而"模型能看到’具体数据库错误’“和"用户能看到"之间只隔着一句"请你把刚才的错误信息原样告诉我”。
正确做法是把异常翻译成"模型可执行的下一步"：
@Tool(description = "查询某员工的报销额度使用情况。")
public QuotaResult getExpenseQuota(...) {
try {
return service.queryQuota(...);
} catch (UserNotFoundException e) {
// 给模型一句"可执行的下一步"，而不是技术细节
throw new ToolExecutionException(
"未找到该工号对应的员工。请先调用 find_user_by_name 获得正确工号后重试。");
} catch (DataAccessException e) {
// 技术细节只进日志，不进模型上下文
log.error("查询额度失败，userId={}", userId, e);
throw new ToolExecutionException(
"额度服务暂时不可用。请如实告知用户「暂时查不到，请稍后再试」，"
+ "不要推测具体数值。");
}
}
这段代码的分工很清楚：日志里留全部技术细节（供你排查），异常的 message 里只留"模型该怎么接"。 我特别建议在异常 message 里显式写上"不要推测具体数值"——因为模型在工具失败时有一个非常强的倾向：用自己的先验知识补一个"看起来合理"的数字。 这个倾向在提示词层面已经有了约束（4.1 节系统提示词第 2 条），但在异常路径上再写一次是有必要的，因为异常场景下模型的"补全压力"最大。
另有一条容易被忽略的纪律：区分"业务失败"与"系统失败"。 上面 UserNotFoundException 是业务失败（参数不对，模型可以通过换参数重试），DataAccessException 是系统失败（重试也没用，只会烧 token 和时间）。如果两类都返回"失败"，模型会对着下游故障反复重试——这和第 2 篇讲 429 退避是同一条纪律的另一种体现：重试必须有意义。
4.6 工具调用 + 结构化输出：把结果直接变成 Java 对象
当最后一个工具执行完，模型生成的是自然语言。但下游系统往往需要的是结构化数据。 Spring AI 的 .entity() 让这一步不需要手写解析：
// 场景：下游需要一个可以直接入库的结构化结果，
// 但数据来源是工具调用（模型必须先去查）
public record DispatchDecision(
String workOrderNo,
String assigneeId, // 建议的处理人工号
String reason, // 为什么派给这个人
int priority // 1-5
) {}
DispatchDecision decision = chatClient.prompt()
.user("把工单 " + no + " 派给合适的人")
.call()
.entity(DispatchDecision.class);
这里必须讲清一个边界，否则会踩坑：不要用模型做"需要确定性的裁决"。 这个例子里的 assigneeId 是模型从工具返回的候选列表里挑出来的——它是一次语义判断（“这个人擅长这类问题”），这没问题。但如果业务规则是"必须派给工单负责人，负责人不在则按代理链顺序下移"，那就不要交给模型——用工具把这个决策做完，让模型只负责叙述结果。
判断标准很简单：如果这个结果需要被审计、需要能解释成一条规则，就不要让模型决定它。 这条纪律和第 4 篇 6.4 节"不要用模型做金额裁决"是同一条。
4.7 循环控制：轮次、超时，以及什么时候该亲自接管
框架托管了循环，但它给的是"默认合理"的参数，不是"适合你的"参数。 这一节讲三个必须自己设的阀门。
第一，轮次上限。 默认行为在多数版本里是"模型不再要求调用工具就结束"，这个条件在模型"绕圈"时永远不会满足。绕圈是很常见的：工具返回"未找到"，模型换个参数再调，又"未找到"……一个 5 轮的循环在 token 上是单次问答的 6 倍。 我的建议是设一个硬上限（经验值 4~6 轮），并在触及上限时**返回"已达到工具调用上限"**而不是静默截断：
// 用工具执行选项控制上限；具体键名以你所用的 2.0.x 版本文档为准
ToolCallingChatOptions options = ToolCallingChatOptions.builder()
.toolNames("query_order", "find_user_by_name")
// 关键：给循环一个物理上限，避免模型"换个参数再试"式的绕圈
.internalToolExecutionEnabled(true)
.build();
第二，超时。 工具调用链上其实有三个独立的超时，它们必须满足 上面 < 下面 的关系，否则外层会先掐断、内层白干：
| 层级 | 超时对象 | 建议 | 配错的后果 |
|---|---|---|---|
| 模型调用超时 | 单次模型请求 | 30~60s | 太短：正常的长回答被掐断 |
| 工具执行超时 | 单个 Java 方法 | 5~15s（按下游 P99 定） | 太长：一个慢工具拖垮整轮 |
| 整轮超时 | 一次 call()（含所有轮次） | 工具超时 × 轮次上限 + 余量 | 太短：第 3 轮被外层掐断，前两轮的 token 白烧 |
这张表第三行是我见过最多配错的地方。 典型错误是：整轮超时设了 30 秒（因为"用户等不了太久"），但工具超时 10 秒、允许 4 轮——最坏情况需要 40 秒以上，于是"整轮超时"会变成一个高频错误，而且它的表现是"有些问题能答、有些问题报错"，看起来像模型不稳定，实际是超时参数互相矛盾。 我的做法是从下往上算：先定工具超时（按下游 P99），再算整轮 = 工具超时 × 轮次上限 + 模型调用时间余量。
第三，什么时候用 internalToolExecutionEnabled(false) 亲自接管。 关掉自动执行后，你会拿到"模型要求调用工具"的中间态，自己执行、自己决定是否继续。我在两种场景下会用它：一是需要审批的动作型工具（模型可以"提议"调用 cancel_order，但必须经人工确认后才真正执行）；二是需要把工具执行过程暴露给前端（比如前端要展示"正在查询订单…"的进度条）。除此之外我都用默认的自动执行——因为手写循环就要重新承担 1.4 节列的那六件事，包括最容易出错的那三件。
5️⃣ 进阶与优化
5.1 工具设计的十条原则
把前面散落的判断收成一张可执行的清单。这张表是我在项目评审时直接拿来当检查项用的：
| # | 原则 | 为什么 | 反例 |
|---|---|---|---|
| 1 | 一个工具只做一件事 | 复合工具迫使模型自己拆解，而拆解往往出错 | queryAndUpdateOrder() |
| 2 | 描述必须写"何时不用" | 相似工具间的选择靠排除法最有效 | 只写"查询订单" |
| 3 | 参数描述写"不是什么" | 阻止模型把用户原话直接塞进参数 | @ToolParam String userId 无描述 |
| 4 | 确定性工作留在 Java 侧 | 单位换算、格式化、聚合交给模型必错且隐蔽 | 让模型把"分"换算成"元" |
| 5 | 返回值只含决策需要的字段 | 结果会占用后续每一轮上下文 | 直接返回数据库实体 |
| 6 | 截断必须显式告知 | 静默截断会导致"漏报"型错误 | 500 条静默截成 20 条 |
| 7 | 身份类信息走 ToolContext | 模型可见即可被用户影响 | getQuota(String userId) 由模型填 |
| 8 | 写操作必须有幂等键 | 循环/重试/超时都可能重复执行 | cancelOrder(orderId) 无幂等保证 |
| 9 | 错误返回给"下一步"，不给技术细节 | 异常栈会泄内部结构 | 把 SQL 异常 message 直接回填 |
| 10 | 工具名一旦发布不改 | 名字是模型的契约，改名等于下线 | 重构时顺手改 name |
第 10 条是这十条里最容易被违反的，因为它看起来只是"命名"问题。 实际上 name 是写进提示词、被模型记住的契约——你把 get_expense_quota 改成 queryExpenseQuota，如果模型侧做了提示词缓存或者你的系统提示词里引用了工具名，行为会直接变化。所以我的做法是：@Tool(name=...) 显式写死，Java 方法名随便重构，工具名当 API 一样做版本管理（5.8 节）。
5.2 返回值瘦身：一个真实的 token 账
把 4.4 节的判断做成可量化的对照。这是我在项目上做的一次实际优化，数据我保留着：
| 优化项 | 优化前 | 优化后 | 单轮节省 |
|---|---|---|---|
| 字段裁剪（30+ 字段 → 6 字段） | 约 1.2k token/条 | 约 0.25k token/条 | — |
| 条数截断（全量 → Top20 + totalCount） | 最坏 200 条 | 固定 20 条 | 约 40k token |
| 冗长字段截断（500 字 → 200 字） | 约 0.4k/条 | 约 0.15k/条 | — |
| 长文本摘要（解析报告类工具） | 约 15k | 约 1.2k | 约 13.8k |
| 合计（以明细查询最坏情况计） | 约 245k token | 约 6.5k token | 约 97% |
"97%"这个数字看起来夸张，但它的口径必须说清楚，否则会误导人： 这是最坏情况（用户问"我今年所有报销"命中 200 条）下的对比。在常见情况下（查 5~10 条）节省幅度大约在 60%~80%。 我把最坏情况放在表里，是因为成本失控恰恰是由最坏情况决定的——平均成本好看，账单是被尾部撑起来的。
另外要注意一个反向风险：瘦身不能瘦到信息不足。 我曾经把 rejectReason 截到 50 字，结果模型在回答"为什么被驳回"时只说了"材料不全"就停了，而原文后半句是"材料不全，且发票抬头与报销主体不一致"。信息被截断之后，模型不会说"我这里信息不全"，它会用剩下的内容给一个看起来完整的答案。 这和第 6 篇要讲的 RAG 内容不够是同一类问题：模型对"我掌握的信息是否充分"的判断，远没有你可靠。
5.3 工具数量与选择准确率
这是本节最需要实测数据的一节，因为它直接决定你的架构（单层还是分层）。 我把上面 4.3 节那张对照表的完整版放在这里，并补上"工具名相似度"这个我认为被严重低估的变量：
| 工具集规模 | 名称相似度高（都含 query/get） | 名称相似度低（语义化命名） | 观察到的失败形态 |
|---|---|---|---|
| 5 个 | 约 96% | 约 98% | 偶发选错，可用描述修正 |
| 10 个 | 约 93% | 约 96% | 开始出现"该调A调了B"，但结果常仍沾边 |
| 20 个 | 约 86% | 约 92% | 明显下降；“不调"的比例上升快于"调错” |
| 40 个 | 约 78% | 约 88% | 出现"调了但不该调"（乱调），且不稳定 |
这张表里有两个判断我认为比数字本身更重要。
第一，“该调而不调"的比例上升快于"调错”，这是最容易被忽视的趋势。 因为不调是不会报错的：模型直接用自己的知识回答了，请求成功、HTTP 200、有自然语言回复——唯一的问题是答案是编的。 所以工具集规模膨胀的第一症状通常不是"调错工具"，而是**“准确率悄悄下降，但监控全绿”**。这就是为什么 5.7 节要把"工具调用率"当成核心指标而不是"调用成功率"。
第二，名称相似度的影响在 20 个工具以上时接近工具数量的影响。 上表 20 个工具时，"相似名"86% 对"语义化名"92%——差 6 个百分点，不需要增加任何代码，只需要重新命名。 这是个极便宜的操作，但我见过的绝大多数项目在这里都是"数据库风格的命名"：selectOrderByNo、queryOrdersByUser、getOrderDetail——三个都能匹配"查订单"，模型没有任何依据区分它们。 我把命名建议固化成一条规则：工具名必须包含"区分性词"，如果两个工具的名字去掉动词后仍然相似，就必须重新命名（例如 query_order_detail 与 query_order_status 是好的，get_order_a 与 get_order_b 是坏的）。
5.4 幂等与重试：写类工具的最大风险
这一节是本文风险最高的一节，因为它的失败后果不可逆。 前面所有内容都围绕"读"类工具展开，但一旦模型能调用写操作（取消订单、改状态、发通知、退款），你就进入了一个新风险等级。
风险从哪来？三个独立的重试源：
（图 6：写操作被重复执行的三个独立重试源，以及幂等键为什么必须由服务端生成）
这张图里我想强调三点。
第一，“第二次执行报错"不等于"安全”。 取消订单第二次执行会返回"已取消"，看起来无害，但它消耗了一轮模型请求；而"加积分"第二次执行是静默的成功——从日志上看两次都成功，从数据上看余额翻倍。所以"是否幂等"要按"重复执行会不会产生新的业务效果"判断，而不是按"会不会抛异常"判断。
第二，幂等键必须由服务端生成，不能由模型生成。 如果让模型提供 idempotencyKey，它每次调用都会生成一个新的（因为它是"生成文本"，而文本每次不同），幂等设计就完全失效了。 正确做法是幂等键在会话层生成一次，随 ToolContext 注入（2.4 节），同一次用户意图内的多次工具调用共享同一个键。
第三，那条"绝不自动重试"的纪律在第 2 篇、系列一第 11 篇都出现过，这里必须第三次强调，因为写类工具把它从"性能问题"变成了"数据问题"。 具体到配置上，如果模型侧或网关侧配置了失败重试，必须排除这两类情况：流式响应已开始输出、工具已执行。 我不建议在工具调用场景下开启任何形式的"自动重试工具执行"——要做补偿，也应该用业务补偿（查一下到底成没成），而不是重试。
5.5 成本账：把每一笔算清
把 1.2 节"一轮至少两次模型请求"这个事实算成具体的账。 下表是一次"查询 + 回答"的典型成本构成（以工具集 10 个、工具返回值经瘦身后约 1.5k token 为例）：
| 项目 | 第 1 次请求 | 第 2 次请求 | 说明 |
|---|---|---|---|
| 系统提示词 | ~400 token | ~400 token | 每次都带 |
| 工具 Schema（10 个） | ~900 token | ~900 token | 工具清单本身也是输入 |
| 用户问题 | ~50 token | ~50 token | — |
| 对话历史 | — | ~50 token | 第 2 次会带上第 1 次的用户消息 |
| 模型输出的工具调用指令 | — | ~80 token | 第 1 次的输出 |
| 工具执行结果 | — | ~1500 token | 瘦身后的值；瘦身前可能 40k+ |
| 输入合计 | ~1350 | ~2980 | — |
| 输出合计 | ~80 | ~300 | 第 2 次是自然语言回答 |
结论：一次带工具调用的问答，输入 token 约是纯对话的 2~3 倍。 这个倍数是结构性成本，不是可以优化掉的浪费——但它是可以"设计"的。 三个最有效的杠杆按性价比排序：
- 瘦身工具返回值（5.2 节，收益最大且不损失能力）；
- 裁剪工具清单（4.3 节，收益同时体现在准确率和成本两侧）；
- 收敛系统提示词长度（最容易失控，因为它是"所有人都在往里加"的一处）。
第三个杠杆值得单说。 系统提示词的膨胀是组织性现象：每个新需求都在往里面加一条规则，半年后它变成 3000 token，而它要被每一次模型请求携带。 我的做法是给系统提示词设一个硬预算（例如 800 token），加规则时必须删或合并——这条预算约束比任何优化技巧都有效，因为它把"膨胀"变成了一个必须显式决策的问题。
5.6 权限：三层防御
这一节把 2.4 节的 ToolContext 纪律扩展成一套可落地的结构。 我的立场是：工具调用的权限不能只有一层，因为每一层的失效方式不同。
（图 7：工具权限的三层防御——工具集裁剪 / 参数级授权 / 审计兜底，每层都假设上面一层已经失效）
这张图的核心设计思想在最后那句话：每一层都假设上面一层已经失效。
第一层（工具集裁剪） 的成本极低但收益明确：一个查不到的工具，模型就不可能调用它。 这比"调用时再判断权限"要安全——因为它把风险从"运行时判断"变成了"部署时不可能"。 这一层的失效方式是角色判定错误（比如把管理员角色错判给普通用户），但即使判错，影响面也被限制在那个角色的工具集内，不会瞬间变成全量能力。
第二层（参数级授权） 是真正的核心，它有两个必须做的检查：一是身份来自 ToolContext（2.4 节）；二是业务对象的归属校验：
@Tool(description = "取消订单。仅能操作本人名下的订单。")
public CancelResult cancelOrder(
@ToolParam(description = "订单号，例如 SO20260927001") String orderNo,
ToolContext context) {
String userId = (String) context.getContext().get("trustedUserId");
if (userId == null) {
throw new ToolExecutionException("缺失可信身份上下文，拒绝执行。");
}
// 关键：归属校验不能省。模型完全可能被诱导去取消别人的订单
// （例如用户说"帮我取消我同事那个订单，单号是 XXX"）
Order order = orderRepository.findByNo(orderNo);
if (order == null) {
throw new ToolExecutionException("订单不存在，请确认订单号。");
}
if (!order.getOwnerUserId().equals(userId)) {
// 注意：这里不要让模型"换个方式再试"，要明确终止
log.warn("[越权尝试] user={} 试图取消 owner={} 的订单 {}",
userId, order.getOwnerUserId(), orderNo);
throw new ToolExecutionException("无权操作该订单。请告知用户只能操作本人订单。");
}
return orderService.cancel(orderNo, userId);
}
这段代码里我要特别指出那个"用户说帮我取消我同事的订单"的场景——它是最典型的间接提示注入。 用户没有说"我是别人"，他只是提供了一个不属于自己的订单号。 如果工具只做了"身份来自 ToolContext"而没有做"归属校验"，这个请求会成功执行。 这就是为什么第一层和第二层必须同时存在：ToolContext 解决"我是谁"，归属校验解决"这个东西是不是我的"，两者是两个独立的问题。
第三层（审计） 的价值在于它不试图阻止，只试图发现。 我在上面代码里的 log.warn("[越权尝试] ...") 就是这一层的最小实现。它必须包含三重信息：谁、想做什么、为什么被拒。 因为没有它，你无法区分"模型在乱试"和"有人在试探"，而这两种情况的处置完全不同（前者要改描述/收窄工具集，后者要封号）。同时注意"越权尝试率"应该是一个被监控的指标——它的突然上升本身就是攻击信号。
5.7 可观测性与测试：怎么知道工具真的在工作
先讲一个残酷的事实：工具调用是 AI 应用里最难"看"到的一层。 因为它发生在"框架内部 + 模型侧"，你的业务日志里只会看到"请求进来了、回答出去了"，中间过程全是黑的。 所以这一节的第一个建议是必须把中间过程显式记录下来：
// 记录什么？这五个字段缺一个，出问题时就要靠猜
public record ToolCallRecord(
String traceId, // 关联整轮请求，2. 定位是哪一次问答
String userId, // 1. 谁触发的（含权限排查）
String toolName, // 3. 用了哪个工具
String argsDigest, // 3. 参数摘要（脱敏 + 截断，不要记全量）
long costMs, // 4. 耗时（定位慢工具）
int resultBytes, // 4. 结果体积（定位 token 爆炸）
String status // 5. OK / BIZ_FAIL / SYS_FAIL（区分两类失败）
) {}
为什么是这五个字段？因为它们分别对应五类不同的故障： userId 对权限问题；toolName 对"该调不调/调错"问题；costMs 对"用户觉得慢"问题；resultBytes 对成本问题（这是最容易被漏掉的——token 账单异常时，你第一个要看的就是有没有哪个工具返回了巨量结果）；status 对"业务失败被当成系统故障重试"问题。
然后是我认为比可观测性更重要的一件事：测试策略。 工具调用有四层需要分别测，混在一起测是无效的：
| 测试层级 | 测什么 | 怎么测 | 通过标准 |
|---|---|---|---|
| L1 单元测试 | 工具方法本身的业务逻辑 | 直接 new ExpenseTools(mockService) 调方法 | 常规单测标准 |
| L2 契约测试 | 工具是否被正确注册、名称是否重名、参数 Schema 是否正确 | 从 ApplicationContext 取出所有 @Tool，断言名称集合与预期一致 | 名称集合完全匹配（改一个名字必须改测试） |
| L3 选择测试 | 模型会不会选对工具 | 100 条真实问题 → 断言"实际调用的工具集"包含期望工具 | 选对率 ≥ 95% |
| L4 回归集 | 参数构造是否正确 | 断言工具调用时的参数值（尤其日期、单位、ID 格式） | 参数错误率 = 0 |
L2 和 L3 是这套里最有价值、也最容易被省略的两层。
L2 契约测试解决的是 3.2 节那个"工具名重复被静默覆盖"的故障——它必须在 CI 里跑，因为这类问题的表现是"某个工具永远不被调用"，人工测试发现不了。
@Test
void 工具契约应保持稳定() {
// 这个断言的真正价值：任何一次"顺手改名"或"误加重复名"都会让 CI 失败
Set<String> actual = toolRegistry.allToolNames();
Set<String> expected = Set.of(
"get_expense_quota", "query_expense_records", "aggregate_expense",
"query_order", "update_order_status", "cancel_order",
"find_user_by_name");
assertEquals(expected, actual,
"工具名集合发生变化。若为有意变更，请同步更新系统提示词与本文档。");
}
L3 选择测试解决的是 5.3 节那个"准确率悄悄下降"的故障。它的关键设计是断言"工具集合"而不是断言"回答内容"——因为回答内容会因模型随机性而波动，而"调用了哪个工具"是布尔事实，可以作为稳定断言。 下面是一个可行的断言写法：
@Test
void 额度类问题应调用额度工具而非明细工具() {
String answer = chatClient.prompt()
.user("张三还剩多少报销额度？")
.call().content();
Set<String> called = TestToolCallRecorder.lastCalledTools(); // 测试期埋点记录
assertTrue(called.contains("get_expense_quota"),
"应调用 get_expense_quota，实际调用：" + called);
assertFalse(called.contains("query_expense_records"),
"不应调用明细工具（这是 4.2 节描述里'何时不用'要拦住的情况）");
}
这段测试代码同时是一项"回归护栏"：它把 4.2 节那些容易失效的描述纪律，变成了一个 CI 会替你检查的约束。 以后有人改坏了工具描述导致模型选错，这次测试会红——这是把"提示词工程"这种看起来软的工作，变成可验证工程产物的关键一步。
5.8 工具的版本演进
工具名是给模型的契约，所以它需要版本管理，但不需要"版本号"。 我的做法是三条：
第一条，name 一经发布不修改、不复用。 不修改的原因见 5.1 节第 10 条。不复用的原因是更隐蔽的风险：如果 query_order 被废弃后又被复用成另一个语义，那么"曾经学会用它的提示词缓存/微调模型/历史对话"会指向一个错误的行为。 废弃工具的正确做法是从注册列表里移除（而不是改名保留），并观察一段时间"是否还有请求在引用它"。
第二条，参数的演进只能"加可选、不能改含义"。 增加一个带默认值的可选参数是安全的；把一个参数的含义改掉（例如 date 从"提交日期"改成"审批日期"）是破坏性的，因为模型的行为会按旧语义生成参数。如果必须改含义，正确做法是新增一个参数名，两个并存一段时间，再从提示词里逐步弱化旧的。
第三条，描述可以随时改，但要跑 L3 选择测试。 描述是唯一可以"自由迭代"的部分——它不影响任何代码契约，只影响模型行为。所以描述优化应该是一个持续动作：每次发现"该调不调"的 case，就回来改描述，然后跑 L3 回归。 这也是我在这一篇里反复强调"描述是核心工程技能"的最终落点：它是这套系统里唯一一处"改一行字就能改变行为、且能立刻验证"的地方。
6️⃣ 适用边界与风险提示
6.1 什么时候不该用工具调用
这一节和前面同样重要。工具调用是有成本的能力，滥用它会把简单问题复杂化。
场景一：确定性的、高频的业务操作。 如果"给订单加备注"这个操作在你的系统里每天执行 10 万次、且业务流程明确，那它应该是一个接口，而不是一个工具。 判断标准是：当"要不要执行"不需要任何语义判断时，就不该让模型参与决策。 加一次模型调用意味着成本增加 2~3 倍、延迟增加数百毫秒到数秒——用它来替代一个 if 语句是纯粹的浪费。
场景二：需要严格顺序与事务保证的多步操作。 比如"扣库存 + 生成订单 + 发通知"必须在一个事务里。不要让模型依次调用三个工具来完成它——中间的失败无法回滚，而且模型可能改变调用顺序。正确做法是把这个事务封装成"一个工具"，内部用你的领域服务保证一致性。
场景三：需要完全可预测的精度与格式。 例如生成一份固定格式的对账单。模型擅长语义判断，不擅长"百分之百按格式输出"——它会偶发地省略一位小数、把日期格式换个写法。这类任务应该用模板引擎，模型只负责"找出需要填的内容"。
场景四：输出需要被审计、需要能解释成一条规则。 前面在 4.6 节提过（金额裁决、审批归属）。这条界限的判据是：如果监管/内审问你"这个结论是怎么得出的"，你必须能用一句规则回答，那么这个决策就不能由模型做。
场景五：下游系统对调用频率极度敏感。 模型可能在一轮里连续调用同一个工具 3~4 次（换个参数重试），如果下游是有严格配额或费用的第三方接口，这会造成真实损失。 这类工具必须加"每轮调用次数上限"。
6.2 五个必须知道的风险
| 风险 | 机制 | 缓解措施 |
|---|---|---|
| 间接提示注入 | 用户通过对话诱导模型调用越权工具（5.6 节的"帮我取消同事的订单"） | 三层防御；归属校验不可省；越权告警 |
| 重复执行写操作 | 模型重试 / 框架重试 / 人工重试三个源（5.4 节） | 幂等键由服务端生成；关闭工具执行的自动重试 |
| 成本失控 | 返回值过大 + 轮次过多 + 工具清单过长（5.5 节） | 返回值瘦身；轮次上限；工具清单裁剪 |
| 静默失效 | 工具没注册上/名称重复/描述改坏 → 只是"不用它"，不报错（3.2、5.7 节） | 启动自检 + L2 契约测试 + L3 选择测试 |
| 版本漂移 | 升级 Spring AI 或换模型后，工具调用行为变化（含 1.1.x → 2.0 的执行位置变化） | 固定版本；升级必跑 L3+L4 回归集；模型切换先测选择准确率 |
其中"版本漂移"要单独强调一句，因为它和本文的版本声明直接相关。 工具调用是 Spring AI 2.0 重构幅度最大的部分，也是模型侧行为差异最大的部分。换模型（哪怕是同一家的不同版本）后，工具选择的行为可能变化——我遇到过同一个工具集在 qwen-plus 与另一个模型上选对率相差十多个百分点，而这在代码层面完全看不出来。 所以 L3 选择测试的另一个用途是"模型切换的准入测试"：选对率不达标就不切。
6.3 生产建议清单
- 提示词里的硬约束必须显式写（“涉及数值一律调工具，禁止自行计算”）——不要指望模型的默认行为。
- 工具描述按"何时用 / 何时不用 / 返回什么 / 前提限制"四段写，缺一段都是技术债。
- 有权限含义的参数一律走
ToolContext，并优先设计成零参数工具。 - 所有写类工具必须带幂等键，且键由服务端生成。
- 返回值只给决策需要的字段；截断必须暴露总量。
- 轮次上限、工具超时、整轮超时三个数必须从下往上算，不能各拍各的。
- 工具调用的五要素必须进日志（身份、工具名、参数摘要、耗时、结果体积）。
- CI 里必须有 L2 契约测试（工具名集合断言）；定期跑 L3 选择测试。
- 系统提示词设 token 预算，防止组织性膨胀。
7️⃣ 总结
7.1 回到开头那个问题
第 1.1 节那个"张三还剩多少额度"的问题，现在有了完整的答案：它不是 RAG 的问题，也不是模型不够强的问题，而是"答案不在知识里，在系统里"这个定位错误的问题。 我们在第 4 篇结尾划的界线——语义问题走 RAG，数值与统计问题走结构化查询——在这一篇里落成了具体机制：把 Java 方法注册成工具，让模型当路由器。
但这一篇真正的收获不是"学会了 @Tool 注解"。 而是四个判断：
第一，模型从不执行代码，它只生成"我要调用什么"的结构化文本。 这一个事实推出了后面所有的工程纪律——权限必须在框架侧（2.4 节），异常必须翻译（4.5 节），重试必须有意义（5.4 节）。
第二，工具描述是决定成败的变量，而不是附带的注释。 实测数据显示，光是把工具名从"数据库风格"改成"语义化命名"，在 20 个工具规模下就能带来约 6 个百分点的选对率提升（5.3 节）——这是整个系统里性价比最高的一项优化。
第三，"工具的循环"必须交给框架，但"循环的参数"必须自己设。 框架解决的是 1.4 节那六件事（尤其最容易出错的参数校验、角色配对、分片拼装）；而轮次上限、三层超时、幂等策略这些参数，框架给的是默认值，不是你的最优值。
第四，也是最反直觉的一条：工具调用最大的风险不是"答错"，而是"静默"。 答错至少能被发现；而"该调不调"（模型自己编）、“工具没注册上”（永远不被调用）、“结果被静默截断”（漏报）这三类问题，请求全部成功、监控全部绿色、日志里什么都没有。 所以 5.7 节把可观测性与测试放在一起讲——在这一层，能"看见"比能"写对"更重要。
7.2 核心决策点回顾
| 决策点 | 选择 | 核心理由 |
|---|---|---|
| 语义 vs 数据 vs 动作 | RAG / 工具 / 工具+权限闸门 三路分流 | 三类问题的答案位置不同，解法不可互换 |
| 循环自己写还是交框架 | 交框架（默认自动执行） | 手写最贵的是三类"第二轮才暴露"的故障（1.4 节） |
| 身份类信息怎么传 | ToolContext 可信旁路 | 模型可见的参数即可被用户影响；优先零参数工具 |
| 返回 POJO 还是拼接文本 | 默认 POJO，字段名要短 | 结构化省 token 且可精确引用；文本仅用于解释性结果 |
| 工具数量策略 | 默认集 + 按名裁剪 + 分层路由 | 40 个工具时选对率约 78%，分组后约 95%、token 降到 1/4 |
| 返回值怎么处理 | 字段裁剪 + TopN + 显式总量 | 结果占用后续每一轮上下文；静默截断导致漏报 |
| 错误怎么返回 | 只给"下一步"，不给技术细节 | 异常栈会泄露内部结构；区分业务失败与系统失败 |
| 写操作的重复执行 | 服务端生成幂等键 + 关闭自动重试 | 三个独立重试源；"第二次也成功"是最危险的形态 |
| 轮次与超时 | 从下往上算：工具 → 模型 → 整轮 | 参数互相矛盾会表现为"偶发失败" |
| 怎么知道它工作正常 | 五要素日志 + L2 契约 + L3 选择测试 | 本层故障以"静默"为主，唯有多层校验才能发现 |
7.3 下一步
这篇让模型能"做事"了，但还有一个更基础的问题没解决：框架选型。 我们这一路用的都是 Spring AI，但如果你团队的项目不是 Spring Boot、或者需要更广的模型/向量库覆盖、或者你现在正卡在"Boot 3.5 已于 2026-06-30 EOL，但升 Boot 4 的代价还没评估清楚"这个岔路口上——那么这个问题必须正面回答。
下一篇就来处理它：LangChain4j vs Spring AI：Java AI 框架怎么选。 那一篇我会做三件事：用同一件需求（聊天 + 工具 + RAG）在两套框架里各写一遍代码，把差异从"功能清单"拉回到"你的代码会长成什么样"；给出十个维度的逐项对比，并说清每个维度在什么条件下会变成决定项；以及我认为最被低估的一条——选型真正的成本不是"功能差多少"，而是"未来三年你跟不跟得上它的版本节奏"。Spring AI 2.0 强制要求 Spring Boot 4，LangChain4j 支持 Boot 3.5 到 Boot 4 并且能跑在 Quarkus/纯 Java 上——这一个事实，对很多团队来说比所有功能对比都重要。
如果你觉得这篇有用，或者你们团队在工具设计上踩过别的坑，欢迎在评论区交流。 下一篇见。
参考资料
- Spring AI Reference Documentation · Tool Calling（
@Tool/@ToolParam/ToolCallback/ToolCallingManager与工具执行机制）：https://docs.spring.io/spring-ai/reference/api/tools.html - Spring AI Reference Documentation · ChatClient（
defaultTools/tools()/ 请求级覆盖与 Advisor 链）：https://docs.spring.io/spring-ai/reference/api/chatclient.html - Spring AI Reference Documentation · Advisors（
ToolCallingAdvisor在链上的位置与顺序约束）：https://docs.spring.io/spring-ai/reference/api/advisors.html - Spring AI Reference Documentation · Observability（工具调用的观测埋点与
include-content开关）：https://docs.spring.io/spring-ai/reference/observability/index.html - Spring AI Reference Documentation · Structured Output（
.entity()将模型输出映射为 Java 对象）：https://docs.spring.io/spring-ai/reference/api/structured-output-converter.html - Spring AI GitHub ·
ToolCallingManager/DefaultToolCallingManager与ToolContext源码（可信旁路的实现依据）：https://github.com/spring-projects/spring-ai - Spring AI GitHub · 2.0 升级说明与工具调用重构相关 issue（1.1.x → 2.0 的行为差异）：https://github.com/spring-projects/spring-ai/releases
- 阿里云百炼 · 通义千问 Function Calling 文档（工具定义格式、并行工具调用与参数约束）：https://help.aliyun.com/zh/model-studio/
- OpenAI Platform Documentation · Function Calling（
tool_calls协议与多轮回填的角色约定）：https://platform.openai.com/docs/guides/function-calling
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/sinat_41617212/article/details/169748248
