🏥 医学证据助手（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	结构化证据卡

---

🏗️ 架构

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. 环境

python -m pip install -r requirements.txt

2. 配置 API

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

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

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

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

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. 构建知识库

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

5. 启动

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

6. 评估与测试

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

---

🤖 作为 AI Agent Tool（MCP 服务）

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

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）：

{
  "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）。

---

📁 项目结构

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