p
pnflly/videoflextok_d18_d18_k600
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

VideoFlexTok d18_d18_k600 昇腾 NPU 适配

模型是什么

EPFL-VILAB/videoflextok_d18_d18_k600 是 EPFL 视觉智能实验室与 Apple 合作发布的可变长视频 tokenizer(VideoFlexTok: Flexible-Length Coarse-to-Fine Video Tokenization, arXiv 2026)。它的职责是把原始视频编码为离散 token 供下游语言模型 / 扩散模型使用,采用 VidTok VAE → 18 层 FlexTransformer 编码器 → FSQ 量化的编码链,配以 MinRF rectified-flow 解码器做重建。

与大多数视频 tokenizer 的一个显著区别:它支持可变长 token 数(通过 register 采样与嵌套截断),从而用更少的 token 表示粗粒度语义、用更多 token 表示细粒度细节,这是"flexible-length"一词的由来。FSQ 而非 VQ 码本,让量化过程无需可学习 embedding 表,直接对 6 维 latent 逐维量化。

本仓库的目标是把这条编码链在 昇腾 Ascend910 NPU 上跑通并服务化——输入一段 RGB 视频,得到 FSQ 离散 token 序列。

适配思路

原版编码器重度依赖 PyTorch 2.x 的 flex_attention(Triton 内核 + torch.compile),该 API 在昇腾 NPU 上报 FlexAttention is only supported on CUDA, CPU or HPU devices。我们的适配分三层处理:

  1. 注意力替换:写了一个与官方 FlexAttention 权重布局完全一致的 attention_npu 模块,把 flex_attention(q,k,v,block_mask) 换成 F.scaled_dot_product_attention(q,k,v,attn_mask=dense_mask)。block_mask 由 packer 生成后直接物化为稠密布尔张量传入,语义逐位一致,权重零改动。
  2. 掩码物化:改写了 flex_seq_packing.py 的 create_block_mask_cached,不再走 create_block_mask(Triton 内核),而是按 mask 函数直接生成 [B,H,M,N] 布尔矩阵,天然兼容 NPU 的 SDPA。
  3. 权重直载:model_loader.py 用 safe_open 把 checkpoint 中 video_tokenizer.vae.* 与 video_tokenizer.encoder.* 的权重流式装载(跳过 decoder 部分),避免 4.23GB 全量读入内存,同时规避 vLLM AutoWeightsLoader 对 VidTok mix_factor 标量 Parameter 的处理问题。

服务侧通过 vLLM OOT 插件(videoflextok_vllm)注册架构,is_pooling_model=True + is_attention_free=True,跑 --runner pooling,对外提供 OpenAI 兼容 /pooling(task=token_classify)。视频像素用固定点编码(1 + round((v+1)*10000))变成 token 流送入。

验证环境

项目版本/配置
NPU昇腾 Ascend910(64GB HBM,绑定 Phy-ID 11)
CANN8.5.1(npu-smi 25.5.5)
Python3.11.14
torch / torch_npu2.9.0 / 2.9.0.post1+gitee7ba04
vLLM / vLLM-Ascend0.18.0 / 0.18.0
权重model.safetensors(4.23GB,741 张量:VAE 416 + encoder 132 + decoder 193)

服务启动

# 1. 准备模型目录(config.json + model.safetensors 软链)
# 2. 启动 vLLM-Ascend pooling 服务
export PYTHONPATH=/opt/atomgit:/opt/atomgit/adapt:/opt/atomgit/adapt/videoflextok_ascend
export TORCHDYNAMO_DISABLE=1
export ASCEND_VISIBLE_DEVICES=1
vllm serve /opt/atomgit/models/EPFL-VILAB/videoflextok_d18_d18_k600_servable \
  --tokenizer /opt/atomgit/adapt/videoflextok_tokenizer \
  --load-format safetensors --dtype float32 \
  --max-model-len 60000 --max-num-seqs 2 \
  --port 8060 --host 127.0.0.1 \
  --runner pooling --enforce-eager \
  --gpu-memory-utilization 0.15 \
  --no-enable-prefix-caching --no-enable-chunked-prefill \
  --served-model-name videoflextok-d18-d18-k600

# 3. 就绪检查
curl http://127.0.0.1:8060/v1/models

关键环境依赖:sitecustomize.py(随 PYTHONPATH 加载)会做两件与昇腾运行时强相关的事——把 CANN TBE 的 multiprocessing.get_context("forkserver") 重定向为 fork,以及给 os.kill 打补丁吞掉 TBE 守护进程退出竞态的 ProcessLookupError。这两处是视频类模型(带 3D 卷积 + 注意力,首次前向触发 TBE 编译)能在 vLLM 多进程下稳定跑通的前提。

Smoke 验证

python3 inference.py --seed 42

输入为 [1,3,17,32,32] 的随机视频(像素归一化到 [-1,1]),输出 1280 维([5,256] 展平)FSQ token。实测样例:

输出前 20 : [24796, 22765, 42803, 49368, 42133, 42139, 22748, 16155, 58155, 29854, 47844, 32412, 1772, 3803, 3220, 29275, 3307, 58092, 35547, 46299]
输出末 20 : [46949, 19163, 31979, 32027, 29412, 31963, 29468, 19186, 44964, 19171, 19163, 19163, 31971, 31971, 33270, 51926, 32467, 29403, 31963, 31963]
去重 token : 764 / 1280
推理耗时   : 0.136 s(预热后)

性能参考

场景数值
单请求(预热后)0.14 s
8 并发0.3–0.6 s
服务 HBM~2.2 GB
首次请求10–20 s(TBE 算子编译)

精度测评

以 CPU 官方参考为基准,对同一随机视频比较 NPU / CPU 输出:

指标数值
token 一致率~95%(1280 token 中约 60 个边界翻转)
翻转根因FSQ round() 在量化边界上对浮点误差敏感
latent 平均误差~0.008
latent 最大误差~3.9(个别边界点)
FP32 vs BF16FP32 显著降低翻转率,故服务强制 FP32

FSQ 是离散量化器,边界附近的微小数值差异会映射到相邻 codebook index。这属于精度边界现象而非适配错误;对下游重建/生成任务影响可忽略(相邻 codebook 对应的 latent 值非常接近)。

注意事项

  1. 算子编译:VidTok VAE 的 3D 因果卷积首次前向会触发 CANN TBE 编译,多窗口并行时偶发 EngineCore 崩溃——sitecustomize 已修复 forkserver 与守护进程竞态,仍建议绑定独立空闲 NPU。
  2. 精度敏感:保持 --dtype float32,勿用低精度加载。
  3. attention-free 约束:必须关 prefix caching 与 chunked prefill。
  4. 服务范围:本仓库暴露 encode(视频→token)路径;decode(token→视频)需官方 decoder 服务。
  5. 端口:8060 被占用时换空闲端口,勿干扰其他窗口进程。

目录

videoflextok_d18_d18_k600/
├── inference.py      # 推理客户端
├── README.md
├── requirements.txt
└── assets/
    └── README.md