推理优化
WorldFoundry 推理加速哪些可以开、哪些组合会被拒绝,以及如何确认开关真正生效。
实验性质
这些优化仍是实验性质。它们可能变更,未必适用于每个模型,也不应被当作已支持的生产契约。
WorldFoundry 只把「有公开开关、且主链会消费」的技术算作可用。参数被接受不等于加速。forward 之后读 runtime_optimization_report() 里的 requested / effective / fallbacks。
可插拔 diffusion 加速补充 Sol-Engine / FlashDreams 对照、原生 SANA/Wan 插件、撤销与请求隔离,以及完整视频测试通过和淘汰的配置。
下面点名的开关,主要针对 原生 Wan 2.1 / Wan 2.2 管线(Wan2p1*、Wan2p2*,含 VACE)。Wan 2.5 / 2.6 / 2.7 是托管 API,没有本地 kernel 开关。其他原生 recipe 只共享一部分(dtype、offload,有的还有 attention 或 VAE tiling)。家族 runtime(LTX、CogVideoX 等)用自己的参数,不要把 Wan 的 key 抄过去。
接受 ≠ 生效
缺 kernel、校准、进程组或 checkpoint 权重时,构建期失败,或明确走 dense / SDPA fallback。只有 wrapper(*-wrapper-installed (runtime-pending))不算加速。
默认建议
首次运行 vs 吞吐
首次运行 / 要接近官方观感。 用目录默认值:torch_dtype="bfloat16";显存够就 offload_mode="resident"(Studio 对 Wan2.2 TI2V-5B 的默认),不够再用 async-block。不要开 feature cache、近似 attention、量化、CUDA Graph、TAEW preview。官方 benchmark 不要减 steps 或改 CFG。
同一 checkpoint 追吞吐。 继续常驻 BF16。按 GPU 把 attention_backend 设成真实的 Flash / Sage,再开 fuse_qkv=True、fused_rope=True、static_cross_kv=True。compile=True 只在 warmup 之后再开——第一次 compiled forward 会很慢。解码 OOM 或占比过高时,再开 Wan VAE 空间 tiling / 时间 chunk。只有在接受跳过 DiT step 时,才开一种 feature cache。
可以做
这些控制已经接入。用 from_pretrained(...)、Workspace 的 load JSON,或该模型 load schema 上的 worldfoundry-eval run --pipeline.load.<kebab-name>。
精度与放置
放置
- torch_dtype / dit_weight_dtype怎么开bfloat16 / bf16
DiT 用 BF16 跑。FP32 checkpoint 加载时转换。这是正常生产精度,不是额外实验。
适用范围原生 Wan 2.1 / 2.2;以及其他把 dtype 传进 RuntimePolicy 的原生 recipe
- offload_mode=resident别名none / fast / resident
权重量在 GPU。装得下时最快。Studio 在 H100 级卡上对 Wan2.2 TI2V-5B 默认 resident。
适用范围调用 parse_offload_policy 的原生视觉 diffusion 加载器
- offload_mode=async-block别名block / cpu / layer
逐层 CPU master + pinned H2D 预取(最多两层常驻)。只在显存紧时用。Wan VAE 仍常驻,只有 DiT offload。
注意不能和量化、device_map=balanced 一起用
- offload_mode=component怎么开offload_mode="component"
整模块 CPU offload。该组件必须声明 vram_module_map。
适用范围声明了 wrapper map 的组件
- device_map=balanced怎么开device_map="balanced"
把 transformer 层切到可见 GPU。要求 offload_mode=none,权重留在显存。
适用范围声明了 layer_container 的模块
- 怎么开inplace_residual=True
inplace_residualWan DiT 原地 residual,降低激活显存。仅推理;autograd 下会关掉。
适用范围仅原生 Wan DiT
Attention backend
Backend
- 取值auto / flash / flash2 / flash3 / flash4 / sage / sage3 / xformers / sdpa / torch
attention_backenddispatcher 选 kernel;provider 不可用或 shape 不合格时报告 SDPA。auto 是稳妥默认。
适用范围原生 Wan;HunyuanVideo 也接受 attention_backend。Studio 下拉:auto、torch、flash_attn_2、flash_attn_3、sage、xformers
- WORLDFOUNDRY_ATTENTION_BACKEND环境变量auto / flash / cudnn / efficient / math
调用 install_worldfoundry_inference_infra 的进程级 SDPA 策略。flash_attention_2 这类名字会映射到 auto,除非你在管线上钉死 dispatcher backend。
相关WORLDFOUNDRY_ENABLE_TF32(默认开)、WORLDFOUNDRY_MATMUL_PRECISION=high、WORLDFOUNDRY_DETERMINISTIC=1
精确或数值等价的 Wan kernel
Kernel
- 怎么开fuse_qkv=True
fuse_qkv合并 Q/K/V 投影。可选 qkv_strategy=auto|packed|split 和 qkv_split_threshold(Studio 默认 8192)。
适用范围原生 Wan DiT。forward 后确认 fused_blocks 和真实投影调用
- 怎么开fused_rope=True
fused_rope融合 3D RoPE。可与 Ulysses SP 组合(kernel 接收 rank offset 与 padding)。rope_precision 为 fp32 或 fp64。
适用范围原生 Wan DiT
- 怎么开static_cross_kv=True
static_cross_kv复用本次请求的文本 cross-attention K/V。Studio 对 Wan2.2 TI2V-5B 默认打开。不能和 CUDA Graph 一起用。
适用范围原生 Wan DiT
Compile 与 CUDA Graph
Compile
- 怎么开compile=True 或 torch_compile=True
compile对绑定的 forward 做 torch.compile。可选 compile_mode(default / reduce-overhead / max-autotune / max-autotune-no-cudagraphs)、compile_backend、compile_fullgraph、compile_dynamic。第一次请求要付 compile + autotune 成本。
另外走 compile_module_if_enabled 的进程可用 WORLDFOUNDRY_TORCH_COMPILE=1
- 怎么开cuda_graph=True
cuda_graph捕获并 replay 形状稳定的 Wan DiT 内层调用。默认关。和 Inductor 一起用时,compile_mode 必须是 max-autotune-no-cudagraphs,避免套娃 Graph。
会拒绝sequence parallel、feature cache、近似 attention、static_cross_kv、自定义 Inductor compile_options
并行
并行方式
- sequence_parallel / sp_degree怎么开torchrun + sp_degree>=2
原生 Ulysses SP:精确 attention,按 token 切卡。加载前需要 NCCL。Wan2.2 有 24 个 head,degree 必须整除 24(2、3、4、6、8、12)。
会拒绝feature cache、近似 attention、CUDA Graph
- 怎么开cfg_parallel=2
cfg_parallelCFG 正负分支分两个 rank。world size 必须匹配 SP×CFG mesh。degree 只能是 1 或 2。
会拒绝cfg_gate_step < 1.0
- 怎么开vae_parallel=True 或显式 degree
vae_parallelWan VAE tile 按 rank 分片,再 typed all-gather。和 SP/CFG 一起用时,degree 必须等于完整 world size。需要 torchrun WORLD_SIZE>1。
适用范围官方 Wan VAE,不是 TAEW preview
Wan VAE 解码
VAE
- 怎么开vae_decode_autocast="bf16"
vae_decode_autocastWan decode 混精。相对 FP32 decode 有轻微数值差。
适用范围原生 Wan VAE
- 怎么开vae_spatial_tiling=True
vae_spatial_tiling空间分 tile 解码。别名:vae_tiled_decode,或组件 tiled=True。默认 tile 34×34、stride 18×16。只切出 1 个 tile 不算 tiled 执行。
不是同一个 flagvae_tiling 是 Hunyuan / Cosmos Predict2 的。Wan 忽略这个名字。
- 怎么开vae_temporal_chunk_size=4
vae_temporal_chunk_size因果时间 streaming 解码。chunk 之间保留 convolution cache。整段能装进一个 chunk 就不算 streaming。
适用范围官方 Wan VAE
- 怎么开vae_channels_last_3d=True
vae_channels_last_3d把 Conv3d 权重量成 channels-last。VAE 没有 Conv3d 会失败。
适用范围原生 Wan VAE
HunyuanVideo 和 Cosmos Predict2 只在各自管线上暴露 vae_tiling(Cosmos 还有 tile size/stride)。
蒸馏 checkpoint
Wan2.2 公开管线接受 peft_adapter_path,在校验 adapter / 基模 / target 后 merge PEFT LoRA。质量和步数属于那份蒸馏权重。没有匹配权重就没有单独的「4-step 模式」。
Feature cache(有损,只能选一种)
可选、单 rank、互斥。每个 CFG 分支独立 cache。TeaCache 对 Wan2.1 1.3B / 14B T2V 与 I2V、Wan2.1 Fun / VACE 别名、Wan2.2 Fun / A14B、Wan2.2 TI2V-5B 有预设系数。其他 model ID 必须显式传 coefficients。
Cache
- 怎么开feature_cache="teacache" 或 teacache=True
teacache按 residual 阈值(默认 0.26)加模型预设跳过 DiT step。也可 teacache=<threshold>。
适用范围有预设或显式 coefficients 的原生 Wan denoiser
- 怎么开feature_cache="adacache"
adacache自适应 residual cache。与其他 cache 一样,不能和 SP / CUDA Graph 组合。
适用范围原生 Wan
- 怎么开magcache={"ratios": [...]}
magcache必须提供逐 step 校准 ratios。仓内没有 Wan2.2 预设。
会 fail-closedmagcache=True 却不给 ratios
- 怎么开feature_cache={"algorithm": "blocktaylorseer"}
blocktaylorseerPinned LightX2V 逐 block self / cross / FFN 外推。默认 dense pattern [true, false, false, false]。
适用范围原生 Wan,单 rank
- 怎么开feature_cache="taylorseer"
taylorseer旧的 whole-stack residual 外推。不是 LightX2V 的逐 block 算法。默认 interval 4。
适用范围原生 Wan,单 rank
- 怎么开feature_cache={"algorithm": "custom", ...}
customLightX2V Tea 判定 + 一阶 stack residual。需要公开或显式 Tea 系数。
适用范围原生 Wan,单 rank
- firstblock / dualblock / dynamicblock怎么开feature_cache={"algorithm": "firstblock", "residual_diff_threshold": ...}
按 block 选择的 cache。必须给 residual_diff_threshold,没有质量安全默认值。
适用范围原生 Wan,单 rank
- 别名cfg_gate_fraction
cfg_gate_step过了该比例的 step 后,复用 CFG delta,不再跑负分支。1.0(默认)是完整 CFG。
会拒绝cfg_parallel=2
近似 attention(有损,必须显式开)
不会自动选择。运行会标 quality_tier="approximate"。只有 Wan denoiser 设置了 supports_approximate_attention。
稀疏
- 怎么开approximate_attention={"kind": "sta", ...}
staSliding-tile attention。只接受已调优 grid:(36, 48, 48) 与 (18, 48, 80)。默认 Wan2.2 TI2V 121×704×1280 → (31, 22, 40) 会在 CUDA 前拒绝。
适用范围原生 Wan,单 rank
- 怎么开approximate_attention={"kind": "vsa", ...}
vsaFastVideo 风格 video sparse attention。需要 3D sparse plan 和训练过的 gate_compress VSA-QAT 权重。缺 metadata 时降级为已记录的 exact attention。
适用范围专用 VSA checkpoint,不是通用 dense Wan
- 怎么开approximate_attention={"kind": "vmoba", ...}
vmoba无权重 FastVideo router。chunk 必须整除实际 Wan patch grid。仓内默认 profile 只匹配 TI2V (31, 22, 40)。几何不对会 fail-closed。
依赖fastvideo_kernel 的 MoBA symbol
- fastvideo_sla / fastvideo_sagesla怎么开kind="fastvideo_sla"
学出来的 Sparse-Linear Attention。checkpoint 必须有完整 proj_l。官方 dense Wan 和当前 FastVideo CausalWan Preview 会 fail-closed。SageSLA 还要 spas_sage_attn。
不要在 dense checkpoint 上开,或用 LightX2V 的 sla 别名冒充
- LightX2V sparse kinds种类dynamic_sparse, sparge, nbhd, lightx2v_sla_mask, flexblock, lightx2v_spas_sage, draft_attn, radial_attn, rainfusion_attn, svg_attn, svg2_attn, lightx2v_svg_mask
Pinned LightX2V 免训练稀疏通路。每次调用必须命中 pinned provider。有歧义的 sla / sagesla 别名不接受。
依赖pinned LightX2V checkout 与匹配的 operator
STA / VSA / VMoBA 的 symbol 来自仓内 thirdparty/fastvideo-kernel(或已安装的匹配 fastvideo_kernel wheel)。本地编译:设置 CUDA_HOME 和 CUDACXX,在该目录跑 ./build.sh。ThunderKittens C++ kernel 只在 Hopper sm_90a 编译(aarch64 宿主永远不编);否则走 Triton fallback。FP4 attention / 量化 CUDA 扩展需要 Blackwell sm_120a 且 CUDA ≥ 12.8。FA4 CuTe block-sparse 是可选的 flash_attn.cute 附加件,不在默认构建里。
量化(实验性)
量化模式
- fp8 / nvfp4怎么开quantization={"mode": "fp8", "min_features": 1024}
打包的低精度 wrapper。不合格 shape 走 dense 并如实报告。这是数值近似,不是已认证质量预设。
会拒绝block 或 disk offload
- 怎么开quantization="int8"
int8大 GEMM 上的动态 per-token / per-channel W8A8 Triton。小 shape 保留 BF16(计为 dense_policy_calls,不是 fallback)。全链路 INT8 是可选的,默认质量不安全。
实测一次完整 Wan INT8 smoke 打到了 kernel,但 latent / 视频质量失败(cosine ~0.91,视频 PSNR ~17)。只当校准,不当速度结论。
- 怎么开quantization="int4"
int4打包 / groupwise 存储,再反量化 + dense。不是声称的 INT4 GEMM 加速。
会拒绝block 或 disk offload
- 怎么开quantization="gguf" 或 .gguf 文件
gguf真实 GGUF tensor loader 与压缩存储。当前 runtime 没有合格的 GGUF 低比特 GEMM。
适用范围安装了可选 gguf 包时的原生 loader
仅 preview 解码
vae_preview_decoder_path 会用 TAEW2.2 替换 Wan2.2 的 48 通道官方 VAE。这是快速、近似、只解码的 preview。官方 VAE 的 tiling、时间 chunk、VAE-parallel 不会生效,因为官方 decoder 根本没建。发布和官方 benchmark 不要用 TAEW。
不可以做 / 不要改
不要
- 把配置当成加速证据不算数
只有 requested 没有 effective、pending wrapper、dense_policy_calls / SDPA fallback,都不是加速。
- 把 sequence parallel 和 cache、稀疏 attention、CUDA Graph 组合构建期拒绝
SP 需要跨 rank 同步 skip / 路由,当前没有。例外是 fused RoPE,它感知 SP。
- 把 CUDA Graph 和 feature cache、近似 attention、static_cross_kv 组合构建期拒绝
Graph replay 会冻住上一步或上一请求的 Python cache / 稀疏调度。
- 量化 + block 或 disk offload构建期拒绝
量化权重是 buffer;异步双层 offloader 只管理 Parameter。disk offload 也无法物化这次变换。
- device_map=balanced + 任何 offload构建期拒绝
balanced 分片要求权重量在显存。
- 同时开两种 feature cache构建期拒绝
teacache、magcache、adacache、taylorseer、blocktaylorseer、custom 和 block cache 互斥。
- MagCache 不给 ratios,或 TeaCache 既无预设也无系数构建期拒绝
未校准的 Wan2.2 MagCache 仓内没有 ratios。未知 TeaCache model ID 必须自己给 coefficients。
- 在默认 TI2V 121×704×1280 grid 上开 STACUDA 前拒绝
只调过 (36, 48, 48) 和 (18, 48, 80)。
- 把 VMoBA profile 复用到别的分辨率或帧数fail-closed
chunk 必须整除真实 post-patch grid。先推导 grid。
- 在官方 dense Wan 上开 FastVideo SLAfail-closed
这些 checkpoint 没有 proj_l。不要用 LightX2V 的 sla / sagesla 别名冒充这条通路。
- 把 sage_attn2_k_int8_v_fp8 当 Wan 稀疏 providerfail-closed
该 registry 项需要量化 K/V 元组。Wan generator 提供浮点 K/V,也没有审计过的逐层 quantize cache。
- 把 INT8 / INT4 / GGUF 当默认质量路径质量悬崖
INT8 kernel 能跑起来,latent 仍可能毁掉。INT4 和 GGUF 在认证新 kernel 之前只是存储 + dense 计算。
- 把 TAEW2.2 当官方 VAE仅 preview
和 48 通道 Wan2.2 VAE 的颜色 / 结构不同。发布和 benchmark 用官方 decoder。
- 把这些 Wan 开关用到 API 或其他家族未接入
Wan 2.5+ API 不理这些。HunyuanVideo 只吃 dtype、offload、attention、vae_tiling。Cosmos Predict2 只吃 dtype、offload、vae_tiling。Echo-Memory 只有 offload_model。Matrix-Game 3.5 固定 BF16 RuntimePolicy。LTX-2.5 有自己的 offload_mode / quantization,不是这张表。
- RuntimePolicy 里没有的 PyTorch 技巧未接入
在家族 runtime 上随便 torch.compile、sequential offload、装了 xFormers 却没选中、或社区 TeaCache monkey-patch,都是「PyTorch 能做」,不是 WorldFoundry 开关。归在这里,不要写进「可以做」。
- 改官方 benchmark 的 steps、CFG、尺寸,或打开有损 cache不可比
评分在评测章节。更快的非官方 schedule 是另一份 workload。
- 在 training build 上开推理加速构建期拒绝
训练禁止 offload、量化、Sage、TeaCache、CUDA Graph、fuse_qkv、static_cross_kv 以及其他推理 wrapper。
- cfg_parallel degree 不是 2构建期拒绝
runner 只实现 degree 1 或 2;degree 2 需要已建立的双 rank CFG group。
OOM 与首次编译成本
显存不够用 block offload。常驻 + INT8 且未开 expandable CUDA segments 时,额外 BF16 副本曾在 VAE 阶段 OOM。torch.compile 和 CUDA Graph 会让第一次请求慢很多,不要拿那次计时。
怎么打开
同一组 load key 可以从 Python、CLI 或 Workspace 打开。
嵌套对象不要写成 CLI flag
feature_cache、approximate_attention、quantization 放进 Python kwargs 或 load JSON,不要猜 CLI flag。
原生 Wan 2.1 / 2.2 的完整表面:
from worldfoundry.pipelines.wan.pipeline_wan_2p2 import Wan2p2Pipeline
pipe = Wan2p2Pipeline.from_pretrained(
model_path="/checkpoints/Wan2.2-TI2V-5B",
device="cuda",
# 放置
offload_mode="resident",
torch_dtype="bfloat16",
dit_weight_dtype="bf16",
# Attention 与精确 kernel
attention_backend="flash3",
fuse_qkv=True,
fused_rope=True,
static_cross_kv=True,
compile=False,
# 有损 — 最多一种 cache,且不要和 SP / CUDA Graph 一起:
# feature_cache={"algorithm": "teacache"},
# Wan VAE 解码
vae_decode_autocast="bf16",
vae_spatial_tiling=True,
vae_tile_size=(34, 34),
vae_tile_stride=(18, 16),
vae_temporal_chunk_size=4,
)该模型 load schema 上的 CLI:
worldfoundry-eval run wan2.2-ti2v-5b \
--pipeline.task-profile <task-profile> \
--pipeline.load.offload-mode resident \
--pipeline.load.attention-backend flash3 \
--pipeline.load.fuse-qkv true \
--pipeline.load.static-cross-kv true \
--output-dir tmp/worldfoundry_infer/wan2.2-ti2v-5b与运行推理同一条 job 路径:
python -m worldfoundry.studio.workspace_job infer \
--model-id wan2.2-ti2v-5b \
--load-json '{
"offload_mode": "resident",
"attention_backend": "flash3",
"fuse_qkv": true,
"static_cross_kv": true
}' \
--output-dir tmp/worldfoundry_infer/wan2.2-ti2v-5bStudio 与多卡
- Workspace UIStudio勾选 + 下拉
compile、CPU offload、fused QKV、static cross-KV、fused RoPE、attention。嵌套对象仍放进 --load-json。
- 多卡怎么开torchrun + sp_degree
Sequence / CFG / VAE 并行需要 CUDA,且 world size 必须匹配。
确认实际跑了什么
dit = pipe.native_pipeline.components.denoiser.runtime_optimization_report()
vae = pipe.native_pipeline.components.decoder.runtime_optimization_report()
print(dit["requested"], dit["effective"], dit["fallbacks"])
print(vae["requested"], vae["effective"], vae["fallbacks"])至少 forward 一次之后:
- Attention —
attempts == successes > 0,目标 fallback 为空。compile:compiled_graph_traces > 0。 - QKV / RoPE / static-KV — 本请求有真实调用。static-KV:有 hits,且
bypasses=0。 - CUDA Graph —
replay > 0,且eager = capture_failed = 0。 - VAE tile / chunk — 最后一次窗口
> 1,lifetime 总数不算。 - 量化 —
low_precision_kernel_calls > 0。dense_policy_calls是 BF16。
下一步
不引入 CUDA 同步的分阶段跟踪
录制 Nsight Systems trace 时设置 WORLDFOUNDRY_NVTX=1。例如,把下列
inference.py 换成现有推理脚本:
WORLDFOUNDRY_NVTX=1 nsys profile --trace=cuda,nvtx,osrt -o inference-trace python inference.py标准 NativeDiffusionRunner 会标记 worldfoundry.run、encode、
denoise_step、denoiser.positive/negative 和 decode。公共视频后处理、
H.264 输出和打包 offload 分别标记 worldfoundry.postprocess、
worldfoundry.output.h264 和 worldfoundry.offload.h2d。
自定义 runner 仅继承其实际调用的公共方法中的标记。
这些范围标记 CPU 提交工作的位置,不额外同步 CUDA,也不代表客户端显示延迟。
未开启时不会导入 PyTorch 或探测 CUDA;无 CUDA 时为空操作。
offload 固定缓冲区与 GQA 兼容路径
通过 Python 接口 enable_layerwise_cpu_offload(..., reuse_buffers=True) 显式开启后,连续权重会
按 dtype 打包到对齐的 CPU 缓冲区,复用最多两个 CUDA 槽,并通过 CUDA event
防止计算尚未结束时覆盖权重。报告新增 buffer_mode 和 device_buffer_bytes。
非连续权重保留原布局,报告 per-parameter;也可用 reuse_buffers=False
显式选择旧路径;默认仍为 False。
打包路径要求 torch.no_grad() 或 torch.inference_mode()、顺序执行各层,
且参数不共享底层存储。开启时拒绝 CUDA Graph capture 和 state-dict 操作。
修改模型 dtype/device 或保存、加载权重前,先 disable。
原地权重修改使用 layerwise_offload_mutation_scope(layer);
handle.disable() 会恢复 CPU 权重并移除 hook。
固定槽改善的是显存和拷贝管理,并不保证所有层尺寸下吞吐都更高。
公共 scaled_dot_product_attention 在显式选择 backend="efficient",或兼容
不支持 enable_gqa 的旧 SDPA 时,对 batch 相同的四维张量和共享 mask 使用
分组 query 与零步长 K/V view。按 batch/head 指定的 mask 仍走显式 head 扩展。
部分形状和布局仍可能触发 reshape 拷贝;原有 native GQA 选择保持不变。
以下本地测量使用排除 warmup 的合成组件测试,记录 CUDA-event 耗时和峰值 allocated 显存, 不代表完整模型 FPS。设计参考 FlashDreams #637、 #632 和 #634。
2026-09-18 的本地组件测量:单张 H100 80GB、PyTorch 2.5.1+cu121、FP16, 每个独立进程 warmup 10 轮、测量 50 轮:
| 用例 | CUDA 耗时中位数 | 峰值 allocated 显存 |
|---|---|---|
| offload:原有逐参数拷贝 | 0.932 ms | 37.38 MiB |
| offload:打包固定槽 | 1.514 ms | 37.38 MiB |
| GQA:显式复制 K/V head | 0.419 ms | 82 MiB |
| GQA:分组 view | 0.358 ms | 19 MiB |
Offload 使用 8 个宽度 1024 的 Linear 层,batch 64。GQA 使用
Q [1,32,256,64]、K/V [1,8,8192,64] 和 efficient SDPA。
打包 offload 将 H2D 拷贝次数减半,但这个小层用例耗时更高,因此保持显式可选。
选择前需对实际模型及层尺寸测量。峰值显存包含进程中所有存活 tensor,不只是权重。