Spring AI 框架核心特性与实战指南

Spring AI 框架完整指南

Spring AI 是 Spring 生态中专为 AI 工程设计的应用框架，于 2024 年正式推出，并在 2025 年快速发展，已成为 Java 开发者构建生成式 AI 应用的首选工具。它简化了与大型语言模型（LLM）、嵌入模型和向量数据库的集成，让企业级 Java 应用轻松接入 AI 能力，如聊天机器人、RAG（Retrieval Augmented Generation）和智能代理。根据官方文档和 2025 年最新发布（如 Spring AI 1.1 GA），本指南从基础到高级全面解析，结合代码示例和最佳实践，帮助你快速上手。

一、Spring AI 概述

Spring AI 的核心使命是'连接企业数据和 API 与 AI 模型'，它不是 Python AI 框架（如 LangChain）的直接移植，而是为 Java/Spring 生态量身定制，提供可移植的抽象层。不同于传统 Spring 模块，它聚焦生成式 AI，强调简洁性和生产就绪（如自动配置、观测性）。

为什么选择 Spring AI？（2025 年价值）

• Java 原生：无需切换到 Python，保持端到端 Java 开发。
• Spring 集成：无缝嵌入 Spring Boot，支持自动装配和 Starter。
• 多提供商支持：统一 API 接入 OpenAI、Anthropic、Ollama 等，避免供应商锁定。
• 企业级特性：工具调用、RAG、评估框架，解决幻觉（hallucination）和安全性问题。
• 2025 年现状：Spring AI 1.1 GA（2025 年 11 月发布），引入 Agents 框架和 Bench 评估工具；兼容 Spring Framework 7.x 和 Java 21+。

适用场景：聊天助手、文档 Q&A、智能搜索、图像生成、代理式 AI（如代码生成工具）。

二、关键特性

Spring AI 的特性围绕可移植性和易用性设计，以下是核心亮点：

特性	描述	2025 年亮点
ChatClient API	流式/同步聊天接口，类似 WebClient，支持多模型。	集成 MCP（Model Context Protocol）协议，提升代理间通信。
嵌入与向量存储	嵌入模型生成向量，向量数据库（如 PGVector、Neo4j）支持 RAG。	新增 SQL-like 过滤 API，简化元数据查询。
工具/函数调用	模型调用客户端工具（如天气 API），实现实时交互。	@Tool 注解简化服务器暴露，支持 OAuth 安全。
结构化输出	AI 输出映射到 POJO，避免解析 JSON。	增强类型安全，支持复杂对象。
观测性	追踪 AI 操作，支持 Prometheus/OpenTelemetry。	新增聊天完成日志，便于调试。
评估框架	Bench 工具评估生成内容，检测幻觉。	Spring AI Bench：基准测试和评估套件。
文档 ETL	摄取/转换/加载框架，处理企业数据。	升级 Tika 3.2.3，支持多模态（文本 + 图像）。
代理与 Advisors	构建代理模式，封装 AI 模式（如重试、缓存）。	Agents 框架：5 大模式（简单代理、工具链等）。

这些特性让 Spring AI 适用于从简单聊天到复杂代理的场景。

三、架构解析

Spring AI 的架构基于抽象层 + 实现多态：

• 抽象层：ChatModel、EmbeddingModel、VectorStore 等接口，提供统一 API。
• 实现层：每个提供商（如 OpenAIChatModel）实现抽象，支持同步/流式。
• Spring Boot 层：Starter 自动配置，@EnableSpringAi 启用。
• 高级层：Advisors（模式封装）、MCP（代理协议）。

流程示例：用户输入 → ChatClient → 模型提供商 → 输出（可流式） → Advisors 处理（日志/缓存）。

2025 更新：兼容 GraalVM Native，提升冷启动性能；MCP 支持 stdio/HTTP SSE 端点。

四、支持的 AI 提供商

Spring AI 支持 20+ 提供商，确保灵活性。

类别	提供商示例	支持功能
聊天/LLM	OpenAI、Anthropic、Microsoft、Amazon Bedrock、Google Vertex、Ollama	聊天、流式、工具调用
嵌入	OpenAI、Hugging Face、Cohere、Google Vertex	向量生成
图像	OpenAI DALL-E、Stability AI、Amazon Bedrock	文本到图像、多模态
向量数据库	PGVector、Neo4j、Milvus、Pinecone、Redis、Weaviate	RAG、相似性搜索

配置示例（application.yml）：

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

五、快速入门

步骤 1: 添加依赖

使用 Spring Initializr（start.spring.io）添加 spring-ai-openai-spring-boot-starter。

Maven 示例：

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

步骤 2: 配置 API Key

在 application.yml 中设置密钥（环境变量推荐）。

步骤 3: 构建简单应用

启动类：

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

六、基本用法代码示例

1. 聊天交互（ChatClient）

@Service
public class ChatService {
    private final ChatClient chatClient;

    public ChatService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    public String chat(String message) {
        return chatClient.prompt().user(message).call().content(); // 同步响应
    }
}

流式示例：.call().stream() 返回 Flux。

2. 嵌入生成

@Service
public class EmbeddingService {
    private final EmbeddingModel embeddingModel;

    public List<Double> embed(String text) {
        EmbeddingResponse response = embeddingModel.embed(text);
        return response.getOutput().get(0).getEmbedding();
    }
}

3. 图像生成

@Service
public class ImageService {
    private final ImageModel imageModel;

    public String generateImage(String prompt) {
        ImageResponse response = imageModel.call(new Prompt(new ImagePrompt(prompt)));
        return response.getResult().getOutput().getUrl(); // 返回图像 URL
    }
}

支持多模态：输入图像 + 文本。

4. RAG 示例（向量存储）

使用 PGVector：

@Autowired
private VectorStore vectorStore;

public SearchResult ragSearch(String query) {
    vectorStore.add(List.of(Document.builder().content("企业数据...").build()));
    return vectorStore.similaritySearch(SimilarityRequest.query(query));
}

集成 ChatClient：chatClient.prompt().user(query).advisors(ragAdvisor).call()。

七、高级主题

1. RAG（Retrieval Augmented Generation）

• 核心：嵌入查询 → 向量搜索 → 注入上下文 → LLM 生成。
• 2025 实践：模块化 RAG 架构，支持多向量存储。

2. 代理（Agents）

Spring AI 1.1 引入 Agents 框架，支持 5 大模式：

• 简单代理：基本工具调用。
• 工具链：顺序执行工具。
• 示例：天气代理（调用 MCP 工具）。

@Tool
public String getWeather(String city) {
    /* 调用 API */
}

使用 Advisors 封装模式，如重试/缓存。

3. 评估与 Bench

使用 Spring AI Bench 评估生成质量：

// 伪代码：评估幻觉率
BenchmarkResult result = bench.evaluate(generatedText, expected);

4. 安全与非功能需求

• moderation 模型过滤内容。
• OAuth for MCP。
• 性能：虚拟线程支持，Native Image 兼容。

八、Spring Boot 集成与最佳实践

• Starter 机制：spring-ai-starter-vector-store-pgvector 等，一键集成。
• 观测：集成 Micrometer，监控令牌使用。
• 最佳实践：
  • 使用 Advisors 封装模式，避免重复代码。
  • 优先结构化输出，减少解析错误。
  • 测试：Mock AI 提供商，单元测试 ChatClient。
  • 伦理：评估幻觉，遵守数据隐私（GDPR）。

2025 学习路线：从 ChatClient 入门 → RAG 项目 → Agents 高级 → Bench 优化。