VideoFlexTok是 EPFL VILAB 推出的灵活长度视频 tokenizer，videoflextok_d18_d18_k600是其预训练权重仓库。它把视频压缩成可变长度的离散 token 序列（灵活长度视频编码），再通过流匹配解码器重建视频。本文带你 10 分钟完成：从 HuggingFace 一键加载 VideoFlexTok 模型，到编码、截断、解码视频的全流程，并附关键配置速查，新手也能照做跑通。

VideoFlexTok 是什么？为什么值得用

传统视频 tokenizer 通常输出固定长度的 token，视频长一点就冗余，短一点又信息不足。VideoFlexTok 的核心思路是Flexible-Length Coarse-to-Fine（灵活长度、由粗到细）：

• 编码器：VAE 先把视频压成低维潜变量，再由 18 层FlexTransformer编码器提取出每个时间步的 128 个 token；
• 灵活长度：token 序列支持嵌套截断——保留前 k 个 token 仍然是一段合法的粗粒度描述，k 越大细节越多；
• 解码器：18 层FlexTransformer+ 流匹配（Rectified Flow）采样，从 token 序列逐步去噪重建视频。

本仓库videoflextok_d18_d18_k600命名对应两个关键规格：

模型权重以 Apache License 2.0 开源，可放心用于研究与商用。

第一步：安装与一键加载 VideoFlexTok 模型

官方安装说明位于videoflextok代码仓库（见 README.md 的 Installation 一节），本文聚焦模型加载。

方式一：从 HuggingFace Hub 一键加载（推荐）

只需两行 Python，模型权重自动下载：

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

方式二：手动加载本地 model.safetensors

如果你已下载 model.safetensors 权重文件（本仓库即包含该文件），可以绕过 Hub 直接加载：

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)

💡 两种方式加载后的model对象完全等价，后续用法一致。

第二步：读取视频并编码成离散 Token

视频编码前预处理：读取 17 帧 128×128 视频

模型对输入有固定要求：17 帧、128×128 分辨率、数值范围 [-1, 1] 的 float 张量，形状为(3, 17, 128, 128)。这些参数就写在 config.json 的video_preprocess_args字段里：

"video_preprocess_args": { "size": 128, "chunk_size": 17, "overlap_size_frames": 0 }

官方提供了一个read_mp4工具函数，自动完成裁剪与归一化：

from videoflextok.utils.demo import read_mp4 video_tensor = read_mp4("./data/video_examples/red_ball.mp4", num_frames=17, **model.video_preprocess_args) # (3, 17, 128, 128)

一行代码完成视频 tokenize

# 输出为 token 序列列表，每个时间步一段，形状 [1, 5, 128] tokens_list = model.tokenize(video_tensor[None])

tokens_list是一个列表：每个时间步对应一段 128 个的离散 token 序列。这就是"灵活长度"的起点——每个时间步的 token 数可以不同。

第三步：灵活长度截断，按需控制细节与码率

这是 VideoFlexTok 最实用的特性。token 序列按嵌套顺序（nested ordering）排列：越靠前越重要。你只需截断到前 k 个，就能得到一段"合法"的粗粒度 token 序列，k 越小描述越抽象、解码越快：

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

这种"由粗到细"的特性让它非常适合做视频检索摘要、分层传输、生成式视频模型的条件输入等场景。

第四步：用流匹配解码器重建视频

拿到 token 序列后，调用detokenize即可重建视频。它内部使用 VideoFlexTok 的Rectified Flow 解码器逐步去噪：

# tokens_list: 每段形状 [1, 5, l]，l <= 128 # reconst: 列表，每项为 RGB 视频张量 [1, 3, 17, 128, 128]，范围 [-1, 1] reconst = model.detokenize( tokens_list, timesteps=30, # 去噪步数 guidance_scale=20., # 无分类器引导强度（15~30 效果较好） perform_norm_guidance=True, # 归一化引导，提升重建稳定度 )

解码参数怎么选

• timesteps：去噪步数，越大越精细、越慢，默认示例用 30；
• guidance_scale：引导强度，官方建议15~30区间，20是通用起点；
• perform_norm_guidance：开启归一化引导可改善画面质量，建议保持True。

关键文件与配置速查

config.json 里值得了解的几个要点：

• vae.tokenizer_id: "vidtok_kl_causal_488_16chn"：底层 VAE 是因果式 VidTok，潜变量 16 通道，force_vae_encode: false表示可复用缓存的潜变量加速推理；
• regularizer（FSQ）：levels: [8,8,8,5,5,5]定义了 6 维离散量化空间，即码本 k600 的来源；
• encoder/decoder：两个 18 层FlexTransformer（dim: 1152），解码器额外接了VideoMinRFPipeline流匹配采样管线，out_channels: 16输出 VAE 潜变量空间。

常见问题排查

Q：加载模型报 ImportError？先确认已安装videoflextok代码包并安装safetensors、hydra-core依赖（安装步骤见 README.md 的 Installation 一节）。

Q：tokenize的输入形状是什么？(B, 3, 17, 128, 128)，B 为 batch 数，数值范围[-1, 1]。直接用read_mp4(..., **model.video_preprocess_args)即可自动对齐参数。

Q：截断 token 后解码报错或质量骤降？截断必须保持嵌套顺序（只保留前缀），不要随机抽取；k 过小（如 < 16）时画面会明显抽象化，属预期行为。

Q：解码速度太慢？先降低timesteps（如 30 → 10），guidance_scale保持 15~20 之间即可，通常质量损失很小。

下一步可以做什么

• 把tokenize输出的离散 token 序列存盘，作为视频检索或视频生成模型的输入；
• 尝试不同k_keep截断长度，对比重建质量与推理速度的权衡曲线；
• 阅读论文了解训练细节（引用信息见 README.md 的 Citation 章节）。

照以上四步操作，从加载到重建，10 分钟即可完整跑通 VideoFlexTok 的"视频 → 灵活长度 token → 视频"全流程。