[docs] Migrate documentation and cookbook to Blume (#1969)

Co-authored-by: Aryan Kumar <aryan5v@users.noreply.github.com>
2026-10-16 16:09:04 -07:00
parent ba371e33ed
commit 6212e7262e
111 changed files with 19501 additions and 5467 deletions
@@ -0,0 +1,27 @@
+# Hardware and runtimes
+
+Choose your runtime first, then check the model and attention backend. A model
+being listed does not mean every precision, kernel, or device supports it.
+
+| Hardware | Runtime | Start here | What changes |
+| --- | --- | --- | --- |
+| NVIDIA RTX / workstation GPUs | PyTorch + CUDA | [NVIDIA GPU setup](installation/gpu.md), then the model's cookbook | Memory budget and GPU architecture determine which precision and attention kernels are available. The [RTX PRO 6000 FastH3 guide](../inference/fasth3_rtx_pro_6000.md) is a specific Blackwell recipe, not a requirement for all NVIDIA users. |
+| NVIDIA data center GPUs | PyTorch + CUDA | [NVIDIA GPU setup](installation/gpu.md), then [multi-GPU configuration](../inference/configuration.md#multi-gpu-setup) | Use the configuration and optimization guides for parallelism, offloading and backend selection. Keep benchmark results tied to the measured GPU. |
+| NVIDIA DGX Spark / GB10 | PyTorch + CUDA on ARM64 | [Spark installation](installation/spark.md) | This is a separate installation path. [Pairing two Sparks](installation/spark_pair.md) and [tuning](installation/spark_performance.md) are advanced steps after one device works. |
+| Apple Silicon | Native MLX | [MLX installation](installation/mlx.md) | Use MLX-compatible checkpoints and examples. FastMetal and FastH3 have different conversion and generation paths. The older MPS example is a separate PyTorch demo. |
+| AMD GPUs | PyTorch + ROCm | [ROCm support and current limits](installation/amd.md) | The repository has a ROCm platform and Triton attention routes. CUDA-specific kernels and quantized exports do not automatically apply. |
+
+## Then choose a model
+
+[Fast Models](https://haoailab.com/FastVideo/fast-models/) highlights FastVideo releases.
+The [support matrix](../inference/support_matrix.md) covers the wider model set.
+The [cookbook](../cookbook/index.md) provides model-specific recipes and runtime
+choices. Follow a recipe's recorded requirements rather than inferring memory
+fit from a model name or parameter count.
+
+## Shared guides
+
+- [Configuration](../inference/configuration.md) owns generation settings and parallelism.
+- [Offloading](../inference/offloading.md) explains memory tradeoffs.
+- [Optimizations](../inference/optimizations.md) lists attention and precision constraints.
+- [ComfyUI](../inference/comfyui.md) is an integration, not a hardware platform.
@@ -1,13 +1,17 @@

 # 🔧 Installation

-FastVideo supports the following hardware platforms:
+Start with [Hardware and runtimes](hardware.md) to distinguish NVIDIA RTX and
+data center GPUs, DGX Spark, Apple Silicon MLX, and AMD ROCm.
+
+The installation paths below cover:

 - [NVIDIA CUDA](installation/gpu.md)
 - **NVIDIA DGX Spark / GB10 (ARM64 + CUDA 13)** — [install](installation/spark.md),
  [performance](installation/spark_performance.md),
  [pair two Sparks](installation/spark_pair.md)
 - [Apple silicon (MLX)](installation/mlx.md)
+- [AMD / ROCm support and current limits](installation/amd.md)

 ## Quick Installation

@@ -0,0 +1,42 @@
+# AMD and ROCm
+
+FastVideo has a ROCm platform implementation for AMD GPUs. This page describes
+the checked-in support paths; a complete device-by-model validation matrix and
+end-to-end installation walkthrough are not currently documented.
+
+## What is implemented
+
+- ROCm platform detection uses AMD SMI or a HIP-enabled PyTorch build with
+  access to `/dev/kfd` and DRM render devices.
+- The platform supports PyTorch SDPA and selects FlashAttention when its
+  installation, dtype and head size are compatible, with SDPA fallback.
+- `VIDEO_SPARSE_ATTN` and `VIDEO_SPARSE_ATTN_H3` use the kernel package's Triton
+  routes. CUDA CuTe and ThunderKittens paths are not ROCm implementations.
+- The optimization guide documents a CDNA4-specific
+  [FP8 weight path](../../inference/optimizations.md#fp8-weight-quantization).
+  This does not establish FP8 support on every AMD device.
+
+These paths are defined in the
+[ROCm platform source](https://github.com/hao-ai-lab/FastVideo/blob/main/fastvideo/platforms/rocm.py)
+and [platform detection](https://github.com/hao-ai-lab/FastVideo/blob/main/fastvideo/platforms/__init__.py).
+
+## Setup references
+
+The repository includes a
+[ROCm Dockerfile](https://github.com/hao-ai-lab/FastVideo/blob/main/docker/rocm7_1.Dockerfile)
+and [kernel build instructions](https://github.com/hao-ai-lab/FastVideo/blob/main/fastvideo-kernel/README.md#rocm-build).
+The kernel build supports `./build.sh --rocm` and a Python/Triton-only mode when
+the compiled HIP extension is unavailable.
+
+Use a matching ROCm-enabled PyTorch environment. The ordinary CUDA installation
+command is not an AMD installation command. Check the
+[support matrix](../../inference/support_matrix.md) and the selected model's
+[cookbook](../../cookbook/index.md) for its runtime requirements. A CUDA recipe
+or released NVFP4 checkpoint alone is not evidence of an AMD-compatible run.
+
+## Documentation still needed
+
+A maintained ROCm walkthrough should record the GPU architecture, ROCm/PyTorch
+versions, model revision, attention backend, runnable command, output, and measured
+memory. Until that evidence is published, device and model combinations beyond
+the linked source paths remain unverified here.
@@ -17,12 +17,15 @@ build needs. The steps below handle both, **without requiring `sudo`**.
 - **Python: 3.10–3.12**
 - **Compilers:** gcc/g++ 10+ (the Spark ships gcc 13)

-!!! note "Different compute capability?"
-    These instructions target the GB10's `sm_121`. The kernel build auto-detects
-    it from your GPU, so there is normally nothing to set. To check your device:
-    ```bash
-    python -c "import torch; print(torch.cuda.get_device_capability(0))"  # GB10 -> (12, 1)
-    ```
+:::note[Different compute capability?]
+These instructions target the GB10's `sm_121`. The kernel build auto-detects
+it from your GPU, so there is normally nothing to set. To check your device:
+
+```bash
+python -c "import torch; print(torch.cuda.get_device_capability(0))"  # GB10 -> (12, 1)
+```
+
+:::

 ## Install

@@ -128,7 +131,7 @@ uv pip install "https://github.com/mjun0812/flash-attention-prebuild-wheels/rele
 |---|---|
 | `Could NOT find Python (missing: ... Development.Module)` | venv built from system Python without headers. Recreate with `--python-preference only-managed` (add `--clear` to reuse the path), or `sudo apt install python3.12-dev`. |
 | kernel build can't find cutlass headers | Submodules not initialised — run the `git submodule update` step. |
-| `fastvideo-kernel: could not determine the target CUDA architecture` | The build couldn't see a GPU and no arch was given. Build on the Spark itself, or pass `TORCH_CUDA_ARCH_LIST=12.1a` (see [Building without a visible GPU](#building-without-a-visible-gpu-ci--docker)). |
+| `fastvideo-kernel: could not determine the target CUDA architecture` | The build couldn't see a GPU and no arch was given. Build on the Spark itself, or pass `TORCH_CUDA_ARCH_LIST=12.1a` (see [Building without a visible GPU](#building-without-a-visible-gpu-ci-docker)). |
 | `sm_121a requires CUDA Toolkit 13.0+` | Confirm `nvcc --version` is 13.x and `CUDACXX=/usr/local/cuda/bin/nvcc`; architecture-specific sm_120a code cannot run on sm_121. |
 | `ninja: command not found` (manual build only) | `uv pip install scikit-build-core cmake ninja setuptools wheel`. |

@@ -5,16 +5,17 @@ run next. It covers **which models are practical on the GB10, what actually
 makes them faster, and what won't help (and why)**, so you don't burn a night
 tuning knobs that can't move on this hardware.

-!!! tip "TL;DR"
-    - **Use distilled few-step models** (e.g. `FastVideo/FastWan2.1-T2V-1.3B-Diffusers`).
-      They run in ~40 s/video. Full-step models are 12–47 min on the GB10.
-    - On few-step models, **VAE decode is the bottleneck**, not attention — it's
-      bandwidth-bound on the Spark's unified memory.
-    - **bf16 VAE decode** is the real, lossless lever (FastVideo already turns it
-      on for Wan). **FlashAttention, linear quantization, and `torch.compile` of
-      the VAE give little or nothing here** — see the table below.
-    - Heavy runs can make the box unreachable — run generations with VAE tiling on
-      and `nice -n 19`. See [Running safely](#running-safely-dont-lock-the-box).
+:::tip[TL;DR]
+- **Use distilled few-step models** (e.g. `FastVideo/FastWan2.1-T2V-1.3B-Diffusers`).
+  They run in ~40 s/video. Full-step models are 12–47 min on the GB10.
+- On few-step models, **VAE decode is the bottleneck**, not attention — it's
+  bandwidth-bound on the Spark's unified memory.
+- **bf16 VAE decode** is the real, lossless lever (FastVideo already turns it
+  on for Wan). **FlashAttention, linear quantization, and `torch.compile` of
+  the VAE give little or nothing here** — see the table below.
+- Heavy runs can make the box unreachable — run generations with VAE tiling on
+  and `nice -n 19`. See [Running safely](#running-safely-dont-lock-the-box).
+:::

 ## The hardware reality (this explains everything below)

@@ -42,12 +43,13 @@ model is ~18× faster than the full-step version of the same architecture:
 The bottleneck flips from decode to denoise at around **4 steps**. Below that,
 you're paying mostly for VAE decode; above it, mostly for the denoising loop.

-!!! note "Few-step timings are noisy — measure in-process"
-    On a 3-step run, one-time per-process startup (Triton autotune, allocator
-    warmup) dominates and never amortizes, so single-run totals wobble ~±30%.
-    Compare levers **back-to-back in one process or as medians**, never as two
-    separate single runs. The [reproduction script](#reproduce-these-numbers)
-    does this for you.
+:::note[Few-step timings are noisy — measure in-process]
+On a 3-step run, one-time per-process startup (Triton autotune, allocator
+warmup) dominates and never amortizes, so single-run totals wobble ~±30%.
+Compare levers **back-to-back in one process or as medians**, never as two
+separate single runs. The [reproduction script](#reproduce-these-numbers)
+does this for you.
+:::

 ## bf16 VAE decode — the real lever (already on for Wan)

@@ -28,12 +28,13 @@ uv pip install flash-attn --no-build-isolation -v
 The cookbook selects complete, checked-in recipes instead of mixing model,
 parallelism, offload, and attention settings independently.

-[Open the inference cookbook](../cookbook/index.md){ .md-button .md-button--primary }
+[Open the inference cookbook](../cookbook/index.md)

-!!! tip "Need more control?"
-    Start from a maintained recipe, then use the
-    [configuration](../inference/configuration.md) and
-    [optimization](../inference/optimizations.md) guides for supported changes.
+:::tip[Need more control?]
+Start from a maintained recipe, then use the
+[configuration](../inference/configuration.md) and
+[optimization](../inference/optimizations.md) guides for supported changes.
+:::

 ## Next Steps

@@ -6,14 +6,7 @@ FastVideo's V1 API provides a streamlined interface for video generation tasks w

 This class will be the primary Python API for generating videos and images.

-::: fastvideo.entrypoints.video_generator.VideoGenerator
-    options:
-      show_root_heading: true
-      show_source: false
-      members:
-        - from_pretrained
-      heading_level: 3
-
+<api-reference path="fastvideo.entrypoints.video_generator.VideoGenerator" heading="3" members="from_pretrained" />
 `VideoGenerator.from_pretrained()` should be the primary way of creating a new video generator.

 ## Configuring FastVideo
@@ -22,25 +15,10 @@ The following two classes `PipelineConfig` and `SamplingParam` are used to confi

 ### PipelineConfig

-::: fastvideo.configs.pipelines.base.PipelineConfig
-    options:
-      show_root_heading: true
-      show_source: false
-      members:
-        - from_pretrained
-        - dump_to_json
-      heading_level: 4
-
+<api-reference path="fastvideo.configs.pipelines.base.PipelineConfig" heading="4" members="from_pretrained,dump_to_json" />
 ### SamplingParam

-::: fastvideo.api.sampling_param.SamplingParam
-    options:
-      show_root_heading: true
-      show_source: false
-      members:
-        - from_pretrained
-      heading_level: 4
-
+<api-reference path="fastvideo.api.sampling_param.SamplingParam" heading="4" members="from_pretrained" />
 ### Returning samples without previews

 Set `OutputConfig(return_samples=True, return_frames=False, save_video=False)`