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

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) 三者的关系掰扯清楚，因为这是被问最多的问题。我用一张表对照，你一眼就能看出该选谁。

决策标准其实只有一条：你团队主力后端是 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 地址：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 兼容接口的 starter，TaoToken 的接口是 OpenAI 兼容格式，所以用这个 starter 最省事。

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>1.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 地址，注意结尾不要带斜杠，也不要带/v1，Spring 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()，返回类型改成Flux<String>，这个后面章节细讲。

配置到这里就齐了。启动项目之前，再检查一遍：环境变量TAOTOKEN_API_KEY设了没，base-url是不是https://taotoken.net/api，model是不是控制台里真实存在的 Model ID。这三项任何一个错了，启动可能不报错，但一调用就失败。下一节我们实际发一次请求，看成功结果长什么样。

4. 验证请求：一次对话调用跑通第一个 Spring AI 应用

配置写完，最激动人心的时刻就是看它到底能不能跑通。这一节我带你走一遍完整的验证流程，包括启动、发请求、看返回，以及成功结果应该长什么样。

先设环境变量。Linux 或 macOS 在终端里执行：

export TAOTOKEN_API_KEY=你的Key

Windows 在 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 Flux<String> 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/completions，Spring 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_source=taotoken_aicg_blog_end&utm_campaign=rewrite。

如果你准备把 Key 管理规范化，比如给不同环境、不同项目分配不同的 Key，方便追踪用量和权限，去 API Keys 页面创建和管理。地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_campaign=rewrite。

如果你打算把 Spring AI 用在长期的编码辅助或者 Agent 类场景上，比如让模型帮你读代码、改 bug、跑多步任务，那 Coding Plan 更适合你，它在调用额度和模型选择上更偏向这类高频开发场景。地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_campaign=rewrite。

配置过程中如果对某个参数拿不准，比如 Base URL 到底该写到哪一层、Model ID 去哪找，接入文档里有完整的说明和示例。地址是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_campaign=rewrite。

下一章我们会把 ChatClient 的两种用法讲透，同步和流式分别在什么场景用，以及怎么给对话加上记忆，让它记住上下文。这些都是在今天这个最小闭环上继续往上搭，配置不用重来。