Spring AI Tool Calling 入门：DeepSeek 调用 Java 方法查询订单物流 Demo
我见过很多客服 AI，第一版都卡在同一个地方。
用户说：
帮我查一下订单 12345 的物流信息。
模型回答：
抱歉，我无法直接查询订单物流信息。
这不是模型不行。
而是这次调用里，你没有给它“查询订单”的工具。
普通聊天模型只能生成文本。
它不能直接访问你的数据库，也不能绕过应用去调用业务系统。
Tool Calling 要解决的就是这件事：
模型负责判断“要调哪个工具、参数是什么”，Java 应用负责真正执行。
这篇文章，我们用 Spring AI 跑一个最小 Demo：
用户问订单物流，模型自动调用一个 Java 方法，再基于方法返回结果回答。
本文基于 Spring AI 1.1.7，模型使用 DeepSeek，示例配置使用 deepseek-v4-flash。
如果你已经有一个能正常调用 ChatClient 的 Spring Boot 项目，大概率 30 分钟就能跑通。
一、先把 Demo 跑起来
这个 Demo 不接真实数据库。
我们先用模拟数据跑通主流程。
真实项目里，再把模拟逻辑换成你的 OrderService。
1. 准备依赖
如果你已经有 Spring Boot 项目，先确认至少有两个依赖：
- spring-boot-starter-web：提供 HTTP 接口；
- spring-ai-starter-model-deepseek：接入 DeepSeek 聊天模型。
pom.xml 可以这样配置：
<properties>
<java.version>17</java.version>
<spring-ai.version>1.1.7</spring-ai.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-deepseek</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
如果你是从 Spring Initializr 新建项目，记得选 Java 17 或以上。
Tool Calling 不需要再额外引入一套复杂依赖。
@Tool、@ToolParam、.tools(…) 这些能力，Spring AI 的模型 Starter 会把相关模块带进来。
2. 配置 DeepSeek
application.yaml：
spring:
application:
name: springai–deepseek–demo
ai:
model:
chat: deepseek
deepseek:
api-key: ${DEEPSEEK_API_KEY}
chat:
options:
model: deepseek–v4–flash
temperature: 0.2
启动前设置环境变量：
export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
如果你用 IDEA 直接运行项目，就在运行配置里加环境变量。
路径是：
Edit Configurations…
→ 选择 SpringaiDeepseekDemoApplication
→ Environment variables
→ 新增 DEEPSEEK_API_KEY=你的 DeepSeek API Key
→ Apply / OK
这样 application.yaml 里的 ${DEEPSEEK_API_KEY} 才能读到你的 Key。
这里补充两点。
第一，Spring AI 1.1.7 本地源码里还有 deepseek-chat 这类旧模型名的测试用例。
但 DeepSeek 官方 Change Log 已经在 2026-04-24 标注：API 支持 deepseek-v4-pro 和 deepseek-v4-flash，并且 deepseek-chat、deepseek-reasoner 会在 2026-07-24 后废弃。
所以这篇示例使用 deepseek-v4-flash。
第二，模型支持 Tool Calling，不等于它每次都会按你想的方式调用工具。
第一次接入时，先用查询类工具验证。
不要一上来就接退款、发短信、删数据这类高风险操作。
3. 定义一个工具类
新建 OrderTools：
package com.example.springaideepseekdemo.toolcalling;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
@Component
public class OrderTools {
@Tool(description = "根据订单ID查询订单物流信息，返回物流状态和预计送达时间")
public String queryOrderLogistics(
@ToolParam(description = "订单ID，5到20位数字") String orderId) {
if (orderId == null || !orderId.matches("\\\\d{5,20}")) {
return "订单ID格式不正确，订单ID应为5到20位数字";
}
if ("12345".equals(orderId)) {
return "订单已发货，当前在北京分拨中心，预计明天送达";
}
return "未找到该订单的物流信息";
}
}
@Tool 表示这个方法可以作为工具暴露给模型。
@ToolParam 用来描述参数。
Spring AI 会根据方法和参数信息生成工具定义，传给模型。
所以描述要写具体。
查询订单 太泛。
根据订单ID查询订单物流信息，返回物流状态和预计送达时间 会清楚很多。
4. 写一个测试接口
新建 OrderController：
package com.example.springaideepseekdemo.controller;
import com.example.springaideepseekdemo.toolcalling.OrderTools;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class OrderController {
private final ChatClient chatClient;
private final OrderTools orderTools;
public OrderController(ChatClient.Builder builder, OrderTools orderTools) {
this.chatClient = builder.build();
this.orderTools = orderTools;
}
@GetMapping("/ask")
public String ask(@RequestParam String question) {
return chatClient.prompt()
.user(question)
.tools(orderTools)
.call()
.content();
}
}
这里用的是请求级工具：
.tools(orderTools)
意思是：这一次请求里，模型能看到 OrderTools 里的工具方法。
权限敏感的工具，建议优先用请求级注册。
如果你用 ChatClient.Builder#defaultTools(…)，这些工具会成为这个 ChatClient 的默认工具，影响范围更大。
5. 启动测试
启动应用：
./mvnw spring-boot:run
调用接口：
curl –get "http://localhost:8080/ask" \\
–data-urlencode "question=帮我查一下订单12345的物流"
如果链路跑通，背后大概是这样：
用户问题：帮我查一下订单12345的物流
模型选择工具：queryOrderLogistics
工具入参：orderId=12345
工具返回：订单已发货，当前在北京分拨中心，预计明天送达
最终回答：您的订单 12345 已发货，当前在北京分拨中心，预计明天送达。
你没有在 Controller 里写“如果用户想查物流，就调用订单服务”的 if-else。
模型会根据用户问题和工具描述，判断要不要请求调用这个工具。
二、背后到底发生了什么
表面上看，业务代码只有一段：
chatClient.prompt()
.user("帮我查一下订单 12345 的物流")
.tools(orderTools)
.call()
.content();
但执行时，通常会经过这几步：
所以 Tool Calling 不是模型直接执行代码。
模型只是提出请求：
{
"tool": "queryOrderLogistics",
"arguments": {
"orderId": "12345"
}
}
真正执行方法的是 Spring AI 和你的 Java 应用。
这点很关键。
不要把模型当成系统权限边界。
三、三个核心概念
入门阶段，先记住三个就够了。
1. @Tool
把一个 Java 方法暴露成工具。
默认情况下，如果不指定工具名，Spring AI 会使用方法名。
工具名最好简单、稳定，不要带奇怪字符。
2. @ToolParam
描述工具参数。
在 Spring AI 1.1.7 里，@ToolParam 的 required 默认是 true。
也就是说，参数默认会被当成必填。
3. ToolCallback
ToolCallback 是 Spring AI 内部的工具抽象。
可以理解成：
给模型看的工具定义 + 真正执行的 Java 调用逻辑。
使用 @Tool 时，Spring AI 会把对象里的工具方法转换成对应的 ToolCallback。
这篇先不展开底层 API。
把 @Tool + .tools(…) 跑通，比一开始研究所有抽象更重要。
四、实战注意事项
Demo 跑通不难，上生产要谨慎。
1. 先用只读工具验证
第一次接入，建议先做查询类工具：
查订单
查物流
查库存
查配置
查工单状态
不要一上来就接这些：
取消订单
执行退款
修改手机号
发放优惠券
发送通知
删除数据
只读工具风险小。
会改变系统状态的工具，一定要加权限校验、参数校验和二次确认。
2. 工具描述要具体
不好的写法：
@Tool(description = "查询订单")
public String query(String id) {
// …
}
更好的写法：
@Tool(description = "根据订单ID查询订单物流信息，返回物流状态和预计送达时间")
public String queryOrderLogistics(
@ToolParam(description = "订单ID，5到20位数字") String orderId) {
// …
}
工具越多，描述越重要。
模型选工具，主要就靠工具名、工具描述和参数描述。
3. 参数别设计太复杂
工具参数要让模型容易构造。
常见类型就够用：
String
Integer / Long / Double
Boolean
简单 POJO
简单列表
如果一个 OrderRequest 里有十几个字段，模型很容易填错。
能拆就拆。
4. 后端必须兜底
不要把工具描述当成安全控制。
你写了“只能取消当前用户的未发货订单”，只是帮助模型理解工具。
真正的校验还要写在业务代码里：
当前用户有没有权限？
订单是不是属于这个用户？
订单状态能不能取消？
是否需要二次确认？
模型负责判断，后端负责兜底。
5. 日志要留
工具调用失败很常见。
比如订单不存在、参数格式错误、接口超时、数据库异常。
建议至少记录：
调用了哪个工具
关键参数是什么
执行耗时
是否成功
异常摘要
以后用户说“AI 查错订单了”，你才有东西可查。
写在最后
Tool Calling 的本质很简单：
模型请求调用，应用真正执行，再把结果交回模型。
如果你已经有 ChatClient 项目，现在就可以加一个 OrderTools，用 .tools(…) 跑一下。
只要模型真的调用了 Java 方法，并基于工具返回结果回答，Tool Calling 就跑通了。
记住三句话：
模型负责判断
工具负责执行
后端负责兜底
RAG 让模型能“查资料”。
Tool Calling 让模型能“调能力”。
这两个组合起来，Agent 才开始从“会聊天”，走向“能做事”。
我是 Dilee，11 年 Java 老兵，专注 AI 落地应用。
后续会继续更新 Spring AI、RAG、Memory、Tool Calling、MCP 等实战内容。
