一条YAML微调8B模型：4GB显存本地即可

一行命令完成 LLM 的微调与后训练。无需 SSH，无需配置地狱。

Website · Quick Start · Config · Docs · Commands · Models · Discord · Product Hunt

Soup 将 LLM 微调的痛苦转化为简单的工作流。一套配置，一条命令，搞定。

pip install "soup-cli[train]"   # 添加 [train] 以进行微调；裸 `soup-cli` 是轻量 CLI
soup init --template chat
soup train

在 4 GB 显存的笔记本 GPU 上微调 8B 模型。Layer streaming 将冻结的基础模型移出 VRAM，每次只向 GPU 推送一个解码器层。在 RTX 3050 Laptop 4 GB 上实测：Llama-3.1-8B-Instruct + NF4 达到 119.6 tok/s，峰值显存 3.32 GB——与常规常驻运行完全位相等，并在 H100 上独立复现了 113.00 tok/s、同样 3.32 GB 的结果。（tok/s 数据是在 v0.72.2 上测量的，早于 v0.73.0 的正确性修复——该修复损失了 −4.8% 的性能；自此未在 4 GB 卡上重新测试。）可选开启（stream_layers: true），仍为 BETA——工作原理 · 全部测量数据 · 论文 · 在免费 Colab T4 上自行验证（将进程上限设为 4 GB，然后断言流式模型与常规模型位相等）

Llama-3.1-8B-Instruct + NF4、LoRA、batch 1、seq 512，在 RTX 3050 Laptop 4 GB 上——峰值 3.32 GB，119.6 tok/s。完整视频（90 秒）

训练 LLM 仍然是痛苦的。即使是经验丰富的团队，也要把 30-50% 的时间花在对抗基础设施上，而不是改进模型。Soup 解决了这个问题。

零 SSH。再也不用 SSH 进一台坏掉的 GPU 机器了。

一套配置。一个简单的 YAML 文件就是你所需的全部。

自动化一切。batch size、GPU 检测、量化——全部自动处理。

本地运行。使用 QLoRA 在你自己的 GPU 上训练。无需云端。

v0.73.2——发布门槛不再双向撒谎。soup ship 回答一个问题：这个模型变好了，还是被我搞坏了？其中两个 suite 排名时用了错误的标准，而一个完整的失败方向根本没有检测器。

某个 suite 对一个 40/40 全对的模型给出了 0.225 分。mini_tool_call 排名依据的是大括号卫生度：模型少输出一个右大括号，导致解析回退到内层对象，评分器因缺少外层键而拒绝它。mini_mmlu 对 Llama-3.1-8B 评分 0.423——低于 0.5B 模型——因为提取器不认识 \boxed{C}，而 prompt 从未要求输出字母。两个均已修复；0.423 → 0.731。

新增：良性 prompt 轴。Leg 2 标记了拒绝率下降且没有反向指标，因此一个拒绝所有请求的调优看起来像单调的安全改进。两模型在全部七个已发布 suite 上字节级得分相同，其中一个拒绝所有良性请求，对发布门槛而言两者无法区分。mini_over_refusal 是其镜像；配合安全 suite，单独一个无法被操纵。

新增：soup ship --noise-floor N 多次（ N 次）重新运行基础模型，拒绝将任何小于测量波动的 delta 视为显著。贪心解码在 GPU 上并非确定性——相同模型、无 adapter、五次运行在 0.05 阈值内散布 0.015–0.020，该 session 中六对 delta 有四对落在地板内。它衡量效应大小；不校准阈值，发布说明如实告知。

调用方错误曾与回归无法区分。不可调用的生成器在三个 suite 上得分 0.0，其余则抛出异常——在 leg 2 中 0.0 意味着"每个条目都失败"，即它失败的方向看起来像一个发现。

此外：soup data split --stratify-semantic（#388）和 soup mcp serve --allow-execute（#391），均来自外部贡献者。

上一版本 VRAM 工作的测量记录，原样发布——包括其中撤销的三次读数——见 benchmarks/gate-v0.73.1-measured-vram-fit.md。

# soup.yaml — 然后只需 `soup train --config soup.yaml`
training:
  stream_layers: true      # 基础模型流出 VRAM；只有 adapter 在训练
  quantization: 4bit       # NF4 — ~4x 更小的存储，使 8B 能在 4 GB 卡上运行
  batch_size: 4            # 更大的 batch 分摊权重读取开销
  stream_source: auto      # 能放 RAM 就放 RAM，放不下就放 NVMe 磁盘
  seed: 1234               # v0.73.0 新增

仅支持 Python 3.10–3.12。v0.73.0 新增了之前缺失的上限：在 3.13+ 上，pip 过去会解析未经测试的 PyTorch wheel，在 Soup 运行之前就在原生扩展中崩溃。

Layer streaming 过去只支持监督微调；v0.72.4 将其扩展到偏好损失。风险只有一点：DPO 需要一个参考模型，第二份拷贝会使内存翻倍，从而失去流式的意义。Soup 使用同一个流式基础模型并关闭其 adapter——经测量为 SFT 峰值的 0.914×，而强制使用真实第二实例需要 +730 MB，正好是一份权重的拷贝。四种情况与常规非流式运行完全位相等。诚实的代价：内存免费，时间不免费——DPO 每步多读取层堆栈 1.52×。grpo/ppo 故意保持排除状态。

使用 stream_layers: true 在 v0.72.0 上训练的？那个 adapter 是惰性的——其张量保存在带额外 .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])"

将 soup reward synth 指向一个参考输出的 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

soup ship 的评判结果变得可发出、可提交并绑定溯源：--emit-evidence 使运行回放为完全相同的评判结果，eval.ship in soup.yaml + --config 使门槛策略可审查，--config 将证据绑定到产生它的确切配方（陈旧证据 → 退出码 3）。soup ship --push owner/repo#N 在 PR 上发布 SHIP / DON'T-SHIP 卡片。

soup ship 的回归 leg 变为真实：基于提取的固定评分器，覆盖七个捆绑的离线 suite（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

完整历史：CHANGELOG.md · GitHub Releases。

# 轻量核心：CLI + 配置 + 数据工具，无 PyTorch
pip install soup-cli

# 添加训练栈（torch、transformers、peft、trl、datasets 等）
pip install "soup-cli[train]"

# 一步到位（train + serve + ui + data）
pip install "soup-cli[all]"

# 或从 GitHub 安装（最新开发版）
pip install git+https://github.com/MakazhanAlpamys/Soup.git

完整的 extras 表格（fast、mlx、serve、eval、ui、vision、audio 等）位于 docs/models.md。

用双引号，不用单引号。"soup-cli[train]" 是唯一在所有 shell 中都能正常工作的写法——cmd.exe、PowerShell、bash 和 zsh 皆是如此。如果你从旧教程中复制了 'soup-cli[train]' 并被 pip 拒绝，原因就在这里：这是写法问题，也是具体的报错信息。

soup init、soup data … 及其他数据/检查命令可以在轻量安装下运行。微调（soup train）需要 [train] extra。

soup init                       # 交互式向导
soup init --template chat       # 或从模板开始

模板列表：chat、code、tool-calling、medical、reasoning、vision、kto、orpo、simpo、ipo、bco、rlhf、pretrain、moe、longcontext、embedding、audio。

soup train --config soup.yaml                 # LoRA、量化、批处理——全部自动处理
soup chat  --model ./output                    # 与模型对话
soup push  --model ./output --repo you/my-model

soup merge  --adapter ./output                              # 将 LoRA 合并到基座
soup export --model ./output --format gguf --quant q4_k_m   # 导出为 GGUF 格式（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 更快，需 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/。从这里开始：

Alpaca、ShareGPT、ChatML、偏好对（DPO / ORPO / SimPO / IPO / KTO）、vision、audio、ASR、纯文本、embedding、RAFT 等——全部从 JSONL、JSON、CSV、Parquet 或 TXT 自动检测，因此大多数情况下只需将 data.train 指向一个文件，其他无需改动。每种格式的 schema 及示例见 docs/data.md，以及数据流水线（远程 URI、流式处理、分片、交错、词表扩展、文档摄入）。

soup train  --config soup.yaml        # 训练（SFT/DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/...）
soup infer  --model ./output --input prompts.jsonl   # 批量推理
soup chat   --model ./output          # 交互式对话
soup serve  --model ./output          # OpenAI 兼容 API 服务器
soup merge  --adapter ./output        # 将 LoRA 合并到基座模型
soup export --model ./output --format gguf           # 导出用于部署
soup eval   benchmark --model ./output               # 评估
soup data   inspect ./data/train.jsonl               # 数据集统计
soup recipes list                     # 100+ 开箱即用的模型配方
soup autopilot --model <id> --data d.jsonl --goal chat  # 零配置
soup doctor                           # 检查 GPU / 依赖 / 环境

完整命令列表见 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）。

完整模型 + vision 表格及可选 extras 矩阵见 docs/models.md。

无需本地安装 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   # 或在本地构建

Python 3.10、3.11 或 3.12（CI 测试的版本；3.13+ 暂不支持，因为 PyTorch 栈尚未在该版本通过验证）

GPU（CUDA，推荐）、Apple Silicon（MPS）或 CPU（实验性——非常慢）

7B 模型 QLoRA 需要 8 GB+ VRAM

所有训练任务均可运行在 CPU 上进行测试（量化自动禁用）。可选 extras（train、all、fast、vision、qat、serve、serve-fast、ui、eval、deepspeed、liger、mlx、onnx、tensorrt 等）列于 docs/models.md。

soup doctor    # GPU、系统资源、依赖和版本一目了然

ImportError: DLL load failed while importing _C（Windows）—— 重新安装与你的 CUDA 版本对应的 PyTorch：pip install torch --index-url https://download.pytorch.org/whl/cu121。

soup version 不等于 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                   # 单元测试（快速，无需 GPU）
pytest tests/ -m smoke -v          # 冒烟测试（下载小型模型，训练）

pre-commit install                 # 可选：commit 时自动 ruff lint + format

完整工作流程见 CONTRIBUTING.md，漏洞报告见 SECURITY.md。

Soup 采用 Apache-2.0 许可证且免费——并将继续保持下去。项目在一台 4 GB 的笔记本电脑上公开构建和维护，这就是为什么这些文档中的每一个性能数字都是测量得出的，而非宣称出来的。

如果 Soup 帮你完成了一次训练，给仓库点个 star 是最大的支持，而且无需任何成本。如果你愿意直接资助这项工作：

❤️ 捐赠——一次性，任意金额（使用结算页的 Change amount 按钮）。付款由 Stripe 处理，收款方为维护者注册的营业主体 MePlay, Inc.——结算页和银行卡账单上显示的名称是 "MePlay" 而非 "Soup"。

捐赠用于购买硬件受限工作所需的 GPU 时间——多 GPU、8B+ 验证、Apple Silicon——这些是一台 4 GB 笔记本电脑无法完成的。

另一种推动这些工作的方式是直接提供硬件。这些工作背后有诚实的 "requires <hardware>" 门槛，而不是未经证实的宣称。因此如果你有一台更大的机器——或者有未使用的 GPU 额度——认领一个 help wanted issue 并公布运行结果，其帮助不亚于资助 GPU 时间。那些 issue 清楚说明了目前哪些工作因硬件限制而受阻。

由社区共同构建 ❤️——感谢每一位贡献者。见 CONTRIBUTORS.md。

Bug 和功能请求请提交至 issue 追踪器，问题请发在 Discussions——两者响应更快，也能帮助后续遇到相同问题的人。

实时聊天、配置帮助和一切更适合对话形式的内容，请加入 Discord。任何应该在六个月后仍可搜索的内容请放在 Issues 或 Discussions——Discord 的回答只帮助一个人，而 issue 帮助所有遇到同样问题的人。行为准则同样适用。

不适合公开的内容——安全报告（见 SECURITY.md）、行为准则相关事宜或媒体——请发送至 team@trysoup.dev。这是项目的官方地址，任何 Soup 相关事务的正确联系方式。makazanalpamys@gmail.com 是维护者的个人地址，能联系到同一人，可作为备选。

层级流式处理——通过逐个将冻结基座的解码器层从主机内存流式传输，在 4 GB 笔记本电脑 GPU 上训练 8B 模型——在一份预印本中有详细描述，同时还包括验证流式运行与驻留运行一致性的正确性协议（前向和后向分别验证，因为这是两个独立的声明而非一个）。

Makazhan, A. (2026). Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop GPU (v3). Zenodo. https://doi.org/10.5281/zenodo.21918325

2026 年 8 月 13 日的第三版为当前版本。标题和核心声明未变——8B 模型在 4 GB 上运行——自第一版以来所有测量数字均未改变。第三版所做的是撤回我们曾发表的一个解释，这也是描述这篇论文用途的最简短方式：

Retracted in v3: "layer streaming is bound by host-to-device transfer, not by the GPU." 这是从下面的 H100 复现实验中得出的推断，但从未经过实际测量。我们于 8 月 11 日对其进行了测量，在发布的配置下该结论是错误的：删除每一个 host-to-device 字节仅获得 1.4% 的提升，计算流在 0.20% 的 step 时间内等待数据拷贝，而整个 step 运行在该卡同会话 GEMM 峰值的 71.3% 速率上。流式处理最大的特定开销是每层的 NF4 反量化，达到 9.8%（这也是一项记录）。每项测量结果均成立；复现在更弱的形式下得以保留——这一限制是两台机器共有的，并非 GPU 计算所致。

在完全不同的硬件上复现（v2 新增）：在 RTX 3050 上达到 119.6 tok/s，与 H100 上的中位数 113.00 tok/s 相近，且峰值显存均为 3.32 GB。

一个静默的梯度错误缺陷，已被发现并修复。在 NF4 模式下，当每层约 ~165 MiB 以上时，前向传播保持位精确且损失曲线看起来正常，但梯度实际上是错误的。成因在上游库中有命名并已在该库中报告；修复已针对真实 32B 和 72B 模型上的控件做了门控。

在真实模型规模下验证位精确性，而非三层玩具模型：前向传播从 0.5B 到 72B，反向传播在 8B 和 14B 上测试。

首次对训练模型质量进行测量，结果与常驻运行无法区分。

与 DeepSpeed 的对比——包括那个对我们不利的结论：八卡 ZeRO-3 比单卡训练常驻模型更慢。

限制条款已重写：v1 的十项中，一项已关闭，四项收窄，并新增七项。

请引用你使用的版本。10.5281/zenodo.21771064 是概念 DOI，始终解析到最新版本（今天是 v3）；v1 和 v2 保留各自的版本 DOI 供引用，且未被编辑——上面的撤回说明是新版本，正是为了保持我们所声称的内容及其时间的记录完整。

其中每个数字的测量记录均位于 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},
  version      = {v3},
  doi          = {10.5281/zenodo.21918325},
  url          = {https://doi.org/10.5281/zenodo.21918325}
}

Apache-2.0。Copyright © the Soup contributors。