Spring AI 是 Spring 官方在 2025 年 5 月 20 日发布 1.0.0 GA 的 LLM 接入层。它把 ChatClient、Advisor 链、Tool Calling 这些原本要手写的东西，封装成 Spring 风格的 Bean。它值得用，前提是项目已经跑在 Spring Boot 3.5 + JDK 21 上。如果全站只有两三个调用点，抽象成本会大于收益。真正的坑不在功能表，在版本节奏和抽象泄漏。
现象：Spring Boot 3.5 项目里突然多出的 spring-ai 依赖
这个日期值得记住。
在此之前，Java 侧接一个大模型，路径基本只有三条：自己写 HTTP 客户端解析 SSE、用 LangChain4j、或者在 Python 服务外面套一层 REST。Spring AI 从 2024 年 5 月的 1.0.0-M1 走到 GA，用了一整年、八个里程碑版本。
真正的变化发生在 GA 之后。
2025 年下半年起，Spring Boot 3.5 的项目模板里开始出现 spring-ai-starter-model-* 这类依赖，Spring Initializr 的依赖列表也能搜到 AI 分类。企业侧的动作更直接：一批原本打算"先用 Python 写 PoC"的项目，把 LLM 调用层挪回了 Java 主服务。
原因不复杂。
Python 做 LLM 原型快，但落地时要解决鉴权、限流、审计、灰度、可观测性。这些在 Java 主站里已经有一整套成熟东西。多一个 Python 服务，等于多一套部署、多一套监控、多一次跨网络调用的 P99 抖动。
Spring AI 卖的不是模型能力，是"这套东西能塞进现有 Spring 生命周期"。
话说回来，慢也是真的慢。LangChain4j 在 2024 年就能跑通多模型加 RAG，Spring AI 到 1.0 才把这些能力收敛成稳定 API。对急着上线的项目，这个时间差是实打实的成本。
Spring AI 到底封装了什么，和 LangChain4j 差在哪
先看它实际提供的东西，核心是五块。
- ChatClient：同步和流式的统一入口，链式 API，写法接近 WebClient。
- Advisor 链：在请求前后插入逻辑，官方文档直接类比 Servlet Filter。QuestionAnswerAdvisor 就是用它实现 RAG 的。
- ToolCallback 与 @Tool 注解：把 Java 方法暴露成模型可调用的工具，JSON Schema 由框架反射生成。
- VectorStore：向量库抽象。SimpleVectorStore 是内存实现，生产环境要换 pgvector、Milvus 或 Redis。
- MCP Client 与 Server：通过 Model Context Protocol 把外部工具接进来，这一块在 1.0 才正式成型。
MCP 值得单独说。Anthropic 在 2024 年 11 月把这套协议开源，2025 年被主流模型厂商陆续跟进。Spring AI 1.0 同时提供客户端和服务端 starter，意味着一个 Spring Boot 服务既能消费别人的工具，也能把自己注册成工具提供方。
这是它和 LangChain4j 最不一样的地方。
LangChain4j 的 AiServices 走接口代理路线：定义一个 interface，加注解，框架生成实现。Spring AI 走 Bean 加链式调用路线，更贴合 Spring 的使用习惯，代价是代码更长。
| 维度 | Spring AI 1.0.x | LangChain4j 1.0.x | 裸 HTTP + 厂商 SDK |
|---|---|---|---|
| 起步方式 | spring-ai-starter-model-* | langchain4j-* 依赖 | 手写客户端 |
| 核心抽象 | ChatClient + Advisor 链 | AiServices 接口代理 | 无 |
| 结构化输出 | BeanOutputConverter + 重试 | 注解 + JSON Schema | 手写解析 |
| RAG 组件 | QuestionAnswerAdvisor + VectorStore | EmbeddingStore + ContentRetriever | 全手写 |
| MCP 支持 | 客户端 + 服务端 | 以客户端为主 | 无 |
| 与 Spring 耦合 | 强，自动配置 + 健康检查 | 弱，可脱离 Spring | 无 |
| 版本状态 | 1.0.0 GA 于 2025-05-20 | 1.0.x 系列，2025 年内 GA | 跟随厂商 |
表里的差异集中在两点：耦合度和扩展点数量。
要 Spring 生态一致性，选 Spring AI；要框架中立、项目里有大量非 Spring 模块，LangChain4j 更省事。
我个人认为，决定选型的不是 API 好不好看，是三年后谁维护这层抽象。Spring AI 挂在 spring-projects 组织下，跟着 Spring Boot 的发布节奏走，长期维护的确定性更高。LangChain4j 社区很活跃，但企业采购时对"非官方项目"的心理门槛确实存在。
为什么 Spring AI 的 Advisor 链反而让你多写胶水代码
抽象层的通病是：它替你处理 80% 的常规路径，剩下 20% 要自己绕过去。
具体在哪几个点。
第一，多模型参数不一致。OpenAI 新接口用 max_completion_tokens，Anthropic 用 max_tokens，Gemini 的 temperature 取值范围和别家不同。Spring AI 的 ChatOptions 做了统一建模，但每家实现的默认值不一样。想用一份配置跑三家模型，至少得准备三份 options bean。
第二，结构化输出靠 prompt 约束。BeanOutputConverter 干的事是：根据你的 record 生成 JSON Schema，塞进 prompt 的 format 指令，再把返回文本反序列化。模型如果返回带 markdown 代码块的 JSON，就得自己加重试。框架给了一些容错，重试策略和降级策略还是你的活。
第三，流式的边界条件。拿到 Flux
第四，多模型 fallback 没有内置。想做到"主模型超时切备用"，得自己写 Router 或者包一层 @Primary Bean。
第五，可观测性要自己补。Spring AI 1.0 集成了 Micrometer observation，能看到调用耗时和 token 数。但要把 prompt 版本、检索命中率、工具调用成功率关联起来，得自己加 tag。注意别把 prompt 正文打进 tag，Prometheus 的标签基数会直接炸。
所以才有"胶水代码"这个说法。
不是说 Spring AI 写得差，是这类框架的宿命。模型厂商的 API 每个季度都在变，抽象层永远追不上。
说实话，如果你的场景就是一次问答、一个模型、不打算换，裸 SDK 加两百行代码可能比引一整套 starter 更省心。Spring AI 的价值要在第二个模型、第二套 RAG、第三个接手的人出现时才开始兑现。
1.0 GA 之后，API 还在破坏性变更吗
会，但幅度在收窄。
把时间线摊开：2024 年 5 月 1.0.0-M1，之后 M2 到 M8，2025 年 5 月 20 日 1.0.0 GA。这一年里最疼的一次改动发生在 M6 前后——starter 的 artifact 命名规则统一，从 spring-ai-openai-spring-boot-starter 改成 spring-ai-starter-model-openai，包路径同步清理，ChatClient 和 ChatModel 的职责重新划分。
官方 Release Notes 写得很清楚，但对已经写了一版代码的人，就是编译不过。
GitHub 的 issue 区和 Discussions 里，这类"升级后找不到类"的反馈在每个里程碑版本都会出现一轮。社区常见的吐槽是：版本号只跳了一个字母，改动量却不像补丁版本。
1.0 GA 之后情况好转，但没到"可以随便升"的程度。1.0.x 补丁版本以修 bug 为主，1.1 系列会带新的模型适配和 API 调整。对生产项目，建议锁死小版本，升级前先跑一遍集成测试。
这条建议不是空话。
LLM 应用的集成测试不好写，因为输出不确定。可行的做法是分两层：一层测 prompt 模板渲染、工具 schema 生成、响应解析这些确定性逻辑；另一层用录制回放测端到端。第二层成本高，但升级时能省下大量排查时间。
MCP 与 Tool Calling：Spring AI 帮你省掉的 3 类工作量
Tool Calling 是 2025 年 LLM 应用最实际的能力。模型不再只吐文本，而是能说"我要调 getOrderStatus(orderId=123)"。
Spring AI 在这块的封装是完整的。
省掉的第一类活：JSON Schema 生成。写一个方法加 @Tool 注解，框架反射参数类型，生成符合模型要求的 schema。手写这段，一个五参数的工具就是几十行样板代码。
省掉的第二类活：多轮工具调用循环。模型请求工具、执行、把结果塞回对话、模型再决定要不要继续——这个循环框架内部做了，并且设了最大迭代次数。自己写容易漏掉终止条件，变成无限循环烧 token。
省掉的第三类活：工具结果的序列化与截断。工具返回一个 200KB 的 JSON，直接塞回上下文会撑爆窗口。框架有默认处理，但阈值要你调。
MCP 则把这件事推到进程外。一个 Spring Boot 服务用 spring-ai-starter-mcp-server 把自己注册成 MCP Server，任何支持该协议的客户端都能调用它的工具，不用为每个模型厂商重写一遍 function calling 适配。
不过呢，工具数量一多就难受。公开的经验值是：单次请求暴露超过 20 个工具，schema 描述本身就会吃掉几千 token，模型的选错率明显上升。目前没有框架层面的银弹，主流做法是先做一层工具检索，只把相关的 5 到 8 个塞进上下文。
Spring AI 没有内置工具检索，这块要自己写。
但也要承认，在工具数量多、需要路由分发的复杂 agent 场景里，Spring AI 的工具编排不如 LangChain4j 灵活，后者的可组合扩展点更多一些。
国内落地：通义、DeepSeek 接入 Spring AI 的现实约束
国内项目最先问的是：能接通义千问和 DeepSeek 吗？
能，路径有两条。
第一条是 Spring AI Alibaba。阿里在 2024 年 10 月把这个项目开源出来，提供 DashScope（通义系列）适配，也支持把 Nacos 当工具注册中心。它跟着 Spring AI 的 API 走，版本必须对齐。
第二条是 OpenAI 兼容端点。DeepSeek、智谱、月之暗面都提供 OpenAI 兼容的 /v1/chat/completions，把 spring-ai-starter-model-openai 的 base-url 改掉、api-key 换掉，基础对话就能跑通。
第二条路简单，坑也多。
- Function Calling 的支持程度不一致，有的厂商只认 schema 的部分关键字。
- 流式返回的 SSE 帧格式有细节差异，偶尔解析出空 chunk。
- JSON mode 有的厂商是独立参数，有的靠 prompt 约束。
- 上下文窗口和限流策略各家不同，配置里写死的 maxTokens 要按模型区分。
可观测性这块国内更容易被忽略。Spring AI 1.0 接 Micrometer，能把耗时和 token 消耗打进 Prometheus。常见错误是只监控"调用成功率"，不监控 token 成本。
算笔账。一个企业内部知识库问答，假设每天 5000 次请求，每次输入 3000 token（含检索到的上下文）、输出 500 token。按 OpenAI GPT-4.1 的公开定价，输入 $2/百万 token、输出 $8/百万 token，单次约 $0.01，一天 $50，一个月约 $1500。embedding 还没算进去——text-embedding-3-small 是 $0.02/百万 token，量大的时候这笔钱不可忽略。
换成国产模型，单价能降一个数量级，但长上下文场景下的稳定性要自己压测。
但也要承认，Spring AI 在国产模型适配深度上确实不如 Spring AI Alibaba。后者对 DashScope 的特有参数支持更细，比如联网搜索开关、多模态输入格式；走 OpenAI 兼容路径只能覆盖通用子集。
读者行动清单：7 步走完从选型到上线
按顺序来，别跳步。
- 先定基线。Spring Boot 3.5 + JDK 21，别拿 2.7 去接。Spring AI 1.0 的官方文档写明基线是 Spring Boot 3.4.x，2.x 没有支持路径。
- 只引 starter，不引底层实现包。用 spring-ai-starter-model-openai 这类，自动配置和版本对齐交给 BOM。
- 把 ChatClient 包在自己的接口后面。定义 LlmService，内部持有 ChatClient，外部只依赖你的接口。换模型、加降级、改 prompt 都不影响业务代码。
- 参数进配置文件。temperature、maxTokens、超时、重试次数，按模型分 profile，不要写死在 Java 里。
- RAG 先用 SimpleVectorStore 验证链路，再换生产向量库。它是内存实现，重启即失效，只适合开发和单测。换 pgvector 时注意 HNSW 索引最多支持 2000 维，超过要降维或换 IVF。
- 开 Micrometer observation，但过滤掉 prompt 正文。只保留模型名、token 数、耗时、是否命中工具这些低基数标签。
- 上线前压测三件事：流式连接在弱网下的表现、工具调用超时的降级路径、单日 token 成本上浮 3 倍时的告警阈值。
第 3 步最容易被跳过，也最值钱。
不少项目一开始就把 ChatClient 直接注入到 Service 里用，等要换模型或者加缓存的时候，发现改动点散在十几个类里。
常见问题
Spring AI 和 LangChain4j 哪个更适合 Java 后端项目？
结论是：已跑在 Spring Boot 3.x 上的业务系统优先选 Spring AI，独立工具或非 Spring 栈选 LangChain4j。Spring AI 1.0 GA 之后 API 稳定度提升，自动配置、健康检查、Micrometer 集成开箱可用；LangChain4j 的 AiServices 接口代理写法更简洁、耦合更低，适合不想被 Spring 生命周期绑住的场景。
Spring AI 支持通义千问和 DeepSeek 吗？
支持，走的是两条不同路径。通义千问优先用 Spring AI Alibaba 的 DashScope 适配，特有参数支持更完整；DeepSeek、智谱等提供 OpenAI 兼容端点的厂商，改 spring-ai-starter-model-openai 的 base-url 即可，代价是 function calling、JSON mode 只能用到通用子集。
Spring AI 1.0 能用在生产环境吗？
能，前提是锁版本、有集成测试、并且接受抽象层会滞后于模型厂商的 API。1.0.0 GA 于 2025 年 5 月 20 日发布，之后进入常规维护节奏；但模型适配的更新频率高于框架发布频率，新模型能力上线时往往要等适配或自己写扩展。
下一个问题是：当模型厂商每季度改一次 API，这层抽象到底该由框架来追，还是该由你的业务代码来兜？