企业官网建设流程全解析

Soup投机解码实战：--auto-spec自动配对draft模型加速推理全记录

【免费下载链接】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

Soup是一款开源的 LLM 微调与推理框架，主打"一份 YAML 微调大模型"。除了训练能力，它的soup serve推理服务还支持投机解码（Speculative Decoding）：只需加上--auto-spec一个开关，Soup 就会自动为你的目标模型配对合适的draft 草稿模型，让大模型推理速度显著提升。本文将完整记录从零启用、自动配对、到训练和测量自有 draft 模型的全流程。

一、投机解码是什么，能快多少？

大模型生成文本是"一个 token 一个 token"串行产出的，每一步都要把整个模型权重从显存搬进计算单元，属于典型的带宽受限瓶颈。投机解码的思路是：

1. 让一个又小又快的draft 模型先一口气"打草稿"，猜测接下来若干个 token；
2. 再让大模型（target）一次性并行验证这些草稿；
3. 猜对的直接采纳，猜错的位置截断重来。

一次大模型前向就"免费"换回多个 token，质量与大模型单独输出完全一致——因为最终每个 token 都经过了 target 模型裁决。

Soup 把这个流程封装到了soup serve命令中，配对逻辑见 src/soup_cli/utils/spec_pairing.py。

二、最快启用方法：一条命令开启 --auto-spec

先安装推理依赖：

pip install "soup-cli[serve]"

然后启动服务：

soup serve --model Qwen/Qwen2.5-72B-Instruct --backend vllm --auto-spec

--auto-spec的完整语义定义在 src/soup_cli/commands/serve.py 中。它会做三件事：

• 查找目标模型对应的 draft 模型（优先级见下文"本地注册表"）；
• 命中后自动注入--speculative-decoding，vLLM 后端走原生投机解码，transformers 后端以assistant_model方式挂载草稿模型；
• 未命中（例如目标模型只有 8B）则打印黄色提示并优雅回退到普通解码，服务照常启动。

内置配对表覆盖哪些模型？

内置配对表遵循"同家族、draft 比 target 小 10~50 倍"的原则，摘录如下：

两点使用提示：

• 小模型不值得开：draft + target 双模型的固定开销只有在约 30B 以上才有正收益，所以配对表里没有 8B 级模型，此时--auto-spec会安静回退；
• 参数可调：--num-speculative-tokens（默认 5）控制每步让 draft 猜测多少个 token，可在速度与显存间权衡。

三、本地 draft 注册表：Soup 优先使用你自训的草稿

如果你自己蒸馏过 draft 模型，Soup 会优先使用它，而不是内置表里的通用小模型。机制是：

1. soup draft distill训练完成后，自动把目标模型 -> draft 路径记录到本地注册表~/.soup/drafts.json；
2. 每次soup serve --auto-spec启动时，pick_draft_model 先查本地注册表，命中即用；
3. 想查看本地已有哪些 draft？运行：

soup draft list

输出是一张包含 Target / Draft / 接受率 / 创建时间的表格。注册表实现（含跨进程文件锁，防止并发蒸馏互相覆盖）在 src/soup_cli/utils/draft.py。

四、训练自己的 draft 模型：soup draft distill

内置配对表用的是"通用"小模型，而从你自己的 target 蒸馏出的 draft 接受率通常更高。Soup 提供了三步式命令（实现见 src/soup_cli/commands/draft.py）：

soup draft distill \ --target ./my-tuned-model \ --draft-base Qwen/Qwen2.5-0.5B \ --data d.jsonl \ -o draft

流程全自动：

• 以你的 target 当教师、tiny 模型当学生，走内置蒸馏配置（LoRA 学生 + 温度 2.0 前向 KL）；
• 训完自动把 LoRA合并成稠密权重——因为 draft 必须能独立加载为assistant_model；
• 自动注册进本地注册表，soup serve --auto-spec立即生效。

两个实用细节：

• 加--plan-only只打印生成的训练配置、不落盘，适合先检查再正式训练；
• 若 target 与 draft-base词表不同（跨 tokenizer），Soup 会自动切换 ULD 蒸馏（wasserstein_aligned），无需手工配置。

五、先测量再信任：soup draft measure

开启投机解码前最关键的问题没人提前回答过：这个 draft 到底值不值得？Soup 的答案是soup draft measure：

soup draft measure \ --target ./my-tuned-model \ --draft draft \ --prompts p.jsonl

它会用你生产的代表性 prompt 实测两个核心指标，并打印一块彩色报告面板：

• 接受率（Acceptance）：教师强制下的 argmax 一致率（Medusa / EAGLE 同款指标），精确、确定且廉价；
• 吞吐对比：普通解码 vs 投机解码的 tok/s，直接给出加速倍数。

报告自带三档结论：STRONG（≥70%）开始真正回本 draft 的前向开销、MODERATE（50%~70%）、WEAK（<50%）建议换 draft 或放弃。支持-o report.json导出，以及--min-acceptance 0.7作为 CI 质量门禁（不达标退出码 2）。

六、常见问题与避坑清单

完整文档见 docs/serving-and-export.md，端到端行为测试见 tests/test_speculative_decoding.py。

七、小结

• 一条命令：soup serve --model <大模型> --auto-spec，自动配对、自动回退；
• 一个注册表：自训 draft 优先于内置配对表，soup draft list随时可查；
• 两个度量：用soup draft measure的接受率与吞吐对比做决策，≥70% 值得开；
• 一个原则：先测量，再信任——投机解码的质量无损，但收益必须实测。

【免费下载链接】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