[docs] DGX Spark (GB10) performance & tuning guide + reproduction examples

[Mister-Raggs]

Summary

The Spark install guide (installation/spark.md) gets you running on a GB10, but
stops there. This adds the layer above it: which models are practical on the
GB10, what actually makes them faster, and what gives little or nothing on this
unified-memory hardware (and why) — so users don't spend a night tuning knobs
that can't move here.

New page docs/getting_started/installation/spark_performance.md:

• Use distilled few-step models (~40 s/video vs 12–47 min full-step); few-step is
  VAE-decode-bound on the ~270 GB/s unified LPDDR5X.
• A "what helps vs what doesn't" matrix: bf16 VAE decode ✅ (already the Wan
  default), distilled models ✅, VSA ✅ — vs building FlashAttention ❌ (SDPA is
  already flash-efficient on sm_121), torch.compile of the VAE ❌, and
  linear-only quantization ❌ on long-sequence models (attention dominates the
  denoise; linears are a few %). FP4 attention is covered as an opt-in path.
• A memory section (unified 128 GB pool, nvidia-smi N/A, peak_memory_mb
  as the real per-run figure) and a gotchas section.

New examples under examples/inference/optimizations/:

• spark_benchmark.py — reproduces the headline claims (few-step median timing +
  fp32-vs-bf16 decode A/B + peak memory), in-process to control for the GB10's
  few-step run-to-run variance.
• qad_fp4_ab.py — FP4 attention quality/speed A/B on the QAD checkpoint
  (FastVideo/FastWan-QAD-1.3B), one arm per process.

Plus cross-links from installation.md, spark.md, and a note at the top of
inference/optimizations.md.

Test evidence — all numbers measured on a DGX Spark (GB10)

Environment: GB10 (cc 12.1), torch 2.12.0+cu130, transformers 5.14.0, CUDA 13.

Claim	Measured
FastWan2.1-1.3B, 3-step	~40 s/video, decode the largest stage
distilled vs full-step (same arch)	~18×
bf16 VAE decode vs fp32	1.14× faster, MS-SSIM 0.9999 (lossless), on the identical latent
FP4 attention (opt-in)	−6% denoise (40.87 s → 38.45 s), visually equivalent to bf16
Wan2.1-1.3B few-step peak memory	~8.4 GB (of the 128 GB pool)

Every number in the guide is one of these measured values (no estimates carried
over). Sample stills from the FP4-attention A/B (bf16 vs FP4) are visually
equivalent; I'll attach them to the PR.

Depends on (merge order)

This PR is written assuming two other Spark PRs are on main, and should merge
after both:

• [kernel] Build + allow attn_qat_infer FP4 attention on sm_121a (DGX Spark) #1598 (build + allow ATTN_QAT_INFER FP4 attention on sm_121a) — qad_fp4_ab.py
  and the guide's FP4-attention section rely on the sm_121 kernel + allowlist it
  adds. [kernel] Build + allow attn_qat_infer FP4 attention on sm_121a (DGX Spark) #1598 also documents the sm_121 backend in optimizations.md, so this PR
  deliberately does not touch that section (only adds a cross-link).
• [bugfix] reason1: handle BatchEncoding from apply_chat_template #1607 (reason1 BatchEncoding fix) — the guide references running Cosmos-2.5;
  without this, Cosmos-2.5 inference crashes at text-encode on recent transformers.

Both PRs also touch installation/spark.md / inference/optimizations.md, in
different sections from this one — landing them first avoids a both-touched merge.

Related (not duplicated)

• The LTX2 FP4-linear reproduction lives in [perf] LTX2 FP4-linear on DGX Spark (GB10/sm_121): ~24% faster denoise at 1080p #1594; this PR cites it rather than
  duplicating the harness.
• A GB10 record for the performance dashboard is being coordinated separately (a
  single-GPU GB10 benchmark config needs CI gating first).

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[mergify]

Merge Protections

🔴 1 of 1 protections blocking · waiting on 👀 reviews and 🤖 CI

	Protection	Waiting on
🔴	PR merge requirements	👀 reviews and 🤖 CI

🔴 PR merge requirements

Waiting for

• #approved-reviews-by>=1
• check-success=fastcheck-passed
• check-success=full-suite-passed
• check-success~=pre-commit

This rule is failing.

• #approved-reviews-by>=1
• check-success=fastcheck-passed
• check-success=full-suite-passed
• check-success~=pre-commit
• title~=(?i)^\[(feat|feature|bugfix|fix|refactor|perf|ci|doc|docs|misc|chore|kernel|new.?model|skill|skills|infra)\]

[mergify]

Pre-commit checks failed

Hi @Mister-Raggs, the pre-commit checks have failed. To fix them locally:

# Install pre-commit if you haven't already
uv pip install pre-commit
pre-commit install

# Run all checks and auto-fix what's possible
pre-commit run --all-files

Common fixes:

• yapf: yapf -i <file> (formatting)
• ruff: ruff check --fix <file> (linting)
• codespell: codespell --write-changes <file> (spelling)

After fixing, commit and push the changes. The checks will re-run automatically.

For future commits, pre-commit will run automatically on changed files before each commit.

[SolitaryThinker]

Pushed two maintainer commits to this branch: a rebase onto current main and a small fix commit.

• rebase picks up [bugfix]: hard-fail when ATTN_QAT_INFER is selected but the kernel is unusable #1690 — selecting ATTN_QAT_INFER without the kernel now hard-fails with a receipt instead of silently running flash, so the A/B can't quietly benchmark bf16 vs bf16 anymore. Note the FP4 arms will error on any box until the sm_121a kernel build ([kernel] Build + allow attn_qat_infer FP4 attention on sm_121a (DGX Spark) #1598) lands.
• generate_video returns a plain dict, so the getattr(result, ...) reads always hit the fallback — generation_time was silently wall time and peak_memory_mb always None. Switched to dict access in both scripts.
• relabeled "denoise" → generation time (it's text-encode + denoise + decode), and fixed the [kernel] Build + allow attn_qat_infer FP4 attention on sm_121a (DGX Spark) #1598 citation (runtime allowlist landed via [feat]: FA4-FP4 ATTN_QAT_INFER on sm_100/sm_103 + NVFP4 weight purge #1647).

Verified the docs' checkable claims and the scripts compile; GPU numbers in the guide are yours to re-confirm with the fixed timing since generation_time may shift them slightly.