### Complete Example of fairseq2 Extension Setup

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/basics/runtime_extension.rst

This example demonstrates registering assets, models, and architectures within a fairseq2 extension setup function. It includes registering assets from a package or file path, defining model and dataset families, and registering custom model architectures.

```python
from fairseq2.runtime.config_registry import ConfigRegistrar
from fairseq2.runtime.dependency import DependencyContainer
from fairseq2.composition import register_package_assets, register_file_assets, register_dataset_family, register_model_family
from my_package.models.my_custom_model import MyCustomModel, MyCustomModelConfig, create_my_custom_model

def setup_my_fairseq2_extension(container: DependencyContainer) -> None:
    # Register custom objects here...
    container.register(...) # Placeholder for custom object registration

    # Register assets (yaml files) from your package, which extends fairseq2
    register_package_assets(container, "my_package.assets")

    # Or register assets from a file path, where you put your asset yaml files
    register_file_assets(container, Path("path/to/assets")) # Assuming Path is imported

    # Register model families (if any)
    register_model_family(
        container,
        "my_custom_model",  # model family name
        kls=MyCustomModel,  # model class
        config_kls=MyCustomModelConfig,  # model config class
        factory=create_my_custom_model,  # factory function
        # ... other parameters
    )

    # Register dataset families (if any)
    register_dataset_family(
        container,             # DependencyContainer instance
        "custom_dataset",      # family name
        CustomDataset,         # dataset class (assuming CustomDataset is imported)
        CustomDatasetConfig,   # config class (assuming CustomDatasetConfig is imported)
        opener=custom_opener   # opener function (assuming custom_opener is imported)
    )

    # Register tokenizer families (if any)
    register_tokenizer_family(
        container,
        "custom_tokenizer",     # tokenizer family name
        CustomTokenizer,        # tokenizer class (assuming CustomTokenizer is imported)
        CustomTokenizerConfig,  # tokenizer config class (assuming CustomTokenizerConfig is imported)
        loader=custom_loader,   # loader function (assuming custom_loader is imported)
    )

    # Register model architectures
    arch = ConfigRegistrar(container, MyCustomModelConfig)

    @arch("my_custom_arch_variant")  # architecture name
    def my_custom_arch_variant() -> MyCustomModelConfig:
        config = MyCustomModelConfig()
        # ... customize your config here...
        return config
```

--------------------------------

### Start fairseq2 Training with SLURM

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/pudb.rst

Example commands for allocating resources and starting fairseq2 training using SLURM. Adjust arguments as needed for your environment.

```bash
# Adjust the arguments (`--nodes`, `--ntasks-per-node`, etc.) as needed for your environment
salloc --nodes=1 --ntasks-per-node=8 --cpus-per-task=10 -t 1:00:00 --gpus-per-node=8
```

```bash
srun python -m recipes.lm.train $OUTPUT_DIR --config-file $CONFIG_YAML
```

--------------------------------

### Quick Start: Loading and Creating Qwen Models

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.hub.rst

Demonstrates how to get the Qwen model hub, list architectures, create a new uninitialized model, and load models from asset cards or custom checkpoints.

```python
from fairseq2.models.qwen import get_qwen_model_hub

# Get the model hub for Qwen family
hub = get_qwen_model_hub()

# List available architectures
archs = hub.get_archs()
print(f"Available architectures: {archs}")

# Create a new uninitialized model
config = hub.get_arch_config("qwen25_7b")
model = hub.create_new_model(config)

# Load a model from asset card
model = hub.load_model("qwen25_7b")

# Load a model from custom checkpoint
from pathlib import Path
model = hub.load_custom_model(Path("/path/to/checkpoint.pt"), config)
```

--------------------------------

### Quick Start

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.olmo.rst

Demonstrates how to get the OLMo model hub, list available architectures, load a model, and load its corresponding tokenizer.

```APIDOC
## Quick Start

.. code-block:: python

    from fairseq2.models.olmo import get_olmo_model_hub, load_olmo_tokenizer

    # Get the model hub
    hub = get_olmo_model_hub()

    # List available architectures
    for arch in sorted(hub.get_archs()):
        print(f"  - {arch}")

    # Load a model
    model = hub.load_model("olmo2_7b")

    # Load corresponding tokenizer
    tokenizer = load_olmo_tokenizer("olmo2_7b")
```

--------------------------------

### Example End-to-End Build Script

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/installation_from_source.rst

A comprehensive script demonstrating the build process from environment setup to wheel creation for fairseq2.

```sh
python_version=3.10.14
torch_version=2.7.1
cuda_version=12.8
variant=cu128
arch=linux-x86_64

conda create --name fs2_build_wheel python $python_version
conda activate fs2_build_wheel
conda install -c conda-forge libsndfile compilers=1.2.0

pip install --extra-index-url https://download.pytorch.org/whl/$variant\
            torch==$torch_version

git clone --recurse-submodules git@github.com:facebookresearch/fairseq2.git
cd fairseq2
pip install --requirement native/python/requirements-build.txt

version=0.5.1
tools/set-project-version.sh --native-only $version+$variant

cuda_archs="70-real;80-real;80-virtual"
cuda=ON
build_type=Release
lto=ON
sanitizers=nosan

# fairseq2/native
cd native
cmake\
-GNinja\
-DCMAKE_BUILD_TYPE=$build_type\
-DCMAKE_CUDA_ARCHITECTURES "$cuda_archs"\
-DFAIRSEQ2N_PERFORM_LTO=$lto\
-DFAIRSEQ2N_SANITIZERS="${SANITIZERS/_/;}"\
-DFAIRSEQ2N_TREAT_WARNINGS_AS_ERRORS=ON\
-DFAIRSEQ2N_USE_CUDA=$cuda\
-DFAIRSEQ2N_PYTHON_DEVEL=OFF\
-B build

cmake --build build

# fairseq2/native/python
cd python
pip wheel\
--use-pep517\
--no-build-isolation\
--no-deps\
--config-settings "--build-option=--plat-name"\
--config-settings "--build-option=manylinux_2_28_$arch"\
--wheel-dir build/wheelhouse\
.

ls build/wheelhouse/

# fairseq2/
cd ../../
pip wheel --no-deps --wheel-dir build/wheelhouse .
ls build/wheelhouse/
```

--------------------------------

### Quick Start: Loading and Using Models

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.hub.rst

Demonstrates how to get a model hub for a specific family (e.g., Qwen), list available architectures, create a new model instance, and load models from asset cards or custom checkpoints.

```APIDOC
## Quick Start

.. code-block:: python

    from fairseq2.models.qwen import get_qwen_model_hub

    # Get the model hub for Qwen family
    hub = get_qwen_model_hub()

    # List available architectures
    archs = hub.get_archs()
    print(f"Available architectures: {archs}")

    # Create a new uninitialized model
    config = hub.get_arch_config("qwen25_7b")
    model = hub.create_new_model(config)

    # Load a model from asset card
    model = hub.load_model("qwen25_7b")

    # Load a model from custom checkpoint
    from pathlib import Path
    model = hub.load_custom_model(Path("/path/to/checkpoint.pt"), config)
```

--------------------------------

### Quick Start: Loading Qwen Models and Tokenizers

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.qwen.rst

Demonstrates how to get the Qwen model and tokenizer hubs, list available architectures, and load a specific model and its corresponding tokenizer.

```APIDOC
## Quick Start: Loading Qwen Models and Tokenizers

### Description
This snippet shows how to initialize the Qwen model and tokenizer hubs, list available model architectures, and load a specific model (e.g., "qwen25_7b") along with its tokenizer. It also includes a basic example of text encoding.

### Code
```python
from fairseq2.models.qwen import get_qwen_model_hub, get_qwen_tokenizer_hub

# Get the model hub
hub = get_qwen_model_hub()

# List available architectures
print("Available Qwen architectures:")
for arch in sorted(hub.get_archs()):
    print(f"  - {arch}")

# Load a model
model = hub.load_model("qwen25_7b")

# Load corresponding tokenizer
tokenizer = get_qwen_tokenizer_hub().load_tokenizer("qwen25_7b")

# Generate some text
text = "The future of AI is"
encoder = tokenizer.create_encoder()
encoded = encoder(text)
# ... model inference code ...
```
```

--------------------------------

### Native LLaMA Configuration Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/hg_sft_example.rst

Illustrates a configuration for a native fairseq2 LLaMA model, showcasing its shorter setup due to registered assets.

```yaml
model:
  name: "llama3_2_1b"
tokenizer:
  name: "llama3_2_1b"
dataset:
  max_seq_len: 4096
  max_num_tokens: 8192
  chat_mode: true
  config_overrides:
    sources:
      train:
      - path: "hg://facebook/fairseq2-lm-gsm8k"
        split: "sft_train"
        weight: 1.0
```

--------------------------------

### Quick Start: Loading LLaMA Model and Tokenizer

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.llama.rst

Demonstrates how to get the LLaMA model and tokenizer hubs, load a specific model (e.g., 'llama3_2_1b'), and load its corresponding tokenizer. It also shows a basic example of encoding text.

```APIDOC
## Quick Start

.. code-block:: python

    from fairseq2.models.llama import get_llama_model_hub, get_llama_tokenizer_hub

    # Get the model hub
    hub = get_llama_model_hub()

    # Load a model
    model = hub.load_model("llama3_2_1b")

    # Load corresponding tokenizer (uses HuggingFace tokenizer by default)
    tokenizer = get_llama_tokenizer_hub().load_tokenizer("llama3_2_1b")

    # Generate some text
    text = "The future of AI is"
    encoder = tokenizer.create_encoder()
    encoded = encoder(text)
    # ... model inference code ...
```

--------------------------------

### Install and Build fairseq2 Docs

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/README.md

Installs project dependencies and builds the documentation. Ensure you are in the project root directory.

```bash
pip install -r requirements.txt

make clean
make html
```

--------------------------------

### Working with Qwen Models

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.hub.rst

Specific example for interacting with the Qwen model family hub, including getting architectures, configurations, and loading models.

```APIDOC
## Working with Model Families

Qwen Models
~~~~~~~~~~~

.. code-block:: python

    from fairseq2.models.qwen import get_qwen_model_hub

    hub = get_qwen_model_hub()

    # Available architectures
    archs = hub.get_archs()  # {'qwen25_0.5b', 'qwen25_1.5b', 'qwen25_3b', ...}

    # Get configuration for specific architecture
    config = hub.get_arch_config("qwen25_7b")

    # Create new model
    model = hub.create_new_model(config)
```

--------------------------------

### Create a fresh environment

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Removes existing environment files and lock files, then performs a fresh installation of dependencies. Useful for starting over or resolving complex environment issues.

```sh
rm -rf .venv uv.lock
```

```sh
uv sync --extra cu128
```

--------------------------------

### Install fairseq2 with development and linting tools

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Installs fairseq2 along with development (e.g., pytest) and linting (e.g., ruff, mypy) tools. This setup is for active development and code quality checks.

```sh
uv sync --extra cu128 --group dev --group lint
```

--------------------------------

### Resume Training Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/hg_sft_example.rst

Demonstrates how to initiate training and then resume it from a saved checkpoint using the same command and output directory.

```bash
# First run (trains and saves checkpoint)
python -m recipes.lm.sft \
    --config-file recipes/lm/sft/configs/gemma_3_1b_it_gsm8k.yaml \
    /path/to/output

# Resume from checkpoint (automatically detects and loads)
python -m recipes.lm.sft \
    --config-file recipes/lm/sft/configs/gemma_3_1b_it_gsm8k.yaml \
    /path/to/output
```

--------------------------------

### Serve fairseq2 Docs Locally

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/README.md

Starts a local HTTP server to view the built documentation. Access it via your browser at localhost:8000.

```bash
python -m http.server -d build/html/
```

--------------------------------

### Configure Package Installation Directories

Source: https://github.com/facebookresearch/fairseq2/blob/main/native/CMakeLists.txt

Sets the installation directories for libraries and include files based on whether Fairseq2 is being installed standalone or as part of another package. This ensures correct placement of installed files.

```cmake
if(FAIRSEQ2N_INSTALL_STANDALONE)
    set(install_lib_dir lib)
    set(install_inc_dir include)
else()
    set(install_lib_dir ${CMAKE_INSTALL_LIBDIR})
    set(install_inc_dir ${CMAKE_INSTALL_INCLUDEDIR})
endif()

set(install_pkg_dir ${install_lib_dir}/cmake/fairseq2n-${PROJECT_VERSION})
```

--------------------------------

### Install fairseq2 with CPU-only

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Installs fairseq2 with CPU-only support using uv sync with the 'cpu' extra.

```sh
uv sync --extra cpu
```

--------------------------------

### Install fairseq2 Python Package

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/installation_from_source.rst

Installs the main fairseq2 Python package.

```sh
pip install .
```

--------------------------------

### Basic Model Usage Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.qwen.rst

Illustrates a complete workflow for loading a Qwen model and tokenizer, preparing input data, and running a simplified inference.

```APIDOC
## Basic Model Usage Example

### Description
This example demonstrates loading a Qwen model and its tokenizer, preparing batched input tokens, and performing a basic inference pass. It utilizes default device settings and batch layout handling.

### Code
```python
import torch

from fairseq2.models.qwen import get_qwen_model_hub, get_qwen_tokenizer_hub
from fairseq2.device import get_default_device
from fairseq2.nn import BatchLayout

device = get_default_device()

# Load model and tokenizer
hub = get_qwen_model_hub()
model = hub.load_model("qwen25_7b", device=device)
tokenizer = get_qwen_tokenizer_hub().load_tokenizer("qwen25_7b")

# Prepare input
texts = ["The capital of France is", "The capital of Germany is"]
encoder = tokenizer.create_encoder()
tokens = torch.vstack([encoder(text) for text in texts]).to(device)

# Run inference (simplified)
model.eval()
with torch.inference_mode():
    seqs_layout = BatchLayout.of(tokens)
    output = model(tokens, seqs_layout=seqs_layout)
    # Process output...
```
```

--------------------------------

### Editable Development Installation of fairseq2

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Sets up fairseq2 for development by cloning the repository, installing it in editable mode, and installing development requirements. Ensure the PyTorch and CUDA versions match.

```sh
git clone https://github.com/facebookresearch/fairseq2.git
cd fairseq2
pip install -e . --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.8.0/cu128
pip install -r requirements-devel.txt
```

--------------------------------

### Quick Install fairseq2

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Installs the latest stable version of fairseq2 using pip.

```sh
pip install fairseq2
```

--------------------------------

### Install Development Tools

Source: https://github.com/facebookresearch/fairseq2/blob/main/CONTRIBUTING.md

Installs necessary development tools such as linters and formatters required for contributing to the project.

```sh
pip install -r requirements-devel.txt
```

--------------------------------

### Load Gemma4 Model with SFT Recipe

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.gemma4.rst

Example of how to use a pre-built SFT recipe configuration for GSM8K fine-tuning with a Gemma4 model.

```bash
fairseq2 lm sft --config recipes/lm/sft/configs/gemma4_e4b_gsm8k.yaml
```

--------------------------------

### Install fairseq2n Python Package

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/installation_from_source.rst

Installs the fairseq2n Python package after building it from the native directory.

```sh
cd native/python

pip install .

cd -
```

--------------------------------

### Working with Qwen Models

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.hub.rst

Illustrates how to interact with the Qwen model hub, including getting available architectures, retrieving configurations, and creating new models.

```python
from fairseq2.models.qwen import get_qwen_model_hub

hub = get_qwen_model_hub()

# Available architectures
archs = hub.get_archs()  # {'qwen25_0.5b', 'qwen25_1.5b', 'qwen25_3b', ...}

# Get configuration for specific architecture
config = hub.get_arch_config("qwen25_7b")

# Create new model
model = hub.create_new_model(config)
```

--------------------------------

### Install Configuration Header

Source: https://github.com/facebookresearch/fairseq2/blob/main/native/src/fairseq2n/CMakeLists.txt

Installs the generated 'config.h' file to the include directory of the Fairseq2n library. This makes the configuration definitions available to the C++ code.

```cmake
install(
    FILES
        ${CMAKE_CURRENT_BINARY_DIR}/config.h
    DESTINATION
        ${install_inc_dir}/fairseq2n
    COMPONENT
        devel
)
```

--------------------------------

### Run Test Suite

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/installation_from_source.rst

Installs development requirements and runs the test suite to check the installation.

```sh
pip install -r requirements-devel.txt

pytest
```

--------------------------------

### Custom Architecture Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.olmo.rst

Demonstrates how to load an architecture configuration, modify its parameters, and create a new model with the custom configuration.

```APIDOC
## Custom Architecture

.. code-block:: python

    from fairseq2.models.olmo import get_olmo_model_hub

    hub = get_olmo_model_hub()

    config = hub.get_arch_config("olmo2_7b")
    config.max_seq_len = 2048
    config.dropout_p = 0.1

    model = hub.create_new_model(config)
```

--------------------------------

### Custom Architecture Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.qwen.rst

Shows how to create a Qwen model with a custom configuration, modifying parameters like sequence length and dropout.

```APIDOC
## Custom Architecture Example

### Description
This example demonstrates how to customize a Qwen model's architecture. It starts by retrieving a base configuration, modifying specific parameters like `max_seq_len` and `dropout_p`, and then creating a new model instance with the adjusted configuration.

### Code
```python
from fairseq2.models.qwen import get_qwen_model_hub, QwenConfig

hub = get_qwen_model_hub()

# Get base configuration and modify
config = hub.get_arch_config("qwen25_7b")
config.max_seq_len = 16384  # Reduce sequence length
config.dropout_p = 0.1      # Add dropout

# Create model with custom config
model = hub.create_new_model(config)
```
```

--------------------------------

### Install Python Library

Source: https://github.com/facebookresearch/fairseq2/blob/main/native/python/src/fairseq2n/bindings/CMakeLists.txt

Installs the 'py_bindings' target as a library to the Python component destination.

```cmake
install(
    TARGETS
        py_bindings
    LIBRARY
        DESTINATION
            .
        COMPONENT
            python
    EXCLUDE_FROM_ALL
)
```

--------------------------------

### Complete pyproject.toml Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

A comprehensive pyproject.toml configuration file for a fairseq2 project, including project metadata, dependency groups, and uv-specific settings.

```toml
[project]
name = "my-fairseq2-project"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "clusterscope>=0.0.31",
    "pip>=25.2",
    "tensorboard~=2.16",
    "vllm>=0.10.0",
]

[dependency-groups]
dev = [
    "pytest~=7.3",
]
lint = [
    "mypy>=1.14.1",
    "ruff>=0.8.4",
]
data = [
    "nltk>=3.9.1",
    "pyarrow>=18.1.0",
]
doc = [
    "sphinx~=7.4.0",
    "sphinxcontrib-bibtex~=2.5.0",
    "sphinx-favicon~=1.0.1",
    "sphinx-design~=0.5.0",
    "myst-parser~=4.0.0",
    "sphinxcontrib-mermaid~=1.0.0",
    "furo==2024.8.6",
    "nbsphinx~=0.9.6",
]

[project.optional-dependencies]
cpu = [
    "torch==2.7.1+cpu",
    "torchaudio==2.7.1+cpu",
    "torchvision==0.22.1+cpu",
    "fairseq2n==0.5.*",
    "fairseq2==0.5.*",
    "vllm==0.10.1",
]
cu128 = [
    "torch==2.7.1+cu128",
    "torchaudio==2.7.1+cu128",
    "torchvision==0.22.1+cu128",
    "fairseq2n==0.5.*",
    "fairseq2==0.5.*",
    "vllm==0.10.1",
]
experimental = [
    "jupyter>=1.1.1",
    "notebook>=7.3.2",
    "torch==2.7.1+cu128",
    "torchaudio==2.7.1+cu128",
    "torchvision==0.22.1+cu128",
    "fairseq2n==0.5.*",
    "fairseq2==0.5.*",
    "vllm==0.10.1",
]
v04-cu124 = [
    "torch==2.6.0+cu124",
    "torchaudio==2.6.0+cu124",
    "torchvision==0.21.0+cu124",
    "fairseq2n==0.4.5",
    "fairseq2==0.4.5",
    "vllm==0.8.5.post1",
]

[tool.uv]
default-groups = ["dev", "lint", "data"]
conflicts = [
    [
        { extra = "cpu" },
        { extra = "cu128" },
        { extra = "experimental" },
        { extra = "v04-cu124" },
    ],
]
prerelease = "allow"

[tool.uv.sources]
torch = [
    { index = "pytorch-cpu", extra = "cpu" },
    { index = "pytorch-cu128", extra = "cu128" },
    { index = "pytorch-cu128", extra = "experimental" },
    { index = "pytorch-cu124", extra = "v04-cu124" },
]
torchaudio = [
    { index = "pytorch-cpu", extra = "cpu" },
    { index = "pytorch-cu128", extra = "cu128" },
    { index = "pytorch-cu128", extra = "experimental" },
    { index = "pytorch-cu124", extra = "v04-cu124" },
]
torchvision = [
    { index = "pytorch-cpu", extra = "cpu" },
    { index = "pytorch-cu128", extra = "cu128" },
    { index = "pytorch-cu128", extra = "experimental" },
    { index = "pytorch-cu124", extra = "v04-cu124" },
]
fairseq2n = [
    { index = "fairseq2-cpu", extra = "cpu" },
    { index = "fairseq2-cu128", extra = "cu128" },
    { index = "fairseq2-experimental", extra = "experimental" },
]
```

--------------------------------

### Run SFT with Pre-configured Llama Setup

Source: https://github.com/facebookresearch/fairseq2/blob/main/recipes/lm/sft/README.md

Launches the SFT recipe with a specific configuration file for a Llama model, such as `llama3_2_1b_gsm8k.yaml`. This allows for customized training parameters.

```bash
python -m recipes.lm.sft --config-file recipes/lm/sft/configs/llama3_2_1b_gsm8k.yaml
```

--------------------------------

### Example: Using HuggingFace Tokenizer

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.llama.rst

Provides a complete example of how to load the default HuggingFace LLaMA tokenizer and create encoders in different modes (default, prompt).

```APIDOC
## Complete Examples

Using HuggingFace Tokenizer
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from fairseq2.models.llama import get_llama_tokenizer_hub
    
    # Load default HuggingFace tokenizer
    tokenizer = get_llama_tokenizer_hub().load_tokenizer("llama3_2_1b")
    
    # Create encoder in different modes
    default_encoder = tokenizer.create_encoder()  # Adds BOS and EOS
    prompt_encoder = tokenizer.create_encoder(mode="prompt")  # Only BOS
    
    # Encode text
    text = "Hello, world!"
    tokens = default_encoder(text)
```

--------------------------------

### Basic Parquet Data Pipeline Setup

Source: https://github.com/facebookresearch/fairseq2/blob/main/src/fairseq2/data/parquet/README.md

Configure and build a basic Parquet data pipeline for a specific rank in a distributed environment. Ensure `dist` is imported and initialized.

```python
import torch.distributed as dist

from fairseq2.data.loading import BasicDataLoadingConfig
from fairseq2.data.parquet.fragment_streaming import FragmentStreamingConfig
from fairseq2.data.parquet.loader import build_basic_parquet_data_pipeline

# Get distributed info
rank = dist.get_rank()
world_size = dist.get_world_size()

config = BasicDataLoadingConfig(
    fragment_stream_config=FragmentStreamingConfig(
        parquet_path="/path/to/dataset/",
        fragment_shuffle_window=100,
        files_circular_shift=True  # Different ranks start at different positions
    ),
    # ... other configs
)

# Create a pipeline for this rank
pipeline = build_basic_parquet_data_pipeline(
    config, rank=rank, world_size=world_size
).and_return()
```

--------------------------------

### Run SFT with Custom Configuration File

Source: https://github.com/facebookresearch/fairseq2/blob/main/recipes/lm/sft/README.md

Starts the SFT recipe with a user-defined configuration file. Replace `path/to/your/config.yaml` with the actual path to your custom settings.

```bash
python -m recipes.lm.sft --config-file path/to/your/config.yaml
```

--------------------------------

### Install System Dependencies (Ubuntu)

Source: https://github.com/facebookresearch/fairseq2/blob/main/INSTALL_FROM_SOURCE.md

Install the libsndfile development package on Ubuntu-based systems, which is a dependency for fairseq2.

```sh
sudo apt install libsndfile-dev
```

--------------------------------

### Native fairseq2 Model Configuration Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/hg_sft_example.rst

Example of a configuration for a native fairseq2 model, contrasting with HuggingFace model configuration.

```yaml
model:
  name: "llama3_2_1b"
```

--------------------------------

### Install Package Configuration Files

Source: https://github.com/facebookresearch/fairseq2/blob/main/native/CMakeLists.txt

Installs the generated Fairseq2 CMake configuration files (`fairseq2-config.cmake` and `fairseq2-config-version.cmake`) to the specified destination directory. This makes the package discoverable by other CMake projects.

```cmake
install(
    FILES
        ${PROJECT_BINARY_DIR}/lib/cmake/fairseq2n/fairseq2n-config.cmake
        ${PROJECT_BINARY_DIR}/lib/cmake/fairseq2n/fairseq2n-config-version.cmake
    DESTINATION
        ${install_pkg_dir}
    COMPONENT
        devel
)
```

--------------------------------

### Install fairseq2 with experimental features and Jupyter

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Installs fairseq2 with experimental features and Jupyter Lab support. This is useful for exploring the latest developments.

```sh
uv sync --extra experimental
```

```sh
uv run jupyter lab
```

--------------------------------

### Install fairseq2 from source with extras and commit hash

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/other/contributing.rst

Install fairseq2 from a Git repository using a specific commit hash and extras, along with specific PyTorch and CUDA versions.

```sh
pip install 'fairseq2[arrow] @ git+https://github.com/facebookresearch/fairseq2.git@<commit-hash> בו'
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.8.0/cu128/
```

--------------------------------

### Install fairseq2 from local source in editable mode

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Installs fairseq2 from a local repository in editable mode, allowing for direct code changes to be reflected without reinstallation. Requires activating the virtual environment first.

```sh
uv sync --extra cu128
```

```sh
source .venv/bin/activate
```

```sh
uv pip install -e /path/to/fairseq2/repo
```

--------------------------------

### Define a Setup Function for fairseq2 Extension

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/basics/runtime_extension.rst

Create a Python function to register custom components with the fairseq2 dependency injection container. This function is the entry point for your extension.

```python
# in my_package/__init__.py
from fairseq2.runtime.dependency import DependencyContainer

def setup_my_fairseq2_extension(container: DependencyContainer) -> None:
    # Your extension setup code here...
    pass
```

--------------------------------

### Working with LLaMA Models

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.hub.rst

Example demonstrating how to use the LLaMA model family hub to list architectures and load specific LLaMA models.

```APIDOC
LLaMA Models
~~~~~~~~~~~~

.. code-block:: python

    from fairseq2.models.llama import get_llama_model_hub

    hub = get_llama_model_hub()

    # List available LLaMA architectures
    archs = hub.get_archs()

    # Load specific LLaMA model
    model = hub.load_model("llama3_8b")
```

--------------------------------

### Install fairseq2 with specific PyTorch and CUDA versions

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/other/contributing.rst

Install fairseq2 with specific PyTorch and CUDA versions using the nightly index URL.

```sh
pip install fairseq2\
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.8.0/cu128
```

--------------------------------

### Create Custom QwenConfig

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.qwen.rst

Shows how to create a custom configuration for Qwen models by modifying default parameters or by starting from a pre-defined architecture's configuration.

```python
from fairseq2.models.qwen import QwenConfig

# Create custom configuration
config = QwenConfig()
config.model_dim = 4096
config.num_layers = 32
config.num_attn_heads = 32
config.max_seq_len = 16384

# Or get pre-defined architecture
from fairseq2.models.qwen import get_qwen_model_hub
hub = get_qwen_model_hub()
config = hub.get_arch_config("qwen25_7b")
```

--------------------------------

### Editable installation of fairseq2

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/other/contributing.rst

Perform an editable installation of fairseq2 from a cloned repository, including development requirements and specific PyTorch/CUDA versions.

```sh
git clone https://github.com/facebookresearch/fairseq2.git
    cd fairseq2
    pip install -e . --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.8.0/cu128
    pip install -r requirements-devel.txt
```

--------------------------------

### Basic Model Usage Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.olmo.rst

Provides a complete example of loading an OLMo model and tokenizer, encoding text, and performing a forward pass.

```APIDOC
## Basic Model Usage

.. code-block:: python

    import torch

    from fairseq2.device import get_default_device
    from fairseq2.models.olmo import get_olmo_model_hub, load_olmo_tokenizer
    from fairseq2.nn import BatchLayout

    device = get_default_device()

    hub = get_olmo_model_hub()
    model = hub.load_model("olmo2_7b", device=device)
    tokenizer = load_olmo_tokenizer("olmo2_7b")

    texts = ["The capital of France is", "The capital of Germany is"]
    encoder = tokenizer.create_encoder()
    tokens = torch.vstack([encoder(text) for text in texts]).to(device)

    model.eval()
    with torch.inference_mode():
        seqs_layout = BatchLayout.of(tokens)
        output = model(tokens, seqs_layout=seqs_layout)
```

--------------------------------

### Example: Using Tiktoken Implementation

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.llama.rst

Demonstrates how to configure and load a LLaMA tokenizer using the Tiktoken implementation with specific overrides like `use_eot=True`.

```APIDOC
Using Tiktoken Implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from fairseq2.models.llama import get_llama_tokenizer_hub
    from fairseq2.models.llama.tokenizer import LLaMATokenizerConfig
    from pathlib import Path

    # Configure tiktoken implementation
    config = LLaMATokenizerConfig(impl="tiktoken", use_eot=True)

    # Load tokenizer with custom config
    hub = get_llama_tokenizer_hub()
    
```

--------------------------------

### Install Nightly Builds of fairseq2

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Installs the latest nightly build of fairseq2, specifying PyTorch and CUDA versions. Use the --pre flag for pre-release versions.

```sh
pip install fairseq2 --pre\
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.8.0/cu128
```

--------------------------------

### Setup Entry Point for Training

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/basics/building_recipes.rst

This is the minimal entry point for a training recipe. It requires importing `train_main` and your custom recipe class, instantiating the recipe, and passing it to `train_main`.

```python
from fairseq2.recipe.cli import train_main
from .recipe import LMTrainRecipe

# Create recipe instance
recipe = LMTrainRecipe()

# Run training with automatic CLI handling
train_main(recipe)
```

--------------------------------

### Install fairseq2 with Extras and Specific Commit

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Installs fairseq2 with optional extras (like 'arrow') from a specific commit hash in the Git repository, along with a specified PyTorch and CUDA version.

```sh
pip install 'fairseq2[arrow] @ git+https://github.com/facebookresearch/fairseq2.git@<commit-hash>'
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.8.0/cu128
```

--------------------------------

### YAML Dataset Asset Card Example

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.datasets.rst

Define dataset configurations using YAML asset cards. This example shows how to specify different dataset variants (`mydataset`, `mydataset@user`, `mydataset@mycluster`) with their respective configurations.

```yaml
name: mydataset
dataset_family: custom_dataset

---

name: mydataset@user
dataset_config:
    data: "/path/to/local/datasets/librilight/10h"

---

name: mydataset@mycluster
dataset_config:
    data: "/path/to/cluster/datasets/librilight/10h"
```

--------------------------------

### Run SFT with Default Llama-3.1-1b Config

Source: https://github.com/facebookresearch/fairseq2/blob/main/recipes/lm/sft/README.md

Executes the SFT recipe using the default configuration for the Llama-3.1-1b model. This is a quick way to start fine-tuning.

```bash
python -m recipes.lm.sft
```

--------------------------------

### Run SFT with Pre-configured Qwen Setup

Source: https://github.com/facebookresearch/fairseq2/blob/main/recipes/lm/sft/README.md

Initiates the SFT recipe using a specified configuration file for a Qwen model, like `qwen3_4b_gsm8k.yaml`. This enables fine-tuning with Qwen-specific settings.

```bash
python -m recipes.lm.sft --config-file recipes/lm/sft/configs/qwen3_4b_gsm8k.yaml
```

--------------------------------

### Create and Initialize fairseq2 Project

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Creates a new project directory, navigates into it, and initializes a pyproject.toml file using uv.

```sh
# Create new project
mkdir my-fairseq2-project
cd my-fairseq2-project

# Initialize with pyproject.toml (see configuration below)
uv init
```

--------------------------------

### Install Nightly Build of fairseq2

Source: https://github.com/facebookresearch/fairseq2/blob/main/README.md

Install nightly builds of fairseq2 for macOS. This command installs the nightly package corresponding to the specified PyTorch version. Ensure PyTorch is installed first.

```sh
pip install fairseq2\
  --pre --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.9.1/cpu
```

--------------------------------

### Basic Dependency Injection Usage in fairseq2

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/basics/design_philosophy.rst

Demonstrates how to initialize fairseq2, access the dependency resolver, and resolve core library components like AssetStore and Device.

```python
import fairseq2
from fairseq2.runtime.dependency import get_dependency_resolver
from fairseq2.assets import AssetStore
from fairseq2.device import Device
from fairseq2.models import load_model

# Initialize the library - sets up the global container
fairseq2.init_fairseq2()

# Access the global resolver
resolver = get_dependency_resolver()

# Resolve library components
asset_store = resolver.resolve(AssetStore)
device = resolver.resolve(Device)
card = asset_store.retrieve_card("llama3_1_8b_instruct")

# These are all automatically configured through the DI system
print(f"Default device: {device}")
print(f"Retrieved card: {card}")
```

--------------------------------

### Verify fairseq2 and PyTorch installation

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Checks the installed fairseq2 version and PyTorch installation, including CUDA availability. Helps diagnose import errors.

```sh
uv run python -c "import fairseq2; print(fairseq2.__version__)"
```

```sh
uv run python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')"
```

--------------------------------

### Install fairseq2 Nightly Build

Source: https://github.com/facebookresearch/fairseq2/blob/main/README.md

Install the nightly build of fairseq2 for Linux. This command installs the package corresponding to the specified PyTorch and CUDA versions.

```sh
pip install fairseq2\
  --pre --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.9.1/cu128
```

--------------------------------

### Register fairseq2 Extension via Setuptools Entry Points

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/basics/runtime_extension.rst

Use setuptools entry points in your `pyproject.toml` file to make your extension discoverable by fairseq2 when installed as a Python package.

```toml
[project.entry-points."fairseq2.extension"]
my_extension = "my_package.module:setup_my_fairseq2_extension"
```

--------------------------------

### Install Specific fairseq2 Variant

Source: https://github.com/facebookresearch/fairseq2/blob/main/README.md

Use this command to install a specific fairseq2 variant that exactly matches your PyTorch version. Ensure your PyTorch version is installed first.

```sh
pip install fairseq2\
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.9.1/cu126
```

--------------------------------

### Build and serve documentation

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/other/contributing.rst

Commands to build the Sphinx documentation and serve it locally for review.

```sh
cd doc

    pip install -r requirements.txt

    make html

    cd build/html

    python -m http.server 8084
```

--------------------------------

### Install fairseq2n Nightly Build

Source: https://github.com/facebookresearch/fairseq2/blob/main/CONTRIBUTING.md

Installs a nightly build of fairseq2n for a specific PyTorch version and CUDA variant. Ensure the variant matches your PyTorch installation to avoid compatibility issues.

```sh
pip install fairseq2n\
  --pre --upgrade --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.9.1/cu128
```

--------------------------------

### Create Qwen Model with Custom Configuration

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.qwen.rst

Demonstrates how to create a new Qwen model instance using a custom configuration, which can be derived from an existing architecture's config and then modified.

```python
from fairseq2.models.qwen import get_qwen_model_hub, QwenConfig

hub = get_qwen_model_hub()

# Get base configuration and modify
config = hub.get_arch_config("qwen25_7b")
config.max_seq_len = 16384  # Reduce sequence length
config.dropout_p = 0.1      # Add dropout

# Create model with custom config
model = hub.create_new_model(config)
```

--------------------------------

### Run SFT Training (Multi-GPU with FSDP)

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/hg_sft_example.rst

Execute the SFT training recipe on multiple GPUs using FSDP. Requires at least 2 GPUs.

```bash
torchrun --nproc_per_node=2 -m recipes.lm.sft \
    --config-file recipes/lm/sft/configs/gemma_3_1b_it_gsm8k.yaml \
    /path/to/output
```

--------------------------------

### Install System Dependency (macOS)

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Installs the libsndfile library using Homebrew on macOS.

```sh
brew install libsndfile
```

--------------------------------

### Install fairseq2 with Specific PyTorch and CUDA Versions

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Installs a specific variant of fairseq2 that matches the installed PyTorch (e.g., 2.8.0) and CUDA (e.g., 12.8) versions. Ensure your PyTorch and CUDA versions are compatible.

```sh
pip install fairseq2 \
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.8.0/cu128
```

--------------------------------

### Build and Serve Documentation Locally

Source: https://github.com/facebookresearch/fairseq2/blob/main/CONTRIBUTING.md

Builds the project documentation locally and serves it via a Python HTTP server. Visit http://localhost:8084 to view the documentation.

```sh
cd doc

pip install -r requirements.txt

make html

cd build/html

python -m http.server 8084
```

--------------------------------

### Editable Install fairseq2n Python Package

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/installation_from_source.rst

Installs the fairseq2n Python package in editable mode for development.

```sh
cd native/python

pip install -e .

cd -
```

--------------------------------

### Install System Dependencies (Fedora)

Source: https://github.com/facebookresearch/fairseq2/blob/main/INSTALL_FROM_SOURCE.md

Install the libsndfile development package on Fedora systems, which is a dependency for fairseq2.

```sh
sudo dnf install libsndfile-devel
```

--------------------------------

### Accessing and Using DatasetHub

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.datasets.hub.rst

Demonstrates how to obtain a DatasetHub instance, list available datasets, load configurations, and open datasets. Assumes a pre-configured DatasetHubAccessor.

```python
get_my_dataset_hub = DatasetHubAccessor(
    MY_DATA_FAMILY_NAME, kls=MyDataset, config_kls=MyDatasetConfig
)

# Get the dataset hub
hub = get_my_dataset_hub()

# List all available datasets
for card in hub.iter_cards():
    print(f"Found dataset: {card.name}")

# Load a dataset configuration
config = hub.get_dataset_config("my_dataset")

# Open a dataset
dataset = hub.open_dataset("my_dataset")

# Open a custom dataset with specific configuration
custom_dataset = hub.open_custom_dataset(config)
```

--------------------------------

### Install System Dependency (Linux Fedora/CentOS)

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Installs the libsndfile library required on Fedora/CentOS-based Linux systems.

```sh
sudo dnf install libsndfile
```

--------------------------------

### Install uv

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Installs uv using a script. Ensure your shell is restarted after this change if you are using Conda.

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install System Dependency (Linux Ubuntu/Debian)

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/index.rst

Installs the libsndfile1 library required on Ubuntu/Debian-based Linux systems.

```sh
sudo apt install libsndfile1
```

--------------------------------

### Run SFT Training (Single GPU)

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/hg_sft_example.rst

Execute the SFT training recipe on a single GPU using the specified configuration file and output directory.

```bash
python -m recipes.lm.sft \
    --config-file recipes/lm/sft/configs/gemma_3_1b_it_gsm8k.yaml \
    /path/to/output
```

--------------------------------

### Verify Model Integration via Command Line

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/add_model.rst

Use these commands to verify that the new model is correctly listed, to show its details, and to perform a quick load test.

```bash
# Check model is listed
python -m fairseq2.assets list --kind model | grep qwen25_3b_instruct
```

```bash
# Show model details
python -m fairseq2.assets show qwen25_3b_instruct
```

```python
from fairseq2.models.hub import load_model
model = load_model('qwen25_3b_instruct')
print('✓ Success!')
```

--------------------------------

### Install Specific fairseq2 Variant with PyTorch

Source: https://github.com/facebookresearch/fairseq2/blob/main/README.md

Install a specific fairseq2 variant that exactly matches your PyTorch version. Ensure PyTorch is installed first, following instructions from pytorch.org. Upgrading PyTorch requires a corresponding fairseq2 upgrade.

```sh
pip install fairseq2 \
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.9.1/cpu
```

--------------------------------

### Install s3fs package

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/guides/s3_checkpointing.rst

Install the s3fs package, which is required for S3 integration. This is typically included with fairseq2 by default.

```bash
pip install s3fs
```

--------------------------------

### Install fairseq2 Build Dependencies

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/installation_from_source.rst

Install C++ build dependencies for fairseq2, such as cmake and ninja, using pip.

```sh
pip install -r native/python/requirements-build.txt
```

--------------------------------

### Initialize fairseq2 with Custom Extension in Standalone Scripts

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/basics/runtime_extension.rst

For standalone scripts, use the `init_fairseq2` function and pass your setup function via the `extras` argument to initialize fairseq2 with your custom extension.

```python
from fairseq2 import init_fairseq2
from my_package import setup_my_fairseq2_extension

if __name__ == "__main__":
    init_fairseq2(extras=setup_my_fairseq2_extension)
```

--------------------------------

### Install fairseq2 with CUDA 12.8

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/getting_started/installation/setup_with_uv.rst

Installs fairseq2 with CUDA 12.8 support using uv sync with the 'cu128' extra.

```sh
uv sync --extra cu128
```

--------------------------------

### Working with LLaMA Models

Source: https://github.com/facebookresearch/fairseq2/blob/main/doc/source/reference/fairseq2.models.hub.rst

Demonstrates how to use the LLaMA model hub to list available architectures and load specific LLaMA models.

```python
from fairseq2.models.llama import get_llama_model_hub

hub = get_llama_model_hub()

# List available LLaMA architectures
archs = hub.get_archs()

# Load specific LLaMA model
model = hub.load_model("llama3_8b")
```

--------------------------------

### Configure CUDA RPATH for Installation

Source: https://github.com/facebookresearch/fairseq2/blob/main/native/python/src/fairseq2n/bindings/CMakeLists.txt

Conditionally adds an RPATH for CUDA runtime libraries if CUDA is enabled and NVIDIA wheels are installed.

```cmake
if(FAIRSEQ2N_USE_CUDA)
    # If NVIDIA's CUDA wheels are installed, give them precedence.
    set_property(
        TARGET
            fairseq2n
        APPEND PROPERTY
            INSTALL_RPATH
                ${rpath_origin}/../../nvidia/cuda_runtime/lib
    )
endif()
```