Spring AI实战指南：Java 开发者的 AI 原生应用构建之路

摘要：随着大模型（LLM）从"玩具"走向"生产力"，Java 生态终于迎来了自己的 AI 基础设施标准------Spring AI。本文基于 2026 年最新稳定版 Spring AI，从核心概念、基础集成、RAG 检索增强、Function Calling 工具调用、Agent 智能体编排，到企业级生产落地，提供了一套完整的知识体系。无论你是刚接触 AI 的 Java 后端，还是寻求架构升级的技术负责人，这篇万字长文都将是你案头必备的实战手册。

关键词：Spring AI, LLM, RAG, Function Calling, MCP, Vector Database, Java AI, 智能体

---

目录

1. 前言：为什么 Java 开发者需要 Spring AI？
2. 第一章：认知重塑------Spring AI 核心抽象与哲学
3. 第二章：快速上手------5分钟接入你的第一个大模型
4. 第三章：结构化输出------让 AI 听懂 Java 的语言
5. 第四章：RAG 检索增强生成------打造企业私有知识库
6. 第五章：Function Calling 与 MCP------让 AI 长出"手脚"
7. 第六章：记忆与对话管理------让 AI 拥有"上下文"
8. 第七章：多模态与高级特性------图片、音频与流式处理
9. 第八章：Agent 智能体编排------从单点能力到复杂任务
10. 第九章：生产环境落地------可观测性、安全与性能调优
11. 第十章：Spring AI vs LangChain4j：选型与未来展望
12. 结语

---

1. 前言：为什么 Java 开发者需要 Spring AI？ {#1-前言}

1.1 AI 时代的 Java 焦虑

在过去两年里，AI 应用开发的舆论场几乎被 Python 垄断。LangChain、LlamaIndex、AutoGen 等框架层出不穷，而 Java 社区似乎成了"沉默的大多数"。许多 Java 开发者面临着这样的困境：

• 生态割裂：想用 AI，但不得不写 Python 微服务，导致系统架构复杂化，运维成本飙升。
• API 地狱：直接调用 OpenAI/通义千问的 HTTP API，代码中充斥着 JSON 解析、重试逻辑、Token 计算和流式处理，业务代码与 AI 胶水代码严重耦合。
• 缺乏标准：每个模型的接口都不一样，切换模型供应商意味着重写大量适配层。

1.2 Spring AI 的使命

Spring AI 的出现，不是为了把 Java 变成 Python，而是用 Spring 的方式解决 AI 问题。它继承了 Spring Framework 的核心哲学：

• 统一抽象（Portable API）：一套代码，无缝切换 OpenAI、Azure、Ollama、通义千问、智谱等 20+ 家模型供应商。
• 声明式编程 ：通过 @Bean、@Value、Starter 自动配置，将 AI 能力像数据库、缓存一样自然地注入 Spring 容器。
• 工程化最佳实践：内置重试、限流、熔断、可观测性（Micrometer/OpenTelemetry）、向量存储抽象等企业级特性。
• 类型安全：利用 Java 强类型优势，将 AI 的非结构化输出映射为 POJO，告别手动解析 JSON。

1.3 2026 年的 Spring AI 现状

截至 2026 年中旬，Spring AI 已进入 1.x 成熟稳定期。MCP（Model Context Protocol）已成为事实上的工具连接标准，GraalVM Native Image 支持完善，Spring Boot 3.4+ 深度集成。现在的 Spring AI，已经完全可以支撑金融、医疗、电商等核心业务系统的 AI 化改造。

---

2. 第一章：认知重塑------Spring AI 核心抽象与哲学 {#2-第一章}

在学习代码之前，必须先建立正确的认知模型。Spring AI 的设计围绕以下几个核心接口展开，理解了它们，就理解了整个框架。

2.1 ChatClient：对话的统一入口

ChatClient 是 Spring AI 最核心的接口，类似于 JDBC 中的 JdbcTemplate 或 WebFlux 中的 WebClient。它屏蔽了底层模型差异，提供了同步、异步、流式三种调用模式。

// 无论底层是 OpenAI 还是 Ollama，API 完全一致
String response = chatClient.prompt()
    .user("解释一下量子纠缠")
    .call()
    .content();

2.2 Prompt & Message：对话的结构化表达

AI 不是魔法，它是基于消息序列的预测机器。Spring AI 将 Prompt 建模为 Message 列表：

• SystemMessage：设定人设、规则、约束。
• UserMessage：用户输入，支持文本+图片+音频等多模态内容。
• AssistantMessage：模型回复，可能包含文本或工具调用请求。
• ToolResponseMessage：工具执行结果反馈。

2.3 OutputParser / BeanOutputConverter：结构化输出的桥梁

这是 Spring AI 区别于裸调 API 的最大亮点之一。它利用 Jackson + Schema Generation，自动将 Java 类转换为 JSON Schema 注入 Prompt，并将 AI 返回的 JSON 反序列化为对象。

2.4 VectorStore：向量数据库的统一抽象

就像 DataSource 抽象了关系型数据库一样，VectorStore 抽象了 Pinecone、Milvus、PgVector、Redis、Elasticsearch 等 15+ 种向量存储。你的 RAG 业务代码永远不需要关心底层用的是哪种向量库。

2.5 ToolCallback / MCP Client：外部能力的标准化接入

Spring AI 将"函数调用"抽象为 ToolCallback，并原生支持 MCP 协议。这意味着你可以用同一套注解声明工具，既可以直接被 LLM 调用，也可以通过 MCP Server 暴露给其他 AI 客户端。

---

3. 第二章：快速上手------5分钟接入你的第一个大模型 {#3-第二章}

3.1 环境准备

• JDK 17+ （推荐 JDK 21+ 以获得虚拟线程支持）
• Spring Boot 3.3+
• Maven / Gradle

3.2 添加依赖

以接入 OpenAI 为例（国内开发者可替换为 spring-ai-alibaba-starter 或 spring-ai-ollama-spring-boot-starter）：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0</version> <!-- 请使用最新版本 -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

3.3 配置 application.yml

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY} # 推荐使用环境变量，不要硬编码
      chat:
        options:
          model: gpt-4o
          temperature: 0.7

3.4 编写第一个 Controller

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

    private final ChatClient chatClient;

    // Spring AI 自动装配 ChatModel，我们用它构建 ChatClient
    public ChatController(ChatModel chatModel) {
        this.chatClient = ChatClient.builder(chatModel).build();
    }

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

    // SSE 流式输出，提升用户体验的关键
    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .stream()
                .content();
    }
}

3.5 切换模型零成本

如果你想本地测试，只需更换 Starter 和配置，业务代码一行不改：

# 切换到本地 Ollama
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: qwen2.5:14b

这就是 Spring AI "可移植性"的威力。

---

4. 第三章：结构化输出------让 AI 听懂 Java 的语言 {#4-第三章}

在实际业务中，我们很少直接使用 AI 返回的纯文本。我们需要的是订单对象、分析报告、分类标签等结构化数据。

4.1 定义目标实体

public record MovieReview(
    String movieName,
    int rating,          // 1-10
    String summary,
    List<String> highlights
) {}

4.2 使用 BeanOutputConverter

@GetMapping("/review")
public MovieReview getReview(@RequestParam String userInput) {
    return chatClient.prompt()
            .user(u -> u.text("请根据以下观众反馈生成电影评论: {input}")
                        .param("input", userInput))
            .call()
            .entity(MovieReview.class); // 核心：自动转换
}

底层发生了什么？

1. Spring AI 读取 MovieReview 的字段和 Javadoc/注解，生成 JSON Schema。
2. 将 Schema 作为系统指令附加到 Prompt 中："你必须返回符合以下 JSON Schema 的对象..."
3. AI 返回 JSON 字符串。
4. Spring AI 使用 Jackson 将其反序列化为 MovieReview 实例。
5. 如果解析失败，内置的重试机制会自动要求 AI 修正格式。

4.3 集合与泛型支持

// 返回列表
List<MovieReview> reviews = chatClient.prompt()
        .user("列出最近三部热门科幻电影的评论")
        .call()
        .entity(new ParameterizedTypeReference<List<MovieReview>>() {});

4.4 自定义验证与容错

结合 Bean Validation，可以在反序列化后自动校验：

public record OrderExtraction(
    @NotBlank String orderId,
    @Positive BigDecimal amount,
    @NotNull LocalDate orderDate
) {}

当 AI 返回的数据不符合校验规则时，Spring AI 可以将校验错误信息反馈给模型进行自我修正（Self-Correction Loop），大幅提高生产环境的可靠性。

---

5. 第四章：RAG 检索增强生成------打造企业私有知识库 {#5-第四章}

RAG（Retrieval Augmented Generation）是目前企业落地 AI 最成熟的范式。Spring AI 提供了端到端的 RAG 支持。

5.1 RAG 流程概览

文档 → 分块(Chunking) → 向量化(Embedding) → 存入向量库(VectorStore)
                                                    ↓
用户提问 → 查询向量化 → 相似度检索 → 获取相关片段 → 注入Prompt → LLM生成回答

5.2 文档加载与分块

Spring AI 支持 PDF、Word、HTML、Markdown、数据库等多种数据源：

// 加载 PDF 并智能分块
var reader = new PagePdfDocumentReader("classpath:docs/company-policy.pdf");
List<Document> documents = reader.get();

// 按 Token 大小分块，保留重叠以保证语义连贯
var splitter = new TokenTextSplitter(800, 200, 5, 10000, true);
List<Document> chunks = splitter.apply(documents);

5.3 向量存储配置

以 PostgreSQL + pgvector 为例（生产推荐）：

spring:
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1536

@Bean
CommandLineRunner ingestData(VectorStore vectorStore) {
    return args -> {
        vectorStore.add(chunks);
        log.info("✅ 已导入 {} 个文档片段", chunks.size());
    };
}

5.4 检索增强问答

@Service
public class KnowledgeBaseService {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    public KnowledgeBaseService(ChatModel chatModel, VectorStore vectorStore) {
        this.vectorStore = vectorStore;
        this.chatClient = ChatClient.builder(chatModel)
                .defaultSystem("你是公司内部政策助手。仅根据提供的上下文回答问题。如果上下文中没有相关信息，请明确告知用户不要编造。")
                .build();
    }

    public String answer(String question) {
        // 1. 检索相关文档
        List<Document> relevantDocs = vectorStore.similaritySearch(
            SearchRequest.builder()
                .query(question)
                .topK(5)
                .similarityThreshold(0.7)
                .build()
        );

        // 2. 构建带上下文的 Prompt
        String context = relevantDocs.stream()
                .map(Document::getText)
                .collect(Collectors.joining("\n\n---\n\n"));

        // 3. 调用 LLM
        return chatClient.prompt()
                .user(u -> u.text("""
                    上下文信息:
                    {context}
                    
                    用户问题: {question}
                    """)
                    .param("context", context)
                    .param("question", question))
                .call()
                .content();
    }
}

5.5 高级 RAG 技巧

• Query Transformation：对用户问题进行改写、扩展、分解，提高召回率。
• Hybrid Search：结合关键词搜索（BM25）和向量搜索，兼顾精确匹配和语义理解。
• Metadata Filtering：按部门、时间、文档类型过滤，缩小检索范围。
• Reranking：对初步检索结果用 Cross-Encoder 重排序，提升 Top-K 质量。

Spring AI 对这些高级策略均有内置 Advisor 支持，可通过链式调用轻松组合。

---

6. 第五章：Function Calling 与 MCP------让 AI 长出"手脚" {#6-第五章}

LLM 本身只能生成文本，无法查数据库、调 API、发邮件。Function Calling 赋予了 AI 行动能力。

6.1 声明式工具定义

@Component
public class WeatherTools {

    @Tool(description = "获取指定城市的当前天气信息，包括温度、湿度、天气状况")
    public WeatherInfo getWeather(
            @Param("city") String city,
            @Param("unit") String unit) {
        // 调用真实天气 API
        return weatherApiClient.fetch(city, unit);
    }
}

6.2 注册并使用工具

@GetMapping("/weather")
public String askWeather(@RequestParam String query) {
    return chatClient.prompt()
            .user(query)
            .tools(weatherTools) // 传入工具实例
            .call()
            .content();
}

当用户问"北京今天适合跑步吗？"，AI 会自动：

1. 识别意图，生成 getWeather("北京", "celsius") 调用请求。
2. Spring AI 拦截请求，反射调用方法，获取结果。
3. 将结果作为 ToolResponseMessage 发回给 AI。
4. AI 综合天气数据，给出"适合/不适合跑步"的自然语言建议。

整个过程对开发者透明，你只需关注业务逻辑。

6.3 MCP：AI 工具的 USB-C 接口

MCP（Model Context Protocol）是 Anthropic 提出的开放标准，解决了工具碎片化问题。Spring AI 同时支持作为 MCP Client 和 MCP Server。

作为 MCP Client 消费外部工具：

spring:
  ai:
    mcp:
      client:
        servers:
          filesystem:
            command: npx
            args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
          github:
            url: https://mcp.github.com/sse

配置完成后，这些 MCP Server 暴露的工具会自动注册到 Spring AI 的工具体系中，无需编写任何适配代码。

作为 MCP Server 暴露自身能力：

@Bean
McpServerFeatures.SyncToolRegistration databaseQueryTool() {
    return McpServerFeatures.SyncToolRegistration.builder()
            .name("query_orders")
            .description("查询订单系统中的订单信息")
            .inputSchema(OrderQuery.class)
            .handler((args) -> orderService.query(args))
            .build();
}

这使得你的 Spring Boot 应用可以被 Cursor、Claude Desktop、其他 AI Agent 直接调用，成为 AI 生态的一部分。

---

7. 第六章：记忆与对话管理------让 AI 拥有"上下文" {#7-第六章}

LLM 本身是无状态的。要实现多轮对话，必须管理聊天历史。

7.1 ChatMemory 抽象

Spring AI 提供了 ChatMemory 接口及多种实现：

• InMemoryChatMemory：开发测试用。
• JdbcChatMemory：持久化到关系型数据库。
• RedisChatMemory：高性能分布式场景。
• CassandraChatMemory：大规模会话存储。

7.2 消息窗口策略

无限累积历史会导致 Token 爆炸和注意力分散。Spring AI 提供多种窗口策略：

@Bean
ChatMemory chatMemory(JdbcTemplate jdbcTemplate) {
    return JdbcChatMemory.builder()
            .jdbcTemplate(jdbcTemplate)
            .conversationIdGenerator(() -> UUID.randomUUID().toString())
            .messageWindowChatMemory(MessageWindowChatMemory.builder()
                    .maxMessages(20) // 保留最近20条消息
                    .build())
            .build();
}

更高级的策略包括：

• Summary Memory：定期用 LLM 压缩历史为摘要。
• Vector Memory：将历史向量化，按需检索相关片段（适合超长对话）。
• Sliding Window + Summary：混合策略，兼顾近期细节和长期记忆。

7.3 Advisor 机制：非侵入式增强

Spring AI 的 Advisor 类似于 AOP，可以在不修改业务代码的情况下横切增强：

ChatClient client = ChatClient.builder(chatModel)
        .defaultAdvisors(
            new MessageChatMemoryAdvisor(chatMemory),     // 自动注入历史
            new RetrievalAugmentationAdvisor(vectorStore), // 自动 RAG
            new LoggingAdvisor(),                          // 日志记录
            new ContentFilterAdvisor()                     // 内容安全过滤
        )
        .build();

Advisor 可以排序、组合、条件启用，是构建复杂 AI 应用的基石。

---

8. 第七章：多模态与高级特性------图片、音频与流式处理 {#8-第七章}

8.1 图像理解与分析

@GetMapping("/analyze-image")
public String analyzeImage(@RequestParam MultipartFile image) throws IOException {
    UserMessage message = new UserMessage(
        "描述这张图片的内容并识别其中的文字",
        new Media(MimeTypeUtils.IMAGE_PNG, image.getResource())
    );

    return chatClient.prompt()
            .messages(message)
            .call()
            .content();
}

8.2 文生图

@Bean
ImageModel imageModel() { ... }

// 生成图片
ImageResponse response = imageModel.call(
    new ImagePrompt("赛博朋克风格的上海外滩夜景", 
        ImageOptions.builder().size("1024x1024").build())
);
String imageUrl = response.getResult().getOutput().getUrl();

8.3 语音转文字 & 文字转语音

Spring AI 集成了 Whisper、TTS 等模型，支持音频文件的转录和合成，为语音交互应用奠定基础。

8.4 流式处理的完整链路

在生产环境中，流式输出是必须的。Spring AI 的流式支持贯穿全栈：

// Controller 层 SSE
@GetMapping(value = "/chat/stream", produces = TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> stream(@RequestParam String msg) {
    return chatClient.prompt()
            .user(msg)
            .stream()
            .content()
            .map(content -> ServerSentEvent.<String>builder()
                    .data(content)
                    .event("message")
                    .build())
            .concatWith(Flux.just(ServerSentEvent.<String>builder()
                    .event("done")
                    .build()));
}

前端配合 EventSource 或 fetch + ReadableStream 即可实现打字机效果。注意：流式模式下 Function Calling 同样支持，Spring AI 会自动缓冲工具调用片段，组装完成后执行。

---

9. 第八章：Agent 智能体编排------从单点能力到复杂任务 {#9-第八章}

单个 LLM 调用解决不了复杂问题。Agent 是将 LLM 作为推理引擎，结合规划、记忆、工具使用的自主系统。

9.1 ReAct 模式

Spring AI 内置 ReAct（Reasoning + Acting）Agent 实现：

ReActAgent agent = ReActAgent.builder()
        .chatClient(chatClient)
        .tools(List.of(searchTool, calculatorTool, codeExecutorTool))
        .maxIterations(10)
        .build();

AgentResponse response = agent.run("分析A股新能源板块过去一周走势并给出投资建议");

Agent 会自主思考→选择工具→观察结果→继续思考，直到得出结论。

9.2 多 Agent 协作

对于复杂业务流程，可以编排多个专职 Agent：

// 研究Agent：负责搜集信息
// 分析Agent：负责数据分析
// 写作Agent：负责撰写报告
// 审核Agent：负责质量把关

WorkflowAgent team = WorkflowAgent.builder()
        .addAgent("researcher", researchAgent)
        .addAgent("analyst", analystAgent)
        .addAgent("writer", writerAgent)
        .addAgent("reviewer", reviewerAgent)
        .orchestrator(SequentialOrchestrator.builder()
                .flow("researcher → analyst → writer → reviewer")
                .build())
        .build();

9.3 人机协同（Human-in-the-Loop）

关键决策点插入人工审批：

ApprovalAdvisor approvalAdvisor = ApprovalAdvisor.builder()
        .approvalFunction(toolCall -> {
            if (toolCall.name().equals("transfer_money")) {
                return userService.requestApproval(toolCall);
            }
            return ApprovalResult.approved();
        })
        .build();

这确保了 AI 在执行高风险操作时受到人类监督，是企业落地的安全底线。

---

10. 第九章：生产环境落地------可观测性、安全与性能调优 {#10-第九章}

10.1 可观测性（Observability）

Spring AI 与 Micrometer + OpenTelemetry 深度集成，开箱即用：

management:
  tracing:
    sampling:
      probability: 1.0
  metrics:
    tags:
      application: my-ai-app

自动采集的指标包括：

• gen_ai.client.token.usage：Token 消耗量（按模型、操作类型分组）
• gen_ai.client.operation.duration：请求延迟
• gen_ai.client.operation.error：错误率
• 完整的 Trace 链路：HTTP → ChatClient → Embedding → VectorStore → Tool Execution

在 Grafana/Prometheus 中可直接构建 AI 专属仪表盘，监控成本和性能。

10.2 安全防护

• Prompt Injection 防御 ：使用 ContentFilterAdvisor 检测恶意输入。
• 敏感数据脱敏：PII Detection Advisor 自动识别并遮蔽手机号、身份证、银行卡号。
• 输出合规检查：Guardrails Advisor 确保 AI 回复不包含违规内容。
• API Key 管理：集成 Vault / KMS，杜绝密钥泄露。

10.3 性能优化

• 语义缓存（Semantic Cache）：相似问题直接返回缓存结果，节省 Token 和延迟。
• 并发工具执行：当 AI 一次调用多个独立工具时，并行执行而非串行。
• 连接池优化：合理配置 HTTP Client 连接池，避免冷启动。
• Native Image：使用 GraalVM 编译为原生镜像，启动时间从 5s 降至 0.3s，内存占用降低 70%，特别适合 Serverless/K8s 弹性场景。
• 虚拟线程：JDK 21+ 开启虚拟线程，大幅提升流式和并发工具调用的吞吐量。

10.4 成本控制

• 模型路由：简单问题用小模型（GPT-4o-mini/Qwen-Turbo），复杂问题用大模型。
• Token 预算：设置单次请求最大 Token 限制，防止异常消耗。
• 用量告警：基于 Micrometer 指标设置阈值告警。

---

11. 第十章：Spring AI vs LangChain4j：选型与未来展望 {#11-第十章}

11.1 对比分析

维度	Spring AI	LangChain4j
定位	Spring 官方 AI 基础设施	独立的 Java AI 框架
生态整合	与 Spring Boot/Data/Security/Cloud 无缝集成	需手动集成 Spring
学习曲线	Spring 开发者零门槛	需学习新概念体系
社区活跃度	Spring 核心团队维护，迭代快	社区驱动，更新频繁
企业特性	内置可观测、安全、重试等企业级支持	部分需自行实现
灵活性	遵循 Spring 约定优于配置	更灵活但配置更多
适用场景	Spring 技术栈的企业应用	非 Spring 项目或轻量级实验

选型建议 ：如果你的项目基于 Spring Boot，Spring AI 是首选。它与现有基础设施的融合度无可替代。如果是纯 AI 研究或非 Spring 项目，LangChain4j 也是优秀选择。

11.2 2026 下半年趋势展望

1. MCP 生态爆发：更多 SaaS 产品提供 MCP Server，AI 连接万物的成本趋近于零。
2. 本地模型崛起：Qwen3、Llama 4 等开源模型能力逼近闭源，Spring AI + Ollama 将成为隐私敏感场景标配。
3. Agent 框架成熟：从 Demo 级 Agent 走向生产级，状态管理、错误恢复、评估体系将标准化。
4. AI-Native 数据库：向量搜索与传统查询深度融合，Spring Data 将进一步抽象多模态数据访问。
5. 端侧 AI：Spring AI 可能拓展到 Android/桌面端，支持边缘推理。

---

12. 结语 {#12-结语}

Spring AI 不仅仅是一个框架，它是 Java 生态在 AI 时代的基础设施升级。它让 Java 开发者能够用自己熟悉的语言、熟悉的模式、熟悉的工具链，构建出世界级的 AI 应用。

AI 不会取代 Java 开发者，但会用 AI 的 Java 开发者将取代不会用的。现在正是入场的最佳时机：

1. 动手实践：克隆 Spring AI Examples 仓库，跑通每一个示例。
2. 改造现有项目：找一个痛点，用 RAG 或 Function Calling 解决它。
3. 参与社区：提 Issue、写博客、贡献代码，与全球开发者共同成长。
4. 保持好奇：AI 领域日新月异，持续学习是唯一不变的竞争力。

希望这篇万字指南能成为你 AI 之旅的可靠伙伴。如果觉得有帮助，欢迎点赞、收藏、转发，让更多 Java 开发者看到属于我们的 AI 时代！