# TRELLIS.2 Flow Model Training: Key Hyperparameters and Config Files Explained

> Master TRELLIS.2 flow model training by understanding key hyperparameters and config files. Learn about batch size, learning rate, max steps, and grad clip for optimal results.

- Repository: [Microsoft/TRELLIS.2](https://github.com/microsoft/TRELLIS.2)
- Tags: how-to-guide
- Published: 2026-08-04

---

**TRELLIS.2 flow model training is controlled entirely through JSON configuration files in `configs/gen/`, with hyperparameters including `batch_size_per_gpu`, `batch_split`, `lr`, `max_steps`, and `grad_clip` consumed by the `FlowMatchingTrainer` class.**

TRELLIS.2 uses **flow-matching** trainers to learn continuous latent flows for 3-D generation. The training pipeline relies on JSON configuration files located under `configs/gen/` that define every aspect of training—from batch layout to optimizer settings. This guide breaks down the essential hyperparameters and configuration files you need to train or fine-tune TRELLIS.2 flow models.

---

## Core Configuration Files for TRELLIS.2 Flow Training

The repository provides several pre-configured JSON files for different training scenarios. These files are the **single source of truth** for every training run.

| Config File | Purpose | Typical Use Case |
|-------------|---------|----------------|
| [`configs/gen/ss_flow_img_dit_1_3B_64_bf16.json`](https://github.com/microsoft/TRELLIS.2/blob/main/configs/gen/ss_flow_img_dit_1_3B_64_bf16.json) | Single-stage flow on 64×64 images | Simple image → latent flow |
| [`configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json`](https://github.com/microsoft/TRELLIS.2/blob/main/configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json) | Image + shape → texture flow (full-size) | Large-scale texture synthesis |
| [`configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json`](https://github.com/microsoft/TRELLIS.2/blob/main/configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json) | Fine-tuned learning-rate variant | Fine-tuned texture training |
| [`configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16.json`](https://github.com/microsoft/TRELLIS.2/blob/main/configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16.json) | Image → shape latent flow | Shape reconstruction |
| [`configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16_ft1024.json`](https://github.com/microsoft/TRELLIS.2/blob/main/configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16_ft1024.json) | Fine-tuned image-to-shape flow | Fine-tuned shape generation |

Changing values in these configs automatically propagates to the trainer via the generic `BasicTrainer` infrastructure in [`trellis2/trainers/basic.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/trainers/basic.py).

---

## Essential TRELLIS.2 Flow Model Hyperparameters

Each JSON configuration follows a consistent schema defining optimizer, scheduler, and training loop parameters.

### Batch and Training Duration Settings

| Parameter | Description | Typical Values |
|-----------|-------------|--------------|
| `batch_size_per_gpu` | Samples processed per GPU before gradient accumulation | `8` (full training), `2` (fine-tuned) |
| `batch_split` | Gradient accumulation steps; effective batch size = `batch_size_per_gpu × batch_split` | `2` (default), `1` (fine-tuned) |
| `max_steps` | Total optimizer steps before training terminates | `1000000` |

These appear in config files such as [`configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json`](https://github.com/microsoft/TRELLIS.2/blob/main/configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json) at lines 70-72 for `max_steps`, `batch_size_per_gpu`, and `batch_split` respectively.

### Learning Rate and Optimization

| Parameter | Description | Typical Values |
|-----------|-------------|--------------|
| `lr` | Base learning rate for Adam optimizer | `1e-4` (standard), `2e-5` (fine-tuned) |
| `optimizer` | Optimizer configuration dictionary | `{"name": "Adam", "args": {"betas": [0.9, 0.99]}}` |
| `lr_scheduler` | Learning rate schedule specification | `{"name": "CosineAnnealingLR", "args": {"T_max": 1000000}}` |
| `grad_clip` | Optional gradient clipping threshold | `1.0` (or omitted) |

Fine-tuned configs like [`slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json`](https://github.com/microsoft/TRELLIS.2/blob/main/slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json) reduce the learning rate to `2e-5` at line 77 for more stable convergence on pre-trained weights.

---

## How Configuration Flows to the Trainer

The `FlowMatchingTrainer` class in [`trellis2/trainers/flow_matching/flow_matching.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/trainers/flow_matching/flow_matching.py) inherits from `BasicTrainer` and consumes the JSON configuration directly.

```python
import json
from pathlib import Path
from trellis2.trainers.flow_matching.flow_matching import FlowMatchingTrainer

# Load configuration

config_path = Path("configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json")
with open(config_path) as f:
    cfg = json.load(f)

# Instantiate trainer—class name resolved from cfg["trainer"]

trainer = FlowMatchingTrainer(**cfg)

# Execute training loop until max_steps

trainer.train()

```

Under the hood, `BasicTrainer` handles:

- **Optimizer construction**: Builds `torch.optim.Adam` with `cfg["optimizer"]` specifications
- **Scheduler attachment**: Wraps the optimizer with `CosineAnnealingLR` or configured alternative
- **Gradient clipping**: Applies threshold from `cfg["grad_clip"]` when present
- **Batch management**: Coordinates `batch_size_per_gpu` and `batch_split` for gradient accumulation
- **Training termination**: Stops automatically after `max_steps` steps

---

## Complete Training Script Example

```python

# run_flow_training.py

import json
from pathlib import Path
from trellis2.trainers.flow_matching.flow_matching import FlowMatchingTrainer

def main():
    # Select configuration based on training goal

    cfg_path = Path("configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json")
    
    with open(cfg_path) as f:
        config = json.load(f)
    
    # Initialize and launch training

    trainer = FlowMatchingTrainer(**config)
    trainer.train()  # Runs until config["max_steps"]

if __name__ == "__main__":
    main()

```

Execute with `python run_flow_training.py` to launch full-scale flow model training using the exact hyperparameters defined in your selected JSON config.

---

## Key Source Files Reference

| File Path | Role in Training |
|-----------|----------------|
| [`trellis2/trainers/flow_matching/flow_matching.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/trainers/flow_matching/flow_matching.py) | Implements `FlowMatchingTrainer`—core training loop for flow-matching models |
| [`trellis2/trainers/basic.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/trainers/basic.py) | Contains `BasicTrainer`—parses optimizer, scheduler, batch, and clipping settings |
| `configs/gen/*.json` | Central hyperparameter definitions for all training scenarios |
| [`trellis2/datasets/structured_latent.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/datasets/structured_latent.py) | Data pipelines respecting batch configuration |
| [`trellis2/models/sparse_structure_flow.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/models/sparse_structure_flow.py) | Flow model architecture consumed by the trainer |

These files collectively define the complete TRELLIS.2 flow model training system.

---

## Summary

- **Configuration-driven**: All TRELLIS.2 flow training hyperparameters live in JSON files under `configs/gen/`
- **Key hyperparameters**: `batch_size_per_gpu`, `batch_split`, `lr`, `max_steps`, `grad_clip`, `optimizer`, and `lr_scheduler`
- **Trainer architecture**: `FlowMatchingTrainer` consumes configs via `BasicTrainer` infrastructure
- **Fine-tuning support**: Separate config files (`*_ft1024.json`) provide reduced learning rates and adjusted batch settings
- **No code changes required**: Modify JSON values to experiment with training configurations

---

## Frequently Asked Questions

### What is the default learning rate for TRELLIS.2 flow model training?

The standard training configs use a learning rate of `1e-4`. Fine-tuning configs reduce this to `2e-5` for more stable convergence when training from pre-trained checkpoints, as implemented in files like [`slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json`](https://github.com/microsoft/TRELLIS.2/blob/main/slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json).

### How does gradient accumulation work in TRELLIS.2 training?

The effective batch size equals `batch_size_per_gpu × batch_split`. With default values of `8` and `2`, you achieve an effective batch size of 16. Fine-tuned configs often use `batch_split: 1` to reduce memory overhead when processing higher-resolution data or larger models.

### Where is the FlowMatchingTrainer class defined?

The `FlowMatchingTrainer` class is defined in [`trellis2/trainers/flow_matching/flow_matching.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/trainers/flow_matching/flow_matching.py). It inherits from `BasicTrainer` in [`trellis2/trainers/basic.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/trainers/basic.py), which handles the generic configuration parsing for optimizers, schedulers, and training loop parameters.

### Can I train without modifying Python source code?

Yes. The TRELLIS.2 architecture is designed so that all training hyperparameters are specified in JSON configuration files. You can adjust batch sizes, learning rates, training duration, and optimizer settings by editing the appropriate file in `configs/gen/` without touching any Python code.