# How to Configure SingleGPUModelBuilder for Loading LTX-2 Model Checkpoints

> Configure SingleGPUModelBuilder to load LTX-2 model checkpoints. Specify configurator, path, and LoRA adapters, then build your PyTorch module for single GPU use.

- Repository: [Lightricks/LTX-2](https://github.com/Lightricks/LTX-2)
- Tags: how-to-guide
- Published: 2026-06-20

---

**Use the immutable `SingleGPUModelBuilder` class to construct LTX-2 models on a single GPU by specifying a `model_class_configurator`, checkpoint path, and optional LoRA adapters, then calling `build()` to fuse weights and return a ready-to-use PyTorch module.**

Configuring the `SingleGPUModelBuilder` for loading LTX-2 model checkpoints requires understanding its immutable builder pattern and core parameters. Located in [`packages/ltx-core/src/ltx_core/loader/single_gpu_model_builder.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-core/src/ltx_core/loader/single_gpu_model_builder.py) within the Lightricks/LTX-2 repository, this class handles safetensors deserialization, meta-model instantiation, and LoRA weight fusion through a fluent API that returns a shallow copy on each configuration call.

## Understanding the SingleGPUModelBuilder Architecture

The `SingleGPUModelBuilder` follows a strict builder pattern where every configuration method returns a new instance, leaving the original untouched. This immutability ensures thread safety and configuration reusability across different model loading scenarios.

### Core Configuration Components

The builder relies on several key components defined during instantiation or chained configuration:

- **`model_class_configurator`**: A class such as `LtxModelConfigurator` that transforms model configuration dictionaries into concrete PyTorch modules (used in `meta_model()` at lines 199-202).
- **`model_path`**: File path or tuple of shard paths pointing to `.safetensors` checkpoint files containing base weights (accessed in `_load_model_weights()` at lines 44-47 and `model_config()` at lines 198-199).
- **`module_ops`**: A sequence of module-level mutations applied to the meta model before weight loading, such as `ReplaceModuleOp` (stored in `_module_ops` and applied in `build()` at lines 202-203).
- **`loras`**: Optional LoRA adapters specified as paths with strength values and optional `sd_ops`, fused into the base model during loading (managed by `lora()`, `with_loras()`, and consumed in `_load_model_weights()` at lines 70-84).
- **`model_loader`**: Strategy for reading safetensors state dictionaries, defaulting to `SafetensorsModelStateDictLoader` (initialized at lines 115-126).
- **`registry`**: Caches loaded state dictionaries to prevent redundant disk reads, defaulting to `DummyRegistry` (initialized at lines 126-128).
- **`lora_load_device`**: Device for initial LoRA tensor loading, defaulting to `cpu` to conserve GPU memory (set at lines 127-129 and passed to `_load_model_weights()`).
- **`fuse_rule`**: Policy defining LoRA weight merging mechanics, defaulting to `bf16_fuse_rule` (set at lines 128-130 and used in `_load_model_weights()` at lines 74-78).

### The Build Execution Flow

When you invoke `build(device, dtype)`, the builder executes a precise sequence of operations:

1. **Device Resolution**: Defaults to the first available CUDA device if none is specified (lines 15-16).
2. **Configuration Reading**: Parses the model config via `read_model_config()` (lines 198-199).
3. **Meta Model Creation**: Instantiates an un-materialized model on the meta device via `create_meta_model()` (lines 202-203).
4. **Weight Loading**: Populates parameters from safetensors files and fuses LoRA adapters if present (`_load_model_weights()` at lines 44-84).
5. **Verification**: Ensures no parameters remain on the meta device (`_check_uninitialized()` at lines 32-41).
6. **Device Transfer**: Moves the fully initialized model to the target GPU (`meta_model.to(device)` at line 36).

## Basic Configuration Examples

### Loading a Base Checkpoint

The simplest configuration requires only the model configurator and checkpoint path:

```python
from ltx_core.loader.single_gpu_model_builder import SingleGPUModelBuilder
from ltx_core.model.model_protocol import LtxModelConfigurator

builder = SingleGPUModelBuilder(
    model_class_configurator=LtxModelConfigurator,
    model_path="models/ltx2_v1.safetensors"
)

model = builder.build()

```

*This configuration loads the model onto the default CUDA device with `bf16` precision, reading the architecture definition from the configurator and weights from the specified safetensors file.*

### Specifying Target Device and Precision

Override the default device and data type for specific hardware configurations:

```python
builder = SingleGPUModelBuilder(
    model_class_configurator=LtxModelConfigurator,
    model_path="models/ltx2_v1.safetensors"
)

model = builder.build(device="cuda:1", dtype=torch.float16)

```

*Use this pattern for mixed-precision inference or when distributing multiple models across different GPUs.*

## Advanced Configuration Patterns

### Injecting Custom Module Operations

Apply structural modifications to the model before weight loading using `with_module_ops()`:

```python
from ltx_core.loader.module_ops import ReplaceModuleOp
from my_custom_modules import MyAttention

replace_attention = ReplaceModuleOp(
    pattern=".*attention.*",
    new_module=MyAttention
)

builder = (
    SingleGPUModelBuilder(LtxModelConfigurator, "models/ltx2_v1.safetensors")
    .with_module_ops((replace_attention,))
)

model = builder.build()

```

*The `ReplaceModuleOp` matches modules using regex patterns and substitutes them with custom implementations before the checkpoint weights are Loaded.*

### Loading and Fusing LoRA Adapters

Chain multiple LoRA configurations to fuse style adapters at different strengths:

```python
from ltx_core.loader.sd_ops import SDOps

builder = (
    SingleGPUModelBuilder(LtxModelConfigurator, "models/ltx2_v1.safetensors")
    .lora("loras/style.safetensors", strength=0.7, sd_ops=SDOps())
    .lora("loras/color.safetensors", strength=0.3, sd_ops=SDOps())
)

model = builder.build()

```

*Each `lora()` call returns a new builder instance. During `build()`, the adapters are fused on-the-fly using the configured `fuse_rule`, ensuring only the final merged weights occupy GPU memory.*

### Optimizing LoRA Loading Performance

Configure the loading device and fusion rules to optimize memory usage:

```python
builder = (
    SingleGPUModelBuilder(LtxModelConfigurator, "models/ltx2_v1.safetensors")
    .with_lora_load_device("cpu")
    .with_fuse_rule(custom_fuse_rule)
)

```

*Setting `lora_load_device` to `cpu` keeps GPU memory available during the loading phase, while custom fuse rules control how adapters merge with base weights.*

## Key Implementation Files

Understanding these source files provides deeper insight into the loading mechanics:

- **[`single_gpu_model_builder.py`](https://github.com/Lightricks/LTX-2/blob/main/single_gpu_model_builder.py)**: Contains the core immutable builder logic, including the `build()` method and weight loading orchestration (lines 1-210).
- **[`helpers.py`](https://github.com/Lightricks/LTX-2/blob/main/helpers.py)**: Implements `create_meta_model()` and `read_model_config()` for meta-model instantiation and configuration parsing.
- **[`module_ops.py`](https://github.com/Lightricks/LTX-2/blob/main/module_ops.py)**: Defines base classes for module mutations like `ReplaceModuleOp` used in pre-loading transformations.
- **[`fuse_loras.py`](https://github.com/Lightricks/LTX-2/blob/main/fuse_loras.py)**: Implements LoRA fusion policies including `bf16_fuse_rule` and the `apply_loras` function.
- **[`sft_loader.py`](https://github.com/Lightricks/LTX-2/blob/main/sft_loader.py)**: Provides `SafetensorsModelStateDictLoader` for efficient checkpoint deserialization.
- **[`model_protocol.py`](https://github.com/Lightricks/LTX-2/blob/main/model_protocol.py)**: Defines abstract interfaces for model configurators that translate config dictionaries to PyTorch modules.

## Summary

- **`SingleGPUModelBuilder`** uses an immutable builder pattern where each configuration method returns a shallow copy, enabling reusable configuration templates.
- **Core parameters** include `model_class_configurator` for architecture definition, `model_path` for checkpoint location, and optional `module_ops` for structural modifications.
- **LoRA integration** happens during the build phase through chained `lora()` calls, with weights fused according to the specified `fuse_rule` and loaded to `lora_load_device` before GPU transfer.
- **The build process** automatically handles meta-model creation, weight verification, and device placement, returning a fully initialized PyTorch module ready for inference.

## Frequently Asked Questions

### What is the difference between SingleGPUModelBuilder and direct checkpoint loading?

**`SingleGPUModelBuilder`** provides a structured, configuration-driven approach that handles complex scenarios like LoRA fusion, module replacement, and memory optimization automatically. Direct loading requires manual implementation of state dict deserialization, device placement, and adapter merging that the builder handles internally through its `_load_model_weights()` and `_check_uninitialized()` methods.

### How do I load multiple LoRA adapters with different strengths?

Chain multiple `.lora()` calls before invoking `build()`, specifying the `strength` parameter for each adapter. The builder fuses all specified adapters sequentially during the weight loading phase at lines 70-84 of [`single_gpu_model_builder.py`](https://github.com/Lightricks/LTX-2/blob/main/single_gpu_model_builder.py), applying the strength multipliers as defined in the [`fuse_loras.py`](https://github.com/Lightricks/LTX-2/blob/main/fuse_loras.py) implementation.

### Why does SingleGPUModelBuilder use the builder pattern?

The immutable builder pattern ensures that configuration objects remain thread-safe and reusable. Each method like `with_module_ops()` or `lora()` returns a shallow copy with the new setting, allowing you to create base configurations and derive specialized variants without side effects, as implemented in the constructor and chaining methods throughout the source file.

### How do I verify that all model weights loaded correctly?

The builder automatically calls `_check_uninitialized()` (lines 32-41) after weight loading to verify that no parameters remain on the meta device. If any parameters were not populated from the checkpoint or LoRA fusion, this method raises an exception before the model moves to the target GPU, ensuring complete initialization.