Soup — one-command LLM fine-tuning

Soup turns fine-tuning into soup init → soup train with a single YAML config: task selection, quantization, batch size, and GPU/backend detection are all handled for you. Its headline feature, layer streaming (stream_layers: true), keeps the frozen base model out of VRAM and streams it one decoder layer at a time, so an 8B model can fine-tune on a 4 GB laptop GPU — measured bit-exact against a normal resident run.

When to use this skill

Standing up a new fine-tuning run (soup init, soup train) instead of hand-rolling a Transformers/PEFT/TRL training script
Choosing a training method (SFT vs DPO/GRPO/ORPO/SimPO/KTO/IPO/BCO) or a memory-saving scheme (QLoRA, DoRA, LoRA+, rsLoRA, layer streaming) for a constrained GPU
Estimating training cost/memory (soup cost, soup profile) before spending GPU hours, or getting a pre-flight method recommendation (soup advise)
Migrating an existing Axolotl / LLaMA-Factory / Unsloth config into Soup
Serving, merging, or pushing a trained adapter (soup serve, soup merge, soup push), or running the data-quality/eval tooling (soup data ..., soup ship)

When not to use this skill

Training infrastructure at the Ray/DeepSpeed-cluster/multi-node scale as the primary concern → use deepspeed or openrlhf-training directly; Soup wraps DeepSpeed/FSDP as launch flags, not a replacement for them
Pure inference serving of an already-merged model with no training involved → a plain inference-runtime skill is a better fit
The user is not touching Soup/PEFT/TRL at all (e.g. prompt engineering only) → route to soup advise's own verdict (it may say PROMPT_ENG, not training) rather than jumping straight into soup train

Instructions

Step 1: Install the right profile

bash pip install soup-cli # light CLI only: init/advise/data/profile/cost pip install "soup-cli[train]" # + torch/transformers/peft/trl for real training

Step 2: Decide the method before spending GPU hours

bash soup advise <data.jsonl> --goal "..." # PROMPT_ENG / RAG / SFT / DPO / GRPO verdict soup autopilot --model <id> --data d.jsonl --goal "<g>" # zero-config: picks task/quant/LR/epochs

Do not default straight to soup train; advise/autopilot exist because the wrong method (e.g. SFT when the data is a preference pair) wastes a full run.

Step 3: Scaffold and edit the config

bash soup init --template chat # or code/audio/... — see docs/models.md soup fetch <name> # pull a ready-made example config

For memory-constrained hardware, opt into layer streaming explicitly:

yaml training: stream_layers: true # base streams out of VRAM; only the adapter trains quantization: 4bit # NF4 batch_size: 4 stream_source: auto # RAM when it fits, NVMe disk otherwise

Layer streaming is BETA and supports SFT plus DPO/ORPO/SimPO/KTO — not GRPO/PPO (those re-read every layer per generated token, which defeats streaming's amortisation).

Step 4: Estimate before you commit a GPU

bash soup profile --config soup.yaml --gpu a100 soup cost --config soup.yaml --gpu H100

Step 5: Train, then verify before shipping

bash soup train --config soup.yaml soup train --config soup.yaml --gate evals/gate.yaml # eval-gated soup ship --config soup.yaml # go/no-go verdict

Step 6: Serve, merge, or push the result

bash soup infer --model ./output --input p.jsonl soup chat --model ./output soup merge --adapter ./output soup push --model ./output --repo user/name soup serve --model ./output

Step 7: Use the wrapper for a read-only environment check

bash bash .agent-skills/soup/scripts/soup.sh doctor bash .agent-skills/soup/scripts/soup.sh advise <data.jsonl> --goal "..." bash .agent-skills/soup/scripts/soup.sh profile <config.yaml>

doctor only inspects the environment (Python version, soup install, [train] extras, CUDA/MPS availability) — it never installs packages or starts a training run.

Best practices

Run soup advise/soup autopilot before soup train — picking the wrong task family (SFT vs a preference loss) is discovered only after a full training run otherwise.
soup cost/soup profile before renting a GPU — cheaper than discovering an OOM or a $40 surprise after the fact.
Layer streaming is an opt-in trade, not a default — it trades memory for extra layer-stack reads (DPO reads it ~1.52× as often as SFT); confirm the method is on the supported list (SFT/DPO/ORPO/SimPO/KTO) before enabling it.
Gate before you ship — prefer --gate evals/gate.yaml and soup ship over eyeballing loss curves.
Heavy deps stay lazy — don't suggest importing torch/transformers/ peft/trl at module top in scripts driving Soup; the project itself lazy-imports them so the light CLI stays fast.
Migrate configs, don't hand-port them — soup migrate --from axolotl|llamafactory|unsloth exists precisely to avoid manual config translation errors.

References

references/commands.md — curated command reference by workflow stage
scripts/soup.sh — read-only doctor + thin advise/profile/cost wrappers
Soup GitHub Repository
Soup docs index
Project standards: .agent-skills/skill-standardization/SKILL.md

Examples

Example 1: Pick a method, then fine-tune on a 4 GB laptop GPU

bash soup advise data.jsonl --goal "make the model follow a strict output schema" soup init --template chat

soup.yaml: set stream_layers: true, quantization: 4bit

soup profile --config soup.yaml soup train --config soup.yaml

Example 2: Environment check before recommending a training path

bash bash .agent-skills/soup/scripts/soup.sh doctor