kennedyraju55/differential-diagnosis-assistant
GitHub: kennedyraju55/differential-diagnosis-assistant
利用本地 Gemma 4 LLM 生成排序鉴别诊断的医疗教育工具，所有数据本地处理保护隐私。
Stars: 0 | Forks: 0
# 🏥 鉴别诊断助手
### AI 驱动的诊断推理
[](https://python.org)
[](https://ollama.com)
[](LICENSE)
[]()
[]()
[]()
[]()
[✨ 功能特性](#-features) · [🚀 快速开始](#-quick-start) · [💻 CLI 参考](#-cli-reference) · [🌐 网页界面](#-web-ui) · [📖 API 参考](#-api-reference) · [🏗️ 架构设计](#️-architecture) · [🔒 HIPAA 合规](#-hipaa-compliance) · [❓ 常见问题](#-faq)
## 📋 概述
一款智能鉴别诊断助手，利用本地 LLM 根据症状、患者病史和检查结果生成排序的鉴别诊断——所有数据都在您的本地机器上私密运行，**患者数据绝不会离开您的系统**。
作为 **Local LLM Projects** 系列项目（第 97/90 号）的一部分，本工具展示了如何在通过本地模型推理维护数据完整性的同时，将 AI 应用于临床教育。
### 为什么选择此项目？
| | 特性 | 描述 |
|---|---------|-------------|
| 🔒 | **100% HIPAA 友好** | 所有患者数据保留在您的机器上——绝无云端上传 |
| 📋 | **排序的鉴别诊断** | AI 生成的鉴别诊断按可能性排序 |
| 🧪 | **检查建议** | 为每个鉴别诊断提供诊断检查建议 |
| ⚖️ | **诊断比较** | 并排比较两个诊断及其鉴别特征 |
| 🔍 | **多系统分析** | 覆盖 8 个身体系统 |
| 💬 | **交互式推理** | 多轮对话以进行迭代诊断推理 |
## ✨ 功能特性
| 功能 | 详情 |
|---------|---------|
| **排序的鉴别诊断** | AI 生成的鉴别诊断按可能性排序，并提供支持/反对证据 |
| **多系统分析** | 覆盖 8 个身体系统：心血管、呼吸、消化、神经、骨骼肌肉、内分泌、感染、精神 |
| **检查建议** | 一线和二线检查建议，以及专科转诊指导 |
| **诊断比较** | 两个诊断的头对头比较，包含鉴别特征和关键检查 |
| **会话追踪** | 追踪所有咨询，包含时间戳、紧急程度和 AI 响应 |
| **紧急程度分诊** | 5 级紧急程度评分（从低到急诊），具有自动关键词检测 |
## 🚀 快速开始
### 前置条件
| 要求 | 版本 | 用途 |
|-------------|---------|---------|
| **Python** | 3.10+ | 运行环境 |
| **Ollama** | 最新版 | 本地 LLM 推理引擎 |
| **Gemma 4** | 最新版 | AI 模型（通过 Ollama 下载）|
### 安装
```
# 1. Clone the repository
git clone https://github.com/kennedyraju55/differential-diagnosis-assistant.git
cd 97-differential-diagnosis-assistant
# 2. Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or
.\venv\Scripts\activate # Windows
# 3. Install dependencies
pip install -r requirements.txt
# 4. Ensure Ollama is running with Gemma 4
ollama pull gemma4
ollama serve
```
### 首次运行
```
# Verify installation
differential-diagnosis --help
# Run your first differential
differential-diagnosis diagnose --symptoms "chest pain radiating to left arm, diaphoresis, shortness of breath" \
--patient-info "55M, HTN, DM2, smoker" \
--exam-findings "BP 160/95, HR 110, diaphoretic"
```
### 预期输出
```
╭─────────────────────────────────────────────────────────────╮
│ ⚠️ MEDICAL DISCLAIMER │
│ This tool is for educational purposes only. │
│ Always consult a qualified healthcare provider. │
╰─────────────────────────────────────────────────────────────╯
📊 Urgency Assessment: 🚨 Emergency
⏳ Generating differential diagnosis with local LLM...
╭─────────────────────────────────────────────────────────────╮
│ 🔍 Differential Diagnosis │
│ │
│ 1. Acute Myocardial Infarction (STEMI) — Most Likely │
│ 2. Unstable Angina / NSTEMI │
│ 3. Aortic Dissection │
│ 4. Pulmonary Embolism │
│ 5. Tension Pneumothorax │
│ │
│ ⚠️ Remember: This is not medical advice. │
╰─────────────────────────────────────────────────────────────╯
```
## 💻 CLI 参考
| 命令 | 描述 |
|---------|-------------|
| `diagnose` | 根据症状生成排序的鉴别诊断 |
| `workup` | 获取特定诊断的检查建议 |
| `compare` | 并排比较两个诊断 |
| `chat` | 交互式多轮诊断推理会话 |
### diagnose
```
differential-diagnosis diagnose \
--symptoms "sudden onset severe headache, worst of life, neck stiffness" \
--patient-info "35F, no significant PMH" \
--exam-findings "photophobia, positive Kernig sign"
```
### workup
```
differential-diagnosis workup --diagnosis "Subarachnoid hemorrhage"
```
### compare
```
differential-diagnosis compare \
--diagnosis1 "Subarachnoid hemorrhage" \
--diagnosis2 "Meningitis" \
--clinical-data "sudden severe headache with neck stiffness and photophobia"
```
### chat
```
differential-diagnosis chat
```
### 全局选项
```
differential-diagnosis --help # Show all commands and options
```
## 🌐 网页界面
本项目包含一个基于 Streamlit 的网页界面，采用专业的深色主题。
```
# Start the web server
streamlit run src/differential_diagnosis/web_ui.py
# Open in browser
# http://localhost:8501
```
| 特性 | 描述 |
|---------|---------|
| **标签页界面** | 独立的鉴别诊断、检查和比较标签页 |
| **症状输入** | 自由文本症状输入，包含患者信息和检查结果 |
| **身体系统筛选** | 身体系统下拉筛选器 |
| **紧急程度评估** | 带进度条的实时紧急程度评分 |
| **会话历史** | 所有咨询的可展开历史记录 |
| **深色主题** | 专业医疗级深色界面 |
## ⚡ REST API
完整的 FastAPI REST API，带有自动生成的 Swagger 文档。
### 启动 API 服务器
```
# Run directly
uvicorn src.differential_diagnosis.api:app --reload --port 8000
# Or with Docker
docker compose up api
```
### API 端点
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/health` | 健康检查 |
| `POST` | `/diagnose` | 生成排序的鉴别诊断 |
| `POST` | `/workup` | 获取检查建议 |
| `POST` | `/compare` | 比较两个诊断 |
| `GET` | `/disclaimer` | 获取医疗免责声明 |
| `GET` | `/docs` | 交互式 Swagger UI |
| `GET` | `/redoc` | ReDoc 文档 |
### 示例请求
#### 生成鉴别诊断
```
curl -X POST http://localhost:8000/diagnose \
-H "Content-Type: application/json" \
-d '{
"symptoms": "chest pain, diaphoresis, shortness of breath",
"patient_info": "55M, HTN, DM2, smoker",
"exam_findings": "BP 160/95, HR 110, diaphoretic, S3 gallop"
}'
```
#### 获取检查建议
```
curl -X POST http://localhost:8000/workup \
-H "Content-Type: application/json" \
-d '{"diagnosis": "Acute myocardial infarction"}'
```
#### 比较两个诊断
```
curl -X POST http://localhost:8000/compare \
-H "Content-Type: application/json" \
-d '{
"diagnosis1": "Pulmonary embolism",
"diagnosis2": "Pneumothorax",
"clinical_data": "sudden dyspnea with pleuritic chest pain"
}'
```
#### 健康检查
```
curl http://localhost:8000/health
```
## 🐳 Docker 部署
使用 Docker 即时运行此项目——无需本地 Python 设置！
### Docker 快速开始
```
# Clone and start
git clone https://github.com/kennedyraju55/differential-diagnosis-assistant.git
cd differential-diagnosis-assistant
docker compose up
# Access the web UI
open http://localhost:8501
# Access the API
open http://localhost:8000/docs
```
### Docker 命令
| 命令 | 描述 |
|---------|-------------|
| `docker compose up` | 启动应用 + Ollama |
| `docker compose up -d` | 后台启动 |
| `docker compose down` | 停止所有服务 |
| `docker compose logs -f` | 查看实时日志 |
| `docker compose build --no-cache` | 从头重建 |
### 架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Streamlit UI │ │ FastAPI API │ │ Ollama + LLM │
│ Port 8501 │────▶│ Port 8000 │────▶│ Port 11434 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## 🏗️ 架构设计
### 项目结构
```
97-differential-diagnosis-assistant/
├── src/
│ └── differential_diagnosis/
│ ├── __init__.py # Package init
│ ├── config.py # Configuration management
│ ├── core.py # Core diagnostic engine
│ ├── cli.py # Click CLI commands
│ ├── web_ui.py # Streamlit web interface
│ └── api.py # FastAPI REST API
├── tests/
│ └── test_core.py # Unit tests (15+ tests)
├── common/
│ ├── __init__.py
│ └── llm_client.py # Shared Ollama client
├── examples/
│ ├── demo.py # Demo script
│ └── README.md # Examples documentation
├── docs/
│ └── images/
│ ├── banner.svg # Project banner
│ ├── architecture.svg # Architecture diagram
│ └── features.svg # Feature grid
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── config.yaml # Model configuration
├── requirements.txt # Python dependencies
├── setup.py # Package setup
├── Makefile # Build automation
├── Dockerfile # Container image
├── docker-compose.yml # Multi-service deployment
└── README.md # This file
```
### 数据流
```
Clinical Input → CLI/Web/API → Core Engine → Ollama (Gemma 4) → Ranked Differentials
↓
Urgency Assessment
Body System Mapping
Session Tracking
```
### 技术栈
| 层级 | 技术 | 用途 |
|-------|-----------|---------|
| **CLI** | Click + Rich | 命令行界面，带精美格式化 |
| **Web** | Streamlit | 浏览器界面，带深色主题 |
| **API** | FastAPI | RESTful API，带 Swagger 文档 |
| **AI** | Ollama + Gemma 4 | 本地 LLM 推理 |
| **配置** | YAML | 配置管理 |
| **测试** | pytest | 单元和集成测试 |
| **部署** | Docker | 容器化部署 |
## ⚙️ 配置
```
# config.yaml
model: "gemma4"
temperature: 0.3
max_tokens: 2048
log_level: "INFO"
ollama_url: "http://localhost:11434"
clinical:
include_red_flags: true
include_workup: true
max_differentials: 10
```
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `OLLAMA_HOST` | `http://localhost:11434` | Ollama API 端点 |
| `OLLAMA_MODEL` | `gemma4` | 默认 LLM 模型 |
| `LOG_LEVEL` | `INFO` | 日志详细程度 |
## 🔒 HIPAA 合规
本工具将隐私作为首要考虑因素进行设计：
| 方面 | 实现方式 |
|--------|---------------|
| **数据存储** | 无患者数据持久化到磁盘——仅会话内存 |
| **网络** | 零网络传输——所有 LLM 推理都在本地进行 |
| **模型** | 通过 Ollama 完全在您的机器上运行 |
| **日志** | 日志中无 PHI——仅操作元数据 |
| **Docker** | 隔离容器，无需外部网络访问 |
### 本地与云端对比
| 方面 | 本地 LLM（本工具）| 云端 API |
|--------|----------------------|-----------|
| **隐私** | ✅ 100% 本地——数据永不离开您的机器 | ❌ 数据发送到外部服务器 |
| **成本** | ✅ 设置后免费 | ❌ 按 API 调用付费 |
| **速度** | ⚡ 取决于硬件 | ⚡ 通常较快 |
| **互联网** | ✅ 离线工作 | ❌ 需要网络连接 |
| **数据控制** | ✅ 完全控制 | ❌ 第三方存储 |
| **HIPAA 担忧** | ✅ 无数据传输 | ⚠️ 需要 BAA |
| **模型更新** | 🔄 手动拉取模型 | ✅ 自动更新 |
| **可扩展性** | ⚡ 受硬件限制 | ✅ 云端规模 |
## 🧪 测试
呼吸系统
- 咳嗽、气短、喘息 - 咯血、胸痛、咳痰 - 喘鸣、呼吸急促消化系统
- 腹痛、恶心、呕吐 - 腹泻、便秘、黑便、血便 - 吞咽困难、黄疸、腹水神经系统
- 头痛、头晕、癫痫发作 - 无力、麻木、意识状态改变 - 视力变化、失语、震颤骨骼肌肉系统
- 关节痛、背痛、肌肉无力 - 肿胀、僵硬、畸形 - 关节活动受限、骨摩擦音内分泌系统
- 疲劳、体重变化、多尿、口渴 - 怕热/怕冷、脱发、震颤感染性疾病
- 发热、寒战、盗汗 - 淋巴结肿大、不适、皮疹 - 咽痛、排尿困难精神疾病
- 焦虑、抑郁、失眠 - 幻觉、自杀观念、妄想 - 精神错乱、意识模糊这能替代医生或临床决策支持系统吗？
绝对不能。这只是一个教育工具。它展示了 AI 如何辅助诊断推理，但不能也不应该替代临床判断。如有健康问题，请务必咨询有资质的医疗保健提供者。
鉴别诊断的准确性如何？
这些鉴别诊断是基于提供的输入由 AI 生成的假设。它们可能会遗漏重要诊断或排序错误。本工具旨在支持学习临床推理，而非用于实际临床决策。
我的患者数据存储在哪里？
不会存储。所有数据都保留在当前会话内存中，不会传输到任何服务器或写入磁盘。关闭应用程序时，会话历史将被清除。这使其 100% HIPAA 友好。
哪些 LLM 模型效果最好？
我们推荐 Gemma 4，因为它在医学知识和推理能力之间取得了最佳平衡。较大的模型往往能提供更详细和细致的鉴别诊断。
我可以离线使用吗？
可以！一旦您安装了 Ollama 并下载了模型，整个应用程序可以 100% 离线运行，无需互联网。
我可以将其与我的 EHR 系统集成吗？
REST API 提供的端点理论上可以与其他系统集成。但是，此工具仅用于**教育目的**，不应在任何临床工作流程中使用或连接到真实的患者数据系统。
### ⚠️ 重要提醒
**本工具仅用于教育和信息目的。**
**它不能替代专业医疗建议、诊断或治疗。**
**鉴别诊断是 AI 生成的假设，绝不能用于临床决策。**
**请务必咨询您的医生或其他合格的医疗保健提供者。**
**属于 [Local LLM Projects](https://github.com/kennedyraju55) 系列——项目第 97/90 号**
使用 ❤️ 构建，基于 [Ollama](https://ollama.com) · [Python](https://python.org) · [Gemma 4](https://ai.google.dev/gemma) · [Click](https://click.palletsprojects.com) · [Rich](https://rich.readthedocs.io) · [FastAPI](https://fastapi.tiangolo.com)
*如果您觉得有用，请给本仓库加星！*
标签：AI风险缓解, AV绕过, Docker, FastAPI, Gemma 4, HIPAA合规, Kubernetes, LLM评估, Ollama, Python, Web界面, 临床诊断工具, 人工智能医疗, 医学教育, 医疗AI, 医疗工具, 安全防御评估, 差分诊断, 患者数据安全, 无后门, 本地LLM, 本地模型推理, 网络安全, 网络测绘, 诊断推理, 请求拦截, 逆向工具, 隐私保护