手把手教你使用 Spring AI 开发 AI 智能体调用 DeepSeek 本地模型：TaoToken 统一 Key 配置实战

1. 为什么要在 Spring AI 智能体里同时接本地 DeepSeek 和远端模型如果你正在用 Spring AI 做 AI 智能体大概率会遇到一个很现实的问题本地 Ollama 跑的 DeepSeek 蒸馏版适合做私有数据、离线推理和低成本试验但一旦智能体需要更强的推理能力、更长的上下文或者要临时切到云端大模型做对比Key 和 API 通道就开始分散了。本地模型走http://localhost:11434远端模型走另一套 base-url 和 api-key代码里到处是 if-else配置文件越写越乱。这篇就聚焦这个工程落地问题用 Spring AI 搭一个 AI 智能体本地 DeepSeek 通过 Ollama 提供远端通道统一走 TaoToken 的 OpenAI 兼容接口用一套统一 Key 管理多模型调用。目标是一次配置完成智能体多模型调用链路打通后面切换模型只改一个 model 名称不用动业务代码。适合谁看已经写过 Spring Boot、想用 Spring AI 快速搭智能体、手里有本地 DeepSeek 或想接远端模型做兜底的 Java 开发者。下面从依赖、配置、代码到验证一步步来配置骨架可以直接复制。2. TaoToken 前置统一 Key 与通道准备TaoToken 在这里的角色是「远端模型的统一入口」。它提供 OpenAI 兼容的 API 格式也就是说 Spring AI 里用spring-ai-openai-spring-boot-starter就能直接对接不需要为每个远端模型单独写适配层。本地 DeepSeek 继续走 Ollama远端走 TaoToken两边在 Spring AI 里都抽象成 ChatModel智能体只认接口不认来源。你需要先拿到一个 API Key。登录官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进入控制台后创建 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完在 API Keys 页面复制页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 的基础地址是 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数直接作为 base-url 用。注意Key 只显示一次复制后放到环境变量或配置中心不要硬编码进 Git 仓库。本地调试可以用.env或 IDE 的运行配置注入。如果你还没决定远端用哪个模型可以先在模型对话页面试一下返回格式和延迟地址 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。确认通道通了再写进 Spring AI 配置能省掉很多「到底是代码问题还是 Key 问题」的排查时间。3. 可复制配置application.yml 里的双通道骨架先看依赖。本地 DeepSeek 用 Ollama starter远端用 OpenAI starter两个可以共存。Spring AI 的版本建议用 1.0.0-M5 及以上Ollama 和 OpenAI 的 starter 都在同一套 BOM 下管理。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency然后是application.yml的核心骨架。这里的关键点是Ollama 和 OpenAI 各自有独立的配置前缀互不干扰智能体通过注入不同的 ChatModel 来选择通道。spring: ai: ollama: base-url: http://localhost:11434 chat: model: deepseek-r1:1.5b options: temperature: 0.7 openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: model: deepseek-chat options: temperature: 0.7几个参数说明。spring.ai.ollama.chat.model填你本地ollama list里看到的模型名比如deepseek-r1:1.5b或deepseek-r1:7b。spring.ai.openai.base-url固定为https://taotoken.net/api不要带结尾斜杠。api-key用环境变量注入启动前设置export TAOTOKEN_API_KEY你的Key。spring.ai.openai.chat.model填远端模型名具体可用名称在接入文档里查地址 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你想让智能体默认走本地、远端作为兜底可以在配置里加一个自定义开关比如agent.default-channel: local然后在 Bean 装配时根据这个值决定注入哪个 ChatModel。这样切换通道不用改代码只改配置。4. 智能体代码注入双 ChatModel 并按场景路由Spring AI 会自动装配OllamaChatModel和OpenAiChatModel两个 Bean。你可以用Qualifier区分也可以包一层路由。下面是一个最小可用的智能体 Controller演示本地和远端两条链路。RestController RequestMapping(/agent) public class AgentController { private final ChatClient localClient; private final ChatClient remoteClient; public AgentController(OllamaChatModel ollamaChatModel, OpenAiChatModel openAiChatModel) { this.localClient ChatClient.builder(ollamaChatModel).build(); this.remoteClient ChatClient.builder(openAiChatModel).build(); } GetMapping(/local) public String local(RequestParam String input) { return localClient.prompt().user(input).call().content(); } GetMapping(/remote) public String remote(RequestParam String input) { return remoteClient.prompt().user(input).call().content(); } }这段代码里localClient走 Ollama 的 DeepSeekremoteClient走 TaoToken 的远端通道。智能体的业务逻辑可以在这里加一层判断简单问答走本地复杂推理或本地模型不可用时走远端。比如加一个GetMapping(/smart)先试本地捕获异常后 fallback 到远端。GetMapping(/smart) public String smart(RequestParam String input) { try { return localClient.prompt().user(input).call().content(); } catch (Exception e) { return remoteClient.prompt().user(input).call().content(); } }实测下来这种 fallback 模式在本地 Ollama 没启动或者模型加载慢的时候特别有用智能体不会直接报错给用户。注意异常捕获不要吞掉日志至少log.warn一下方便排查是本地挂了还是远端 Key 失效。5. 验证请求与成功结果CC Switch 切换本地与远端配置写完先确认本地 Ollama 在跑。终端执行ollama list能看到deepseek-r1:1.5b就说明模型就绪。然后启动 Spring Boot 应用默认端口 8080。验证本地通道curl http://localhost:8080/agent/local?input用一句话解释什么是Spring AI预期返回一段中文解释说明 Ollama 通道通了。如果返回连接拒绝检查spring.ai.ollama.base-url和 Ollama 进程。验证远端通道curl http://localhost:8080/agent/remote?input用一句话解释什么是Spring AI预期返回远端模型的回答。如果返回 401说明TAOTOKEN_API_KEY没注入或 Key 无效如果返回 404检查 base-url 是不是写成了带路径的形式。接下来是 CC Switch 的切换验证。CC Switch 在这里的作用是帮你管理不同通道的配置切换避免手动改 yml。你可以把它理解成一个配置切换器本地开发时指向 Ollama需要远端能力时切到 TaoToken 通道。操作上在 CC Switch 里配置两组 profile一组对应本地http://localhost:11434一组对应https://taotoken.net/api切换后重启应用或触发配置刷新。验证切换是否生效最直接的方法是打/agent/smart接口然后停掉 Ollama 进程再打一次。第一次应该走本地成功第二次本地失败后 fallback 到远端成功。两次都返回内容说明双通道链路和 fallback 逻辑都通了。如果你更习惯用图形界面验证模型返回也可以直接在模型对话页面发同样的 prompt对比本地和远端的输出差异地址 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。这样能快速判断是模型能力差异还是接入层问题。6. 本篇常见错排查报错一Connection refused: localhost/11434。Ollama 没启动或者端口不是默认的 11434。执行ollama serve手动启动确认spring.ai.ollama.base-url和实际端口一致。报错二远端返回 401 Unauthorized。Key 没注入或复制时带了空格。检查环境变量echo $TAOTOKEN_API_KEY确认没有多余字符。如果用的是 IDE 运行配置确认环境变量传进去了。报错三远端返回 404 Not Found。base-url 写错了。正确写法是https://taotoken.net/api不要加/v1或结尾斜杠。Spring AI 的 OpenAI starter 会自动拼接/chat/completions。报错四本地模型返回乱码或截断。1.5B 蒸馏版能力有限长 prompt 容易截断。换 7B 或 8B 模型或者把options.num-predict调大。显存不够就减小上下文长度。报错五两个 ChatModel Bean 冲突。如果启动时报NoUniqueBeanDefinitionException说明注入时没区分。用Qualifier(ollamaChatModel)和Qualifier(openAiChatModel)明确指定或者像上面那样在构造方法参数里用具体类型。报错六切换通道后配置没生效。Spring Boot 的配置刷新需要RefreshScope或重启。CC Switch 切换后如果没生效先重启应用确认再排查是不是 profile 没激活。排障时如果怀疑是接入层问题优先看接入文档里的错误码说明地址 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Key 相关的问题去 API Keys 页面重新生成一个对比测试地址 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。7. 长期编码与 Agent 场景的通道选择如果你只是偶尔跑一下智能体 demo上面的双通道配置够用了。但如果你在长期做编码类 Agent比如让智能体持续读代码、改代码、跑测试那通道的稳定性和成本就要单独考虑。本地 DeepSeek 适合高频、低成本的代码补全和私有仓库问答远端通道适合复杂重构和跨文件推理。这种长期编码场景可以了解一下 Coding Plan地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它针对的就是持续编码类调用配合 Spring AI 的智能体循环能把本地和远端的能力按任务类型分流。比如单元测试生成走本地架构级重构走远端Key 还是同一套配置不用改。如果你用的是 Claude Code 这类编码工具做 Agent 开发Anthropic 兼容通道的配置入口在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 思路和 Spring AI 一样统一 Key按场景切通道。最后给一个实用建议把本地和远端的模型名都抽到配置里不要写死在代码。智能体的路由逻辑只判断「任务复杂度」和「本地可用性」不判断具体模型名。这样以后换模型、加通道只改 yml不动 Java 代码。配置骨架上面已经给了直接复制改 Key 就能跑。