【Bug已解决】[serge] integration failure triage - 2026-07-06 解决方案一、现象长什么样serge 是 transformers 内部用来自动给新模型跑集成测试的流水线。当你提交一个新模型的 PRserge 会拉起集成测试并比对输出与参考值然后报失败# 现象 A集成测试的 generate 输出与参考 token 序列不一致 AssertionError: generation output mismatch expected tokens: [1, 450, 23, 881, ...] actual tokens: [1, 12, 900, 55, ...] # 第 1 个 token 相同BOS之后全错 # 现象 B前几步 logits 接近但从第 2 个生成 token 起发散 # 说明 prefill 正确decode自回归阶段出问题 # 现象 C集成测试直接 shape 错 ValueError: attention_mask shape (1, 5) does not match past_key_values length # generate 时没正确维护 attention_mask / position_ids # 典型触发 # serge 跑model.generate(input_ids, attention_mask...) 比对参考最典型的指纹前向forward的 loss / logits 和参考对得上但generate()的输出却对不上——说明问题不在数学计算而在生成流程的喂料准备上。二、背景serge 集成测试对新模型会做两类检查forward校验给固定输入比对 loss / 最后一层 logits 是否与参考在 PR 提交时记录的一致。generate校验跑一小段自回归生成比对输出 token 序列。问题常出在第 2 类。一个新模型如果没正确实现prepare_inputs_for_generation或者forward在use_cacheTrue时对attention_mask/position_ids的处理不完整那么prefill第一次forward无 cache能正常算出第一个 token但从第 2 个 token 起generate会把上一步的输出 历史重新喂给forward此时需要模型用prepare_inputs_for_generation正确构造attention_mask把新 token 补上、position_ids递增和past_key_values。如果模型自己不处理HF 的GenerationMixin会用默认值而新模型可能依赖特殊的 mask/position 语义 → 喂错料 → 生成发散。三、根因根因有三类prepare_inputs_for_generation缺失或实现不全。 新模型若需要自定义attention_mask/position_ids比如带图像 token、或特殊因果掩码必须实现prepare_inputs_for_generation。缺失时generate第 2 步起的输入不含正确 mask/position → 模型看到错误的上下文 → 后续 token 全错。forward在use_cacheTrue下不消费attention_mask。 有些模型forward只在use_cacheFalse时用了attention_mask缓存命中后忽略它。于是 prefill 用了 mask、decode 阶段 mask 丢了 → 注意力范围出错 → 发散。position_ids没随生成递增。generate默认会给 position_ids但若模型内部用相对位置编码如 RoPE且期望 position_ids 随步数递增而prepare_inputs_for_generation没生成正确的递增序列第 2 步起位置编码错 → 语义漂移。四、最小可运行复现下面用纯 Python 模拟generate 第 2 步起因为没有 prepare_inputs 维护 mask导致喂错料、输出发散from dataclasses import dataclass from typing import List dataclass class GenState: step: int attention_mask: List[int] def no_prepare(state: GenState, new_token: int): 有 bug不维护 attention_mask第 2 步起 mask 没补长。 # 模型假装用 mask但 generate 没把新 token 加进 mask return state.attention_mask # 长度始终是初始的没随 step 增长 def with_prepare(state: GenState, new_token: int): 修正每步把新 token 补进 mask。 state.attention_mask state.attention_mask [1] state.step 1 return state.attention_mask # 模拟 generate第 1 步 mask[1,1,1]之后每步应 1 s GenState(step0, attention_mask[1, 1, 1]) # buggymask 永远是 [1,1,1]但序列已长到 5mask 长度不够 - 模型读错上下文 bad no_prepare(s, 450) print(buggy mask after step1:, bad, 序列长度应4) # [1,1,1] 长度不够 assert len(bad) ! 4, 复现失败 # fixedmask 随步增长 s2 GenState(step0, attention_mask[1, 1, 1]) good with_prepare(s2, 450) print(fixed mask after step1:, good) # [1,1,1,1] assert len(good) 4运行后buggy 版 mask 长度停在 3与已经生成的 4 个 token 不符模型因此看到错误的注意力范围fixed 版每步补长上下文正确——复现了generate 第 2 步起发散的根因。五、解决方案第一层最小直接修复最快的止血为模型实现正确的prepare_inputs_for_generation保证generate每步都拿到补长后的 mask 递增的 position_ids past_key_valuesfrom transformers import PreTrainedModel import torch class MyModelForCausalLM(PreTrainedModel): # ... 其它代码 ... def prepare_inputs_for_generation(self, input_ids, past_key_valuesNone, attention_maskNone, inputs_embedsNone, **kwargs): # 1) 有缓存时只喂最后一个 token性能但 position_ids 要指向当前步 if past_key_values is not None: past_length past_key_values[0][0].shape[2] # 已生成的 token 数 input_ids input_ids[:, -1:] # 只取新 token # position_ids 递增到当前步 position_ids kwargs.get(position_ids) if position_ids is not None: position_ids position_ids[:, -1:] else: position_ids torch.arange(past_length, past_length 1, deviceinput_ids.device).unsqueeze(0) else: position_ids kwargs.get(position_ids) # 2) attention_mask 原样透传HF 会自行补长但若你自定义了编码 # 确保它随序列增长 return { input_ids: input_ids, position_ids: position_ids, past_key_values: past_key_values, attention_mask: attention_mask, use_cache: kwargs.get(use_cache, True), } def forward(self, input_idsNone, attention_maskNone, position_idsNone, past_key_valuesNone, use_cacheFalse, **kwargs): # 关键无论 use_cache 与否都要消费 attention_mask / position_ids # 不要只在 use_cacheFalse 时才用 mask ...第一层让generate在 prefill 与 decode 阶段都喂对料输出与参考对齐serge 集成测试通过。六、解决方案第二层结构性改进用GenerationInputPrep把mask 补长 position 递增 cache 裁剪收口新模型直接复用避免手写遗漏from dataclasses import dataclass from typing import Optional dataclass class GenerationInputPrep: 统一维护 generate 每步的输入mask 补长、position 递增、输入裁剪。 def prepare(self, input_ids, past_key_values, attention_mask, position_ids): if past_key_values is not None: past_len past_key_values[0][0].shape[2] input_ids input_ids[:, -1:] if position_ids is not None: position_ids position_ids[:, -1:] else: import torch position_ids torch.arange(past_len, past_len 1, deviceinput_ids.device).unsqueeze(0) # attention_mask 必须随序列长度HF 默认会处理这里显式保证 if attention_mask is not None and past_key_values is not None: attention_mask attention_mask[:, -input_ids.shape[1] - past_len:] return input_ids, attention_mask, position_ids # 在模型里 class MyModelForCausalLM(PreTrainedModel): def prepare_inputs_for_generation(self, input_ids, past_key_valuesNone, attention_maskNone, position_idsNone, **kw): prep GenerationInputPrep() iid, am, pid prep.prepare(input_ids, past_key_values, attention_mask, position_ids) return {input_ids: iid, attention_mask: am, position_ids: pid, past_key_values: past_key_values, use_cache: True}GenerationInputPrep把生成输入的维护逻辑标准化新模型不再因手写漏了 mask 补长而让 serge 集成测试发散。七、解决方案第三层断言 / CI 守护用 pytest 固化generate 每步 mask 长度 序列长度、position 递增、与参考一致import pytest import torch def test_prepare_grows_mask_each_step(): from gen_prep import GenerationInputPrep prep GenerationInputPrep() past (torch.randn(2, 1, 3, 8),) # 已生成 3 个 token iid torch.tensor([[5]]) # 新 token am torch.ones(1, 4) # 当前序列长 4 iid2, am2, _ prep.prepare(iid, past, am, None) assert am2.shape[1] 4, attention_mask 长度应等于当前序列长 def test_position_increments(): from gen_prep import GenerationInputPrep prep GenerationInputPrep() past (torch.randn(2, 1, 3, 8),) iid torch.tensor([[5]]) _, _, pid prep.prepare(iid, past, None, None) assert pid.item() 3, position_ids 应递增到 past_len(3) def test_generate_matches_reference(): # 端到端实现了 prepare 的模型generate 输出应与参考 token 一致 from transformers import AutoModelForCausalLM # 用一个小模型本地验证 prepare 逻辑无网络 # 这里以 prep 覆盖为例 prep GenerationInputPrep() past (torch.randn(2, 1, 2, 8),) iid, am, pid prep.prepare(torch.tensor([[9]]), past, None, None) assert pid.item() 2CI 跑pytest tests/test_serge_integration.py以后只要新模型又漏了prepare_inputs_for_generation或 mask 没补长serge 风格的集成比对会暴露或单测先拦下。八、排查清单当 serge 集成测试generate输出与参考不一致但 forward 对得上按顺序查第 1 个 token 对、之后全错 → 必是 decode 阶段的喂料问题优先查prepare_inputs_for_generation。attention_mask长度在 decode 时不够 → mask 没随序列补长用GenerationInputPrep保证。position_ids没递增 → RoPE/相对位置编码下第 2 步起位置错实现 position 递增。forward只在use_cacheFalse时用 mask → 改为无论是否 cache 都消费 mask/position。长期方案新模型统一复用GenerationInputPrep并在 CI 加generate 输出与参考比对的集成测试。九、小结[serge] integration failure triage 里forward 对得上但 generate 对不上的根因是新模型没正确实现生成喂料准备prepare_inputs_for_generation导致generate从第 2 个 token 起attention_mask未补长 /position_ids未递增 /past_key_values截断不对模型看到错误的上下文 → 自回归发散偏离参考值。第一层实现正确的prepare_inputs_for_generation保证每步 mask 补长、position 递增、输入裁剪立刻对齐参考。第二层用GenerationInputPrep把生成输入维护标准化新模型复用避免手写遗漏。第三层pytest 断言mask 长度序列长、position 递增、generate 与参考一致防止回归。记住前向对、生成错几乎都是生成喂料的问题prepare_inputs_for_generation是连接forward与自回归的桥桥不通generate 就发散。