上个月我在给一套订单系统做 AI 问答助手，第一个被问倒的问题不是什么高深架构，而是用户随口一句：“我上周买的那个包裹现在到哪了？”我一开始用的是 Spring AI Alibaba 里最普通的 ChatClient 对话模式，结果大模型非常礼貌地回了一段物流描述——查无此单。它不是不想回答，而是它根本“不知道”。这个问题恰恰是 Tool Calling 函数工具调用技术要解决的：让模型在需要时，主动伸手去调用你写的 Java 方法，拿真实数据再继续回答。
这篇文章写给两类读者：一是刚学 Spring AI Alibaba、想搞懂 Tool Calling 到底怎么用的新手；二是已经在做“玩具 Demo”，想往生产环境接业务系统的人。我会从概念讲到多工具协作，再到框架底层链路，最后把我踩过的坑全部摊开，尽量不让你再走一遍弯路。
1. Tool Calling 不是“API 调用”，而是让模型学会“伸手要数据”
1.1 先搞清楚模型“编答案”和“调工具”的本质区别
很多新手会把 Tool Calling 理解成“在代码里调用一次 HTTP 接口”，然后让大模型在回复里引用结果。这种理解不算全错，但会严重限制你的设计思路。
我习惯用一个类比来解释：一个大语言模型，本质上是一个“被关在图书馆里、读过海量书籍但不能出门的博学读者”。你问它“法国大革命发生在哪一年”，它能秒答，因为书里有。但你问它“现在杭州室外温度多少”，它只能猜，因为图书馆的书不会实时更新。更麻烦的是，如果你问“我的订单现在到哪了”，它连“你的订单”长什么样都不知道——这是你私有系统里的数据。
Tool Calling 解决的，就是给这位博学读者配了一部电话。它遇到自己不知道、但是“可以通过某种方式查到”的问题时，不再硬编答案，而是主动拨电话给一个外部函数，把问题拆成参数传过去，等函数把结果返回，再基于真实结果组织语言。
整个过程的核心在于：决定调用哪个工具、参数怎么填、要不要连续调用多个工具，都是模型在生成回复时自主做出的，不是你在代码里写死的 if-else。你的职责是“把函数注册给模型”，并把函数签名和用途描述清楚。
1.2 一次典型的 Tool Calling 调用链路长什么样
以 Spring AI Alibaba 为例，一次完整链路大致是这样的：
- 用户输入：“杭州今天天气怎么样？”
- 模型收到消息后，发现“实时天气”属于自己知识盲区，而对话上下文中恰好有一个注册过的
getWeather(city)工具。 - 模型返回的不是普通文本，而是一个“工具调用指令”：
工具名 = getWeather，参数 = {"city": "杭州"}。 - 框架（Spring AI Alibaba）收到指令，在工具注册表中找到对应的 Java 方法，反序列化参数，通过反射执行你的方法。
- 方法返回一个 JSON 字符串，框架把结果作为一条“工具响应消息”回传给模型。
- 模型拿到结果后，把“杭州 26℃、多云、湿度 68%”组织成一句自然语言回复给你。
这里最反直觉的一点是：真正干活的不是模型，是你的 Java 方法；但“让谁干活”的决策权在模型手里。参数化、选择、多步规划都发生在模型侧，Java 侧只负责“把方法写好、把描述写清楚、把结果返回对”。
1.3 哪些场景适合用 Tool Calling，哪些不适合
从我实际接入的经验看，以下场景收益最大：
- 实时/动态数据查询：天气、股价、库存、汇率。
- 用户私有数据：订单状态、账户余额、审批进度。
- 写操作：创建工单、提交请假、发送通知——这类场景建议加人工确认，后面我会细说。
- 需要计算的：比如“帮我算一下这个月加班总共多少小时”。
不适合的场景也别硬上。如果你的业务逻辑是确定的、可枚举的，直接在代码里走分支判断，比让模型“思考”更便宜、更稳定；如果流程特别低频且固定，也没必要为它单独注册工具。Tool Calling 的价值在于“模型用自然语言把问题拆解成可执行动作”，它的优势场景一定是开放式的、需要实时数据的对话交互。
2. 搭好 Spring AI Alibaba 开发环境，坑我先替你踩一遍
2.1 生成工程与依赖引入
我建议直接通过 Spring Initializr 或官方提供的工程生成站点创建 Spring Boot 3.x 项目，Java 版本选 17 或 21。生成时直接勾选 Spring AI Alibaba 相关依赖；如果没有对应选项，可以手动加依赖管理。
我当前项目里用的是 Spring Boot 3.2.x + Spring AI Alibaba 1.x，下面是最小化的依赖配置。版本号我没有写死，因为不同小版本 API 有些微差异，建议以官方 BOM 为准。
<dependencyManagement> <dependencies> <dependency> <groupId>com.alibaba.cloud.ai</groupId> <artifactId>spring-ai-alibaba-bom</artifactId> <version>${spring-ai-alibaba.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.alibaba.cloud.ai</groupId> <artifactId>spring-ai-alibaba-starter</artifactId> </dependency> </dependencies>如果你在生成本地工程时遇到依赖拉不下来，优先检查 Maven 仓库配置和版本是否存在。实测下来，用国内云效镜像比自己改中央仓库地址稳得多。
2.2 配置文件里最容易忽略的几项
工程建好之后，配置application.yml。不同版本配置前缀有差异，我见过两种：旧版前缀是spring.ai.dashscope.*，新版可能是spring.ai.alibaba.dashscope.*。不要背，最快的确认方式是打开本地依赖里的 autoconfigure 包，看一眼属性类上的@ConfigurationProperties前缀。
spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.7如果你的版本前缀不同，改成对应写法即可。api-key 强烈建议放在环境变量里，别硬编码进仓库。这里还有个隐蔽问题：很多人配了 key 但没配 model，结果默认模型又老又慢。另外temperature在工具调用场景下建议调低一点，比如 0.3 到 0.7。温度太高，模型的参数生成会不稳定，明明该传{"city": "杭州"}，它可能给你传{"city": "杭州市"}，后面处理起来很麻烦。
2.3 先跑通不带工具的基础对话
不要一上来就写工具，先确认模型通道是通的：
@RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient = builder.build(); } @GetMapping("/chat") public String chat(String message) { return chatClient.prompt() .user(message) .call() .content(); } }这一步看似多余，但能把“配置问题”和“工具逻辑问题”分开排查。很多新手一上来就 debug 工具为什么没被调用，结果折腾半天发现是 api-key 写错了，浪费一晚上。
3. 第一个工具方法：@Tool 注解让查询函数“上桌”
3.1 代码怎么写：一个带 @Tool 的天气查询方法
我把这个案例称为“Hello Tool Calling”：一个根据城市查询天气的工具。为了演示，我直接返回 mock 数据，你替换成真实天气 API 的逻辑即可。
import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.Parameter; import org.springframework.stereotype.Component; @Component public class WeatherToolService { @Tool(description = "根据城市名称查询实时天气，返回温度、天气状况和湿度。") public String getWeather( @Parameter(description = "城市名称，例如：杭州、北京") String city) { // 这里对接真实天气API，或按城市读取mock数据 return "{\"city\": \"" + city + "\", \"temperature\": \"26℃\", \"condition\": \"多云\", \"humidity\": \"68%\"}"; } }注意几个关键点：
- 类上标注
@Component，交给 Spring 管理。 - 方法必须是
public，且不能是static。原因后面讲框架反射时再展开。 @Tool注解带description，这是模型判断“要不要用这个工具”的核心依据。- 方法参数上的
@Parameter(description = "...")会被转换成模型的 JSON Schema，模型照着 schema 来填参数。 - 返回类型建议统一为
String，内容是 JSON 字符串，方便模型解析。
然后在调用处注册并测试：
String answer = chatClient.prompt() .user("杭州今天天气怎么样？") .tools(new WeatherToolService()) .call() .content(); System.out.println(answer);运行后如果一切正常，你会得到类似这样的回答：“杭州今天多云，气温 26℃，湿度 68%。”而不是模型瞎编的“杭州今天晴，23℃”。说明模型确实调用了你的方法，而不是从训练数据里猜。
3.2 工具描述与参数描述为什么直接决定效果
这一节是新手最忽略、但其实性价比最高的点。模型看不懂你的 Java 代码，它只看得懂你写的描述。框架会把@Tool的description、方法名、@Parameter的description拼成一段 JSON Schema 描述，塞进模型请求的 tools 参数里。模型完全靠这段描述来理解“这个工具是干嘛的”“参数该怎么填”。
我用两个写法对比说明：
写法 A（模糊）：
@Tool(description = "查询订单信息") public String getOrder(String id) { ... }写法 B（清晰）：
@Tool(description = "根据订单号查询电商订单详情，返回订单状态、商品列表、金额和收货地址。") public String getOrder( @Parameter(description = "订单号，例如：SO20250618001") String orderId) { ... }写法 A 的问题在于：用户说“帮我看看那个键盘发货了没”，模型不知道该不该用这个工具，因为“订单信息”到底指什么、方法参数id是订单号还是用户 ID，全部靠猜。一旦有多个相似工具，模型选错工具的概率直线上升。写法 B 的每一个描述都在告诉模型：什么时候用、参数是什么格式、返回什么内容。
这就像给新同事交接一个接口，你只写“查订单”，对方必然来问东问西；你把入参、返回、典型场景写清楚，对方才能准确接活。
提示：如果你发现模型经常不调用工具，或者调用了但参数填错，先别急着怀疑框架，回去读一遍自己写的 description 是否足够“把话说死”。
4. 从“单工具”到“多工具协作”：订单查询与物流跟踪实例
4.1 注册多个工具，模型怎么选
单工具跑通之后，下一步就是多工具协作。这是 Tool Calling 真正体现价值的地方，也最能暴露设计问题。
我还是用订单系统的例子。用户问“我的包裹到哪了”，模型实际上需要两步：先拿到最新订单号，再用订单号查物流。如果只注册一个工具，模型会卡在“没有订单号”这一步。所以我们设计两个工具，让模型自己完成信息传递：
@Component public class OrderToolService { @Tool(description = "查询用户最近一笔订单信息，返回订单号、商品名称、下单时间和订单状态。") public String getLatestOrder() { return "{\"orderId\": \"SO20250618001\", \"product\": \"无线机械键盘\", \"orderTime\": \"2025-06-18 10:22\", \"status\": \"已发货\"}"; } @Tool(description = "根据订单号查询物流轨迹，返回快递公司和最新一条物流信息。") public String queryLogistics( @Parameter(description = "订单号，例如：SO20250618001") String orderId) { return "{\"orderId\": \"" + orderId + "\", \"carrier\": \"顺丰速运\", \"latestTrace\": \"快件已到达杭州萧山集散中心\"}"; } }调用时同时注册两个工具：
String answer = chatClient.prompt() .user("我的包裹到哪了？") .tools(new OrderToolService()) .call() .content(); System.out.println(answer);框架会自动处理“先查订单，再查物流”的连续动作。你只需要注册一次，剩下的多轮工具调用由框架内部循环完成。模型第一次返回getLatestOrder的调用请求，框架执行后把订单号回传；模型看到订单号后，再返回queryLogistics("SO20250618001")的调用请求；框架再次执行并把物流信息回传；最后模型才组织成最终回答。
4.2 链式调用：一次对话连续触发两个工具
这个案例里最值得感受的点是：模型的“规划能力”体现在工具之间的参数传递上。它看到getLatestOrder返回的 JSON 里有orderId字段，会自动把这个值填进queryLogistics的orderId参数里。这种链式调用不需要你在代码里写任何衔接逻辑，模型天然支持。
但这也带来一个要求：工具返回的 JSON 字段名要见名知意，并且稳定。如果getLatestOrder返回的字段名一会儿是orderId，一会儿是oid，模型就可能填错参数。我在实际项目中吃过这个亏，后来给自己定了一条规则：工具返回的 JSON 结构尽量扁平、字段命名稳定、值必须是可读的字符串或数字，不要返回嵌套太深的对象。模型不是解析器，嵌套再深它也能处理，但嵌套越深、字段越复杂，它“理解并复述”时越容易出错。
另外，多个工具同时注册时，description 的边界要清晰。比如“查询用户最近一笔订单”和“根据订单号查询物流”是两种粒度，描述必须让模型一眼看出差异。否则用户问“我最近买了啥”，模型却去调了物流查询工具，你排查半天才发现是描述含糊导致的。
4.3 如果你想让多个服务批量注册，用 ToolCallbackProvider
工具数量少时，.tools(new xxx())很方便。但当你有一个订单服务、一个用户服务、一个库存服务，每个服务里又挂了七八个工具方法时，我更推荐用ToolCallbackProvider统一注册：
import org.springframework.ai.tool.ToolCallbackProvider; import org.springframework.ai.tool.method.MethodToolCallbackProvider; @Configuration public class ToolConfig { @Bean public ToolCallbackProvider orderToolCallbackProvider(OrderToolService orderToolService, WeatherToolService weatherToolService) { return MethodToolCallbackProvider.builder() .toolObjects(orderToolService, weatherToolService) .build(); } }然后在构建ChatClient时直接注入：
@Bean public ChatClient chatClient(ChatClient.Builder builder, ToolCallbackProvider provider) { return builder.defaultTools(provider).build(); }用defaultTools之后，每次对话都会带上这批工具，不用每次调用都写.tools(...)。这种方法在工具数量多、团队协作时尤为清晰，工具注册表一目了然。如果你的场景是需要动态从数据库加载工具定义，那就得走自定义ToolCallback的路子，我在第 5 章会详细对比。
5. 框架底层做了什么：从方法签名到模型 JSON Schema
5.1 核心链路拆解
理解了使用方式，我还是建议花半小时搞清楚底层链路，因为这决定了你排查问题的思路。Spring AI Alibaba 把“工具注册”“模型调用”“工具执行”“结果回传”这几件事封装得很干净，但你不看的话，出了 bug 就像在雾里开车。
整体流程拆开是这样的：
工具扫描与注册：你传入的工具对象（比如
WeatherToolService）被包装成ToolCallback。@Tool注解被解析成ToolDefinition，里面包含方法名、description、参数的 JSON Schema。每个ToolCallback进入一个注册表，按“工具名”作为 key 索引。请求组装：模型调用时，框架把当前所有已注册的工具定义，作为
tools参数塞进模型 API 请求。模型看到的是 JSON 形式的函数列表，而不是 Java 对象。模型决策：模型读完用户消息和工具定义，决定是直接回答还是调用工具。如果调用，会返回
tool_calls结构，包含工具名和参数 JSON。参数反序列化与反射调用：框架根据工具名找到
ToolCallback，用 Jackson 把模型生成的参数 JSON 反序列化成 Java 方法入参，然后通过反射执行方法。结果回传：方法返回的字符串被包装成一条工具响应消息，追加到对话历史里。
循环直到结束：框架再次把“原始用户消息 + 工具结果 + 之前的工具调用记录”一起发给模型，模型继续生成。如果模型还要调用工具，就重复 3 到 5；如果模型不再调用，就返回最终自然语言回答。
链条里最容易让你困惑的是第 4 步：模型生成参数是 JSON，不是 Java 对象。所以你的方法参数绝不允许是 Spring 管理的复杂对象，比如注入进来的 service、dao，必须全部是基本类型、String、或能被 Jackson 反序列化的 DTO。方法在反射调用前，参数值完全由模型决定，模型给你什么，你就得接住什么。
5.2 从调试日志里看模型到底做了什么
排查问题的时候，看日志比猜管用得多。打开 debug 级别日志后，重点关注这几类输出：
- 请求里包含的工具定义，确认你的工具“上桌”了。
- 模型返回的
tool_calls，确认模型有没有做出调用决策。这一步你能看到两个关键信息：工具名和参数 JSON。 ToolCallback执行后的结果消息，确认你的工具被调用了，以及结果有没有正确回传。
在实际开发中，我通常会临时在工具方法入口加一行日志，打印入参。这能快速定位三类问题：模型没调用（日志里没有调用记录）、调用但参数不对（打印参数 JSON 异常）、方法执行了但结果处理有问题（回传结果被截断或格式损坏）。
5.3 三种注册方式的差异，我该用哪种
我在不同项目里用过三种注册方式，简单对比一下：
| 注册方式 | 典型代码 | 适用场景 | 灵活度 |
|---|---|---|---|
| 调用时临时注册 | .tools(new WeatherToolService()) | 少量工具、临时测试 | 低，工具不随对话自动带入 |
| Spring Bean 统一注册 | MethodToolCallbackProvider.builder().toolObjects(...) | 工具固定、多服务协作 | 中，适合大多数业务 |
| 自定义 ToolCallback | 实现ToolCallback接口，自己装配call() | 动态工具加载、fine-grained 控制、需要注入上下文 | 高 |
自定义ToolCallback是我做生产项目时的最终选择，因为它的call(String toolInput)方法可以直接拿到模型生成的原始参数 JSON，我可以在这里做参数校验、租户上下文注入、审计日志，甚至返回结果脱敏。相比之下，@Tool注解方式是框架自动反射调用，适合快速开发，但中间没有你插手的缝隙。
一句话总结选型思路：刚开始学用注解，做业务系统用ToolCallbackProvider，做中台或高定制需求再上自定义ToolCallback。别一上来就追求最灵活的，那会让 debug 成本翻倍。
6. 新手最容易踩的六个坑，以及我的解决办法
6.1 工具方法必须 public、非 static、非重载
框架通过反射执行工具方法。如果方法不是public，反射调用时可能因为访问权限抛异常；如果是static，部分版本的MethodToolCallbackProvider处理起来会有问题；如果方法有重载，@Tool注解无法区分同名方法，注册时可能直接冲突。我的建议是：工具方法命名保持全局唯一，全用小写驼峰，不要跟其他工具重名。多服务协作时，你永远不知道另一个同事是不是也注册了一个queryDetails。
6.2 参数没写 @Parameter，或描述太敷衍
这是“模型不调用工具”之外最常见的问题。没有@Parameter(description)的方法参数，框架也能反序列化，但模型拿不到参数说明，等于让它盲猜。比如参数叫q，模型根本不知道q是关键词还是城市名。我自己的习惯是：每个参数描述至少包含“参数类型 + 取值示例 + 单位/格式”，让模型不需要看额外文档就能正确填参。
6.3 返回 JSON 结构里没有“模型可直接复述”的内容
工具返回结果不只是给框架用的，更是给模型用来组织回答的素材。如果你的工具返回{"code": 0, "data": {"orderId": "...", "status": 3}}，模型看到status: 3可能会一脸茫然——它不知道 3 代表“已发货”。解决办法是在返回结果里带上可读文案字段："statusDesc": "已发货"。框架不为难、模型不困惑、你的最终回答质量也高。
6.4 返回值过大被截断
某些模型对工具结果的长度有限制，你返回一个 5 万字的 JSON，模型可能只读到前半段，后面就“瞎了”。我的处理办法是：工具返回前做裁剪/汇总，只返回模型组织回答必需的信息。比如查日志工具，不要返回原始日志全文，而是返回“错误码 + 错误数 + 最近一条摘要”。这既省 token 又避免截断。
6.5 工具方法内异常处理不当，导致整轮对话直接失败
@Tool标注的方法里如果抛出异常，异常会向上传播，ChatClient 调用可能直接失败，用户只看到超时或 500。别把异常抛出去，我通常会在工具方法内部 catch 并返回结构化错误信息字符串，比如{"error": "快递单号不存在"}。模型拿到这个结果后，能自然地说出“抱歉，没有查到该订单”，体验和稳定性都更好。这相当于把“工具执行失败”变成“工具返回了一个业务错误”，让模型来兜底。
6.6 多个工具同时被返回时，别指望它们“并行执行”
模型确实可能一次返回多个tool_calls，比如用户问“今天杭州天气和北京天气分别怎么样”，模型可以一次返回两个getWeather调用。但 Spring AI 的默认执行方式是逐个串行执行，不是真正的并发。如果你的工具方法耗时较长，串行累加起来会让用户感觉回答很慢。我的优化办法：在自定义ToolCallback里对无状态、独立的工具调用做并行执行，或者干脆在工具方法内部异步化。但要注意，如果多个工具调用存在依赖关系，比如先查订单再查物流，绝不能并行，必须等前一步拿到订单号。
| 常见坑 | 现象 | 我的解决办法 |
|---|---|---|
| 方法可见性/static/重载 | 注册失败或调用异常 | 保证 public、非静态、唯一命名 |
| 参数无注解或描述模糊 | 模型不调用或参数乱填 | 每个参数写清类型、示例、格式 |
| 返回 JSON 缺可读字段 | 模型答非所问或状态码困惑 | 补充 statusDesc 等可读字段 |
| 返回值过长 | 结果被截断、回答失真 | 工具侧裁剪、摘要化后再返回 |
| 工具内部异常 | 整轮对话直接失败 | 内部 catch，返回结构化错误 JSON |
| 多工具串行执行 | 响应慢 | 独立调用异步化，依赖关系保持串行 |
7. 进阶玩法：把 Tool Calling 接进真正的业务系统
7.1 工具方法里拿不到用户身份？用上下文传递来解决
聊到生产落地，第一个现实问题就是：工具方法怎么知道“当前用户是谁”？@Tool方法本身没有请求上下文，Spring 容器里也没有当前登录用户信息。直接写一个CurrentUserHolder的静态变量在 Web 容器下容易串用户，非常危险。
我的做法是：在 Controller 层从请求里解析用户 ID，放入一个基于 ThreadLocal 的上下文对象，然后在工具方法里从同一个上下文读取。使用完后在 finally 块里清理，防止线程池复用污染。如果你用的是 Reactor 响应式栈，ThreadLocal 无效，可以改成在上下文对象里显式传递，或者用响应式上下文。这不是框架问题，是你自己业务层必须设计的机制。
public class BizContext { private static final ThreadLocal<String> CURRENT_USER = new ThreadLocal<>(); public static void setUserId(String userId) { CURRENT_USER.set(userId); } public static String getUserId() { return CURRENT_USER.get(); } public static void clear() { CURRENT_USER.remove(); } }工具方法里直接BizContext.getUserId()。这种方式在 Web 请求线程里很稳，但如果你在工具内部又开了新线程，记得把用户 ID 手动传进子线程。
7.2 审计日志：每个工具调用都可追踪
接入业务系统后，用户可能会问“为什么我的权限被改了”“为什么订单状态变了”。没有审计日志，你只能干瞪眼。我做了两件事：第一，在自定义ToolCallback的call方法里记录工具名、入参、出参（出参做脱敏）、耗时；第二，把工具调用记录和最终生成的回复关联到同一个请求 ID。
这有一个额外好处：模型调错工具时，你从日志里能一眼看出“用户说的是 A，模型却调了 B”，然后去优化 description，而不是猜模型为什么抽风。盲目重复测试几百次，不如看一次完整审计日志见效快。
7.3 超时与幂等：工具不是免费的
模型在等待工具结果时会挂着整轮对话，所以工具方法必须控时。如果工具内部还调第三方接口，一定要给第三方调用设置超时，并且加一个整体超时兜底。我用的是CompletableFuture+get(3, TimeUnit.SECONDS)，超时直接返回“查询超时，请稍后再试”的结构化错误，让模型能体面地回复用户。
写操作类工具，比如“提交请假”“创建工单”，必须考虑幂等性。模型可能会因为重试机制调用同一工具两次，你需要在工具方法里加业务幂等键，或者在工具描述里注明“仅当用户明确要求时执行”。另外，任何写操作工具上线前，我都会在工具方法里加一个二次确认流程：先返回“即将执行 XX 操作，是否继续”，等用户确认后再调执行接口。这一步看着笨，但能挡住大量不可控的模型输出。
说到底，Tool Calling 真正厉害的地方，不是“能调函数”，而是把自然语言、业务系统和模型智能三者串在了一条链路上。我做了几个月后的总感受是：它上手不难，但要做好难在描述设计、上下文管理和异常兜底这些细节上。如果你刚开始接触，先别急着做复杂业务，把天气查询这个最小闭环跑通，再逐步叠加订单、物流这类有依赖关系的多工具场景，最后再考虑并发、审计和幂等。这条路走下来，你对 Spring AI Alibaba 的理解会扎实很多。
