maggie_Ha/peek-NPU
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

PEEK · 昇腾 NPU 推理服务化适配

English / README (upstream) · 中文 · Ascend NPU 适配

本仓库在原始 PEEK 模型(momentslab/peek)的基础上,使用 PyTorch + torch_npu 将其完整迁移到华为昇腾 NPU,并通过 FastAPI 提供 REST 服务化推理。


1. 模型简介

PEEK (Picking Essential frames via Efficient Knowledge distillation) 是一种查询无关(query-free)的关键帧选择器。

  • 输入:视频帧的 512 维特征(MobileCLIP2-S0 抽取)
  • 输出:每帧的相关性分数;通过 stratified_argmax 选出 top-k 帧
  • 模型规模:约 1.7 M 参数(2 层 Transformer 编码器)
  • 训练数据:ActivityNet Captions train.json
  • 蒸馏教师:冻结的 SigLIP2-so400m-patch14-384

2. 目录结构

/opt/atomgit/peek/
├── README.md                       # 本文件
├── upstream_README.md              # 原始仓库 README(保留)
├── config.json                     # 架构与训练元信息
├── peek_base.safetensors           # 权重(原始 release)
├── LICENSE                         # CC-BY-NC-SA-4.0
├── requirements.txt                # 本次部署的依赖清单
├── inference.py                    # ★ 服务化推理脚本(FastAPI + NPU)
├── test.py                         # ★ 测试用例(健康/评分/选帧/异常/长跑)
├── test_report.json                # ★ 最新一次测试结果
├── model_files/
│   └── peek_scorer.py              # 自包含 PeekScorer NPU 实现
├── assets/                         # ★ 截图 / 适配过程图
│   ├── npu_device_call.png
│   ├── model_result.png
│   └── agent_workflow.png
└── predict.log                     # 服务化推理运行的完整日志

带 ★ 的文件是本次 NPU 适配新增的产物。


3. 昇腾 NPU 适配策略

维度方案
框架PyTorch 2.9.0 + torch_npu 2.9.0.post1
CANN8.5.1(驱动 25.5.5)
模型实现依据 config.json + 权重键名 自包含重建 PeekScorer,不依赖外部 peek 包
权重加载safetensors.torch.load_file + 严格 load_state_dict
推理设备torch.device("npu:0") 单卡
预热启动期 3 轮 dry-run 触发算子编译缓存
算子兼容Linear / LayerNorm / MultiheadAttention / GELU 全部为 torch_npu 原生支持,无需手工替换
精度对齐NPU 与 CPU 输出 **max

3.1 为什么是自包含重建

  • 原始 peek 包需要 MobileCLIP2-S0 图像编码器,而本任务只关心打分器(PeekScorer);
  • 权重键名 transformer.layers.{i}.* 与默认 nn.ModuleList 的 transformer.{i}.* 不一致,因此新增 _TransformerStack 容器来匹配键空间;
  • 不引入 peek / transformers 依赖,降低部署体积与首启时间。

3.2 网络结构

输入 (B, T, 512)            # MobileCLIP2-S0 帧特征
   │
   ├─ LayerNorm(512)        # 键:layer_norm
   ├─ Linear(512 → 256)     # 键:input_projection
   ├─ TransformerEncoderLayer × 2
   │      ├─ self_attn (in_proj 768, out_proj 256)
   │      ├─ linear1 (256 → 1024) + GELU
   │      ├─ linear2 (1024 → 256)
   │      └─ norm1 / norm2 (256)
   └─ Linear(256 → 1)       # 键:score_head
   ↓
输出 (B, T)                 # 每帧相关性分数

4. 部署 & 运行

4.1 准备环境

# 假设 CANN 8.5.1、torch_npu 2.9.0 已安装
pip install -r requirements.txt

4.2 启动服务化推理

cd /opt/atomgit/peek
python3 inference.py --port 8087 --device npu:0

启动后会在终端打印:

[INFO] ============================================================
[INFO] 权重路径: /opt/atomgit/peek/peek_base.safetensors
[INFO] 配置路径: /opt/atomgit/peek/config.json
[INFO] 运行设备: npu:0
[INFO] HTTP 地址: 0.0.0.0:8087
[INFO] 开始加载 PEEK 模型 → 设备: npu:0
[PEEK] 权重加载完成: missing=0, unexpected=0
[INFO] 模型加载完成,耗时 1164.68 ms
[INFO] 开始 NPU 预热(3 轮)
[INFO] NPU 预热完成
[INFO] PEEK 服务已就绪,等待推理请求
INFO:     Uvicorn running on http://0.0.0.0:8087 (Press CTRL+C to quit)

4.3 REST 接口

方法路径说明
GET/health健康检查,返回设备 / 参数量
POST/score输入 (T, 512) 帧特征,返回每帧分数
POST/select输入 (T, 512) 帧特征 + 时间戳 + k,返回选中帧下标与时间戳

示例:

curl -s http://localhost:8087/health
# {"status":"ok","device":"npu:0","model":"PEEK (PeekScorer)","params":1712129}

curl -s -X POST http://localhost:8087/score \
     -H "Content-Type: application/json" \
     -d '{"embeddings": [[0.1, 0.2, ... 512 floats ...], ...]}'
# {"scores": [...], "num_frames": 8, "latency_ms": 4.6, "device": "npu:0"}

curl -s -X POST http://localhost:8087/select \
     -H "Content-Type: application/json" \
     -d '{"embeddings": [...], "timestamps": [0.0, 0.5, 1.0, ...], "k": 4}'

4.4 运行测试用例

python3 test.py --host localhost --port 8087

用例覆盖:

  1. /health 健康检查
  2. /score 在 8 / 32 / 64 帧三种长度上的纯推理
  3. /select 在 16 / 32 帧中分别选 4 / 8 帧
  4. 异常输入(空 embeddings / 长度不一致)应返回 400
  5. 长跑 50 次推理,统计 P50 / P95 时延

5. 性能结果

硬件:Ascend 910(npu:0)
软件:PyTorch 2.9.0 + torch_npu 2.9.0.post1 + CANN 8.5.1
模型参数:1,712,129(约 1.7 M)

用例帧数NPU 推理耗时(服务端)客户端耗时
/score8~4.6 ms~9.8 ms
/score32~6.3 ms~22.4 ms
/score64~8.0 ms~38.7 ms
/select16, k=4~11.9 ms~20.4 ms
/select32, k=8~6.8 ms~22.4 ms
test_long_run 50 次16平均 4.477 msP50 12.6 ms / P95 12.7 ms

CPU 与 NPU 输出 max |diff| ≈ 4.6e-4(float32 精度范围内一致)。

一次推理耗时(16 帧)平均 ≈ 4.5 ms(仅 NPU 推理)+ ~8 ms HTTP 往返 = 客户端 P50 ≈ 12.6 ms。

完整测试报告见 test_report.json。


6. 截图

截图文件
NPU 设备调用assets/npu_device_call.png
测试结果assets/model_result.png
适配过程assets/agent_workflow.png

(图中带 maggie_Ha 水印)


7. 局限与注意事项

  • 本次只迁移 打分器 PeekScorer。如需端到端(含 MobileCLIP2-S0 抽帧),需要额外加载图像编码器。
  • 服务端假设每帧 512 维特征。批量推理时建议每帧确保已是 L2-normalized 的视觉特征(与 PEEK 训练方式一致)。
  • k = 0 会触发 400 校验;k > T 时服务会返回全部帧并按时间排序。
  • 选帧策略按 stratified_argmax 实现,与论文默认配置一致。

8. 引用

@inproceedings{steunou2026peek,
  title={{PEEK}: Picking Essential frames via Efficient Knowledge distillation},
  author={Steunou, Killian and Filali Razzouki, Anas and Guetari, Khalil and El-Yacoubi, Moun{\^i}m A. and Tevissen, Yannis},
  year={2026},
  url={https://arxiv.org/abs/2605.31029}
}

9. License

模型权重遵循 CC-BY-NC-SA-4.0;本仓库新增的 NPU 适配代码按 Apache-2.0 风格开放,便于二次集成。