Spring AI 工程分析文档

请关注微信公众号：阿呆-bot

1. 工程结构概览

Spring AI 是一个大型的多模块 Maven 项目，采用模块化设计，主要分为核心模块、模型实现、向量存储、自动配置等几大类。下面我们来看看主要的目录结构（已排除 spec、doc 等文档相关文件夹）：

复制代码

spring-ai-main/
├── spring-ai-commons/              # 基础公共模块，无其他 Spring AI 依赖
├── spring-ai-model/                 # AI 能力抽象层（ChatModel、EmbeddingModel 等）
├── spring-ai-vector-store/          # 向量数据库统一抽象
├── spring-ai-client-chat/           # 高级对话 AI API（ChatClient）
├── spring-ai-rag/                   # 检索增强生成框架
├── spring-ai-retry/                 # 重试机制
├── spring-ai-bom/                   # 依赖管理 BOM
│
├── models/                          # AI 模型实现
│   ├── spring-ai-openai/           # OpenAI 实现
│   ├── spring-ai-anthropic/         # Anthropic Claude 实现
│   ├── spring-ai-azure-openai/      # Azure OpenAI 实现
│   ├── spring-ai-ollama/            # Ollama 本地模型
│   └── ... (20+ 个模型实现)
│
├── vector-stores/                   # 向量数据库实现
│   ├── spring-ai-pgvector-store/   # PostgreSQL/PGVector
│   ├── spring-ai-chroma-store/      # Chroma
│   ├── spring-ai-pinecone-store/    # Pinecone
│   ├── spring-ai-qdrant-store/      # Qdrant
│   └── ... (20+ 个向量存储实现)
│
├── auto-configurations/             # Spring Boot 自动配置
│   ├── models/                      # 模型自动配置
│   ├── vector-stores/               # 向量存储自动配置
│   └── mcp/                         # MCP 协议自动配置
│
├── document-readers/                # 文档读取器
│   ├── pdf-reader/                    # PDF 解析
│   ├── markdown-reader/              # Markdown 解析
│   └── tika-reader/                 # 通用文档解析
│
├── memory/repository/               # 对话记忆存储实现
│   ├── spring-ai-model-chat-memory-repository-jdbc/
│   ├── spring-ai-model-chat-memory-repository-mongodb/
│   └── ...
│
└── spring-ai-spring-boot-starters/  # Spring Boot Starters
    ├── spring-ai-starter-model-openai/
    ├── spring-ai-starter-vector-store-pgvector/
    └── ...

2. 技术体系与模块关系

Spring AI 采用分层架构设计，从底层到上层依次是：基础层 → 抽象层 → 实现层 → 自动配置层。这种设计让代码既灵活又易于扩展。

技术栈说明：

Java 17 + Spring Boot 3.5.7：现代 Java 企业级开发栈
Maven：依赖管理和构建工具
响应式编程：支持 Reactor 流式处理
观察性：集成 Micrometer，提供指标和追踪

3. 关键场景示例代码

3.1 使用 ChatModel 进行对话

这是最基础的用法，直接调用 AI 模型：

java 复制代码

@Autowired
private ChatModel chatModel;

public String chat(String userMessage) {
    // 简单调用
    String response = chatModel.call(userMessage);
    return response;
    
    // 或者使用 Prompt 对象，更灵活
    Prompt prompt = new Prompt(new UserMessage(userMessage));
    ChatResponse response = chatModel.call(prompt);
    return response.getResult().getOutput().getContent();
}

3.2 使用 ChatClient 流式 API

ChatClient 提供了更友好的流式 API，类似 WebClient 的风格：

java 复制代码

@Autowired
private ChatModel chatModel;

public void streamChat(String question) {
    ChatClient chatClient = ChatClient.create(chatModel);
    
    chatClient.prompt()
        .user(question)
        .stream()
        .content()
        .doOnNext(chunk -> System.out.print(chunk))
        .blockLast();
}

3.3 使用 VectorStore 进行相似度搜索

向量存储是 RAG 的核心，用于存储和检索文档：

java 复制代码

@Autowired
private EmbeddingModel embeddingModel;
@Autowired
private VectorStore vectorStore;

public void storeAndSearch() {
    // 1. 存储文档
    List<Document> documents = Arrays.asList(
        new Document("Spring AI 是一个 AI 应用开发框架"),
        new Document("支持多种 AI 模型和向量数据库")
    );
    vectorStore.add(documents);
    
    // 2. 相似度搜索
    List<Document> results = vectorStore.similaritySearch("AI 框架");
    results.forEach(doc -> System.out.println(doc.getContent()));
}

3.4 RAG 模式：检索增强生成

这是 Spring AI 的杀手级功能，结合向量存储和 AI 模型：

java 复制代码

@Autowired
private ChatClient chatClient;
@Autowired
private VectorStore vectorStore;

public String ragQuery(String question) {
    // 使用 QuestionAnswerAdvisor 自动处理 RAG
    QuestionAnswerAdvisor advisor = new QuestionAnswerAdvisor(vectorStore);
    
    return chatClient.prompt()
        .user(question)
        .advisors(advisor)
        .call()
        .content();
}

4. 入口类与关键类关系

Spring AI 的入口主要是各种 AutoConfiguration 类，它们负责自动配置 Bean。核心接口之间的关系如下：

关键入口类说明：

AutoConfiguration 类 ：位于 auto-configurations/ 目录，根据 classpath 自动配置相应的 Bean
ChatModel：所有对话模型的统一接口，包括 OpenAI、Anthropic 等
VectorStore：向量数据库的统一抽象，支持 PGVector、Chroma、Pinecone 等
ChatClient：高级 API，提供流式、Advisor 等高级特性

5. 外部依赖

Spring AI 的外部依赖主要分为几大类：

5.1 AI 模型提供商 SDK

OpenAI：官方 Java SDK
Anthropic：Claude API 客户端
Azure OpenAI：Azure 服务 SDK
AWS Bedrock：AWS SDK for Java
Google GenAI：Google AI SDK
Ollama：本地模型运行框架

5.2 向量数据库客户端

PostgreSQL/PGVector：JDBC + pgvector 扩展
Chroma：Python 服务的 HTTP 客户端
Pinecone：官方 Java SDK
Qdrant：REST API 客户端
Redis：Spring Data Redis
MongoDB Atlas：MongoDB Java Driver
Elasticsearch：Elasticsearch Java Client
还有 Neo4j、Weaviate、Milvus 等 10+ 种实现

5.3 文档处理

Apache Tika：通用文档解析
PDFBox：PDF 处理
Jsoup：HTML 解析
CommonMark：Markdown 解析

5.4 构建和测试工具

Maven：构建工具
Testcontainers：集成测试容器
JaCoCo：代码覆盖率
Checkstyle：代码风格检查

6. 工程总结

Spring AI 这个项目，说白了就是 Spring 生态在 AI 领域的延伸。它的设计理念非常清晰：可移植性 + 模块化 + POJO 优先。

6.1 设计亮点

第一，抽象做得好。不管是 OpenAI 还是 Anthropic，不管是 PGVector 还是 Pinecone，都用统一的接口。这意味着你可以轻松切换提供商，不用改业务代码。

第二，模块化设计。核心抽象和具体实现完全分离，想用哪个模型、哪个向量数据库，引入对应的 starter 就行。这种设计让项目既灵活又不会臃肿。

第三，Spring Boot 深度集成。自动配置、Starters、观察性，该有的都有。用起来就像用 Spring Data 一样自然。

6.2 核心价值

Spring AI 解决的核心问题是：如何把企业数据和 API 连接到 AI 模型。它提供了：

RAG 框架：让 AI 能"看到"你的数据
工具调用：让 AI 能"操作"你的系统
对话记忆：让 AI 能"记住"对话历史
流式处理：让 AI 响应更流畅

6.3 适用场景

这个框架特别适合：

企业内部知识库问答系统
文档智能检索和分析
AI 驱动的业务自动化
多模型、多数据源的 AI 应用

总的来说，Spring AI 是一个企业级、生产就绪的 AI 应用开发框架。它把复杂的 AI 集成工作标准化、简单化，让 Java 开发者也能轻松构建 AI 应用。如果你熟悉 Spring 生态，上手会非常快。

Spring AI 代码分析（一）--工程结构

Spring AI 工程分析文档

1. 工程结构概览

2. 技术体系与模块关系

3. 关键场景示例代码

3.1 使用 ChatModel 进行对话

3.2 使用 ChatClient 流式 API

3.3 使用 VectorStore 进行相似度搜索

3.4 RAG 模式：检索增强生成

4. 入口类与关键类关系

5. 外部依赖

5.1 AI 模型提供商 SDK

5.2 向量数据库客户端

5.3 文档处理

5.4 构建和测试工具

6. 工程总结

6.1 设计亮点

6.2 核心价值

6.3 适用场景