README.md

metadata

title: ECG卡使用者问答智能体
emoji: 🫀
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.47.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: ECG卡使用者的中文问答助手(方案A2 示例实现)

🫀 ECG卡使用者问答智能体 (方案 A2)

面向 ECG 卡使用者(以中老年慢性心血管病患者及家属为主)的中文问答助手 Demo。 本仓库对应 Hugging Face Space:YVES28/ecg-chatbot。

⚠ 本项目内置 FAQ 与患者档案均为示例条目,标注"需临床团队审核"。不构成医学诊断,不能替代医生;紧急情况请拨打 120。

---

📖 文档快速入口

• 完整使用说明书 → USER_GUIDE.md — 面向终端用户的完整使用文档,包含界面导览、提问技巧、三级风险说明、个人数据上传的 3 种方式、示例对话、隐私说明与术语速查
• 空白档案模板 → my_profile_template.json — 下载后填入自己的 ECG 历史 / 病史 / 用药 / 生命体征,即可粘贴到侧栏"档案 JSON"框中启用个性化回答

---

功能特性

• 严格四段输出模板:每次回复固定 问题分析 / 原因说明 / 建议 / 是否需要医生,风险等级用 ✅ / ⚠ / 🚨 三色标注。
• 内置约 160 条 FAQ,覆盖使用类、信号类、医学类、报告类、长期管理 5 大类。
• 三级风险自动升级:检测到胸痛、晕厥、呼吸困难等关键词时强制升级为 🚨 急诊提示。
• 患者档案个性化:侧边栏可加载示例档案或粘贴自己的 JSON(ECG 历史 / 报告 / 病史 / 用药 / 生命体征 / 预警),机器人会在压缩后注入到每轮对话上下文中。
• 无向量数据库依赖:FAQ 检索使用关键词 + 字符相似度 (difflib),部署轻量。
• HF Inference Router 后端:通过 huggingface_hub.InferenceClient 调用 Router,可通过环境变量 MODEL_ID 切换模型(默认 Qwen/Qwen2.5-7B-Instruct)。

---

部署到 Hugging Face Space

1. 准备 Space

• 已存在 Space:YVES28/ecg-chatbot
• SDK:Gradio
• Hardware:ZeroGPU(保留原设置;当前路由走 HF Router,GPU 处于 idle,方便未来切换本地模型)

2. 上传 4 个文件到 Space 根目录

app.py
requirements.txt
faq_ecg.json
sample_patients.json
README.md   # 本文件(带 Space 元数据 frontmatter)

推荐命令(在本地克隆 Space 之后):

git clone https://huggingface.co/spaces/YVES28/ecg-chatbot
cd ecg-chatbot
# 用本项目 4 个文件替换/覆盖:
cp /path/to/app.py .
cp /path/to/requirements.txt .
cp /path/to/faq_ecg.json .
cp /path/to/sample_patients.json .
cp /path/to/README.md .
git add app.py requirements.txt faq_ecg.json sample_patients.json README.md
git commit -m "Deploy ECG QA Agent (方案A2)"
git push

3. 配置 Space Secrets 与 Variables

在 Space 页面右上角 Settings → Variables and secrets:

必填 Secret

Name	说明
HF_TOKEN	Hugging Face Personal Access Token(Read 权限即可)。在 https://huggingface.co/settings/tokens 生成

可选 Variable

Name	默认值	说明
MODEL_ID	Qwen/Qwen2.5-7B-Instruct	HF Router 支持的任意 chat completion 模型;可换成 Qwen/Qwen2.5-14B-Instruct、meta-llama/Llama-3.3-70B-Instruct 等

保存后 Space 会自动 rebuild,首次 build ~2-5 分钟。

4. 常见部署问题

• 红色 "Runtime error: HF_TOKEN 未配置":检查 Secret 名称是否精确为 HF_TOKEN,并有 Read 权限。
• 403 Forbidden:所选 MODEL_ID 需要额外的 Terms 接受,请在该模型页面点击 "Accept license" 后重试。
• 429 rate limit:免费额度用完,升级为 PRO 或换免费模型。
• 回复不是四段模板:大概率是模型 hallucinate,本项目在后处理里会自动补齐缺失段落,如果连续偶发可以在 Variables 里降低 temperature(需修改 app.py)。

---

患者档案 JSON 结构

粘贴到左侧 "档案 JSON" 输入框的完整结构(所有字段均可选;缺失字段会自动跳过):

{
  "patient": {"name": "张**", "age": 68, "gender": "男", "diagnosis": "心衰随访"},
  "ecg_history": [
    {"time": "2026-07-10 08:15", "HR": 78, "PR": 168, "QRS": 92,
     "QT": 388, "QTc": 428, "rhythm": "窦性心律",
     "ai_finding": "窦性心律,偶发室早", "signal_quality": "good"}
  ],
  "reports": [
    {"time": "2026-07-01", "type": "医生复核报告",
     "content": "……全文……",
     "key_metrics": {"LVEF": 42, "BNP": 380}}
  ],
  "medical_history": {
    "conditions": ["心衰", "高血压"],
    "past_events": ["2025-12 冠脉造影"]
  },
  "medications": [{"name": "美托洛尔", "dose": "25mg", "freq": "bid"}],
  "vitals_log": [{"time": "2026-07-13", "weight_kg": 72.4, "bp": "128/80"}],
  "alerts": [{"time": "2026-07-05", "level": "L2",
              "content": "夜间HR>110持续10min",
              "handled": "已联系管理师"}]
}

压缩规则(自动)

• 最近 8 条 ECG
• 最新 1 份报告(内容截断至 800 字符,key_metrics 完整保留)
• 全部当前用药
• 最近 3 条预警
• 病史 conditions + past_events
• 空档案时不注入任何患者数据,并提示模型"未上传历史"

---

本地开发 / 测试

pip install -r requirements.txt
export HF_TOKEN=hf_xxx     # 可选;未配置时会走 FAQ 直答降级模式
python app.py
# 打开 http://127.0.0.1:7860

---

目录

文件	作用
app.py	Gradio 主程序:UI + FAQ 检索 + 患者档案压缩 + HF Router 调用 + 输出后处理
faq_ecg.json	160 条示例 FAQ,5 类目均衡
sample_patients.json	2 位示例患者(A:心衰随访 + 阵发房颤;B:高血压 + 良性室早)
requirements.txt	仅 gradio + huggingface_hub
README.md	本文件(带 Space 元数据 frontmatter)
USER_GUIDE.md	完整使用说明书(面向终端用户,含个人数据上传步骤)
my_profile_template.json	空白档案模板(用户下载后填写)

---

免责声明

本项目为方案 A2 的示例实现,所有 FAQ 内容与示例患者数据均为演示用,未经临床团队正式审核。正式面向患者部署前必须:

1. 由心内科/临床团队逐条审核 FAQ 内容与风险等级;
2. 由合规团队评估提示话术、免责语句;
3. 补充真实患者数据的读写、权限与脱敏机制;
4. 与院方合作方共同评估上线路径。

如有临床或工程问题反馈,请通过 Space 讨论区或 Issue 联系。