Axolotl — Config-Driven Production Fine-Tuning

Module FTDD-05 · Course 3 — LLM Fine-Tuning Masterclass

45 minutes · 4 sub-sections: The Config Pattern · Under the Hood · The Three-Way Decision · Reading a Config

One YAML describes the whole run. Underneath, it's still TRL.

Deep-Dives

The core idea: config as source of truth

The training recipe should be a declarative file, not a program.

Old way — train.py

200 lines, hardcoded paths, ad-hoc hyperparams.

Runs once. Unreproducible in a quarter.

Axolotl — config.yml

Model · data · PEFT · hyperparams · distributed · eval.

Reproducible. Diff-able. CI-validatable.

Why config-not-code wins in production

PropertyWhy it matters
Reproducibility is a file"Reproduce my run" = "run this file." No reverse-engineering a script.
Diff-able & version-ableA git diff shows exactly what changed between two runs.
CI-validatableA YAML can be linted + schema-validated before touching a GPU. A script cannot.

The same reason Kubernetes manifests are YAML, not Python: declarative config is auditable in a way imperative code is not.

Under the hood: Axolotl wraps TRL

Axolotl is not a competing engine. Underneath the YAML, it calls TRL's trainers — SFTTrainer, DPOTrainer, GRPOTrainer.

Two things the wrapper adds that raw TRL does not:

  • Opinionated cross-family defaults — known-good sequence lengths, grad accum, PEFT configs across Llama / Mistral / Qwen.
  • Battle-tested multi-GPU orchestration — curated FSDP / DeepSpeed configs that are fiddly + error-prone to write by hand.

Cost: a layer of abstraction. Slight latency on bleeding-edge methods; debuggability through Axolotl → TRL → Transformers.

The three-way decision

Choose by constraint, not preference.

If your constraint is...Reach for
Multi-GPU production, must reproduce, standard recipeAxolotl
Single GPU, sub-30B, speed / VRAM constrainedUnsloth
Custom reward, non-standard loop, brand-new method, full controlRaw TRL (Python API)
Standard recipe, zero code, no wrapper dependencyRaw TRL CLI
The hybrid pattern: Unsloth for sub-30B single-GPU, Axolotl for multi-GPU / >30B. Not indecision — each tool for its strength.

Anatomy of an Axolotl YAML

Five sections. The complete, reproducible recipe.

# 1. MODEL
base_model: meta-llama/Llama-3.1-8B
# 2. DATA
datasets:
  - path: HuggingFaceTB/smoltalk
    type: chat_template
val_set_size: 0.02
# 3. PEFT
adapter: qlora            # qlora | lora | none
lora_r: 16
lora_target_modules: [q_proj, k_proj, v_proj, o_proj]
# 4. HYPERPARAMS (pinned)
learning_rate: 2e-4
micro_batch_size: 2
gradient_accumulation_steps: 8
# 5. DISTRIBUTED + OUT
deepspeed: deepspeed_configs/zero2.json
output_dir: ./out/llama31-8b-smoltalk

What to notice in the config

  • Everything is pinned. No magic defaults. learning_rate, lora_r, sequence_len — all explicit.
  • PEFT is a section. QLoRA → LoRA → full FT is changing adapter: — one line, not a rewrite.
  • Multi-GPU is a config value. deepspeed: or fsdp: — Axolotl's curated configs are the value-add over raw TRL.
  • Eval is first-class. val_set_size / eval_steps declared in the source of truth.

The reproducibility checklist

Before treating a config as production-ready:

  • Every hyperparameter pinned (no reliance on a default)?
  • Dataset path AND split explicit?
  • Distributed strategy declared (single-GPU / FSDP / named DeepSpeed)?
  • Precision known (what did bf16: auto resolve to)?
  • Eval declared?
  • Could a colleague reproduce this from the YAML alone?
Six yeses = your run is reproducible. That is the bar Axolotl was built to clear.

Anti-patterns

Config as documentation, not source. "Tweaking live" via CLI overrides so the on-disk YAML no longer matches what ran. Commit every override into the YAML.
Axolotl for a custom reward. Axolotl is configured, not programmed. A GRPO job with a custom reward function cannot live in YAML — drop to raw TRL.
Assuming the wrapper removes the need to understand TRL. A TRL-level problem is still your problem. Learn TRL first; Axolotl is the layer above.

What you can now do

  1. Explain the declarative YAML pattern and why config-as-source-of-truth wins in production.
  2. Describe how Axolotl wraps TRL and what the wrapper adds (defaults + multi-GPU).
  3. Choose between Axolotl, Unsloth, and raw TRL by constraint.
  4. Read and write an Axolotl YAML across its five sections.

Next: FTDD-06 — Dolphin / Hermes · Uncensored lineages as engineering case studies

Course 3 — LLM Fine-Tuning Masterclass · FTDD-05 · Deep-Dives