VideoFlexTok(videoflextok_d18_d18_k600)实战指南:tokenize与detokenize两大API详解,附嵌套截断示例代码
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])
几个容易踩的点:
read_mp4的预处理参数直接透传model.video_preprocess_args即可(size=128、chunk_size=17),与 config.json 中的video_preprocess_args保持一致;- 输入记得补 batch 维(
video_tensor[None]); - 返回的
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 协议发布,可放心用于研究与商业场景。