Soup v0.72.4：在4 GB显存笔记本GPU上微调8B模型

Soup

一条命令即可微调和后训练 LLM。无需 SSH，无需配置地狱。

网站 · 快速开始 · 配置 · 文档 · 命令 · 模型 · Discord

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

pip install "soup-cli[train]"   # add [train] to fine-tune; bare `soup-cli` is the light CLI
soup init --template chat
soup train

为什么选择 Soup？

训练 LLM 依然令人痛苦。即便是经验丰富的团队，也会把 30-50% 的时间花在与基础设施搏斗上，而不是改进模型。Soup 解决了这个问题。

• 零 SSH。再也不用 SSH 登录到一台坏掉的 GPU 机器了。
• 一份配置。一个简单的 YAML 文件就够了。
• 全自动。批大小、GPU 检测、量化——全部自动处理。
• 本地运行。用 QLoRA 在你自己的 GPU 上训练。无需云端。

新功能

v0.72.4 — 在笔记本上做对齐：基于层流式加载的 DPO、ORPO、SimPO 和 KTO。 层流式加载让冻结的基础模型不占用 VRAM，并一次一个解码器层地送入 GPU。它过去只支持监督微调；现在也能运行偏好损失了。

• DPO 的参考模型是免费的。 DPO 需要一个参考模型来对比，而模型的第二份副本会使内存翻倍，彻底违背初衷。Soup 使用同一个流式加载的基础模型，只是关闭其适配器——一套权重，一条流。在 RTX 3050 4 GB 上实测：流式 DPO 的峰值是0.914×监督微调的峰值。在同一测试中强行加入一个真正的第二模型，代价是+730 MB——恰好是一份权重副本。
• KTO 并非无参考模型，不管它通常是怎么被描述的：它选取参考模型的方式和 DPO 一样，所以它得到同样的处理。ORPO 和 SimPO 才是真正的无参考模型。
• 与同一损失函数的普通非流式运行相比逐位精确——0.0差异，这是本系列每次发布都必须跨过的门槛。
• VRAM 预检知道配对损失的行数是两倍，因为 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 reward synth（从你的数据中生成奖励验证器）

将 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

上一个版本——v0.71.39，针对权重而非提示词的 CI（发出并溯源绑定发布判定）

soup ship 的裁决变得可输出、可提交、可溯源绑定：--emit-evidence 让一次运行重放出完全相同的裁决，eval.ship 在 soup.yaml + --config 中让门禁策略可审查，而 --config 将证据绑定到产生它的确切配方（过期证据 → exit 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 草稿

（测量投机解码）

soup draft measure 报告草稿模型的 接受率 + 真实的普通解码对比辅助解码的 tok/s（exit 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 上会失败，因为 Windows 不支持单引号引用，会把引号直接传给 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 选项记录在 文档下。

文档

完整功能参考见 docs/。从这里开始：

数据格式

所有格式都会从 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（视觉）、audio、plaintext（预训练）、embedding、prm、pre_tokenized、video、multimodal

完整 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）。

完整模型 + 视觉表格以及可选扩展项矩阵见 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（实验性——非常慢）
• 使用 QLoRA 运行 7B 模型需 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: 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 安装；请使用 virtualenv。

开发

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 帮你省下了一次训练，给仓库点个 star帮助最大，而且不花一分钱。如果你想直接资助这项工作：

❤️ 捐赠——一次性，金额随意（在结账页面使用 Change amount）。付款由 Stripe 处理，收款方为维护者注册的企业 MePlay, Inc.——结账页面和你的信用卡账单上显示的是这个名字，而不是"Soup"。

捐款用于购买硬件门槛所限工作的 GPU 时间——多 GPU、8B+ 验证、Apple Silicon——这些是单台 4 GB 笔记本电脑无法企及的。

推动这些事项的另一种方式是硬件本身。它们以诚实的“需要 <硬件>”门槛发布，而非未经证实的声明，因此如果你能使用一台更大的机器——或者有闲置未用的 GPU 额度——运行其中一个help wanted issue 并公布数据，其帮助不亚于资助 GPU 时间。那些 issue 明确说明了当前受硬件阻塞的事项。

贡献者

由社区构建 ❤️——感谢每一位做出贡献的人。参见 CONTRIBUTORS.md。

联系方式

Bug 和功能请求请提交至issue tracker，问题请提交至Discussions——两者都能更快得到答复，并帮助下一个遇到同样问题的人。

如需实时聊天、设置帮助，以及一切更适合以对话形式呈现的内容，请加入Discord。任何六个月后仍应能被找到的内容都属于 Issues 或 Discussions——Discord 上的回答只帮到一个人，而 issue 能帮到所有遇到同样问题的人。Code of Conduct同样适用于那里。

对于任何不适合公开处理的事项——安全报告（见 SECURITY.md）、行为准则相关事宜或媒体咨询——请发送邮件至 team@trysoup.dev。这是该项目的邮箱地址，也是处理任何与 Soup 相关事宜的正确地址。makazanalpamys@gmail.com 是维护者的个人邮箱；它能联系到同一个人，是一个不错的备用选择。

引用 Soup

层流式加载——通过从主机内存中一次流式传输一个解码器层来加载冻结的基础模型，从而在 4 GB 的笔记本 GPU 上训练一个 8B 模型——在一篇预印本中进行了描述，同时还包括验证流式运行与常驻运行逐位一致的正确性协议：

Makazhan, A. (2026). 精确层流式加载：在 4 GB 笔记本 GPU 上对 8B 模型进行 LoRA 微调。 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 贡献者。