在实际 Java 项目中接入大模型,2026 年已经不是一个实验性需求,而是很多业务系统里真实存在的功能模块。Spring AI 2.0 是 Spring 官方统一 Java 侧 LLM 集成方式的框架,DeepSeek 是目前 Java 开发者接入成本最低的国产对话模型之一,Langchain4j 则提供了另一套偏轻量、偏链路的 Java AI 框架思路。与此同时,Spring AI Alibaba 在国内环境下提供了一系列更贴近云上实践的组件。只要同时关注这几条技术路线,就能在项目选型时把“用哪个框架”和“接哪个模型”拆开考虑。
这篇教程不打算做成纯概念罗列,而是按一条完整的落地链路来走:先理解 Spring AI 2.0 是什么,再准备好 JDK、Maven、API Key,接着用 DeepSeek 跑通最小对话,然后做结构化输出,再进入向量检索场景,最后对比 Langchain4j 和 Spring AI Alibaba,并梳理生产环境常见问题。读完以后,你应该能独立完成一个“DeepSeek + Spring AI”的最小可运行项目,也知道后续该往哪个方向扩展。
1. Spring AI 2.0 到底改了哪些东西,Java 接入大模型为什么值得关注
1.1 从 Spring AI 1.x 到 2.0 的定位变化
Spring AI 在 1.x 时代解决的核心问题是“让 Java 开发者能用类似 Spring 的风格调用大模型”。到了 2.0,它不再只是把 OpenAI 客户端包装成一个 Bean,而是把模型调用、提示词管理、结构化输出、向量检索、Agent 编排等能力做成了统一的抽象层。
对业务开发者来说,最直观的变化有三个:
- ChatClient 成为和 RestTemplate、JdbcTemplate 一样的基础组件,写模型调用越来越像写普通数据访问代码。
- 模型接入通过 spring-ai-starter-model-* 这样的模块隔离,切换模型供应商时,业务代码可以保持稳定。
- AI 相关的自动配置被大幅精简,application.yml 里配好 Key 和模型名,就能直接注入 ChatClient。
但要注意,Spring AI 2.0 的 API 仍然在迭代,不同小版本之间可能存在方法签名调整。实际项目落地时,建议先锁定一个具体版本,再查看该版本的官方参考文档,不要直接照抄最新博客里的代码。
1.2 三条技术路线的定位差异
在搜资料时会发现,同一个 DeepSeek 接入需求,至少有三套写法:
- Spring AI:Spring 官方方案,适合已经使用 Spring Boot 的项目,能和 Spring 的配置、监控、测试体系天然整合。
- Langchain4j:更偏 LLM 应用的通用 Java 库,不强制依赖 Spring,适合想自己控制链路、或者非 Spring 技术栈的项目。
- Spring AI Alibaba:面向国内云环境和阿里系中间件的派生方向,提供了一些本地化组件和更细的 AI 应用编排能力。
这三者不是互斥关系。最简单的项目可以只依赖 Spring AI;如果业务里需要高度自定义 Prompt 链,Langchain4j 的 AiServices 模型会更顺手;如果整套基础设施都在阿里云上,Spring AI Alibaba 可能更合适。
1.3 本文的最小目标与学习路径
这篇教程的最小目标是:在一个 Spring Boot 工程里,通过 Spring AI 调用 DeepSeek,完成对话、结构化输出、向量检索三个场景。再往后,文章会给出 Langchain4j 和 Spring AI Alibaba 的选型参考,方便你决定下一步用哪套体系。
学习路径可以这样安排:
- 先跑通最小对话,理解 ChatClient 和模型配置。
- 再做结构化输出,理解模型返回如何映射成 Java 对象。
- 然后加入向量库,理解检索增强生成的基本链路。
- 最后再看框架选型,避免一开始就陷入多框架比较。
2. 开发环境准备:JDK、Maven、模型 API Key 三者缺一不可
2.1 环境清单与版本确认
在写代码之前,先把环境检查一遍。Spring AI 2.0 整体对 Spring Boot 3.x / 4.x 的兼容情况在不同版本有差异,下面是常见开发环境的参考清单。
| 项目 | 推荐参考值 | 说明 |
|---|---|---|
| JDK | 17 或 21 | Spring Boot 3.x 要求 JDK 17 起步,建议直接用 21 |
| Maven | 3.8+ | 仓库拉取 Spring AI BOM 需要可用的 Maven 仓库 |
| Spring Boot | 3.3.x / 3.4.x 或更高 | 以 Spring AI 版本对应的兼容矩阵为准 |
| Spring AI | 2.0.x | 文中示例基于 2.x API 思路 |
| DeepSeek API Key | 从开放平台申请 | 用于访问对话模型,需要单独配置 |
| Embedding 模型 | qwen embedding 或 OpenAI 兼容接口 | 用于向量检索场景,与对话模型分开配置 |
注意:原始材料没有给出固定的 Spring Boot 版本,因此落地前要确认依赖版本和兼容矩阵。不要在 pom.xml 里随意写一个高版本 Spring Boot 去搭配低版本 Spring AI,否则很容易出现自动配置不生效的问题。
2.2 申请 DeepSeek API Key 并核对模型名
DeepSeek 的接入方式和 OpenAI 兼容 API 非常接近。在 DeepSeek 开放平台完成注册后,可以创建 API Key。创建之后需要注意两点:
第一,API Key 只显示一次,离开页面后无法再次查看,需要自己保存好。建议使用环境变量或本地配置中心管理,不要把 Key 硬编码提交到 Git 仓库。
第二,模型名要以官方文档为准。常见的对话模型有 deepseek-chat、deepseek-reasoner 等,不同时期开放平台可能增加或调整模型。写配置时不要把模型名写死成博客里的示例值,先到开放平台确认当前模型名。
export DEEPSEEK_API_KEY=sk-你的key
在本地开发时,这个环境变量会被 Spring 的配置占位符读取,避免 Key 出现在代码中。
2.3 新建一个干净的 Spring Boot 工程
创建一个最小工程,建议先不引入复杂依赖。在 start.spring.io 或者 IDE 初始化工具中选择 Spring Web 和 Spring AI 相关依赖即可。如果 IDE 里还没有 Spring AI 选项,可以在 pom.xml 中手动引入 BOM。
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.4.x</version>
<relativePath/>
</parent>
<properties>
<java.version>21</java.version>
<spring-ai.version>2.0.x</spring-ai.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
核心依赖只需要一个 Web Starter 和一个模型 Starter。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
5220



被折叠的 条评论
为什么被折叠?



