大模型开发框架 —— SpringAI

Spring AI 是 Spring 官方推出的Java 生态 AI 应用开发框架 ，2025 年 5 月发布 1.0 GA 稳定版，核心是把 Spring 的可移植、模块化、POJO 编程原则带入 AI 领域，让 Java/Spring 开发者用熟悉的方式快速集成大模型、向量库、RAG、函数调用等能力，无需从零对接各类 AI SDK。

一、Spring AI 核心定位与设计理念

1.核心定位

• 不是简单的 AI SDK 封装，而是AI 工程化应用框架，解决 "企业数据 / API 与 AI 模型连接" 的核心问题。
• 作为 Spring 生态的自然延伸，深度融合 Spring Boot、Spring Cloud、Spring Security、Spring Data 等组件，提供自动配置、依赖注入、AOP、可观测性、安全等企业级能力。
• 统一了 API 抽象，封装OpenAI、Anthropic、阿里云通义千问等主流AI厂商接口，实现"一次开发，多模型适配"。
• 企业级特性完备，内置全链路监控、安全审计、成本控制、异常处理等生产级能力。
• 轻量级与可扩展性，采用模块化设计，按需引入功能，避免冗余。
• POJO 优先，AI 输入输出直接映射为 Java 对象，支持结构化输出，避免手动解析 JSON。

2.核心模块设计

模块	核心功能	说明
spring-ai-core	基础抽象层	定义 ChatClient、EmbeddingClient、VectorStore、Prompt、Document 等核心接口，是所有能力的基础
spring-ai-chat	聊天模型统一接入	支持同步 / 流式 / 异步调用，提示模板、结构化输出、函数调用
spring-ai-embedding	文本向量化	对接各类嵌入模型，生成语义向量，用于 RAG、语义搜索
spring-ai-vector-store	向量存储统一抽象	支持 Chroma、Milvus、PGVector、Redis、Pinecone 等主流向量库
spring-ai-document	文档处理	文档加载（PDF/Markdown/Word/ 网页）、文本分割、元数据管理
spring-ai-advisors	增强机制（AOP）	内置 RAG、对话记忆、日志、重试、内容过滤等 Advisor，可自定义扩展
spring-ai-function	函数调用（工具调用）	模型主动调用 Java 方法 / 外部 API，获取实时数据
spring-ai-agent	Agent 智能体	自主规划、决策、调用工具 / 模型，完成复杂任务
spring-ai-starters	Spring Boot 自动配置	一键集成各类模型 / 向量库，开箱即用

3.多模型统一接入

Spring AI 提供 统一高层 API，同时保留模型专属能力，支持主流模型提供商：

• 聊天模型（Chat）：OpenAI、Anthropic Claude、Google Gemini、阿里云通义千问、DeepSeek、Ollama（本地大模型）、智谱 AI、文心一言等。
• 嵌入模型（Embedding）：OpenAI Embedding、BGE、M3E、通义 Embedding 等，用于文本向量化。
• 多模态能力：文生图（DALL・E、Stable Diffusion）、图像理解、音频转录、文本转语音、内容审核。
• 调用方式 ：同步 call()、流式 stream()(返回 Flux，适配 SSE)、异步 asyncCall()，适配 Web、后端、实时场景。

仅仅了解 SpringAI 的内容是不全面的，既然是一款基于 AI 的框架，必然融合了大量 AI 的有关知识，下面补充一些 AI 有关的知识，以便更好地理解 SpringAI。

二、AI 核心知识

（一）RAG（检索增强生成）：让 AI 基于事实回答

1.什么是 RAG

RAG（Retrieval Augmented Generation）是解决大模型幻觉、知识陈旧、无法访问私有数据 的核心技术，核心逻辑：先检索外部知识库，再基于检索结果生成回答，让 AI 从 "凭记忆答题" 变为 "查资料答题"。

解决的主要痛点：

• 大模型知识截止（如 GPT-3.5 知识截止 2021 年），无法获取实时或私有数据。
• 容易产生 "幻觉"（编造不存在的信息）。
• 上下文窗口有限，无法处理超长文本。

**达到的核心目标：**答案准确、可溯源、知识更新无需重新训练模型。

2.RAG 全链路流程（SpringAI 实现）

Spring AI 提供模块化 RAG 架构 ，内置开箱即用的 RetrievalAugmentationAdvisor、QuestionAnswerAdvisor，支持自定义编排 RAG Pipeline：

1）文档加载（Extract） ：读取 PDF、Markdown、Word、网页、数据库、CSV 等非结构化数据，封装为 Document 对象（含内容、元数据、ID）。

2）文本分割（Transform）：将长文档按段落、句子、Token 切分为小片段（Chunk），保持语义连贯性，避免在段落 / 表格中间分割。

3）向量嵌入（Embed） ：调用 EmbeddingClient 将文本片段转为语义向量（高维数值数组），语义相近的文本向量距离更近。

4）向量存储（Load）：将向量 + 原文 + 元数据存入向量库（Vector Store），建立索引，支持快速相似度检索。

5）检索（Retrieve）：用户提问 → 问题向量化 → 向量库检索 Top-K 最相似片段 → 元数据过滤（如按部门、日期）→ 文档后处理（去重、重排序、去噪、压缩）。

6）生成（Generate）：将 "检索结果 + 用户问题" 拼接为提示词 → 传给大模型 → 模型基于上下文生成精准、可溯源的回答。

3.Spring AI RAG 的核心组件

1）DocumentReader：文档读取器，支持多种格式（PDF、Markdown、HTML、FileSystem、UrlResource）。

2）DocumentSplitter：文本分割器（TokenTextSplitter、ParagraphTextSplitter），支持自定义分割规则。

3）EmbeddingClient：嵌入模型客户端，生成文本向量。

4）VectorStore：向量存储接口，统一实现添加、查询、删除、相似度检索。

5）DocumentRetriever ：文档检索器（VectorStoreDocumentRetriever），支持相似度阈值、Top-K、元数据过滤。

6）DocumentPostProcessor：文档后处理器，去重、重排序、压缩，提升生成质量。

7）RetrievalAugmentationAdvisor ：RAG 增强顾问，自动完成 "检索→拼接提示→生成" 全流程，可通过 ChatClient 直接使用。

4. RAG 进阶优化

1）查询重写（Query Transformation）：将用户模糊问题转为精准检索式，提升召回率。

2）混合检索：向量检索 + 关键词检索（BM25），兼顾语义与字面匹配。

3）上下文压缩：将长检索结果压缩为精简上下文，适配模型上下文窗口。

4）多向量库联合检索：同时检索多个向量库，覆盖更多知识源。

（二）Agent（智能体）：自主完成复杂任务

1. 什么是 Agent

Agent 是具备感知、决策、规划、执行能力的 AI 实体 ，核心特征是自主性：无需人工干预，自主理解目标、制定计划、调用工具 / 模型、迭代优化，完成复杂任务（如数据分析、报告生成、代码开发、多步骤问答）。

• 对比普通聊天 AI：
  • 普通 AI：你问我答，被动响应，无自主决策。
  • Agent：你给目标（如 "分析本月销售数据并生成 PPT"），自主拆解任务、调用工具、整合结果，主动完成。

2. Agent 核心架构（Spring AI 实现）

Spring AI 提供模块化 Agent 框架，核心组件：

1）任务规划器（Planner）：解析用户目标，拆解为子任务，制定执行计划（如 "先查数据库→再分析数据→最后生成报告"）。

2）工具调用器（Tool Invoker）：管理注册的工具（Java 方法、外部 API、RAG 检索、代码执行器），根据计划调用工具。

3）记忆模块（Memory）：存储对话历史、任务状态、中间结果，支持短期记忆（对话上下文）、长期记忆（知识库）。

4）执行器（Executor）：执行计划，调用模型 / 工具，处理结果，迭代优化。

5）决策器（Decider）：判断任务是否完成，是否需要继续调用工具 / 模型。

3.Spring AI Agent 核心能力

1）工具集成：无缝对接 Spring AI 函数调用、RAG、外部 API、数据库、代码执行器。

2）多模型协作：根据任务类型选择最优模型（如简单问答用轻量模型，复杂推理用强模型）。

3）状态管理：支持任务暂停、恢复、失败重试，适配长时任务。

4）可观测性：监控任务执行流程、工具调用日志、模型响应，便于调试与优化。

（三）函数调用（Function Calling / 工具调用）

1.什么是函数调用

函数调用是大模型主动调用外部工具 / API 的能力，让 AI 突破自身知识边界，获取实时数据、执行操作（如查天气、查订单、发邮件、计算、调用数据库）。

核心流程：

1. 开发者注册工具（Java 方法 / 外部 API），定义工具名称、描述、输入参数。
2. 将工具列表传给大模型。
3. 模型判断是否需要调用工具，返回工具名称 + 参数。
4. 应用执行工具，返回结果给模型。
5. 模型基于工具结果生成最终回答。

2. Spring AI 函数调用实现

1）@Tool 注解：快速将 Java 方法注册为工具，自动生成工具描述与参数 schema。

2）自动参数解析：模型返回的参数自动映射为 Java 对象，无需手动解析 JSON。

3）多工具支持：一个请求可注册多个工具，模型自主选择调用。

4）工具调用上下文：支持传递对话历史、元数据，提升工具调用准确性。

例如：

// 注册工具
@Tool("获取当前天气")
public String getWeather(@ToolParam("城市") String city) {
    // 调用天气 API
    return "北京今日天气：晴，25℃";
}

// 调用
ChatResponse response = chatClient.prompt()
    .user("北京今天天气怎么样？")
    .functions(getWeather) // 传入工具
    .call();

三、Spring AI 核心 API 详解

1.ChatClient：聊天交互核心入口

1）同步调用 ：chatClient.call(prompt) → 返回字符串结果。

2）流式调用 ：chatClient.stream(prompt) → 返回 Flux<String>，适配 SSE 实时输出。

3）结构化输出 ：chatClient.call(prompt, POJO.class) → 自动将 AI 响应映射为 Java 对象。

4）提示模板 ：PromptTemplate → 支持变量注入、提示工程最佳实践。

5）增强配置 ：通过 Advisor 集成 RAG、记忆、日志、重试等能力。

2.EmbeddingClient：文本向量化

// 生成文本向量
List<Double> vector = embeddingClient.embed("Spring AI 是企业级 AI 开发框架");
// 批量嵌入
List<List<Double>> vectors = embeddingClient.embed(List.of("文本1", "文本2"));

3.VectorStore：向量存储统一接口

// 添加文档
vectorStore.add(List.of(new Document("Spring AI 核心能力", Map.of("author", "Spring"))));
// 相似度检索
List<Document> docs = vectorStore.similaritySearch("Spring AI RAG", 5); // Top 5

4.RAG 快速集成（QuestionAnswerAdvisor）

// 注入 VectorStore
@Autowired
private VectorStore vectorStore;

// 创建 RAG 顾问
QuestionAnswerAdvisor ragAdvisor = new QuestionAnswerAdvisor(vectorStore);

// 调用时启用 RAG
String answer = chatClient.prompt()
    .user("Spring AI 支持哪些向量库？")
    .advisors(ragAdvisor) // 启用 RAG
    .call()
    .getResult()
    .getOutput()
    .getContent();

四、总结

Spring AI 是 Java 开发者进入 AI 领域的最佳入口，它将复杂的 AI 技术（RAG、Agent、函数调用、向量存储）封装为 Spring 风格的简单 API，让你专注业务而非底层对接。无论是快速原型开发还是企业级生产应用，Spring AI 都能提供高效、稳定、可扩展的解决方案，助力企业快速落地 AI 能力。