Fine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.
Python cliconsumer-gpudpofine-tuningggufhuggingfacellmllmopslocal-ailocal-llmloralow-vrammachine-learningollamapeftpythonpytorchqlorasfttransformers
"""Axolotl config → Soup config migration."""
from pathlib import Path
from typing import Any, Dict, List
from soup_cli.config.schema import SFT_KERNEL_AWARE_TASKS
from soup_cli.migrate.common import to_number, unmapped_keys_warning, validation_split
from soup_cli.utils.yaml_limits import MAX_CONFIG_BYTES, load_yaml_file_limited
# Axolotl rl → Soup task mapping
_RL_MAP = {
"dpo": "dpo",
"kto": "kto",
"grpo": "grpo",
"gdpo": "grpo",
"orpo": "orpo",
"ipo": "ipo",
"simpo": "simpo",
}
# Axolotl dataset type → Soup format
_FORMAT_MAP = {
"alpaca": "alpaca",
"sharegpt": "sharegpt",
"chat_template": "chatml",
"completion": "auto",
}
# Optimizer name mapping
_OPTIMIZER_MAP = {
"adamw_8bit": "adamw_bnb_8bit",
}
# Every top-level key this migrator reads, mapped or warned about by name. Any
# other key in the source is listed in one "not migrated" warning (#1807).
_HANDLED_KEYS = frozenset({
"base_model", "rl", "datasets", "sequence_len", "val_set_size", "adapter", "lora_r",
"lora_alpha", "lora_dropout", "lora_target_linear", "lora_target_modules",
"micro_batch_size", "gradient_accumulation_steps", "num_epochs", "learning_rate",
"optimizer", "lr_scheduler", "warmup_ratio", "load_in_4bit", "load_in_8bit",
"flash_attention", "output_dir", "sample_packing", "wandb_project",
})
# Task → default data format
_TASK_FORMAT_MAP = {
"sft": None, # Use dataset type
"dpo": "dpo",
"kto": "kto",
"grpo": "auto",
"orpo": "dpo",
"ipo": "dpo",
"simpo": "dpo",
}
def migrate_axolotl(config_path: Path) -> Dict[str, Any]:
"""Parse an Axolotl YAML config and return a Soup config dict.
Returns a dict suitable for config_to_yaml(). Includes a ``_warnings``
key with a list of human-readable migration notes.
"""
raw = load_yaml_file_limited(
config_path, f"Config file {config_path}", max_bytes=MAX_CONFIG_BYTES
)
if not raw or not isinstance(raw, dict):
raise ValueError("Config file is empty or not a valid YAML mapping")
if "base_model" not in raw:
raise ValueError("Missing required key: base_model")
warnings: List[str] = []
# --- Base model ---
base = raw["base_model"]
# --- Task ---
rl_type = raw.get("rl")
if rl_type:
if rl_type not in _RL_MAP:
supported = ", ".join(sorted(_RL_MAP))
raise ValueError(
f"No Soup task matches axolotl rl: {rl_type}. Supported rl "
f"values are {supported}."
)
task = _RL_MAP[rl_type]
else:
task = "sft"
# --- Data ---
data: Dict[str, Any] = {}
datasets = raw.get("datasets", [])
if datasets:
first_ds = datasets[0]
data["train"] = first_ds.get("path", "./data/train.jsonl")
ds_type = first_ds.get("type", "auto")
# Use task-specific format or dataset type
task_fmt = _TASK_FORMAT_MAP.get(task)
if task_fmt:
data["format"] = task_fmt
else:
data["format"] = _FORMAT_MAP.get(ds_type, ds_type)
if len(datasets) > 1:
warnings.append(
f"Multiple datasets found ({len(datasets)}). "
"Only the first dataset was imported. "
"Soup uses a single data.train path — merge datasets with "
"'soup data merge' first."
)
else:
data["train"] = "./data/train.jsonl"
data["format"] = "auto"
warnings.append("No datasets specified. Using placeholder path.")
if "sequence_len" in raw:
data["max_length"] = raw["sequence_len"]
# val_set_size: axolotl's default is 0 (train on every row); without this
# mapping every migrated config got Soup's default of 0.1 (#1807).
val_split = validation_split(raw.get("val_set_size"), "val_set_size", warnings)
if val_split is not None:
data["val_split"] = val_split
# --- LoRA / Full Fine-tuning ---
adapter = raw.get("adapter")
lora_section: Dict[str, Any] = {}
include_lora = adapter in ("lora", "qlora")
if adapter and not include_lora:
warnings.append(f"adapter: {adapter} has no Soup equivalent. Using LoRA instead.")
include_lora = True
if include_lora:
if "lora_r" in raw:
lora_section["r"] = raw["lora_r"]
if "lora_alpha" in raw:
lora_section["alpha"] = raw["lora_alpha"]
if "lora_dropout" in raw:
lora_section["dropout"] = raw["lora_dropout"]
if raw.get("lora_target_linear"):
# Every linear layer; peft's spelling is ``all-linear``. ``auto`` would
# resolve to q_proj / v_proj on Llama, two of seven (#1807).
lora_section["target_modules"] = "all-linear"
elif "lora_target_modules" in raw:
lora_section["target_modules"] = raw["lora_target_modules"]
else:
# No adapter specified -> full fine-tuning requested
if task in ("sft", "embedding"):
warnings.append(
f"No adapter specified for task '{task}' - "
"full fine-tuning will be used (lora.r: 0)."
)
lora_section["r"] = 0
else:
raise ValueError(
f"No adapter specified for task '{task}', but Soup only supports full "
"fine-tuning (lora.r: 0) for sft and embedding tasks. "
"Specify an adapter (lora/qlora)."
)
# --- Training ---
training: Dict[str, Any] = {}
if "micro_batch_size" in raw:
training["batch_size"] = raw["micro_batch_size"]
if "gradient_accumulation_steps" in raw:
training["gradient_accumulation_steps"] = raw["gradient_accumulation_steps"]
if "num_epochs" in raw:
training["epochs"] = raw["num_epochs"]
if "learning_rate" in raw:
training["lr"] = to_number(raw["learning_rate"])
if "optimizer" in raw:
opt = raw["optimizer"]
training["optimizer"] = _OPTIMIZER_MAP.get(opt, opt)
if "lr_scheduler" in raw:
training["scheduler"] = raw["lr_scheduler"]
if "warmup_ratio" in raw:
training["warmup_ratio"] = raw["warmup_ratio"]
# Quantization
if lora_section.get("r") == 0:
training["quantization"] = "none"
elif adapter == "qlora" or raw.get("load_in_4bit"):
training["quantization"] = "4bit"
elif raw.get("load_in_8bit"):
training["quantization"] = "8bit"
else:
training["quantization"] = "none"
# Flash attention. use_flash_attn is only read by the SFT-family trainer
# (#806), so mapping it for any other task produces a config the loader
# then refuses; drop it and say why instead of handing back a file the
# next `soup train` rejects.
if raw.get("flash_attention"):
if task in SFT_KERNEL_AWARE_TASKS:
training["use_flash_attn"] = True
else:
warnings.append(
f"flash_attention was set but task '{task}' does not use it "
f"(only {sorted(SFT_KERNEL_AWARE_TASKS)} read use_flash_attn). Dropped."
)
# Add lora section
if lora_section:
training["lora"] = lora_section
# --- Output ---
output = raw.get("output_dir", "./output")
# --- Unsupported features ---
if raw.get("sample_packing"):
warnings.append(
"sample_packing is not supported in Soup. "
"Sequences will be padded individually."
)
if raw.get("wandb_project"):
warnings.append(
f"wandb_project: {raw['wandb_project']}. Use --wandb flag with soup train."
)
dropped = unmapped_keys_warning(raw, _HANDLED_KEYS, "axolotl")
if dropped is not None:
warnings.append(dropped)
result: Dict[str, Any] = {
"base": base,
"task": task,
"data": data,
"training": training,
"output": output,
"_warnings": warnings,
}
return result