小鹅通1. 项目概述
作为一名长期深耕Java生态的开发者，我最近被各种AI应用刷屏了。看着Python开发者们轻松调用各种大模型，心里难免痒痒的。直到发现了Spring AI Alibaba这个宝藏框架，终于让我在Java世界里也能玩转AI智能体开发。今天就用这篇实战指南，带大家用10分钟快速构建一个具备思考能力的天气查询智能体。
这个项目最大的价值在于：它打破了Java生态与AI应用之间的技术壁垒。通过阿里云百炼平台提供的DashScope模型（通义千问），我们可以用最熟悉的Spring风格代码实现：
- 自然语言交互
- 工具函数调用
- 多轮对话记忆
- 复杂任务分解
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备
2.1 基础环境配置
工欲善其事必先利其器，我们先确认基础环境：
bash复制# 确认JDK版本（必须≥17）
java -version
# 确认Maven版本（必须≥3.8）
mvn -version
注意：低版本JDK会遇到
var语法兼容性问题，建议使用Amazon Corretto-17这类长期支持版本
2.2 获取模型API Key
- 访问阿里云百炼平台
- 完成企业实名认证（个人开发者可用支付宝认证）
- 在"模型服务"中开通DashScope
- 在"API密钥管理"创建新密钥
建议将API Key设置为环境变量（避免硬编码）：
bash复制# Linux/macOS
export AI_DASHSCOPE_API_KEY=your_api_key
# Windows
setx AI_DASHSCOPE_API_KEY "your_api_key"
3. 项目搭建
3.1 初始化Spring Boot项目
使用start.spring.io生成项目时注意勾选：
- Spring Web（可选）
- Lombok（推荐）
3.2 关键依赖配置
在pom.xml中添加这些核心依赖：
xml复制<dependencies>
<!-- 智能体框架核心 -->
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-agent-framework</artifactId>
<version>1.1.2.0</version>
</dependency>
<!-- 通义千问模型支持 -->
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
<version>1.1.2.0</version>
</dependency>
</dependencies>
刷新Maven依赖时可能会遇到阿里云仓库鉴权问题，建议在settings.xml中添加：
xml复制<mirror>
<id>aliyunmaven</id>
<mirrorOf>*</mirrorOf>
<name>阿里云公共仓库</name>
<url>https://maven.aliyun.com/repository/public</url>
</mirror>
3.3 配置文件设置
application.yml最小化配置：
yaml复制spring:
ai:
dashscope:
api-key: ${AI_DASHSCOPE_API_KEY} # 从环境变量读取
connect-timeout: 5000 # 连接超时(ms)
socket-timeout: 10000 # 响应超时(ms)
4. 开发基础智能体
4.1 最小化示例
创建一个WeatherAgentDemo.java：
java复制import com.alibaba.cloud.ai.dashscope.api.DashScopeApi;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatModel;
import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import org.springframework.ai.chat.model.ChatModel;
public class WeatherAgentDemo {
public static void main(String[] args) {
// 1. 初始化模型API
DashScopeApi dashScopeApi = DashScopeApi.builder()
.apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
.build();
// 2. 构建聊天模型
ChatModel chatModel = DashScopeChatModel.builder()
.dashScopeApi(dashScopeApi)
.build();
// 3. 创建智能体
ReactAgent agent = ReactAgent.builder()
.name("weather_agent")
.model(chatModel)
.instruction("你是一个专业的天气助手")
.build();
// 4. 执行查询
String response = agent.call("上海明天会下雨吗？");
System.out.println(response);
}
}
4.2 运行效果分析
执行后会得到类似这样的响应：
code复制根据天气预报数据，上海明天（2023-11-15）将有阵雨，气温在18-22℃之间，建议出门携带雨具。
此时智能体还只是简单的大模型问答，没有真正的"智能体"特性。接下来我们给它升级装备。
5. 进阶智能体开发
5.1 添加工具调用能力
真正的智能体应该能调用外部工具。我们先定义两个工具类：
java复制// WeatherTool.java
import org.springframework.ai.tool.ToolContext;
import org.springframework.ai.tool.function.FunctionToolCallback;
import java.util.function.BiFunction;
public class WeatherTool implements BiFunction<String, ToolContext, String> {
@Override
public String apply(String city, ToolContext context) {
// 模拟真实天气API调用
String[] weatherTypes = {"晴", "多云", "小雨", "大雨", "雷阵雨"};
String randomWeather = weatherTypes[(int)(Math.random() * weatherTypes.length)];
return String.format("%s天气：%s，温度：%d℃~%d℃",
city,
randomWeather,
15 + (int)(Math.random() * 10),
20 + (int)(Math.random() * 5)
);
}
}
// UserLocationTool.java
public class UserLocationTool implements BiFunction<String, ToolContext, String> {
@Override
public String apply(String query, ToolContext context) {
// 实际项目可以从JWT token或数据库获取
return "北京"; // 默认返回北京
}
}
5.2 配置系统提示词
好的提示词是智能体的灵魂：
java复制String SYSTEM_PROMPT = """
你是一个智能天气预报专家，遵守以下规则：
1. 当用户询问天气时，必须明确具体城市
2. 如果用户说"这里"、"当地"等模糊词，使用get_user_location工具
3. 回答需包含：天气状况、温度范围、穿衣建议
4. 温度低于15℃要提示"注意保暖"，高于30℃提示"注意防暑"
5. 遇到雨天必须提醒带伞
可用工具：
- get_weather_for_location：查询指定城市天气
- get_user_location：获取用户当前位置
""";
5.3 完整智能体组装
java复制import com.alibaba.cloud.ai.graph.checkpoint.MemorySaver;
import org.springframework.ai.tool.ToolCallback;
public class AdvancedWeatherAgent {
public static void main(String[] args) {
// 初始化模型（同上）
// 创建工具实例
ToolCallback weatherTool = FunctionToolCallback.builder()
.name("get_weather_for_location")
.description("查询指定城市的详细天气")
.inputType(String.class)
.function(new WeatherTool())
.build();
ToolCallback locationTool = FunctionToolCallback.builder()
.name("get_user_location")
.description("获取用户当前所在城市")
.inputType(String.class)
.function(new UserLocationTool())
.build();
// 构建智能体
ReactAgent agent = ReactAgent.builder()
.name("advanced_weather_agent")
.model(chatModel)
.systemPrompt(SYSTEM_PROMPT)
.tools(weatherTool, locationTool)
.saver(new MemorySaver()) // 开启对话记忆
.build();
// 测试对话
String threadId = "user_123";
RunnableConfig config = RunnableConfig.builder()
.threadId(threadId)
.build();
System.out.println(agent.call("我这边天气怎么样？", config));
// 输出：北京当前天气：多云，温度：18℃~25℃...
System.out.println(agent.call("需要带伞吗？", config));
// 输出：根据当前多云天气，不需要带伞...
}
}
6. 生产级优化
6.1 性能调优参数
java复制DashScopeChatModel.builder()
.dashScopeApi(dashScopeApi)
.defaultOptions(DashScopeChatOptions.builder()
.withModel("qwen-max") // 使用最强模型
.withTemperature(0.3) // 降低随机性
.withTopP(0.8)
.withMaxToken(1000)
.build())
.build();
6.2 异常处理机制
java复制try {
agent.call("查询纽约天气", config);
} catch (DashScopeException e) {
if (e.getStatusCode() == 429) {
// 处理限流
Thread.sleep(1000);
retry();
}
} catch (ToolExecutionException e) {
// 工具执行异常
log.error("工具调用失败", e);
}
6.3 对话历史管理
java复制MemorySaver memory = new MemorySaver();
ReactAgent agent = ReactAgent.builder()
// ...其他配置
.saver(memory)
.build();
// 获取历史记录
List<Message> history = memory.load("user_123");
history.forEach(msg -> {
System.out.println(msg.getRole() + ": " + msg.getContent());
});
7. 实战技巧
7.1 调试技巧
- 开启详细日志：
yaml复制logging:
level:
com.alibaba.cloud.ai: DEBUG
- 查看智能体思考过程：
java复制agent = ReactAgent.builder()
// ...
.hooks(new ConsoleLogHook()) // 打印决策过程
.build();
7.2 性能优化
- 批量处理请求：
java复制List<CompletableFuture<String>> futures = queries.stream()
.map(query -> CompletableFuture.supplyAsync(
() -> agent.call(query, config)))
.collect(Collectors.toList());
List<String> results = futures.stream()
.map(CompletableFuture::join)
.collect(Collectors.toList());
- 使用本地缓存：
java复制agent = ReactAgent.builder()
// ...
.hooks(new CacheHook(new GuavaCacheLoader()))
.build();
8. 扩展应用场景
8.1 电商客服智能体
java复制String prompt = """
你是专业电商客服，需要：
1. 根据订单号查询物流
2. 处理退货申请
3. 回答产品咨询
工具：
- query_order_status：查询订单状态
- initiate_return：发起退货流程
- search_products：商品搜索
""";
8.2 技术文档助手
java复制ToolCallback codeSearch = FunctionToolCallback.builder()
.name("search_code_docs")
.function((String query, ToolContext ctx) -> {
// 调用内部文档系统API
return docsClient.search(query);
})
.build();
9. 常见问题排查
9.1 API连接问题
错误现象：
code复制ConnectException: Connection timed out
解决方案：
- 检查网络是否能访问
dashscope.aliyuncs.com - 如有代理，需配置JVM参数：
bash复制-Dhttps.proxyHost=proxy.com -Dhttps.proxyPort=8080
9.2 内存泄漏处理
长时间运行后出现OOM时：
- 限制记忆存储条数：
java复制new MemorySaver().setMaxMessagesPerThread(50);
- 定期清理：
java复制memory.cleanUp(threadId -> lastAccessTime < cutoffTime);
9.3 模型响应慢优化
- 降低
max_tokens参数 - 使用更小模型（如
qwen-turbo） - 实现流式响应：
java复制agent.stream("查询天气", config)
.subscribe(chunk -> {
System.out.print(chunk);
});
10. 架构设计建议
对于生产环境部署，推荐采用以下架构：
code复制[客户端] -> [Spring Cloud Gateway]
-> [Agent Service集群]
-> [Redis对话存储]
-> [DashScope API]
关键配置：
- 服务熔断：
java复制@Bean
public CircuitBreakerFactory customizer() {
return new Resilience4JCircuitBreakerFactory();
}
- 限流配置：
java复制@Bean
public RateLimiter dashscopeRateLimiter() {
return RateLimiter.create(50); // 50 QPS
}
经过这个完整实践，我们已经把一个简单的问答机器人升级成了具备工具调用、状态记忆、异常处理等能力的生产级智能体。Spring AI Alibaba框架最让我惊喜的是它的设计理念 - 用Spring开发者熟悉的编程模式实现了复杂的AI能力集成。