HealthcareAgent：基于Python和Streamlit的医疗保健智能体设计

简介这份基于Python与Streamlit实现的HealthcareAgent医疗保健智能体源码包定位为医疗健康领域的可运行Demo适合智能体应用开发者、医疗信息化学习者及数据科学爱好者借鉴。压缩包内共18个文件大小仅2.77MB主要包含两个Python入口程序、requirements依赖清单、README项目说明、TXT安装文本、12张PNG运行效果图以及IMG图像文件类型覆盖源码、说明与界面预览便于对照查看。已有76人浏览学习适合希望快速掌握Streamlit交互式Web开发并基于Lagent框架编排工具调用的人群。项目核心涵盖智能问答、CVD慢病管理、Lagent智能体集成等功能通过源码可学习多模块结构设计、自然语言处理与图表化展示的衔接方式效果截图和说明文档能帮助理解界面布局、运行流程与二次开发所需的配置点。对于心血管疾病风险管理场景可在此基础上调整提示词与数据接入方式适配家庭健康管理需求也能直接作为课程设计、毕业设计或医疗智能体产品原型的起步模板。 最近在梳理自己写过的几个智能体项目刚好有个医疗保健方向的案例被朋友问得最多也就是标题里的这个HealthcareAgent。它是个基于 Python 和 Streamlit 搭起来的医疗保健智能体源码打包成 zip 分享给了不少人反应比预期好干脆把完整设计思路、踩坑记录和运行方式整理成文给想自己做智能体但又不知道从哪下手的朋友一条可以抄的近路。这个项目能做什么先一句话说清它把“患者症状录入—科室建议—常见病科普—用药/健康提醒”这几个环节串成了一个能跑起来、能看界面、能二次开发的智能体应用。你输入一段身体不舒服的描述它会做意图识别匹配知识库给出科室推荐和自护建议如果你是开发者这还是一个非常适合练手的 Streamlit 工程模板。适合谁来读我觉得有三类人一是刚开始学 Python 和 Streamlit、想做点具体东西的初学者二是手头有医疗健康类数据想快速出个 Demo 去给业务方看的开发三是纯粹对“智能体怎么组成”感兴趣、想拆源码的人。这篇文章不做医学层面的专业背书重点讲技术实现、产品逻辑和工程细节。1. 项目整体思路拆解1.1 为什么选 Python 和 Streamlit选 Python 是没什么争议的智能体要做文本处理、规则匹配、后续接大模型调用Python 的生态是最顺手的。所有 NLP 预处理、关键词匹配、JSON 数据管理全部可以在一个语言体系内完成不需要额外引入别的技术栈。Streamlit 可能有些朋友不熟简单说它是一个“纯 Python 写前端界面”的框架。你不用写 HTML、CSS、JS只要按它的规则在 Python 脚本里调用组件就能得到一个可交互的 Web 页面。这个项目里所有界面、按钮、输入框、结果显示全部是用 Streamlit 完成的代码量比传统 Web 开发少一个数量级。Streamlit 有几个特点特别适合医疗保健这个场景。第一热加载机制改完代码保存浏览器自动刷新对于反复调界面非常友好第二会话状态管理它提供了st.session_state可以轻松在多次交互之间保留患者输入历史、诊断记录这是智能体应用最需要的第三部署简单本地跑起来就是一个本地服务甚至可以打包给非技术背景的人体验。1.2 智能体结构怎么设计做智能体最忌讳一上来就堆功能。我最初把 HealthcareAgent 拆成四个模块这个划分决定了下游所有开发流程交互层负责接收用户输入做基础校验和意图识别。推理层基于规则引擎和知识库匹配输出科室建议和健康建议不依赖外部大模型时也能独立工作。数据层管理症状库、科室库、药物提醒数据采用 JSON 格式存储。管理界面层提供历史记录查询、数据标注入口、健康提醒设置面板。这个四层结构不是拍脑袋想的它参考了常规的中台化设计思路把交互和推理解耦。好处非常明确如果你以后想把规则引擎替换成大模型接口只需要改推理层其他几层完全不用动如果你只想换界面风格改交互层就行推理逻辑和数据不动。从智能体的定义上看它不是一个简单的“问答机器人”而是一个“有输入、有处理、有反馈、有记录”的完整闭环。它不依赖外部大模型也能响应用户这在很多医疗场景下是必需的因为网络不可用、数据隐私、响应速度都是实际问题。这不是落后反而是医疗场景的理性选择。2. 环境准备与项目启动2.1 Python 环境搭建的几个注意点这个项目要求 Python 3.9 以上我推荐 3.10 或 3.11。之前有人在 3.7 环境跑Streamlit 新版已经不支持那么老的版本了代码会直接报语法错误。安装 Python 的时候有一点特别值得提醒注意安装过程中务必勾选Add Python to PATH否则后续使用pip安装依赖、命令行运行streamlit命令时系统会提示找不到命令这是我被问过最多的问题。安装完成后建议创建虚拟环境不要直接装到全局环境里区别很大。虚拟环境可以把项目的依赖隔离避免不同项目之间的包版本冲突尤其是 Streamlit 更新频繁global 环境很容易被其他项目搞乱。我一般这么操作python -m venv healthcare_envWindows 下激活虚拟环境healthcare_env\Scripts\activateMac / Linux 下激活虚拟环境source healthcare_env/bin/activate激活之后命令行提示符前面会多一个(healthcare_env)前缀说明已经进入虚拟环境了。这时候再安装依赖就不会和系统全局环境产生冲突。2.2 源码目录结构解读解压 zip 之后目录结构大概是这样的HealthcareAgent/ ├── app.py # Streamlit 主入口文件 ├── requirements.txt # 项目依赖列表 ├── data/ │ ├── symptoms.json # 症状-科室映射库 │ ├── department.json # 科室信息库 │ └── medicine_alerts.json # 药物提醒规则 ├── core/ │ ├── matcher.py # 症状匹配引擎 │ ├── intent.py # 意图识别模块 │ └── advisor.py # 健康建议生成器 ├── assets/ │ └── logo.png # 界面 logo └── README.md # 项目说明文档app.py是主入口Streamlit 启动时会加载它core目录放的是核心逻辑和界面层分离data目录放的是 JSON 数据文件所有症状和科室信息都集中在这里。这样设计的好处是后续你想扩充知识库只需要改 JSON 文件不需要动代码。2.3 依赖安装没有你想的复杂在项目根目录下用 pip 安装依赖pip install -r requirements.txtrequirements.txt里主要包含这些库streamlit1.36.0 pandas2.2.2 scikit-learn1.4.2这里我把scikit-learn加进来了但它的用途可能和你预期的不一样。在初始版本里它用于做文本向量化和相似度匹配改进后的版本保留它作为可选的匹配增强依赖——如果安装失败系统会自动降级到基于关键词的匹配模式不影响主流程。这个设计就是考虑到实际部署环境的差异不让一个库的安装失败影响整个项目运行。启动项目在项目根目录下执行streamlit run app.py浏览器会自动打开http://localhost:8501看到界面就说明环境完全没问题了。3. 核心功能模块的实现细节3.1 症状输入与意图识别怎么做用户输入一句“我头疼、发热还咳嗽”系统怎么知道这是“感冒”还是“肺炎”这个项目用的是基于多模式匹配的意图分类方法。core/intent.py里有一个IntentClassifier类它会对输入文本做几层处理第一层文本清洗。去掉标点、多余空格把全角字符转半角避免因为标点不同导致匹配失败。第二层同义词扩展。例如“头疼”和“头痛”是同义词系统会在匹配前做归一化处理。第三层权重评分。每个症状词带有一个基础权重比如“胸痛”比“咳嗽”指向性更强所以它在判断时的分值更高最终综合所有命中词的得分决定走哪个意图分支。在早期版本里意图识别走的是纯规则引擎效果其实足够用。后来我尝试用 TF-IDF 向量化加余弦相似度作为辅助召回率有所提升但代价是引入了模型体积所以最终保留了双通道方案——规则优先、向量辅助。如果向量通道因为缺少库不可用系统自动走规则通道不会崩。3.2 应急知识库如何构建医疗保健智能体能不能给用户带来实际价值知识库的设计比算法更重要。我没有去网上抓一堆数据盲目堆砌而是按照“由专业公开资料整理的结构化要点 免责提示”的思路把知识库做成了 JSON 格式的结构化数据。data/department.json里存了 36 个科室信息包括科室名称、常见症状、就诊时机提示。每条记录都有三个字段{ id: cardiology, name: 心血管内科, keywords: [胸痛, 心悸, 心慌, 胸闷], advice: 出现持续性胸痛尤其是伴随出汗、恶心时应立即前往医院。 }知识库的增删改主要在数据层做即使没有编程基础也能通过编辑 JSON 文件来维护知识库。这种设计让 HealthcareAgent 不是写死的硬编码而是可持续维护的工程产品。这里有件事必须说明这个项目的定位是健康咨询辅助不是医疗诊断工具。它的建议字段必须包含“如果症状严重或持续不缓解请及时就医”这类引导语句。这不是免责条款的敷衍而是医疗场景产品的基本伦理。3.3 用药提醒与健康记录管理这可能是用户反馈里最惊喜的功能。最初我只做了症状到科室的推荐后来有朋友说如果能记录历史症状、做用药提醒就更好了于是增加了健康记录和提醒功能。用药提醒模块的数据结构是一个简单的时间规则列表{ medicine_name: 维生素D, time: [08:00, 20:00], frequency: 每天, notes: 饭后服用 }界面层会在主面板的侧边栏显示“今日提醒”当前时间点在提醒时间的前后 15 分钟内会高亮显示。这个功能看起来小但涉及一个有意思的技术点Streamlit 的页面不是常驻进程每次交互都会重新执行脚本所以不能用常规的阻塞式定时器。我采用的是“启动时计算 基于时间的动态刷新”方案页面每次刷新时读取当前时间比对提醒规则再做渲染这样既简单又可靠。健康记录管理用的是st.session_state它可以在页面重载时保留数据。但如果关掉浏览器记录就没了。要不要接数据库我建议根据实际需要来本地演示和入门学习用 session_state 就足够了如果要上线多用户使用再迁移到 SQLite 或 MySQL 不迟。3.4 对话界面与多轮交互的实现很多人以为 Streamlit 做不出对话感强的界面其实不然。Streamlit 1.36 之后加强了对话组件支持我用st.chat_input和st.chat_message两个 API 完成了对话界面的搭建。代码不长但效果很自然with st.chat_message(user): st.write(user_input) with st.chat_message(assistant): st.write(response_text)多轮交互依赖会话列表。每一次对话都会追加到st.session_state.messages里刷新之后整个对话记录还在就像正常的聊天应用一样。在最初的版本里没有维护消息列表导致每次交互只反馈单条结果用户无法回溯之前的建议体验差很多。加上消息列表之后整个智能体的“完整感”立刻上来了。4. 运行调试与常见问题排查4.1 Streamlit 常见报错速查我在分享源码之后收到最多的不是“这个功能怎么实现”而是“为什么我跑不起来”。很大一部分问题出在环境层面下面几个是典型情况我整理成一个速查表方便排查报错信息常见原因解决方法streamlit: command not foundPython 未加入 PATH或虚拟环境未激活重新安装 Python 时勾选 “Add to PATH”激活虚拟环境后再执行ModuleNotFoundError: No module named streamlit依赖未安装或安装在另一个 Python 环境重新执行pip install -r requirements.txt确认当前在正确环境Missing module: sklearnscikit-learn 未安装安装scikit-learn如果网络受限可删除相关调用代码系统自动进入降级匹配模式Port 8501 is already in use8501 端口被占用换端口streamlit run app.py --server.port 8502FileNotFoundError: data/symptoms.json启动目录不对确保在项目根目录执行streamlit run app.py不要进入子目录再运行这张表说实话值不少钱因为这些问题每一个我都自己踩过。4.2 排查思路比解决更重要分享一个通用的排查思路走这个流程基本能解决八成问题先看控制台输出Streamlit 启动时会在终端打印详细的日志错误信息会直接告诉你是哪一行代码出了问题再确认当前工作目录pwdWindows 用cd不带参数看一下你在不在项目根目录确认依赖版本pip list里看关键包的版本最后检查 JSON 文件格式如果你的知识库文件不小心多了一个逗号或者少了括号Python 导入时就会直接报错。另外有一个很隐蔽的坑JSON 文件编码问题。如果你用 Windows 平台自带的记事本编辑过 JSON 文件很可能会被保存成 GBK 编码而 Python 默认读取的是 UTF-8结果就是在导入阶段报编码错误。我建议统一用 VSCode 编辑所有.json文件并在右下角确认编码是 UTF-8。4.3 分享几个调试小技巧调试 Streamlit 应用有个非常爽的模式在app.py里加几个st.write()输出调试信息页面会实时展示变量内容。你不需要像调 Python 命令行程序那样用 print直接用界面上的组件反馈就行。我在做症状匹配调试的时候会把每个候选科室的匹配得分用st.expander折叠展示点击“查看诊断依据”就能看到详细的匹配过程和权重得分这才让“智能体”的结果不至于变成黑盒。另一个技巧是利用st.cache_data装饰器缓存数据加载过程。如果不加缓存每次页面交互都会重新读取 JSON 文件本地跑感觉不出来但部署到服务器上就会拖慢响应。加上缓存之后数据只在首次加载时读一次后续交互直接使用缓存结果实测响应速度提升明显。5. 从 Demo 到产品的扩展路径5.1 把规则引擎升级为大模型接口这个项目目前可以独立运行但如果你想让它更“智能”一个很自然的扩展方向就是接入大模型接口。具体做法不复杂在core/advisor.py里把生成建议的逻辑改成调用大模型接口把用户的症状历史和知识库中的匹配结果作为上下文传入让模型生成更口语化的回答。双通道设计在这里非常有价值——大模型离线时系统自动走规则引擎大模型在线时走大模型生成。这种设计保证了服务不中断后端即便模型挂了也能给用户一个像样的响应。医疗场景对可用性的要求很高这一点不能妥协。5.2 从单机脚本到多用户部署当前版本的 session_state 方案只在单次会话内有效不适合多用户部署。如果要做成真正可用的 Web 应用需要把健康记录持久化到 SQLite甚至 MySQL 里再按用户维度做数据隔离。Streamlit 并不适合直接暴露在公网环境常规做法是在前面加一层反向代理处理认证和 HTTPS。这一步不是必须的但真正上线时一定要考虑。我建议先用sqlite3把数据持久化搞定再考虑认证和代理一步步来。5.3 后续迭代方向参考我自己的计划里还有几个方向供你参考多轮诊断模型让智能体可以在回答后追问用户更多细节而不是只根据初次输入就给结论。这种交互模式更接近真实问诊。知识库后台管理目前在 JSON 文件里直接改数据还是比较 geek后续打算增加一个管理面板让不懂代码的人也能维护知识库。报告生成根据用户一段时间的健康记录自动生成图表报告用上streamlit的绘图组件会很直观。6. 实际使用心得与最后的技巧分享这个项目从最初两百行的脚本到现在一个五脏俱全的源码包全程都是一个普通开发者用业余时间做的。最大的感受是Streamlit 让开发者能极度专注在业务逻辑上不用花时间写前端页面也不需要知道 JavaScript就能快速得到一个有模有样、可交互、可部署的应用。最后分享一个很多人没注意到的技巧把 Streamlit 项目包装成桌面应用。用pyinstaller把app.py打包成可执行文件再把 Streamlit 的启动命令嵌进去双击就能运行不需要用户去安装 Python、执行命令。我把这个思路用在了给一个诊所做的内部演示上对方不需要任何技术背景双击就能打开智能体页面效果比我自己演示好得多。打包命令很简单但需要注意把静态资源文件一并带上否则启动时会找不到 logo 和数据库文件。如果你只是入门从跑通这个 HealthcareAgent 源码开始把它当成一份可以自由修改的骨架按自己的业务需求塞数据、改逻辑会比重新造一个轮子快得多。本文还有配套的精品资源点击获取