1
gcw_xUvjaUyi/xECG_base_model_v1-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

xECG_base_model_v1-npu

12 导联心电图(ECG)基础模型 riccardolunelli/xECG_base_model_v1 的昇腾 Ascend NPU 适配工程。 原始模型:huggingface.co/riccardolunelli/xECG_base_model_v1(xLSTM 骨干 + patch embedding,MIT License)。 论文:BenchECG and xECG: a benchmark and baseline for ECG foundation models。

本工程将原始模型适配到华为昇腾 NPU(torch-npu),支持命令行单次推理与 FastAPI 推理服务,全程无 GPU 私有 kernel,模型与输入 Tensor 均运行在 npu:0。


模型说明

  • 输入:12 导联 ECG 信号,形状 [12, T](T 为时间采样点,采样率 100Hz)。 导联顺序固定为:['i','ii','iii','avr','avl','avf','v1','v2','v3','v4','v5','v6']。 缺失导联直接置 0 即可。
  • 输出:
    • pooled:池化后的全局表示向量([1024],默认 avg 均值池化)。
    • patches:所有 patch 的 embedding([num_patches, 1024])。
  • 模型参数:约 57.02M;patch_size=25,embedding_size=1024,xLSTM 混合堆叠(9 层,sLSTM/mLSTM)。

昇腾 NPU 适配要点

  1. 无 GPU 私有 kernel 依赖:sLSTM 固定使用 backend="vanilla"(纯 PyTorch 实现);代码全域不调用任何 GPU 私有 kernel 与私有设备迁移 API。
  2. 权重加载适配:原 safetensors 中 sLSTM 的 _recurrent_kernel_ 形状为 [H, 256, 1024],而 vanilla backend 期望 [H, 1024, 256],加载时做 permute(0, 2, 1) 维度置换(对应官方 load_checkpoint 中的注释逻辑)。
  3. 设备迁移:模型与输入 Tensor 全部 .to('npu:0');推理在 torch.no_grad() 下进行;加载后 model.eval()。
  4. 入口防御:main / FastAPI 启动处 try-except 捕获 NPU 初始化异常(torch_npu import 失败或 npu:0 不可用 → 打印清晰中文错误并优雅退出)。
  5. 权重缓存:缓存路径固定 ./model_weights/riccardolunelli__xECG_base_model_v1/,启动优先加载本地缓存,命中则跳过下载(未命中自动从 hf-mirror.com 拉取)。

环境依赖

# 已实测环境:Python 3.11 · torch 2.9.0+cpu · torch-npu 2.9.0.post1 · Ascend910 ×2
pip install timm -i https://mirrors.aliyun.com/pypi/simple/
pip install xlstm==2.0.4 --no-deps -i https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

注意:严禁重装/升级 torch / torch-npu / numpy / transformers。 完整依赖见 requirements.txt。

CLI 用法

# 方式一:提供真实 12 导联 ECG 信号文件(.npy 或 .json,形状 [12, T])
python3 inference.py --signal sample_ecg.npy

# 方式二:不传 --signal,自动使用内置合成 ECG 演示数据(25s @ 100Hz)
python3 inference.py

真实运行示例(NPU):

$ python3 inference.py --signal sample_ecg.npy
[NPU] Ascend NPU 初始化成功:device_count=2, device=npu:0
[Weights] 命中本地缓存:/opt/atomgit/xECG_base_model_v1-npu/model_weights/riccardolunelli__xECG_base_model_v1
[Model] 构建 xECG 模型(xLSTM 骨干,sLSTM backend=vanilla)...
[Model] 加载 safetensors 权重...
[Model] 模型加载完成:57.02M 参数,已迁移到 npu:0,eval 模式
[Input] 读取信号文件: sample_ecg.npy
[Infer] 输入信号 [12, 1000] @ 100Hz -> patches=40
[Result] 推理 JSON:
{
  "model": "riccardolunelli/xECG_base_model_v1",
  "device": "npu:0",
  "inference_time_ms": 353.548,
  "input": {"shape": [12, 1000], "sampling_freq_hz": 100, "patch_size": 25, "num_patches": 40, ...},
  "pooled": {"shape": [1024], "norm_l2": 73.665123, "mean": -0.00578, "std": 2.303153, ...},
  "patches": {"shape": [40, 1024], "num_patches": 40, "embedding_size": 1024, ...}
}

FastAPI 推理服务

uvicorn inference:app --host 0.0.0.0 --port 8001
端点方法说明
/GET服务信息
/healthGET健康检查,返回 {"status":"ok","device":"npu:0"}
/predictPOST推理;接收 JSON body 或上传 .npy / .json 文件

JSON body 示例({"signal": [[12 导联数组...]]},导联优先 [12, T],也支持 [T, 12]):

curl -s -X POST http://127.0.0.1:8001/predict \
  -H "Content-Type: application/json" \
  --data '{"signal": [[...12 导联 ECG 信号...]]}'

文件上传示例(.npy / .json):

curl -s -X POST http://127.0.0.1:8001/predict -F "file=@sample_ecg.npy"

真实响应(HTTP/1.1 200 OK,Content-Type: application/json):

{
  "model": "riccardolunelli/xECG_base_model_v1",
  "device": "npu:0",
  "inference_time_ms": 144.228,
  "input": {"shape": [12, 1000], "sampling_freq_hz": 100, "patch_size": 25, "num_patches": 40, "lead_order": ["i","ii","iii","avr","avl","avf","v1","v2","v3","v4","v5","v6"]},
  "pooled": {"shape": [1024], "norm_l2": 73.665123, "mean": -0.00578, "std": 2.303153, "min": -8.937963, "max": 16.192976},
  "patches": {"shape": [40, 1024], "num_patches": 40, "embedding_size": 1024, "norm_mean": 76.446449, "abs_mean": 1.666736}
}

工程结构

xECG_base_model_v1-npu/
├── inference.py        # 单文件推理(CLI + FastAPI 双模式,含模型结构)
├── requirements.txt    # 依赖清单
├── README.md
├── .gitignore
├── logs/               # 运行日志(npu_cli.log / api_result.log)
├── assets/             # 真实运行截图
└── model_weights/      # 权重缓存(已 gitignore,不随仓库提交)

截图(真实运行)

  • assets/agent_workflow.png — NPU 环境部署、依赖安装、任务启动总日志
  • assets/npu_device_call.png — 命令行推理成功界面(含 NPU 设备信息与结果)
  • assets/model_result.png — FastAPI 返回推理 JSON 界面

免责声明

合成 ECG 演示数据仅用于功能验证,不构成任何医学诊断。