Spring AI 从入门到实战

来源：互联网 2026-04-22 22:59:01

前言从2025年Spring AI 1.0正式版发布，到如今2026年全面拥抱Agent工程，这个框架已经悄然成为Ja va开发者构建企业级AI应用的首选。无论你是想为现有系统注入AI能力，还是从零搭建一个RAG知识库，Spring AI都值得你投入时间深入了解。今天，我们就来系统性地聊聊它。一

前言

从2025年Spring AI 1.0正式版发布，到如今2026年全面拥抱Agent工程，这个框架已经悄然成为Ja va开发者构建企业级AI应用的首选。无论你是想为现有系统注入AI能力，还是从零搭建一个RAG知识库，Spring AI都值得你投入时间深入了解。今天，我们就来系统性地聊聊它。

一、Spring AI是什么？

1.1 核心定位

简单来说，Spring AI是Spring生态在2024年推出的AI开发框架。它的精髓在于，将Spring那套经典的设计原则——可移植性、模块化和POJO编程模型——成功地应用到了AI工程领域。这意味着，它远不止一个简单的“AI SDK”，而是一套完整的、让Ja va开发者能用熟悉的Spring Boot风格来构建AI应用的框架。

长期稳定更新的攒劲资源： >>>点此立即查看<<<

那么，它到底解决了什么核心痛点？答案是将企业的“数据”、“API”与“AI模型”高效连接。它把所有主流AI模型的API统一成了一套高层抽象接口。你只需要学会这一套接口，就能轻松调用OpenAI、阿里云通义千问乃至本地的Ollama模型，切换模型通常只需改动配置文件即可。

1.2 支持的能力矩阵

（此处保留原文关于能力矩阵的描述，内容未提供具体细节，故维持原状。）

1.3 技术架构图

Spring AI 从入门到实战图片

二、环境搭建

2.1 使用Spring Boot Starter快速集成

上手的第一步，自然是在pom.xml中添加依赖。这里有个细节需要注意：Spring AI 1.1.x版本的构件托管在Spring Milestones仓库，即便是使用1.0.x版本，也建议添加此仓库以确保兼容性。

首先，添加仓库配置：


    
        spring-milestones
        Spring Milestones
        https://repo.spring.io/milestone

接着，引入BOM和具体的starter依赖，比如OpenAI的：


    1.1.2



    
        
            org.springframework.ai
            spring-ai-bom
            ${spring-ai.version}
            pom
            import
        
    



    
        org.springframework.boot
        spring-boot-starter-web
    
    
        org.springframework.ai
        spring-ai-openai-spring-boot-starter

2.2 配置API Key

依赖搞定后，下一步就是在application.yml中配置密钥和模型。以OpenAI为例：

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
ollama pull qwen2.5:latest
ollama serve

然后在项目中引入对应的starter：


    org.springframework.ai
    spring-ai-ollama-spring-boot-starter

配置指向本地服务：

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

三、基础对话：Hello World

3.1 使用ChatClient（推荐方式）

与AI对话，Spring AI提供了两种主要抽象：ChatModel和ChatClient。目前更推荐使用功能更丰富的ChatClient，它提供了流畅的Builder API。看一个简单的控制器示例：

@RestController
@RequestMapping("/api/ai")
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("你是一个专业的Ja va技术专家")
            .build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

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

想要实现那种逐字输出的“打字机”效果？利用响应式编程的Flux，几行代码就能搞定：

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

3.3 ChatModel vs ChatClient如何选择？

这里简单厘清一下：ChatModel是更底层的模型抽象，而ChatClient是在其之上构建的、功能更全面的客户端。对于大多数应用场景，直接从ChatClient入手会更高效。

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

在智能客服这类场景中，AI必须能记住上下文。Spring AI通过其独特的Advisor机制，可以非常优雅地实现对话记忆。关键在于引入MessageChatMemoryAdvisor：

@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();
    }
}

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

如果说多轮对话是“记忆”，那么RAG（检索增强生成）就是给AI装上了“知识库”。这是企业级AI应用的核心能力，Spring AI通过VectorStore和QuestionAnswerAdvisor提供了开箱即用的支持。

5.1 RAG工作流程图

Spring AI 从入门到实战

5.2 添加RAG依赖

以常用的PGVector向量库为例，首先引入对应依赖：


    org.springframework.ai
    spring-ai-pgvector-store

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

服务层的实现反而变得异常简洁，QuestionAnswerAdvisor会自动完成向量检索和提示词增强：

@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

让AI不仅能说，还能“做”，这就是Tool Calling（函数调用）的价值，它是构建智能体（Agent）的基石。Spring AI通过一个简单的@Tool注解，就能让模型调用你定义的Ja va方法。

6.1 定义工具

比如，定义一个查询天气的工具：

@Component
public class WeatherTools {

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

6.2 在ChatClient中注册工具

在控制器中，将工具实例注册到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“看懂”图片

现代大模型早已不止于文本。以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架构图

Spring AI 从入门到实战图片

8.2 添加MCP依赖

首先引入实验性的MCP模块：


    org.springframework.experimental
    spring-ai-mcp
    1.0.0

8.3 将MCP工具注入ChatClient

通过配置，可以将MCP服务（例如一个联网搜索工具）提供的所有工具自动注入到ChatClient中：

@Configuration
public class McpConfig {

    @Bean
    public McpClient mcpClient() {
        var stdioParams = ServerParameters.builder("npx")
            .args("-y", "@modelcontextprotocol/server-bra ve-search")
            .addEnvVar("BRA VE_API_KEY", System.getenv("BRA VE_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，据说能将多智能体应用的开发周期从数天压缩到数小时。

9.1 添加Spring AI Alibaba依赖


    com.alibaba.cloud.ai
    spring-ai-alibaba-starter-dashscope
    1.1.2.0

9.2 创建ReactAgent

创建一个具备思考和工具使用能力的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等一套新的抽象概念。
Ja va版本要求：需要JDK 17及以上版本。
生态相对年轻：与Python领域的LangChain等相比，社区规模和第三方工具集成度仍有发展空间。

适用场景

Spring Boot/Cloud技术栈的企业：无缝融入现有技术体系。
企业级RAG知识库系统：需要基于私有文档进行智能问答的场景。
AI智能客服、内容生成应用：需要多轮对话和复杂逻辑处理。
需要多模型切换或国内模型接入的项目：一套代码适配多种模型需求。
追求工程化、可维护性的AI应用：利用Spring的成熟实践保障项目质量。

总结

纵观全文，Spring AI本质上是将AI能力集成变成了Spring开发者最熟悉的“配置驱动”模式。通过上面的实战，我们其实已经掌握了它的六大核心能力：

ChatClient：统一的对话接口，支持同步和流式调用。
多轮对话：通过Advisor机制轻松实现会话记忆。
RAG：结合向量数据库，构建企业专属知识库问答系统。
Tool Calling：让AI获得“动手能力”，调用外部API和系统。
多模态：处理图像、音频等非文本输入，拓展应用边界。
Agent开发：通过ReactAgent和Graph工作流构建复杂多智能体系统。

实践路径也很清晰：可以从基础对话开始，逐步为项目添加RAG和Tool Calling能力，再根据业务需要引入多模态和Agent。如果你的系统对延迟和隐私要求极高，Ollama本地部署是优选；如果需要稳定可靠的企业级服务，那么阿里云通义千问或Azure OpenAI会是更稳妥的选择。

技术浪潮奔涌，Ja va生态凭借Spring AI再次展现了其强大的适应性和生命力。对于广大Ja va开发者而言，这意味着我们熟悉的武器库中，又多了一件应对AI时代的利器。希望这份指南能帮助你快速上手，将AI能力扎实地融入你的下一个项目之中。

侠游戏发布此文仅为了传递信息，不代表侠游戏网站认同其观点或证实其描述