Diagrams — Module FTDD-05: Axolotl

Module: FTDD-05 — Axolotl: Config-Driven Production Fine-Tuning Diagram count: 4 Tool: Mermaid (primary). Each diagram validated in Mermaid Live Editor.

Diagram 1 — Config as the Source of Truth

Type: Comparison / before-and-after Purpose: The core pattern. A training recipe as a declarative file vs as an imperative script. Reading the diagram: Left = the old way (script), unreproducible. Right = the Axolotl way (YAML), reproducible / diff-able / CI-validatable. The three properties on the right are why the pattern wins.

flowchart LR
  subgraph Old["THE OLD WAY — training script"]
    S["train.py\n200 lines\nhardcoded paths\nad-hoc hyperparams"]
    S --> R1["runs once\nunreproducible in a quarter"]
  end
  subgraph New["THE AXOLOTL WAY — config"]
    Y["config.yml\nmodel · data · PEFT · hyperparams\ndistributed · eval"]
    Y --> R2["reproducible\n(diff-able, version-able, CI-validatable)"]
  end

  Old -.->|"replaced by"| New

  style S fill:#14141f,stroke:rgba(255,255,255,0.12),color:#9494a0
  style R1 fill:#08080c,stroke:rgba(255,255,255,0.08),color:#9494a0
  style Y fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8
  style R2 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4

Diagram 2 — Axolotl Wraps TRL (and Adds Multi-GPU)

Type: Layered architecture Purpose: Axolotl is not a competing engine — it is a config + orchestration layer over TRL. The decisive addition is curated multi-GPU configs. Reading the diagram: Top-down. Your YAML config enters Axolotl, which adds (1) opinionated cross-family defaults and (2) curated FSDP/DeepSpeed configs, then calls TRL's trainers, which call the HuggingFace Trainer.

block-beta
  columns 1
  Yaml["YOUR config.yml\n(base_model · datasets · adapter · LR · distributed)"]
  Axolotl["Axolotl\n+ opinionated cross-family defaults\n+ curated FSDP / DeepSpeed configs"]
  TRL["TRL Trainers\nSFTTrainer · DPOTrainer · GRPOTrainer"]
  Trainer["HuggingFace Trainer\nDDP · DeepSpeed ZeRO · FSDP"]

  Yaml --> Axolotl
  Axolotl --> TRL
  TRL --> Trainer

  style Yaml fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8
  style Axolotl fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8
  style TRL fill:#14141f,stroke:rgba(94,234,212,0.5),color:#e4e4e8
  style Trainer fill:#14141f,stroke:rgba(94,234,212,0.5),color:#e4e4e8

Diagram 3 — The Three-Way Decision: Axolotl vs Unsloth vs Raw TRL

Type: Decision tree Purpose: Which tool for which constraint. The decision is by constraint, not preference. Reading the diagram: Start at the top. Each branch ends in the tool whose strength matches the constraint.

flowchart TD
  Start["Your fine-tuning job"]
  Start --> Q1{"Multi-GPU / production /\nmust reproduce?"}
  Q1 -->|"Yes"| Ax["Axolotl\n(curated multi-GPU +\nconfig-as-source-of-truth)"]
  Q1 -->|"No"| Q2{"Single-GPU, sub-30B,\nspeed/VRAM constrained?"}
  Q2 -->|"Yes"| Un["Unsloth\n(Triton kernels: ~2x faster,\n~half VRAM)"]
  Q2 -->|"No"| Q3{"Custom reward / non-standard\nloop / brand-new method?"}
  Q3 -->|"Yes"| Raw["Raw TRL (Python API)\n(full control, freshest methods)"]
  Q3 -->|"No"| Cli["Raw TRL CLI\n(trl sft --config\nzero wrapper dependency)"]

  style Start fill:#14141f,stroke:rgba(255,255,255,0.12),color:#e4e4e8
  style Ax fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8
  style Un fill:#14141f,stroke:#5eead4,color:#e4e4e8
  style Raw fill:#14141f,stroke:#5eead4,color:#e4e4e8
  style Cli fill:#14141f,stroke:#5eead4,color:#e4e4e8

Diagram 4 — Anatomy of an Axolotl YAML

Type: Labeled structure Purpose: The five sections of a real config. What each controls. Reading the diagram: Five blocks, top to bottom. Together they are the complete, reproducible recipe.

flowchart LR
  A["1. MODEL\nbase_model\nmodel_type / tokenizer"]
  B["2. DATA\ndatasets (path, type, split)\nval_set_size"]
  C["3. PEFT\nadapter: qlora/lora/none\nlora_r · lora_alpha\ntarget_modules"]
  D["4. HYPERPARAMS\nsequence_len · batch\ngrad_accum · LR · scheduler\n(pinned explicitly)"]
  E["5. DISTRIBUTED + OUT\ndeepspeed / fsdp config\noutput_dir · save/eval steps"]

  A --> B --> C --> D --> E

  style A fill:#14141f,stroke:#5eead4,color:#e4e4e8
  style B fill:#14141f,stroke:#5eead4,color:#e4e4e8
  style C fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8
  style D fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8
  style E fill:#14141f,stroke:#5eead4,color:#e4e4e8

Validation notes

All four diagrams use the course design system colors: #14141f panel fill, #5eead4 accent for primary, rgba(255,255,255,0.08–0.12) / rgba(94,234,212,0.3–0.5) for secondary borders, #e4e4e8 / #9494a0 for text.
Paste each into Mermaid Live Editor to render. All use stable Mermaid syntax (block-beta, flowchart) supported in current Mermaid (v10.4+).
For the slide deck (artifact 03), these are rendered as static SVG/PNG captures from Mermaid Live, inlined into reveal.js.

# Diagrams — Module FTDD-05: Axolotl **Module**: FTDD-05 — Axolotl: Config-Driven Production Fine-Tuning **Diagram count**: 4 **Tool**: Mermaid (primary). Each diagram validated in [Mermaid Live Editor](https://mermaid.live). --- ## Diagram 1 — Config as the Source of Truth **Type**: Comparison / before-and-after **Purpose**: The core pattern. A training recipe as a declarative file vs as an imperative script. **Reading the diagram**: Left = the old way (script), unreproducible. Right = the Axolotl way (YAML), reproducible / diff-able / CI-validatable. The three properties on the right are why the pattern wins. ```mermaid flowchart LR subgraph Old["THE OLD WAY — training script"] S["train.py\n200 lines\nhardcoded paths\nad-hoc hyperparams"] S --> R1["runs once\nunreproducible in a quarter"] end subgraph New["THE AXOLOTL WAY — config"] Y["config.yml\nmodel · data · PEFT · hyperparams\ndistributed · eval"] Y --> R2["reproducible\n(diff-able, version-able, CI-validatable)"] end Old -.->|"replaced by"| New style S fill:#14141f,stroke:rgba(255,255,255,0.12),color:#9494a0 style R1 fill:#08080c,stroke:rgba(255,255,255,0.08),color:#9494a0 style Y fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8 style R2 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 ``` --- ## Diagram 2 — Axolotl Wraps TRL (and Adds Multi-GPU) **Type**: Layered architecture **Purpose**: Axolotl is not a competing engine — it is a config + orchestration layer over TRL. The decisive addition is curated multi-GPU configs. **Reading the diagram**: Top-down. Your YAML config enters Axolotl, which adds (1) opinionated cross-family defaults and (2) curated FSDP/DeepSpeed configs, then calls TRL's trainers, which call the HuggingFace Trainer. ```mermaid block-beta columns 1 Yaml["YOUR config.yml\n(base_model · datasets · adapter · LR · distributed)"] Axolotl["Axolotl\n+ opinionated cross-family defaults\n+ curated FSDP / DeepSpeed configs"] TRL["TRL Trainers\nSFTTrainer · DPOTrainer · GRPOTrainer"] Trainer["HuggingFace Trainer\nDDP · DeepSpeed ZeRO · FSDP"] Yaml --> Axolotl Axolotl --> TRL TRL --> Trainer style Yaml fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8 style Axolotl fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8 style TRL fill:#14141f,stroke:rgba(94,234,212,0.5),color:#e4e4e8 style Trainer fill:#14141f,stroke:rgba(94,234,212,0.5),color:#e4e4e8 ``` --- ## Diagram 3 — The Three-Way Decision: Axolotl vs Unsloth vs Raw TRL **Type**: Decision tree **Purpose**: Which tool for which constraint. The decision is by constraint, not preference. **Reading the diagram**: Start at the top. Each branch ends in the tool whose strength matches the constraint. ```mermaid flowchart TD Start["Your fine-tuning job"] Start --> Q1{"Multi-GPU / production /\nmust reproduce?"} Q1 -->|"Yes"| Ax["Axolotl\n(curated multi-GPU +\nconfig-as-source-of-truth)"] Q1 -->|"No"| Q2{"Single-GPU, sub-30B,\nspeed/VRAM constrained?"} Q2 -->|"Yes"| Un["Unsloth\n(Triton kernels: ~2x faster,\n~half VRAM)"] Q2 -->|"No"| Q3{"Custom reward / non-standard\nloop / brand-new method?"} Q3 -->|"Yes"| Raw["Raw TRL (Python API)\n(full control, freshest methods)"] Q3 -->|"No"| Cli["Raw TRL CLI\n(trl sft --config\nzero wrapper dependency)"] style Start fill:#14141f,stroke:rgba(255,255,255,0.12),color:#e4e4e8 style Ax fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8 style Un fill:#14141f,stroke:#5eead4,color:#e4e4e8 style Raw fill:#14141f,stroke:#5eead4,color:#e4e4e8 style Cli fill:#14141f,stroke:#5eead4,color:#e4e4e8 ``` --- ## Diagram 4 — Anatomy of an Axolotl YAML **Type**: Labeled structure **Purpose**: The five sections of a real config. What each controls. **Reading the diagram**: Five blocks, top to bottom. Together they are the complete, reproducible recipe. ```mermaid flowchart LR A["1. MODEL\nbase_model\nmodel_type / tokenizer"] B["2. DATA\ndatasets (path, type, split)\nval_set_size"] C["3. PEFT\nadapter: qlora/lora/none\nlora_r · lora_alpha\ntarget_modules"] D["4. HYPERPARAMS\nsequence_len · batch\ngrad_accum · LR · scheduler\n(pinned explicitly)"] E["5. DISTRIBUTED + OUT\ndeepspeed / fsdp config\noutput_dir · save/eval steps"] A --> B --> C --> D --> E style A fill:#14141f,stroke:#5eead4,color:#e4e4e8 style B fill:#14141f,stroke:#5eead4,color:#e4e4e8 style C fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8 style D fill:#14141f,stroke:#5eead4,stroke-width:1.5px,color:#e4e4e8 style E fill:#14141f,stroke:#5eead4,color:#e4e4e8 ``` --- ## Validation notes - All four diagrams use the course design system colors: `#14141f` panel fill, `#5eead4` accent for primary, `rgba(255,255,255,0.08–0.12)` / `rgba(94,234,212,0.3–0.5)` for secondary borders, `#e4e4e8` / `#9494a0` for text. - Paste each into [Mermaid Live Editor](https://mermaid.live) to render. All use stable Mermaid syntax (`block-beta`, `flowchart`) supported in current Mermaid (v10.4+). - For the slide deck (artifact 03), these are rendered as static SVG/PNG captures from Mermaid Live, inlined into reveal.js.