背景

最近在用 Spring AI 接工具调用时，我遇到过一个很典型的问题：模型明明收到了用户问题，回答里也像是在“思考”，但就是不触发 Tool Calling。日志没有报错，接口也能正常返回，看起来像是“功能可用”，但核心链路其实没有走通。

这种问题很容易让人先怀疑模型能力，或者一股脑去改 Prompt。后来我复盘了一下，真正高频的问题大多集中在下面 5 个方向。

1. 先看工具有没有真的注册进去

很多时候不是模型不调用，而是应用压根没有把工具正确暴露给 Spring AI。

我一般先确认三件事：

• Tool 对应的 Bean 是否真的被 Spring 扫描到
• 方法签名是否符合当前使用版本的约定
• 发起调用时是否把工具集合传给了 ChatClient 或 Advisor

如果工具没有进入模型可见范围，再好的 Prompt 也没用。

2. 工具描述写得太虚，模型不知道什么时候该调

Tool Calling 能不能触发，和工具描述质量关系很大。很多人只写一句“查询数据”或者“执行操作”，这对模型来说信息太少了。

更稳妥的写法应该包含：

• 这个工具是干什么的
• 在什么场景下应该调用
• 输入参数分别代表什么
• 返回结果会提供什么信息

如果描述不清，模型往往会直接用自然语言“猜答案”，而不是发起工具调用。

3. Prompt 把模型引到了纯文本回答上

我见过一种常见写法：系统提示里反复强调“请直接回答用户问题”“尽量给出完整结论”。这种写法看起来没问题，但它会弱化模型调用工具的意愿。

更合理的方式是明确告诉模型：

• 遇到需要实时数据、外部系统数据、内部接口结果时优先调用工具
• 如果信息不足，不要编造结论
• 调完工具后再组织最终回答

Tool Calling 场景里，Prompt 不是越像文章写作越好，而是越像“任务约束”越好。

4. 模型本身或配置不支持当前能力

有时问题并不在代码，而在模型或网关配置上。比如：

• 当前接入的模型版本不稳定支持 Tool Calling
• 网关把工具相关字段过滤掉了
• 中间层做了字段转换，导致请求格式和模型期望不一致

这类问题最容易被忽略，因为业务代码里看不出明显异常。排查时我会直接抓请求体和响应体，确认工具定义有没有真正发到模型侧。

5. 没有把日志打到“能定位问题”的粒度

如果日志里只有“开始调用模型”和“模型返回成功”，那基本查不动。至少应该补这些信息：

• 本次请求传了哪些工具
• 系统提示和用户提示是什么
• 模型原始返回里有没有 tool call 相关字段
• 工具执行前后的参数和耗时

很多 Tool Calling 问题不是不会修，而是日志不够，导致每次都像在猜。

一个更实用的排查顺序

如果你也遇到“死活不触发”的情况，我建议按这个顺序查：

1. 先确认工具有没有注册成功
2. 再确认请求里有没有把工具真正带上
3. 再看工具描述是否足够明确
4. 再检查系统 Prompt 是否压制了工具调用
5. 最后确认模型和网关链路是否支持

这个顺序的好处是从本地代码到外部依赖逐层收缩，效率会比到处改 Prompt 高很多。

总结

Tool Calling 不触发，很多时候并不是“模型太笨”，而是工程链路里某一层没有对齐。我的经验是，先查注册、再查描述、再查 Prompt、最后查模型和网关，通常都能比较快定位到问题。

如果后面要继续做 Spring AI 落地，我会更建议把这套排查顺序固化成清单，因为它真的比临场猜原因省时间得多。