获课：xingkeit.top/18093/

避开 SpringAI 集成大坑，AI 家庭医生应用开发问题汇总

用一个周末把 Spring AI 的 Demo 跑通，再用两个月把它打磨成一个可用的 AI 家庭医生应用——这个过程让我对“集成”这两个字有了全新的理解。Demo 和生产的距离，远不是“加几行配置”能填平的。这篇把开发 AI 家庭医生过程中踩过的 Spring AI 集成坑做个汇总，希望对正在这条路上的同行有所帮助。

坑一：环境依赖不兼容，入门就卡三天

很多 Java 开发者的 Spring AI 之路，不是死在代码上，而是死在环境上。依赖下不动、版本对不上、启动就报错，一个上午就没了。

血的教训：版本铁律一定要背牢。 JDK 必须 17 及以上（低于 17 直接报错），Spring Boot 必须 3.2 及以上，Spring AI 用 1.0.0 及以上稳定版，别碰 SNAPSHOT。Maven 镜像配置不对也会导致依赖下载失败——90% 的环境问题出在仓库配置上，不是框架本身的问题。

对于 AI 家庭医生这种有数据合规要求的场景，如果用本地部署的模型，Ollama 是门槛最低的选择，配置一行 spring.ai.ollama.base-url=http://localhost:11434 就能接上。如果不想折腾代理，国内用户直接用 Spring AI Alibaba 或智谱 starter 更省心。

坑二：版本升级后的 API 破坏性变更，防不胜防

Spring AI 还在快速迭代期，版本之间的 API 变更常常是“破坏性”的。我们最痛苦的经历是从 1.0.0-M6 升级到 2.0.0-M7 时，API Key 认证机制被强制要求，导致整个自定义认证体系崩了。

具体来说： 旧版本可以用 NoopApiKey 绕过 Authorization 头，用 Cookie/Session 做认证；但 2.0.0-M7 强制要求 API Key，不传就启动失败，传了又会在请求里强行塞一个 Authorization: Bearer xxx 头，自定义 AI 服务器直接返回 403。这个坑在 GitHub 上已经被大量开发者反馈，2.0.0-M8 部分修复但仍有遗留问题。

在 MCP（Model Context Protocol）集成上也有类似的问题：新版 Spring AI 的 MCP Server 依赖 spring-ai-starter-mcp-server-webflux，如果项目中同时存在 spring-boot-starter-web（Tomcat 容器），服务能启动但 MCP Service 根本起不来——因为 MCP 用的是 Netty，Tomcat 和 Netty 冲突了。排查时控制台还没有明确报错，全靠猜。

坑三：结果不稳定，根本原因在约束不够

AI 家庭医生最怕的就是“同一症状昨天给的建议和今天不一样”——用户会直接质疑专业性。但 Spring AI 集成后结果不稳定是常态，根本原因不是模型突然变差，而是约束条件还不够稳定。

排查时重点关注三个维度：

Prompt 设计——很多系统 Prompt 堆了太多要求：要专业、要友好、要严格格式、要主动调工具，反而让模型顾此失彼。更好的做法是把 Prompt 收敛到三件事：明确角色和任务范围、明确什么时候必须调用工具、明确输出格式和禁止项。越到工程场景，Prompt 越需要约束性，而不是文学性。

模型参数——temperature 设太高会导致输出飘忽不定。业务场景下 0.7 是个比较稳的“甜点值”，太高不可控。如果目标是稳定输出，temperature 和 top_p 都应该更保守一些。

工具描述清晰度——在 Spring AI 里用 @Tool 注解注册工具时，description 字段的清晰程度直接影响模型是否调用正确。模糊的名字如“queryData”对模型帮助不大，换成“根据用户症状描述查询相关疾病知识”会稳定得多。

坑四：医疗场景的特殊性，通用模型天然水土不服

这不算 Spring AI 的坑，但对 AI 家庭医生应用来说是绕不开的底线问题。王小川最近在清华的论坛上明确说过：医疗有三条刚性要求——专业循证、主动问诊、低幻觉强可靠，市面上通用大模型一条都不达标。

在 Spring AI 里接入通用模型做医疗问答，最大的风险是幻觉。模型会把碎片化症状拼凑成一个看似完整的诊断，用户信了，后果可能是灾难性的。北大的研究团队也指出，AI 家庭医生的两大核心挑战正是“大模型幻觉问题”和“生理信号理解问题”。

在这个场景下，RAG 不是可选项，是必选项。 必须把医学指南、诊疗规范、药品说明书建立成可追溯的知识库，让模型的每一条建议都能溯源到权威依据。Spring AI 的向量存储和 RAG 支持就是为了解决这个问题——但前提是，你得有质量够硬的医学知识库。

写在最后

Spring AI 的定位其实很清晰：它就是 Spring Data 之于数据库——你不需要懂大模型底层，只需要会注入 ChatClient。它把不同 LLM、向量数据库抽象成统一 API，让 Java 开发者用熟悉的方式接入 AI。

但在 AI 家庭医生这种对准确性、稳定性、合规性要求极高的场景下，框架只是起点，真正的工程在框架之外。Prompt 设计、参数调优、工具描述、RAG 知识库质量、版本升级策略——每一个环节都可能成为坑。比踩坑更重要的，是建立一套“版本升级前先读 Release Notes”“参数调整前先做对比测试”“医疗类回答必须有引用溯源”的工程纪律。

这条路没有捷径，但踩过的坑，都是之后少翻的车。