From 661d18ba55ddd2fde1802960cf4343a2ca84f57e Mon Sep 17 00:00:00 2001 From: Aryan Kumar <156166681+aryan5v@users.noreply.github.com> Date: Tue, 3 Nov 2026 01:07:54 -0800 Subject: [PATCH] [docs] Pika H3 Flex cookbook: --weights for the NVFP4 QAD releases and FP4 attention (#2054) Co-authored-by: Aryan Kumar --- docs/assets/cookbook-recipes.json | 27 ++++++++++++++- .../inference/basic/basic_pika_h3_flex.py | 33 ++++++++++++++++--- 2 files changed, 55 insertions(+), 5 deletions(-) diff --git a/docs/assets/cookbook-recipes.json b/docs/assets/cookbook-recipes.json index 26d614001..0c13d83fd 100644 --- a/docs/assets/cookbook-recipes.json +++ b/docs/assets/cookbook-recipes.json @@ -766,7 +766,7 @@ "stage": "inference", "task": "Text to video (with audio)", "label": "Pika H3 Flex", - "summary": "Pika's post-trained MiniMax-H3: synchronized video and stereo audio from text in six forwards, at 480p or 768p, 5-15 s, with optional NVFP4 decoder and text encoder on Blackwell.", + "summary": "Pika's post-trained MiniMax-H3: synchronized video and stereo audio from text in six forwards, at 480p or 768p, 5-15 s, in BF16 or as FastVideo's NVFP4 QAD release on Blackwell, with optional FP4 attention.", "model": "Pika-Labs/Pika-H3-Flex", "source": "examples/inference/basic/basic_pika_h3_flex.py", "command": "FASTVIDEO_ATTENTION_BACKEND=FLASH_ATTN FASTVIDEO_FA4=1 python examples/inference/basic/basic_pika_h3_flex.py --task t2va --offload resident --prompt 'A paper boat drifts down a rainy city street at night; rain patters on the water.'", @@ -783,6 +783,14 @@ "expected_artifact": "MP4 with synchronized stereo audio at outputs/pika_h3_flex/pika_h3_flex_t2va.mp4", "modes": ["T2VA"], "knobs": [ + { + "key": "weights", + "label": "Weights", + "hint": "NVFP4 QAD needs Blackwell", + "flag": "--weights", + "options": [{"value": "bf16", "label": "BF16 (Pika release)"}, {"value": "nvfp4-qad", "label": "NVFP4 QAD"}, {"value": "nvfp4-qad-fp4-attention", "label": "NVFP4 QAD + FP4 attention"}], + "default": "bf16" + }, { "key": "resolution", "label": "Resolution", @@ -855,6 +863,7 @@ } ], "limitations": [ + "NVFP4 QAD release (--weights), one GB200, 768p 16:9, 5 s, warm: 16.8 s with BF16 attention and 15.2 s with FP4 attention; at 768p, 15 s, FP4 attention is 16% faster than BF16 attention (85.3 s vs 101.8 s).", "Measured on one GB200 at 768p 16:9, 5 s, warm: official pika-h3-pro CLI 59.7 s; FastVideo BF16 26.2 s; with the NVFP4 quality-36L decoder 18.0 s; with the fast-8L decoder 17.4 s. The 36L decoder measured 40.5 dB PSNR against the BF16 decoder.", "Peak resident memory was about 129 GiB for the all-BF16 run and 104.6 GiB with the NVFP4 text encoder (25.49 s) at 768p / 5 s on GB200; the official CLI's sampling peak was 71.7 GiB, a different measurement. The NVFP4 text encoder's first request in a fresh process pays a one-time cost of about 183 s.", "--offload resident keeps every component on the GPU (104.6-108.5 GiB peak with the NVFP4 text encoder, about 129 GiB all-BF16, on GB200). --offload lazy loads components on demand for smaller devices; on GB200 it took 48.06 s for the same T2VA request.", @@ -887,6 +896,14 @@ "expected_artifact": "MP4 with synchronized stereo audio at outputs/pika_h3_flex/pika_h3_flex_.mp4", "modes": ["I2VA", "L2VA", "FL2VA"], "knobs": [ + { + "key": "weights", + "label": "Weights", + "hint": "NVFP4 QAD needs Blackwell", + "flag": "--weights", + "options": [{"value": "bf16", "label": "BF16 (Pika release)"}, {"value": "nvfp4-qad", "label": "NVFP4 QAD"}, {"value": "nvfp4-qad-fp4-attention", "label": "NVFP4 QAD + FP4 attention"}], + "default": "bf16" + }, { "key": "task", "label": "Task", @@ -1002,6 +1019,14 @@ "expected_artifact": "MP4 with synchronized stereo audio at outputs/pika_h3_flex/pika_h3_flex_ref2va.mp4", "modes": ["Ref2VA"], "knobs": [ + { + "key": "weights", + "label": "Weights", + "hint": "NVFP4 QAD needs Blackwell", + "flag": "--weights", + "options": [{"value": "bf16", "label": "BF16 (Pika release)"}, {"value": "nvfp4-qad", "label": "NVFP4 QAD"}, {"value": "nvfp4-qad-fp4-attention", "label": "NVFP4 QAD + FP4 attention"}], + "default": "bf16" + }, { "key": "resolution", "label": "Resolution", diff --git a/examples/inference/basic/basic_pika_h3_flex.py b/examples/inference/basic/basic_pika_h3_flex.py index 337001334..90e03a023 100644 --- a/examples/inference/basic/basic_pika_h3_flex.py +++ b/examples/inference/basic/basic_pika_h3_flex.py @@ -14,7 +14,8 @@ does not expose a step-count flag. ``--lossless-accel`` turns on the existing training-free FastVideo switches (bit-identical kernels, reference memo, parallel VAE tiles) before the generator starts. ``--nvfp4-decoder`` and ``--nvfp4-text-encoder`` opt into the existing Blackwell FP4 weight paths; -``--nvfp4-dit h3_dit`` loads a packed NVFP4 DiT export (e.g. +``--weights nvfp4-qad`` (or ``nvfp4-qad-fp4-attention``) selects FastVideo's NVFP4 QAD release; +``--nvfp4-dit h3_dit`` loads any packed NVFP4 DiT export (e.g. FastVideo/Pika-H3-Flex-NVFP4-QAD). They change weights, not the six-forward sampler. Kernel/VSA work is separate. ``--nvfp4-attention`` turns on FlashAttention-4 NVFP4 attention (Q/K in NVFP4, P/V in BF16; Blackwell and FA4 only) @@ -104,9 +105,31 @@ def _reference(value: str) -> MiniMaxH3Reference: return MiniMaxH3Reference(source=source, media_type=media_type) +WEIGHT_PRESETS = { + "bf16": { + "model_path": "Pika-Labs/Pika-H3-Flex" + }, + "nvfp4-qad": { + "model_path": "FastVideo/Pika-H3-Flex-NVFP4-QAD", + "nvfp4_dit": "h3_dit" + }, + "nvfp4-qad-fp4-attention": { + "model_path": "FastVideo/Pika-H3-Flex-NVFP4-FP4Attn-QAD", + "nvfp4_dit": "h3_dit", + "nvfp4_attention": "smooth_k+hadamard", + "nvfp4_attention_bf16_blocks": "45,49" + }, +} + + def parse_args() -> argparse.Namespace: parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - parser.add_argument("--model-path", default="Pika-Labs/Pika-H3-Flex") + parser.add_argument("--weights", + choices=tuple(WEIGHT_PRESETS), + default="bf16", + help="bf16: Pika's release; nvfp4-qad: FastVideo's NVFP4 QAD release; " + "nvfp4-qad-fp4-attention: NVFP4 QAD with FP4 attention (both need Blackwell)") + parser.add_argument("--model-path", help="local model directory or Hub repo (overrides --weights)") parser.add_argument("--task", choices=TASKS, default="t2va") parser.add_argument("--prompt", required=True) parser.add_argument("--image", help="first frame (i2va/fl2va)") @@ -146,10 +169,12 @@ def parse_args() -> argparse.Namespace: choices=tuple(QK_TRANSFORMS), help="FA4 NVFP4 Q/K attention with this exact Q/K preconditioning (default: BF16 attention)") parser.add_argument("--nvfp4-attention-bf16-blocks", - default="", help="comma-separated transformer_blocks indices that keep BF16 attention, e.g. 45,49") parser.add_argument("--output", default="outputs/pika_h3_flex") args = parser.parse_args() + for name, value in WEIGHT_PRESETS[args.weights].items(): + if getattr(args, name) is None: + setattr(args, name, value) if args.nvfp4_attention_bf16_blocks and not args.nvfp4_attention: parser.error("--nvfp4-attention-bf16-blocks needs --nvfp4-attention") try: @@ -232,7 +257,7 @@ def _apply_nvfp4_attention(args: argparse.Namespace) -> None: return envs.FASTVIDEO_NVFP4_FA4.set(True) envs.FASTVIDEO_NVFP4_FA4_QK_TRANSFORM.set(args.nvfp4_attention) - envs.FASTVIDEO_NVFP4_FA4_BF16_BLOCKS.set(args.nvfp4_attention_bf16_blocks) + envs.FASTVIDEO_NVFP4_FA4_BF16_BLOCKS.set(args.nvfp4_attention_bf16_blocks or "") envs.setdefault_external("CUTE_DSL_ENABLE_TVM_FFI", "1")