English / README (upstream) · 中文 · Ascend NPU 适配
本仓库在原始 PEEK 模型(momentslab/peek)的基础上,使用 PyTorch + torch_npu 将其完整迁移到华为昇腾 NPU,并通过 FastAPI 提供 REST 服务化推理。
PEEK (Picking Essential frames via Efficient Knowledge distillation) 是一种查询无关(query-free)的关键帧选择器。
stratified_argmax 选出 top-k 帧train.json/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 适配新增的产物。
| 维度 | 方案 |
|---|---|
| 框架 | PyTorch 2.9.0 + torch_npu 2.9.0.post1 |
| CANN | 8.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 |
peek 包需要 MobileCLIP2-S0 图像编码器,而本任务只关心打分器(PeekScorer);transformer.layers.{i}.* 与默认 nn.ModuleList 的 transformer.{i}.* 不一致,因此新增 _TransformerStack 容器来匹配键空间;peek / transformers 依赖,降低部署体积与首启时间。输入 (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) # 每帧相关性分数# 假设 CANN 8.5.1、torch_npu 2.9.0 已安装
pip install -r requirements.txtcd /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)| 方法 | 路径 | 说明 |
|---|---|---|
| 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}'python3 test.py --host localhost --port 8087用例覆盖:
/health 健康检查/score 在 8 / 32 / 64 帧三种长度上的纯推理/select 在 16 / 32 帧中分别选 4 / 8 帧硬件: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 推理耗时(服务端) | 客户端耗时 |
|---|---|---|---|
/score | 8 | ~4.6 ms | ~9.8 ms |
/score | 32 | ~6.3 ms | ~22.4 ms |
/score | 64 | ~8.0 ms | ~38.7 ms |
/select | 16, k=4 | ~11.9 ms | ~20.4 ms |
/select | 32, k=8 | ~6.8 ms | ~22.4 ms |
test_long_run 50 次 | 16 | 平均 4.477 ms | P50 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。
| 截图 | 文件 |
|---|---|
| NPU 设备调用 | assets/npu_device_call.png |
| 测试结果 | assets/model_result.png |
| 适配过程 | assets/agent_workflow.png |
(图中带 maggie_Ha 水印)
PeekScorer。如需端到端(含 MobileCLIP2-S0 抽帧),需要额外加载图像编码器。k = 0 会触发 400 校验;k > T 时服务会返回全部帧并按时间排序。stratified_argmax 实现,与论文默认配置一致。@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}
}模型权重遵循 CC-BY-NC-SA-4.0;本仓库新增的 NPU 适配代码按 Apache-2.0 风格开放,便于二次集成。