Spring AI 学习指南：在 Spring 生态中无缝集成 AI 能力

Spring AI 是一个旨在简化人工智能（AI）功能集成的开源项目，它将大语言模型（LLM）等 AI 能力无缝融入 Spring 应用开发框架中 。它为 Java 开发者提供了一套标准化的 API和抽象，使得调用不同供应商的 AI 模型（如 OpenAI、Azure OpenAI、Ollama 等）变得像使用普通 Spring Bean 一样简单 。

一、Spring AI 的核心价值与定位

Spring AI 的核心目标是降低 AI 应用的开发门槛，其设计遵循了 Spring 框架一贯的“约定优于配置”和模块化思想 。通过提供统一的抽象接口，它解决了以下痛点：

痛点	Spring AI 的解决方案
模型供应商锁定	提供 ChatClient、EmbeddingClient 等通用接口，轻松切换底层模型供应商 。
复杂集成代码	通过自动配置和 Starter 依赖，只需几行配置即可接入 AI 服务。
缺乏标准化	为对话、文生图、向量计算等常见 AI 任务定义了标准化的编程模型。
工程化挑战	内置了对提示词模板、数据流处理、上下文管理等生产级功能的支持 。

二、核心组件与架构

Spring AI 围绕几个核心抽象构建，理解它们是上手的关键。

1. ChatClient：对话中枢
这是与 LLM 交互的主要接口。无论后端是 OpenAI GPT 还是本地部署的 Ollama，你都可以通过统一的 ChatClient 进行对话 。

// 示例：使用 ChatClient 进行简单对话
@RestController
public class ChatController {
    private final ChatClient chatClient;
    public ChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }
    @GetMapping("/ai/chat")
    public String chat(@RequestParam String message) {
        // 调用统一的ChatClient接口 ChatResponse response = chatClient.call(
            new UserMessage(message)
        );
        return response.getResult().getOutput().getContent();
    }
}

2. EmbeddingClient：向量化引擎
负责将文本、图像等数据转换为向量（嵌入）。这是构建检索增强生成（RAG）应用的基础 。

// 示例：使用 EmbeddingClient 将文本转换为向量
@Service
public class EmbeddingService {
    private final EmbeddingClient embeddingClient;
    public EmbeddingService(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;
    }
    public List<Double> embedText(String text) {
        // 调用EmbeddingClient获取文本向量
        Embedding embedding = embeddingClient.embed(text);
        return embedding.getValues();
    }
}

3. VectorStore：向量数据库抽象
一个用于存储和检索向量的接口。Spring AI 支持多种后端，如 Pinecone、Redis、PGVector 等，通过统一的 VectorStore API 操作，实现了业务代码与底层数据库的解耦 。

4. PromptTemplate：提示词管理
帮助管理和参数化构建发送给 LLM 的提示词，提升可维护性。

// 示例：使用 PromptTemplate
PromptTemplate promptTemplate = new PromptTemplate("""
    请扮演一位{role}，用{style}的风格回答以下问题：
    问题：{question}
    """);
Map<String, Object> model = Map.of(
    "role", "资深Java架构师",
    "style", "简洁专业",
    "question", "如何理解Spring AI的VectorStore抽象？"
);
Prompt renderedPrompt = promptTemplate.render(model);
// 将renderedPrompt传递给ChatClient

三、快速入门：构建你的第一个 Spring AI 应用

下面通过一个简单的步骤，演示如何创建一个能进行对话的 Spring Boot 应用。

步骤1：创建项目并引入依赖
使用 Spring Initializr 创建一个新项目，并添加 spring-ai-openai-spring-boot-starter 依赖（以 OpenAI 为例）。

<!-- pom.xml 关键依赖 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <!-- 请查看Spring AI官方文档获取最新版本 -->
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

步骤 2：配置模型 API 密钥
在 application.yml 中配置你的 OpenAI API 密钥和模型。

# application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:你的API密钥}
      chat:
        options:
          model: gpt-3.5-turbo
          temperature: 0.7

步骤 3：编写一个简单的 REST 控制器
创建一个控制器，注入 ChatClient 并对外提供聊天接口。

@RestController
@RequestMapping("/api/ai")
public class SimpleAIController {
    private final ChatClient chatClient;
    public SimpleAIController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }
    @PostMapping("/chat")
    public Map<String, String> chat(@RequestBody Map<String, String> request) {
        String userMessage = request.get("message");
        if (userMessage == null || userMessage.isBlank()) {
            return Map.of("response", "请输入有效内容。");
        }
        // 调用AI模型
        String aiResponse = chatClient.call(userMessage);
        return Map.of("response", aiResponse);
    }
}

步骤 4：运行与测试
启动 Spring Boot 应用，使用 curl 或 Postman 测试接口。

curl -X POST http://localhost:8080/api/ai/chat \
  -H "Content-Type: application/json" \
d '{"message":"请用一句话介绍Spring AI"}'

四、进阶实战：构建 RAG 应用

检索增强生成（RAG）是 Spring AI 的强项。以下是一个简化的 RAG 流程代码框架，演示如何从文档加载到智能问答的全过程 。

@Service
public class RAGService {
    private final VectorStore vectorStore;
    private final ChatClient chatClient;
    private final EmbeddingClient embeddingClient;
    // 1. 文档加载与向量化存储 public void indexDocument(String documentText) {
        // 将文档分块（此处简化，实际可使用TextSplitter）
        List<String> chunks = splitDocument(documentText);
        for (String chunk : chunks) {
            // 为每个文本块生成向量 Embedding embedding = embeddingClient.embed(chunk);
            // 构建文档对象并存储到向量数据库 Document doc = new Document(chunk, Map.of("source", "internal_doc"));
            vectorStore.add(List.of(embedding), List.of(doc));
        }
    }
    // 2. 检索与生成 public String answerQuestion(String question) {
        // 将问题转换为向量
        Embedding questionEmbedding = embeddingClient.embed(question);
        // 从向量库中检索最相关的文档块（Top-K）
        List<Document> relevantDocs = vectorStore.similaritySearch(
            SearchRequest.query(questionEmbedding).withTopK(3)
        );
        // 构建包含上下文的提示词
        String context = relevantDocs.stream()
 .map(Document::getContent)
                                     .collect(Collectors.joining("

"));
        Prompt prompt = new Prompt("""
            基于以下上下文信息回答问题。如果上下文不包含答案，请说“根据已知信息无法回答”。
            上下文：
            {context}
            问题：{question}
答案：
            """, Map.of("context", context, "question", question));
        // 调用LLM生成最终答案
        ChatResponse response = chatClient.call(prompt.toUserMessage());
        return response.getResult().getOutput().getContent();
    }
    private List<String> splitDocument(String text) {
        // 简化的分块逻辑，实际应使用Spring AI提供的TextSplitter
        return List.of(text); // 此处仅为示例
    }
}

五、模型连接协议：MCP

对于需要连接本地或私有化部署模型的场景，Spring AI 支持模型连接协议（MCP）。MCP 主要提供了两种传输机制 ：

传输机制	特点	适用场景
SSE	基于 HTTP 的服务器发送事件，单向流式通信。	适合浏览器或需要服务器推送结果的 Web 应用。
stdio	标准输入输出，通过进程间通信。	适合与本地进程（如 Ollama 服务）进行交互，延迟更低。

配置 MCP 客户端连接到本地 Ollama 服务的示例：

# application.yml 配置 MCP 连接
spring:
  ai:
    mcp:
      clients:
        ollama-client:
          transport: stdio          command: ollama
          args: run llama2

六、生产实践与最佳建议

1. 提示词工程：将复杂的提示词模板化、外部化（如存储在数据库中），便于管理和 A/B 测试 。
2. 性能与监控：对于高频调用，考虑启用缓存（如对 EmbeddingClient 的结果缓存），并集成 Spring Boot Actuator 或 Micrometer 来监控 AI 调用的延迟和成功率 。
3. 错误处理与降级：AI 服务调用可能不稳定，务必实现重试、熔断和降级策略（可借助 Spring Cloud CircuitBreaker）。
4. 安全与合规：注意用户输入和 AI 输出的内容安全过滤，避免注入攻击和不恰当内容生成。处理敏感数据时，关注模型供应商的数据合规政策。
5. 多模型策略：利用 Spring AI 的抽象，可以轻松配置多个 ChatClient Bean，根据场景（如成本、性能、准确性）动态路由请求。

七、学习资源与生态

• 官方文档：首要学习资源，包含详细的 API 说明和概念指南。
• Spring Cloud Alibaba AI：如果你主要使用阿里云的通义系列模型，可以关注此子项目，它提供了对阿里云模型的深度适配和便捷的 Starter 。
• 社区与教程：CSDN、Bilibili 等平台上有丰富的入门教程和实战案例视频，可以帮助你从不同维度理解 Spring AI 。

Spring AI 通过其清晰的抽象和与 Spring 生态的深度集成，正成为 Java 开发者构建 AI 增强型应用的首选框架。从简单的对话接口到复杂的 RAG 系统，它都能提供强有力的支持。