1. 从 Spring Boot 项目出发为什么 Java 后端需要 Spring AI 这层封装如果你是一个写了几年 Spring Boot 的 Java 后端最近大概率被两个词反复刷屏一个是 LangChain一个是 Spring AI。前者是 Python 生态里做大模型应用的事实标准后者是 Spring 官方团队给 Java 世界补上的那块拼图。问题在于很多同学第一次接触时会把它们当成同一类东西去比较结果越比越乱。我先把结论放前面Spring AI 不是Java 版的 LangChain它是 Spring 生态的 AI 接入层定位更接近 JdbcTemplate 之于数据库——把各家大模型千奇百怪的 HTTP 协议、鉴权方式、流式响应格式统一收敛成一套你熟悉的 Spring 风格 API。那为什么 Java 后端需要这层封装你可以回想一下在没有 Spring AI 之前你要在 Spring Boot 里接一个大模型得干哪些活。首先得引入 HTTP 客户端RestTemplate 或者 WebClient 选一个然后手动拼请求体 JSON把 model、messages、temperature 这些字段一个个塞进去接着处理响应普通响应还好流式响应就得自己解析 SSE 的 data 行处理[DONE]结束标记最后还要为不同厂商写不同的适配代码因为 OpenAI、通义千问、DeepSeek 的字段名和返回结构并不完全一致。这一整套下来一个简单的问一句答一句功能能写出三四百行胶水代码而且每换一个模型供应商就要改一遍。Spring AI 要解决的就是这个重复劳动。它提供了一套统一的抽象ChatClient、EmbeddingClient、VectorStore、ChatMemory 等等。你面向接口编程底层换模型只改配置文件业务代码一行不动。这对 Java 团队的意义特别大因为 Spring 生态里那些你已经用顺手的东西——配置中心、AOP 切面、事务管理、监控埋点——全都能无缝套在 AI 调用上。比如你想给每次大模型调用加个耗时统计写个Around切面就行不需要额外适配。这里必须把 Spring AI、LangChain4j、LangChain(Python) 三者的关系掰扯清楚因为这是被问最多的问题。我用一张表对照你一眼就能看出该选谁。维度Spring AILangChain4jLangChain(Python)母体生态Spring Boot / Spring CloudJava 生态非 Spring 专属Python 生态上手门槛会 Spring Boot 就能用需学 LangChain 抽象概念需学概念 PythonAI 能力完备度Chat、Embedding、RAG、Function Calling、多模态Chat、Embedding、RAG、Agent、Tools最全社区最活跃生产适配天然集成 Spring 全家桶需自己集成 Spring 组件非 Java 生态适合谁Spring 技术栈团队Java 非 Spring 项目如 QuarkusPython / 算法团队决策标准其实只有一条你团队主力后端是 Java Spring就直接上 Spring AI别犹豫。Spring AI 在 Spring 生态里的集成体验是降维打击级别的事务、配置中心、AOP 这些你不需要额外适配。你是 Python 技术栈用 LangChain。你是 Java 但不用 Spring比如 Quarkus 或者纯 Java 项目那看 LangChain4j。不过说实话国内 Java 后端有多少不用 Spring 的这个选项其实很少人走。我试过在一个知识库问答项目里做技术选型当时有人提议用 Python LangChain理由是资料多。我否决了原因很实在团队全员 Java引入 Python 服务意味着多维护一套技术栈知识库数据在现有 Spring 服务里跨语言调用增加网络开销而 Spring AI 做的事情本质上是 HTTP 调用加向量检索不复杂没必要为此引入新语言。最后全链路用 Spring AI 做的研发效率高于预期。当然它当时有些功能不成熟比如 Agent 编排这部分我们自己写了点胶水代码后面章节会细说。所以这一章的目标很明确先让你在脑子里建立Spring AI 是接入层这个认知然后动手把第一个能跑通的 Spring AI 应用搭起来。而搭的过程中绕不开一个现实问题——模型 API 的接入通道。这就是 TaoToken 出场的地方下一节展开。2. TaoToken 前置统一 Key 与 API 通道解决 Spring AI 配置里的多模型切换痛点在动手写代码之前得先把模型从哪来这件事说清楚。Spring AI 本身不提供模型它只是个调用框架你得给它配一个能访问的模型服务。这时候通常有几条路直接用某一家厂商的官方 API、自己搭一套转发服务、或者用一个统一的 API 通道。前两条路各有各的麻烦——官方 API 意味着你被单一厂商绑定想换模型就得改代码改配置自己搭转发服务维护成本不说稳定性和鉴权都得自己扛。TaoToken 在这里扮演的角色就是一个统一的 Key 与 API 通道。你注册后拿到一个 API Key配一个 Base URL就能通过同一套接口访问多种模型。对 Spring AI 来说这意味着你的application.yml里那几行配置换模型时只需要改model字段Base URL 和 Key 都不用动。这个价值在开发阶段特别明显你想对比 DeepSeek 和通义千问哪个回答质量好不用去两个平台各注册一遍、各拿一个 Key、各配一套环境变量改一行配置就能切。先把地址记下来后面配置要用官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api注意 API 地址后面不加任何 UTM 参数配置里就写这个干净的地址。这一点很多人第一次配会搞错把带参数的完整 URL 填进去结果请求路径拼出来是错的报 404。接下来是拿 Key 的步骤。打开官网注册登录后进入控制台找到 API Keys 页面创建一个新的 Key。创建时通常会让你起个名字随便起比如spring-ai-demo方便以后区分。创建完把 Key 复制下来注意它一般只显示一次关掉页面就看不到了所以先粘到安全的地方。这个 Key 就是你 Spring AI 配置里的api-key。这里有个安全提醒Key 千万不要硬编码在代码里提交到 Git。正确做法是放在环境变量或者配置中心application.yml里用占位符引用。后面配置片段我会写成${TAOTOKEN_API_KEY}这种形式你在本地跑的时候要么设环境变量要么在 IDE 的运行配置里填。关于模型选择TaoToken 控制台里一般能看到当前支持的模型列表每个模型有个 Model ID比如deepseek-chat、qwen-plus这类。这个 Model ID 就是 Spring AI 配置里options.model要填的值。你选哪个模型取决于你的场景日常对话和代码生成DeepSeek 系列性价比高中文理解和长文本通义千问系列表现稳需要多模态看图就选支持视觉的模型。开发阶段建议先选一个便宜的跑通流程别一上来就用最贵的。还有一个容易被忽略的点Base URL 的路径。Spring AI 的 OpenAI 兼容 starter 默认会往 Base URL 后面拼/v1/chat/completions这类路径。所以你的 Base URL 应该配到域名加/api这一层而不是配到完整的接口路径。配错了典型表现就是 404 或者 401下一节配置里我会写清楚。把 Key 和 Base URL 准备好环境就算齐了。接下来进入正题在 Spring Boot 项目里把这些配置项填进去让 ChatClient 能真正发出请求。3. 可复制配置Spring Boot 项目接入 Spring AI 的 application.yml 与依赖片段这一节是纯操作你跟着复制粘贴就能跑。先确认你的项目环境JDK 17 或以上Spring Boot 3.2 或以上Maven 或 Gradle 都行我用 Maven 演示。Spring AI 已经发布 1.0 正式版核心 API 稳定所以依赖版本直接用 1.0.0 即可不用再追 SNAPSHOT。第一步在pom.xml里加依赖。Spring AI 提供了针对 OpenAI 兼容接口的 starterTaoToken 的接口是 OpenAI 兼容格式所以用这个 starter 最省事。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0/version /dependency如果你用的是 Spring AI 的 BOM 管理版本也可以在dependencyManagement里引入 BOM然后依赖不写版本号。两种方式都行我这里写死版本号是为了让你复制就能用。第二步配置application.yml。这是本篇最核心的片段路径和字段名都按 Spring AI 1.0 的规范来你直接抄。spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: deepseek-chat temperature: 0.7 embedding: options: model: text-embedding-3-small逐行解释一下。base-url填 TaoToken 的 API 地址注意结尾不要带斜杠也不要带/v1Spring AI 会自己拼。api-key用环境变量占位符你在本地跑之前先设好TAOTOKEN_API_KEY这个环境变量值就是你刚才复制的 Key。chat.options.model填你在控制台选的 Model ID我这里用deepseek-chat举例。temperature控制回答的随机性0 到 1 之间写代码建议 0.2 到 0.5创意写作可以 0.8 以上。embedding那段是给向量检索用的这一章用不到可以先留着不影响启动。如果你不想用环境变量也可以直接在 yml 里写 Key但强烈不建议提交到 Git。折中方案是用 Spring 的多环境配置本地建一个application-local.yml并加入.gitignore。第三步写一个配置类把 ChatClient 注册成 Bean。Spring AI 的 starter 会自动装配ChatModel你只需要基于它构建ChatClient。Configuration public class ChatClientConfig { Bean public ChatClient chatClient(ChatModel chatModel) { return ChatClient.builder(chatModel) .defaultSystem(你是一个严谨的 Java 技术助手回答尽量给出可运行的代码。) .build(); } }这里defaultSystem设的是系统提示词相当于给模型定个人设。你可以改成任何你想要的比如你是一个客服助手回答要简洁。第四步写一个 Controller 或者 CommandLineRunner 来发起调用。为了验证方便我用一个简单的 REST 接口。RestController RequestMapping(/ai) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.prompt() .user(message) .call() .content(); } }这段代码就是 Spring AI 的核心用法prompt()开始构建请求user()填用户消息call()同步调用content()取文本结果。如果你要流式输出把call()换成stream()返回类型改成FluxString这个后面章节细讲。配置到这里就齐了。启动项目之前再检查一遍环境变量TAOTOKEN_API_KEY设了没base-url是不是https://taotoken.net/apimodel是不是控制台里真实存在的 Model ID。这三项任何一个错了启动可能不报错但一调用就失败。下一节我们实际发一次请求看成功结果长什么样。4. 验证请求一次对话调用跑通第一个 Spring AI 应用配置写完最激动人心的时刻就是看它到底能不能跑通。这一节我带你走一遍完整的验证流程包括启动、发请求、看返回以及成功结果应该长什么样。先设环境变量。Linux 或 macOS 在终端里执行export TAOTOKEN_API_KEY你的KeyWindows 在 PowerShell 里$env:TAOTOKEN_API_KEY你的Key如果你用 IDEA也可以在 Run Configuration 的 Environment variables 里填这样不用每次开终端都设一遍。然后启动 Spring Boot 应用。启动日志里你会看到 Spring AI 自动装配的相关信息比如OpenAiChatModel被创建。如果启动阶段就报错大概率是依赖版本冲突或者 yml 格式问题先看日志第一行报的什么。启动成功后用 curl 发一个请求curl http://localhost:8080/ai/chat?message用一句话解释什么是Spring AI正常的话你会看到类似这样的返回{ code: 200, data: Spring AI 是 Spring 生态中用于接入大模型的统一抽象层让你用熟悉的 Spring 风格调用各种 AI 模型。 }注意我这里为了演示包了一层你实际返回的是纯文本字符串因为 Controller 直接返回String。如果你想要 JSON 结构把返回类型改成自定义的 DTO 就行。再试一个稍微复杂点的让它写代码curl http://localhost:8080/ai/chat?message写一个Java方法判断字符串是否为回文返回应该是一段带代码块的文本。到这一步你的第一个 Spring AI 应用就算跑通了。整个过程的核心就三件事配好 Base URL 和 Key构建 ChatClient调用 prompt 链。如果你想验证流式输出把 Controller 改一下GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }然后用 curl 加-N参数看流式效果curl -N http://localhost:8080/ai/chat/stream?message讲个笑话你会看到文字一段一段吐出来而不是等全部生成完才返回。流式在聊天类应用里体验好很多用户不用干等。验证阶段还有个小技巧如果你不确定请求到底发到哪了可以在application.yml里把 Spring AI 的日志级别调成 DEBUG。logging: level: org.springframework.ai: DEBUG这样你能在控制台看到实际发出的请求 URL、请求体、响应体排查问题特别有用。我第一次配的时候就是靠这个日志发现 Base URL 多写了个/v1导致路径拼成了/v1/v1/chat/completions直接 404。跑通之后你可以试着改model字段换成控制台里另一个 Model ID重启应用再调一次感受一下换模型不改代码是什么体验。这就是 Spring AI 加统一通道组合起来的价值。5. 本篇常见错排查401、local proxy failed、reading choices 这些报错怎么解配置和验证都顺的话你已经跑通了。但现实是第一次配大概率会踩坑。这一节我把最常见的几类报错和排查思路列出来你对着日志找就行。第一类401 Unauthorized。这个最直接就是 Key 不对。可能的原因有几个Key 复制的时候带了空格或者换行环境变量没设成功${TAOTOKEN_API_KEY}解析成了字面量Key 被禁用或者额度用完了。排查方法先在终端echo $TAOTOKEN_API_KEY看看值对不对然后确认 yml 里占位符拼写没错。如果 Key 本身没问题去控制台看看这个 Key 的状态和余额。第二类404 Not Found。这个八成是 Base URL 配错了。常见错误是把完整接口路径填进去了比如https://taotoken.net/api/v1/chat/completionsSpring AI 又给你拼了一次结果路径重复。正确写法就是https://taotoken.net/api不要带/v1不要带/chat/completions。还有一种可能是 Model ID 写错了某些服务对不存在的模型返回 404 而不是 400。第三类local proxy failed或者连接超时。这个报错通常出现在网络层意思是请求根本没发出去或者连不上目标。排查顺序先确认你的机器能访问taotoken.net用curl -v https://taotoken.net/api看能不能通然后检查有没有配了什么奇怪的代理设置比如http_proxy环境变量指向了一个不可用的地址最后确认防火墙或者公司网络有没有拦截。这类问题跟代码无关是环境问题。第四类Error reading choices或者解析响应失败。这个报错说明请求发出去了也收到响应了但 Spring AI 解析响应体的时候对不上字段。常见原因是返回的不是标准 OpenAI 格式比如某些错误响应被当成了正常响应解析。排查方法开 DEBUG 日志看实际返回的 JSON 长什么样。如果返回的是错误信息比如{error: {message: ...}}那真正的问题在错误信息里不在解析。如果返回格式确实不对检查你用的 starter 版本和接口是否匹配。第五类OAuth 或者鉴权相关的报错。如果你看到类似OAuth字样的错误先确认你用的是 API Key 鉴权而不是 OAuth 流程。Spring AI 的 OpenAI starter 默认走 Bearer Token也就是Authorization: Bearer key这个头。如果你在配置里混入了其他鉴权方式就会冲突。检查 yml 里有没有多余的鉴权配置项。第六类启动就失败报 Bean 创建异常。这个通常是依赖问题。检查pom.xml里 Spring AI 的版本和 Spring Boot 版本是否兼容1.0.0 的 Spring AI 需要 Spring Boot 3.2 以上。另外如果你同时引入了多个 AI starter比如又引了 OpenAI 又引了别的可能导致ChatModelBean 冲突这时候需要用Qualifier指定或者排除掉不用的。排查的通用思路就一条先看日志级别调到 DEBUG看实际请求和响应大部分问题一眼就能定位。报错信息里如果出现了具体的 URL、状态码、响应体优先看这些比瞎猜快得多。6. 语义一致 CTA下一步该往哪走跑通第一个 Spring AI 应用之后你手里已经有了一个能对话的最小闭环。接下来无非是三个方向把模型调用能力用起来、把接入配置管好、把复杂场景搭起来。如果你现在最想做的事是赶紧多试几个模型看看哪个回答质量合你胃口可以直接去模型对话页面手动聊几轮感受不同模型的差异再决定项目里默认用哪个。地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。如果你准备把 Key 管理规范化比如给不同环境、不同项目分配不同的 Key方便追踪用量和权限去 API Keys 页面创建和管理。地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。如果你打算把 Spring AI 用在长期的编码辅助或者 Agent 类场景上比如让模型帮你读代码、改 bug、跑多步任务那 Coding Plan 更适合你它在调用额度和模型选择上更偏向这类高频开发场景。地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。配置过程中如果对某个参数拿不准比如 Base URL 到底该写到哪一层、Model ID 去哪找接入文档里有完整的说明和示例。地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。下一章我们会把 ChatClient 的两种用法讲透同步和流式分别在什么场景用以及怎么给对话加上记忆让它记住上下文。这些都是在今天这个最小闭环上继续往上搭配置不用重来。
