1. SpringBoot 接入 AI 的真实痛点为什么 Key 管理比写代码更麻烦很多同学第一次给 SpringBoot 项目加 AI 能力时卡住的地方往往不是代码而是 Key 和通道。你手上可能同时有 OpenAI 的 Key、本地 Ollama 的地址甚至还有几个不同平台的 Key散落在 application.yml、环境变量、测试类里。项目一多改一个模型就要翻半天配置团队协作时更是互相覆盖。这篇就围绕一个真实场景展开你有一个 SpringBoot 3.2 项目想同时支持「云端 OpenAI 兼容接口」和「本地 Ollama」两条路线并且希望用一套统一的 Key 和 API 通道来管理避免每个环境都改配置。我会给出 application.yml 骨架、config.toml 骨架、TaoToken 统一 Key 的配置示例以及启动后能直接验证的对话接口。适合谁看有 SpringBoot 基础、想快速跑通 AI 对话接口的后端开发正在纠结 Spring AI 和手写 HTTP 调用怎么选的人以及被多平台 Key 管理折磨过的团队。读完后你能得到一个可复制的最小工程两条路线都能跑切换只改配置。先说结论Spring AI 负责「统一调用抽象」TaoToken 负责「统一 Key 与通道」Ollama 负责「本地兜底」。三者组合起来才是从 0 到 1 最省心的路径。2. 前置准备TaoToken 统一 Key 与 Spring AI 版本对齐在动手写代码前先把两个基础件准备好否则后面一定踩坑。第一是环境。Spring Boot 3.2 和 Spring AI 1.0 GA 都要求 JDK 17 起步Maven 3.8 或 Gradle 8。如果你还在 Spring Boot 2.x要么升级要么把 Spring AI 降到 0.8.x 系列但接口差异较大本文以 1.0 GA 为准。第二是 AI 资源。这里就是 TaoToken 出场的地方。它的定位是统一 Key 与 API 通道你只需要在 TaoToken 控制台创建一个 Key就能通过同一个 base-url 访问多种模型不用为每个平台单独维护一套鉴权逻辑。对 SpringBoot 项目来说这意味着 application.yml 里只有一组api-key和base-url切换模型只改model字段。具体操作路径先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力然后进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建 API Key。创建完成后在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以随时查看和轮换。API 通道地址统一用 https://taotoken.net/api注意这个地址不带任何查询参数。注意Key 不要硬编码进 Git 仓库。推荐用环境变量TAOTOKEN_API_KEY注入本地开发用 IDE 的 EnvFile 插件线上用配置中心或 KMS。Ollama 这边本地装好后默认监听http://localhost:11434先ollama pull qwen2.5:7b或你喜欢的模型确认ollama list能看到。这样两条路线的资源就齐了。3. 可复制配置application.yml 与 config.toml 骨架这一节是全文的核心直接给可复制的骨架。先看 Maven 依赖Spring AI 1.0 GA 的 starter 命名已经稳定dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId version1.0.0/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency两个 starter 可以同时存在Spring AI 会分别装配OpenAiChatModel和OllamaChatModel互不冲突。接下来是 application.yml注意 OpenAI 这条路线我们指向 TaoToken 的通道server: port: 8080 spring: ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: model: gpt-4o-mini options: temperature: 0.7 ollama: base-url: http://localhost:11434 chat: model: qwen2.5:7b options: temperature: 0.7这里的关键点base-url用 TaoToken 的 API 通道api-key从环境变量读。这样你的 SpringBoot 项目不需要知道底层是哪个厂商Spring AI 的 OpenAI 客户端会按 OpenAI 兼容协议发请求TaoToken 负责路由。如果你用的是某些需要 config.toml 的工具链比如本地 CLI 或某些 Agent 框架骨架可以这样写保持和 yml 一致的语义[openai] api_key ${TAOTOKEN_API_KEY} base_url https://taotoken.net/api model gpt-4o-mini [ollama] base_url http://localhost:11434 model qwen2.5:7b两条配置的字段名刻意保持一致方便你在不同工具间迁移。实测下来这种「一份 Key、两个 base-url」的结构比每个平台单独维护配置要清爽得多。4. 两条路线落地Spring AI 统一调用与 Ollama 本地兜底配置好了代码其实很短。Spring AI 1.0 的ChatClient是统一入口无论底层是 OpenAI 兼容通道还是 Ollama调用方式一致。先写一个 Service注入两个ChatModel用ChatClient包装Service public class AiService { private final ChatClient openAiClient; private final ChatClient ollamaClient; public AiService(OpenAiChatModel openAiChatModel, OllamaChatModel ollamaChatModel) { this.openAiClient ChatClient.builder(openAiChatModel).build(); this.ollamaClient ChatClient.builder(ollamaChatModel).build(); } public String chat(String prompt, String route) { ChatClient client local.equals(route) ? ollamaClient : openAiClient; return client.prompt() .user(prompt) .call() .content(); } public FluxString stream(String prompt, String route) { ChatClient client local.equals(route) ? ollamaClient : openAiClient; return client.prompt() .user(prompt) .stream() .content(); } }Controller 暴露两个接口一个同步一个流式用route参数切换路线RestController public class AiController { private final AiService aiService; public AiController(AiService aiService) { this.aiService aiService; } GetMapping(/ai/chat) public String chat(RequestParam String prompt, RequestParam(defaultValue cloud) String route) { return aiService.chat(prompt, route); } GetMapping(value /ai/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString stream(RequestParam String prompt, RequestParam(defaultValue cloud) String route) { return aiService.stream(prompt, route); } }这段代码的价值在于业务层完全不关心底层是 TaoToken 通道还是本地 Ollama切换只靠一个参数。如果你后续要加更多模型只要 TaoToken 通道支持改model字段即可Java 代码一行不动。提示流式接口返回text/event-stream浏览器直接访问会看到逐段输出前端用 EventSource 接收即可实现打字机效果。5. 验证请求启动后如何确认两条路线都通了代码写完启动项目用 curl 做最小验证。先测云端路线也就是走 TaoToken 通道curl http://localhost:8080/ai/chat?prompt用一句话解释SpringBootroutecloud预期返回一段中文回答。如果返回 401说明 Key 没读到检查环境变量TAOTOKEN_API_KEY是否在当前 shell 生效。如果返回 404检查base-url是否误加了/v1或末尾斜杠正确写法就是https://taotoken.net/api。再测本地路线curl http://localhost:8080/ai/chat?prompt你好routelocal这条要求 Ollama 正在运行且模型已 pull。如果报连接拒绝先ollama serve确认服务在 11434 端口。如果报模型不存在用ollama list核对名称yml 里的model必须和 list 输出完全一致包括 tag。流式接口验证curl -N http://localhost:8080/ai/stream?prompt写三行诗routecloud-N关闭缓冲你能看到内容一段段刷出来。如果一次性全返回说明中间有缓冲层检查是否被网关或 IDE 的代理干扰。成功的结果是云端和本地两条路线都能返回内容流式接口有逐段输出。到这一步你的 SpringBoot 项目已经具备双路线 AI 对话能力。6. 本篇常见错排查从 401 到流式截断实际落地时下面几个错误出现频率最高我按现象、原因、解决三段式列出来。401 UnauthorizedKey 没读到或格式不对。检查环境变量名是否和 yml 里的${TAOTOKEN_API_KEY}一致注意大小写。另外确认 Key 没有多余空格复制时容易带上换行。404 Not Foundbase-url 写错。TaoToken 通道地址是https://taotoken.net/api不要自己拼/v1/chat/completionsSpring AI 的 OpenAI 客户端会自动补路径。多一个斜杠或少一个都可能 404。Connection refused本地路线Ollama 没启动或者端口不是 11434。先curl http://localhost:11434/api/tags确认服务活着再检查 yml。模型不存在yml 里的 model 名和实际不一致。Ollama 的模型名带 tag比如qwen2.5:7b少写:7b就会报错。流式响应被截断常见于中间有反向代理或 Nginx 缓冲。开发阶段先用直连端口验证上线时在 Nginx 加proxy_buffering off;和proxy_cache off;。依赖冲突Spring Boot 3.2 用的是 Jakarta EE 10如果你项目里还混着旧版javax.*的 HTTP 客户端可能启动失败。用mvn dependency:tree排查把冲突的旧 SDK 排除掉。上下文超限长对话时输入 token 超过模型窗口表现为回答突然变短或报错。控制单次 prompt 长度或者做摘要压缩别把整段历史无脑塞进去。这些坑我基本都踩过一遍核心经验是先保证最小请求能通再往上叠业务逻辑。别一上来就写复杂 Agent先用 curl 把通道验证通。7. 下一步从对话接口到长期编码与 Agent跑通对话接口只是起点。如果你打算把 AI 能力长期用在编码辅助、代码审查、Agent 工作流上建议关注 TaoToken 的 Coding Plan它针对长期编码场景做了通道和额度优化比按次调用更适合高频使用。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你更想先在网页里直接试模型效果不写代码可以用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速对比不同模型的回答质量再决定项目里默认用哪个。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言的最小示例遇到参数不确定时优先查它。ClaudeCodeAnthropic 相关配置参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个实用技巧把route参数做成配置项而不是硬编码比如ai.default-routecloud本地断网时自动降级到 Ollama。这样你的 SpringBoot 服务在云端通道抖动时依然可用用户体验不会断崖式下跌。