Spring AI 2.0 全面解析Java 程序员的 AI 应用开发第一课本文是《Spring AI 实战》系列第 1 章。2025 年 Spring AI 2.0.0 GA 正式发布Java 程序员终于有了一个生产可用的 AI 应用开发框架。本文从零开始带你搭建环境、写出第一个 AI 程序并理解 Spring AI 到底解决了什么问题。一、AI 应用开发的现状Java 程序员不该被排除在外2024-2025 年AI 应用开发爆发式增长。但如果你是一个 Java/Spring 后端程序员会发现一个尴尬的现实几乎所有的 AI 教程、框架、工具链都是 Python 生态的。Python 有 LangChain、LlamaIndex、Haystack有 Hugging Face 生态有数不清的教程和开源项目。而 Java 程序员呢想在 Spring Boot 项目里接入大模型你得自己封装 HTTP 请求、处理 JSON 解析、管理 API Key、处理流式响应、实现重试逻辑… 纯手工。这不是能力问题是生态缺失的问题。Java 在企业级后端占据统治地位全球超过 60% 的企业后端系统跑在 JVM 上。这些系统积累了大量的业务逻辑和数据恰恰是 AI 应用最好的落地场景——智能客服、文档问答、数据分析、代码审查、流程自动化。Spring AI 的出现正是为了填补这个空白。它把大模型的能力Spring 化了——就像 Spring Data 让你不用写 SQL 就能操作数据库Spring Security 让你不用从零实现认证一样Spring AI 让你不用处理底层 HTTP 请求就能调用大模型。你只需要关注业务逻辑框架帮你搞定剩下的。二、Spring AI 到底解决了什么问题在 Spring AI 出现之前Java 程序员要接入一个大模型 API典型流程是这样的引入 HTTP 客户端OkHttp / WebClient手动构建请求 JSON不同厂商的格式不同手动解析响应 JSON不同厂商的字段名不同处理错误码和重试逻辑每个厂商的错误码定义不同实现 API Key 管理、速率限制如果要切换模型厂商——以上全部重写这就是 Spring AI 要解决的核心痛点统一模型接入。2.1 直接调用 OpenAI API vs 用 Spring AI我们用一个简单的你好请介绍一下自己调用为例看看代码量差多少对比项直接调用 OpenAI API用 Spring AI依赖数量OkHttp JSON 库1 个 Starter代码行数80-120 行5-10 行请求构建手动拼接 JSONchatClient.prompt().user(msg)响应解析手动解析嵌套 JSON.call().content()直接拿字符串流式输出手动处理 SSE 流.stream().content()一行搞定错误处理手动处理各种 HTTP 状态码Spring 自动重试 异常体系切换模型改代码重写请求逻辑只改配置文件直接调用 OpenAI API 的伪代码你真正要写的代码量// 1. 构建 HTTP 请求OkHttpClientclientnewOkHttpClient();Stringjson { model: gpt-4o-mini, messages: [{role: user, content: 你好}], temperature: 0.7 } ;RequestBodybodyRequestBody.create(json,MediaType.parse(application/json));RequestrequestnewRequest.Builder().url(https://api.openai.com/v1/chat/completions).addHeader(Authorization,Bearer apiKey).addHeader(Content-Type,application/json).post(body).build();// 2. 发送请求并解析响应try(Responseresponseclient.newCall(request).execute()){StringresponseBodyresponse.body().string();JsonObjectjsonObjectJsonParser.parseString(responseBody).getAsJsonObject();// 3. 从嵌套 JSON 中提取内容StringcontentjsonObject.getAsJsonArray(choices).get(0).getAsJsonObject().getAsJsonObject(message).get(content).getAsString();returncontent;}用 Spring AI 的代码RestControllerpublicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.Builderbuilder){this.chatClientbuilder.build();}GetMapping(/chat)publicStringchat(RequestParamStringmsg){returnchatClient.prompt().user(msg).call().content();}}代码量从 80 行降到 5 行这不是简单的封装而是抽象层次的跃升。你不再关心 HTTP 细节只关心我要问什么。2.2 消除厂商锁定假设你的应用现在用的是 OpenAI GPT-4o某天老板说成本太高要换成本地部署的开源模型。如果代码里硬编码了 OpenAI 的 API 格式你得把所有 HTTP 请求代码推倒重来。用 Spring AI你只需要改两个地方pom.xml中的 Starter 依赖OpenAI 换成 Ollamaapplication.yml中的配置API Key 换成本地地址Java 代码一行不动。这就是 Spring AI 抽象层的威力——它定义了统一的ChatModel接口OpenAI、Ollama、通义千问、Claude、Gemini 都提供了自己的实现。你的代码只依赖接口不依赖具体实现切换模型就像切换数据库驱动一样简单。2.3 Spring Boot 自动配置Spring AI 完全遵循 Spring Boot 的自动配置理念。你只需要引入 Starter 依赖框架会自动创建ChatModelBean根据你引入的 Starter创建ChatClient.BuilderBean读取application.yml中的配置配置默认的重试策略注册内置的 Advisor就像用 MyBatis 一样自然——引入mybatis-spring-boot-starter写一个 Mapper 接口就能直接用。Spring AI 也是同理引入 starter注入 ChatClient就能直接调用大模型。三、Spring AI vs Spring AI Alibaba该怎么选在开始动手之前你需要了解一个重要的事实Spring AI 和 Spring AI Alibaba 是两个不同的项目它们的定位和适用场景有差异。3.1 对比表格对比项Spring AI官方Spring AI Alibaba定位Spring 官方 AI 框架国际化视野阿里巴巴维护面向国内开发者核心功能模型接入、RAG、Function Calling、Agent在 Spring AI 基础上增加国内云服务适配支持的模型OpenAI、Ollama、Anthropic、Google 等通义千问、百炼平台、阿里云服务额外能力MCP 协议、多模态、向量数据库抽象阿里云 OSS/Redis/RDS 集成、短信/支付社区活跃度Spring 官方维护国际社区活跃阿里巴巴维护国内社区活跃生产可用2.0.0 GA已生产可用同步跟随 Spring AI 版本适合场景国际化项目、多模型需求、标准 AI 能力国内项目、深度使用阿里云生态3.2 选择建议如果你需要对接多个模型厂商OpenAI Ollama Claude 通义千问或者你的项目有国际化需求选择Spring AI 官方版。如果你深度使用阿里云生态OSS、Redis、RDS、短信等主要对接通义千问/百炼平台选择Spring AI Alibaba。好消息是两者兼容。Spring AI Alibaba 是在 Spring AI 基础上的扩展你引入 Spring AI Alibaba 的 Starter 就同时获得了两者的能力。本文基于 Spring AI 2.0.0 官方版讲解所有代码在纯 Spring AI 环境下即可运行。后续涉及国内云服务时我会特别说明。四、完整的环境搭建教程4.1 JDK 版本选择Spring AI 2.0 要求 JDK 17 或更高版本。原因Spring Boot 3.x 要求 JDK 17这是硬性要求Spring AI 大量使用 Java 17 的 Record、Sealed Class、Pattern Matching 等新特性JDK 17 是 LTS长期支持版本生产环境首选推荐 JDK 21。理由JDK 21 也是 LTS 版本支持到 2031 年Spring Boot 3.2 针对 JDK 21 做了优化虚拟线程等Record、Pattern Matching for switch 等特性让 AI 相关代码更简洁# 检查 Java 版本java-version# 推荐输出openjdk version 21.0.x 或 java version 21.0.x4.2 用 Spring Initializr 创建项目最简单的方式是使用 Spring Initializr打开 https://start.spring.io/选择Java 21、Maven、Spring Boot 3.4.xGroup:com.exampleArtifact:spring-ai-demo添加依赖Spring Web点击 Generate下载 zip 包并解压踩坑提醒Spring Initializr 上可能不会直接显示 Spring AI 的依赖。没关系我们手动在 pom.xml 里添加即可。Spring AI 的 BOM 管理会帮你处理版本兼容。4.3 完整 pom.xml?xml version1.0 encodingUTF-8?projectxmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsdmodelVersion4.0.0/modelVersion!-- 使用 Spring Boot 3.4.x 的父 POM自动管理 Spring 版本 --parentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion3.4.2/versionrelativePath//parentgroupIdcom.example/groupIdartifactIdspring-ai-demo/artifactIdversion0.0.1-SNAPSHOT/versionnamespring-ai-demo/namedescriptionSpring AI First Demo/description!-- Java 21 编译级别 --propertiesjava.version21/java.version!-- Spring AI BOM 版本统一管理所有 Spring AI 组件的版本号 --spring-ai.version2.0.0/spring-ai.version/propertiesdependencies!-- Spring Web提供 REST 接口能力 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI OpenAI Starter引入后自动配置 OpenAI 的 ChatModel --!-- 如果用 Ollama换成 spring-ai-starter-model-ollama --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependency!-- Spring Boot Test单元测试 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependencies!-- BOMBill of Materials统一管理 Spring AI 所有 Starter 的版本 --!-- 有了 BOM你不需要在每个 dependency 里写 version --dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementbuildplugins!-- Spring Boot Maven Plugin打包为可执行 jar --plugingroupIdorg.springframework.boot/groupIdartifactIdspring-boot-maven-plugin/artifactId/plugin/plugins/build!-- Spring AI 2.0 的 milestone 和 snapshot 版本需要这个仓库 --!-- GA 版本2.0.0已在 Maven Central 发布可以不加 --repositoriesrepositoryidspring-milestones/idnameSpring Milestones/nameurlhttps://repo.spring.io/milestone/urlsnapshotsenabledfalse/enabled/snapshots/repository/repositories/project4.4 application.yml 配置server:port:8080spring:ai:openai:# API Key 从环境变量读取不要硬编码到代码里api-key:${OPENAI_API_KEY}# 如果使用代理或兼容 OpenAI 协议的第三方服务可以自定义 base-url# base-url: https://your-proxy.com/v1chat:options:# 使用的模型名称model:gpt-4o-mini# 温度参数0确定性输出2创造性输出temperature:0.7API Key 安全管理# Linux/Mac设置环境变量exportOPENAI_API_KEYsk-your-key-here# Windows PowerShell$env:OPENAI_API_KEYsk-your-key-here踩坑提醒不要把 API Key 写到 application.yml 里然后提交到 Git使用环境变量是最佳实践。如果是本地开发可以创建一个application-local.yml加入.gitignore专门存放本地配置。4.5 Maven 镜像配置中国开发者常见坑中国大陆访问 Maven Central 速度慢建议配置阿里云镜像。修改~/.m2/settings.xmlmirrorsmirroridaliyunmaven/idmirrorOf*/mirrorOfname阿里云公共仓库/nameurlhttps://maven.aliyun.com/repository/public/url/mirror/mirrors踩坑提醒Spring AI 的一些里程碑版本可能只在 Spring 自己的仓库里repo.spring.io阿里云镜像可能同步有延迟。如果遇到Could not find artifact错误尝试临时去掉镜像配置直接访问中央仓库或者手动指定 Spring 仓库。4.6 启动验证# 编译并启动mvn spring-boot:run如果看到Started Application in x.xx seconds说明项目启动成功Spring AI 的自动配置已经生效。五、第一个 AI 程序详解5.1 完整 Controller 代码packagecom.example.springaidemo.controller;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;/** * 第一个 AI 程序简单的对话接口 * * 这个 Controller 展示了 Spring AI 最核心的调用模式 * 1. 注入 ChatClient.Builder由 Spring AI 自动配置创建 * 2. 通过 Builder 构建 ChatClient 实例 * 3. 使用 Fluent API 发送请求并获取响应 */RestControllerpublicclassChatController{// ChatClient 是 Spring AI 的核心入口类// 它封装了与大模型通信的所有细节privatefinalChatClientchatClient;/** * 构造函数注入 ChatClient.Builder * * Spring AI 的自动配置会根据你引入的 Starter比如 OpenAI Starter * 自动创建一个 ChatClient.Builder Bean。你只需要注入它然后调用 build() * 就能得到一个配置好的 ChatClient 实例。 * * param builder ChatClient.Builder由 Spring 自动注入 */publicChatController(ChatClient.Builderbuilder){// build() 创建一个默认配置的 ChatClient 实例// 后续我们会看到如何通过 Builder 配置默认 System Prompt、Advisor 等this.chatClientbuilder.build();}/** * 简单对话接口 * * 调用链路拆解 * 1. chatClient.prompt() → 创建一个 Prompt 请求构建器 * 2. .user(msg) → 设置用户消息User Message * 3. .call() → 发送请求到大模型同步等待响应 * 4. .content() → 从响应中提取文本内容 * * param msg 用户输入的消息 * return AI 模型的回复文本 */GetMapping(/chat)publicStringchat(RequestParamStringmsg){returnchatClient.prompt().user(msg).call().content();}}5.2 逐行解释让我们拆解这行核心代码chatClient.prompt().user(msg).call().content()方法作用类比prompt()创建一个 Prompt 请求构建器后续所有调用都基于它PreparedStatement的创建user(msg)设置用户输入的消息内容设置 SQL 参数call()将请求发送到大模型同步等待响应返回execute()执行查询content()从 ChatResponse 中提取纯文本内容getString()从 ResultSet 取值ChatClient.Builder 的注入方式是 Spring AI 的设计亮点ChatClient.Builder是一个 Spring Bean由自动配置创建你通过构造函数注入它然后在构造函数中调用build()得到ChatClient实例这种设计的好处是你可以在 build() 之前配置默认行为后面章节会详细介绍如果需要多个不同配置的 ChatClient可以注入 Builder 多次 build()5.3 启动测试# 确保 Ollama 或 OpenAI API Key 已配置然后启动应用mvn spring-boot:run# 另开一个终端发送测试请求curlhttp://localhost:8080/chat?msg你好请用一句话介绍你自己# 预期输出类似# 你好我是一个AI语言模型可以帮助你回答问题、提供建议和进行各种语言相关的任务。如果你使用的是 OpenAI响应会来自 GPT-4o-mini如果使用的是 Ollama响应会来自本地运行的模型。代码完全一样只是配置不同。六、Ollama 本地方案详解不是每个人都愿意花钱调用 OpenAI API也不是每个项目都适合把数据发送到第三方。Ollama 提供了一个零成本、完全本地的方案。6.1 Ollama 是什么Ollama 是一个本地大模型运行工具它让你在自己的电脑上运行开源大模型如 LLaMA、Qwen、DeepSeek 等无需任何云端 API。为什么推荐 Ollama零成本不需要 API Key不按 Token 计费数据隐私数据不出本地适合处理敏感信息离线可用断网也能用一键安装支持 Windows / Mac / Linux模型丰富支持 100 开源模型6.2 安装命令# WindowsPowerShellwingetinstallOllama.Ollama# MacHomebrewbrewinstallollama# Linuxcurl 一键安装curl-fsSLhttps://ollama.com/install.sh|sh安装完成后Ollama 会作为一个后台服务运行监听http://localhost:11434。6.3 拉取模型# 拉取 Qwen 2.5 7B 模型推荐中文场景ollama pull qwen2.5:7b# 拉取完成后可以直接在命令行对话测试ollama run qwen2.5:7b# 输入你好# 输出你好有什么我可以帮助你的吗# 输入 /exit 退出# 后台启动 Ollama 服务如果还没有启动ollama serve6.4 切换到 Ollamapom.xml 变更!-- 把 OpenAI Starter 替换为 Ollama Starter --!-- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependency6.5 切换到 Ollamaapplication.yml 变更spring:ai:ollama:# Ollama 默认端口是 11434base-url:http://localhost:11434chat:options:# 使用 Qwen 2.5 7B 模型model:qwen2.5:7bJava 代码完全不用改。Controller 中的chatClient.prompt().user(msg).call().content()照常工作。这就是 Spring AI 抽象层的威力。6.6 推荐模型表格模型名参数量中文能力显存需求适用场景qwen2.57B优秀8GB推荐 16GB中文对话、问答、翻译中文场景首选llama3.18B一般8GB推荐 16GB英文对话、代码生成英文能力最强deepseek-r18B良好8GB推荐 16GB复杂推理、数学、逻辑分析gemma29B良好8GB推荐 16GB通用对话、指令跟随phi3-mini3.8B一般4GB轻量级任务、资源受限环境6.7 CPU vs GPU 模式Ollama 会自动检测你的硬件有 NVIDIA GPU自动使用 CUDA 加速速度大幅提升有 Apple SiliconM1/M2/M3/M4自动使用 Metal 加速只有 CPU也能运行但速度慢Qwen 7B 在 CPU 上大约 10-20 tokens/秒踩坑提醒模型不存在错误如果你配置的模型名没有ollama pull过会报错model not found。解决先ollama pull 模型名。端口冲突Ollama 默认使用 11434 端口。如果该端口被占用Ollama 服务会启动失败。检查端口netstat -ano | findstr 11434。Mac M 芯片兼容性Mac Apple Silicon 原生支持体验很好。但部分大参数模型14B可能需要 32GB 以上内存。内存不足7B 模型至少需要 8GB 系统内存。如果你的电脑只有 8GB 内存运行模型时可能非常卡顿。七、Spring AI 核心能力全景图Spring AI 2.0 不仅仅是一个大模型调用工具它是一个完整的 AI 应用开发框架。以下是它的8 大核心能力能力描述适用场景成熟度1. 统一模型接入通过ChatModel接口统一对接 OpenAI、Ollama、通义千问、Claude、Gemini 等任何需要调用大模型的应用稳定2. Prompt 工程PromptTemplate模板系统、变量注入、System Prompt 管理需要精确控制 AI 输出的场景稳定3. 对话记忆ChatMemory接口 MessageChatMemoryAdvisor自动管理多轮对话历史智能客服、对话式应用稳定4. 结构化输出AI 返回的文本自动映射为 Java 对象Record / Bean情感分析、信息提取、意图分类稳定5. RAG检索增强生成文档加载、分割、向量化、存储、检索的完整流程企业知识库问答、文档助手稳定6. Function Calling让 AI 调用你定义的 Java 方法查数据库、调 API、发通知AI 助手、自动化工作流稳定7. Advisor 机制类似 Servlet Filter 的请求/响应处理链可自定义扩展Prompt 增强、日志记录、内容安全稳定8. 多模态与 Agent图片理解Vision、语音交互、Agent 编排复杂的 AI 应用场景快速演进中总结前 7 个能力已经稳定可用可以放心在生产环境使用。多模态和 Agent 相关的能力在 2.0 版本中已经有了基础支持正在快速演进。八、小结本章我们完成了以下内容理解了Spring AI 解决的三个核心痛点统一模型接入、消除厂商锁定、Spring 生态融合搞清了Spring AI 和 Spring AI Alibaba 的区别和选择建议从零搭建了完整的开发环境JDK 21 Spring Boot 3.4 Spring AI 2.0写出了第一个 AI 程序5 行代码调用大模型学会了使用Ollama 本地方案零成本运行大模型了解了 Spring AI 的8 大核心能力下一章我们将深入学习 Spring AI 的核心类ChatClient掌握多轮对话、流式输出、结构化返回等实战能力。Spring AI 实战 — 第1章完整内容与源码
Spring AI 2.0 全面解析Java 程序员的 AI 应用开发第一课本文是《Spring AI 实战》系列第 1 章。2025 年 Spring AI 2.0.0 GA 正式发布Java 程序员终于有了一个生产可用的 AI 应用开发框架。本文从零开始带你搭建环境、写出第一个 AI 程序并理解 Spring AI 到底解决了什么问题。一、AI 应用开发的现状Java 程序员不该被排除在外2024-2025 年AI 应用开发爆发式增长。但如果你是一个 Java/Spring 后端程序员会发现一个尴尬的现实几乎所有的 AI 教程、框架、工具链都是 Python 生态的。Python 有 LangChain、LlamaIndex、Haystack有 Hugging Face 生态有数不清的教程和开源项目。而 Java 程序员呢想在 Spring Boot 项目里接入大模型你得自己封装 HTTP 请求、处理 JSON 解析、管理 API Key、处理流式响应、实现重试逻辑… 纯手工。这不是能力问题是生态缺失的问题。Java 在企业级后端占据统治地位全球超过 60% 的企业后端系统跑在 JVM 上。这些系统积累了大量的业务逻辑和数据恰恰是 AI 应用最好的落地场景——智能客服、文档问答、数据分析、代码审查、流程自动化。Spring AI 的出现正是为了填补这个空白。它把大模型的能力Spring 化了——就像 Spring Data 让你不用写 SQL 就能操作数据库Spring Security 让你不用从零实现认证一样Spring AI 让你不用处理底层 HTTP 请求就能调用大模型。你只需要关注业务逻辑框架帮你搞定剩下的。二、Spring AI 到底解决了什么问题在 Spring AI 出现之前Java 程序员要接入一个大模型 API典型流程是这样的引入 HTTP 客户端OkHttp / WebClient手动构建请求 JSON不同厂商的格式不同手动解析响应 JSON不同厂商的字段名不同处理错误码和重试逻辑每个厂商的错误码定义不同实现 API Key 管理、速率限制如果要切换模型厂商——以上全部重写这就是 Spring AI 要解决的核心痛点统一模型接入。2.1 直接调用 OpenAI API vs 用 Spring AI我们用一个简单的你好请介绍一下自己调用为例看看代码量差多少对比项直接调用 OpenAI API用 Spring AI依赖数量OkHttp JSON 库1 个 Starter代码行数80-120 行5-10 行请求构建手动拼接 JSONchatClient.prompt().user(msg)响应解析手动解析嵌套 JSON.call().content()直接拿字符串流式输出手动处理 SSE 流.stream().content()一行搞定错误处理手动处理各种 HTTP 状态码Spring 自动重试 异常体系切换模型改代码重写请求逻辑只改配置文件直接调用 OpenAI API 的伪代码你真正要写的代码量// 1. 构建 HTTP 请求OkHttpClientclientnewOkHttpClient();Stringjson { model: gpt-4o-mini, messages: [{role: user, content: 你好}], temperature: 0.7 } ;RequestBodybodyRequestBody.create(json,MediaType.parse(application/json));RequestrequestnewRequest.Builder().url(https://api.openai.com/v1/chat/completions).addHeader(Authorization,Bearer apiKey).addHeader(Content-Type,application/json).post(body).build();// 2. 发送请求并解析响应try(Responseresponseclient.newCall(request).execute()){StringresponseBodyresponse.body().string();JsonObjectjsonObjectJsonParser.parseString(responseBody).getAsJsonObject();// 3. 从嵌套 JSON 中提取内容StringcontentjsonObject.getAsJsonArray(choices).get(0).getAsJsonObject().getAsJsonObject(message).get(content).getAsString();returncontent;}用 Spring AI 的代码RestControllerpublicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.Builderbuilder){this.chatClientbuilder.build();}GetMapping(/chat)publicStringchat(RequestParamStringmsg){returnchatClient.prompt().user(msg).call().content();}}代码量从 80 行降到 5 行这不是简单的封装而是抽象层次的跃升。你不再关心 HTTP 细节只关心我要问什么。2.2 消除厂商锁定假设你的应用现在用的是 OpenAI GPT-4o某天老板说成本太高要换成本地部署的开源模型。如果代码里硬编码了 OpenAI 的 API 格式你得把所有 HTTP 请求代码推倒重来。用 Spring AI你只需要改两个地方pom.xml中的 Starter 依赖OpenAI 换成 Ollamaapplication.yml中的配置API Key 换成本地地址Java 代码一行不动。这就是 Spring AI 抽象层的威力——它定义了统一的ChatModel接口OpenAI、Ollama、通义千问、Claude、Gemini 都提供了自己的实现。你的代码只依赖接口不依赖具体实现切换模型就像切换数据库驱动一样简单。2.3 Spring Boot 自动配置Spring AI 完全遵循 Spring Boot 的自动配置理念。你只需要引入 Starter 依赖框架会自动创建ChatModelBean根据你引入的 Starter创建ChatClient.BuilderBean读取application.yml中的配置配置默认的重试策略注册内置的 Advisor就像用 MyBatis 一样自然——引入mybatis-spring-boot-starter写一个 Mapper 接口就能直接用。Spring AI 也是同理引入 starter注入 ChatClient就能直接调用大模型。三、Spring AI vs Spring AI Alibaba该怎么选在开始动手之前你需要了解一个重要的事实Spring AI 和 Spring AI Alibaba 是两个不同的项目它们的定位和适用场景有差异。3.1 对比表格对比项Spring AI官方Spring AI Alibaba定位Spring 官方 AI 框架国际化视野阿里巴巴维护面向国内开发者核心功能模型接入、RAG、Function Calling、Agent在 Spring AI 基础上增加国内云服务适配支持的模型OpenAI、Ollama、Anthropic、Google 等通义千问、百炼平台、阿里云服务额外能力MCP 协议、多模态、向量数据库抽象阿里云 OSS/Redis/RDS 集成、短信/支付社区活跃度Spring 官方维护国际社区活跃阿里巴巴维护国内社区活跃生产可用2.0.0 GA已生产可用同步跟随 Spring AI 版本适合场景国际化项目、多模型需求、标准 AI 能力国内项目、深度使用阿里云生态3.2 选择建议如果你需要对接多个模型厂商OpenAI Ollama Claude 通义千问或者你的项目有国际化需求选择Spring AI 官方版。如果你深度使用阿里云生态OSS、Redis、RDS、短信等主要对接通义千问/百炼平台选择Spring AI Alibaba。好消息是两者兼容。Spring AI Alibaba 是在 Spring AI 基础上的扩展你引入 Spring AI Alibaba 的 Starter 就同时获得了两者的能力。本文基于 Spring AI 2.0.0 官方版讲解所有代码在纯 Spring AI 环境下即可运行。后续涉及国内云服务时我会特别说明。四、完整的环境搭建教程4.1 JDK 版本选择Spring AI 2.0 要求 JDK 17 或更高版本。原因Spring Boot 3.x 要求 JDK 17这是硬性要求Spring AI 大量使用 Java 17 的 Record、Sealed Class、Pattern Matching 等新特性JDK 17 是 LTS长期支持版本生产环境首选推荐 JDK 21。理由JDK 21 也是 LTS 版本支持到 2031 年Spring Boot 3.2 针对 JDK 21 做了优化虚拟线程等Record、Pattern Matching for switch 等特性让 AI 相关代码更简洁# 检查 Java 版本java-version# 推荐输出openjdk version 21.0.x 或 java version 21.0.x4.2 用 Spring Initializr 创建项目最简单的方式是使用 Spring Initializr打开 https://start.spring.io/选择Java 21、Maven、Spring Boot 3.4.xGroup:com.exampleArtifact:spring-ai-demo添加依赖Spring Web点击 Generate下载 zip 包并解压踩坑提醒Spring Initializr 上可能不会直接显示 Spring AI 的依赖。没关系我们手动在 pom.xml 里添加即可。Spring AI 的 BOM 管理会帮你处理版本兼容。4.3 完整 pom.xml?xml version1.0 encodingUTF-8?projectxmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsdmodelVersion4.0.0/modelVersion!-- 使用 Spring Boot 3.4.x 的父 POM自动管理 Spring 版本 --parentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion3.4.2/versionrelativePath//parentgroupIdcom.example/groupIdartifactIdspring-ai-demo/artifactIdversion0.0.1-SNAPSHOT/versionnamespring-ai-demo/namedescriptionSpring AI First Demo/description!-- Java 21 编译级别 --propertiesjava.version21/java.version!-- Spring AI BOM 版本统一管理所有 Spring AI 组件的版本号 --spring-ai.version2.0.0/spring-ai.version/propertiesdependencies!-- Spring Web提供 REST 接口能力 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI OpenAI Starter引入后自动配置 OpenAI 的 ChatModel --!-- 如果用 Ollama换成 spring-ai-starter-model-ollama --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependency!-- Spring Boot Test单元测试 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependencies!-- BOMBill of Materials统一管理 Spring AI 所有 Starter 的版本 --!-- 有了 BOM你不需要在每个 dependency 里写 version --dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementbuildplugins!-- Spring Boot Maven Plugin打包为可执行 jar --plugingroupIdorg.springframework.boot/groupIdartifactIdspring-boot-maven-plugin/artifactId/plugin/plugins/build!-- Spring AI 2.0 的 milestone 和 snapshot 版本需要这个仓库 --!-- GA 版本2.0.0已在 Maven Central 发布可以不加 --repositoriesrepositoryidspring-milestones/idnameSpring Milestones/nameurlhttps://repo.spring.io/milestone/urlsnapshotsenabledfalse/enabled/snapshots/repository/repositories/project4.4 application.yml 配置server:port:8080spring:ai:openai:# API Key 从环境变量读取不要硬编码到代码里api-key:${OPENAI_API_KEY}# 如果使用代理或兼容 OpenAI 协议的第三方服务可以自定义 base-url# base-url: https://your-proxy.com/v1chat:options:# 使用的模型名称model:gpt-4o-mini# 温度参数0确定性输出2创造性输出temperature:0.7API Key 安全管理# Linux/Mac设置环境变量exportOPENAI_API_KEYsk-your-key-here# Windows PowerShell$env:OPENAI_API_KEYsk-your-key-here踩坑提醒不要把 API Key 写到 application.yml 里然后提交到 Git使用环境变量是最佳实践。如果是本地开发可以创建一个application-local.yml加入.gitignore专门存放本地配置。4.5 Maven 镜像配置中国开发者常见坑中国大陆访问 Maven Central 速度慢建议配置阿里云镜像。修改~/.m2/settings.xmlmirrorsmirroridaliyunmaven/idmirrorOf*/mirrorOfname阿里云公共仓库/nameurlhttps://maven.aliyun.com/repository/public/url/mirror/mirrors踩坑提醒Spring AI 的一些里程碑版本可能只在 Spring 自己的仓库里repo.spring.io阿里云镜像可能同步有延迟。如果遇到Could not find artifact错误尝试临时去掉镜像配置直接访问中央仓库或者手动指定 Spring 仓库。4.6 启动验证# 编译并启动mvn spring-boot:run如果看到Started Application in x.xx seconds说明项目启动成功Spring AI 的自动配置已经生效。五、第一个 AI 程序详解5.1 完整 Controller 代码packagecom.example.springaidemo.controller;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;/** * 第一个 AI 程序简单的对话接口 * * 这个 Controller 展示了 Spring AI 最核心的调用模式 * 1. 注入 ChatClient.Builder由 Spring AI 自动配置创建 * 2. 通过 Builder 构建 ChatClient 实例 * 3. 使用 Fluent API 发送请求并获取响应 */RestControllerpublicclassChatController{// ChatClient 是 Spring AI 的核心入口类// 它封装了与大模型通信的所有细节privatefinalChatClientchatClient;/** * 构造函数注入 ChatClient.Builder * * Spring AI 的自动配置会根据你引入的 Starter比如 OpenAI Starter * 自动创建一个 ChatClient.Builder Bean。你只需要注入它然后调用 build() * 就能得到一个配置好的 ChatClient 实例。 * * param builder ChatClient.Builder由 Spring 自动注入 */publicChatController(ChatClient.Builderbuilder){// build() 创建一个默认配置的 ChatClient 实例// 后续我们会看到如何通过 Builder 配置默认 System Prompt、Advisor 等this.chatClientbuilder.build();}/** * 简单对话接口 * * 调用链路拆解 * 1. chatClient.prompt() → 创建一个 Prompt 请求构建器 * 2. .user(msg) → 设置用户消息User Message * 3. .call() → 发送请求到大模型同步等待响应 * 4. .content() → 从响应中提取文本内容 * * param msg 用户输入的消息 * return AI 模型的回复文本 */GetMapping(/chat)publicStringchat(RequestParamStringmsg){returnchatClient.prompt().user(msg).call().content();}}5.2 逐行解释让我们拆解这行核心代码chatClient.prompt().user(msg).call().content()方法作用类比prompt()创建一个 Prompt 请求构建器后续所有调用都基于它PreparedStatement的创建user(msg)设置用户输入的消息内容设置 SQL 参数call()将请求发送到大模型同步等待响应返回execute()执行查询content()从 ChatResponse 中提取纯文本内容getString()从 ResultSet 取值ChatClient.Builder 的注入方式是 Spring AI 的设计亮点ChatClient.Builder是一个 Spring Bean由自动配置创建你通过构造函数注入它然后在构造函数中调用build()得到ChatClient实例这种设计的好处是你可以在 build() 之前配置默认行为后面章节会详细介绍如果需要多个不同配置的 ChatClient可以注入 Builder 多次 build()5.3 启动测试# 确保 Ollama 或 OpenAI API Key 已配置然后启动应用mvn spring-boot:run# 另开一个终端发送测试请求curlhttp://localhost:8080/chat?msg你好请用一句话介绍你自己# 预期输出类似# 你好我是一个AI语言模型可以帮助你回答问题、提供建议和进行各种语言相关的任务。如果你使用的是 OpenAI响应会来自 GPT-4o-mini如果使用的是 Ollama响应会来自本地运行的模型。代码完全一样只是配置不同。六、Ollama 本地方案详解不是每个人都愿意花钱调用 OpenAI API也不是每个项目都适合把数据发送到第三方。Ollama 提供了一个零成本、完全本地的方案。6.1 Ollama 是什么Ollama 是一个本地大模型运行工具它让你在自己的电脑上运行开源大模型如 LLaMA、Qwen、DeepSeek 等无需任何云端 API。为什么推荐 Ollama零成本不需要 API Key不按 Token 计费数据隐私数据不出本地适合处理敏感信息离线可用断网也能用一键安装支持 Windows / Mac / Linux模型丰富支持 100 开源模型6.2 安装命令# WindowsPowerShellwingetinstallOllama.Ollama# MacHomebrewbrewinstallollama# Linuxcurl 一键安装curl-fsSLhttps://ollama.com/install.sh|sh安装完成后Ollama 会作为一个后台服务运行监听http://localhost:11434。6.3 拉取模型# 拉取 Qwen 2.5 7B 模型推荐中文场景ollama pull qwen2.5:7b# 拉取完成后可以直接在命令行对话测试ollama run qwen2.5:7b# 输入你好# 输出你好有什么我可以帮助你的吗# 输入 /exit 退出# 后台启动 Ollama 服务如果还没有启动ollama serve6.4 切换到 Ollamapom.xml 变更!-- 把 OpenAI Starter 替换为 Ollama Starter --!-- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependency6.5 切换到 Ollamaapplication.yml 变更spring:ai:ollama:# Ollama 默认端口是 11434base-url:http://localhost:11434chat:options:# 使用 Qwen 2.5 7B 模型model:qwen2.5:7bJava 代码完全不用改。Controller 中的chatClient.prompt().user(msg).call().content()照常工作。这就是 Spring AI 抽象层的威力。6.6 推荐模型表格模型名参数量中文能力显存需求适用场景qwen2.57B优秀8GB推荐 16GB中文对话、问答、翻译中文场景首选llama3.18B一般8GB推荐 16GB英文对话、代码生成英文能力最强deepseek-r18B良好8GB推荐 16GB复杂推理、数学、逻辑分析gemma29B良好8GB推荐 16GB通用对话、指令跟随phi3-mini3.8B一般4GB轻量级任务、资源受限环境6.7 CPU vs GPU 模式Ollama 会自动检测你的硬件有 NVIDIA GPU自动使用 CUDA 加速速度大幅提升有 Apple SiliconM1/M2/M3/M4自动使用 Metal 加速只有 CPU也能运行但速度慢Qwen 7B 在 CPU 上大约 10-20 tokens/秒踩坑提醒模型不存在错误如果你配置的模型名没有ollama pull过会报错model not found。解决先ollama pull 模型名。端口冲突Ollama 默认使用 11434 端口。如果该端口被占用Ollama 服务会启动失败。检查端口netstat -ano | findstr 11434。Mac M 芯片兼容性Mac Apple Silicon 原生支持体验很好。但部分大参数模型14B可能需要 32GB 以上内存。内存不足7B 模型至少需要 8GB 系统内存。如果你的电脑只有 8GB 内存运行模型时可能非常卡顿。七、Spring AI 核心能力全景图Spring AI 2.0 不仅仅是一个大模型调用工具它是一个完整的 AI 应用开发框架。以下是它的8 大核心能力能力描述适用场景成熟度1. 统一模型接入通过ChatModel接口统一对接 OpenAI、Ollama、通义千问、Claude、Gemini 等任何需要调用大模型的应用稳定2. Prompt 工程PromptTemplate模板系统、变量注入、System Prompt 管理需要精确控制 AI 输出的场景稳定3. 对话记忆ChatMemory接口 MessageChatMemoryAdvisor自动管理多轮对话历史智能客服、对话式应用稳定4. 结构化输出AI 返回的文本自动映射为 Java 对象Record / Bean情感分析、信息提取、意图分类稳定5. RAG检索增强生成文档加载、分割、向量化、存储、检索的完整流程企业知识库问答、文档助手稳定6. Function Calling让 AI 调用你定义的 Java 方法查数据库、调 API、发通知AI 助手、自动化工作流稳定7. Advisor 机制类似 Servlet Filter 的请求/响应处理链可自定义扩展Prompt 增强、日志记录、内容安全稳定8. 多模态与 Agent图片理解Vision、语音交互、Agent 编排复杂的 AI 应用场景快速演进中总结前 7 个能力已经稳定可用可以放心在生产环境使用。多模态和 Agent 相关的能力在 2.0 版本中已经有了基础支持正在快速演进。八、小结本章我们完成了以下内容理解了Spring AI 解决的三个核心痛点统一模型接入、消除厂商锁定、Spring 生态融合搞清了Spring AI 和 Spring AI Alibaba 的区别和选择建议从零搭建了完整的开发环境JDK 21 Spring Boot 3.4 Spring AI 2.0写出了第一个 AI 程序5 行代码调用大模型学会了使用Ollama 本地方案零成本运行大模型了解了 Spring AI 的8 大核心能力下一章我们将深入学习 Spring AI 的核心类ChatClient掌握多轮对话、流式输出、结构化返回等实战能力。Spring AI 实战 — 第1章完整内容与源码
