Configuration System

The Configuration System in AReaL provides a hierarchical, type-safe mechanism for specifying experiment parameters through dataclass-based configurations. This system supports YAML configuration files, command-line argument overrides, and sensible defaults, enabling reproducible experiments with flexible parameter tuning.

Scope: This page covers the configuration architecture, dataclass structures, precedence rules, and validation mechanisms.

• For detailed parameter references, see CLI Arguments Reference.
• For resource allocation syntax, see allocation_mode Syntax.
• For specific engine configurations, see Training Engine Configurations and Inference Engine Configurations.
• For text generation settings, see Generation Hyperparameters.
• For micro-batching and data settings, see MicroBatchSpec and Data Configurations.
• For RL algorithm parameters, see Algorithm-Specific Configurations.

Configuration Architecture

AReaL's configuration system follows a three-tier precedence hierarchy where CLI arguments override YAML values, which in turn override dataclass defaults. This design enables template-based experimentation with selective parameter customization.

Sources: areal/api/cli_args.py1-32 docs/en/cli_reference.md1-20

The configuration flow starts with Hydra's compose mechanism, which merges YAML files with CLI overrides areal/api/cli_args.py14-17 The merged DictConfig is then validated through __post_init__ methods in each dataclass, ensuring type safety and constraint satisfaction before execution begins. For more details on the hierarchy, see Configuration Overview.

Configuration Precedence Rules

The precedence hierarchy ensures predictable parameter resolution:

Example Resolution:

Parameter	CLI Value	YAML Value	Default Value	Final Value	Source
actor.lr	1e-4	5e-5	1e-3	1e-4	CLI
seed	-	42	1	42	YAML
total_train_epochs	-	-	1	1	Default

Sources: areal/api/cli_args.py39-138 docs/en/cli_reference.md92-111

Configuration Categories

AReaL organizes configurations into hierarchical categories, each serving a specific purpose in the training pipeline. For a full list of available flags, see CLI Arguments Reference.

Sources: areal/api/cli_args.py39-210 docs/en/cli_reference.md23-85 areal/experimental/engine/archon_engine.py144-162

Base Experiment Configuration

BaseExperimentConfig provides the foundation for all experiment types, containing shared parameters like experiment naming, seeding, and dataset specifications docs/en/cli_reference.md95-111

Configuration Class	Purpose	Key Fields
BaseExperimentConfig	Root experiment configuration	experiment_name, trial_name, seed, train_dataset, saver
TrainDatasetConfig	Training dataset specification	type, data_dir, tokenizer_path
ValidDatasetConfig	Validation dataset specification	Inherits from TrainDatasetConfig

Sources: docs/en/cli_reference.md89-111 areal/api/cli_args.py39-138

Training Engine Configuration

TrainEngineConfig controls model training behavior, including backend selection, optimization, and parallelism. For detailed backend options, see Training Engine Configurations.

Sources: areal/engine/fsdp_engine.py219-221 areal/engine/megatron_engine.py168-177 areal/experimental/engine/archon_engine.py147-196

Inference Engine Configuration

InferenceEngineConfig manages distributed inference backends and resource allocation. The allocation_mode field is used to define GPU parallel strategies docs/en/cli_reference.md104 For details on the allocation syntax, see allocation_mode Syntax.

Field	Type	Purpose
allocation_mode	str	Resource allocation pattern (e.g., "sglang:d4")
max_batch_size	int	Maximum concurrent requests
sglang	SGLangConfig	SGLang-specific settings
vllm	vLLMConfig	vLLM-specific settings

Sources: areal/api/cli_args.py139-210 docs/en/cli_reference.md44-50

Validation and Constraints

Each configuration dataclass implements validation in __post_init__ methods to ensure runtime stability.

Example: NormConfig Validation

The NormConfig class validates normalization levels for rewards and advantages areal/api/cli_args.py42-78 For more algorithm-specific settings, see Algorithm-Specific Configurations.

Sources: areal/api/cli_args.py42-96

Example: MicroBatchSpec Validation

The MicroBatchSpec class manages micro-batch splitting behavior areal/api/cli_args.py99-139 For details on how this affects data loading, see MicroBatchSpec and Data Configurations.

Field	Type	Default	Validation
n_mbs	int | None	1	Minimum number of micro-batches areal/api/cli_args.py102-107
granularity	int	1	Grouping size for micro-batches areal/api/cli_args.py108-113
max_tokens_per_mb	int | None	None	If set, triggers dynamic splitting areal/api/cli_args.py114-119
n_mbs_divisor	int	1	Adjusts n_mbs for parallel divisibility areal/api/cli_args.py120-125
packing_algorithm	str	"ffd"	Supported: "ffd", "kk" areal/api/cli_args.py126-138

Sources: areal/api/cli_args.py99-148

Configuration Usage Patterns

Engine Initialization

Training engines consume TrainEngineConfig during initialization to set up optimizers and device meshes:

Sources: areal/engine/fsdp_engine.py218-222 areal/engine/megatron_engine.py168-177 areal/experimental/engine/archon_engine.py147-158

Text Generation Control

Rollout workflows use GenerationHyperparameters to control decoding diversity and length areal/api/cli_args.py163-210 For a deep dive into these parameters, see Generation Hyperparameters.

Parameter	Default	Purpose
temperature	1.0	Controls sampling randomness areal/api/cli_args.py193-196
top_p	1.0	Nucleus sampling threshold areal/api/cli_args.py185-188
max_new_tokens	16384	Generation limit areal/api/cli_args.py169-171

Sources: areal/api/cli_args.py163-210