soup

Soup — 一条命令微调大模型

Soup 将微调流程简化为 soup init → soup train，只需一个 YAML 配置：任务选择、量化、批次大小以及 GPU/后端检测都会由它为你处理。它的核心功能是层流式处理 （stream_layers: true），让冻结的基础模型无需常驻 VRAM，而是每次流式加载一个解码器层，因此 8B 模型可在 4 GB 笔记本 GPU 上进行微调——经测量，结果与模型常驻运行完全一致。

何时使用此技能

• 启动新的微调任务（soup init、soup train），而不是手动编写 Transformers/PEFT/TRL 训练脚本
• 为受限 GPU 选择训练方法（SFT、DPO/GRPO/ORPO/SimPO/KTO/IPO/BCO）或 节省内存的方案（QLoRA、DoRA、LoRA+、rsLoRA、层流式处理）
• 在花费 GPU 时长之前估算训练成本/内存（soup cost、soup profile），或获取训练前的方法建议 （soup advise）
• 将现有 Axolotl / LLaMA-Factory / Unsloth 配置迁移到 Soup
• 部署、合并或推送训练好的适配器（soup serve、soup merge、 soup push），或运行数据质量/评估工具（soup data ...、 soup ship）

何时不使用此技能

• 主要关注 Ray/DeepSpeed 集群/多节点规模的训练基础设施 → 直接使用 deepspeed 或 openrlhf-training；Soup 将 DeepSpeed/FSDP 封装为启动参数，而不是替代它们
• 仅部署已合并模型进行推理，不涉及训练 → 使用纯推理运行时技能更合适
• 用户完全不使用 Soup/PEFT/TRL（例如，仅进行提示词工程）→ 按照 soup advise 自身的判断处理（它可能会建议 PROMPT_ENG，而不是 训练），不要直接跳到 soup train

说明

第 1 步：安装合适的配置

bash pip install soup-cli # 仅安装轻量 CLI：init/advise/data/profile/cost pip install "soup-cli[train]" # 另加用于实际训练的 torch/transformers/peft/trl

第 2 步：花费 GPU 时长之前先决定方法

bash soup advise <data.jsonl> --goal "..." # 给出 PROMPT_ENG / RAG / SFT / DPO / GRPO 建议 soup autopilot --model --data d.jsonl --goal "" # 零配置：自动选择任务/量化/LR/轮数

不要一上来就默认使用 soup train；提供 advise/autopilot 是因为方法选错了（例如，数据是偏好对却使用 SFT）会浪费一整次训练。

第 3 步：创建配置框架并编辑配置

bash soup init --template chat # 或 code/audio/... — 参见 docs/models.md soup fetch # 获取现成的示例配置

对于内存受限的硬件，需明确启用层流式处理：

yaml training: stream_layers: true # 基础模型流出 VRAM；只有适配器参与训练 quantization: 4bit # NF4 batch_size: 4 stream_source: auto # 适合时使用 RAM，否则使用 NVMe 磁盘

层流式处理目前处于 BETA 阶段，支持 SFT 以及 DPO/ORPO/SimPO/KTO——不支持 GRPO/PPO（这些方法会针对每个生成的 token 重新读取每一层，从而抵消流式处理的摊销收益）。

第 4 步：使用 GPU 前先估算

bash soup profile --config soup.yaml --gpu a100 soup cost --config soup.yaml --gpu H100

第 5 步：训练，然后在发布前验证

bash soup train --config soup.yaml soup train --config soup.yaml --gate evals/gate.yaml # 通过评估门控 soup ship --config soup.yaml # 给出是否发布的判断

第 6 步：部署、合并或推送结果

bash soup infer --model ./output --input p.jsonl soup chat --model ./output soup merge --adapter ./output soup push --model ./output --repo user/name soup serve --model ./output

步骤 7：使用封装脚本检查只读环境

bash bash .agent-skills/soup/scripts/soup.sh doctor bash .agent-skills/soup/scripts/soup.sh advise <data.jsonl> --goal "..." bash .agent-skills/soup/scripts/soup.sh profile <config.yaml>

doctor 只检查环境（Python 版本、soup 安装情况、[train] 扩展、CUDA/MPS 可用性）——不会安装软件包，也不会启动训练任务。

最佳实践

1. 在运行 soup train 前先运行 soup advise/soup autopilot——否则，只有在完整训练运行结束后，才能发现选错了任务类型（SFT 还是偏好损失）。
2. 租用 GPU 前先运行 soup cost/soup profile——这样比事后才发现内存溢出或意外多花了 $40 更省钱。
3. 分层流式处理是可选的权衡，并非默认设置——它以额外的层堆栈读取换取更低的内存占用（DPO 的读取频率约为 SFT 的 1.52 倍）；启用前请确认所用方法在支持列表中（SFT/DPO/ORPO/SimPO/KTO）。
4. 发布前先通过门禁检查——建议使用 --gate evals/gate.yaml 和 soup ship，而不是凭目测判断损失曲线。
5. 重型依赖保持延迟加载——不要建议在驱动 Soup 的脚本模块顶层导入 torch/transformers/peft/trl；项目本身会延迟导入它们，以保持轻量级 CLI 的运行速度。
6. 迁移配置，不要手动移植——soup migrate --from axolotl|llamafactory|unsloth 的存在正是为了避免手动翻译配置时出错。

参考资料

• references/commands.md — 按工作流阶段整理的精选命令参考
• scripts/soup.sh — 只读的 doctor 检查，以及精简的 advise/profile/cost 封装脚本
• Soup GitHub Repository
• Soup 文档索引
• 项目规范：.agent-skills/skill-standardization/SKILL.md

示例

示例 1：选择方法，然后在 4 GB 笔记本电脑 GPU 上微调

bash soup advise data.jsonl --goal "make the model follow a strict output schema" soup init --template chat

soup.yaml: set stream_layers: true, quantization: 4bit

soup profile --config soup.yaml soup train --config soup.yaml

示例 2：推荐训练方案前检查环境

bash bash .agent-skills/soup/scripts/soup.sh doctor