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

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	Single-stage flow on 64×64 images	Simple image → latent flow
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	Fine-tuned learning-rate variant	Fine-tuned texture training
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	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.

---

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 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 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 inherits from BasicTrainer and consumes the JSON configuration directly.

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

# 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	Implements FlowMatchingTrainer—core training loop for flow-matching models
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	Data pipelines respecting batch configuration
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.

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. It inherits from BasicTrainer in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}