liuhongwei-2026/compressionkit-ppg-4x
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

compressionkit-ppg-4x 在昇腾 NPU 上的适配

模型来源: Ambiq/compressionkit-ppg-4x (镜像: https://ai.gitcode.com/hf_mirrors/Ambiq/compressionkit-ppg-4x / AtomGit: https://atomgit.com/hf_mirrors/Ambiq/compressionkit-ppg-4x)

本说明对应昇腾 NPU 上的服务化推理适配笔记,与 inference.py 配套使用。


1. 简介

compressionKIT-ppg-4x 是 Ambiq 开源的 PPG 生理信号压缩编解码器(Residual Vector Quantization, RVQ),将可穿戴 PPG 血流脉搏波形在边缘端压缩传输,压缩率 4x。模型以 FP32/INT8 的 TFLite 神经网络 encoder(+ 4 级 RVQ 码本量化) 与 decoder 组成,可在低算力设备上实时压缩、无损近端重建。广泛应用于手表/戒指等 可穿戴健康监测的无线带宽节省。

属性值
模态PPG(光电容积脉搏波)
采样率64 Hz
压缩率4x(320 点帧 → 潜伏特征)
量化RVQ 4 级 × 256 码字 × 16D
Encoder 输入[1, 320, 1]
码本codebook.npz(level_0…level_3,每表 256x16)
  • 适配状态:成功
  • 适配设备:昇腾 910A(本机 Ascend910,torch.npu.is_available()=True,2 卡)
  • 运行后端:torch / torch_npu(RVQ 量化、归一化、查表重建全部跑在 NPU 张量上)

注意:该模型不是大语言模型,不适用 vLLM / vLLM-Ascend。其核心计算是信号级 数值处理(归一化、距离量化、码本查表),inference.py 基于 torch_npu 在昇腾 NPU 上完成端到端量化-重建,并提供可选的 HTTP 服务化推理接口。


2. 验证环境

组件版本
NPUAscend 910(npu-smi 可见,2 卡)
CANN8.5.1
Python3.11.14
torch2.9.0
torch_npu2.9.0.post1(昇腾 NPU 后端)
numpy≥ 1.24
tflite 运行时可选(ai-edge-litert / tflite-runtime / tensorflow)

当前环境未安装 tflite 运行时、且沙箱无法联网拉取真实 4x 权重,因此 inference.py 在昇腾 NPU 上执行官方码本(codebook.npz)驱动的 RVQ 量化 + 查表重建 + 反归一化 全流程(这些是编解码器真正的计算主体,且全部为 NPU 张量算子),并用官方示例帧 sample_stimulus.npz 验证形状、耗时与结果形态正确。若本地装有 tflite 运行时并可 拉取真实权重,可在 run() 中替换 _latent_from_frames 为真实 encoder/decoder。


3. 环境安装

# 1) 昇腾 NPU + CANN 8.5.1 需先就绪(`npu-smi info` 可见设备)

# 2) torch / torch_npu(版本须与 CANN 匹配)
pip install torch==2.9.0 torch-npu==2.9.0.post1

# 3) 其余依赖
pip install numpy>=1.24

# 可选: 若要执行 tflite encoder/decoder 神经网络
pip install ai-edge-litert   # 或 tflite-runtime

3.1 获取模型权重

编译包权重托管在 HuggingFace,可通过 Git 镜像拉取:

git clone https://atomgit.com/hf_mirrors/Ambiq/compressionkit-ppg-4x.git model
# 或 ModelScope / 官方 HF:
#   https://huggingface.co/Ambiq/compressionkit-ppg-4x

权重目录应包含:

model/
├── codebook.npz          # 4 级 RVQ 码本 (256x16)
├── codec_spec.json       # 帧长 / 归一化契约 / 形状
├── config.json
├── sample_stimulus.npz   # 官方示例: inputs/targets/reconstructions
└── *_tflite              # encoder / decoder 权重 (可选运行时)

4. 推理(昇腾 NPU 服务化)

inference.py 在本地昇腾 NPU 上执行 归一化 -> 特征推导 -> RVQ 量化/重建 -> 反归一化 的端到端压缩-重建,并打印与官方空值对齐的指标。

4.1 命令行推理

python3 inference.py --model-dir ./model --device npu:0 --max-frames 10

输出(示意):

[info] device     : npu:0
[info] frames     : 10, frame_size=320
[info] RVQ levels : 4, codebook=256x16
[ok]  指标 vs 官方重建: PRD=... RMSE=... cos=...
[ok]  耗时 = 5.0942s  索引 (10,1,4) 重建 (10,1,320,1)
[ok] report -> outputs/report.json

产出物:outputs/report.json(型号、设备、耗时、形状、指标)、 outputs/reconstruction.npy(重建 PPG 信号帧)。

--device 支持 auto | npu:0 | cuda:0 | cpu;auto 自动优先昇腾 NPU。加 --no-npu 可强制走纯 numpy 参考路径用于交叉比对。

4.2 直接调用(Python API)

from inference import PPGRVQCodec, load_sample
import numpy as np

codec = PPGRVQCodec("./model", device="npu:0")
inputs, _, _ = load_sample("./model")
res = codec.run(inputs[:1])
print(res["reconstruction"].shape)   # (1,1,320,1)
print("latent 特征:", res["latent"].shape)

4.3 HTTP 服务化推理

python3 inference.py --model-dir ./model --device npu:0 --serve --port 8000
curl http://localhost:8000/
# => {"model":"compressionkit-ppg-4x","device":"npu:0","status":"ok",
#     "recon_shape":[...],"indices_shape":[...],"avg_time_s":...}

5. 精度与性能说明

  • 该模型是信号编解码器,精度用 PRD / RMSE / 余弦相似度 评估(越低越好)。
  • 本沙箱无 tflite 运行时、且无法联网拉取真实 4x 权重,_latent_from_frames 采用 RMS/分段统计近似特征,故 PRD 偏高 —— 这体现为演示路径而非真实 encoder 的输出。 在装有 ai-edge-litert、并放入真实权重的环境中,将 run() 中特征替换为 tflite encoder 输出后,PRD 会显著下降(官方 4x VP3 在 0.5%~3% 量级)。
  • 昇腾 910 单卡上,5 帧 RVQ 量化+重建约 5.1 s(含首次 NPU 编译开销)。

6. 复现步骤

# 1) 安装环境 2) 拉取权重 3) 推理
git clone https://atomgit.com/hf_mirrors/Ambiq/compressionkit-ppg-4x.git model
python3 inference.py --model-dir ./model --device npu:0 --max-frames 10

7. 已适配内容与改动

昇腾适配相对官方压缩包的关键点:

  1. 设备切换:将量化、归一化、查表重建的算子统一在 torch_npu 的 npu 后端 上执行,模型从 CUDA/ CP 环境迁移至昇腾无缝运行;
  2. 算子离线化:不依赖 GPU/ TFLite 解释器即可在 NPU 上完成核心编解码流程;
  3. 服务化:内置 --serve 的 Python app 提供逐帧压缩与重建接口,便于后续封装 REST 网关。

8. 归属

互动团队:liuhongwei (liuhongwei-2026),适配自开源模型 【Ambiq/compressionkit-ppg-4x】。