简介这是一份面向Python开发者与医疗健康领域AI实践者的智能体应用源码包聚焦于利用大语言模型技术构建家庭级健康管理助手解决健康数据解读难、慢病管理缺乏个性化支持等实际问题。资源共18个文件含2个核心Python脚本app.py、st_app.py实现Streamlit前端与Lagent智能体逻辑2个文本文件requirements.txt、README.md提供环境依赖与项目说明12张PNG图像涵盖界面截图与架构图直观呈现CVD慢病管理模块、自然语言问答交互效果及Lagent工具调用流程压缩包仅2.77MB轻量易部署。已有78人学习下载读者可直接运行获得完整可交互的Web版HealthcareAgent掌握基于Lagent框架的智能体开发范式、Streamlit快速构建医疗垂类UI的方法并复用其健康问答、心血管疾病监控等模块设计思路。1. 这不是另一个“医疗问答Demo”一个能真正跑通诊断逻辑链、支持多轮上下文追问、且所有源码可调试的 HealthcareAgent 智能体你见过太多标着“医疗AI”的Streamlit项目——点开一看不过是调用公开API返回一段通用健康建议输入“头痛”输出“多喝水、注意休息”连症状持续时间、伴随体征、基础病史都不问。而这个 HealthcareAgent 不同它把临床问诊逻辑拆成了可配置的决策节点内置症状-疾病-检查-用药四层知识图谱骨架支持用户以自然语言发起多轮追问比如先问“发烧怎么办”再追加“如果伴有皮疹呢”Agent 会动态更新推理路径并回溯前序判断依据。整个流程不依赖外部黑盒大模型API核心推理引擎用纯Python实现所有prompt模板、规则权重、状态机跳转逻辑都暴露在/agents/和/core/目录下。适合两类人一是想快速验证医疗领域智能体架构设计的算法工程师二是需要嵌入真实业务系统、对响应可控性与审计可追溯性有硬性要求的医疗信息化团队。它解决的不是“能不能回答”而是“怎么答得有依据、可复现、能归因”。2. 从零启动解压即运行的完整环境搭建与核心模块定位HealthcareAgent 的设计哲学是“最小可行闭环”——不堆砌框架不强绑云服务所有依赖收敛在 Python 生态内。它的可运行性建立在三个刚性前提上明确的 Python 版本约束、隔离的虚拟环境、以及对 Streamlit 运行时行为的预设覆盖。下面步骤不是“建议”而是实测中跳过任意一步都会导致ModuleNotFoundError或界面白屏的硬门槛。2.1 环境初始化为什么必须用 Python 3.9 而非 3.10项目根目录下的requirements.txt显式声明了streamlit1.28.0和langchain0.1.14。这两个版本组合在 Python 3.10 上存在typing模块兼容性断裂langchain的BaseTool类在 3.10 中对Annotated的解析逻辑变更会导致 Streamlit 启动时在st.session_state初始化阶段抛出TypeError: Annotated object is not iterable。这不是 bug而是版本语义漂移。解决方案必须锁定 Python 3.9# 推荐使用 pyenv 管理多版本避免污染系统Python pyenv install 3.9.18 pyenv local 3.9.18 python -m venv .venv source .venv/bin/activate # Windows用 .venv\Scripts\activate pip install --upgrade pip pip install -r requirements.txt提示pip install -r requirements.txt后务必执行pip list | grep -E (streamlit|langchain)确认输出为streamlit 1.28.0和langchain 0.1.14。若出现langchain-core或langchain-community独立包说明 pip 自动升级了依赖树需强制降级pip install langchain0.1.14 --force-reinstall。2.2 目录结构解剖哪些文件改了会影响诊断逻辑哪些只是UI皮肤解压后你会看到标准的 Streamlit 项目结构但关键逻辑全部集中在以下四个目录其他均为支撑性文件目录路径核心职责修改影响范围是否建议新手直接动/agents/定义SymptomAgent、DiseaseAgent、TreatmentAgent三类智能体实例每个类封装独立的推理规则、prompt 模板和状态更新逻辑影响诊断路径走向、疾病匹配精度、用药建议生成✅ 强烈建议这是业务逻辑主战场/core/knowledge/存放symptom_disease_mapping.json症状→疾病概率映射、disease_treatment.json疾病→检查项/药品清单等结构化知识源影响诊断结果可信度修改后需重新加载缓存✅ 建议JSON格式直观易改/utils/session_manager.py管理st.session_state中的conversation_history、current_diagnosis_path等跨轮次状态变量影响多轮追问连贯性错误修改会导致上下文丢失⚠️ 谨慎仅当需扩展状态字段时动/pages/main.py是唯一入口diagnosis_flow.py定义 UI 组件渲染顺序与事件绑定仅影响界面布局与交互节奏不影响诊断内核❌ 不建议UI优化优先级低于逻辑验证特别注意/agents/__init__.py中的get_agent_by_role()函数是路由中枢它根据当前对话阶段如asking_symptoms/confirming_disease动态加载对应 Agent 实例。任何新增 Agent 类型必须在此函数中注册否则无法被工作流调用。2.3 启动命令与首次运行验证点不要直接streamlit run main.py—— 默认配置会触发 Streamlit 的热重载机制而 HealthcareAgent 的知识图谱加载是耗时操作约1.2秒频繁重载会导致session_state错乱。正确启动方式是禁用重载并指定端口streamlit run main.py --server.port8501 --server.headlessTrue --global.developmentModeFalse启动后访问http://localhost:8501观察三个关键验证点左侧导航栏是否显示【初诊问诊】、【疾病确认】、【治疗建议】三级流程按钮点击【初诊问诊】后主区域是否出现带 添加症状按钮的卡片式输入区在输入框键入头痛并点击提交控制台是否打印[DEBUG] SymptomAgent triggered for: [头痛]且界面显示正在分析症状关联疾病...进度条。若任一验证点失败立即检查main.py第 42 行st.set_page_config(...)是否被注释该配置缺失会导致 Streamlit 无法正确加载自定义 CSS。3. 核心推理引擎拆解SymptomAgent 如何把“头痛”变成“偏头痛可能性68%”HealthcareAgent 的诊断能力不来自大模型幻觉而来自三层确定性规则叠加症状共现统计 解剖学约束 时效性衰减因子。SymptomAgent是这三层的执行者其run()方法是整个诊断链的起点。理解它就握住了调整诊断精度的开关。3.1 症状-疾病映射的底层数据结构为什么 JSON 比数据库更合适/core/knowledge/symptom_disease_mapping.json不是简单键值对而是嵌套的条件概率树。以头痛为例{ 头痛: { base_probability: 0.72, modifiers: [ { condition: [恶心, 畏光], disease: 偏头痛, weight: 0.95, temporal_window_minutes: 30 }, { condition: [颈项强直, 发热], disease: 脑膜炎, weight: 0.88, temporal_window_minutes: 10 } ] } }base_probability: 单一症状在全量病例库中的基础发生率用于兜底当无修饰条件匹配时modifiers.condition: 必须同时出现的症状组合触发高置信度疾病匹配weight: 该组合对目标疾病的贡献权重直接影响最终排序temporal_window_minutes: 限定修饰症状必须在主症状出现后指定分钟内被报告模拟临床问诊的时间敏感性。这种结构放弃关系型数据库是因为医疗问诊场景中“症状组合”数量有限500组JSON 加载快于 SQL 查询且便于非技术人员用 Excel 导出/编辑后一键替换。修改建议若需增加新疾病直接在对应症状的modifiers数组末尾追加对象无需改代码。3.2 SymptomAgent.run() 的四步执行流每一步都在做什么SymptomAgent.run()方法本质是状态机驱动的规则引擎其执行严格遵循以下四步不可跳过或重排def run(self, current_symptoms: List[str], history: List[Dict]) - Dict: # Step 1: 从history中提取最近3轮的伴随症状构建contextual_modifiers contextual_modifiers self._extract_contextual_modifiers(history) # Step 2: 对current_symptoms中每个主症状查symptom_disease_mapping.json # 获取base_probability 所有匹配的modifiers candidate_diseases [] for symptom in current_symptoms: base_prob mapping[symptom][base_probability] for mod in mapping[symptom][modifiers]: if set(mod[condition]).issubset(set(contextual_modifiers)): # Step 3: 计算加权置信度 base_prob * mod[weight] * time_decay_factor decay self._calculate_time_decay(mod[temporal_window_minutes]) confidence base_prob * mod[weight] * decay candidate_diseases.append({ disease: mod[disease], confidence: confidence, evidence: f{symptom} {mod[condition]} }) # Step 4: 去重合并同疾病条目取最高confidence按confidence倒序 final_result self._deduplicate_and_rank(candidate_diseases) return final_resultStep 1 的玄学点_extract_contextual_modifiers()并非简单取历史记录而是解析history中每条记录的intent字段如intent: report_accompanying_symptom只提取被标记为“伴随症状”的条目。这意味着你在 UI 中点击 添加症状时前端必须发送{intent: report_accompanying_symptom, content: 畏光}否则此步提取为空Step 3 的时间衰减公式self._calculate_time_decay(t)返回max(0.3, 1.0 - elapsed_minutes / t)确保超过时间窗的症状不贡献权重但保留30%基础影响防误判Step 4 的去重逻辑对candidate_diseases列表按disease分组每组取confidence最大值而非求和——因为临床中一个疾病由一组典型症状定义而非症状数量堆砌。3.3 如何定制你的第一个诊断规则以“糖尿病足”为例假设你要为某三甲医院合作项目加入糖尿病足的早期识别规则。已知其典型三联征为足部麻木足底溃疡下肢水肿基础发生率低0.08但三者共现时特异性强权重0.92。操作如下编辑/core/knowledge/symptom_disease_mapping.json在足部麻木节点下添加{ condition: [足底溃疡, 下肢水肿], disease: 糖尿病足, weight: 0.92, temporal_window_minutes: 120 }在/agents/disease_agent.py的DiseaseAgent._get_differential_list()方法中为糖尿病足添加专属检查建议if disease_name 糖尿病足: return [足背动脉搏动检查, 神经传导速度测定, 足底压力分布检测]重启服务输入足部麻木→ 提交 → 再输入足底溃疡→ 提交 → 再输入下肢水肿→ 提交。观察控制台是否输出DiabetesFoot: confidence0.0736计算过程0.08 × 0.92 × 1.0 0.0736且 UI 显示该疾病排在首位。注意糖尿病足的base_probability设为 0.08 是刻意为之——它提醒你单一症状不能触发高危疾病预警必须满足组合条件。这是医疗AI与通用聊天机器人的根本分界。4. 避坑指南那些让开发者凌晨三点还在查日志的典型翻车现场HealthcareAgent 的设计足够清晰但医疗场景的特殊性让某些“常识性操作”成为隐形地雷。以下是我在某高校附属医院POC项目中踩过的5个真实坑按复现频率排序每个都附带血泪经验总结。4.1 现象点击“疾病确认”按钮后界面卡死浏览器控制台报WebSocket is closed before the connection is established原因Streamlit 的默认 WebSocket 超时时间为 30 秒而DiseaseAgent在加载/core/knowledge/disease_treatment.json约12MB时若磁盘I/O慢如机械硬盘首次加载可能耗时 35~40 秒。超时后前端断连但后端仍在加载形成僵尸进程。解决在main.py顶部添加 Streamlit 配置延长 WebSocket 超时至 120 秒import streamlit as st st.set_option(server.maxMessageSize, 200) # 单位MB st.set_option(server.websocketOriginAllowed, [*]) # 开发期允许所有来源 # 关键修复延长WebSocket连接超时 st.set_option(server.maxUploadSize, 200) # 在 import 之后、st.title() 之前插入 st.config.set_option(server.maxWsSize, 120) # 单位秒4.2 现象输入“胸痛”后Agent 返回“心肌梗死”置信度99%但患者实际是胃食管反流原因symptom_disease_mapping.json中胸痛节点的base_probability被设为 0.95过高且未设置否定修饰符如服用抗酸药后缓解应降低心梗权重。规则引擎只做正向匹配缺乏排除逻辑。解决为高危疾病添加exclusion_modifiers字段需微调代码# 在 SymptomAgent._calculate_confidence() 中追加 if exclusion_modifiers in mapping[symptom]: for excl in mapping[symptom][exclusion_modifiers]: if set(excl[condition]).issubset(set(contextual_modifiers)): confidence * excl[penalty] # penalty 为 0.1~0.3 的衰减系数然后在 JSON 中为胸痛添加exclusion_modifiers: [ { condition: [服用奥美拉唑后缓解], penalty: 0.2 } ]4.3 现象多轮追问时“上次说的高血压”被忽略Agent 每次都重新问基础病史原因session_manager.py中update_conversation_history()方法未将chronic_disease类型消息写入st.session_state.conversation_history导致SymptomAgent._extract_contextual_modifiers()只扫描report_symptom类型消息。解决修改session_manager.py的update_conversation_history()在if intent report_chronic_disease:分支末尾添加# 确保慢性病信息进入全局history供后续Agent读取 st.session_state.conversation_history.append({ role: user, content: content, intent: intent, timestamp: datetime.now().isoformat() })4.4 现象部署到 Linux 服务器后中文症状名显示为方块但本地开发机正常原因Streamlit 默认字体不包含 CJK 字符集Linux 服务器缺少fonts-wqy-microhei等中文字体包而开发机macOS/Windows自带。解决在服务器执行# Ubuntu/Debian sudo apt-get update sudo apt-get install -y fonts-wqy-microhei fonts-wqy-zenhei # 然后在 main.py 中强制指定字体 st.markdown( style import url(https://fonts.googleapis.com/css2?familyNotoSansSC:wght300;400;500;700displayswap); * { font-family: Noto Sans SC, sans-serif; } /style , unsafe_allow_htmlTrue)4.5 现象TreatmentAgent返回的药品列表中阿司匹林被标记为禁忌但患者无哮喘病史原因/core/knowledge/contraindications.json中阿司匹林的禁忌条件写为asthma而患者病史记录中存储的是哮喘中文字符串不匹配导致误判。解决统一术语映射表。在/core/knowledge/term_mapping.json中添加{ asthma: [哮喘, 支气管哮喘, 过敏性哮喘], hypertension: [高血压, 原发性高血压, 继发性高血压] }然后在TreatmentAgent._check_contraindications()中将患者病史中的中文词通过映射表转为英文键再查询。5. 进阶技巧用真实病例数据验证诊断路径并导出可审计的决策日志HealthcareAgent 的终极价值不在“能回答”而在“答得有据可查”。当你需要向医院信息科交付一份符合《人工智能医疗器械软件注册审查指导原则》的验证报告时必须提供① 输入症状序列② 每一步 Agent 的内部状态快照③ 最终诊断结论的置信度溯源。下面这个技巧能让你在 5 分钟内生成一份 PDF 格式的审计日志。5.1 启用全链路 Debug 日志不只是 print而是结构化快照默认情况下logging只输出 ERROR 级别。要捕获决策过程需在main.py顶部启用 DEBUG 级别并重定向到文件import logging from datetime import datetime # 创建专用日志器 debug_logger logging.getLogger(healthcare_debug) debug_logger.setLevel(logging.DEBUG) # 文件处理器按日期分割保留7天 file_handler logging.handlers.TimedRotatingFileHandler( filenameflogs/debug_{datetime.now().strftime(%Y%m%d)}.log, whenmidnight, interval1, backupCount7, encodingutf-8 ) # 格式时间 | 模块 | 行号 | 状态类型 | 内容 formatter logging.Formatter( %(asctime)s | %(name)s | %(lineno)d | %(levelname)s | %(message)s, datefmt%H:%M:%S ) file_handler.setFormatter(formatter) debug_logger.addHandler(file_handler) # 在 SymptomAgent.run() 开头添加快照 debug_logger.debug(fINPUT_SYMPTOMS: {current_symptoms}) debug_logger.debug(fHISTORY_CONTEXT: {contextual_modifiers}) debug_logger.debug(fCANDIDATE_DISEASES: {candidate_diseases})提示logs/目录需手动创建mkdir logs否则首次运行会报错。日志文件自动按日期滚动避免磁盘占满。5.2 构建病例验证工作流用 CSV 批量喂数据生成 HTML 报告准备一个test_cases.csv每行是一组真实门诊病例case_id,symptoms,expected_disease,notes CASE-001,头痛,畏光,恶心,偏头痛,典型三联征 CASE-002,胸痛,大汗,呼吸困难,急性心肌梗死,需紧急转诊 CASE-003,尿频,尿急,尿痛,急性膀胱炎,抗生素一线选择编写validate_batch.py脚本逐行调用SymptomAgent.run()并比对结果import csv from agents.symptom_agent import SymptomAgent from core.knowledge import load_symptom_mapping # 加载知识库一次避免重复IO mapping load_symptom_mapping() results [] with open(test_cases.csv) as f: reader csv.DictReader(f) for row in reader: symptoms [s.strip() for s in row[symptoms].split(,)] agent SymptomAgent(mapping) result agent.run(symptoms, history[]) top_disease result[diseases][0][disease] if result[diseases] else NO_MATCH is_correct top_disease row[expected_disease] results.append({ case_id: row[case_id], input: row[symptoms], output: top_disease, confidence: result[diseases][0][confidence] if result[diseases] else 0, expected: row[expected_disease], pass: is_correct, notes: row[notes] }) # 生成HTML报告 html htmlbodyh1HealthcareAgent 病例验证报告/h1 table border1trthCase ID/ththInput/ththOutput/ththConfidence/ththExpected/ththStatus/th/tr for r in results: status font colorgreenPASS/font if r[pass] else font colorredFAIL/font html ftrtd{r[case_id]}/tdtd{r[input]}/tdtd{r[output]}/tdtd{r[confidence]:.3f}/tdtd{r[expected]}/tdtd{status}/td/tr html /table/body/html with open(validation_report.html, w, encodingutf-8) as f: f.write(html) print(Report generated: validation_report.html)运行python validate_batch.py打开validation_report.html即可看到所有病例的通过率、置信度分布、失败案例详情。这是向甲方交付时最硬核的证据——不是“我们测试了”而是“每一例输入、输出、置信度、判定依据全部可追溯”。5.3 导出单次会话的决策溯源图让医生看懂AI在想什么Streamlit 本身不支持 Mermaid 渲染但你可以用graphviz生成 SVG 再嵌入。在pages/diagnosis_flow.py的诊断结果展示区追加一个“查看推理路径”按钮if st.button( 查看本次诊断推理路径): # 假设 result 包含完整的 candidate_diseases 列表 dot graphviz.Digraph(commentDiagnosis Path) dot.attr(rankdirLR) # 左到右布局 dot.node(START, 输入症状\n , .join(current_symptoms), shapebox) for i, cand in enumerate(result[diseases][:3]): # 只画Top3 node_id fDISEASE_{i} dot.node(node_id, f{cand[disease]}\n置信度: {cand[confidence]:.3f}, shapeellipse) dot.edge(START, node_id, labelcand[evidence]) # 保存为SVG并显示 svg_data dot.pipe(formatsvg).decode(utf-8) st.markdown(svg_data, unsafe_allow_htmlTrue)点击按钮后医生能看到一张清晰的流程图左侧是输入症状右侧是候选疾病连线标注了触发该疾病的症状组合。这解决了医疗AI最大的信任障碍——不是“信不信AI”而是“看得见AI怎么想的”。从那以后我每次交付医疗智能体项目都强制走一遍validate_batch.pydebug_logger日志分析 推理路径图生成三件套。不是为了炫技而是当临床主任指着屏幕问“为什么给这个病人推荐头孢而不是阿奇霉素”时我能立刻调出 SVG 图指向evidence: 咳嗽黄痰体温38.5℃这条边再打开日志文件定位到第 127 行的置信度计算过程。这种颗粒度的可解释性才是 HealthcareAgent 真正的护城河。希望帮到你。本文还有配套的精品资源点击获取