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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 了解整体能力，然后进入控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 创建 API Key。创建完成后，在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-ollama-spring-boot-starter</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-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 Flux<String> 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 Flux<String> 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=用一句话解释SpringBoot&route=cloud"预期返回一段中文回答。如果返回 401，说明 Key 没读到，检查环境变量TAOTOKEN_API_KEY是否在当前 shell 生效。如果返回 404，检查base-url是否误加了/v1或末尾斜杠，正确写法就是https://taotoken.net/api。
再测本地路线：
curl "http://localhost:8080/ai/chat?prompt=你好&route=local"这条要求 Ollama 正在运行且模型已 pull。如果报连接拒绝，先ollama serve确认服务在 11434 端口。如果报模型不存在，用ollama list核对名称，yml 里的model必须和 list 输出完全一致，包括 tag。
流式接口验证：
curl -N "http://localhost:8080/ai/stream?prompt=写三行诗&route=cloud"-N关闭缓冲，你能看到内容一段段刷出来。如果一次性全返回，说明中间有缓冲层，检查是否被网关或 IDE 的代理干扰。
成功的结果是：云端和本地两条路线都能返回内容，流式接口有逐段输出。到这一步，你的 SpringBoot 项目已经具备双路线 AI 对话能力。
6. 本篇常见错排查：从 401 到流式截断
实际落地时，下面几个错误出现频率最高，我按现象、原因、解决三段式列出来。
401 Unauthorized：Key 没读到或格式不对。检查环境变量名是否和 yml 里的${TAOTOKEN_API_KEY}一致，注意大小写。另外确认 Key 没有多余空格，复制时容易带上换行。
404 Not Found：base-url 写错。TaoToken 通道地址是https://taotoken.net/api，不要自己拼/v1/chat/completions，Spring 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
如果你更想先在网页里直接试模型效果，不写代码，可以用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，快速对比不同模型的回答质量，再决定项目里默认用哪个。
接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各语言的最小示例，遇到参数不确定时优先查它。ClaudeCodeAnthropic 相关配置参考 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
最后给一个实用技巧：把route参数做成配置项而不是硬编码，比如ai.default-route=cloud，本地断网时自动降级到 Ollama。这样你的 SpringBoot 服务在云端通道抖动时依然可用，用户体验不会断崖式下跌。
