一文掌握 Spring AI：集成主流大模型的完整方案与思考

Spring AI 是 Spring 生态中一个新兴的框架，旨在简化 Java/Spring Boot 应用与主流大语言模型（Large Language Models, LLM）的集成。它提供了一套统一的抽象接口，让开发者无需纠结于不同 AI 提供商的 API 差异，就能轻松接入 OpenAI、Anthropic (Claude)、Hugging Face、Ollama 等模型。Spring AI 于 2023 年发布，2025-2026 年已进入成熟阶段，支持多模态（文本、图像、语音）和嵌入式 AI 能力，特别适合企业级应用如聊天机器人、智能推荐、内容生成等。

本文基于 Spring Boot 3.x 和 Spring AI 1.x（2025 年最新稳定版），从零到一讲解集成方案，包括安装、配置、代码实战和思考。假设你有 Spring Boot 基础，代码可在 IntelliJ IDEA 或 VS Code 中运行。所有示例使用 Maven 构建。

第一步：Spring AI 的核心概念与优势

核心组件：

• AiClient：统一接口，用于调用 LLM 生成响应。
• EmbeddingClient：用于文本嵌入（向量表示），支持搜索/推荐。
• PromptTemplate：模板化提示词，支持变量注入。
• ChatMemory：会话内存管理，支持上下文保持。
• Multi-modal：2025+ 新增，支持图像/语音输入（e.g., GPT-4o）。

优势（为什么用 Spring AI 而不是直接调用 API？）：

• 统一抽象：换模型只需改配置，不改代码（e.g., 从 OpenAI 切换到 Hugging Face）。
• Spring 生态集成：无缝结合 Spring Boot、Security、Data 等。
• 生产级特性：内置重试、限流、监控、异步支持。
• 开源免费：基于 Apache License，无需额外付费。
• 2025-2026 趋势：支持边缘部署（e.g., Ollama 本地模型），降低云依赖；集成 RAG（Retrieval-Augmented Generation）增强知识检索。

局限：计算密集型任务仍需外部 GPU 支持；对自定义模型训练支持有限（需结合 Hugging Face Transformers）。

第二步：安装与项目搭建

1. 创建 Spring Boot 项目：

   • 使用 Spring Initializr（https://start.spring.io）：选择 Spring Boot 3.3.x，添加依赖：Web、Lombok。
   • 下载并导入 IDE。

2. 添加 Spring AI 依赖（pom.xml）：

   <dependencies>
       <!-- Spring AI 核心 -->
       <dependency>
           <groupId>org.springframework.ai</groupId>
           <artifactId>spring-ai-spring-boot-starter</artifactId>
           <version>1.0.0</version>  <!-- 查官网最新版 -->
       </dependency>
   
       <!-- OpenAI 支持 -->
       <dependency>
           <groupId>org.springframework.ai</groupId>
           <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
           <version>1.0.0</version>
       </dependency>
   
       <!-- Anthropic (Claude) 支持 -->
       <dependency>
           <groupId>org.springframework.ai</groupId>
           <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
           <version>1.0.0</version>
       </dependency>
   
       <!-- Hugging Face 支持（需本地或远程模型） -->
       <dependency>
           <groupId>org.springframework.ai</groupId>
           <artifactId>spring-ai-transformers-spring-boot-starter</artifactId>
           <version>1.0.0</version>
       </dependency>
   </dependencies>
   

3. 配置 API Key（application.yml，生产用环境变量避免泄露）：

   spring:
     ai:
       openai:
         api-key: sk-xxx  # 从 OpenAI 官网获取
         base-url: https://api.openai.com/v1  # 可自定义代理
       anthropic:
         api-key: sk-ant-xxx  # 从 Anthropic 官网获取
       huggingface:
         model: meta-llama/Llama-2-7b-chat-hf  # Hugging Face 模型 ID
         access-token: hf_xxx  # Hugging Face Token
   

4. 启动类（启用 Spring AI）：

   @SpringBootApplication
   public class AiDemoApplication {
       public static void main(String[] args) {
           SpringApplication.run(AiDemoApplication.class, args);
       }
   }
   

第三步：集成主流大模型实战

Spring AI 通过 ChatClient 接口统一调用不同模型。以下示例展示文本生成、嵌入和多模态。

3.1 集成 OpenAI（GPT-4o 等）

@Service
public class OpenAiService {
    private final ChatClient chatClient;

    public OpenAiService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();  // 自动注入 OpenAI 配置
    }

    public String generateResponse(String prompt) {
        Prompt aiPrompt = new Prompt(new UserMessage(prompt));
        ChatResponse response = chatClient.call(aiPrompt);
        return response.getResult().getOutput().getContent();
    }

    // 示例：生成代码
    public String generateCode(String description) {
        String prompt = "请用 Python 写一个函数：" + description;
        return generateResponse(prompt);
    }
}

// Controller 示例
@RestController
public class AiController {
    @Autowired
    private OpenAiService openAiService;

    @GetMapping("/generate")
    public String generate(@RequestParam String query) {
        return openAiService.generateResponse(query);
    }
}

测试：访问 /generate?query=解释 Spring AI，返回 AI 生成的解释。

3.2 集成 Anthropic（Claude 系列）

配置类似 OpenAI，只需换依赖和 yml 中的 api-key。代码几乎相同，因为 Spring AI 抽象统一：

// 在 yml 中配置 anthropic.api-key 后，ChatClient 会自动切换（或指定 provider）
public String claudeResponse(String prompt) {
    // 如需指定模型：chatClientBuilder.defaultOptions(AnthropicChatOptions.builder().withModel("claude-3.5-sonnet").build())
    return generateResponse(prompt);  // 复用以上方法
}

优势：Claude 在代码生成和逻辑推理上往往优于 GPT，尤其长上下文处理。

3.3 集成 Hugging Face（开源模型，如 Llama、Mistral）

Hugging Face 支持本地部署或远程 API。需安装 Transformers 库（额外依赖）。

@Service
public class HfService {
    private final EmbeddingClient embeddingClient;  // 用于向量嵌入

    public HfService(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;  // 自动注入 Hugging Face 配置
    }

    // 嵌入示例（用于搜索/推荐）
    public List<Double> embedText(String text) {
        EmbeddingResponse response = embeddingClient.embed(text);
        return response.getResult().getOutput();
    }

    // 生成文本（需配置生成模型）
    public String generateWithHf(String prompt) {
        // 类似 ChatClient，但 Hugging Face 更偏向嵌入和自定义模型
        return "Generated by Hugging Face: " + prompt;  // 简化示例，实际用 TransformersOnnxEmbeddingClient
    }
}

本地运行：下载模型（e.g., huggingface-cli download meta-llama/Llama-2-7b-chat-hf），配置 spring.ai.transformers.onnx.model-uri 为本地路径。

优势：免费、隐私保护；2025 年开源模型性能已接近闭源前沿。

3.4 多模型集成与切换

在 Spring AI 中，通过 @ConditionalOnProperty 或动态配置切换模型：

@Bean
@ConditionalOnProperty(name = "spring.ai.provider", havingValue = "openai")
public ChatClient openAiChatClient() {
    // 配置 OpenAI
}

@Bean
@ConditionalOnProperty(name = "spring.ai.provider", havingValue = "anthropic")
public ChatClient anthropicChatClient() {
    // 配置 Anthropic
}

第四步：高级应用与优化

1. RAG 集成：结合向量数据库（如 Pinecone 或本地 Faiss）增强知识检索。

   // 示例：嵌入 + 检索
   List<Double> queryEmbedding = embeddingClient.embed("查询文本");
   // 用向量搜索数据库，返回相关文档，再注入 Prompt
   

2. 异步 & 流式响应：用 StreamingChatClient 支持实时输出（e.g., 聊天界面）。

   StreamingChatResponse response = streamingChatClient.stream(prompt);
   response.getResults().forEach(System.out::println);  // 流式打印
   

3. 监控与限流：集成 Micrometer/Prometheus 监控调用；用 Resilience4J 限流/重试。

4. 多模态：OpenAI 支持图像输入（ImageMessage）。

   Prompt prompt = new Prompt(List.of(new ImageMessage("描述图像", "image_url")));
   

第五步：思考与 2025-2026 趋势

优势思考：

• Spring AI 让 Java 开发者快速进入 AI 时代，避免从零学 Python/ML 框架。
• 与 Spring Cloud 集成，实现分布式 AI 服务（e.g., 微服务调用 LLM）。
• 成本控制：开源模型（如 Hugging Face）降低依赖云厂商。

挑战与风险：

• 隐私与合规：API 调用泄露数据风险，用本地模型（Ollama）解决。
• 性能瓶颈：LLM 调用延迟高，用缓存（Redis）+ 异步优化。
• 模型选择：OpenAI 强于通用，Claude 强于代码，Hugging Face 强于自定义。
• 未来趋势（2025-2026）：Spring AI 将深化 Agent 支持（多步推理）、边缘 AI（手机/设备部署）、联邦学习（隐私保护）。

学习建议：从官方文档（https://spring.io/projects/spring-ai）起步，实践一个聊天机器人项目。生产前评估模型偏置/幻觉风险。

这份指南覆盖了从入门到落地的核心。如果你想看完整代码仓库或特定模型的扩展示例，直接告诉我，我再细化！