Health-Agent：基于三层 Pipeline 的个人健康管理 AI 助手

Health-Agent 是一个开源的个人健康管理 AI Agent，采用 Triage/Agent Graph/Critic 三层架构，支持语义记忆检索、医学知识库 RAG、联网搜索溯源、结构化问诊流程、健康预警广播和 PDF 健康报告导出。

背景：个人健康管理的数字化困境\n\n在数字化时代，我们的健康信息却呈现出 paradoxical 的状态——一方面，智能手表、健康 App、体检报告产生了海量数据；另一方面，这些信息往往分散在不同平台，难以形成系统性的健康档案。当我们需要就医时，常常记不清上次症状的具体时间、用药历史，更难以发现长期的健康规律。\n\nHealth-Agent 正是为了解决这一问题而设计的。它不仅仅是一个聊天机器人，而是一个完整的个人健康管理系统，通过 AI Agent 技术将健康记录、症状追踪、医学知识查询和预警提醒整合在一个统一的对话界面中。\n\n## 项目架构：三层 Pipeline 设计\n\nHealth-Agent 的核心创新在于其分层处理架构。每条用户消息都会经过严格的三层流水线处理，确保安全性、准确性和合规性：\n\n### L1：Triage Gate（分诊层）\n\n这是整个 Pipeline 的第一道防线。使用 Claude Haiku 4.5 模型进行快速判定（平均响应时间 < 500ms），专门识别紧急医疗情况。当用户描述胸痛、骤停、重度出血等危重症状时，系统会立即短路返回，提示用户拨打 120 急救电话，而不会进入后续的 AI 分析流程。\n\n这种设计体现了医疗 AI 系统最重要的原则——安全优先。在测试中，Triage 层的准确率达到 96.7%（30 条测试用例），能够有效识别绝大多数紧急情况。\n\n### L2：Main Agent Graph（主 Agent 层）\n\n通过分诊层后，消息进入由 Claude Sonnet 4.6 驱动的主 Agent 处理流程。这是一个单节点的 LangGraph 架构，工具循环在节点内部管理（最多 5 轮），决策权始终在同一模型，避免了多节点状态序列化的性能开销。\n\n主 Agent 可以按需调用多种工具：\n\n- search_memory：通过 Mem0 检索用户的历史健康记录，实现症状关联和趋势分析\n- search_rag：从 Qdrant 医学知识库检索药物说明、疾病描述、临床指南\n- web_search：通过 Brave Search API 获取最新医学资讯，回复末尾自动追加可点击的参考来源\n- generate_report：生成结构化健康报告\n\n### L3：Critic Review（质检层）\n\n最后一道关卡是合规质检。Critic Agent 使用 Haiku 模型审查每条回复，防止出现明确诊断、不当用药建议等违规输出。如果检测到问题，会追加补充说明并将案例记入 critic_failures.jsonl，形成负样本用于后续的自学习优化。\n\n实测显示，Critic 层的拦截准确率达到 100%（13 条测试用例，7 违规 + 6 合规），无漏拦或误拦情况。\n\n## 核心技术特性\n\n### 语义记忆与向量检索\n\nHealth-Agent 使用 Mem0 作为向量记忆层，支持语义搜索和自动去重。当用户描述症状时，系统会自动关联历史记录，主动提示相关信息。例如，当用户提到「最近又头痛了」，Agent 会检索并提示「您上次记录头痛是在两周前，当时伴随的症状是...」。\n\n为了优化性能，系统还实现了记忆预热机制——后端启动和前端页面加载时双重触发 Mem0 检索，结果写入 Redis prefetch 缓存，消除冷启动延迟。\n\n### 医学知识库 RAG\n\n系统内置了基于 Qdrant 的医学知识库，使用 BGE-M3 模型同时生成 dense 向量和 sparse 词袋，通过 Qdrant 原生的 RRF（Reciprocal Rank Fusion）融合两路召回结果。这种双路融合策略比单路检索具有更高的准确率，确保检索到的医学知识既相关又全面。\n\n### 联网搜索与来源溯源\n\n对于新药信息、最新研究等时效性强的内容，系统会强制走联网搜索通道。Brave Search API 的返回结果会在回复末尾以可点击链接的形式呈现，确保信息的可追溯性。这种设计解决了大模型「幻觉」问题，让用户可以验证 AI 提供的信息来源。\n\n### Token 级流式输出\n\n使用 LangGraph 的 astream_events(version="v2") 捕获 on_chat_model_stream 事件，实现真正的 token 级流式输出。用户无需等待完整回复生成，字符会逐个实时显示，提供接近真人的对话体验。\n\n### 健康预警广播系统\n\n这是一个独立运行的后台模块。APScheduler 每 6 小时执行一次 alert_monitor.py，抓取药品召回、疫情预警、健康风险提示等信息。通过关键词匹配用户的 Mem0 档案，相关预警会通过 Redis Pub/Sub + SSE 实时推送到用户界面，并使用 7 天哈希去重机制避免重复打扰。\n\n## 实际使用场景\n\nHealth-Agent 支持多种交互模式，适应不同的使用场景：\n\n### 症状记录与关联\n\n用户可以直接用自然语言描述症状，Agent 会自动提取关键信息并记录。更重要的是，它会主动关联历史记录，帮助用户发现潜在的健康模式。例如，系统可能会提示：「您在过去三个月中记录了 5 次类似症状，都发生在工作压力大的时候。」\n\n### 结构化问诊模式\n\n发送 /consult 命令可以启动结构化问诊流程。Agent 会逐步收集完整的症状信息（发病时间、持续时间、伴随症状、既往病史等），然后交由主 Agent 进行综合分析。这种模式特别适合在就医前整理症状描述，提高与医生沟通的效率。\n\n### 个性化健康建议\n\n发送 /recommend 命令，系统会基于用户的历史健康记录生成个性化的作息、饮食、运动和就医建议。这些建议不是通用的健康提示，而是真正基于用户个人数据定制的。\n\n### 健康报告导出\n\n用户可以一键生成结构化的 PDF 健康报告。系统使用 Playwright（headless Chromium）进行渲染，完整支持中文，报告包含症状历史、用药记录、健康趋势分析和建议。这在转诊、保险理赔或长期健康管理中非常实用。\n\n## 技术栈与部署\n\nHealth-Agent 采用了现代化的全栈技术方案：\n\n| 层级 | 技术选型 |\n|------|----------|\n| Agent 框架 | LangGraph（单节点 Orchestrator + 工具循环）|\n| 大语言模型 | Claude Sonnet 4.6（主 Agent）/ Claude Haiku 4.5（Triage、Critic）|\n| 向量记忆 | Mem0（语义搜索 + 去重）|\n| 医学知识库 | Qdrant + BGE-M3（dense + sparse 双路 RRF 融合）|\n| 联网搜索 | Brave Search API |\n| 后端框架 | FastAPI + APScheduler |\n| 前端框架 | Next.js 14 + Tailwind CSS |\n| 会话缓存 | Redis（会话历史 / 记忆预热 / 健康预警 Pub/Sub）|\n| PDF 渲染 | Playwright（headless Chromium）|\n| 容器编排 | Docker Compose |\n\n项目提供了完整的 Docker Compose 配置，只需几条命令即可完成部署：\n\nbash\ngit clone https://github.com/Jennifer-00/health-agent.git\ncd health-agent\ncp .env.example .env\n# 编辑 .env 填入 API Key\ndocker compose up -d\n\n\n## 性能实测数据\n\n根据 measure.py 及 logs/agent_trace.jsonl 的实测结果（本地环境）：\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Triage 准确率 | 96.7%（29/30） | 30 条测试用例 |\n| Triage 延迟 avg / p95 | 1470ms / 2533ms | Haiku 快速判定 |\n| Critic 拦截准确率 | 100%（13/13） | 无漏拦/误拦 |\n| Critic 延迟 avg / p95 | 1487ms / 2638ms | 串行追加在主链路后 |\n| 端到端延迟（预热后） | 9.6s – 14.5s | n=3 |\n\n这些数据表明，三层 Pipeline 的设计在确保安全性的同时，保持了可接受的响应延迟。\n\n## 设计亮点与优化细节\n\nHealth-Agent 在工程实现上有几个值得注意的设计选择：\n\n来源链接确定性追加：web_search 结果的 URL 在工具循环内用正则提取，存入 AgentState.web_sources，在 Critic Review 之前以 SSE delta 推送给前端。这种设计不依赖 LLM 自行引用来源，确保了溯源的可靠性。\n\nCritic 自学习闭环：违规案例持久化为 JSONL 格式，下次对话启动时自动读取最近 3 条注入 system prompt 作为负样本反例，让主 Agent 主动规避同类错误。\n\nXML 结构化 Prompt：System prompt 采用 XML 标签划分角色、工具、触发条件与禁止行为，利用 Claude 对 XML 的边界感知提升指令遵循准确性。\n\nPrompt Cache：system prompt 使用 Anthropic 的 cache_control: ephemeral，在重复对话中减少 token 消耗。\n\n## 总结与展望\n\nHealth-Agent 展示了 AI Agent 在个人健康管理领域的巨大潜力。它不仅仅是一个问答工具，而是一个具备记忆、推理、检索、预警能力的完整系统。通过三层 Pipeline 的架构设计，它在安全性、准确性和用户体验之间取得了良好的平衡。\n\n对于关注健康科技、AI 医疗应用的开发者和研究者来说，Health-Agent 提供了一个优秀的参考实现。它的模块化设计也意味着可以方便地替换组件（如使用其他 LLM 提供商、接入不同的医学知识库），适应不同的部署场景。\n\n项目采用 MIT 许可证开源，社区欢迎贡献新功能，如检查报告图片 OCR 解析、多用户隔离的 RAG 知识库、健康预警前端弹窗 UI 等。

背景：个人健康管理的数字化困境\n\n在数字化时代，我们的健康信息却呈现出 paradoxical 的状态——一方面，智能手表、健康 App、体检报告产生了海量数据；另一方面，这些信息往往分散在不同平台，难以形成系统性的健康档案。当我们需要就医时，常常记不清上次症状的具体时间、用药历史，更难以发现长期的健康规律。\n\nHealth-Agent 正是为了解决这一问题而设计的。它不仅仅是一个聊天机器人，而是一个完整的个人健康管理系统，通过 AI Agent 技术将健康记录、症状追踪、医学知识查询和预警提醒整合在一个统一的对话界面中。\n\n项目架构：三层 Pipeline 设计\n\nHealth-Agent 的核心创新在于其分层处理架构。每条用户消息都会经过严格的三层流水线处理，确保安全性、准确性和合规性：\n\nL1：Triage Gate（分诊层）\n\n这是整个 Pipeline 的第一道防线。使用 Claude Haiku 4.5 模型进行快速判定（平均响应时间 < 500ms），专门识别紧急医疗情况。当用户描述胸痛、骤停、重度出血等危重症状时，系统会立即短路返回，提示用户拨打 120 急救电话，而不会进入后续的 AI 分析流程。\n\n这种设计体现了医疗 AI 系统最重要的原则——安全优先。在测试中，Triage 层的准确率达到 96.7%（30 条测试用例），能够有效识别绝大多数紧急情况。\n\nL2：Main Agent Graph（主 Agent 层）\n\n通过分诊层后，消息进入由 Claude Sonnet 4.6 驱动的主 Agent 处理流程。这是一个单节点的 LangGraph 架构，工具循环在节点内部管理（最多 5 轮），决策权始终在同一模型，避免了多节点状态序列化的性能开销。\n\n主 Agent 可以按需调用多种工具：\n\n- search_memory：通过 Mem0 检索用户的历史健康记录，实现症状关联和趋势分析\n- search_rag：从 Qdrant 医学知识库检索药物说明、疾病描述、临床指南\n- web_search：通过 Brave Search API 获取最新医学资讯，回复末尾自动追加可点击的参考来源\n- generate_report：生成结构化健康报告\n\nL3：Critic Review（质检层）\n\n最后一道关卡是合规质检。Critic Agent 使用 Haiku 模型审查每条回复，防止出现明确诊断、不当用药建议等违规输出。如果检测到问题，会追加补充说明并将案例记入 critic_failures.jsonl，形成负样本用于后续的自学习优化。\n\n实测显示，Critic 层的拦截准确率达到 100%（13 条测试用例，7 违规 + 6 合规），无漏拦或误拦情况。\n\n核心技术特性\n\n语义记忆与向量检索\n\nHealth-Agent 使用 Mem0 作为向量记忆层，支持语义搜索和自动去重。当用户描述症状时，系统会自动关联历史记录，主动提示相关信息。例如，当用户提到「最近又头痛了」，Agent 会检索并提示「您上次记录头痛是在两周前，当时伴随的症状是...」。\n\n为了优化性能，系统还实现了记忆预热机制——后端启动和前端页面加载时双重触发 Mem0 检索，结果写入 Redis prefetch 缓存，消除冷启动延迟。\n\n医学知识库 RAG\n\n系统内置了基于 Qdrant 的医学知识库，使用 BGE-M3 模型同时生成 dense 向量和 sparse 词袋，通过 Qdrant 原生的 RRF（Reciprocal Rank Fusion）融合两路召回结果。这种双路融合策略比单路检索具有更高的准确率，确保检索到的医学知识既相关又全面。\n\n联网搜索与来源溯源\n\n对于新药信息、最新研究等时效性强的内容，系统会强制走联网搜索通道。Brave Search API 的返回结果会在回复末尾以可点击链接的形式呈现，确保信息的可追溯性。这种设计解决了大模型「幻觉」问题，让用户可以验证 AI 提供的信息来源。\n\nToken 级流式输出\n\n使用 LangGraph 的 astream_events(version="v2") 捕获 on_chat_model_stream 事件，实现真正的 token 级流式输出。用户无需等待完整回复生成，字符会逐个实时显示，提供接近真人的对话体验。\n\n健康预警广播系统\n\n这是一个独立运行的后台模块。APScheduler 每 6 小时执行一次 alert_monitor.py，抓取药品召回、疫情预警、健康风险提示等信息。通过关键词匹配用户的 Mem0 档案，相关预警会通过 Redis Pub/Sub + SSE 实时推送到用户界面，并使用 7 天哈希去重机制避免重复打扰。\n\n实际使用场景\n\nHealth-Agent 支持多种交互模式，适应不同的使用场景：\n\n症状记录与关联\n\n用户可以直接用自然语言描述症状，Agent 会自动提取关键信息并记录。更重要的是，它会主动关联历史记录，帮助用户发现潜在的健康模式。例如，系统可能会提示：「您在过去三个月中记录了 5 次类似症状，都发生在工作压力大的时候。」\n\n结构化问诊模式\n\n发送 /consult 命令可以启动结构化问诊流程。Agent 会逐步收集完整的症状信息（发病时间、持续时间、伴随症状、既往病史等），然后交由主 Agent 进行综合分析。这种模式特别适合在就医前整理症状描述，提高与医生沟通的效率。\n\n个性化健康建议\n\n发送 /recommend 命令，系统会基于用户的历史健康记录生成个性化的作息、饮食、运动和就医建议。这些建议不是通用的健康提示，而是真正基于用户个人数据定制的。\n\n健康报告导出\n\n用户可以一键生成结构化的 PDF 健康报告。系统使用 Playwright（headless Chromium）进行渲染，完整支持中文，报告包含症状历史、用药记录、健康趋势分析和建议。这在转诊、保险理赔或长期健康管理中非常实用。\n\n技术栈与部署\n\nHealth-Agent 采用了现代化的全栈技术方案：\n\n| 层级 | 技术选型 |\n|------|----------|\n| Agent 框架 | LangGraph（单节点 Orchestrator + 工具循环）|\n| 大语言模型 | Claude Sonnet 4.6（主 Agent）/ Claude Haiku 4.5（Triage、Critic）|\n| 向量记忆 | Mem0（语义搜索 + 去重）|\n| 医学知识库 | Qdrant + BGE-M3（dense + sparse 双路 RRF 融合）|\n| 联网搜索 | Brave Search API |\n| 后端框架 | FastAPI + APScheduler |\n| 前端框架 | Next.js 14 + Tailwind CSS |\n| 会话缓存 | Redis（会话历史 / 记忆预热 / 健康预警 Pub/Sub）|\n| PDF 渲染 | Playwright（headless Chromium）|\n| 容器编排 | Docker Compose |\n\n项目提供了完整的 Docker Compose 配置，只需几条命令即可完成部署：\n\nbash\ngit clone https://github.com/Jennifer-00/health-agent.git\ncd health-agent\ncp .env.example .env\n编辑 .env 填入 API Key\ndocker compose up -d\n\n\n性能实测数据\n\n根据 measure.py 及 logs/agent_trace.jsonl 的实测结果（本地环境）：\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Triage 准确率 | 96.7%（29/30） | 30 条测试用例 |\n| Triage 延迟 avg / p95 | 1470ms / 2533ms | Haiku 快速判定 |\n| Critic 拦截准确率 | 100%（13/13） | 无漏拦/误拦 |\n| Critic 延迟 avg / p95 | 1487ms / 2638ms | 串行追加在主链路后 |\n| 端到端延迟（预热后） | 9.6s – 14.5s | n=3 |\n\n这些数据表明，三层 Pipeline 的设计在确保安全性的同时，保持了可接受的响应延迟。\n\n设计亮点与优化细节\n\nHealth-Agent 在工程实现上有几个值得注意的设计选择：\n\n来源链接确定性追加：web_search 结果的 URL 在工具循环内用正则提取，存入 AgentState.web_sources，在 Critic Review 之前以 SSE delta 推送给前端。这种设计不依赖 LLM 自行引用来源，确保了溯源的可靠性。\n\nCritic 自学习闭环：违规案例持久化为 JSONL 格式，下次对话启动时自动读取最近 3 条注入 system prompt 作为负样本反例，让主 Agent 主动规避同类错误。\n\nXML 结构化 Prompt：System prompt 采用 XML 标签划分角色、工具、触发条件与禁止行为，利用 Claude 对 XML 的边界感知提升指令遵循准确性。\n\nPrompt Cache：system prompt 使用 Anthropic 的 cache_control: ephemeral，在重复对话中减少 token 消耗。\n\n总结与展望\n\nHealth-Agent 展示了 AI Agent 在个人健康管理领域的巨大潜力。它不仅仅是一个问答工具，而是一个具备记忆、推理、检索、预警能力的完整系统。通过三层 Pipeline 的架构设计，它在安全性、准确性和用户体验之间取得了良好的平衡。\n\n对于关注健康科技、AI 医疗应用的开发者和研究者来说，Health-Agent 提供了一个优秀的参考实现。它的模块化设计也意味着可以方便地替换组件（如使用其他 LLM 提供商、接入不同的医学知识库），适应不同的部署场景。\n\n项目采用 MIT 许可证开源，社区欢迎贡献新功能，如检查报告图片 OCR 解析、多用户隔离的 RAG 知识库、健康预警前端弹窗 UI 等。