Soup：一条命令在4GB笔记本GPU上微调8B大模型

从一个 YAML 微调大型语言模型。分层流式训练一个 8B 模型，配备 4 GB 笔记本 GPU。

汤

一个命令就能微调和列车后置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

在4GB笔记本GPU上微调8B型号。分层流式将冻结的基座排除在显存之外，并一层一层地将它送给 GPU。在 RTX 3050 笔记本上测量 4 GB：Llama-3.1-8B-Instruct + NF4119.6 tok/s，峰值3.32 GB—— 对正常驻留运行进行位精确匹配，并且在同一 3.32 GB 内存中，以 113.00 tok/s 的 H100 独立重现。

（tok/s 数值是在 v0.72.2 上测量的，在 v0.73.0 正确性修复之前，修复成本为 32B，损失 −4.8%;此后未在 4 GB 卡上重新运行。）选择加入（stream_layers: true）而且依然是BETA——工作原理·所有测量数据·纸张·你可以自己在免费的Colab T4上看看（将进程限制为4 GB，然后断言流式模型与普通模型位完全相同）

Llama-3.1-8B-Ininstruction + NF4，LoRA，批次1，序列512，运行于RTX 3050笔记本4GB — 峰值3.32 GB，119.6 tok/s。完整视频（90年代）

为什么是汤？

训练大型语言模型依然很痛苦。即使是有经验的团队，也花了30-50%的时间与基础设施斗争，而不是改进模型。Soup解决了这个问题。

• 完全没有SSH。以后绝不要再用SSH登录坏掉的GPU盒子。
• 一个配置。一个简单的 YAML 文件就足够了。
• 全部自动。批次大小、GPU检测、量化——已处理。
• 本地有效。用自己的GPU和QLoRA训练。不需要云端。

最新动态

v0.73.2 — 释放门不再双向放置。 soup ship回答了一个问题：这个模型是变好了，还是我把它弄坏了？它的两个套件排名错误，还有一个故障方向根本没有检测器。

• 一套模型答对了40/40，得了0.225分。 mini_tool_call排名护具卫生：模型发射了一个闭合括号，因此解析法退回内对象，评分者因缺少外键而拒绝。且mini_mmlu在Llama得分3.1-8B。0.423 — 低于0.5B指数——因为提取者并不知道\boxed{C}提示从未要求字母。两者均固定;0.423→0.731。
• 新：良性提示轴。第二段赛程显示掉落拒绝率且没有反向，因此一首拒绝一切的曲调听起来像是单调的安全改进。两款型号在七套发货套间中评分字节相同，其中一台拒绝所有无害请求，在门口时无法区分。mini_over_refusal是它的镜像;与安全套装配合使用，单独操作时都无法控。
• 新内容：soup ship --noise-floor N重复运行基础模型N次，且拒绝将任何小于测量扩散的差异称为显著。贪婪解码在GPU上并非确定性——同一型号，无适配器，五次运行间距0.015–0.020在0.05的阈值下，那次会议中六对delta中有四个坐在地板内。它尺寸效果;它不会校准阈值，而发布文件中也说明了这一点。
• 来电者错误与回归无法区分。不可叫的生成器得分0.0在三个组曲上，在其他组曲上提高——在第二段中，0.0的表现为“所有项目都失败”，也就是说，它朝着看起来像是发现的方向失败。
• 另外：soup data split --stratify-semantic（#388） 和soup mcp serve --allow-execute（#391），两者均来自外部贡献者。

上一版本的显存测量记录，按原文发布——包括期间撤回了三次阅读— 是benchmarks/gate-v0.73.1-measured-vram-fit.md.

# 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            # bigger batches amortise the weight read
  stream_source: auto      # RAM when it fits, NVMe disk when it does not
  seed: 1234               # new in v0.73.0

蟒蛇3.10–3.12仅。v0.73.0 增加了缺失的上限：在 3.13+ 版本中，Pip 用于解决在原生扩展中崩溃的未测试 PyTorch 轮子，而 Soup 根本无法运行。

之前版本 — v0.72.4，笔记本对齐（DPO / ORPO / SimPO / KTO 通过图层流式传输）

层流以前只支持监督微调;v0.72.4 则开放了偏好丢失。风险只有一个：DPO 需要一个参考模型，第二个副本会加倍内存，破坏目的。Soup 使用同一个流式基地，但适配器关闭了—— 测量值0.914×SFT峰值，强制进行真正的第二次审判成本+730 MB，权重的正好一份副本.四人都比普通非直播运行比特精确。

诚实费用：免费记忆，不是在时间— DPO 读取层栈1.52×每步的频率。grpo/ppo故意被排除在外。

训练对象stream_layers: true在 v0.72.0 上？那个适配器是惰性的——它的张量被保存在有额外钥匙的键下.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在引用输出的 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，权重非提示的置信区间（emit + provenance-bind the ship verdict）

soup ship的判决变得可发布、可提交且受来源约束：--emit-evidence使得分重播成相同的判决，eval.ship在soup.yaml+--config使登机口政策可审查，且--config将证据绑定于制作该配方的确切配方（陈旧证据→出口3）。

soup ship --push owner/repo#N在PR上发布了“SHIP/don't-ship”卡。

之前版本 — v0.71.38，门长牙（真正的第二腿回归门）

soup ship的回归环节成为现实：一个固定的、基于提取的评分器，覆盖七个捆绑的离线套件（多选题·算术·工具调用·JSON有效性·安全/拒绝）。

一个能赢得任务但悄悄破坏工具调用的调校现在会得到不要寄出.零新的 DEPS。

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 发布.

快速入门

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

完整花絮表（fast,mlx,serve,eval,ui,vision,audio, …)居住于以下docs/models.md.

双引号，不是单引号。 "soup-cli[train]"是唯一能在每个壳体中都成立的拼写——cmd.exePowerShell、bash 和 zsh。如果你复制了'soup-cli[train]'这是之前一个教程，PIP拒绝了，这就是原因：为什么，以及具体错误.

soup init,soup data …，其他数据/检查命令则用于灯光安装。微调（soup train）需要[train]快讯。

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/.从这里开始：

数据格式

Alpaca、ShareGPT、ChatML、偏好对（DPO / ORPO / SimPO / IPO / KTO）、视觉、音频、ASR、明文、嵌入、RAFT 等——这些都会自动检测到 JSONL、JSON、CSV、Parquet 或 TXT，所以大多数情况下你只能指向data.train在文件中，其他都不变。

包含每个格式可行示例的模式，以及数据管道（远程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  --data d.jsonl --goal chat  # zero-config
soup doctor                           # check GPU / deps / environment

完整的命令列表已在docs/commands.md.

支持的型号

汤的作用任何文本生成模型拥抱面孔中心——如果加载为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

在本地运行 Soup 而不安装 CUDA 或 PyTorch（每次发布时发布给 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、3.11 或 3.12（这些版本是 CI 测试的版本;3.13+ 尚未支持，因为 PyTorch 堆栈尚未在该版本获得验证）
• 配备CUDA（推荐）、苹果硅片（MPS）或CPU（实验性——非常慢）
• 7B型号配备8GB+显存，支持QLoRA

所有训练任务均在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（窗户）——为您的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是Apache-2.0且免费的——并且一直保持如此。它是在一台4GB笔记本电脑上公开构建和维护的，这也是为什么这些文档中的每一个性能数据都是测量的，而不是宣称。

如果Soup帮你省了一次训练跑，最有帮助，而且完全免费。如果你想直接资助这项工作：

❤️ 捐赠— 一次性，任意数量（使用变更金额在结账页面）。付款由Stripe以维护者注册的企业名义处理，MePlay公司——结账页面和信用卡账单上显示的名称，而不是“Soup”。

捐款为硬件门控工作——多GPU、8B+验证、苹果硅芯片——购买了GPU时间，而单个4GB笔记本无法满足。

另一种正好移动这些物品的方式是硬件本身.他们以诚实的“需求”门槛发货，而不是未经验证的声明，所以如果你能使用更大的盒子——或者GPU积分闲置——运行其中一个help wanted问题和公布数据的帮助，就像为GPU时间提供资金一样。

这些问题正好说明了目前硬件上被阻挡的因素。

撰稿人

由社区❤️建设——感谢所有贡献者。参见CONTRIBUTORS.md.

联系方式

错误和功能请求应当在问题追踪器，问题讨论——两者都能更快得到回答，并帮助下一个遇到同样问题的人。

如需在线聊天、设置帮助以及所有更适合对话的内容，请加入Discord.任何六个月后还能找到的内容都应该放在问题或讨论区——Discord的答案帮助一个人，问题帮助所有遇到同样问题的人。

这个行为准则那里也适用。

对于任何不适合公开的内容——安全报告（参见SECURITY.md行为准则事务，或新闻 — 电子邮件team@trysoup.dev.那是项目地址，也是所有与Soup相关内容的正确地址。makazanalpamys@gmail.com是维护者的个人地址;它能到达同一个人，是很好的后备。

引用汤

层流——通过从主机内存中逐层流式流式解析，在4GB笔记本GPU上训练8B模型——在预印本中描述了，以及验证流运行与常驻运行的正确性协议（正向和反向分别说明，因为它们是两个主张而非一个）。

马卡赞，A.（2026）。精确层流：在4GB笔记本GPU上对8B型号进行LoRA微调（v3）。泽诺多。https://doi.org/10.5281/zenodo.21918325

版本3（2026年8月13日）是当前版本。标题和声明保持不变——8B，4 GB内存——自v1以来测量的数字未变。v3的作用是撤回我们发布的解释这也是描述论文用途的最简方式：

• v3中撤回：“层流是通过主机到设备传输绑定的，而不是GPU。”那是推理来自下面的H100复制，且从未被测量过。我们在8月11日测量，发现在发布的配置下是错误的：删除所有主机到设备购买的字节1.4%，计算流等待 的副本0.20%阶梯的，阶梯在71.3%该卡的同会话GEMM上限。流媒体专属的最大成本是每层NF4的去量化，高达9.8%（纪录).每一项测量都成立;复制以较弱的形式存活——该约束是两台机器共有的，而非GPU的计算。
• 硬件上的复制完全不同于原版（v2 新增）：RTX 3050 的 119.6 tok/s，而 H100 的中位数 113.00，峰值同样为 3.32 GB。
• 一个无声的错误梯度缺陷，被发现并修复。在每层超过 165 MiB 的 NF4 上，前向保持位精确，丢失曲线看起来健康，而梯度则错误。原因在上游库中被命名并报告;修复通过实际 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}
}

许可

阿帕奇2.0.版权归© Soup贡献者所有。