VideoFlexTok(videoflextok_d18_d18_k600)实战指南:tokenize与detokenize两大API详解,附嵌套截断示例代码

原创2026-10-21 15:01:421,382 阅读

VideoFlexTok(videoflextok_d18_d18_k600)实战指南:tokenize与detokenize两大API详解,附嵌套截断示例代码

VideoFlexTok(videoflextok_d18_d18_k600)是 EPFL VILAB 团队开源的灵活长度视频分词器(video tokenizer):tokenize 一次调用把 17 帧视频压成离散 token 序列,detokenize 一次调用即可从 token 重建出视频。本文按实战顺序讲清两大 API 的用法,并给出嵌套截断的完整示例代码,帮你快速上手视频 tokenization。

为什么选 VideoFlexTok:灵活长度视频tokenization

💡 传统视频 tokenizer 输出的 token 数量是固定的;而 VideoFlexTok 的核心卖点是 Flexible-Length(灵活长度)+ Coarse-to-Fine(由粗到细):

  • 编码一个 17 帧、128×128 的视频片段,得到 5 个时间步 × 128 个 token 的序列;
  • 解码端接受任意长度 l ≤ 128 的前缀 token,你截断得越多,重建精度越低但算力消耗越小,精度与效率由你自己权衡;
  • 底层采用 FSQ 量化器(levels 为 [8, 8, 8, 5, 5, 5],共 64000 种组合)输出离散 token,解码器基于 Rectified Flow(直整流) 做去噪重建。

模型命名也直接反映了关键超参数:d18_d18 表示编码器与解码器各为 18 层 FlexTransformer,配置详情可查阅仓库中的 config.json。

关键信息 说明
输入规格 17 帧、128×128 视频片段,像素归一化到 [-1, 1]
输出 tokens 每个时间步 128 个离散 token(共 5 步)
量化方式 FSQ,64000 种 token 组合
解码器 Rectified Flow(VideoMinRFPipeline),支持 classifier-free guidance

如何快速加载VideoFlexTok模型:两种方式

方式一:从 HuggingFace Hub 一行加载(推荐,官方文档见 README.md)

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

方式二:手动加载本地权重(适合已下载 model.safetensors 的场景),借助 Hydra 的 instantiate 按 config.json 构建模型:

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)

tokenize API:把视频压缩成离散token序列

from videoflextok.utils.demo import read_mp4

# 读取视频为 (3, 17, 128, 128) 的 float 张量,像素归一化到 [-1, 1]
video_tensor = read_mp4("./data/video_examples/red_ball.mp4",
                       num_frames=17, **model.video_preprocess_args)

# 编码为 token 序列列表,每条形状 [1, 5, 128]
tokens_list = model.tokenize(video_tensor[None])

几个容易踩的点:

  1. read_mp4 的预处理参数直接透传 model.video_preprocess_args 即可(size=128、chunk_size=17),与 config.json 中的 video_preprocess_args 保持一致;
  2. 输入记得补 batch 维(video_tensor[None]);
  3. 返回的 tokens_list 是列表,每个元素是一条 [1, 5, 128] 的整数 token 序列——5 个时间步,每步 128 个 token。

嵌套截断技巧:减少token数同时保留质量

这是 VideoFlexTok 最有意思的特性。token 序列按"嵌套(nested)"方式组织——前缀 token 承载最重要的全局信息(训练时通过 MaskedNestedDropout 让模型适应任意长度输入),因此直接"掐头去尾"只保留前缀即可:

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

🎯 效果:token 总量直接减半(5 × 128 → 5 × 64),下游算力减半,重建结果保留"粗"的整体结构;k_keep 可在 1~128 之间自由调节,实现精度与效率的连续权衡。

detokenize API:直整流解码器重建视频

截断(或完整)的 token 列表可直接送入解码器:

# tokens_list 是 [1, 5, l] 的离散 token 序列列表,l <= 128
# reconst 是重建视频列表,形状 [1, 3, 17, 128, 128],归一化到 [-1, 1]
reconst = model.detokenize(
    tokens_list,
    timesteps=30,           # 去噪步数
    guidance_scale=20.,      # classifier-free guidance 强度(15~30 通常效果较好)
    perform_norm_guidance=True,  # 归一化引导,可显著改善画质
)

⚠️ 调参建议:timesteps 越大越精细但越慢;guidance_scale 低于 15 画面偏柔和、高于 30 容易过饱和;perform_norm_guidance 默认建议开启。

参数速查表:VideoFlexTok关键参数一览

参数 位置 说明
chunk_size=17 model.video_preprocess_args 每次编码的视频帧数
size=128 model.video_preprocess_args 输入分辨率(128×128)
k_keep 截断时自定义 每个时间步保留的 token 数,1~128
timesteps=30 detokenize 去噪步数,越大越精细
guidance_scale=20. detokenize 引导强度,推荐区间 15~30
perform_norm_guidance=True detokenize 归一化引导,建议开启

仓库文件与引用方式

文件 作用
README.md 模型卡:安装说明、API 示例与引用信息
config.json Hydra 模型配置:VAE、编码器、FSQ 量化器、解码器完整结构
model.safetensors 预训练模型权重

如果这项工作对你的研究有帮助,建议引用论文(完整 BibTeX 见 README.md):

@article{videoflextok,
    title={{VideoFlexTok}: Flexible-Length Coarse-to-Fine Video Tokenization},
    author={Andrei Atanov and Jesse Allardice and Roman Bachmann and others},
    journal={arXiv 2604.12887},
    year={2026},
}

📌 本仓库模型权重以 Apache License 2.0 协议发布,可放心用于研究与商业场景。

登录后查看全文
videoflextok_d18_d18_k600