Transformers DataCollatorForSeq2Seq 的 label_pad_token_id 为什么影响 loss mask

我第一次排查翻译模型 loss 异常时，最容易把“标签补齐”和“decoder 输入”混成一件事。实际训练批次里，input_ids 可以用 tokenizer 的 padding 规则补齐，labels 却还要额外决定：补齐出来的位置到底是一个普通 token，还是应该从损失计算中排除。DataCollatorForSeq2Seq 的 label_pad_token_id 正是在这里起作用。

官方地址：https://huggingface.co/docs/transformers/main/en/main_classes/data_collator

默认的 label_pad_token_id=-100 不是“把 padding token 改名”，而是把 labels 中的补齐位置标成 PyTorch loss 默认忽略的索引。这样动态补齐只影响张量形状，不会把人为补出的空位当成真实答案学习。

先把一次训练批次拆开

序列到序列任务的每条样本通常有一段输入和一段目标输出。批处理要求同一字段在一个张量里拥有相同长度，于是较短的输入和标签都要补齐。这里我会把它们分成三层看：输入侧的 input_ids，输入侧的 attention_mask，以及训练目标侧的 labels。

# 这是一个抽象批次：真实标签长度不同，所以第二行需要补齐。
input_ids      = [[11, 21, 31,  1], [12, 22, 32, 42]]
attention_mask = [[ 1,  1,  1,  1], [ 1,  1,  1,  1]]
labels         = [[51, 61,  2, -100], [52, 62, 72, 82]]

# -100 只是损失侧的忽略标记，不代表词表中存在一个 -100 token。

上面的第一行标签只有三个真实位置，最后一个位置是为了和 batch 中的最长标签对齐。假如这个位置保留成普通的 pad_token_id，模型会收到一个看似合法的监督目标，损失函数就可能尝试预测它。补齐本身没有错，错的是让补齐产生虚假的监督信号。

理解 label_pad_token_id 与 loss mask

Hugging Face 文档给出的默认值是 -100，并明确说明 PyTorch loss 会自动忽略它。因此 label_pad_token_id 的核心含义可以写成一句话：当 collator 为 labels 做动态补齐时，应该用什么整数表示“这个位置不参与监督”。

它和 tokenizer 的 pad_token_id 服务于不同环节：

所以，不要看到 pad_token_id 就直接把它填入 labels，也不要为了让 labels “看起来像 token id” 把 -100 替换掉。调试时最有价值的不是只打印一条 loss，而是同时统计 labels 中真实位置与忽略位置的数量。

用 DataCollatorForSeq2Seq 生成批次

实际项目中我更倾向于让 collator 负责动态补齐，而不是在数据预处理阶段手工把所有目标序列补成固定长度。这样每个 batch 只按当前最长样本补齐，通常更省显存，也能把“标签补齐用哪个忽略值”集中在一个配置点。

from transformers import DataCollatorForSeq2Seq

# tokenizer 负责输入侧的 padding；collator 负责把 labels 补到 batch 的最长目标长度。
data_collator = DataCollatorForSeq2Seq(
    tokenizer=tokenizer,
    model=model,
    label_pad_token_id=-100,
    return_tensors="pt",
)

# 每个 feature 至少应包含 input_ids 和 labels，collator 返回可直接送入模型的 batch。
batch = data_collator(features)
print(batch.keys())
print(batch["labels"])

这里的 features 可以来自 tokenizer 预处理后的样本列表。设置 return_tensors="pt" 会让返回结果直接变成 PyTorch 张量；如果项目使用其他框架，应按训练器支持的张量类型调整。不要只检查 keys，还要抽一行 labels 看末尾的补齐位置是不是 -100。

区分 decoder_input_ids 的准备职责

传入 model 的意义不只是“让 collator 知道模型名字”。文档说明，如果模型实现了 prepare_decoder_input_ids_from_labels，collator 可以基于 labels 准备 decoder_input_ids。这条链路解决的是 decoder 在训练时从哪里开始读目标序列，和 labels 哪些位置参与 loss 是两件事。

可以用下面的职责划分避免误判：

• labels：告诉 loss 每个时间步应该预测什么；其中 -100 表示跳过。
• decoder_input_ids：告诉 decoder 训练时读取怎样的右移目标输入，具体由模型架构决定。
• label_pad_token_id：只决定 labels 的补齐值，不能替代模型的 decoder 起始 token 规则。

因此，如果训练 loss 变成 NaN、几乎不下降或不同 batch 的数值差异异常，我会分别打印 labels 和 decoder_input_ids，确认问题到底是目标 mask 错了，还是 decoder 输入准备与模型预期不一致。不要只因为 labels 里有 -100 就认定 batch 损坏。

排查 loss 异常的最小检查

下面这段代码只做本地批次检查，不依赖具体模型名称。它先统计被忽略的位置，再把 labels 中的 -100 临时替换为一个可打印值，避免把负索引误当成词表 id 去解码。

import torch

def inspect_seq2seq_batch(batch):
    labels = batch["labels"]
    ignored = labels.eq(-100)

    # 统计每个样本的有效目标长度，快速发现 padding 是否异常地占满一行。
    valid_counts = (~ignored).sum(dim=1)
    print("有效标签数:", valid_counts.tolist())
    print("忽略位置数:", ignored.sum(dim=1).tolist())

    if "decoder_input_ids" in batch:
        # decoder 输入与 labels 是不同职责，分别打印形状帮助定位右移问题。
        print("decoder_input_ids shape:", tuple(batch["decoder_input_ids"].shape))

    # 仅用于观察或解码：不要把替换后的副本写回训练 batch。
    printable_labels = labels.masked_fill(ignored, tokenizer.pad_token_id)
    print("可观察 labels:", printable_labels[0].tolist())

inspect_seq2seq_batch(batch)

我通常把检查结果和三种现象对照起来：

我会保留的几个边界

第一，-100 是 PyTorch 交叉熵常用的忽略索引，但如果你自定义了 loss，就要确认自己的实现是否真的读取这个 ignore index。不能只看 collator 参数名就假设所有损失函数都自动跳过。

第二，改变 label_pad_token_id 会改变 loss mask 的语义，不是一个无关紧要的格式偏好。如果改成别的值，必须同步确认 loss 的 ignore_index；否则要么补齐位置被计算，要么真实标签被错误过滤。

第三，动态补齐减少的是 batch 内无效长度，不会自动解决目标文本过长、标签截断或 tokenizer 特殊 token 配置问题。我的习惯是先固定一小批样本，把 labels、忽略位置和 decoder 输入都打印出来，再开始长时间训练。

常见问题

label_pad_token_id 能不能直接设成 tokenizer.pad_token_id？

可以传入，但只有在你的 loss 明确把该值设为 ignore index 时才安全。使用 PyTorch 默认交叉熵时，常见做法仍是让 labels 的补齐位置使用 -100。

为什么 labels 中出现 -100 不会导致 tokenizer 解码报错吗？

不要直接把包含 -100 的 labels 交给 tokenizer 解码。先用一个可打印副本把忽略位置替换成 pad_token_id，训练用的原始 labels 不要改。

传入 model 后还需要检查 decoder_input_ids 吗？

需要。model 让 collator 有机会调用架构提供的准备方法，但你仍应确认返回字段、形状和有效长度符合当前模型的训练接口。

最简单的判断标准是什么？

抽取一个 batch，确认真实目标位置数量大于零，补齐位置统一使用 loss 的 ignore index，并确认 decoder 输入的形状与 labels 对齐。三项都成立后，再看整体 loss 曲线。