Speculative decoding: candidate generators return a `q` they did not sample from, breaking losslessness with `do_sample=True`

快速结论：该报错发生在 Transformers 库的投机解码（Speculative decoding）流程中，当候选生成器（candidate generator）返回的 logits 与其实际采样所用的分布不一致时触发。优先检查使用的候选生成器类型（如 DFlashTokenCandidateGenerator）和 logits processor 配置，确认是否存在分布不匹配问题。

适用环境：已确认的环境包括 Transformers 5.16.0.dev0（main 分支，commit d1123114da1ab4395198146f4f84dae7fe8b693e）、Python 3.14.6、PyTorch 2.11.0、macOS 26.4.1（CPU 测试）及 NVIDIA A100-SXM4-80GB（真实 checkpoint 测试）。

最快修复方案：将 Transformers 升级到包含 PR #48007 修复的版本，该 PR 已确认修复此问题。在修复版本发布前，暂无确认的一步修复方案。

注意事项：如果使用自定义脚本且无法立即升级，可通过检查候选生成器的 logits processor 路径来确认问题；但官方修复涉及多个生成器的改动，建议直接升级库版本。

问题场景

在 Transformers 库的投机解码流程中，用户使用 do_sample=True 进行生成时遇到采样一致性问题。问题涉及三个候选生成器：DFlashTokenCandidateGenerator、MTPCandidateGenerator 和 SinglePositionMultiTokenCandidateGenerator。用户通过固定 logits 向量的合成测试脚本，确认生成器返回的 logits 与其实际采样分布不一致。

报错原文

Speculative decoding: candidate generators return a `q` they did not sample from, breaking losslessness with `do_sample=True`

原因分析

可能原因：_speculative_sampling 函数将候选生成器返回的 candidate_logits 视为 drafter 的提议分布 q。但在 DFlashTokenCandidateGenerator.get_candidates 中，每个 token 是从 经过 processor 处理后的 logits 中采样（见 candidate_generator.py#L1674-L1685），而方法返回的是 原始 candidate_logits（见 #L1696），处理后的 next_token_logits 被丢弃。

当使用 top-k warper 时，drafter 从 q(x)/Z（Z 为 warper 保留的原始质量）中采样，但返回 q(x)，导致 p_i/q_i 的计算多了一个 1/Z 因子，使 draft token 的接受频率高于算法允许的范围，破坏了无损采样（losslessness）。

环境排查

确认 Transformers 版本是否为 5.16.0.dev0 或相近开发版本（问题在 main 分支 commit d1123114da1ab4395198146f4f84dae7fe8b693e 上确认）
检查 Python 版本（报告环境为 3.14.6）
确认 PyTorch 版本（报告环境为 2.11.0）
若使用 GPU，确认 CUDA 和显卡型号（报告环境为 NVIDIA A100-SXM4-80GB）
检查是否使用了 LogitsProcessorList（如 TopKLogitsWarper）且 do_sample=True

解决步骤

升级 Transformers 到包含 PR #48007 修复的版本，或在开发环境中拉取 main 分支最新代码。
如果无法升级，可优先尝试检查代码中是否直接调用 DFlashTokenCandidateGenerator、MTPCandidateGenerator 或 SinglePositionMultiTokenCandidateGenerator，确认是否使用了 logits processor。
对于 DFlashTokenCandidateGenerator：检查 get_candidates 方法中 next_token_logits 的处理逻辑，确保返回的 logits 与采样所用分布一致（官方修复方案）。
对于 MtpModel.forward：注意 next_token_scores 的赋值条件问题（见评论摘要），虽然当前默认参数下不可达，但修复过程中应确保所有路径都正确绑定该变量。
运行官方合成测试（固定 logits 向量）验证修复效果，确认返回的 logits 与实际采样分布匹配。

验证方法

运行用户提供的合成测试脚本（将 drafter 的词汇表投影固定为已知 logits 向量，每个位置独立同分布采样），对比生成器返回的 logits 与实际采样分布。修复后应观察到两者一致，接受率符合投机解码算法的理论值。此外，可使用 do_sample=True 和 do_sample=False 分别测试，确认两种模式下的生成分布一致。