Spring AI 使用介绍

面向 Java 开发者的企业级 AI 开发框架。通过统一的抽象层，将 AI 模型、向量数据库、工具调用等核心能力无缝集成到 Spring 生态体系中，让 Java 开发者也能高效构建生成式 AI 应用。

---

目录

1. 框架概述
2. 快速开始
3. Chat Model API
4. ChatClient 流式 API
5. 工具调用 (Function Calling)
6. RAG 与向量数据库
7. ETL 数据管道
8. Advisors API
9. 会话记忆
10. 支持的模型与向量库
11. 最佳实践与总结

---

1. 框架概述

Spring AI 是 Spring 官方推出的 AI 集成框架，其核心理念是：将企业数据与 API 同 AI 模型连接起来。它借鉴了 Python 生态中 LangChain、LlamaIndex 等项目的思路，但专为 Java/Spring 生态设计，相信下一波生成式 AI 应用不仅属于 Python 开发者，也将遍布各种编程语言。

Spring AI 提供了一套可移植的抽象层，开发者可以在不同 AI 供应商之间自由切换，而只需最少的代码改动。2025 年 5 月，Spring AI 1.0 GA 正式发布[1]；截至本文编写时，Spring AI 已发布 2.0.0 版本，支持 Spring Boot 4.0.x。

特性	说明
多模型统一 API	OpenAI、Anthropic、Ollama、Mistral、Amazon Bedrock 等主流模型统一接口
向量数据库支持	PgVector、Redis、Milvus、Pinecone、Chroma 等 15+ 向量库统一抽象
工具调用	让 AI 模型调用你的 Java 方法，实现信息检索与自动化操作
RAG 开箱即用	内置 ETL 管道、文档加载器、文本分割器，快速构建检索增强生成
结构化输出	AI 返回结果直接映射为 Java POJO / Record
MCP 协议	原生支持 Model Context Protocol，接入或暴露 MCP 服务

---

2. 快速开始

2.1 项目初始化

推荐通过 Spring Initializr 创建项目，选择所需的 AI Models 和 Vector Stores 依赖。

2.2 依赖管理 (Maven)

首先引入 Spring AI BOM 进行版本管理：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>2.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

然后添加所需的 Starter，例如使用 OpenAI：

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

2.3 基础配置

在 application.yml 中配置 API Key 等参数：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o
          temperature: 0.7

2.4 第一个 AI 应用

只需几行代码即可完成第一次 AI 调用：

@RestController
public class AiController {

    private final ChatClient chatClient;

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

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

提示： Spring Boot 自动配置会为你创建 ChatClient.Builder Bean，直接注入即可使用。

---

3. Chat Model API

Chat Model API 是 Spring AI 的核心抽象，定义了与 AI 对话模型交互的统一接口。

3.1 核心接口

ChatModel 接口提供了两种调用方式：

public interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {

    // 简单字符串调用
    default String call(String message) { ... }

    // 完整的 Prompt 调用
    @Override
    ChatResponse call(Prompt prompt);
}

StreamingChatModel 则提供流式响应：

public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {

    default Flux<String> stream(String message) { ... }

    @Override
    Flux<ChatResponse> stream(Prompt prompt);
}

3.2 Prompt 与 Message 体系

Prompt 封装了一组 Message 对象和可选的模型参数。Message 按角色分为：

消息类型	角色说明	使用场景
SystemMessage	系统消息	定义 AI 的行为指令和角色设定
UserMessage	用户消息	用户的输入、查询、指令
AssistantMessage	助手消息	AI 的回复内容
ToolResponseMessage	工具响应	工具执行后的结果回传给模型

3.3 ChatOptions 配置

可通过 ChatOptions 控制模型行为的核心参数：

ChatOptions options = OpenAiChatOptions.builder()
    .model("gpt-4o")           // 模型名称
    .temperature(0.7)          // 随机性 (0-2)
    .topP(0.9)                 // 核采样
    .maxTokens(2048)           // 最大输出 Token 数
    .frequencyPenalty(0.0)     // 频率惩罚
    .presencePenalty(0.0)      // 存在惩罚
    .stopSequences(List.of("\n"))  // 停止序列
    .build();

---

4. ChatClient 流式 API

ChatClient 是 Spring AI 提供的高级 Fluent API，风格类似于 Spring 的 WebClient 和 RestClient，让与 AI 模型的交互更加优雅和直觉。

4.1 创建 ChatClient

通过自动注入的 Builder 创建：

@RestController
class MyController {

    private final ChatClient chatClient;

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

4.2 Fluent API 用法

三种 prompt 初始化方式：

// 方式一：无参初始化，自由构建
chatClient.prompt()
    .system("你是一个友好的助手")
    .user("你好，介绍一下你自己")
    .call()
    .content();

// 方式二：传入 Prompt 对象
chatClient.prompt(prompt).call().content();

// 方式三：快捷字符串
chatClient.prompt("讲个笑话").call().content();

4.3 响应类型

// 返回纯文本
String text = chatClient.prompt("说个笑话").call().content();

// 返回完整 ChatResponse（含元数据、Token 用量等）
ChatResponse response = chatClient.prompt("说个笑话").call().chatResponse();

// 返回结构化 Java 对象
record ActorFilms(String actor, List<String> movies) {}
ActorFilms films = chatClient.prompt()
    .user("生成一个演员的电影作品列表")
    .call()
    .entity(ActorFilms.class);

// 流式响应
Flux<String> stream = chatClient.prompt()
    .user("讲个长故事")
    .stream()
    .content();

4.4 Prompt 模板

支持带变量的模板，变量在运行时替换：

String answer = chatClient.prompt()
    .user(u -> u
        .text("列出 5 部由 {composer} 配乐的电影")
        .param("composer", "Hans Zimmer"))
    .call()
    .content();

4.5 使用多个模型

通过配置 spring.ai.chat.client.enabled=false 禁用默认自动配置后，可以手动创建多个 ChatClient：

@Configuration
public class ChatClientConfig {

    @Bean
    public ChatClient openAiChatClient(OpenAiChatModel chatModel) {
        return ChatClient.create(chatModel);
    }

    @Bean
    public ChatClient anthropicChatClient(AnthropicChatModel chatModel) {
        return ChatClient.create(chatModel);
    }
}

多模型使用场景： 不同任务使用不同模型（复杂推理用大模型、简单任务用小模型）、故障切换、A/B 测试、让用户自选模型等。

---

5. 工具调用 (Function Calling)

工具调用让 AI 模型能够请求执行客户端的方法，从而获取实时信息或执行操作。这是构建智能 Agent 的关键能力。

5.1 工作原理

用户 → ChatClient → AI模型 → ChatClient → 工具方法
                    ↓                        ↓
                    ← 请求调用工具(附带参数) ←
                    ←   返回结果             ←
                    ↓
ChatClient → AI模型 → 生成最终回答 → 用户

工具调用流程说明：

1. 用户向 ChatClient 提问
2. ChatClient 将 Prompt + 工具定义发送给 AI 模型
3. AI 模型请求调用工具（附带参数）
4. ChatClient 执行工具方法
5. 工具方法返回结果给 ChatClient
6. ChatClient 将工具执行结果发送给 AI 模型
7. AI 模型生成最终回答
8. ChatClient 将结果返回给用户

5.2 定义工具 - @Tool 注解

使用 @Tool 注解将 Java 方法声明为可被 AI 调用的工具：

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class DateTimeTools {

    @Tool(description = "获取用户所在时区的当前日期和时间")
    String getCurrentDateTime() {
        return LocalDateTime.now().toString();
    }

    @Tool(description = "为用户设置闹钟")
    void setAlarm(
        @ToolParam(description = "闹钟时间，ISO-8601 格式") String time
    ) {
        LocalDateTime alarmTime = LocalDateTime.parse(time,
            DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("闹钟已设置：" + alarmTime);
    }
}

5.3 使用工具

String response = ChatClient.create(chatModel)
    .prompt("帮我设置一个 10 分钟后的闹钟")
    .tools(new DateTimeTools())
    .call()
    .content();

关键点： 模型只能"请求"工具调用，实际执行由 ChatClient 完成。模型永远不会直接访问你的 API，这是一个重要的安全设计。

5.4 @ToolParam 注解说明

属性	说明
description	参数描述，帮助模型理解如何使用此参数
required	是否为必填参数，默认为 true

---

6. RAG 与向量数据库

检索增强生成（RAG）是 Spring AI 最重要的应用场景之一。其核心思路是：先从向量数据库中检索与用户问题相关的文档，再将这些文档作为上下文提供给 AI 模型，从而生成更准确、更有依据的回答。

6.1 VectorStore 接口

Spring AI 提供统一的 VectorStore 接口，支持读写操作：

public interface VectorStore extends DocumentWriter, VectorStoreRetriever {

    // 添加文档到向量库
    void add(List<Document> documents);

    // 按文档 ID 删除
    void delete(List<String> idList);

    // 按过滤表达式删除
    void delete(Filter.Expression filterExpression);

    // 相似性搜索
    List<Document> similaritySearch(SearchRequest request);
}

6.2 文档写入与检索

// 写入文档
Document doc = new Document("Spring AI 是面向 Java 开发者的 AI 框架",
    Map.of("source", "spring-ai-guide", "type", "intro"));
vectorStore.add(List.of(doc));

// 检索相似文档
List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("什么是 Spring AI？")
        .topK(5)                          // 返回最相似的 5 条
        .similarityThreshold(0.75)        // 相似度阈值
        .filterExpression("type == 'intro'") // 元数据过滤
        .build()
);

6.3 元数据过滤

Spring AI 提供了类似 SQL WHERE 子句的 DSL 过滤表达式：

// 字符串表达式
"country == 'UK' && year >= 2020 && isActive == true"

// 编程式构建
Filter.Expression filter = new Filter.Expression(
    FilterExpressionOperator.AND,
    new Filter.Expression("country", "UK"),
    new Filter.Expression("year", ">=", 2020)
);

---

7. ETL 数据管道

ETL（Extract-Transform-Load）管道是 RAG 应用的数据基础，负责将各种格式的外部数据转化为可被向量数据库存储和检索的 Document 对象。

7.1 三大核心组件

DocumentReader          →    DocumentTransformer    →    DocumentWriter
(读取文档)                    (转换处理)                   (写入存储)
    ↑                             ↑                            ↑
PDF / DOCX / HTML          VectorStore / 文件系统
Markdown / JSON / Text

图：ETL 管道三大组件

7.2 支持的文档格式

格式	Reader 类	说明
PDF (按页)	PagePdfDocumentReader	按页面分割 PDF
PDF (按段落)	ParagraphPdfDocumentReader	按段落智能分割
DOCX / PPTX	TikaDocumentReader	基于 Apache Tika
HTML	JsoupDocumentReader	基于 JSoup，支持 CSS 选择器
Markdown	MarkdownDocumentReader	可配置代码块、引用的提取
JSON	JsonReader	支持 JSON Pointer 定位
纯文本	TextReader	最基础的文本读取

7.3 文本分割器

// TokenTextSplitter - 按 Token 数分割
TokenTextSplitter splitter = TokenTextSplitter.builder()
    .defaultChunkSize(800)
    .defaultOverlapSize(100)
    .build();

List<Document> chunks = splitter.apply(documents);

7.4 完整 ETL 流程

// 读取 -> 分割 -> 写入向量库，一行代码搞定
vectorStore.write(
    tokenTextSplitter.split(
        pdfReader.read()
    )
);

7.5 HTML 文档读取示例

JsoupDocumentReaderConfig config = JsoupDocumentReaderConfig.builder()
    .selector("article p")                  // CSS 选择器
    .charset("UTF-8")
    .includeLinkUrls(true)                   // 包含链接 URL
    .metadataTags(List.of("author", "date")) // 提取 meta 标签
    .build();

JsoupDocumentReader reader = new JsoupDocumentReader(resource, config);
List<Document> docs = reader.get();

---

8. Advisors API

Advisors 是 Spring AI 中封装通用 AI 模式的机制。它们可以在请求发送到模型之前和模型响应返回之后对数据进行转换，并提供跨模型的可移植性。

8.1 Advisor 链

Advisors 以链式方式工作，每个 Advisor 可以修改输入/输出：

用户请求 → Advisor 1(日志) → Advisor 2(RAG检索) → Advisor 3(工具调用) → AI 模型
                                                                              ↓
用户 ← Advisor 1响应处理 ← Advisor 2响应处理 ← Advisor 3响应处理 ← AI 模型响应

图：Advisor 处理链

8.2 内置 Advisor

Advisor	功能
ToolCallingAdvisor	自动处理工具调用请求的完整生命周期
QuestionAnswerAdvisor	RAG 问答：自动检索相关文档并注入上下文
MessageChatMemoryAdvisor	会话记忆：自动管理对话历史
SimpleLoggerAdvisor	日志记录：记录请求和响应

---

9. 会话记忆

默认情况下，每次调用 AI 模型都是独立的，模型不会"记住"之前的对话。通过 Chat Memory 机制，可以让 AI 保持多轮对话的上下文。

9.1 配置方式

@Bean
public ChatMemory chatMemory() {
    return MessageWindowChatMemory.builder()
        .maxMessages(20)       // 保留最近 20 条消息
        .build();
}

9.2 使用方式

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory()))
    .build();

// 第一轮
chatClient.prompt().user("我叫小明").call().content();
// 第二轮 - AI 会记得你叫小明
chatClient.prompt().user("我叫什么名字？").call().content();

注意： 内存管理直接影响 Token 消耗。建议合理设置 maxMessages，避免过多历史消息导致成本过高。

---

10. 支持的模型与向量库

10.1 AI 模型供应商

供应商	支持类型	流式	工具调用
OpenAI	Chat / Embedding / Image / TTS / STT	✅	✅
Anthropic (Claude)	Chat	✅	✅
Ollama	Chat / Embedding	✅	✅
Mistral AI	Chat / Embedding	✅	✅
Amazon Bedrock	Chat / Embedding	✅	✅
Google Vertex AI	Chat / Embedding	✅	✅
Microsoft Azure	Chat / Embedding	✅	✅

10.2 向量数据库

数据库	类型	数据库	类型
PgVector	PostgreSQL 扩展	Pinecone	全托管向量服务
Redis	Redis Stack 搜索	Chroma	开源向量库
Milvus	高性能向量库	Qdrant	高性能向量引擎
Elasticsearch	OpenSearch	Neo4j	图数据库向量搜索
MongoDB Atlas	Atlas Vector Search	Cassandra	Apache Cassandra
Oracle	Oracle Vector Search	MariaDB	MariaDB Vector

---

11. 最佳实践与总结

架构建议

• 使用 ChatClient 而非直接使用 ChatModel，获得更强大的 Fluent API 和 Advisor 支持
• 通过 Advisor 模式 封装通用逻辑（如日志、记忆、RAG），保持代码整洁
• 利用 Spring Boot Starter 简化配置，避免手动管理 Bean
• 使用 BOM 管理依赖版本，确保组件兼容性
• 对生产环境配置 相似度阈值 和 Top-K 参数，控制检索质量

性能优化

• 使用 TokenTextSplitter 的批量策略避免超出 Token 限制
• 对于多模型场景，使用 mutate() 方法复用配置
• 开启 流式响应 提升用户体验（stream().content()）
• 合理使用 会话记忆窗口，控制 Token 消耗

安全注意事项

• AI 模型永远不会直接访问你的 API，所有工具调用由客户端执行
• 通过 Tool Context 控制工具可访问的数据范围
• 不要在 Prompt 中暴露敏感信息，使用模板变量隔离
• 配置 内容审核 (Moderation) API 对输入输出进行过滤

推荐学习路径： ChatClient 基础 → 工具调用 → 结构化输出 → RAG/向量库 → Advisors → MCP 集成。循序渐进，先跑通简单 Demo 再深入复杂场景。

---

参考资料

1. Spring AI 官方文档 - Index & Getting Started
   https://docs.spring.io/spring-ai/reference/index.html
2. Spring AI 官方文档 - Chat Client API
   https://docs.spring.io/spring-ai/reference/api/chatclient.html
3. Spring AI 官方文档 - Chat Model API
   https://docs.spring.io/spring-ai/reference/api/chatmodel.html
4. Spring AI 官方文档 - Tool Calling
   https://docs.spring.io/spring-ai/reference/api/tools.html
5. Spring AI 官方文档 - Vector Databases
   https://docs.spring.io/spring-ai/reference/api/vectordbs.html
6. Spring AI 官方文档 - ETL Pipeline
   https://docs.spring.io/spring-ai/reference/api/etl-pipeline.html

---