[docs]: fix various broken links across the documentation (#979)

2026-01-01 20:02:39 -06:00
parent 40ce2d72f5
commit 5285116e73
12 changed files with 79 additions and 36 deletions
@@ -50,21 +50,25 @@ class MyNewAttnBackend(AttentionBackend):
 FastVideo uses a `ForwardContext` to pass global metadata (like current timestep, batch info, or custom attention configurations) to attention backends without changing the `forward` signature of every layer. **This is optional and only required if your backend needs dynamic per-step information.**

 To use this:
+
 1. **Set Context**: In your pipeline or generation loop, use the `set_forward_context` context manager.
 2. **Access Context**: Inside your attention backend, use `get_forward_context()`.

-See `docs/attention/sta/index.md` (Sliding Tile Attention) for an example of how complex configuration (window sizes) is passed this way.
+See [`docs/attention/sta/index.md`](../sta/index.md) (Sliding Tile Attention) for an example of how complex configuration (window sizes) is passed this way.

 ## 3. Adding Compiled Kernels (C++/CUDA)

 If your backend requires custom CUDA kernels, you need to add them to the `fastvideo-kernel` package.

 ### A. Add Source Files
+
 Place your kernel implementation files in `fastvideo-kernel/csrc/attention/`.
+
 * `mynew_attn.cu` (CUDA implementation)
 * `mynew_attn.h` (Optional headers)

 ### B. Register in Extension
+
 Update `fastvideo-kernel/csrc/common_extension.cpp` to expose your function to Python.

 ```cpp
@@ -84,6 +88,7 @@ PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) {
 ```

 ### C. Update CMakeLists.txt
+
 Update `fastvideo-kernel/CMakeLists.txt` to compile your new files.

 **Case 1: General CUDA Kernel (Runs on all GPUs)**
@@ -111,6 +116,7 @@ endif()
 ```

 ### D. Expose in Python Ops
+
 Update `fastvideo-kernel/python/fastvideo_kernel/ops.py` to make the function importable and handle fallbacks gracefully.

 ```python
@@ -133,6 +139,7 @@ def my_compiled_attn_func(q, k, v):
 ```

 ### E. Expose in Package Init
+
 Update `fastvideo-kernel/python/fastvideo_kernel/__init__.py` to export the function.

 ```python
@@ -4,25 +4,26 @@ This document outlines FastVideo's architecture for developers interested in fra

 ## Table of Contents - Directory Structure and Files

- [`fastvideo/pipelines/`](#design-pipeline-system) - Core diffusion pipeline components
- [`fastvideo/models/`](#design-model-components) - Model implementations
-  - [`dits/`](#design-transformer-models) - Transformer-based diffusion models
-  - [`vaes/`](#design-vae-variational-auto-encoder) - Variational autoencoders
-  - [`encoders/`](#design-text-and-image-encoders) - Text and image encoders
-  - [`schedulers/`](#design-schedulers) - Diffusion schedulers
- [`fastvideo/attention/`](#design-optimized-attention) - Optimized attention implementations
- [`fastvideo/distributed/`](#design-distributed-processing) - Distributed computing utilities
- [`fastvideo/layers/`](#design-tensor-parallelism) - Custom neural network layers
- [`fastvideo/platforms/`](#design-platforms) - Hardware platform abstractions
- [`fastvideo/worker/`](#design-executor-and-worker-abstractions) - Multi-GPU process management
- [`fastvideo/fastvideo_args.py`](#design-fastvideo-args) - Argument handling
- [`fastvideo/forward_context.py`](#design-forwardcontext) - Forward pass context management
+- [`fastvideo/pipelines/`](#pipeline-system) - Core diffusion pipeline components
+- [`fastvideo/models/`](#model-components) - Model implementations
+  - [`dits/`](#transformer-models) - Transformer-based diffusion models
+  - [`vaes/`](#vae-variational-auto-encoder) - Variational autoencoders
+  - [`encoders/`](#text-and-image-encoders) - Text and image encoders
+  - [`schedulers/`](#schedulers) - Diffusion schedulers
+- [`fastvideo/attention/`](#optimized-attention) - Optimized attention implementations
+- [`fastvideo/distributed/`](#distributed-processing) - Distributed computing utilities
+- [`fastvideo/layers/`](#tensor-parallelism) - Custom neural network layers
+- [`fastvideo/platforms/`](#platforms) - Hardware platform abstractions
+- [`fastvideo/worker/`](#executor-and-worker-system) - Multi-GPU process management
+- [`fastvideo/fastvideo_args.py`](#fastvideoargs) - Argument handling
+- [`fastvideo/forward_context.py`](#forward-context-management) - Forward pass context management
 - `fastvideo/utils.py` - Utility functions
- [`fastvideo/logger.py`](#design-logger) - Logging infrastructure
+- [`fastvideo/logger.py`](#logger) - Logging infrastructure

 ## Core Architecture

 FastVideo separates model components from execution logic with these principles:
+
 - **Component Isolation**: Models (encoders, VAEs, transformers) are isolated from execution (pipelines, stages, distributed processing)
 - **Modular Design**: Components can be independently replaced
 - **Distributed Execution**: Supports various parallelism strategies (Tensor, Sequence)
@@ -34,12 +35,14 @@ FastVideo separates model components from execution logic with these principles:
 The `FastVideoArgs` class in `fastvideo/fastvideo_args.py` serves as the central configuration system for FastVideo. It contains all parameters needed to control model loading, inference configuration, performance optimization settings, and more.

 Key features include:
+
 - **Command-line Interface**: Automatic conversion between CLI arguments and dataclass fields
 - **Configuration Groups**: Organized by functional areas (model loading, video params, optimization settings)
 - **Context Management**: Global access to current settings via `get_current_fastvideo_args()`
 - **Parameter Validation**: Ensures valid combinations of settings

 Common configuration areas:
+
 - **Model paths and loading options**: `model_path`, `trust_remote_code`, `revision`
 - **Distributed execution settings**: `num_gpus`, `tp_size`, `sp_size`
 - **Video generation parameters**: `height`, `width`, `num_frames`, `num_inference_steps`
@@ -90,7 +93,9 @@ class MyCustomPipeline(ComposedPipelineBase):
 ```

 ### Pipeline Stages
+
 Each stage handles a specific diffusion process component:
+
 - **Input Validation**: Parameter verification
 - **Text Encoding**: CLIP, LLaMA, or T5-based encoding
 - **Image Encoding**: Image input processing
@@ -133,6 +138,7 @@ Transformer networks perform the actual denoising during diffusion:
  - `HunyuanVideoTransformer3DModel`

 Features include:
+
 - Text/image conditioning
 - Standardized interface for model-specific optimizations

@@ -161,6 +167,7 @@ VAEs handle conversion between pixel space and latent space:
 These models compress image/video data to a more efficient latent representation (typically 4x-8x smaller in each dimension).

 FastVideo's VAE implementations include:
+
 - Efficient video batch processing
 - Memory optimization
 - Optional tiling for large frames
@@ -179,6 +186,7 @@ Encoders process conditioning inputs into embeddings:
  - `CLIPVisionModel`

 FastVideo implements optimizations such as:
+
 - Vocab parallelism for distributed processing
 - Caching for common prompts
 - Precision-tuned computation
@@ -193,6 +201,7 @@ Schedulers manage the diffusion sampling process:
  - `FlowMatchEulerDiscreteScheduler`

 These components control:
+
 - Diffusion timestep sequences
 - Noise prediction to latent update conversions
 - Quality/speed trade-offs
@@ -219,7 +228,9 @@ This diagram shows how models are discovered, validated, and loaded across entry
 The `fastvideo/attention/` directory contains optimized attention implementations crucial for efficient video diffusion:

 ### Attention Backends
+
 Multiple implementations with automatic selection:
+
 - **FLASH_ATTN**: Optimized for supporting hardware
 - **TORCH_SDPA**: Built-in PyTorch scaled dot-product attention
 - **SLIDING_TILE_ATTN**: For very long sequences
@@ -240,7 +251,9 @@ self.attn = LocalAttention(
 ![Attention backend selector design](../assets/images/attention_backend.png)

 ### Attention Patterns
+
 Supports various patterns with memory optimization techniques:
+
 - **Cross/Self/Temporal/Global-Local Attention**
 - Chunking, progressive computation, optimized masking

@@ -296,6 +309,7 @@ self.attn = DistributedAttention(
 ```

 ### Communication Primitives
+
 Efficient distributed operations via AllGather, AllReduce, and synchronization mechanisms.

 Efficient communication primitives minimize distributed overhead:
@@ -314,6 +328,7 @@ Defined in `fastvideo/forward_context.py`, `ForwardContext` manages execution-sp
 - **Profiling Data**: Potential hooks for performance metrics collection

 This context-based approach enables:
+
 - Dynamic optimization based on execution state (e.g., attention backend selection)
 - Step-specific customizations within model components

@@ -339,12 +354,14 @@ FastVideo implements a flexible execution model for distributed processing:
 - **GPU Workers**: Handle actual model execution on individual GPUs

 The MultiProcExecutor implementation:
+
 1. Spawns worker processes for each GPU
 2. Establishes communication channels via pipes
 3. Coordinates distributed operations across workers
 4. Handles graceful startup and shutdown of the process group

 Each GPU worker:
+
 1. Initializes the distributed environment
 2. Builds the pipeline for the specified model
 3. Executes requested operations on its assigned GPU
@@ -359,11 +376,13 @@ The `fastvideo/platforms/` directory provides hardware platform abstractions tha
 ### Platform Abstraction

 FastVideo's platform abstraction layer enables:
+
 - **Hardware Detection**: Automatic detection of available hardware
 - **Backend Selection**: Appropriate selection of compute kernels
 - **Memory Management**: Efficient utilization of hardware-specific memory features

 The primary components include:
+
 - **Platform Interface**: Defines the common API for all platform implementations
 - **CUDA Platform**: Optimized implementation for NVIDIA GPUs
 - **Backend Enum**: Used throughout the codebase for feature selection
@@ -383,6 +402,7 @@ else:
 The platform system is designed to be extensible for future hardware targets.

 ## Logger
+
 See [PR](https://github.com/hao-ai-lab/FastVideo/pull/356)

 *TODO*: (help wanted) Add an environment variable that disables process-aware logging.
@@ -397,6 +417,7 @@ If you're a new contributor, here are some common areas to explore:
 4. **Hardware support**: Extend the `platforms` module for new hardware targets

 When adding code, follow these practices:
+
 - Use type hints for better code readability
 - Add appropriate docstrings
 - Maintain the separation between model components and execution logic
@@ -13,7 +13,7 @@ We provide two distilled models:
 Both models are trained on **61×448×832** resolution but support generating videos with **any resolution** (1.3B  model mainly support 480P, 14B model support 480P and 720P, quality may degrade for different resolutions).

 ## ⚙️ Inference
-First install [VSA](https://hao-ai-lab.github.io/FastVideo/video_sparse_attention/installation). Set `MODEL_BASE` to your own model path and run:
+First install [VSA](../attention/vsa/index.md). Set `MODEL_BASE` to your own model path and run:

 ```bash
 bash scripts/inference/v1_inference_wan_dmd.sh
@@ -38,4 +38,4 @@ pip install -e .

 - [Quick Start Guide](quick_start.md) - Get started with your first video generation
 - [Configuration](../inference/configuration.md) - Learn about configuration options
- [Examples](../inference/examples/) - Explore example scripts and notebooks
+- [Examples](../inference/examples/examples_inference_index.md) - Explore example scripts and notebooks
@@ -84,12 +84,12 @@ pip install flash-attn --no-build-isolation

 ## Set up using Docker
 We also have prebuilt docker images with FastVideo dependencies pre-installed:
-[Docker Images](#docker)
+[Docker Images](../../contributing/developer_env/docker.md)

 ## Development Environment Setup

 If you're planning to contribute to FastVideo please see the following page:
-[Contributor Guide](#developer-overview)
+[Contributor Guide](../../contributing/overview.md)

 ## Hardware Requirements

@@ -78,7 +78,7 @@ uv pip install -e .
 ## Development Environment Setup

 If you're planning to contribute to FastVideo please see the following page:
-[Contributor Guide](#developer-overview)
+[Contributor Guide](../../contributing/overview.md)

 ## Hardware Requirements

@@ -45,6 +45,7 @@ FastVideo uses the Hugging Face Diffusers format for model organization:
 ### Implementing Modules

 Place new modules in the appropriate directories:
+
 - Encoders: `fastvideo/models/encoders/`
 - VAEs: `fastvideo/models/vaes/`
 - Transformer models: `fastvideo/models/dits/`
@@ -53,12 +54,15 @@ Place new modules in the appropriate directories:
 ### Adapting Model Layers

 #### Layer Replacements
+
 Replace standard PyTorch layers with FastVideo optimized versions:
+
 - nn.LayerNorm → fastvideo.layers.layernorm.RMSNorm
 - Embedding layers → fastvideo.layers.vocab_parallel_embedding modules
 - Activation functions → versions from fastvideo.layers.activation

 #### Distributed Linear Layers
+
 Use appropriate parallel layers for distribution:

 ```python
@@ -91,6 +95,7 @@ self.out_proj = RowParallelLinear(
 ```

 ### Attention Layers
+
 Replace standard attention with FastVideo's optimized attention:

 ```python
@@ -304,6 +309,7 @@ EntryClass = [MyCustomPipeline, MyOtherPipeline]
 ```

 The registry will automatically:
+
 1. Scan all packages under `fastvideo/pipelines/`
 2. Look for `EntryClass` variables
 3. Register pipelines using their class names as identifiers
@@ -1,7 +1,7 @@
 # FastVideo CLI Inference

 The FastVideo CLI provides a quick way to access the FastVideo inference pipeline for video generation. For more advanced usage,
-see the Python interface [here](https://hao-ai-lab.github.io/FastVideo/inference/examples/basic.html).
+see the Python interface [here](examples/basic.md).

 ## Basic Usage

@@ -74,4 +74,4 @@ if __name__ == '__main__':

 ## Performance Optimization

-For configuring optimizations, please see our [optimizations guide](#inference-optimizations)
+For configuring optimizations, please see our [optimizations guide](optimizations.md)
@@ -3,6 +3,7 @@
 This page contains step-by-step instructions to get you quickly started with video generation using FastVideo.

 ## Requirements
+
 - **OS**: Linux (Tested on Ubuntu 22.04+)
 - **Python**: 3.10-3.12
 - **CUDA**: 12.8
@@ -21,9 +22,10 @@ conda activate fastvideo
 pip install fastvideo
 ```

-For advanced installation options, see the [Installation Guide](installation.md).
+For advanced installation options, see the [Installation Guide](../getting_started/installation.md).

 ## Generating Your First Video
+
 Here's a minimal example to generate a video using the default settings. Create a file called `example.py` with the following code:

 ```python
@@ -60,9 +62,10 @@ python example.py
 The generated video will be saved in the current directory under `my_videos/`  

 More inference example scripts can be found in `scripts/inference/`
+
 ## Available Models

-Please see the [support matrix](#support-matrix) for the list of supported models and their available optimizations.
+Please see the [support matrix](support_matrix.md) for the list of supported models and their available optimizations.

 ## Image-to-Video Generation

@@ -96,20 +99,26 @@ if __name__ == '__main__':
 Common issues and their solutions:

 ### Out of Memory Errors
+
 If you encounter CUDA out of memory errors:
+
 - Reduce `num_frames` or video resolution
 - Enable memory optimization with `enable_model_cpu_offload`
 - Try a smaller model or use distilled versions
 - Use `num_gpus` > 1 if multiple GPUs are available

 ### Slow Generation
+
 To speed up generation:
+
 - Reduce `num_inference_steps` (20-30 is usually sufficient)
 - Use half precision (`fp16`) for the VAE
 - Use multiple GPUs if available

 ### Unexpected Results
+
 If the generated video doesn't match your prompt:
+
 - Try increasing `guidance_scale` (7.0-9.0 works well)
 - Make your prompt more detailed and specific
 - Experiment with different random seeds
@@ -117,8 +126,8 @@ If the generated video doesn't match your prompt:

 ## Next Steps

- Learn about [Advanced Inference Configurations](#inference-configuration)
- Learn about using [Optimizations](#inference-optimizations)
- See [Examples](../examples/examples_inference_index.md) for more usage scenarios
+- Learn about [Advanced Inference Configurations](configuration.md)
+- Learn about using [Optimizations](optimizations.md)
+- See [Examples](examples/examples_inference_index.md) for more usage scenarios
 - Join our [Community Discord](https://discord.gg/JA7cksDz86).
 - Join our [Community Slack](https://join.slack.com/t/fastvideo/shared_invite/zt-38u6p1jqe-yDI1QJOCEnbtkLoaI5bjZQ).
@@ -7,13 +7,13 @@ This page describes the various options for speeding up generation times in Fast

 - Optimized Attention Backends

-  - [Flash Attention](#optimizations-flash)
-  - [Sliding Tile Attention](#optimizations-sta)
-  - [Sage Attention](#optimizations-sage)
-  - [Sage Attention 3](#optimizations-sage3)
+  - [Flash Attention](#flash-attention)
+  - [Sliding Tile Attention](#sliding-tile-attention)
+  - [Sage Attention](#sage-attention)
+  - [Sage Attention 3](#sage-attention-3)

 - Caching Techniques
-  - [TeaCache](#optimizations-teacache)
+  - [TeaCache](#teacache)

 ## Attention Backends

@@ -74,7 +74,7 @@ python setup.py install
 pip install st_attn==0.0.4
 ```

-Please see [this page](#sta-installation) for more installation instructions.
+Please see [this page](../attention/sta/index.md) for more installation instructions.

 ### Video Sparse Attention

@@ -85,7 +85,7 @@ git submodule update --init --recursive
 python setup_vsa.py install
 ```

-Please see [this page](#vsa-installation) for more installation instructions.
+Please see [this page](../attention/vsa/index.md) for more installation instructions.

 ### Sage Attention

@@ -1,7 +1,7 @@

 # 🧠 Finetune
 ## ⚡ Full Finetune
-Ensure your data is prepared and preprocessed in the format specified in [data_preprocess.md](#v0-data-preprocess). For convenience, we also provide a mochi preprocessed Black Myth Wukong data that can be downloaded directly:
+Ensure your data is prepared and preprocessed in the format specified in [data_preprocess.md](data_preprocess.md). For convenience, we also provide a mochi preprocessed Black Myth Wukong data that can be downloaded directly:

 ```bash
 python scripts/huggingface/download_hf.py --repo_id=FastVideo/Mochi-Black-Myth --local_dir=data/Mochi-Black-Myth --repo_type=dataset
@@ -17,7 +17,7 @@ bash scripts/finetune/finetune_mochi.sh # for mochi

 **Note that for finetuning, we did not tune the hyperparameters in the provided script.**
 ## ⚡ Finetune with VSA
-Follow [data_preprocess.md](#v0-data-preprocess) to get parquet files for preproccessed latent, and then run:
+Follow [data_preprocess.md](data_preprocess.md) to get parquet files for preproccessed latent, and then run:

 ```bash
 bash scripts/finetune/finetune_v1_VSA.sh