Soup
一条命令完成大语言模型的微调与后训练。无需 SSH，无需繁琐配置。
官网 · 快速上手 · 配置 · 文档 · 命令 · 模型 · Discord
Soup 将大语言模型微调的痛点转化为简单的工作流。一份配置，一条命令，搞定。
pip install "soup-cli[train]" # add [train] to fine-tune; bare `soup-cli` is the light CLI
soup init --template chat
soup train
为什么选择 Soup？
训练大语言模型仍然很痛苦。即便是经验丰富的团队，也要花 30-50% 的时间与基础设施搏斗，而不是改进模型。Soup 解决了这个问题。
- 零 SSH。再也不用 SSH 登录到出故障的 GPU 机器上。
- 一份配置。只需要一个简单的 YAML 文件。
- 全自动。批大小、GPU 检测、量化——统统自动处理。
- 本地运行。用 QLoRA 在自己的 GPU 上训练，无需云端。
最新动态
v0.72.4 —— 在笔记本上对齐：通过层流式传输（layer streaming）支持 DPO、ORPO、SimPO 和 KTO。层流式传输将冻结的基础模型排除在显存之外，一次只向 GPU 喂入一个解码器层。此前它只支持监督微调；现在也能运行这些偏好损失了。
- DPO 的参考模型是免费的。DPO 需要一个参考模型来对比，而模型的第二份副本会使显存翻倍，违背初衷。Soup 使用同一个流式传输的基础模型，并关闭其适配器——一组权重，一条流。在 RTX 3050 4 GB 上实测：流式 DPO 的峰值显存占用为监督微调峰值的 0.914 倍。在同一测试中强制加载真正的第二份模型要多占 +730 MB——恰好是一份权重的体积。
- KTO 并非无参考模型，尽管它通常被这样描述：它选取参考模型的方式与 DPO 相同，因此也采用同样的处理方式。ORPO 和 SimPO 才是真正无参考模型的。
- 与同一损失函数的普通非流式运行逐位一致——差异为 0.0，这是该系列每个版本都必须达到的标准。
- 显存预检知道配对损失的行数是两倍，因为 chosen 和 rejected 会作为一个张量一起通过模型。
- 诚实的成本：参考模型在显存上是免费的，但在时间上不是——DPO 每步读取层栈的频率是监督微调的 1.52 倍。
- grpo / ppo 有意保持不支持：生成过程每个 token 都要重新读取每一层，这正是流式传输无法摊薄的开销。
- 仍为 BETA 版。
# soup.yaml — then just `soup train --config soup.yaml`
training:
stream_layers: true # base streams out of VRAM; only the adapter trains
quantization: 4bit # NF4 — ~4x smaller store, so 8B fits a 4 GB card
batch_size: 4 # v0.72.3: bigger batches amortise the weight read
stream_source: auto # RAM when it fits, NVMe disk when it does not
在 v0.72.0 上以 stream_layers: true 训练？那个适配器是无效的——它的张量保存在带有额外 .inner. 段的键下，所以每个加载器都返回了未调优的基础模型。已在 v0.72.1 中修复；请重新运行或重新保存。用以下命令检查：python -c "from safetensors.torch import load_file; print([k for k in load_file('adapter_model.safetensors') if '.inner.' in k][:3])"
上一版本——v0.71.40，soup 奖励合成（从你的数据生成一个奖励验证器）
将 soup 奖励合成指向一个参考输出的 JSONL 文件，它会推断出一个确定性验证器，写出一个可读/可提交的 .py 奖励函数，并且——这是别人都做不到的部分——拒绝生成一个无法区分你的参考输出和错误答案的验证器（四个类别：numeric / json_schema / regex / tool_call；强制性的校准报告就是护城河）。奖励集成（reward_fn: "accuracy,format"）现在也可以训练了。（#311）
soup reward synth references.jsonl -o reward.py --output-report calib.json
上一版本——v0.71.39，针对权重而非提示词的 CI（生成并溯源绑定发布判定）
soup ship 的判定变得可生成、可提交、且可溯源绑定：--emit-evidence 让一次运行重放产生完全相同的判定，soup.yaml 中的 eval.ship 加上 --config 让门禁策略可审查，而 --config 将证据绑定到产生它的确切配方上（过期证据 → 退出码 3）。soup ship --push owner/repo#N 会在 PR 上发布 SHIP / DON'T-SHIP 卡片。
上一版本——v0.71.38，门禁长出牙齿（真正的第二阶段回归门禁）
soup ship 的回归阶段变成了真格的：一个固定的、基于提取的评分器，覆盖七个内置离线测试套件（MCQ · 算术 · 工具调用 · JSON 有效性 · 安全/拒答）。一个在你的任务上表现优异但悄悄破坏工具调用的调优现在会得到 DON'T SHIP。零新增依赖。
soup ship --base ./base --adapter ./my-lora --task-eval my_task.jsonl
# exit 0 = SHIP · 2 = DON'T SHIP · 3 = bad flags · 1 = runtime error
上一版本——v0.71.33，
soup draft
（测量投机解码）
soup draft measure 报告草稿模型的接受率以及真实的普通 vs 辅助 tok/s（退出码 0/2/1 用于 CI）；soup draft distill 将你的目标模型蒸馏成一个密集的小型草稿模型，自动接入 soup serve --auto-spec。在小型同族模型对上的诚实结果：蒸馏没有改变接受率（69.3% → 69.3%），辅助解码反而是净减速——而这正是你在部署投机解码之前想要的那个数字。
soup draft measure --target ./my-tuned-model --draft HuggingFaceTB/SmolLM2-135M-Instruct \
--prompts prod-prompts.jsonl # -> acceptance %, real tok/s, ship-or-not
完整历史记录：CHANGELOG.md · GitHub Releases。
快速上手
1. 安装
# Light core: CLI + config + data tools, no PyTorch
pip install soup-cli
# Add the training stack (torch, transformers, peft, trl, datasets, …)
pip install "soup-cli[train]"
# Everything (train + serve + ui + data) in one shot
pip install "soup-cli[all]"
# Or from GitHub (latest dev)
pip install git+https://github.com/MakazhanAlpamys/Soup.git
完整的 extras 列表（fast、mlx、serve、eval、ui、vision、audio 等）位于 docs/models.md。
请使用双引号包裹 extra。双引号是唯一在所有 shell（cmd.exe、PowerShell、bash 和 zsh）中都能正常工作的写法。
较旧的教程和视频（包括我们的一些内容）展示的是单引号写法 `pip install 'soup-cli[train]'`。那是 bash / zsh / PowerShell 的语法，在 Windows cmd.exe 上会失败，因为 cmd.exe 没有单引号引用机制，会把引号原样传给 pip：
ERROR: Invalid requirement: "'soup-cli[train]'": Expected package name at the start of dependency specifier如果遇到这种情况，把 `'` 换成 `"` 即可——是 pip 在拒绝字面引号字符，包本身没有问题。（在 Windows 上完全去掉引号也可以，但 zsh 会把 `[train]` 当作通配符解析而失败。）
`soup init`、`soup data …` 以及其他数据/检查命令在精简安装下即可运行。微调（`soup train`）需要 `[train]` extra。
2. 创建配置
soup init # interactive wizard
soup init --template chat # or start from a template
模板：chat、code、tool-calling、medical、reasoning、vision、kto、orpo、simpo、ipo、bco、rlhf、pretrain、moe、longcontext、embedding、audio。
3. 训练、测试、发布
soup train --config soup.yaml # LoRA, quantization, batching — all handled
soup chat --model ./output # talk to your model
soup push --model ./output --repo you/my-model
soup merge --adapter ./output # merge LoRA into the base
soup export --model ./output --format gguf --quant q4_k_m # GGUF for Ollama / llama.cpp
更多导出目标（ONNX、TensorRT、AWQ、GPTQ、BitNet）和部署选项位于 docs/serving-and-export.md。
配置
一份完整的 soup.yaml：
base: meta-llama/Llama-3.1-8B-Instruct
task: sft
# backend: unsloth # 2-5x faster, pip install "soup-cli[fast]"
data:
train: ./data/train.jsonl
format: alpaca
val_split: 0.1
training:
epochs: 3
lr: 2e-5
batch_size: auto
lora:
r: 64
alpha: 16
quantization: 4bit
output: ./output
config/schema.py 是每个字段的唯一权威来源。高级数据、训练和 PEFT 选项在 Documentation 下有文档说明。
文档
完整功能参考位于 docs/。从这里开始：
| 指南 | 涵盖内容 |
|---|---|
| 训练任务与方法 | SFT、DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO、工具调用、PRM、预训练、知识蒸馏、分类、视觉/音频/TTS、遗忘学习、RAFT/RA-DIT、循环加固检测器 |
| PEFT、长上下文与效率 | DoRA、LoRA+、rsLoRA、VeRA、OLoRA、NEFTune、PiSSA、ReLoRA、优化器与 PEFT 工具集、LLaMA Pro、GaLore、YaRN/LongLoRA、打包、课程学习、自动调优 |
| 性能与量化 | QAT、FP8、量化菜单（I 和 II）、KV 缓存、NVFP4、保存格式、Cut Cross-Entropy、梯度检查点、内核、激活卸载、层流式传输、多 GPU / DeepSpeed / FSDP |
| 数据工程 | 格式、Axolotl/LF 对齐流水线、数据工具、合成生成与锻造、质量评分卡、追踪工具、远程数据集、混合、配方 DAG |
| 评估与探针 | 评估设计与门禁、评估门控训练、基准测试、NLG 指标、校准、Elo 竞技场、诊断、训练后 X 射线探针、A/B 测试、漂移、可调性、模型融合建议 |
| 服务与导出 | OpenAI 兼容服务器、批量推理、基准测试、合并/导出、Anthropic Messages 端点、推测解码（训练并测量你自己的草稿模型）、自动部署、Web UI、Agent Forge |
| 适配器、注册表与治理 | 适配器生命周期/管理、模型注册表、Soup Cans、数据飞轮（模型融合循环）、知识编辑、引导控制、供应链管控（扫描/签名/BOM/证明/审计/物理隔离） |
| 合规与治理快速入门 | HIPAA/SOC2/EU-AI-Act/SR-11-7 初始化模板、溯源（BOM/证明/可复现凭证）、审计日志、物理隔离、模型卡自动生成（soup card）、CI 门禁（soup ci init） |
| 后端、平台与运维 | MLX/Unsloth 后端、替代模型中心、HF Hub 集成、自动部署、实验跟踪、计划/应用、环境锁文件、硬件适配、补全、插件、实用命令 |
| 命令参考 | 完整的 soup 命令列表 |
| 支持的模型与扩展 | 推荐模型系列、VRAM 容量指南、pip 扩展矩阵 |
数据格式
所有格式均可从 JSONL、JSON、CSV、Parquet 或 TXT 自动检测：
- alpaca — {"instruction": ..., "input": ..., "output": ...}
- sharegpt — {"conversations": [{"from": "human", "value": ...}, ...]}
- chatml — {"messages": [{"role": "user", "content": ...}, ...]}
- dpo / orpo / simpo / ipo — {"prompt": ..., "chosen": ..., "rejected": ...}
- kto — {"prompt": ..., "completion": ..., "label": true}
- llava / sharegpt4v（视觉）、音频、纯文本（预训练）、嵌入向量、prm、预分词、视频、多模态
完整 schema 以及与 Axolotl/LlamaFactory 对齐的数据管道（远程 URI、流式处理、分片、交错、词表扩展、文档摄取）详见 docs/data.md。
常用命令
soup train --config soup.yaml # train (SFT/DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/...)
soup infer --model ./output --input prompts.jsonl # batch inference
soup chat --model ./output # interactive chat
soup serve --model ./output # OpenAI-compatible API server
soup merge --adapter ./output # merge LoRA into the base model
soup export --model ./output --format gguf # export for deployment
soup eval benchmark --model ./output # evaluate
soup data inspect ./data/train.jsonl # dataset stats
soup recipes list # 100+ ready-made model recipes
soup autopilot --model <id> --data d.jsonl --goal chat # zero-config
soup doctor # check GPU / deps / environment
完整命令列表见 docs/commands.md。
支持的模型
Soup 可与 HuggingFace Hub 上的任何文本生成模型配合使用——只要它能通过 AutoModelForCausalLM 加载，就能直接运行，零配置改动。Llama 3.x/4、Qwen 2.5/3、Gemma 3、Mistral、Mixtral、DeepSeek R1/V3、Phi-4 以及 100 多个其他模型均自带现成配方（soup recipes list）。
| VRAM | 最大模型（QLoRA 4-bit） | 示例 |
|---|---|---|
| 8 GB | 约 7B | Llama-3.1-8B、Mistral-7B |
| 16 GB | 约 14B | Phi-4-14B、Qwen2.5-14B |
| 24 GB | 约 34B | CodeLlama-34B、Yi-1.5-34B |
| 48 GB | 约 70B | Llama-3.3-70B |
| 80 GB 以上 | 70B 以上（完整版）或 MoE | Mixtral-8x22B、DeepSeek-V3 |
完整模型 + 视觉表格以及可选扩展矩阵见 docs/models.md。
Docker
无需在本地安装 CUDA 或 PyTorch 即可运行 Soup（镜像在每次发布时发布到 GHCR）：
docker pull ghcr.io/makazhanalpamys/soup:latest
docker run --gpus all -v $(pwd):/workspace ghcr.io/makazhanalpamys/soup train --config soup.yaml
docker compose up # or build locally
环境要求
- Python 3.10 及以上
- 支持 CUDA 的 GPU（推荐）、Apple Silicon（MPS）或 CPU（实验性——速度非常慢）
- 7B 模型使用 QLoRA 需要 8 GB 以上显存
所有训练任务均可在 CPU 上运行以进行测试（量化自动禁用）。可选扩展（train、all、fast、vision、qat、serve、serve-fast、ui、eval、deepspeed、liger、mlx、onnx、tensorrt 等）列于 docs/models.md。
故障排查
soup doctor # GPU, system resources, dependencies, and version in one place
- ImportError：导入 _C 时 DLL 加载失败（Windows）——请为你的 CUDA 版本重新安装 PyTorch：pip install torch --index-url https://download.pytorch.org/whl/cu121。
- soup 版本 ≠ pip show soup-cli——存在多个 Python 安装；请使用虚拟环境。
开发
git clone https://github.com/MakazhanAlpamys/Soup.git
cd Soup
pip install -e ".[dev]"
ruff check src/soup_cli/ tests/ # lint
pytest tests/ -v # unit tests (fast, no GPU)
pytest tests/ -m smoke -v # smoke tests (downloads a tiny model, trains)
pre-commit install # optional: ruff lint+format on commit
完整工作流程请参阅 CONTRIBUTING.md，报告漏洞请参阅 SECURITY.md。
支持 Soup
Soup 采用 Apache-2.0 许可且完全免费——并将一直如此。它是在一台 4 GB 笔记本电脑上公开构建和维护的，因此本文档中的每一个性能数字都是实测得出的，而非凭空声称。
如果 Soup 帮你省下了一次训练任务，给仓库点个星标就是最大的帮助，而且完全免费。如果你想直接资助这项工作：
❤️ 捐赠——一次性，金额不限（在结账页面使用“更改金额”选项）。支付由 Stripe 在维护者注册的企业 MePlay, Inc. 名下处理——结账页面和你的银行卡账单上显示的是这个名字，而不是“Soup”。
捐赠将用于购买 GPU 算力，以推进受硬件限制的工作——多 GPU、8B 以上模型验证、Apple Silicon——这些是单台 4 GB 笔记本电脑无法完成的任务。
推进这些项目的另一种方式就是硬件本身。这些项目都诚实地标注了“需要 <硬件>”的门槛，而非未经证实的承诺，所以如果你能接触到更大的机器——或者有闲置的 GPU 额度——运行一个“待认领”问题并发布数据，其帮助不亚于资助 GPU 算力。这些问题明确列出了当前被硬件阻塞的具体事项。
贡献者
由社区共同构建 ❤️ —— 感谢每一位贡献者。详见 CONTRIBUTORS.md。
联系方式
Bug 和功能请求请提交到 issue 跟踪器，问题请发布在 Discussions 中——这两种方式都能得到更快的回复，也能帮助遇到同样问题的下一个人。
如需实时聊天、搭建帮助，以及任何更适合以对话形式交流的内容，欢迎加入 Discord。任何在六个月后仍应可查的内容，请发布在 Issues 或 Discussions 中——Discord 上的回答只能帮到一个人，而一个 issue 能帮到所有遇到同样问题的人。行为准则同样适用于那里。
任何不适合公开的内容——安全报告（见 SECURITY.md）、行为准则相关事宜，或媒体联系——请发送邮件至 team@trysoup.dev。这是项目官方地址，也是所有与 Soup 相关事宜的正确联系渠道。makazanalpamys@gmail.com 是维护者的个人邮箱；同样可以联系到同一个人，也是一个不错的备用选择。
引用 Soup
分层流式训练——通过在 4 GB 显存的笔记本电脑 GPU 上，从主机内存逐层流式加载冻结的基座模型，训练一个 8B 模型——在一篇预印本论文中有所描述，同时还包括正确性验证协议，该协议可验证流式运行与常驻运行的结果逐位完全一致：
Makazhan, A. (2026). Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop GPU. Zenodo. https://doi.org/10.5281/zenodo.21771064
其中每个数字背后的测量记录都存放在 benchmarks/ 中，按原始记录发布——包括失败案例、被证明是错误的假设，以及那些被测量后又被舍弃的数据。
@misc{makazhan2026exact,
title = {Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop GPU},
author = {Makazhan, Alpamys},
year = {2026},
publisher = {Zenodo},
doi = {10.5281/zenodo.21771064},
url = {https://doi.org/10.5281/zenodo.21771064}
}
许可证
Apache-2.0。版权所有 © Soup 贡献者。