eardoi/videoflextok_d18_d28-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

VideoFlexTok:灵活长度粗到细视频令牌化(昇腾 NPU 适配)

项目主页 | 论文 | GitHub | BibTeX

官方实现与预训练模型:
VideoFlexTok: Flexible-Length Coarse-to-Fine Video Tokenization,arXiv 2026
Andrei Atanov*、Jesse Allardice*、Roman Bachmann、Oğuzhan Fatih Kar、R Devon Hjelm、David Griffiths、Peter Fu、Afshin Dehghan、Amir Zamir

VideoFlexTok 以可变长度令牌序列表示视频,结构采用粗到细(coarse-to-fine)方式: 前序令牌捕获语义、运动等抽象信息,后续令牌逐步补充细粒度细节。

安装

安装说明请参考 https://github.com/apple/ml-videoflextok。

使用方法

直接从 HuggingFace Hub 加载 VideoFlexTok 模型:

from videoflextok.wrappers import VideoFlexTokFromHub
model = VideoFlexTokFromHub.from_pretrained('EPFL-VILAB/videoflextok_d18_d28').eval()

也可以手动下载本仓库中的 model.safetensors 权重,并用辅助函数加载:

from hydra.utils import instantiate
from videoflextok.utils.checkpoint import load_safetensors

ckpt, config = load_safetensors('/path/to/model.safetensors')
model = instantiate(config).eval()
model.load_state_dict(ckpt)

加载 VideoFlexTok 模型后,可对视频进行编码:

from videoflextok.utils.demo import read_mp4
# 将示例视频加载为 (3, T, 256, 256) 的 float 张量,归一化到 [-1, 1]
# 将以约 8 FPS 采样帧,确保 T = 1 + K * 16(K 为不小于 1 的整数),
# 这是 VideoFlexTok 分块机制所要求的
video_tensor = read_mp4("./data/video_examples/red_ball.mp4", fps=8)  # (C, T, H, W)

# 编码为离散令牌序列列表,每个序列形状为 [1, t, 256]
# 将自动以滑动窗口方式应用编码器,并按序列维度拼接所得令牌
# t = 1 + K * 4:每个 16 帧块被令牌化为 4 个令牌,第一个令牌对应第一帧
tokens_list = model.tokenize(video_tensor[None])

令牌序列可进行嵌套式截断:

k_keep = 64  # 例如,每个时间步只保留 256 个令牌中的前 64 个
tokens_list = [t[..., :k_keep] for t in tokens_list]

使用 VideoFlexTok 的整流流(rectified flow)解码器还原视频:

# tokens_list 为 [1, t, l] 的离散令牌序列列表,其中 l <= 256
# reconst 为 [1, 3, T, 256, 256] 的 RGB 视频张量列表,归一化到 [-1, 1]
reconst = model.detokenize(
    tokens_list,
    timesteps=30,          # 去噪步数
    guidance_scale=20.,    # 无分类器引导尺度(通常 15-30 效果较好)
    perform_norm_guidance=True,  # 参见 https://arxiv.org/abs/2410.02416
)

昇腾 NPU 适配说明

  • 本仓库为 VideoFlexTok d18/d28(约 1.06B 参数) 在昇腾 Ascend 910B 上的推理适配。
  • inference.py 在 npu:0 上加载完整模型,并运行核心 Transformer 自注意力 (FlexSelfAttention)前向;注意力经 scaled_dot_product_attention (torch_npu 原生)路由,替代仅支持 CUDA/CPU/HPU 的 flex_attention。
  • 说明:完整 packed-sequence 令牌化路径依赖 flex_attention 块掩码, 其稠密形式在 NPU 上不可物化;核心 Transformer 前向为 NPU 已验证的计算。
  • 设备自动回退:NPU 不可用时回退到 CPU。

引用

如果本仓库对您有帮助,欢迎引用我们的工作:

@article{videoflextok,
    title={{VideoFlexTok}: Flexible-Length Coarse-to-Fine Video Tokenization},
    author={Andrei Atanov and Jesse Allardice and Roman Bachmann and O{\u{g}}uzhan Fatih Kar and Peter Fu and David Griffiths and Devon Hjelm and Afshin Dehghan and Amir Zamir},
    journal={arXiv 2026},
    year={2026},
}

许可

本仓库中的模型权重基于 Apache License 2.0 发布。