Additional options for include_num_input_tokens_seen in Trainer

快速结论：这个报错/需求通常出现在使用 Hugging Face Transformers 的 Trainer 进行训练时，`include_num_input_tokens_seen` 统计的 token 数包含了 padding token，导致令牌数虚高。优先排查方法是将该参数设置为 `”non_padding”`，从而改用注意力掩码（attention mask）来统计实际输入 token。

适用环境：Hugging Face Transformers 库（Trainer 组件，涉及 trainer.py 文件）；Discord 讨论涉及 v4.43.4 版本及后续版本。未确认操作系统、Python、CUDA、显卡等环境信息。

最快修复方案：将 `include_num_input_tokens_seen` 参数值从默认值改为 `”non_padding”`。该选项在后续版本（由 PR #40416 引入）中已支持 `”all”`、`”non_padding”` 和 `”no”` 三种取值，现有行为默认保持不变。

注意事项：若需统计仅参与损失的 token（例如 SFT 训练中仅标签部分），此方案仍未完全覆盖；相关讨论中建议保持统计所有 token 的行为。如果使用自定义数据或处理 2D 格式的 attention mask，需确认数据加载器是否提供该字段。

问题场景

使用 Hugging Face Transformers 的 Trainer 进行模型训练（尤其是打包/非打包训练时），需要跟踪模型实际看到的 token 数。原始实现基于 `input_ids` 统计，会将 padding token 也计入，导致统计不准确。Issue 提出于文本生成或 SFT（监督微调）场景。

报错原文

Additional options for include_num_input_tokens_seen in Trainer

原因分析

可能原因：Trainer 统计的 `num_input_tokens_seen` 指标按序列长度（即 `input_ids`）计数，而 pad 填充的 token 也被计入。以下场景中统计会失真：1) 未使用打包训练，每个 batch 内样本 pad 到最长序列；2) SFT 仅对补全（completions）部分训练，但 padding token 也被计入（或标签为 -100 的 token）。

环境排查

Transformers Trainer 版本：v4.43.4 及之后（建议升级到包含 fix 的版本）。
检查 trainer.py 中 include_num_input_tokens_seen 参数当前设置。
确认数据加载是否提供 attention_mask，以及其格式（2D 或 3D）。
确认训练脚本中是否使用了打包（packing）逻辑，以及 SFT 是否设置标签 -100。

解决步骤

升级 Transformers 到包含修复的版本，并查看对应 trainer.py 中相关实现（约 line 2596-2599）。
训练时设置参数：include_num_input_tokens_seen="non_padding"，替代原有默认值。
如需兼容旧行为而保留原有统计，可继续使用默认值或显式设置为 "all"。这个新控制选项避免用户指标在升级后发生变化。
若需进一步过滤到仅对 label != -100 的 token 计数（例如只统计参与损失的部分），当前官方方案尚未支持，需自行修改 trainer 代码或使用第三方程式（可优先尝试关注用户讨论中提出的临时代码片段，但未被维护者合并）。

验证方法

升级后对比开启 "non_padding" 与默认值（即统计所有 token）时的 num_input_tokens_seen 数值。若前者不再随输入序列中的 padding 长度变化，则表明问题已解决。若还需验证是否只计算非 padding token，可在同一 batch 中人为改变最长序列长度并观察统计值变化。