VAR 视觉自回归建模实战指南：Next-Scale 预测范式下的图像生成、训练与零样本推理-平芜编程栈

计算机视觉
媒体生成
深度学习
大模型

【免费下载链接】VAR

[NeurIPS 2024 Best Paper Award][GPT beats diffusion🔥] [scaling laws in visual generation📈] Official impl. of "Visual Autoregressive Modeling: Scalable Image Generation via Next-Scale Prediction". An *ultra-simple, user-friendly yet state-of-the-art* codebase for autoregressive image generation!

项目地址：https://gitcode.com/GitHub_Trending/va/VAR

点击查看免费下载

本文以 Visual Autoregressive Modeling（VAR）官方开源仓库（NeurIPS 2024 收录论文Visual Autoregressive Modeling: Scalable Image Generation via Next-Scale Prediction的官方实现）为对象，系统讲解其核心思想、模型配置、环境安装、ImageNet 全量训练脚本与零样本采样推理流程。读者将掌握 VAR 的 "next-scale prediction" 生成范式、各尺寸模型（d16–d36）的选择与部署方法，以及从数据准备、分布式训练到 FID 评测的完整实操路径。

VAR 核心范式：从 "next-token" 到 "next-scale"

Visual Autoregressive Modeling（VAR）重新定义了图像上的自回归学习方式：把图像生成建模为coarse-to-fine（从粗到细）的 "next-scale prediction"（下一尺度预测）或 "next-resolution prediction"（下一分辨率预测），而不是传统光栅扫描式的 "next-token prediction"（下一 token 预测）。

在实现层面，VAR 将一张图像编码为K 级多尺度 token 金字塔，每级尺度对应的 patch 数量由patch_nums决定。官方默认配置为(1, 2, 3, 4, 5, 6, 8, 10, 13, 16)，即 10 个尺度；每个尺度的 token 数为pn × pn（如第 1 级为1×1，第 10 级为16×16）。全部 token 总数L = sum(pn²) = 680，该数值在 models/var.py 中通过self.L = sum(pn ** 2 for pn in self.patch_nums)计算得到。训练时 Transformer 按尺度顺序依次预测每一级的 token 分布；推理时则逐级采样、逐级叠加，最终解码出完整图像。256 分辨率对应patch_size=16，因此第 10 级16×16 × 16px = 256×256；512 分辨率对应的 patch 序列见下文训练参数一节。

与扩散模型相比，VAR 证明了 GPT 风格的自回归模型可以在视觉生成任务上达到超越扩散模型的水平；同时论文观察到 VAR Transformer 中存在可预测的power-law（幂律）scaling laws，为视觉生成模型的规模扩展提供了可量化的规律。这些结论详见论文原文（arXiv: 2404.02905），本文聚焦仓库内可直接运行、可复现的工程细节。

VAR zoo：预训练模型清单与权重准备

仓库提供如下已发布的 VAR 模型权重（分辨率、FID、相对推理成本与参数量见下表），可直接用于生成与推理：

模型	分辨率	FID	相对成本	参数量	权重文件
VAR-d16	256	3.55	0.4	310M	`var_d16.pth`
VAR-d20	256	2.95	0.5	600M	`var_d20.pth`
VAR-d24	256	2.33	0.6	1.0B	`var_d24.pth`
VAR-d30	256	1.97	1	2.0B	`var_d30.pth`
VAR-d30-re	256	1.80	1	2.0B	`var_d30.pth`
VAR-d36	512	2.63	—	2.3B	`var_d36.pth`

使用前提：加载上述任意 VAR 模型前，必须先下载配套的 VQVAE 权重vae_ch160v4096z32.pth。该 VQVAE 承担图像与离散 token 之间的编解码（词表大小V=4096、潜在通道Cvae=32、通道基数ch=160），这些超参数在 train.py 的build_vae_var(V=4096, Cvae=32, ch=160, share_quant_resi=4, ...)调用中被硬编码，并在训练启动时自动下载缺失的 VQVAE 权重（train.py）。

从源码结构看（models/init.py），build_vae_var会先构建VQVAE（test_mode=True，参数冻结、置为 eval 态），再构建VAR主干（embed_dim = depth*64、num_heads = depth、drop_path_rate = 0.1*depth/24，并调用init_weights完成初始化）。VARHF类（models/var.py）通过PyTorchModelHubMixin提供 Hugging Face Hub 加载兼容入口，便于在 HF 生态中直接加载权重。

环境安装与数据集准备

按 README 的官方步骤，环境搭建分三步：

安装 PyTorch：torch>=2.0.0（torch.compile、scaled_dot_product_attention等特性依赖 2.0 及以上版本）。
安装其余依赖：pip3 install -r requirements.txt。
准备 ImageNet 数据集，目录结构必须与官方约定一致：

/path/to/imagenet/: train/: n01440764: many_images.JPEG ... n01443537: many_images.JPEG ... val/: n01440764: ILSVRC2012_val_00000293.JPEG ... n01443537: ILSVRC2012_val_00000236.JPEG ...

训练时务必通过--data_path=/path/to/imagenet传入数据集根路径；若未指定，utils/arg_util.py 会直接抛出ValueError提示。

可选加速（强烈建议生产环境启用）：安装并编译flash-attn与xformers以加速注意力计算。代码会自动探测并启用已安装的算子——models/basic_var.py 中依次尝试导入flash_attn的dropout_add_layer_norm/fused_mlp_func/flash_attn_func、xformers.ops.memory_efficient_attention，最后回退到 PyTorch 原生scaled_dot_product_attention。SelfAttention会依据导入结果自动设置using_flash/using_xform标志（models/basic_var.py），因此无需修改代码即可自动加速。

训练脚本与超参数全解

使用torchrun以 8 卡分布式方式在 ImageNet 256×256 或 512×512 上训练 VAR-{d16, d20, d24, d30, d36-s}：

# d16, 256x256 torchrun --nproc_per_node=8 --nnodes=... --node_rank=... --master_addr=... --master_port=... train.py \ --depth=16 --bs=768 --ep=200 --fp16=1 --alng=1e-3 --wpe=0.1 # d20, 256x256 torchrun --nproc_per_node=8 --nnodes=... --node_rank=... --master_addr=... --master_port=... train.py \ --depth=20 --bs=768 --ep=250 --fp16=1 --alng=1e-3 --wpe=0.1 # d24, 256x256 torchrun --nproc_per_node=8 --nnodes=... --node_rank=... --master_addr=... --master_port=... train.py \ --depth=24 --bs=768 --ep=350 --tblr=8e-5 --fp16=1 --alng=1e-4 --wpe=0.01 # d30, 256x256 torchrun --nproc_per_node=8 --nnodes=... --node_rank=... --master_addr=... --master_port=... train.py \ --depth=30 --bs=1024 --ep=350 --tblr=8e-5 --fp16=1 --alng=1e-5 --wpe=0.01 --twde=0.08 # d36-s, 512x512 (-s 表示 saln=1，即 shared AdaLN) torchrun --nproc_per_node=8 --nnodes=... --node_rank=... --master_addr=... --master_port=... train.py \ --depth=36 --saln=1 --pn=512 --bs=768 --ep=350 --tblr=8e-5 --fp16=1 --alng=5e-6 --wpe=0.01 --twde=0.08

以上命令中各核心参数的含义与默认值（取自 utils/arg_util.py 的Args类）如下：

参数	默认值	含义与说明
`--depth`	16	VAR Transformer 的层数（`build_vae_var`中同时决定`embed_dim=depth*64`、`num_heads=depth`）
`--bs`	768	全局 batch size；每卡 batch 自动计算为`round(bs/ac/world_size)`的倍数（utils/arg_util.py）
`--ep`	250	训练总 epoch 数
`--fp16`	0	`1`使用 fp16 混合精度，`2`使用 bf16
`--tblr`	1e-4	基础学习率；实际`tlr = ac × tblr × glb_batch_size / 256`（utils/arg_util.py），即随全局 batch 线性缩放
`--alng`	1e-5	AdaLN 中 gamma 通道初始化的乘子（对应`init_adaln_gamma`，models/var.py）
`--wpe`	0.01	训练结束时学习率衰减到的比例（LR warmup 起点为`--wp0`，默认 0.005）
`--twde`	0	训练结束时的权重衰减；默认沿用`--twd`（默认 0.05）
`--saln`	False	是否使用共享 AdaLN（`SharedAdaLin`）；d36-s 需设为 1
`--pn`	1_2_3_4_5_6_8_10_13_16	patch 序列；`256`→10 级默认序列，`512`→`1_2_3_4_6_9_13_18_24_32`，`1024`→14 级序列（utils/arg_util.py）
`--ac`	1	梯度累积步数
`--tclip`	2.0	梯度裁剪阈值（≤0 表示不裁剪）
`--opt`	adamw	优化器（`adam`/`adamw`，均为 AdamW，`betas=(0.9, 0.95)`，见 train.py）
`--ls`	0.0	标签平滑（对应`CrossEntropyLoss(label_smoothing=...)`，见 trainer.py）
`--vfast`/`--tfast`	0	是否对 VAE / VAR 使用`torch.compile`：1→`reduce-overhead`，2→`max-autotune`（utils/arg_util.py）

其他可选参数还包括：--anorm（注意力 L2 归一化，默认 True）、--fuse（是否使用 fused 算子，默认 True）、--hflip（水平翻转增强）、--mid_reso（先放大到 1.125 倍再裁剪）、--pg/--pg0/--pgwp（渐进式训练，默认关闭pg=0.0）、--seed、--tf32（默认 True）。此外，--data_path为必填项，--exp_name用于标识实验。

训练产出与监控：训练会创建local_output目录保存 checkpoint 与日志。可通过local_output/log.txt与local_output/stdout.txt查看进度，或运行tensorboard --logdir=local_output/可视化 loss、acc 与学习率曲线（TensorBoard 日志目录按tb-VARd{depth}__pn{...}__b{bs}ep{ep}...命名，见 utils/arg_util.py）。每个 epoch 结束后，训练循环会打印Lm/Lt/Accm/Acct（整体与最后一级尺度的 loss 与准确率）；每 10 个 epoch（或最终 epoch）还会执行一次验证集评估并保存 checkpoint（train.py）。

自动断点续训：若实验被中断，直接重跑相同命令即可自动从local_output/ckpt*.pth中最新 checkpoint 恢复。该逻辑由auto_resume实现（utils/misc.py）：它按修改时间倒序查找ar-ckpt*.pth，读取其中的epoch、iter、trainer与args状态，从而无缝衔接训练。

零样本推理：采样、CFG 与 FID 评测

仓库核心推理接口是 models/var.py 中的VAR.autoregressive_infer_cfg，它以(B, 3, H, W)的[0,1]图像张量形式返回生成结果。官方推荐的 FID 评测采样配置为：

var.autoregressive_infer_cfg(..., cfg=1.5, top_p=0.96, top_k=900, more_smooth=False)

关键参数（对应 models/var.py 的 docstring）：

B：batch size；
label_B：ImageNet 类别标签；传None时按均匀分布随机采样；
g_seed：随机种子，便于可复现采样；
cfg：Classifier-Free Guidance（无分类器引导）强度，默认 1.5；
top_k/top_p：top-k / top-p 截断采样参数（0 表示不启用对应截断）；
more_smooth：是否用 Gumbel Softmax 平滑预测（仅用于可视化，不用于 FID/IS 基准评测）。

渐进式 CFG 的源码实现：VAR 的引导强度随尺度推进而增强。在 models/var.py 中，当前尺度进度ratio = si / num_stages_minus_1，条件分支与无条件分支（batch 翻倍，类别嵌入中混入num_classes作为无类别 token）的 logits 按logits = (1 + t)·logits[:B] - t·logits[B:]融合，其中t = cfg · ratio。这正是 README 所说"使用相对较小的cfg=1.5在图像质量与多样性之间折中"的原因。

采样策略建议（README 原文要点）：可将cfg调至5.0，或使用autoregressive_infer_cfg(..., more_smooth=True)（Gumbel Softmax 温度tau = max(0.27·(1 - ratio·0.95), 0.005)，见 models/var.py）以获得更好的视觉质量；但 FID/IS/Precision/Recall 等指标评测必须保持more_smooth=False的默认路径（直接查表取 embedding，models/var.py）。

逐尺度自回归生成流程（从源码推断）：推理开始时对所有 block 开启 KV cache（models/var.py），先以类别嵌入与pos_start/lvl_pos初始化第 1 尺度输入；随后对每个尺度si前向全部 block 得到 logits，经 CFG 融合与sample_with_top_k_top_p_采样（实现见 models/helpers.py，先 top-k 屏蔽再 top-p 累积概率截断，最后torch.multinomial采样），再由 VQVAE 量化器get_next_autoregressive_input将当前尺度 token 上采样叠加进f_hat，插值出下一尺度的输入（models/var.py、models/quant.py）；完成后关闭 KV cache 并调用fhat_to_img解码为图像（models/var.py）。

FID 评测流水线：

用上述配置采样 50,000 张图像（每个类别 50 张），以PNG（而非 JPEG）格式保存到指定文件夹；
调用create_npz_from_sample_folder(sample_folder)将文件夹打包为.npz（utils/misc.py，内部严格校验 PNG 数量恰为 50,000，否则报错）；
使用 OpenAI 官方 FID 评测工具包（guided-diffusion 的 evaluations 模块），配合 ImageNet 256×256（VIRTUAL_imagenet256_labeled.npz）或 512×512（VIRTUAL_imagenet512.npz）的参考真实分布 npz，计算 FID、IS、Precision 与 Recall。

从源码理解 VAR 的模型骨架

VAR 的完整前向/推理链路分布在 models/var.py、models/basic_var.py、models/vqvae.py 与 models/quant.py 中，关键构成如下：

VAR 主干（models/var.py）：

word_embed（Linear(Cvae, C)）：把 VQVAE 的 token embedding 映射为 Transformer 维度；
class_emb（Embedding(num_classes+1, C)）：类别嵌入，额外第num_classes位用作 CFG 无条件 token；训练时以cond_drop_rate=0.1的概率随机替换为无条件类别（models/var.py），这是 CFG 得以生效的根基；
pos_1LC：绝对位置嵌入；lvl_embed：尺度级嵌入（类似 GPT 的 segment embedding，用于区分 token 金字塔的不同层级）；
blocks：depth个AdaLNSelfAttn块（models/basic_var.py），每个块由 AdaLN 条件化的自注意力与 FFN 组成，支持shared_aln（共享 AdaLN，参数ada_gss与条件相加）与非共享两种模式，并线性递增的 stochastic depth（drop_path_rate）；
head_nm（AdaLNBeforeHead）+head（Linear(C, V)）：输出词表V=4096的 logits。

训练注意力掩码：训练阶段使用逐尺度因果掩码attn_bias_for_masking——低尺度 token 可以关注同尺度及之前所有 token，高尺度 token 只能看到"过去"（models/var.py）；推理阶段因 KV cache 存在而不使用该掩码（注释与调用均表明attn_bias=None）。

VQVAE 多尺度残差量化（models/quant.py）：VectorQuantizer2沿v_patch_nums从粗到细逐级执行最近邻量化：每级先在area模式下插值到该尺度，查找最近词表向量得到 token 序列idx_Bhw，再经残差模块Phi（φ(x) = (1-resi_ratio)·x + resi_ratio·conv(x)）重建f_hat并累加、从残差中扣除（f_rest -= h_BChw）。quant_resi=0.5与share_quant_resi=4（4 个部分共享的 φ 层）决定了残差重建的权重分配。这套"逐尺度残差叠加"机制正是 next-scale 预测能跨尺度传播信息、并实现零样本泛化的关键组件。

训练循环与评估逻辑（补充）

训练入口 train.py 的主流程为：init_dist_and_get_args初始化分布式环境与参数 →build_everything自动续训、构建数据与模型、下载 VQVAE、组装AmpOptimizer（fp16/bf16 混合精度 + 梯度裁剪）与VARTrainer→ 逐 epoch 训练与评估。VARTrainer.train_step（trainer.py）通过img_to_idxBl把 GT 图像转为多尺度 token 序列、idxBl_to_var_input构造 teacher-forcing 输入，再以带标签平滑的交叉熵计算 loss；eval_ep则在验证集上报告整体与尾部（最后一级尺度）的 loss 与准确率（trainer.py）。

扩展与衍生生态

自 2024-04 发布以来，VAR 已被 NeurIPS 2024 收录（Oral，并获 Best Paper Award），官方后续在 2025 年陆续发布了基于 VAR 的文本到图像（Infinity，CVPR 2025 Oral）与文本到视频（InfinityStar，NeurIPS 2025 Oral）工作。社区亦涌现了大量基于 VAR 的衍生研究（如高效解码、免引导生成、图像编辑、超分与 3D 生成等），README 的 "Third-party Usage and Research" 一节按时间线汇总了这些工作及其链接，读者可自行查阅并对照复现。

License 与引用

本项目采用 MIT License，详见 LICENSE。若 VAR 对你的研究有所帮助，可按如下 BibTeX 引用：

@Article{VAR, title={Visual Autoregressive Modeling: Scalable Image Generation via Next-Scale Prediction}, author={Keyu Tian and Yi Jiang and Zehuan Yuan and Bingyue Peng and Liwei Wang}, year={2024}, eprint={2404.02905}, archivePrefix={arXiv}, primaryClass={cs.CV} }

结语

VAR 用 "next-scale prediction" 一举将 GPT 风格自回归模型带入超越扩散模型的行列，并在 ImageNet 256/512 上以极简、用户友好的代码库提供了端到端可复现的完整链路：从多尺度 VQVAE 编码、10 级 token 金字塔的因果 Transformer 训练，到渐进式 CFG 采样与 FID 评测。无论你是想复现论文结果、微调新类别，还是将其作为自回归视觉生成研究的起点，本仓库的 train.py、models/、utils/ 都值得逐行细读。