MakazhanAlpamys/Soup

项目介绍

Soup 是一个用于大模型微调和后训练的命令行工具，覆盖 SFT、DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO 等偏好优化、tool-calling、预训练、蒸馏等任务。用户只需写一份 soup.yaml 描述基座模型、数据集、训练参数和输出目录，GPU 检测、量化、batch size、LoRA 配置由工具处理。它支持本地 QLoRA 训练，并提供 OpenAI 兼容服务、评测、LoRA 合并与导出，以及本地 Web UI。

核心卖点是层流式训练（通过 stream_layers: true 开启，仍为 BETA）：冻结的基座模型留在主机内存里，逐层送入 GPU。项目报告在 4 GB 显存的 RTX 3050 Laptop 上用 NF4 训练 Llama-3.1-8B-Instruct，v0.72.2 上达到 119.6 tok/s、峰值 3.32 GB，并用一套正确性协议验证流式运行与常驻运行逐位一致。另一位贡献者在更高频率下的新测量为 208.6 tok/s、峰值 2.40 GB，但项目自己说明这部分原始提速来自频率而非算法本身。

它面向有 GPU、有数据集，但不想手工拼装训练栈或折腾远程机器的人。

快速使用

先在隔离环境里从 PyPI 安装。轻量安装只有命令行和数据工具，soup train 需要 [train] extra。

pipx install "soup-cli[train]"
# 或：uv tool install "soup-cli[train]"
# 或在 venv/Colab/Docker 中：pip install "soup-cli[train]"

extra 必须用双引号，这样在 cmd.exe、PowerShell、bash 和 zsh 中都能用。接着生成配置并训练：

soup init --template chat        # 交互式向导，或从模板开始
soup train --config soup.yaml    # LoRA、量化、batch 由工具处理

训练完成后可直接对话或导出：

soup chat  --model ./output
soup export --model ./output --format gguf --quant q4_k_m

一份最小配置如下（完整字段以 config/schema.py 为准）：

base: meta-llama/Llama-3.1-8B-Instruct
task: sft
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

出错时先跑 soup doctor，它会汇总 GPU、依赖和版本信息。想在浏览器里操作，可执行 pip install "soup-cli[ui]" 后运行 soup ui，本地面板地址为 127.0.0.1:7860。

使用约束

• Python 3.11–3.13 是 CI 测试过的版本；3.14+ 暂不支持，因为 PyTorch 栈尚未验证。
• 推荐 CUDA GPU；Apple Silicon（MPS）和 CPU 也可运行，但 CPU 仅属实验性质且非常慢。README 的显存表给出 8 GB 可跑约 7B 的 QLoRA、24 GB 约 34B、48 GB 约 70B。
• 微调需要 [train] extra，服务、UI 等能力是各自独立的 extra。
• 从 v0.75 起未知配置键会被拒绝，不再静默忽略；v0.77.0 又收紧了校验，之前在 v0.76 能加载的配置可能无法通过。升级前先运行 soup doctor --config soup.yaml。另外 soup data 系列命令会拒绝把 --output 指向输入文件本身。
• 遥测默认关闭，只有设置 SOUP_TELEMETRY=1 才开启。许可证为 Apache-2.0，分发时需保留 LICENSE 与 NOTICE 并遵守名称使用条款。
• 层流式仍为 BETA 且需手动开启；README 中的性能数字来自特定硬件和版本，项目把修复前、修复后的数据分开列出，没有合并成一个提速倍数。

HotRepo 点评

Soup 在 2026-08-15 的全语言日榜上单日新增 303 Star，次日再增 297；到 2026-11-03 的 Python 语言日榜记录时累计 10,061 Star，当日新增 135，在该榜单的最好名次为第 11。2026-08-04 的 Show HN 帖也围绕「在 4 GB 笔记本 GPU 上微调 8B 模型」展开，获得 139 分、28 条评论。

这个项目最鲜明的特点是测量上的克制：它公开原始基准记录，说明一个曾被撤回的解释和一次错误梯度缺陷的修复，并主动指出某次新测量中的原始提速来自频率而非方法。HN 讨论里也有不太好看的一面——维护者承认用 LLM 代写回复，有评论者指出这导致大量评论被折叠。这属于讨论行为，不涉及代码或训练结论。