soup
Fine-tune and post-train large language models from one YAML config
TLDR
SYNOPSIS
soup [global-options] command [args]
DESCRIPTION
soup is the command-line interface for Soup (PyPI package soup-cli): a Python toolkit that turns LLM fine-tuning into a single config file and a few subcommands. You describe base model, data, task type, and training knobs in soup.yaml, then run soup train. The same binary covers data prep, evaluation, export, local serving, adapter management, and shipping gates.The default pip install soup-cli is intentionally light (CLI, config, and data tools without PyTorch). Fine-tuning needs pip install "soup-cli[train]" (or [all] for the full optional stack). Training can run on CUDA GPUs, Apple Silicon (MPS), or CPU for smoke tests; optional extras enable Unsloth, MLX, serving backends, UI, and more.Supported data formats include Alpaca, ShareGPT, ChatML, preference pairs (DPO-style), KTO, vision, audio, and pretraining text. Models load through Hugging Face AutoModelForCausalLM, so most Hub text-generation checkpoints work without custom glue code.
PARAMETERS
init [--template name]
Create a soup.yaml config interactively or from a template (chat, code, tool-calling, medical, reasoning, vision, compliance templates such as hipaa / soc2, and others).train --config file
Run supervised or preference fine-tuning (SFT, DPO, KTO, ORPO, SimPO, GRPO, PPO, and more) from YAML. Handles LoRA/QLoRA, batch size, quantization, and multi-GPU when the [train] extra is installed. Optional layer streaming (stream_layers: true) keeps the frozen base out of VRAM for small GPUs.chat --model path
Interactive chat against a local model or adapter directory.infer --model path --input file
Batch inference over prompts (JSONL and related formats).serve --model path [--port n] [--backend name]
Serve an OpenAI-compatible HTTP API (optional backends include vllm, sglang).merge --adapter path
Merge a LoRA adapter into the base model weights.export --model path --format fmt
Export for deployment (gguf, onnx, tensorrt, awq, gptq, and others).push --model path --repo user/name
Upload a model or adapter to the Hugging Face Hub.data subcommand ...
Dataset tools: inspect, validate, convert, dedup, split, generate, forge, and many quality / PII / contamination helpers.eval subcommand ...
Evaluation: benchmarks, custom JSONL tasks, LLM-as-judge, gates, and comparison.ship --base model --adapter path --task-eval file
Emit a SHIP / DON'T-SHIP gate (task win plus regression suite). Exit codes: 0 ship, 2 don't ship, 3 bad flags, 1 runtime error.doctor
Diagnose GPU, drivers, Python packages, and environment.recipes list|show|use|search
Browse and materialize ready-made training recipes.version [--full] [--json]
Print the installed Soup version.--log-level quiet|normal|verbose|debug
Global logging verbosity (Rich-formatted output).
CONFIGURATION
Primary file: soup.yaml (path passed to --config). Core fields include base (model id or path), task (for example sft), data.train / format / split, training (epochs, learning rate, LoRA, quantization, optional stream_layers), and output. Schema details live in the project docs under docs/ and config/schema.py.
CAVEATS
Fine-tuning requires substantial disk, RAM, and preferably a GPU; an 8B QLoRA run typically wants on the order of 8 GB+ VRAM without layer streaming. The bare soup-cli install cannot train until the [train] extra is installed. Layer streaming is still marked BETA. Prefer double quotes around extras in shells that treat [train] as a glob (pip install "soup-cli[train]"). Some advanced commands need optional extras ([serve], [ui], [mcp], and others).
HISTORY
Soup is an Apache-2.0 open-source project maintained as soup-cli on PyPI. Recent releases focus on low-VRAM training (layer streaming for 8B models on ~4 GB laptop GPUs), preference-training losses over that path, and shipping / eval gates for CI.
SEE ALSO
ollama(1), llama(1), huggingface-cli(1), pip(1)
