第一章：先唠明白，Spring AI 到底是个啥？

---

1.1 不是"又一个 AI 框架"，是 Spring 生态的 AI 接入层

很多同学第一次听到"Spring AI"这个名字，脑子里冒出来的第一个念头是：又来一个要学的东西？是不是跟 LangChain 差不多？

我带你一句话搞清楚它的定位——

Spring AI 不是要你放弃 LangChain 或者重新学一套 AI 理念，它是把"调用大模型"这件事，用 Spring 生态里你熟悉的方式封装了一层。

说白了，你写 Spring Boot 项目，想接大模型（ChatGPT、通义千问、DeepSeek……），以前你怎么办？自己写 HTTP 请求，拼 JSON，处理流式响应，适配各家不同的 API 格式，写一堆工具类。

Spring AI 就是帮你把这一坨脏活干了：你只管写业务逻辑，跟 AI 交互的部分，跟调 Spring 的 JdbcTemplate 一样自然。

它的核心思路是"大一统接口"：

// 不管底层是 OpenAI 还是千问还是 DeepSeek，
// 你写的代码是这样的，换模型只改配置不动代码
ChatClient client = chatClientBuilder.build();
String answer = client.prompt()
    .user("帮我写一段冒泡排序的代码")
    .call()
    .content();

如果明天你觉得 OpenAI 太贵要切到 DeepSeek，改一行配置完事，业务代码零改动——这就是 Spring AI 最大价值。

---

1.2 和 LangChain4j、LangChain(Python) 掰扯清楚

这是被问最多的问题，我用一张表把关键差异列清楚：

维度	Spring AI	LangChain4j	LangChain（Python）
母体生态	Spring Boot / Spring Cloud	Java 生态（非 Spring 专属）	Python 生态
上手门槛	会 Spring Boot 就能用，零额外学习成本	需要学 LangChain 那一套抽象概念	需要学 LangChain 概念 + Python
AI 能力完备度	Chat、Embedding、RAG、Function Calling、多模态	Chat、Embedding、RAG、Agent、Tools	最全，社区最活跃
生产环境适配	天然集成 Spring 全家桶（AOP、事务、监控、配置中心）	需要自己集成 Spring 组件	非 Java 生态
文档与社区	官方文档稳定但案例偏少，社区增长中	文档一般，Java 大模型场景资料少	资料最多，但都是 Python
适合谁	Spring 技术栈团队，不想折腾框架	Java 团队，非 Spring 项目（如 Quarkus）	Python 团队、算法团队

怎么选？只给你一个决策标准：

你团队的主力后端是 Java/Spring 技术栈 → 无脑 Spring AI。 别去看 LangChain4j 了，Spring AI 在 Spring 生态里的集成体验是降维打击级别的——事务管理、配置中心、AOP 切片这些你不需要额外适配。

你是 Python 技术栈 → 用 LangChain。 这没什么好纠结的。

你是 Java 但不是 Spring（比如 Quarkus、纯 Java）→ 看 LangChain4j。 不过说实话，Java 后端有多少不用 Spring 的？所以这个选项其实很少人走。

一个真实的选择经历

我们团队之前做一个知识库问答项目，一开始有人提议用 Python + LangChain，理由是"LangChain 资料多"。我否决了，原因很简单：

1. 团队全员 Java，引入 Python 服务意味着要多维护一个技术栈
2. 知识库数据在现有的 Spring 服务里，跨语言调用增加网络开销和维护成本
3. Spring AI 虽然是新项目，但它做的事情本质上是 HTTP 调用 + 向量检索，不复杂，没必要引入新语言

最后全链路用 Spring AI 做的，研发效率远高于预期。当然，Spring AI 当时有些功能不成熟（比如 Agent 编排），我们这部分自己写了一点胶水代码。这是后话，后面章节会细说。

---

1.3 一张图看懂 Spring AI 全家桶

Spring AI 不是一个大而全的"平台"，它是一个模块化的工具箱。你跟 AI 交互会遇到的所有环节，它都提供对应的模块。用大白话翻译一下每个模块是干嘛的：

┌───────────────────────────────────────────────────────────────────────┐
│                        你的 Spring Boot 业务代码                        │
└───────────────────────────────────────────────────────────────────────┘
                                    │
          ┌─────────────────────────┼─────────────────────────┐
          │                         │                         │
          ▼                         ▼                         ▼
    ┌──────────┐           ┌──────────────┐          ┌──────────────┐
    │  Chat    │           │  Embedding   │          │  多模态       │
    │  聊天    │           │  文本→向量    │          │  图片/语音    │
    └──────────┘           └──────────────┘          └──────────────┘
                                    │
                                    ▼
    ┌──────────────────────────────────────────────────────────────────┐
    │                        Vector Store（向量数据库）                  │
    │   PgVector  │  Milvus  │  Redis  │  Elasticsearch  │  Chroma     │
    └──────────────────────────────────────────────────────────────────┘
                                    │
          ┌─────────────────────────┼─────────────────────────┐
          │                         │                         │
          ▼                         ▼                         ▼
    ┌──────────┐           ┌──────────────┐          ┌──────────────┐
    │   RAG    │           │   Agent      │          │  Memory      │
    │  检索增强 │           │   智能体      │          │  对话记忆     │
    └──────────┘           └──────────────┘          └──────────────┘

逐一说一下这些模块是干啥的，用最土的话：

模块	大白话解释	你什么时候用到它
Chat	跟大模型对话，问问题它回答	天天用，最基础的能力
Embedding	把一段文字变成一串数字（向量），用于"找相似内容"	做知识库、做搜索、做推荐时
Vector Store	存这些向量数字的地方，能快速找出"最相似的几条"	做 RAG 必须用
RAG	先从你的知识库里搜相关内容，塞给 AI，让它基于你的资料回答	内部文档问答、客服机器人
Function Calling	让 AI 能"指挥"你的系统做事（查数据库、调接口、发邮件）	你想让 AI 不只是聊天，还能办事
Agent	Function Calling 的升级版，AI 自行决定"先做什么、后做什么"	复杂任务自动编排
多模态	除了文字，还能看图、听语音	发票识别、图片描述
Memory	让 AI 记住你们刚才聊过什么	多轮对话

重要提示：这些模块不是都要学。你 80% 的场景只需要 Chat + RAG + Function Calling 三个模块。别被全家桶唬住。

---

1.4 版本现状：能不能上生产？

这是每个想引入 Spring AI 的人最关心的问题。我直接说现状（截至 2026 年 8 月）：

版本号

Spring AI 已经发布 1.0 正式版。这意味着核心 API 已经稳定，不会再有破坏性变更了。之前那些年追 SNAPSHOT 版的痛苦终于结束了。

各模块成熟度

模块	成熟度	说明
Chat / Streaming	✅ 生产可用	核心功能，最稳
Embedding	✅ 生产可用	没什么幺蛾子
PgVector 集成	✅ 生产可用	Spring 官方主推，维护积极
Milvus 集成	✅ 生产可用	社区维护，稳定
Function Calling	✅ 生产可用	经历了多轮迭代，API 已收敛
RAG（ETL Pipeline）	✅ 生产可用	文档处理链路稳定
Agent 编排	⚠️ 谨慎	目前功能相对基础，复杂编排建议自己控制
多模态	✅ 生产可用	接口稳定，注意各模型支持差异
对话记忆	✅ 生产可用	简单的上下文窗口没问题

我的建议

• 如果你的需求是 Chat + RAG + Function Calling：完全可以上生产，我们已经跑了几个月了，没啥坑。
• 如果你要复杂的 Agent 多步推理、自动规划：Agent 模块能用但不够灵活，建议主要逻辑自己写状态机控制，用 Spring AI 做模型调用那层。

---

第一章小结

三句话总结：

1. Spring AI 是 Spring 生态的 AI 接入层，把你本来就要写的 HTTP 请求封装成了 Spring 风格接口，切换模型只改配置。
2. Java / Spring 团队直接上 Spring AI，别犹豫，别去折腾 LangChain4j。
3. Chat + RAG + Function Calling 三大核心模块生产可用，日常场景全覆盖。

---

下一章，我们一起 5 分钟把 Hello World 跑起来，顺便讲讲 ChatClient 的两种用法，以及为什么要用流式，什么场景用同步就够了。