前言

从2025年Spring AI 1.0 GA正式发布，到如今2026年全面拥抱Agent工程，Spring AI已成为Java开发者构建企业级AI应用的首选框架。

不管你是想给现有系统加上AI能力，还是从零开始搭建RAG知识库，Spring AI都值得你认真了解。

今天这篇文章就专门跟大家一起聊聊SpringAI，希望对你会有所帮助。

更多项目实战在Java突击队网：susan.net.cn

一、Spring AI是什么？

1.1 核心定位

Spring AI是Spring官方在2024年推出的AI开发框架，它将Spring的设计原则——可移植性、模块化设计和POJO编程模型——应用到了AI工程领域。

它不是一个简单的“AI SDK”，而是一套完整的AI应用开发框架，让Java开发者可以用熟悉的Spring Boot风格来构建AI应用。

Spring AI解决的核心问题是：将企业的“数据”和“API”与“AI模型”连接起来。

它把所有主流AI模型的API统一成了一致的高层抽象，你只需学会一套接口，就能调用OpenAI、阿里云通义千问、Ollama本地模型等各种模型，切换模型只需改配置文件。

1.2 支持的能力矩阵

能力类型	支持的功能	代表模型提供商
聊天完成	对话、代码生成、内容创作	OpenAI、通义千问、DeepSeek、Claude
嵌入	文本向量化、语义搜索	同左
多模态	图像识别、视频理解、音频转录	GPT-4o、Qwen-VL
函数调用	外部API集成、工具调用	主流模型均支持
向量数据库	相似性检索、RAG	PGVector、Milvus、Redis、Chroma
MCP	模型上下文协议、外部工具集成	Spring AI原生支持

1.3 技术架构图

二、环境搭建

2.1 使用Spring Boot Starter快速集成

在pom.xml中添加Spring AI BOM和具体模型的starter依赖。

首先，添加Spring Milestones仓库（Spring AI 1.1.x版本的jar包托管在此，且1.0.x也建议添加以确保兼容性）：

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

然后，添加BOM和starter：

<properties>
    <spring-ai.version>1.1.2</spring-ai.version>
</properties>

<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>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

2.2 配置API Key

在application.yml中配置：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o

对于国内开发者，也可以使用阿里云通义千问：

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}

2.3 本地运行Ollama（无需API Key）

如果想本地免费体验，可以使用Ollama：

# 安装并运行Ollama
ollama pull qwen2.5:latest
ollama serve

配置Ollama starter：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:latest

三、基础对话：Hello World

3.1 使用ChatClient（推荐方式）

ChatClient提供了流畅的API，是官方推荐的主要交互方式，功能比直接使用ChatModel更丰富。

@RestController
@RequestMapping("/api/ai")
public class ChatController {
    
    private final ChatClient chatClient;
    
    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("你是一个专业的Java技术专家")
            .build();
    }
    
    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

3.2 流式输出（打字机效果）

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> stream(@RequestParam String message) {
    return chatClient.prompt()
            .user(message)
            .stream()
            .content();
}

3.3 ChatModel vs ChatClient如何选择？

这是两个核心抽象，区别如下：

特性维度	ChatModel	ChatClient
API复杂度	高（需手动构建Prompt）	低（流式DSL）
Advisor支持	❌ 不支持	✅ 内置支持
记忆管理	需手动实现	✅ 自动会话记忆
流式输出	需额外封装	✅ 一行代码开启
错误处理	需自行捕获	✅ 统一异常封装
推荐度	⭐⭐ 特殊场景使用	⭐⭐⭐⭐⭐ 首选方案

四、多轮对话：让AI拥有“记忆”

在智能客服等场景中，AI需要记住之前的对话内容。Spring AI通过Advisor机制轻松实现。

@Service
public class ChatMemoryService {
    
    private final ChatClient chatClient;
    private final ChatMemory chatMemory;
    
    public ChatMemoryService(ChatClient.Builder builder) {
        this.chatMemory = new InMemoryChatMemory();
        this.chatClient = builder
            .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory))
            .build();
    }
    
    public String chat(String sessionId, String message) {
        return chatClient.prompt()
                .user(message)
                .advisors(advisor -> advisor.param("chat_memory_conversation_id", sessionId))
                .call()
                .content();
    }
}

更多项目实战在Java突击队网：susan.net.cn/project

五、RAG实战：让AI基于你的文档回答

RAG（检索增强生成）是企业级AI应用的核心能力。

Spring AI通过VectorStore和QuestionAnswerAdvisor提供了开箱即用的RAG支持。

5.1 RAG工作流程图

5.2 添加RAG依赖

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pgvector-store</artifactId>
</dependency>

5.3 配置向量数据库（以PGVector为例）

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/vectordb
    username: postgres
    password: password
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1536

5.4 实现RAG问答

@Service
public class RagService {
    
    @Autowired
    private VectorStore vectorStore;
    
    @Autowired
    private ChatClient chatClient;
    
    public String ask(String question) {
        // QuestionAnswerAdvisor会自动完成向量检索并增强Prompt
        return chatClient.prompt()
                .user(question)
                .advisors(new QuestionAnswerAdvisor(vectorStore))
                .call()
                .content();
    }
}

六、Tool Calling：让AI调用外部API

Tool Calling（函数调用）是Agent的核心能力之一。

Spring AI通过@Tool注解让模型能够调用Java方法，从而与外部系统交互。

6.1 定义工具

@Component
public class WeatherTools {
    
    @Tool(description = "根据城市名称查询当前天气")
    public String getWeather(@ToolParam(description = "城市名称，如'北京'") String city) {
        // 实际项目中调用真实天气API
        Map<String, String> weatherMap = Map.of(
            "北京", "晴天，25°C，北风2级",
            "上海", "多云，22°C，东风3级",
            "深圳", "阵雨，28°C，南风2级"
        );
        return weatherMap.getOrDefault(city, "天气数据暂不可用");
    }
}

6.2 在ChatClient中注册工具

@RestController
@RequestMapping("/api/tools")
public class ToolController {
    
    private final ChatClient chatClient;
    
    public ToolController(ChatClient.Builder builder, WeatherTools weatherTools) {
        this.chatClient = builder
            .defaultSystem("你是一个专业的天气助手")
            .build();
    }
    
    @GetMapping("/weather")
    public String askWeather(@RequestParam String question) {
        // 将工具注册到ChatClient，模型会自动判断何时调用
        return chatClient.prompt()
                .user(question)
                .tools(new WeatherTools())
                .call()
                .content();
    }
}

七、多模态：让AI“看懂”图片

多模态AI能同时理解文本和图像。以GPT-4o为例，Spring AI支持将图片与文本一起发送给模型。

@Service
public class MultimodalService {
    
    private final ChatClient chatClient;
    
    public MultimodalService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }
    
    public String analyzeReceipt(byte[] imageBytes) {
        return chatClient.prompt()
            .user(userSpec -> userSpec
                .text("请分析这张收据图片，提取商户名称、消费总额和明细列表，以JSON格式返回")
                .media(MimeTypeUtils.IMAGE_JPEG, new ByteArrayResource(imageBytes))
            )
            .call()
            .content();
    }
}

八、MCP集成：连接外部工具生态

MCP（模型上下文协议）是连接AI模型与外部工具的标准化协议，Spring AI提供了完整的MCP集成支持。

8.1 MCP架构图

8.2 添加MCP依赖

<dependency>
    <groupId>org.springframework.experimental</groupId>
    <artifactId>spring-ai-mcp</artifactId>
    <version>1.0.0</version>
</dependency>

8.3 将MCP工具注入ChatClient

@Configuration
public class McpConfig {
    
    @Bean
    public McpClient mcpClient() {
        var stdioParams = ServerParameters.builder("npx")
            .args("-y", "@modelcontextprotocol/server-brave-search")
            .addEnvVar("BRAVE_API_KEY", System.getenv("BRAVE_API_KEY"))
            .build();
        
        return McpClient.using(new StdioClientTransport(stdioParams))
            .sync();
    }
    
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder, McpClient mcpClient) {
        var init = mcpClient.initialize();
        
        return builder
            .defaultFunctions(mcpClient.listTools().tools().stream()
                .map(tool -> new McpFunctionCallback(mcpClient, tool))
                .toArray(McpFunctionCallback[]::new))
            .build();
    }
}

九、Agent智能体开发

Spring AI Alibaba在1.1.2.x版本中提供了完整的Agent开发能力，基于Graph工作流和Agent Framework可将MultiAgent开发周期从数天压缩到数小时。

9.1 添加Spring AI Alibaba依赖

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.0</version>
</dependency>

9.2 创建ReactAgent

@Component
public class WeatherAgent {
    
    private final ReactAgent agent;
    
    public WeatherAgent(ChatModel chatModel, WeatherTools weatherTools) {
        this.agent = ReactAgent.builder()
            .name("weather_assistant")
            .model(chatModel)
            .tools(weatherTools)
            .systemPrompt("你是一个专业的天气助手，帮用户查询天气信息")
            .build();
    }
    
    public String ask(String question) {
        return agent.call(question);
    }
}

十、优缺点与适用场景

优点

• 与Spring Boot深度集成：遵循Spring开发者熟悉的配置和开发习惯
• 模型切换零成本：统一API，改配置即可切换不同模型
• 企业级特性完备：支持事务、安全、监控等Spring生态能力
• 模块化设计：按需引入功能模块，避免依赖臃肿
• 官方文档完善：Spring团队持续维护，1.0 GA版本已稳定

缺点

• 学习曲线：需理解ChatModel、ChatClient、Advisor等抽象概念
• Java版本要求：需JDK 17+
• 生态相对年轻：相比Python的LangChain，社区规模仍需发展

适用场景

• Spring Boot/Cloud技术栈的企业
• 企业级RAG知识库系统
• AI智能客服、内容生成应用
• 需要多模型切换或国内模型接入的项目

总结

Spring AI将AI能力集成变成了Spring开发者熟悉的配置驱动模式。从本章的实战中，我们已掌握了Spring AI的六大核心能力：

1. ChatClient：统一的对话接口，支持同步/流式调用
2. 多轮对话：通过Advisor机制实现会话记忆
3. RAG：结合向量数据库实现企业知识库问答
4. Tool Calling：让AI调用外部API和系统操作
5. 多模态：处理图像、音频等非文本输入
6. Agent开发：通过ReactAgent和Graph工作流构建多智能体系统

你可以从基础对话开始，逐步为项目添加RAG和Tool Calling能力，再根据业务需要引入多模态和Agent。

如果你的系统对性能要求极高，可以选择Ollama本地部署；如果需要稳定可靠的企业级服务，推荐使用阿里云通义千问或Azure OpenAI。

未来已来，Java开发者终于可以在AI时代喊出那句话：“Make Java Great Again！”

希望这篇文章能帮你快速上手Spring AI，让AI成为你开发工具箱中的得力助手。