ALISY/compressionkit-ppg-4x-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

compressionkit-ppg-4x-npu

Ambiq compressionkit PPG 神经信号压缩 Codec (4x) — 昇腾 NPU 适配版

本工程将 Ambiq compressionkit 的 PPG 光电容积脉搏波 RVQ 神经压缩 codec(4x 压缩率)从 Keras/TFLite 迁移到 昇腾 NPU(torch-npu) 纯 PyTorch 实现。

模型信息

项目值
模态PPG(光电容积脉搏波)
采样率64 Hz
帧长320 样本(5 秒)
压缩率4x(码率压缩比 4.0)
Codec 族Residual Vector Quantization (RVQ)
RVQ 级数4 级,每级 256 个 16 维码本向量
编码器输出[1, 80, 16](时域降采样 4x)
解码器输出[1, 320, 1]

昇腾 NPU 适配说明

  • 使用纯 PyTorch 重建 encoder/decoder 网络,逐层移植 Keras 权重(keras.weights 已导出为 encoder_weights.npz / decoder_weights.npz,缓存于 model_weights/Ambiq/compressionkit-ppg-4x-v1.0/)。
  • 自动权重下载(模板要求 #3):本地缓存缺失/不完整时, inference.py 会自动从 hf-mirror 下载 encoder.keras / decoder.keras / codebook.npz / codec_spec.json,并调用 convert_weights.py 现场转换为 codec 需要的 npz 权重。已有完整缓存时优先使用缓存,不触发下载。
  • 全程 无 CUDA:模型与输入 Tensor 均运行在 npu:1(本模型指定设备;忙/OOM 自动回退 npu:0)。
  • 已通过 Keras 参考模型逐层数值校验(编码器/解码器最大绝对误差 < 1e-6)。
  • RVQ 量化:z 与各级码本做最近邻(欧氏距离),逐级 argmin 得到码索引,解码时按索引查码本求和。

文件

文件说明
inference.py双模式推理:CLI + FastAPI(见下);含权重自动下载+转换
codec.py纯 PyTorch codec 实现(encoder / decoder / RVQ / 归一化)
convert_weights.pyKeras(.keras) → codec npz 权重转换脚本
model_weights/权重本地缓存(gitignore,不入库)

环境

  • Python 3.11,torch 2.9.0+cpu,torch_npu 2.9.0,CANN 8.5.1,Ascend910B
  • 依赖:torch torch_npu numpy fastapi uvicorn python-multipart keras

用法

CLI 推理(输入 .npz / .npy / 一维信号文件)

python inference.py --img sample_ppg.npz

输出 JSON:model、compression_ratio、mse、snr_db、codebook_indices、 reconstructed_signal 等。首次运行若本地无权重缓存,会自动从 hf-mirror 下载 Keras 原权重并转换为 npz(日志输出到 stderr,stdout 保持纯净 JSON)。

FastAPI 服务

uvicorn inference:app --host 0.0.0.0 --port 8000
curl -s -F "file=@sample_ppg.npz" http://127.0.0.1:8000/predict

POST multipart/form-data,字段名 file,返回 JSON 推理结果。

许可

权重遵循原仓库 LICENSE-MODEL-WEIGHTS.md(Ambiq Model Weights License); 样例/演示数据使用合成 physiokit 波形与 BIDMC PPG 数据集(ODC-By-1.0)。