已完结｜DeepSeek+SpringAI踩坑，AI家庭医生业务落地经验

当DeepSeek的推理能力遇上Spring AI的工程化框架，Java开发者终于不用再手写HTTP调用、硬编码JSON请求体、为每个大模型厂商写一套适配代码了。Spring AI官方于2025年5月发布1.0正式版，首周下载量突破15万次，GitHub星标超过3.2万，支持20余种模型架构。然而，把课程里的Demo跑通只需一下午，把AI家庭医生业务稳稳落地，可能需要几周甚至一个月。

本文不重复教程目录，只聚焦AI家庭医生业务落地途中，那些"课程不讲、但线上必踩"的工程化深坑。

坑位一：调用DeepSeek-reasoner做工具调用，第二轮对话必崩

这是目前踩得最深、最隐蔽的坑。在AI家庭医生场景中，DeepSeek需要调用多个工具——查询患者健康档案、检索药品说明书、匹配慢病管理指南等。第一轮工具调用一切正常，但Spring AI自动发起的第二轮请求直接报400错误，提示"Missing reasoning_content field in the assistant message"。

根本原因在于，DeepSeek的"思考模式"（Thinking Mode）要求：当模型发起过工具调用后，对话历史中的assistant消息必须包含reasoning_content字段，否则API拒绝处理。而Spring AI 1.1.0版本的DeepSeekChatModel在重建历史消息时，传入的reasoning_content始终为null。换言之，框架没有跟上模型厂商的协议更新节奏。

破局思路：短期内，可尝试将Spring AI升级到1.1.0-SNAPSHOT版本，或通过显式构建Prompt对象绕过快捷方法的序列化bug。长期来看，务必关注Spring AI Release Notes中关于DeepSeek适配器的修复说明，这个坑在2026年5月仍然存在讨论。

坑位二：角色字段大小写问题，调用直接422

另一个"优雅但致命"的问题：Spring AI的DeepSeekChatModel在某些调用路径下，会将角色（role）字段序列化为大写的"USER"和"ASSISTANT"，而DeepSeek API严格遵守OpenAI兼容规范，只接受小写的"user"、"assistant"、"system"。于是你的请求直接返回422，连重试的机会都没有。

破局思路：在业务代码中统一使用Prompt对象构造调用，而非直接调用model.call(new UserMessage("..."))这种快捷方法——后者在1.0.1版本中依然存在序列化问题。对于2026年已完结的训练营课程，建议优先使用Spring AI 1.1.x版本，并在pom.xml中锁定明确的release版本而非snapshot快照，避免一夜之间"莫名其妙崩了"的惊吓。

坑位三：把Spring AI当"万能瑞士军刀"，却忘了企业级可观测性

课程中的Demo跑在本地，日志打满控制台就完事了。但在真实的AI家庭医生平台中，每一次DeepSeek调用都关联着患者的健康咨询、用药提醒、慢病随访。线上出问题时，你需要知道：是哪个患者的哪次请求出了问题？DeepSeek返回的Token消耗是多少？调用链路中哪一步超时了？

Spring AI 2.0版本切换底层SDK后（Anthropic SDK和OpenAI SDK），HTTP层面的指标、链路追踪和上下文传播已经不复存在——框架不再自动提供调用DeepSeek API的观测数据。

破局思路：不要依赖框架的"内置观测"。在AI家庭医生业务落地时，自行封装一个带监控的调用层：记录每次请求的TraceId、Token消耗、响应时长，将数据接入Prometheus或接入ELK日志系统。同时，利用Spring AI的@Tools注解为工具方法添加详细的自然语言描述，帮助DeepSeek更精准地判断何时调用哪个工具。

结语：AI落地的底气在工程，不在Demo

AI家庭医生不是"接入DeepSeek就完事了"——石家庄和新疆等地已经在推进"数字家医"和基层AI辅助诊疗，其背后是一整套覆盖签约、建档、慢病管理、用药审核的全链条服务体系。DeepSeek只负责"思考"和"生成"，而Spring AI负责"连接"。当协议变更、角色大小写、可观测性缺失这些工程暗礁浮出水面时，决定业务能不能跑下去的，不是你有多懂模型，而是你有多懂生产环境的容错、降级和兜底。

学完课程只是拿到了地图，真正的旅程从踩进第一个坑才刚开始。