Where to Find the Central Configuration Object for LlamaFactory: A Complete Guide

The central configuration object for LlamaFactory is the tuple returned by get_args() in src/llamafactory/v1/config/arg_parser.py, which parses YAML, JSON, or CLI inputs into four specialized dataclass containers.

LlamaFactory unifies its training, inference, and API pipelines through a robust configuration system built on Python dataclasses. Understanding where this central configuration object resides and how to access it is essential for customizing model behavior, extending the framework, or debugging training runs.

Understanding the Central Configuration Architecture

Rather than a single monolithic dictionary, LlamaFactory distributes configuration across four specialized argument containers. This modular design separates concerns between model loading, data processing, training hyperparameters, and generation settings.

The Four Core Argument Containers

The central configuration object is actually a tuple containing these four dataclass instances:

• ModelArguments – Defines model architecture, checkpoint paths, quantization settings, and adapter configurations (defined in src/llamafactory/v1/config/model_args.py).
• DataArguments – Controls dataset paths, preprocessing options, template selection, and data collator behavior (defined in src/llamafactory/v1/config/data_args.py).
• TrainingArguments – Contains optimizer settings, learning rate schedules, batch sizes, and distributed training flags (defined in src/llamafactory/v1/config/training_args.py).
• SampleArguments – Governs generation parameters like temperature, top-p sampling, and maximum new tokens (defined in src/llamafactory/v1/config/sample_args.py).

Locating the Central Configuration Parser

The entry point that instantiates these objects is get_args() located in src/llamafactory/v1/config/arg_parser.py. This function serves as the canonical accessor for the central configuration object across the entire codebase.

# src/llamafactory/v1/config/arg_parser.py

def get_args(args: InputArgument = None) -> tuple[
        ModelArguments, DataArguments, TrainingArguments, SampleArguments]:
    """Parse arguments from command line or config file."""
    parser = HfArgumentParser(
        [ModelArguments, DataArguments, TrainingArguments, SampleArguments])
    # ... parsing logic using OmegaConf for YAML/JSON merging

    return tuple(parsed_args)

The function leverages HfArgumentParser from the Hugging Face ecosystem and OmegaConf to merge configuration files with command-line overrides.

Configuration File Structure and Locations

Each argument dataclass resides in its own module within the src/llamafactory/v1/config/ package. The package initializer (src/llamafactory/v1/config/__init__.py) re-exports these classes for convenient imports.

Model Arguments (model_args.py)

Located at src/llamafactory/v1/config/model_args.py, this dataclass handles:

• model_name_or_path: Hugging Face model identifier or local path
• adapter_name_or_path: LoRA/QLoRA checkpoint paths
• quantization_bit: Bits for quantization (4, 8)
• template: Chat template selection

Data Arguments (data_args.py)

Found in src/llamafactory/v1/config/data_args.py, controlling:

• dataset: Dataset name or path
• cutoff_len: Maximum sequence length
• preprocessing_num_workers: Parallel preprocessing workers
• val_size: Validation split ratio

Training Arguments (training_args.py)

Defined in src/llamafactory/v1/config/training_args.py, extending Hugging Face's TrainingArguments with:

• stage: Training stage (pt, sft, rm, ppo, dpo)
• finetuning_type: Fine-tuning method (lora, full, freeze)
• lora_target: Target modules for LoRA adaptation
• deepspeed: DeepSpeed configuration path

Sample Arguments (sample_args.py)

Located at src/llamafactory/v1/config/sample_args.py, managing generation:

• temperature: Sampling temperature
• top_p: Nucleus sampling threshold
• max_new_tokens: Generation length limit
• repetition_penalty: Token repetition penalty

Practical Usage Examples

Loading Configuration from YAML

To load a central configuration object from a YAML file, pass the file path to get_args():

from llamafactory.v1.config import get_args

# Load from YAML configuration

model_args, data_args, training_args, sample_args = get_args(
    ["examples/finetune.yaml"]
)

print(model_args.model_name_or_path)   # "meta-llama/Meta-Llama-3-8B-Instruct"

print(training_args.output_dir)        # "outputs/llama3_lora_sft"

Overriding Settings via Command Line

The central configuration object supports CLI overrides through OmegaConf merging:

python -m llamafactory.train \
    examples/finetune.yaml \
    --output_dir my_custom_run \
    --learning_rate 5e-5 \
    --lora_target q_proj,v_proj

Inside arg_parser.py, these CLI arguments merge with the base YAML configuration before instantiation.

Accessing Configuration in Custom Scripts

For programmatic modification of the central configuration object:

from llamafactory.v1.config import get_args, ModelArguments, DataArguments

# Get default or parsed args

model_args, data_args, training_args, _ = get_args()

# Modify specific parameters

training_args.micro_batch_size = 4
training_args.global_batch_size = 32
training_args.learning_rate = 2e-5

# Use in custom training loop

print(f"Training with batch size {training_args.micro_batch_size}")

Integration with Entry Points

The central configuration object is consumed by all major entry points in the LlamaFactory repository:

• src/train.py: Invokes model_args, data_args, training_args, sample_args = get_args() to configure supervised fine-tuning, DPO, or pre-training pipelines.
• src/api.py: Uses the same pattern to load model and sampling configurations for OpenAI-compatible API serving.
• Web UI: The Gradio interface internally constructs argument lists that feed into get_args() before launching training jobs.

According to the LlamaFactory source code, this unified access pattern ensures consistent configuration handling across CLI, API, and web interfaces.

Summary

• The central configuration object for LlamaFactory is the tuple (ModelArguments, DataArguments, TrainingArguments, SampleArguments) returned by get_args() in src/llamafactory/v1/config/arg_parser.py.
• Configuration is split across four specialized dataclasses located in src/llamafactory/v1/config/, each handling distinct aspects: model loading, data processing, training hyperparameters, and generation sampling.
• The get_args() function parses YAML, JSON, and CLI inputs using HfArgumentParser and OmegaConf, merging configuration sources before instantiation.
• All entry points (src/train.py, src/api.py, and the Web UI) consume this central configuration tuple to drive training, inference, and API serving pipelines.

Frequently Asked Questions

What is the central configuration object in LlamaFactory?

The central configuration object is a tuple containing four dataclass instances—ModelArguments, DataArguments, TrainingArguments, and SampleArguments—returned by the get_args() function. This object encapsulates all settings needed to load models, process datasets, configure training loops, and control text generation sampling.

How do I load a custom YAML configuration file?

Pass the file path as a list element to get_args():

from llamafactory.v1.config import get_args
model_args, data_args, training_args, sample_args = get_args(["path/to/config.yaml"])

The parser automatically detects the file extension and uses OmegaConf to load the YAML content, merging it with any additional command-line arguments.

Can I modify configuration arguments programmatically?

Yes. After calling get_args(), you can modify the attributes of the returned dataclass instances before passing them to trainers or model engines. For example, you can adjust training_args.learning_rate or model_args.adapter_name_or_path dynamically based on runtime conditions.

Where are the configuration dataclasses defined?

The four core dataclasses are defined in separate modules within src/llamafactory/v1/config/:

• model_args.py contains ModelArguments
• data_args.py contains DataArguments
• training_args.py contains TrainingArguments
• sample_args.py contains SampleArguments

All are re-exported through src/llamafactory/v1/config/__init__.py for convenient importing.

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