Spring AI实战：ChatModel到RAG应用开发完整指南

引言：Spring AI 为 Java 开发者带来的机遇

在大模型应用开发领域，Python 长期占据主导地位。但对于庞大的 Java 企业级开发生态而言，如何优雅地接入 DeepSeek、ChatGPT、Claude 等大语言模型，一直是个痛点。Spring AI 的出现填补了这一空白——它以 Spring 生态一贯的抽象设计理念，将各类大模型的调用统一封装成一致的 API，让 Java 开发者能够用熟悉的方式构建 AI 应用。

Spring AI 的统一抽象设计源自 Spring 框架一贯的"面向接口编程"哲学。与 Spring Data 通过统一接口屏蔽不同数据库差异、Spring Security 统一认证授权机制类似，Spring AI 定义了一套与厂商无关的核心接口层（如 ChatModel、EmbeddingModel），各厂商的具体实现作为独立的 Starter 模块接入。这种设计模式在软件工程中称为"适配器模式"（Adapter Pattern），它将变化点（各家模型 API 的差异）隔离在实现层，对上层应用暴露稳定的抽象接口。因此无论你使用 ChatGPT、Claude 还是 DeepSeek，切换模型时往往只需调整少量配置参数。

值得注意的是，这种架构设计在工程实践中还带来了另一个隐性收益：可测试性的大幅提升。由于所有模型调用都面向接口编程，开发者可以在单元测试中轻松注入 Mock 实现，无需真实调用付费的云端 API 即可完成业务逻辑验证。这与 Spring 生态中依赖注入（Dependency Injection）和控制反转（IoC）的核心设计理念一脉相承——在 Spring AI 中，ChatModel 和 EmbeddingModel 的具体实现 Bean 由 Spring 容器统一管理，开发者只需通过 @Autowired 或构造器注入获取接口引用，运行时自动绑定到对应厂商的实现类。这种松耦合的架构也使得同一套代码在开发环境使用本地 Ollama 模型、在生产环境切换至云端 API 成为可能，极大降低了开发和运营成本。

本文基于马士兵教育的 Spring AI 实战教程内容，系统梳理这门框架的核心模块与应用场景，帮助读者建立完整的知识地图。整个课程围绕 ChatModel、Embedding、RAG 等核心能力展开，覆盖了从入门到工程化落地的完整链路。

Spring AI 的核心定位与快速上手

Spring AI 的设计目标非常明确：为 Spring 应用提供大模型能力的统一抽象。它并不局限于某一家厂商的模型，而是通过统一的接口屏蔽了底层差异。这意味着无论你使用 ChatGPT、Claude 还是 DeepSeek，切换模型时往往只需要调整少量配置参数即可。

在快速上手环节，首先需要关注的是环境要求——Spring AI 对 JDK 版本和 Spring Boot 版本有明确的依赖限制，只有满足这些前提才能正常运行。Spring AI 目前要求 JDK 17 及以上版本，并与 Spring Boot 3.x 深度绑定。这一版本要求背后有其技术合理性：JDK 17 带来的 Records、Sealed Classes 等语言特性使得 Spring AI 内部的数据模型（如 ChatResponse、Generation 等不可变值对象）可以用更简洁、安全的方式表达；而 Spring Boot 3.x 基于 Jakarta EE 9+（包名从 javax.* 迁移至 jakarta.*），与 Spring AI 依赖的 Spring WebFlux 响应式模块深度集成，为流式输出、异步处理等 AI 特有场景提供了更完善的底层支撑。教程以 DeepSeek 为例演示了最基础的对话案例，这也是入门的最佳起点。

值得强调的是一个核心学习方法：举一反三。由于 Spring AI 对不同模型的 API 高度统一，掌握一种模型的用法后，其他模型的调用方式几乎完全一致，仅存在配置参数上的差异。这种设计极大降低了学习和迁移成本。

四大 Model 类型：Spring AI 的能力基石

Spring AI 官方支持的模型类型非常丰富，主要可归为四类：

ChatModel：聊天对话的核心

ChatModel 是最常用的模块，负责与大模型进行文本对话。它支持普通聊天、流式聊天（stream）以及各类参数设置（如温度、最大 token 数等）。流式聊天对于提升用户体验尤为重要——它能让回复逐字呈现，而不是等待完整结果一次性返回。

流式聊天基于 HTTP 的 Server-Sent Events（SSE）或 WebSocket 技术实现。大模型生成文本是一个自回归过程——每次只预测下一个 token（词元），完整回复可能需要数秒甚至数十秒。流式传输使服务端能够在生成每个 token 后立即推送给客户端，实现"打字机效果"，显著改善用户的等待体验。在 Spring AI 中，流式响应通过 Project Reactor 的 Flux<ChatResponse> 类型返回，与 Spring WebFlux 的响应式编程模型天然契合，也可通过 Spring MVC 的 SseEmitter 在传统 Servlet 架构中使用。

理解 ChatModel 中的参数设置对于工程化落地同样重要。温度（Temperature） 是控制模型输出随机性的关键参数，取值通常在 0 到 2 之间：接近 0 时模型倾向于选择概率最高的词，输出更确定、更保守，适合代码生成、数据提取等需要准确性的场景；接近 2 时随机性增大，输出更富创意和多样性，适合文案创作、头脑风暴等场景。最大 Token 数（Max Tokens） 则直接影响响应长度和 API 调用成本——每个大模型 API 都按照消耗的 token 数量计费，合理设置上限可有效控制开支。此外，Top-P（核采样）和 Frequency Penalty（频率惩罚）等参数也是生产环境中常用的调优手段，Spring AI 的 ChatOptions 接口对这些参数提供了统一的设置入口。

EmbeddingModel：向量化的关键

EmbeddingModel（嵌入模型）是整个 RAG 应用的基础。所谓 Embedding，就是将一段文字转化为向量的过程。教程中以智谱 AI 为例进行演示。

Embedding 是自然语言处理领域的基础技术，其核心思想是将离散的文本符号映射到连续的高维向量空间中，使得语义相近的词语或句子在向量空间中距离更近。现代大模型使用的 Embedding 通常是数百到数千维的浮点数向量。例如，"苹果"和"水果"的向量距离会远小于"苹果"和"汽车"。向量相似度通常使用余弦相似度（Cosine Similarity）或点积（Dot Product）来衡量，这也是 RAG 检索的数学基础。

从技术演进的视角看，Embedding 技术经历了从 Word2Vec（2013 年，Google）到 GloVe、FastText，再到 BERT（2018 年，Google）的重要发展历程。早期的 Word2Vec 为每个词分配一个固定向量，无法处理"苹果手机"和"苹果水果"中同一词的不同语义；而 BERT 及其后续模型产生的是上下文感知的动态向量——同一个词在不同句子中会得到不同的向量表示，从而更准确地捕捉语义。当前主流的 Embedding 模型（如 OpenAI 的 text-embedding-3-large、智谱 AI 的 embedding-3）输出维度通常在 768 到 3072 维之间，维度越高通常语义表达能力越强，但存储和计算成本也相应增加。在选择 Embedding 模型时，还需注意模型的最大输入 token 限制——超过限制的长文档需要先进行分块（Chunking）处理，这也是 RAG 工程实践中的重要环节。

Embedding 的价值不仅在于向量化本身，更在于它在 RAG（检索增强生成）场景中的核心作用。教程围绕 EmbeddingModel 设计了三个递进式案例：

1. 查找相似文本——最基础的向量相似度计算
2. 手动实现 RAG——不依赖封装 API，纯手工搭建检索增强流程
3. RAG 优化升级——针对手动实现中的弊端进行改进

这种"先手动、后封装"的教学思路很有价值，能让开发者真正理解 RAG 背后的原理，而不是只会调用现成 API。

ImageModel 与 AudioModel

除了文本能力，Spring AI 还支持图片生成（ImageModel）和语音文本互转（AudioModel）。在实际项目中，ChatModel 和 EmbeddingModel 的应用频率远高于这两者，后者更多作为拓展能力了解即可。

ImageModel 对接的是 DALL·E、Stable Diffusion API 等图像生成服务，通过文本描述（Prompt）生成图片，在内容创作、产品设计原型等场景有实际应用价值。AudioModel 则覆盖了语音转文字（STT，Speech-to-Text）和文字转语音（TTS，Text-to-Speech）两个方向，对接的是 OpenAI Whisper、TTS 等服务。值得关注的是，随着多模态大模型（如 GPT-4o、Gemini 1.5）的快速发展，图像和音频能力正在与文本对话能力深度融合——未来 Spring AI 的 ChatModel 接口很可能直接支持多模态输入，ImageModel 和 AudioModel 作为独立模块的重要性或将进一步演变。

Ollama 集成：本地大模型私有化部署

对于数据隐私要求高、或不希望依赖云端 API 的场景，本地模型部署是刚需。Ollama 作为流行的本地模型管理工具，与 Spring AI 的集成非常顺畅。

Ollama 诞生于 2023 年下半年，其核心价值在于极大降低了本地大模型的运行门槛——开发者只需一条命令（如 ollama run llama3）即可在本地拉取并运行开源大模型，无需手动处理模型权重下载、量化格式转换、GPU 内存管理等复杂配置。Ollama 底层基于 llama.cpp 构建，支持 CPU 推理（速度较慢但无需 GPU）和 GPU 加速（NVIDIA CUDA、Apple Metal），并提供了兼容 OpenAI API 格式的本地 HTTP 接口。正是这个 OpenAI 兼容接口使得 Spring AI 与 Ollama 的集成极为简洁——Spring AI 的 Ollama Starter 只需将 API 地址指向本地 http://localhost:11434 即可工作。对于企业级私有化部署场景，Ollama 支持的模型涵盖 Llama 3、Mistral、Qwen（通义千问）、DeepSeek 等主流开源模型，可根据硬件条件和业务需求灵活选型。

通过 Spring AI 结合 Ollama，开发者可以直接调用本地部署的模型完成聊天、嵌入等任务。由于 API 高度统一，无论是 ChatModel 还是 EmbeddingModel，其使用方式与云端模型几乎没有区别。这为企业级私有化部署提供了便捷路径。

ChatClient 与 ChatMemory：更优雅的对话封装

ChatClient：更易用的客户端封装

如果说 ChatModel 是底层接口，那么 ChatClient 则是 Spring AI 提供的更高层、更易用的封装。它以流式 API 的方式简化了对话构建流程，是实际开发中更推荐的选择。

ChatClient 的设计借鉴了 Builder 模式和方法链（Method Chaining）风格，允许开发者以声明式的方式构建复杂的对话请求。例如，可以在 ChatClient 层面统一设置系统提示词（System Prompt）、绑定 ChatMemory、挂载 Tool 列表，而无需在每次调用 ChatModel 时手动组装 Prompt 对象。更重要的是，Spring AI 支持通过 @Bean 注解将预配置的 ChatClient 注入 Spring 容器，实现跨组件复用。ChatClient 还内置了对结构化输出（Structured Output）的支持——通过指定目标 Java 类型，Spring AI 会自动将模型的文本输出解析为对应的 POJO 对象，大幅简化了从 AI 响应中提取结构化数据的工程工作量。

ChatMemory：让大模型具备上下文记忆

大模型默认是无状态的——每次对话都是独立的一问一答，无法记住之前的上下文。ChatMemory 解决的正是这个问题。教程详细讲解了两种存储方式：

• 基于内存存储：适合临时会话，简单高效
• 基于数据库存储：适合需要持久化的生产场景

理解 ChatMemory 的实现原理有助于更好地使用这一特性。大模型本身并没有"记忆"能力，所谓"上下文记忆"的实现方式是：将历史对话记录（包括用户消息和模型回复）拼接到每次新请求的 Prompt 中一并发送给模型，模型据此理解对话上下文。这种方式的本质是利用模型的上下文窗口（Context Window）来模拟记忆。这也带来了一个工程挑战：随着对话轮次增加，历史消息越来越长，最终会超过模型的最大上下文长度（Context Length Limit）并产生高额 API 费用。因此生产级 ChatMemory 实现通常需要配套消息窗口管理策略，常见方案包括：保留最近 N 轮对话（滑动窗口）、基于摘要压缩历史对话、或根据语义相关性动态检索历史消息。Spring AI 的 ChatMemory 接口为这些策略提供了扩展点。

值得关注的是，官方文档往往只提供 ChatMemory 的 API 说明，缺乏与 Spring Boot 结合的完整工程实践。如何在 Controller 和 Service 层进行合理配置和开发，正是实战教程的核心价值所在。

Tool Calling 与 MCP：从工具调用到统一协议

Tool Calling：赋予模型执行行动的能力

工具调用（Tool Calling）让大模型能够调用外部函数、查询数据库或访问第三方 API，从而突破纯文本生成的局限。Tool Calling 也称 Function Calling，最早由 OpenAI 在 2023 年 6 月引入 GPT 模型中。其工作原理是：开发者预先向模型声明一组可用函数的名称、描述和参数 Schema，当用户提问涉及这些功能时，模型不直接生成答案，而是返回一个结构化的函数调用请求（包含函数名和参数），由应用层执行实际调用后再将结果返回给模型进行最终作答。这种机制使大模型从"只会说话"升级为"能够行动"，是 AI Agent（智能体）架构的核心基础能力。目前主流大语言模型基本都支持这一能力，只是各家的 API 实现方式存在差异。

在 Spring AI 中，Tool Calling 的实现方式非常符合 Spring 开发者的直觉：只需在普通的 Java 方法上添加 @Tool 注解，并在 ChatClient 调用时通过 .tools() 方法注册，Spring AI 会自动完成函数签名到 JSON Schema 的转换、工具调用的拦截执行、以及结果回传给模型的完整生命周期管理。这种声明式的工具注册方式，与 Spring MVC 中通过 @RequestMapping 声明 HTTP 端点的设计理念高度一致，极大降低了 Java 开发者的学习门槛。需要注意的是，Tool Calling 涉及多轮模型交互（用户提问 → 模型返回工具调用请求 → 执行工具 → 将结果返回模型 → 模型生成最终回复），在高并发场景下需要关注延迟和成本控制。

MCP：统一工具调用的模型上下文协议

正是由于不同模型工具调用 API 的不一致性，才催生了 MCP（Model Context Protocol，模型上下文协议）。需要澄清的是，MCP 并非 Spring AI 提出的标准，而是由 Anthropic（Claude 的母公司）推出，Spring AI 负责实现了这一协议。

MCP 于 2024 年 11 月由 Anthropic 发布并开源，设计初衷是解决 AI 应用生态中的"集成碎片化"问题——此前每个 AI 应用都需要为每个工具单独编写适配代码，形成 M×N 的集成复杂度。MCP 借鉴了 LSP（Language Server Protocol，语言服务器协议）的设计思路，定义了一套标准化的客户端-服务器通信协议，使任意 MCP 兼容的 AI 应用都能直接使用任意 MCP 服务器提供的工具，将复杂度降低为 M+N。协议支持 stdio（标准输入输出）和 SSE（Server-Sent Events）两种传输方式，分别适用于本地进程通信和远程网络调用场景。

MCP 发布后获得了业界的广泛响应，OpenAI、Google DeepMind、微软等主要 AI 厂商相继宣布支持，众多 AI 编程工具（如 Cursor、Claude Desktop、VS Code Copilot）也迅速接入。这使得 MCP 有望成为 AI 工具生态的事实标准协议，类比于 HTTP 之于 Web、LSP 之于 IDE 插件生态的地位。从 Java 开发者的视角来看，掌握 MCP Server 的开发能力意味着可以将现有的 Spring Boot 服务直接包装为 MCP 工具服务，供各类 AI 应用调用，这也是当前企业 AI 化改造中极具价值的技术方向。Spring AI 对 MCP 的支持包括 MCP Client（让 Spring AI 应用调用 MCP 服务器提供的工具）和 MCP Server（将 Spring 服务暴露为 MCP 工具）两个方向，为 Java 开发者参与 MCP 生态提供了完整的工程支撑。

MCP 的核心价值在于统一了各模型在工具调用时的 API 规范。教程从 MCP 的概念切入，讲解了它在 Java/Spring AI 中的整体架构、涉及的角色划分，以及客户端（Client）和服务端（Server）的具体开发方式，并覆盖了不同通信协议的案例实践。

RAG 深度实战：向量数据库与综合案例

课程的压轴内容是 RAG（检索增强生成）的深度实战。RAG 由 Meta AI 研究团队于 2020 年在论文《Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks》中正式提出，旨在解决大语言模型的两个核心痛点：知识截止日期（模型训练后无法获取新知识）和幻觉问题（模型倾向于生成听起来合理但实际错误的内容）。RAG 通过在生成阶段引入外部知识检索，让模型的回答有据可查，同时也使私有知识库的接入成为可能，这正是企业级 AI 应用中最常见的落地场景。

从架构演进的视角来看，RAG 目前已经发展出多个技术代际。Naive RAG（基础 RAG）即简单的"检索+生成"流程，存在检索精度不足、上下文利用率低等问题。Advanced RAG（高级 RAG）引入了查询改写（Query Rewriting）、混合检索（Hybrid Search，结合向量检索与关键词检索）、重排序（Re-ranking）等优化手段，显著提升了检索质量。Modular RAG（模块化 RAG）则进一步将 RAG 拆解为可灵活组合的功能模块，支持根据不同场景动态编排检索策略。Spring AI 的 QuestionAnswerAdvisor 和 VectorStore 抽象层为实现这些 RAG 变体提供了良好的扩展基础。理解这一技术演进路径，有助于开发者在面对具体业务需求时做出合适的 RAG 架构选型。

这里的 RAG 与前面 EmbeddingModel 章节的手动实现有所不同——它引入了专业的向量数据库和 Spring AI 封装的完整工具链。

Milvus 向量数据库：企业级 RAG 的存储底座

在企业级 RAG 应用中，当本地文档规模庞大时，必须借助专业的向量数据库进行存储和检索。教程选用了业界广泛使用的 Milvus，系统讲解了其搭建方式、核心概念、常用命令以及 API 调用方法。

Milvus 是由 Zilliz 公司主导开发的开源向量数据库，于 2019 年发布，2021 年进入 CNCF（云原生计算基金会）沙箱项目。它专为大规模向量相似度检索设计，支持十亿级向量的毫秒级检索，底层集成了 FAISS、HNSW、IVF 等多种业界主流的近似最近邻（ANN）索引算法。向量数据库相比传统数据库的核心优势在于：能够高效执行基于语义相似度的检索，而非简单的关键词匹配，从而实现真正意义上的"语义搜索"。除 Milvus 外，业界常用的向量数据库还有 Pinecone、Weaviate、Qdrant 和 pgvector（PostgreSQL 插件）等。

在实际工程选型中，这几类向量数据库各有侧重：Milvus 适合超大规模（十亿级）向量存储和高并发检索场景，支持云原生部署，但运维复杂度较高；Qdrant 以 Rust 语言实现，在性能和资源占用上表现突出，且提供了友好的 REST API；pgvector 作为 PostgreSQL 扩展，允许在现有关系型数据库中直接存储向量，对于已有 PostgreSQL 基础设施的团队来说迁移成本最低；Pinecone 是全托管的向量数据库云服务，无需自行运维但存在数据出境合规风险。Spring AI 的 VectorStore 接口对上述所有方案都提供了统一的抽象，切换存储后端同样只需修改配置。

完整的 RAG 工作流

一个完整的 RAG 流程可概括为以下四个步骤：

1. 文档向量化存储：本地文档通过 EmbeddingModel 转化为向量，存入 Milvus
2. 用户提问向量化：用户的问题同样通过 EmbeddingModel 进行向量化处理
3. 相似度检索：在向量数据库中检索与提问语义相近的文档片段
4. 大模型生成回复：将检索到的相关片段交由 LLM 生成最终答案

在工程实践中，步骤 1 中的文档分块策略（Chunking Strategy）对 RAG 效果有决定性影响，往往是被初学者忽视的关键环节。常见的分块策略包括：按固定字符数切分（简单但可能破坏语义完整性）、按段落/句子切分（保留语义边界但块大小不均匀）、递归字符分割（按层次结构优先切分，兼顾效果与灵活性）。此外，块重叠（Chunk Overlap）技术通过让相邻块共享一定数量的字符，避免检索时遗漏跨块的关键信息。Spring AI 提供了 TokenTextSplitter 等文档分割工具，并支持在 Document 对象中附加元数据（如文件名、页码、创建时间），这些元数据可在检索后用于过滤和来源溯源，对于企业级知识库应用的可信度建设尤为重要。

课程最后以"导游考试"综合案例收尾，将 Embedding、RAG、向量数据库检索融为一体，完整演示了从文档入库到智能问答的全流程。这类综合案例最能体现 Spring AI 在实际项目中的工程落地价值。

总结

Spring AI 为 Java 开发者打开了大模型应用开发的大门。从 ChatModel 的基础对话，到 EmbeddingModel 的向量化能力，再到 Tool Calling、MCP 协议和 RAG 检索增强，它构建了一套完整、统一的 AI 开发范式。对于深耕 Spring 生态的开发者而言，掌握这套框架意味着能够以最低的迁移成本，快速将 AI 能力融入现有的企业级应用。

学习过程中最关键的方法论是举一反三——理解一种模型的用法即可触类旁通，因为 Spring AI 的核心价值正是其统一的接口抽象设计。

从更宏观的技术趋势来看，Spring AI 目前仍处于快速迭代阶段（版本号尚未到达 1.0 正式版），API 存在一定的变动风险，建议在生产环境中锁定依赖版本并密切关注官方 Release Notes。与此同时，随着 AI 应用从"概念验证"走向"规模化生产"，性能调优（如 Embedding 批处理、连接池管理）、成本控制（如缓存语义相似的查询结果）、可观测性（如集成 Spring Boot Actuator 监控 AI 调用指标）等工程化能力将逐渐成为 Spring AI 开发者的核心竞争力。这也预示着 Spring AI 生态将在框架成熟后迎来更丰富的工程化最佳实践积累。

核心要点

核心要点