Spring AI Alibaba从0到1完全指南

一、什么是 Spring AI Alibaba

Spring AI Alibaba 是阿里云基于 Spring Boot 3.x 开发的 AI 框架，深度集成通义千问大模型与百炼平台，核心价值在于降低 Java 开发者的 AI 应用开发门槛，支持从简单聊天机器人到复杂多智能体系统的全场景开发。

核心能力矩阵

能力模块	核心价值	应用场景示例
ChatClient 组件	零配置调用大模型	智能客服、文本生成
Graph 多智能体框架	可视化编排工作流与多智能体	审批流程机器人、多角色协作系统
企业级生态集成	对接 Nacos、ARMS 等中间件	分布式 AI 服务、可观测监控
RAG 知识库	私有数据与大模型融合	文档问答、产品知识库

二、环境准备

1. 前置工具安装

• JDK：17 及以上版本（推荐 JDK 21）

• 构建工具：Maven 3.6+ 或 Gradle 8.0+

• IDE：IntelliJ IDEA（社区版即可）

• API 密钥：阿里云百炼平台申请（获取地址）

2. 项目初始化

# 方式1：克隆官方示例（推荐）

git clone --depth=1 https://github.com/springaialibaba/spring-ai-alibaba-examples.git

cd spring-ai-alibaba-examples/spring-ai-alibaba-helloworld

# 方式2：新建Spring Boot项目

# IDEA中选择Spring Initializr，Java版本选17，暂不添加依赖

3. 依赖配置

在pom.xml中添加核心依赖（需配置阿里云仓库）：

<!-- 核心 starter -->

<dependency>

   <groupId>com.alibaba.cloud.ai</groupId>

   <artifactId>spring-ai-alibaba-starter</artifactId>

   <version>1.1.0</version> <!-- 最新稳定版 -->

</dependency>

<!-- Web依赖（用于接口测试） -->

<dependency>

   <groupId>org.springframework.boot</groupId>

   <artifactId>spring-boot-starter-web</artifactId>

</dependency>

<!-- 仓库配置（解决依赖下载问题） -->

<repositories>

   <repository>

       <id>aliyun-maven</id>

       <url>https://maven.aliyun.com/repository/public</url>

   </repository>

</repositories>

4. 密钥配置

# application.yml

spring:

 ai:

   alibaba:

     api-key: ${AI_DASHSCOPE_API_KEY} # 从环境变量读取

     model: qwen-turbo # 免费可用的通义模型

server:

 port: 8080

设置环境变量（Linux/Mac）：

export AI_DASHSCOPE_API_KEY=你的密钥

三、核心实战：3 个递进案例

案例 1：极简聊天机器人（10 行代码）

// 1. 控制器层

@RestController

@RequestMapping("/chat")

public class ChatController {

   // 自动注入ChatClient（无需手动初始化）

   @Autowired

   private ChatClient chatClient;

   // 2. 对话接口

   @GetMapping("/ask")

   public String ask(@RequestParam String question) {

       // 调用大模型并返回结果

       return chatClient.call(question);

   }

}

启动项目后测试：

curl http://localhost:8080/chat/ask?question=SpringAI是什么

案例 2：带记忆的多轮对话

添加 Redis 记忆存储，实现上下文保留：

<!-- 新增Redis依赖 -->

<dependency>

   <groupId>org.springframework.boot</groupId>

   <artifactId>spring-boot-starter-data-redis</artifactId>

</dependency>

// 配置类

@Configuration

public class ChatConfig {

   @Bean

   public ChatMemory redisChatMemory(RedisTemplate<String, String> redis) {

       return RedisChatMemory.builder()

               .redisTemplate(redis)

               .maxTurns(20) // 保留20轮对话

               .ttl(Duration.ofHours(12)) // 记忆有效期12小时

               .build();

   }

}

// 服务层

@Service

public class ChatService {

   @Autowired

   private ChatClient chatClient;

   @Autowired

   private ChatMemory chatMemory;

   public String chat(String sessionId, String question) {

       // 加载会话记忆

       ChatHistory history = chatMemory.get(sessionId);

       // 构建带上下文的请求

       Prompt prompt = Prompt.from(question, history);

       // 调用模型并更新记忆

       String answer = chatClient.call(prompt);

       history.add(new UserMessage(question));

       history.add(new AssistantMessage(answer));

       chatMemory.update(sessionId, history);

       return answer;

   }

}

案例 3：函数调用（查询订单物流）

// 工具类（标记为AI可调用函数）

@Component

public class OrderTools {

   @AiFunction(description = "根据订单号查询物流状态")

   public LogisticsDTO getLogistics(@AiParam("orderNo") String orderNo) {

       // 实际项目中对接物流API

       return new LogisticsDTO(orderNo, "运输中", "杭州→上海");

   }

}

// 控制器

@GetMapping("/logistics")

public String queryLogistics(@RequestParam String question) {

   // 让模型自动判断是否调用工具

   ToolExecution toolExecution = chatClient.execute(

           ToolCallRequest.from(question, List.of(orderTools))

   );

   return toolExecution.getResult();

}

四、常见问题排查

1. 依赖下载失败：检查仓库配置，执行mvn clean install -U强制更新

2. API 调用报错：确认密钥有效性，检查网络是否能访问阿里云服务

3. 记忆丢失：Redis 未启动或配置错误，查看redisChatMemoryBean 是否加载

4. 函数调用失效：确保@AiFunction注解描述清晰，模型需理解调用场景