Soup适配器Git化管理教程diff、merge、bisect与任务向量算术全解【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/SoupSoupsoup-cli是一个「一条命令 一个 YAML 就能微调大模型」的开源自工具Layer streaming 甚至能在 4 GB 显存的笔记本显卡上训练 8B 模型。而它对 LoRA 适配器的Git 化管理能力是新手最容易忽视、却最实用的部分——soup adapters子命令把 diff差异对比、merge权重合并、bisect二分定位回归和任务向量算术加减、缩放、抵消行为做成了开箱即用的 CLI就像给模型适配器装上了一套 git。本文将带你完整走完这条「适配器的版本控制」链路全部基于官方文档 docs/adapters-and-governance.md 的「Adapter Management (git for LoRA)」章节。为什么需要给 LoRA 适配器做版本管理微调一次得到一个 LoRA 适配器一个只有几十 MB 的小目录。当你训出 v17、v18、v19 好几版或者为不同领域金融、医疗、法务各训一版时很快会遇到这些问题v18 比 v17 改了哪些权重—— 需要 diff能不能把 v17 和 v18 的优点合在一起—— 需要 merge某个 step 之后评测突然变差是哪里引入的—— 需要 bisect能减去一个坏行为吗—— 需要任务向量算术Soup 的答案是把 git 的核心概念原样搬过来branch快照分支、diff权重级差异、merge多策略合并、bisect二分查找回归点、pr生成 PR 文档供评审。所有命令都作用于 peft 兼容的adapter_model.safetensors目录。下图是 Soup 的 Web UI 新建训练界面可以看到 LoRA 参数r、alpha直接写在同一份 YAML 配置里训练产物就是上述命令操作的对象第一步diff——像 git diff 一样对比两个适配器Soup 提供两种 diff分别回答权重层面和输出层面的问题。1. 权重级 diffsoup adapters diff# 逐层 ΔW Frobenius 范数差异 有效秩漂移 Top-K 变化最大的投影 soup adapters diff ./run-v17 ./run-v18 # 输出机器可读 JSON方便接入 CI soup adapters diff ./run-v17 ./run-v18 --format json --output diff.json它会告诉你两层适配器在每一层的权重增量差异有多大、有效秩是否漂移以及变化最剧烈的 Top-K 投影--top-k可调 1~200。实现代码位于 src/soup_cli/commands/adapters.py核心数学在soup_cli.utils.adapter_diff。2. 输出级 diffsoup diff权重变了 ≠ 知道效果变了。soup diff直接对同一组提示词让两个模型并排生成逐条对比输出soup diff -a ./adapter-a -b ./adapter-b --prompts prompts.jsonlLoRA 适配器会自动从adapter_config.json检测基座模型无需手动指定。实现见 src/soup_cli/commands/diff.py。第二步merge——五种合并策略把多个适配器融为一体当多个任务各自训练了一个适配器soup adapters merge可以把它们融合成一个。内置五种策略纯 numpy 实现无需额外依赖策略原理适用场景linear逐层加权平均默认基线任务间共享基底ties按密度修剪 → 多数符号投票 → 不相交平均任务间存在冲突TIES 论文方法dare按density随机丢弃 1/density重缩放后平均降低参数互相干扰可用--seed保证可复现svd线性合并后经 SVD 低秩重构约束合并结果的秩cmaes进化算法搜索权重单纯形以你的评测集为适应度自动找最优配比# 加权线性合并 soup adapters merge ./run-v17 ./run-v18 ./run-v19 -o ./merged \ --strategy linear --weights 0.5,0.3,0.2 # 评测驱动进化合并每个候选都会被打分最优配比写入 --output soup adapters merge adapter-finance/ adapter-medical/ adapter-legal/ \ --strategy cmaes --eval evals/domain_mix.yaml --budget 1h \ --population 8 --max-generations 20 -o merged/ # 合并后一键跑 canary 回归判定OK / MINOR / MAJOR soup adapters merge a/ b/ -o merged/ --canary evals/canary.json --strict-verdict安全细节值得新手了解每次合并前会自动跑后门扫描和许可证冲突检查--allow-unscanned可跳过扫描输出路径做了目录包含性检查并拒绝预置符号链接safetensors 写入是原子的——中途崩溃不会留下半个适配器。如果你只是想验证合并没把模型搞坏--canary会用评测套件给合并结果打 OK / MINOR / MAJOR 三档判定--strict-verdict在 MAJOR 时以退出码 2 结束非常适合接 CI。第三步bisect——二分查找哪一步把模型训坏了这是 git bisect 思路在训练历史中的翻版内核在 src/soup_cli/utils/adapter_bisect.py。给定一条按时间排序的检查点历史和一条评测通过的判定命令Soup 用二分搜索找到第一个开始失败的检查点——也就是回归边界soup adapters bisect \ ckpt-step-100 ckpt-step-200 ckpt-step-400 ckpt-step-800 \ --eval-command soup eval custom --model {ckpt} --tasks eval.jsonl \ -o bisect.json几个关键行为判定命令通过{ckpt}占位符注入检查点路径内部使用参数列表模式非 shell 字符串拼接检查点名里带特殊字符也不会注入。找到回归点时退出码为 3结果可直接交给下一条命令。最终结论只有两种ALL_OK全部通过没找到回归或BROKEN_AT定位到首个失败点。找到边界后可衔接soup adapters blame做数据集归因——用 leave-one-out 影响函数近似把回归归因到具体的训练样本行soup adapters blame ./run-v18 --dataset train.jsonl --layer q_proj.7 \ --budget 4h --shards 10 --plan-onlydiff看差异、merge做融合、bisect定回归、blame追源头四步构成完整的适配器调试闭环。第四步任务向量算术——加上数学能力减去毒性soup adapters arithmeticv0.71.34 引入是整套能力里最有想象力的部分把适配器看作任务向量像 git 里合并分支一样做加减法理论基础是 Task ArithmeticarXiv:2212.04089soup adapters arithmetic coder 0.5*math - toxic \ --adapter coder./coder-lora \ --adapter math./math-lora \ --adapter toxic./toxic-lora \ -o ./blended加法融合两种技能缩放2*coder让编码能力更强减法- toxic抵消掉毒性行为——这正是它区别于普通权重平均的关键。实现上有个新手容易踩的数学细节LoRA 的贡献是ΔW B·ASoup 在有效增量层面做算术保证系数严格线性缩放。如果只是朴素的逐元素相加减去一个适配器会因c²效应变成几乎无效操作——Soup 已经替你修正了这一点。使用约束都是保护性的所有输入必须共享同一基座模型--allow-cross-base可覆盖但不同基座的向量本不可比支持混合 rank 输入可选--rank N用截断 SVD 限制输出秩每个输入先过后门扫描门禁。训练阶段配合 Layer streaming即使显卡只有 225 MB 显存占用上限8B 模型也能稳定训练出这些可算术组合的适配器团队协作branch、PR 与 lock 保证可复现单人闭环之外Soup 还给团队配齐了协作面branch / checkout / branches把某次训练的「配置 基座 数据集」做 SHA-256 快照checkout恢复配置时若源已漂移会直接拒绝——可复现性不会悄悄说谎soup adapters pr把一次合并渲染成 PR 文档评测增量 样例 diff供评审soup lock write / check生成soup.lock把「基座 数据 环境」的闭包锁进一个文件队友check时任何漂移都以退出码 3 报警。总结一张表记住 Soup 适配器的 Git 工作流需求命令类比 git列出所有适配器soup adapters listgit log --oneline对比两个适配器soup adapters diff/soup diffgit diff融合多个适配器soup adapters merge/arithmeticgit merge定位回归点soup adapters bisectgit bisect快照与恢复soup adapters branch / checkoutgit branch / checkout提交评审soup adapters prgit pr从 diff 到 merge、从 bisect 到任务向量算术Soup 让 LoRA 适配器第一次拥有了完整的版本控制体验。更多细节可查阅 docs/commands.md 与 docs/adapters-and-governance.md示例配置在 examples/configs/ 中直接可用。【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Soup适配器Git化管理教程diff、merge、bisect与任务向量算术全解【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/SoupSoupsoup-cli是一个「一条命令 一个 YAML 就能微调大模型」的开源自工具Layer streaming 甚至能在 4 GB 显存的笔记本显卡上训练 8B 模型。而它对 LoRA 适配器的Git 化管理能力是新手最容易忽视、却最实用的部分——soup adapters子命令把 diff差异对比、merge权重合并、bisect二分定位回归和任务向量算术加减、缩放、抵消行为做成了开箱即用的 CLI就像给模型适配器装上了一套 git。本文将带你完整走完这条「适配器的版本控制」链路全部基于官方文档 docs/adapters-and-governance.md 的「Adapter Management (git for LoRA)」章节。为什么需要给 LoRA 适配器做版本管理微调一次得到一个 LoRA 适配器一个只有几十 MB 的小目录。当你训出 v17、v18、v19 好几版或者为不同领域金融、医疗、法务各训一版时很快会遇到这些问题v18 比 v17 改了哪些权重—— 需要 diff能不能把 v17 和 v18 的优点合在一起—— 需要 merge某个 step 之后评测突然变差是哪里引入的—— 需要 bisect能减去一个坏行为吗—— 需要任务向量算术Soup 的答案是把 git 的核心概念原样搬过来branch快照分支、diff权重级差异、merge多策略合并、bisect二分查找回归点、pr生成 PR 文档供评审。所有命令都作用于 peft 兼容的adapter_model.safetensors目录。下图是 Soup 的 Web UI 新建训练界面可以看到 LoRA 参数r、alpha直接写在同一份 YAML 配置里训练产物就是上述命令操作的对象第一步diff——像 git diff 一样对比两个适配器Soup 提供两种 diff分别回答权重层面和输出层面的问题。1. 权重级 diffsoup adapters diff# 逐层 ΔW Frobenius 范数差异 有效秩漂移 Top-K 变化最大的投影 soup adapters diff ./run-v17 ./run-v18 # 输出机器可读 JSON方便接入 CI soup adapters diff ./run-v17 ./run-v18 --format json --output diff.json它会告诉你两层适配器在每一层的权重增量差异有多大、有效秩是否漂移以及变化最剧烈的 Top-K 投影--top-k可调 1~200。实现代码位于 src/soup_cli/commands/adapters.py核心数学在soup_cli.utils.adapter_diff。2. 输出级 diffsoup diff权重变了 ≠ 知道效果变了。soup diff直接对同一组提示词让两个模型并排生成逐条对比输出soup diff -a ./adapter-a -b ./adapter-b --prompts prompts.jsonlLoRA 适配器会自动从adapter_config.json检测基座模型无需手动指定。实现见 src/soup_cli/commands/diff.py。第二步merge——五种合并策略把多个适配器融为一体当多个任务各自训练了一个适配器soup adapters merge可以把它们融合成一个。内置五种策略纯 numpy 实现无需额外依赖策略原理适用场景linear逐层加权平均默认基线任务间共享基底ties按密度修剪 → 多数符号投票 → 不相交平均任务间存在冲突TIES 论文方法dare按density随机丢弃 1/density重缩放后平均降低参数互相干扰可用--seed保证可复现svd线性合并后经 SVD 低秩重构约束合并结果的秩cmaes进化算法搜索权重单纯形以你的评测集为适应度自动找最优配比# 加权线性合并 soup adapters merge ./run-v17 ./run-v18 ./run-v19 -o ./merged \ --strategy linear --weights 0.5,0.3,0.2 # 评测驱动进化合并每个候选都会被打分最优配比写入 --output soup adapters merge adapter-finance/ adapter-medical/ adapter-legal/ \ --strategy cmaes --eval evals/domain_mix.yaml --budget 1h \ --population 8 --max-generations 20 -o merged/ # 合并后一键跑 canary 回归判定OK / MINOR / MAJOR soup adapters merge a/ b/ -o merged/ --canary evals/canary.json --strict-verdict安全细节值得新手了解每次合并前会自动跑后门扫描和许可证冲突检查--allow-unscanned可跳过扫描输出路径做了目录包含性检查并拒绝预置符号链接safetensors 写入是原子的——中途崩溃不会留下半个适配器。如果你只是想验证合并没把模型搞坏--canary会用评测套件给合并结果打 OK / MINOR / MAJOR 三档判定--strict-verdict在 MAJOR 时以退出码 2 结束非常适合接 CI。第三步bisect——二分查找哪一步把模型训坏了这是 git bisect 思路在训练历史中的翻版内核在 src/soup_cli/utils/adapter_bisect.py。给定一条按时间排序的检查点历史和一条评测通过的判定命令Soup 用二分搜索找到第一个开始失败的检查点——也就是回归边界soup adapters bisect \ ckpt-step-100 ckpt-step-200 ckpt-step-400 ckpt-step-800 \ --eval-command soup eval custom --model {ckpt} --tasks eval.jsonl \ -o bisect.json几个关键行为判定命令通过{ckpt}占位符注入检查点路径内部使用参数列表模式非 shell 字符串拼接检查点名里带特殊字符也不会注入。找到回归点时退出码为 3结果可直接交给下一条命令。最终结论只有两种ALL_OK全部通过没找到回归或BROKEN_AT定位到首个失败点。找到边界后可衔接soup adapters blame做数据集归因——用 leave-one-out 影响函数近似把回归归因到具体的训练样本行soup adapters blame ./run-v18 --dataset train.jsonl --layer q_proj.7 \ --budget 4h --shards 10 --plan-onlydiff看差异、merge做融合、bisect定回归、blame追源头四步构成完整的适配器调试闭环。第四步任务向量算术——加上数学能力减去毒性soup adapters arithmeticv0.71.34 引入是整套能力里最有想象力的部分把适配器看作任务向量像 git 里合并分支一样做加减法理论基础是 Task ArithmeticarXiv:2212.04089soup adapters arithmetic coder 0.5*math - toxic \ --adapter coder./coder-lora \ --adapter math./math-lora \ --adapter toxic./toxic-lora \ -o ./blended加法融合两种技能缩放2*coder让编码能力更强减法- toxic抵消掉毒性行为——这正是它区别于普通权重平均的关键。实现上有个新手容易踩的数学细节LoRA 的贡献是ΔW B·ASoup 在有效增量层面做算术保证系数严格线性缩放。如果只是朴素的逐元素相加减去一个适配器会因c²效应变成几乎无效操作——Soup 已经替你修正了这一点。使用约束都是保护性的所有输入必须共享同一基座模型--allow-cross-base可覆盖但不同基座的向量本不可比支持混合 rank 输入可选--rank N用截断 SVD 限制输出秩每个输入先过后门扫描门禁。训练阶段配合 Layer streaming即使显卡只有 225 MB 显存占用上限8B 模型也能稳定训练出这些可算术组合的适配器团队协作branch、PR 与 lock 保证可复现单人闭环之外Soup 还给团队配齐了协作面branch / checkout / branches把某次训练的「配置 基座 数据集」做 SHA-256 快照checkout恢复配置时若源已漂移会直接拒绝——可复现性不会悄悄说谎soup adapters pr把一次合并渲染成 PR 文档评测增量 样例 diff供评审soup lock write / check生成soup.lock把「基座 数据 环境」的闭包锁进一个文件队友check时任何漂移都以退出码 3 报警。总结一张表记住 Soup 适配器的 Git 工作流需求命令类比 git列出所有适配器soup adapters listgit log --oneline对比两个适配器soup adapters diff/soup diffgit diff融合多个适配器soup adapters merge/arithmeticgit merge定位回归点soup adapters bisectgit bisect快照与恢复soup adapters branch / checkoutgit branch / checkout提交评审soup adapters prgit pr从 diff 到 merge、从 bisect 到任务向量算术Soup 让 LoRA 适配器第一次拥有了完整的版本控制体验。更多细节可查阅 docs/commands.md 与 docs/adapters-and-governance.md示例配置在 examples/configs/ 中直接可用。【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考