# 🏥 医学证据助手（Medical Evidence Assistant）

面向医生、医学生与科研人员的**本地医学证据检索问答平台**：基于本地文献库的 RAG 检索增强生成 + 循证医学工具链 + 可复现评估。

> ⚠️ **教学演示项目，不用于诊疗。** 回答仅供参考，重要决策请咨询专业医生并核对原始文献。

---

## ✨ 功能总览

### 六个页面

| 页面 | 说明 |
| --- | --- |
| 🏠 首页 | DeepSeek 风格统一问答：⚡快速 / 🧠深度思考 × 🍎营养 / 🏥临床 / 💬客服 |
| 🍎 营养健康 RAG 助手 | 大众模式：口语化回答、不输出具体数字、引用与图表展示 |
| 🏥 临床证据助手 | 临床模式：允许统计量、证据分级、一键生成证据卡 |
| 🧪 对比评估实验 | 专用 RAG vs 纯 LLM：引用有效率、假引用率、LLM 裁判打分、检索退化测试 |
| ☁️ 云端看板 | 问答自动记录、回答率/联网兜底率、未答问题 → 自动建议补文献方向 |
| 🧰 医学工具 | 8 个结构化工具交互演示 |

### 核心能力

- **混合检索**：本地语义嵌入（bge-small-en，GPU）+ BM25 + RRF 融合 + LLM 重排 + 医学实体扩检索
- **引用三重保险**：编号校验 → 语义核验（引用是否真支撑句子）→ 不匹配强制重写
- **联网兜底**：本地证据不足时自动调用 PubMed 工具 → Europe PMC + 必应 → 最后诚实拒答
- **Agent 短轨迹**：每次问答记录决策过程（本地 → 工具 → 联网 → 拒答），界面可展开、云端可查
- **函数调用式 Agent**：本地证据不足时，由 LLM 自主决定调用哪些医学工具（实测：他汀×克拉霉素问题自动调用 4 次工具并给出带 PMID 的相互作用结论）
- **跨领域双模式路由**：问题同时涉及营养与临床时，自动用两个视角分别生成再合并成统一回答（如「糖尿病合并高血脂怎么吃」）
- **安全护栏**：胸痛/卒中/自杀/中毒等紧急问题直接转介 120；剂量/孕期/儿童用药强制警示
- **速度优化**：翻译+实体并行、进程内缓存、BM25 落盘缓存、启动预热、⚡快速模式

### 8 个医学工具（MCP 暴露 7 个）

| 工具 | 数据源 | 用途 |
| --- | --- | --- |
| `search_pubmed` | Europe PMC | 医学文献检索 |
| `verify_citation` | Europe PMC | 核验 PMID/DOI、撤稿提示 |
| `get_trial_record` | ClinicalTrials.gov | 临床试验状态/分期/干预 |
| `lookup_drug` | OpenFDA | 药品说明书（适应症/用法/警示） |
| `check_drug_interaction` | RxNorm | 药物相互作用（尽力查询+诚实兜底） |
| `extract_pico` | LLM | PICO 抽取（人群/干预/对照/结局） |
| `extract_entities` | LLM | 医学实体识别 |
| `build_evidence_card` | LLM | 结构化证据卡 |

---

## 🏗️ 架构

```text
PDF ──> ingest.py ──> ChromaDB（14,839 块 + 920 图）
                        │
用户问题 ──> pipeline.py（Agent 调度）
              ├─ 安全护栏（紧急转介 / 谨慎警示）
              ├─ 检索：语义嵌入 + BM25 + RRF + LLM 重排 + 实体扩检索
              ├─ 生成：nutrition / clinical 双模式 + 引用三重校验
              ├─ 工具层：PubMed / 临床试验 / 药品 / PICO / 实体
              ├─ 联网兜底：Europe PMC + Bing
              └─ 云端记录：usage.db（决策轨迹）
评估：evaluate.py（8 题基准 + LLM 裁判 + 关键词断言）
```

---

## 🚀 快速开始

### 1. 环境

```bash
python -m pip install -r requirements.txt
```

### 2. 配置 API

复制 `.env.example` 为 `.env`，填入 DeepSeek（或其他 OpenAI 兼容）API Key：

```ini
OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_LLM_MODEL=deepseek-chat
```

### 3. 下载嵌入模型（不随仓库分发）

模型通过 ModelScope 下载（推荐国内网络）：

```bash
python - <<'EOF'
from modelscope import snapshot_download
snapshot_download("BAAI/bge-small-en-v1.5", local_dir="models/bge-small-en-v1.5")
EOF
```

### 4. 构建知识库

```bash
python ingest.py                    # 首次入库（读取 ./2026暑期实践 下的 PDF）
python build_semantic_index.py      # 用语义嵌入重建索引（GPU 约 1-2 分钟）
```

### 5. 启动

```bash
streamlit run app.py                # http://localhost:8501
```

### 6. 评估与测试

```bash
python evaluate.py --fixtures tests/fixtures/8q.yaml   # 8 题基准评估
python -m pytest tests -q           # 单元测试
```

---

## 🤖 作为 AI Agent Tool（MCP 服务）

项目内置 [mcp_server.py](mcp_server.py)，把 7 个医学工具封装为标准 MCP 服务，可被 **Cursor / Claude Desktop / Claude Code** 等调用：

```bash
python mcp_server.py                            # stdio 模式（默认）
python mcp_server.py --transport http --port 8000   # HTTP 模式
pip install -e . && mcp-medical-evidence        # 安装为命令后直接运行
```

配置示例（Claude Desktop `claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "medical-evidence": {
      "command": "python",
      "args": ["E:/path/to/project/mcp_server.py"],
      "env": { "OPENAI_API_KEY": "sk-xxxx", "OPENAI_BASE_URL": "https://api.deepseek.com" }
    }
  }
}
```

工具：`search_pubmed` / `verify_citation` / `get_trial_record` / `lookup_drug` / `check_drug_interaction` / `extract_pico` / `extract_entities`

> 🔑 密钥只通过环境变量传入，绝不写入日志或提交到仓库（`.env` 已在 `.gitignore`）。

---

## 📁 项目结构

```text
app.py                    # 平台入口（多页面导航）
views/                    # 页面：home/nutrition/clinical/evaluation/cloud/tools
pipeline.py               # Agent 调度：检索 → 工具 → 联网 → 拒答 + 轨迹
agent.py                  # 函数调用式 Agent（LLM 自主选择工具）
routing.py                # 跨领域识别 + 双视角回答合并
retrieve.py               # 混合检索（语义/BM25/RRF/重排/实体扩检索/缓存）
generate.py               # 双模式生成 + 引用三重校验 + 深度思考
embeddings.py             # 本地语义嵌入（bge-small-en，GPU）
ingest.py                 # PDF → ChromaDB 入库
tools.py                  # 8 个医学工具（结构化 JSON）
medical_nlp.py            # 医学实体 + 证据分级（牛津 CEBM）
safety_rules.py           # 安全护栏（紧急/谨慎规则）
websearch.py              # 联网兜底（Europe PMC + Bing）
cloud.py                  # 云端问答记录（SQLite）
evaluate.py               # 评估实验（RAG vs 纯 LLM）
mcp_server.py             # MCP 服务封装
ocr_pdfs.py               # 扫描版 PDF 识别（RapidOCR）
tests/                    # 18 个单元测试 + 固定 8 题 fixtures
```

---

## 🗺️ 路线图

- [x] 语义嵌入检索 / LLM 重排 / 实体扩检索
- [x] 双模式生成 + 引用核验 / 安全护栏 / 联网兜底
- [x] 8 题评估基准 + LLM 裁判 + 关键词断言
- [x] MCP 工具服务
- [x] 函数调用式 Agent（LLM 自主选择工具）
- [x] 跨领域双模式路由
- [ ] 中文资料入库（《中国居民膳食指南》《现代营养学》OCR）
- [ ] 流式输出 / CI（GitHub Actions）

---

## ⚠️ 免责声明

本项目为**教学演示**，输出不构成医疗建议。涉及紧急症状请立即拨打 120；用药剂量、孕期/儿童用药等请咨询执业医师或药师。

## 📄 License

[MIT](LICENSE)