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

PPG-4x-NPU:PPG 信号压缩编解码器(4x)昇腾 NPU 服务化推理

将 Ambiq 的 compressionkit-ppg-4x-v1.0 PPG(光电容积脉搏波)信号压缩编解码器迁移至本地昇腾 NPU(Ascend910 系列), 并提供 HTTP 服务化推理能力。

NPU 设备调用


1. 项目概述

compressionkit-ppg-4x-v1.0 是 Ambiq 面向可穿戴设备的 PPG 信号压缩编解码器 (Residual Vector Quantization, RVQ),压缩比 4x,INT8 量化,专为边缘设备设计。 与 2x 版本同家族,编码器采用双级下采样、解码器双级上采样。

组件说明
编码器Conv1×7(s2)+BN+ReLU ×2 + Conv1×1:320 点帧 → 80×16 latent
RVQ 量化4 级码本(每级 256 个 16 维向量),残差量化
解码器[Up1×2 + Conv1×7 + SeparableConv1×5] ×2 + LayerNorm + Conv1×1
采样率64 Hz(帧长 320 点 = 5 秒)
压缩比4x(320 点 → 80 个 16 维 latent → 320 个 8bit 索引)
推理框架PyTorch 2.9.0 + torch_npu 2.9.0.post1
服务框架FastAPI + Uvicorn

迁移方式:官方权重为 Keras(.keras) 格式,本项目转换为等价 PyTorch 网络, 精度经 TFLite 参考输出与官方重建样本双重验证。


2. 环境要求

组件版本备注
操作系统openEuler 22.03 (aarch64)其他昇腾支持系统亦可
昇腾硬件Ascend910 系列至少 1 卡
CANN25.5.0(≥ 8.0)/usr/local/Ascend/ascend-toolkit/set_env.sh
Python3.113.8–3.10 亦可
PyTorch2.9.0与 CANN 版本配套
torch_npu2.9.0.post1与 PyTorch 版本一致

依赖安装

# 1. 加载 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 2. 配置华为镜像源(国内加速)
export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/

# 3. 安装依赖
pip install -r requirements.txt

# 4. 校验 NPU 可用性
python3 -c "import torch, torch_npu; print(torch.randn(3,4).npu() + torch.randn(3,4).npu())"

注意:numpy 固定 1.26.4(华为 CANN 推荐 + tflite-runtime 兼容)。


3. 目录结构

compressionkit-ppg-4x-v1.0-npu/
├── inference.py              # 服务化推理主入口(FastAPI 服务)
├── model.py                  # PyTorch 网络定义 + Keras 权重转换 + RVQ + 预处理
├── test_inference.py         # 服务化推理测试用例(12 项)
├── requirements.txt          # 运行环境依赖清单
├── README.md                 # 本文件(中文指引)
└── assets/                   # 验证截图
    ├── npu_device_call.png   # NPU 设备调用截图
    ├── model_result.png      # 测试结果截图
    └── agent_workflow.png    # 适配过程截图

权重文件(encoder.keras / decoder.keras / codebook.npz)仍在原始目录 /mnt/old_data/whl/models/8/Ambiq/compressionkit-ppg-4x-v1.0,通过 --model-dir 指定。


4. 快速开始

4.1 启动服务

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=0

python inference.py \
    --port 8004 \
    --model-dir /mnt/old_data/whl/models/8/Ambiq/compressionkit-ppg-4x-v1.0

启动日志示例:

[PPG4x-NPU] 加载模型: /mnt/.../Ambiq/compressionkit-ppg-4x-v1.0 -> npu:0
[PPG4x-NPU] 模型就绪, 设备: npu:0
[PPG4x-NPU] 当前 NPU 显存占用: 0 MB / 62740 MB
INFO:     Uvicorn running on http://0.0.0.0:8004

4.2 运行测试用例

python test_inference.py --port 8004

预期输出(详见 测试结果截图):

== 4. 重建质量校验 ==
  [PASS] PRD < 5%(4x 压缩) PRD=0.59%
  [PASS] 余弦相似度 > 0.98 cos=0.999984
== 6. 压缩比换算校验 ==
  [PASS] 每帧索引数 = 320/4×4 实际 (1, 80, 4)
===== 测试结果: 12 通过, 0 失败 =====
全部测试通过 ✅

5. HTTP 接口说明

5.1 GET /health — 健康检查 / NPU 设备状态

curl http://127.0.0.1:8004/health

5.2 GET /model — 模型信息

curl http://127.0.0.1:8004/model

5.3 POST /codec — PPG 信号编解码

curl -X POST http://127.0.0.1:8004/codec \
     -H "Content-Type: application/json" \
     -d '{"signal": [0.12, 0.34, ...], "return_indices": true}'
参数说明默认
signal原始 PPG 信号(float 数组,长度需 ≥ 320 且为 320 的倍数)必填
return_indices是否返回 RVQ 码本索引(压缩表示)false

响应:

{
  "input_length": 1920,
  "frames": 6,
  "compression_ratio": 4,
  "latent_shape": [6, 80, 4],
  "reconstruction": [0.119, 0.341, ...],
  "prd_percent": 0.59,
  "rmse": 0.000019,
  "cosine_similarity": 0.999984,
  "elapsed_seconds": 0.0542,
  "indices": [[...80×4 码本索引...]]
}

压缩表示:每帧 320 点(float32,1280 字节)→ 80×4 个 8bit 码本索引(320 字节), 压缩比 4x;由索引可直接解码重建。


6. 昇腾 NPU 适配说明

本项目依据 ascend-model-agent-plugin(ai4s-basic)迁移流程完成, 复用 2x 版本已验证的转换框架,关键适配点:

  1. 自动迁移注入:inference.py 顶部导入
    import torch_npu
    from torch_npu.contrib import transfer_to_npu   # cuda API 自动映射 npu
  2. Keras → PyTorch 权重转换(model.py):Conv2D 布局 [KH, KW, in, out] → PyTorch [out, in, KH, KW];BatchNorm 的 gamma/beta/moving_mean/moving_var 映射。
  3. 双级下采样 padding 适配:两级 stride=2、kernel=7 卷积的 Keras same padding 均为"前 2 后 3"(总 5),用 F.pad 手动补边。
  4. SeparableConv 语义:两级 depthwise 均无 bias(bias 仅属 pointwise 层)。
  5. RVQ 量化:4 级残差量化,latent 长度 80(4x 压缩),索引语义与官方一致。

精度验证(vs 官方基线)

对比对象PRD说明
Encoder vs TFLite 参考0.023%权重转换正确性
Decoder vs TFLite 参考0.017%权重转换正确性
端到端 vs 官方重建样本0.55%含 RVQ 量化
服务实测(demo 数据)0.59%4x 压缩

实测性能(NPU 卡 0)

指标数值
单帧编解码(6 帧/1920 点)0.054 s
单帧推理(320 点)~9 ms
NPU 显存占用< 100 MB

7. 常见问题

问题解决方案
重建信号与预期差异大确认输入为原始未归一化信号(服务自动做 per-frame norm)
numpy 相关报错按 requirements 固定 numpy==1.26.4
需要 2x 压缩版本见姊妹项目 compressionkit-ppg-2x-v1.0-npu(端口 8003)

8. 许可证

  • 适配代码:Apache-2.0
  • 模型权重:Ambiq 模型权重许可(非商用),详见 LICENSE-MODEL-WEIGHTS.md