核心问题: 这条「4 GB 内完成 8B 训练且逐位一致」的路径，在你的硬件与模型规模上是否成立？
RepoDaily 采用评分
RepoDaily 将该项目的采用分评为 89/100（强）：分数来自文章来源、安装路径、生产风险、差异化、许可证清晰度以及 AI/Agent 适配度。
包含 8 个来源、覆盖 4 类来源；如有 RepoDaily 独有模块，会进一步提高证据分。
检测到 6 个工作流步骤、4 个下一步动作，以及 2 个命令/安装信号。
趋势热度为 +456 stars；如内容中有 release、issue 或维护信号，会提高维护可信度。
采纳风险标记为 medium，并包含 5 条安全说明与 5 条跳过条件。
3 个机会视角、4 个替代方案，以及 4 个类型化模块支撑差异化判断。
文章中包含许可证来源或许可证表述。
文章正文和元数据中检测到 5 个 AI/Agent 相关信号。
项目概览
Soup 是一个本地优先的 Python CLI，把 LLM 后训练压缩为一个配置文件加一条命令：`pip install 'soup-cli[train]'`、`soup init --template chat`、`soup train`。README 徽章区写明关键信息：Apache-2.0 许可、Python 3.10–3.12、PyPI 包名 `soup-cli`、CI 徽章，以及 layer-streaming 论文的 DOI（10.5281/zenodo.21771064）。口号很直接：No SSH, no config hell。
头条主张异常具体：layer streaming 让冻结的基座模型不进显存，按解码器层逐层喂给 GPU；在 RTX 3050 Laptop 4 GB 上实测 Llama-3.1-8B-Instruct + NF4 达到 119.6 tok/s、峰值 3.32 GB，并断言与常驻式运行逐位一致，另在 H100 上以同样的 3.32 GB 复现为 113.00 tok/s。该功能需显式开启（`stream_layers: true`），仍是 BETA；tok/s 数据测于 v0.72.2——早于付出 −4.8%（32B 档）代价的 v0.73.0 正确性修复——此后未在 4 GB 卡上重测。
除 4 GB 技巧外，文档索引铺开了很宽的面：从 SFT 到 GRPO/PPO/KTO/ORPO 与遗忘训练，从 DoRA 到 VeRA 的 PEFT 家族，QAT/FP8/NVFP4 量化，OpenAI 兼容推理服务，模型注册表与 `.can` 工件，HIPAA/SOC2/EU-AI-Act/SR-11-7 合规模板，MLX 与 Unsloth 后端，以及 144 份现成配方。本文依据 README、文档索引、变更日志、安全策略与贡献指南，把「文档写明的行为」和「宣传话术」区分开。
为什么现在变热
- 本期收获 456 星，位列 2026-08-17 趋势榜第 6 名。
- 一个可证伪的具体主张：RTX 3050 Laptop 4 GB 上 Llama-3.1-8B-Instruct + NF4 达 119.6 tok/s、峰值 3.32 GB，与常驻运行逐位一致，并在 H100 上复现为 113.00 tok/s。
- 主张附带 `notebooks/proof-4gb.ipynb`：在免费 Colab T4 上把进程限制在 4 GB，并断言流式模型与常规模型逐位一致。
- 单一 CLI 覆盖面广：`src/soup_cli/trainer/` 下 18 个训练封装、144 份配方、从 DoRA/LoRA+ 到 VeRA/PiSSA 的 PEFT 变体，以及合规 init 模板。
- 坦诚是差异点：有 DOI 论文、`benchmarks/` 目录，变更日志还点名自己未解决的 bug（#394）和正确性修复的 −4.8% 代价。
解决什么问题
- 微调配置散落在多份文件和多台远程机器上；Soup 的答案是一份 `soup.yaml` 加一条命令，口号是 No SSH, no config hell。
- 显存墙：常驻的 8B NF4 基座加优化器状态会超过 4 GB，把笔记本用户推向他们未必想要的云租赁。
- 上线决策通常靠手工；Soup 把 `soup ship` 判定、eval 门控训练和 `soup advise` 步骤接进同一份配置。
- 受监管场景的溯源（BOM、签名证明、复现回执）通常要手工拼装；Soup 提供 `soup attest`、`soup card` 和带 HIPAA/SOC2/EU-AI-Act/SR-11-7 模板的 `soup ci init`。
- 换训练器就要重写配置；`src/soup_cli/migrate/` 支持导入 LLaMA-Factory、Axolotl、Unsloth 的现有配置。
工作原理
- `pip install 'soup-cli[train]'`——`[train]` extra 会拉入 torch、transformers、peft、trl、datasets、bitsandbytes、accelerate；裸 `soup-cli` 保持轻量（自 v0.71.0 起 extra 为可选项，不属于核心依赖）。
- `soup init --template chat` 生成 `soup.yaml`；也可从 144 份配方起步，例如 `qwen3.5-4b-pretrain`（#278）或 `deepseek-v4-flash-grpo`（#279）。
- 在 YAML 中选择方法：SFT、DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO，另有预训练、蒸馏、分类、PRM、遗忘等，各自是 `src/soup_cli/trainer/` 下的封装。
- 执行 `soup train`。开启 `stream_layers: true` 后，冻结基座被固定在内存（跨 32 层的 3.60 GB 存储），经两个 113 MB 显存缓冲逐层送入 GPU。
- 门控结果：`soup ship` 依据门禁策略给出判定；`eval.ship.noise_floor` 现可写入 `soup.yaml`（#406）——取值限制在 [2, 10]，拒绝 bool 冒充 int，优先级为 CLI > config > 默认值。
- 导出或部署：merge/export、OpenAI 兼容服务、Anthropic Messages 端点、可分享的 `.can` 工件，以及生成模型卡的 `soup card`。
产品演示与界面预览
架构解读：layer streaming 如何塞进 4 GB
layer streaming 颠倒了常驻模式：冻结基座从不进显存，而是把 3.60 GB 存储固定在内存、按 32 个解码器层切片，由两个 113 MB 显存缓冲每次搬运一层；可训练的适配器和优化器状态保持常驻。在 RTX 3050 Laptop 4 GB 上，Llama-3.1-8B-Instruct NF4 实测峰值 3.32 GB、119.6 tok/s，低于 4 GB 红线，且断言与常驻运行逐位一致，另在 H100 上以同样 3.32 GB 复现为 113.00 tok/s。
该功能按磁盘分档，档位判断正是工程细节所在。`detect_disk_kind` 原本信任 `/sys/block/<dev>/queue/rotational`，会把默认值为 `1` 的半虚拟化 virtio 盘误判为 HDD——使实测 1.5 GB/s 读取的 NVMe 云盘拿不到 disk-overflow 档。修复 #365 改为在 `rotational=1` 时用有界的 O_DIRECT 顺序读测量来判定：吞吐 ≥ 1 GB/s 才给档位，真正慢的盘仍被拒绝（160 seeks/step，plan P11），并新增 `training.stream_disk_kind` 配置暴露判定结果。
两个诚实标记值得注意。其一，功能需 `stream_layers: true` 显式开启且标注 BETA，按文档锚点：v0.72.2 引入 NF4，v0.72.3 加入磁盘与更广架构，v0.72.4 支持偏好类损失。其二，119.6 tok/s 测于 v0.72.2——早于在 32B 档付出 −4.8% 代价的 v0.73.0 正确性修复——此后未在 4 GB 卡重测。数字是真的，但落后了一个正确性版本。
命令面：`soup` 暴露了什么
- `soup init --template chat` 与 `soup train`——README 快速开始的两条命令路径。
- `soup ship`——按门禁策略出判定；#406 之后 `eval.ship.noise_floor`（限制 [2, 10]）加入其余五个可提交的门禁旗标，且不计入配方 `config_sha`，设置噪声下限不会使证据失效。
- `soup runs`——基于 SQLite 的实验跟踪；#401 修复后，watcher 挂掉的运行会在读取时改判为 `terminated` 且退出码未知，不再永远显示 `running`。
- `soup card`、`soup ci init`、`soup attest`、`soup adapters sign`——模型卡自动生成、CI 门禁与 ed25519 溯源；`[sign]` extra 拉入 `cryptography` 让相关测试进入 CI。
- `soup shrink`——深度剪枝加 distill-heal，列于 PEFT 与效率指南。
- `soup loop` 与 `soup advise`——文档索引中点名的数据飞轮与训后建议步骤。
- `soup train --annex-xi *.pdf`——Annex XI/XII 报告输出，由 `[pdf]` extra（`reportlab`）支撑。
- 完整命令表在 `docs/commands.md`；`docs/models.md` 收录推荐模型家族、显存尺寸指南与 pip extras 矩阵。
维护风险：变更日志自己承认了什么
- #401（已修复）：`ExecutionManager._watch` 是 `daemon=True` 线程，MCP 服务进程退出时会不经清理地被杀，导致运行状态永远停在 `running`；现在跟踪器读取时对账，绝不把未知结果记为成功。
- #431（已合入，作者 @Shutaru）：MLX SFT 分发不再导入 Transformers 封装；新增的 Apple Silicon CI 任务验证 `mlx`/`mlx-lm` 可导入、PyTorch/TRL 栈不存在、一步真实 CLI SFT 可完成。
- #394（未解决）：变更日志直言 #431「不声称解决仍未定位的 torch 存在时挂起问题」——已知的 Apple Silicon 暗坑。
- 版本策略：SECURITY.md 仅支持 0.73.x；变更日志提到 70+ 个已发布版本，旧部署很快会失去修复。
- 发布节奏快——v0.72.0 到 v0.73.2 之间密集交付了 layer streaming、正确性修复和新门禁旗标——建议在 CI 中锁定版本并在升级后复测。
集成面：后端、Hub 与迁移
- 后端：MLX 与 Unsloth 为一等公民（#431 加固了独立的 `soup-cli[mlx]` 运行时），`[train]` 则对应 PyTorch/TRL 栈。
- 云端：backends-and-ops.md 列出 Modal 云 GPU 训练、备用 Hub 与 HF Hub 集成。
- 服务：OpenAI 兼容服务、Anthropic Messages 端点、批量推理与投机解码（含训练自己的 draft 模型）。
- 迁移：`src/soup_cli/migrate/` 可转换 LLaMA-Factory、Axolotl、Unsloth 的配置。
- 跟踪与运维：`src/soup_cli/experiment/` 使用 SQLite；环境锁文件与硬件适配检查补齐了 backends-and-ops 指南。
- 横向扩展：multi-GPU、DeepSpeed、FSDP 见 performance-and-quantization.md，用于 4 GB 技巧不够用的场景。
谁适合关注
适合关注
- 你只有 4–8 GB 笔记本 GPU，想在本地微调 7–8B 模型而不是租云卡。
- 你希望一份 `soup.yaml` 把项目从 SFT 一路带到 DPO/GRPO 和带门禁的 `soup ship` 决策。
- 你受 HIPAA/SOC2/EU-AI-Act/SR-11-7 约束，想要内置的 init 模板、BOM、签名证明和 `soup ci init`。
- 你在 Apple Silicon 上，想用 CI 已验证不含 PyTorch/TRL 栈的 `[mlx]` 路径。
- 你有现成的 LLaMA-Factory、Axolotl 或 Unsloth 配置，可经 `src/soup_cli/migrate/` 迁移。
可以先跳过
- 你现在就需要非 BETA 的吞吐保证——头条 tok/s 早于 v0.73.0 正确性修复，且未在 4 GB 卡上重测。
- 你必须用 Python 3.13 及以上——`requires-python` 为 >=3.10,<3.13，CI 只跑 3.10、3.11、3.12。
- 你需要对锁定的旧版本长期支持——SECURITY.md 仅支持 0.73.x，更低的版本一律不支持。
- 你需要 SLA 保障的厂商支持——报告渠道是 GitHub 安全公告加两个邮箱，且明确没有赏金。
- 你的任务是在别处编排的大型多节点训练；4 GB 常驻技巧不是你的瓶颈。
风险与注意事项
核心主张可证伪、文档坦诚，但 layer streaming 明确标注 BETA，头条 tok/s 早于 v0.73.0 正确性修复，且仅 0.73.x 线获得安全修复。
- `stream_layers: true` 为可选且标注 BETA；119.6 tok/s 测于 v0.72.2，早于在 32B 档付出 −4.8% 代价的 v0.73.0 正确性修复，此后未在 4 GB 卡重测。
- SECURITY.md 仅支持 0.73.x；更低版本不在安全支持范围内，升级实际上是强制的。
- 变更日志自己标注了未解决的 Apple Silicon 挂起（#394），且 #431 的 MLX 分发修复明确不声称解决它。
- 70+ 个已发布版本加上 #406 等未发布条目说明迭代很快；配置与门禁行为可能在次版本间变动。
- 支持渠道是 GitHub 安全公告加两个邮箱（[email protected]、[email protected]）——偏单人维护者形态的薄弱报告路径。
- 许可证为 Apache-2.0，见 README 徽章。
- 支持版本：仅 0.73.x；策略表格将 0.73 以下全部标记为不支持。
- 范围内威胁类别：来自配置/数据集/工件路径的路径穿越或任意文件读写；合成数据提供方、推理服务、Hub/端点校验器中的 SSRF；命令、Modelfile、Jinja 聊天模板与 systemd/launchd 注入；日志、崩溃包或生成工件中的秘密泄漏；RLVR 代码执行奖励路径的沙箱逃逸。
- 只接受私密报告：优先 GitHub 安全公告，否则发 [email protected] 或维护者个人邮箱；明确不接受 Discord 报告。确认受理目标为 5 个工作日；没有赏金——发布说明中的署名即是全部回报。
- 明确不在范围：你选择加载的第三方模型权重或数据集的漏洞、已被入侵的主机，以及 trysoup.dev 的 DNS/邮件配置（如 DMARC/SPF/DKIM）。
替代方案比较
| 方案 | 适用场景 | 代价 |
|---|---|---|
Axolotl | 想要成熟的 YAML 驱动多卡训练器、方法覆盖广，且不需要 4 GB 流式常驻技巧；Soup 的 migrate/ 将其视为一等导入源。 | 开源（Apache-2.0） |
LLaMA-Factory | 偏好 YAML 之上再加 Web UI 与广泛的模型覆盖；同样是 Soup 支持的迁移来源。 | 开源 |
| 更看重 NVIDIA/AMD 单卡吞吐而非单配置可移植性；在 Soup 内可作为后端和迁移来源使用。 | 开源（Apache-2.0） | |
Hugging Face TRL | 想要 Soup 自己也依赖的库（[train] extra 会拉入 trl），并直接用 Python 控制而非走 CLI。 | 开源（Apache-2.0） |
这个趋势说明了什么
小显存微调作为切入口
3.32 GB / 119.6 tok/s 的实测加一份自我验证的 notebook，瞄准的是大量只有 4 GB 笔记本显卡的学生、顾问和爱好者——多数训练器忽略的群体。
在免费 Colab T4 上打开 notebooks/proof-4gb.ipynb；确认逐位一致断言通过，并记录自己显卡上的峰值显存与 tok/s。
合规级后训练
compliance.md 提供 HIPAA、SOC2、EU-AI-Act、SR-11-7 的 init 模板，以及 BOM/attest/repro-receipt 溯源、气隙说明、`soup card` 与 `soup ci init`——受监管团队本要手工拼装的部件。
把 `soup ci init` 接入一个 CI 任务，确认门禁能拦下 eval 退化超过 `eval.ship.noise_floor` 的配方。
配置迁移作为上手通道
`src/soup_cli/migrate/` 可转换 LLaMA-Factory、Axolotl、Unsloth 配置，降低已投入这些工具的人的切换成本。
转换一份现有 YAML，分别在 Soup 与原训练器上跑 200 步，对比损失曲线后再决定。
RepoDaily 判断
Soup 靠一个可证伪的主张赢得趋势席位——8B 模型在 3.32 GB 内训练、逐位一致、可在免费 Colab T4 上复现——并有坦诚的文档和敢于点名自身 bug 的变更日志背书。把 layer streaming 当作 BETA 使用，锁定 0.73.x，并在标准化之前用自己的硬件重测。