configuration_reference.md

Configuration Reference

Libra loads its primary configuration from YAML files under configs/ into the dataclasses defined in config.py. The tables below cover the options most commonly changed for experiments and cluster deployments.

Core Options

Option	Meaning
model_path	Policy model path
tokenizer_path	Tokenizer path; defaults to model_path when empty
train_backend	Training backend; defaults to megatron_core
train_gpus	GPUs assigned to the core training pool
rollout_gpus	GPUs assigned to rollout at launch
train_tp_size	Tensor-parallel size for training
train_pp_size	Pipeline-parallel size for training
train_cp_size	Context-parallel size for Megatron-Core
batch_size	Global training batch size
n_samples	Rollouts per prompt group for GRPO
max_model_len	vLLM context length
max_new_tokens	Maximum generated tokens per rollout request
max_concurrent_rollouts	Maximum in-flight rollout tasks
max_head_offpolicyness	Maximum accepted policy-version lag
recompute_logprobs	Recompute log probabilities with the current model
sync_interval	Training steps between weight sync attempts

Megatron-Core Options

Option	Meaning
megatron_use_precision_aware_optimizer	Keep optimizer-state precision aligned with mixed precision
megatron_optimizer_cpu_offload	Offload optimizer state to CPU
megatron_optimizer_offload_fraction	Fraction of optimizer state to offload
megatron_use_cpu_initialization	Build model weights through CPU initialization
megatron_grouped_gemm	Enable grouped GEMM when available

Runtime Planner and Elastic Options

Option	Meaning
global_resource_planner.runtime_dynamic_reconfiguration_enabled	Master switch for runtime reconfiguration
initial_allocation_strategy	grp runs planning before launch; configured preserves an explicitly pinned legacy split
allocation_granularity_gpus	Initial train/rollout split granularity (normally one node or one DP replica)
min_train_gpus / min_rollout_gpus	Minimum viable capacity retained for each stage during startup planning
runtime_online_replanning	Use online metrics in planner decisions
runtime_manage_rollout_processes	Let Libra start, stop, and adopt rollout processes
runtime_rollout_reconfigure_strategy	diff, restart_all, blue_green, prewarm, or cluster_swap
runtime_cluster_swap_enabled	Enable rollout/training pool exchange without spare GPUs
runtime_reconfigure_training	Enable training-side pool changes
runtime_training_pool_plan_only	Record training-pool changes without attaching workers
decouple_communication_domains	Keep elastic gradient traffic off the core training DP process group
elastic_hybrid_replica_size_gpus	Physical ranks in one complete TP×PP×CP DP replica; zero derives it from training topology
elastic_hybrid_min_rollout_gpus	Rollout capacity that EHP may never borrow
elastic_hybrid_max_workers	Deprecated and ignored; EHP has no policy maximum
runtime_batch_collection_timeout_s	Timeout for collecting a training batch
runtime_batch_collection_max_retries	Retries after a batch collection timeout
runtime_drain_before_reconfigure	Drain in-flight rollout work before a runtime change

See the cluster manual for recommended combinations and launch examples.