1. 从零搭公司 AI 助手Spring AI ChatModel 配置为什么总踩坑刚接触 Spring AI 的人八股背得再熟一到真项目里把 ChatModel 配起来还是会卡在几个地方依赖版本对不上、ChatClient 注入不进来、endpoint 写死在某家厂商、Key 散落在各个配置文件里。我试过最省事的做法就是先别管面试题直接跟着一个真实场景把链路跑通——给公司内部做一个 AI 助手员工能问报销制度、查年假、建工单还要记住上下文。跑通一遍之后ChatModel、ChatClient、Advisor、RAG、Tool Calling 这些词自然就串成一条线了。这篇要解决的核心问题很具体Spring AI 的 ChatModel/ChatClient 初始化链路到底怎么走以及怎样把 endpoint 统一改到 TaoToken 的 Key/API 通道上。适合谁看适合已经会写 Spring Boot、但第一次接大模型、被各种厂商 SDK 和配置项绕晕的 Java 后端。你不需要先懂向量数据库也不需要先买某家模型的额度跟着配置走一遍能拿到一次真实的 RAG Tool Calling 返回结果。先说清楚 Spring AI 是什么。它是 Spring 生态里的 AI 应用开发框架自己不训练模型做的是“翻译”和“组装”把不同模型厂商、向量库、工具调用、聊天记忆包装成一套相对统一的 Spring API。业务代码只依赖 ChatClient、ChatModel 这些抽象底层换模型时改动量能压到很小。这一点在面试里经常被问但真正理解它得从你亲手写一个 Bean 开始。我踩过的第一个坑是版本。Spring AI 2.0.x 对应 Spring Boot 4.0/4.1如果你的项目还在 Spring Boot 3依赖大概率停在 Spring AI 1.1.x部分依赖名和 Tool Calling API 有区别。本文以 Spring AI 2.0.0 为主线核心思路在 1.1.x 上也通用遇到差异我会标出来。下面从依赖开始一步步把 ChatModel 和 ChatClient 配出来再把 endpoint 切到统一通道。2. TaoToken 前置准备统一 Key 与 API 通道怎么接在写配置之前先把“模型从哪来”这件事定下来。很多教程默认你直连某家厂商结果代码里到处是厂商专属的 base-url 和 api-key换模型时全项目搜替换。更省心的做法是用一个统一的 OpenAI 兼容通道把 Key 和 endpoint 收敛到一处。TaoToken 就是这样一个通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要准备的东西只有两样一个 API Key一个 Base URL。Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建之后复制出来注意它只完整显示一次丢了就重新建一个。Base URL 统一用 https://taotoken.net/api 后面 Spring AI 的配置里会用到。这里要强调一个概念TaoToken 是合规的 API 聚合通道不是让你绕过什么限制的工具。它的价值在于把多家模型的调用统一成 OpenAI 兼容格式你的 Spring AI 代码只认一套协议切换模型时改一个 model 名就行。对团队来说Key 集中管理、用量集中看比每个服务各配一份厂商 Key 要清爽得多。选模型的时候如果你只是验证连通性随便挑一个对话模型即可如果要做长期编码或 Agent 类任务可以看 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有适合持续调用的套餐说明。想先在网页上试试模型对话效果可以直接打开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 不用写代码就能发一句话看返回。把 Key 和 Base URL 拿到手之后别急着写 Java。先用一条 curl 确认通道是通的这一步能帮你排除掉后面一半的“配置没错但请求失败”问题。命令如下把$TAOTOKEN_KEY换成你自己的 Keycurl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话介绍 Spring AI}] }如果返回里能看到choices数组和一段回答说明 Key 和通道都没问题。如果返回 401先检查 Key 有没有复制全、有没有多余空格如果返回 404检查 Base URL 是不是写成了带/v1的完整路径——Spring AI 的 OpenAI starter 会自己拼/v1/chat/completions你只需要给到https://taotoken.net/api这一层。这个细节后面排障还会再提。3. 可复制配置application.yml 与 ChatClient Bean 完整写法现在进入正题把 Spring AI 的依赖和配置写出来。先看 Maven 依赖Spring AI 2.0.0 的 OpenAI starter 是核心dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId version2.0.0/version /dependency如果你用的是 Spring Boot 3 Spring AI 1.1.xartifactId 可能是spring-ai-openai-spring-boot-starter以你项目实际能拉到的版本为准。依赖拉下来之后写application.yml。这里的关键是把base-url指向 TaoTokenapi-key从环境变量读不要把 Key 硬编码进仓库spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7 max-tokens: 2048base-url只写到https://taotoken.net/api不要带/v1。api-key用${TAOTOKEN_API_KEY}占位启动时通过环境变量注入这样配置文件可以安全提交。model换成你在 TaoToken 控制台确认可用的模型名即可。配置写完Spring AI 的自动配置会帮你创建好底层的OpenAiChatModel它实现了ChatModel接口。但业务代码里我们一般不直接用 ChatModel而是用 ChatClient。ChatClient 构建在 ChatModel 之上提供链式 API还能组合 Advisor、Memory、RAG 和 Tool Calling。手动声明一个 ChatClient BeanConfiguration public class AiConfig { Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultSystem(你是公司内部技术助手回答要简洁准确涉及制度时以检索到的文档为准。) .build(); } }ChatClient.Builder是 Spring AI 自动注入的它内部已经持有了配置好的 ChatModel。你不需要自己 new 一个 ChatModel也不需要在 Bean 里重复写 base-url。这就是统一通道的好处配置只在一处Bean 只关心业务默认值。如果你需要更细的控制比如给不同业务用不同模型可以注入ChatModel自己构造Bean public ChatClient reportChatClient(OpenAiChatModel chatModel) { return ChatClient.builder(chatModel) .defaultSystem(你负责整理报销相关问答。) .build(); }注意这里注入的是具体实现OpenAiChatModel它由 starter 根据application.yml自动创建。如果你在 1.1.x 上类名可能是OpenAiChatModel或OpenAiApi的组合以实际包路径为准。核心逻辑不变配置驱动底层模型Bean 负责业务默认值。到这里ChatModel 和 ChatClient 的初始化链路就清楚了application.yml→ 自动配置创建 ChatModel → ChatClient.Builder 持有 ChatModel → 你的 Bean 产出 ChatClient。面试问“ChatModel 和 ChatClient 谁调用谁”答案就是 ChatClient 建立在 ChatModel 之上ChatModel 负责真正访问模型ChatClient 负责组织一次完整的 AI 业务对话。4. 验证请求一次 RAG Tool Calling 的完整返回结构配置好了得验证它真的能跑。先写一个最简单的 Controller确认 ChatClient 能返回文本RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/chat) public String chat(RequestParam String q) { return chatClient.prompt() .user(q) .call() .content(); } }启动项目访问/chat?q用一句话介绍Spring AI如果返回一段正常回答说明 ChatModel 配置和 TaoToken 通道都通了。这一步失败的话先看启动日志里有没有OpenAiApi相关的初始化异常再对照第 5 节的排障表。接下来加 RAG。RAG 的核心是“先检索、再增强 Prompt、最后生成”。为了演示我们用一个内存向量库避免额外装数据库。Spring AI 提供了SimpleVectorStore配合EmbeddingModel就能跑Bean public VectorStore vectorStore(EmbeddingModel embeddingModel) { SimpleVectorStore store SimpleVectorStore.builder(embeddingModel).build(); ListDocument docs List.of( new Document(差旅管理制度第12条出差住宿每晚标准为500元超标部分需提前审批。), new Document(年假制度入职满一年享5天年假满三年享10天。) ); store.add(docs); return store; }然后在调用时挂上QuestionAnswerAdvisorString answer chatClient.prompt() .advisors(QuestionAnswerAdvisor.builder(vectorStore).build()) .user(出差住酒店每晚最多报销多少) .call() .content();如果返回里出现“500元”这个数字说明检索和增强都生效了。注意EmbeddingModel也是走 TaoToken 通道的因为 OpenAI starter 会复用同一套base-url和api-key。如果你的 Embedding 模型和对话模型不是同一个需要在配置里单独指定 embedding 的 model 名。再加 Tool Calling。定义一个查询年假的工具public class LeaveTools { Tool(description 查询当前登录员工的剩余年假天数) public String getLeaveBalance() { return 剩余年假 5 天; } }调用时把工具传进去String answer chatClient.prompt() .user(我还剩几天年假) .tools(new LeaveTools()) .call() .content();返回里应该包含“5 天”。这里要理解 Tool Calling 的完整链路应用把工具名、说明、参数 Schema 发给模型 → 模型判断需要调用getLeaveBalance→ 模型返回工具名和参数 → 应用执行 Java 方法 → 应用把结果发回模型 → 模型组织成自然语言。模型不会直接执行你的 Java 代码执行的是应用。这一点面试常考也是安全设计的底线。如果你想看完整的返回结构把.content()换成.chatResponse()会拿到ChatResponse对象里面有Generation、token 使用量、模型元数据和结束原因。做成本统计和排障时保留ChatResponse比只拿字符串有用得多。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置和验证都跑通之后实际项目里还是会遇到各种报错。下面这张表是我和同事踩过的坑对照着查能省不少时间。报错现象常见原因处理方式401 UnauthorizedKey 错误、过期、有多余空格重新在控制台复制 Key检查环境变量是否注入成功local proxy failed本地网络或代理配置干扰检查系统代理设置确认请求能直达https://taotoken.net/apireading choices 为空返回结构不是预期格式或模型名写错用 curl 单独验证确认 model 名在通道里可用OAuth / 鉴权失败误用了需要 OAuth 的厂商专属配置统一走 API Key 方式不要混用厂商 SDK 的鉴权404 Not Foundbase-url 多写了/v1配置里只写到https://taotoken.net/apiChatClient 注入失败缺少 starter 或版本不匹配确认依赖是spring-ai-starter-model-openai版本与 Boot 对齐重点说几个。401最常见九成是 Key 没复制全或者环境变量没生效。你可以在启动日志里打印一下System.getenv(TAOTOKEN_API_KEY)的长度确认不是 null。local proxy failed通常是本地开了某些网络工具导致请求走不到目标地址关掉再试。reading choices报错一般是返回体里没有choices字段可能是模型名不对或者通道返回了错误信息用 curl 打一次就能看到原始返回。还有一个容易忽略的点如果你同时引入了多个厂商的 starterSpring AI 可能会创建多个 ChatModel Bean导致注入歧义。解决办法是用Qualifier指定或者只保留一个 starter。OAuth 类报错基本是误用了需要 OAuth 的厂商配置统一走 API Key 就不会遇到。排障的时候记住一个原则先用 curl 验证通道再验证 Spring 配置最后验证业务代码。分层排查比一上来就改 Java 代码高效得多。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的接入示例遇到协议层问题可以对照。6. 把链路记成一条线从 ChatClient 到 RAG 与 Tool Calling跑完一遍之后回头看那些八股会发现它们其实是同一条链路上的不同环节。ChatClient 组织请求Advisor 在调用前后插入 Memory、RAG 和工具能力ChatModel 真正访问模型。模型需要事实时RAG 去 VectorStore 找文档Tool Calling 去业务系统查数据结果经过校验后返回。入库链路是另一条原始文件 → DocumentReader → DocumentTransformer → EmbeddingModel → VectorStore。查询链路是用户提问 → 问题向量化 → 相似度检索 → 加入 Prompt → ChatModel 生成。把这两条链分开讲面试时就不会显得数据是凭空出现的。如果你要长期做编码或 Agent 类任务可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它适合持续调用的场景。想快速验证某个模型的效果直接打开模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一句话就行。Key 管理在控制台 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后给一个实用建议别把这篇当阅读材料把application.yml和 ChatClient Bean 复制到你的项目里跑通一次/chat再加一个 RAG 问题和一个 Tool Calling 问题。能亲手让返回里出现“500元”和“5天”比背十遍定义都管用。链路跑通了八股自然就顺了。