---
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](./USER_GUIDE.md)** — 面向终端用户的完整使用文档,包含界面导览、提问技巧、三级风险说明、**个人数据上传的 3 种方式**、示例对话、隐私说明与术语速查
- **[空白档案模板 → my_profile_template.json](./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 之后):

```bash
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" 输入框的完整结构(所有字段均可选;缺失字段会自动跳过):

```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`
- 空档案时不注入任何患者数据,并提示模型"未上传历史"

---

## 本地开发 / 测试

```bash
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 联系。