Transformers 批量生成时 padding_side 为什么重要

在 Transformers 里，padding_side 不是单纯的排版选项。批量输入长度不一致时，填充 token 放在左边还是右边，会改变 decoder-only 模型看到的最后一个位置，进而影响它从哪里开始续写。对这类自回归模型，批量生成通常应使用左填充；单条输入不需要补齐时，这个设置几乎没有可见差别。

官方资料入口：https://huggingface.co/docs/transformers/

padding_side 只在批量对齐时真正起作用

假设一批里有“介绍 Go”与“介绍 Go 的 HTTP 客户端超时处理”两条提示词。tokenizer 为了把它们组成一个张量，需要把较短的一条补到相同长度。padding_side="right" 会把填充放在真实 token 后面，padding_side="left" 则把填充放在真实 token 前面。

这两个选择不会改变原始字符串本身，却会改变 token 在批次中的位置。attention_mask 可以标记哪些位置是填充位，但它不能把“短提示词的最后有效位置”重新移动到批次末端。因此，理解生成模型如何取下一词位置，比记住一个固定参数更重要。

为什么 decoder-only 生成更偏向左填充

decoder-only 模型按从左到右的上下文继续预测。批量生成时，框架需要为每一行找到适合继续生成的末端位置。右填充会让较短提示词的末列变成 pad_token，真实上下文的末端反而提前结束；这就是官方 Transformers 文档把 LLM 批量生成的填充方向指向左侧的原因。

右填充并不等于所有 Transformer 任务都会报错。它在某些编码任务或其他模型架构中可能是合理默认值，但不能把“适合编码输入”直接套到 decoder-only 的批量续写上。判断时先看模型架构和任务，再看 tokenizer 的实际配置。

decoder-only LLM 的一套基础配置

可以把左填充固定在 tokenizer 初始化处，而不是每次调用 tokenizer 时临时修改。下面的示例只展示配置关系，不依赖某个私有模型；模型名称替换成你已获授权使用的 checkpoint 即可。

from transformers import AutoTokenizer

# decoder-only 模型批量续写时，把补齐 token 放在真实提示词左侧。
tokenizer = AutoTokenizer.from_pretrained(
    "your-org/your-causal-lm",
    padding_side="left",
)

# 有些 causal LM 没有单独的 pad_token；只有在模型约定允许时才复用 eos_token。
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

prompts = [
    "用一句话解释 goroutine",
    "用三句话解释 Go 中 goroutine 与 channel 的关系",
]

# padding=True 让同一批输入对齐，return_tensors 产出可交给模型的张量。
model_inputs = tokenizer(
    prompts,
    padding=True,
    truncation=True,
    return_tensors="pt",
)

# 将 input_ids、attention_mask 等编码结果整体传入生成接口。
generated_ids = model.generate(**model_inputs, max_new_tokens=80)

# 跳过特殊 token，得到每条输入对应的可读文本。
texts = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)

这里最重要的不是把 eos_token 机械复制给每个模型，而是确认模型的 tokenizer 是否缺少 pad token，以及当前模型的官方用法是否允许这样处理。若模型已经定义了专用的 pad token，就保留它；若模型对 chat template、设备或 dtype 有额外要求，也要沿用它自己的加载方式。

attention_mask 与 pad_token_id 要一起看

padding_side 决定填充放在哪里，attention_mask 负责告诉模型哪些位置是有效上下文。只改填充方向，却在后续调用中丢掉 mask，仍然可能让填充位参与计算。

# 复用 tokenizer 返回的 mask；不要只取 input_ids 而丢掉它。
input_ids = model_inputs["input_ids"]
attention_mask = model_inputs["attention_mask"]

# pad_token_id 需要与 tokenizer 的实际填充 token 对齐。
outputs = model.generate(
    input_ids=input_ids,
    attention_mask=attention_mask,
    pad_token_id=tokenizer.pad_token_id,
    max_new_tokens=80,
)

# 批量解码时跳过 eos/pad 等特殊 token，避免把控制 token 当正文显示。
texts = tokenizer.batch_decode(outputs, skip_special_tokens=True)

如果出现“批量结果异常、短输入重复或输出像是从填充位开始”的现象，先打印 tokenizer 的 padding_side、pad_token_id，再确认 attention_mask 是否随输入传入。不要先把采样参数、温度或最大长度全部改一遍，那些参数解决的是另一层问题。

不同模型架构该怎么选

我更愿意把这个问题看成一次小型选型：先确认是否真的需要批量补齐，再确认模型是“接着输入续写”还是“把输入编码后生成输出”。下面的表格给出一个不容易混淆的默认判断。

排查时按这张清单收敛范围

1. 确认输入是不是同一批、长度是否真的不同；如果只有一条输入，先排除 padding 造成的猜测。
2. 确认模型是 decoder-only 还是 encoder-decoder；不要只看模型名字里的“生成”二字。
3. 打印 tokenizer.padding_side 与 tokenizer.pad_token_id，确认配置没有被加载文件覆盖。
4. 检查编码结果中是否包含 attention_mask，并确认调用 generate() 时没有丢失它。
5. 最后再看 max_new_tokens、采样策略和 chat template；这些设置不应替代对齐方向的判断。

# 这段只打印配置事实，便于定位批量生成的输入边界。
print("padding_side:", tokenizer.padding_side)
print("pad_token_id:", tokenizer.pad_token_id)
print("has_attention_mask:", "attention_mask" in model_inputs)

# 若是 decoder-only 批量续写，通常期望左填充。
if tokenizer.padding_side != "left":
    raise ValueError("decoder-only 批量生成请先确认 padding_side 配置")

结论

padding_side 重要，是因为批量生成不仅要把序列凑成相同长度，还要让模型找到正确的真实上下文末端。对 decoder-only LLM，左填充通常更符合 Transformers 官方的批量生成建议；对 encoder-decoder 或编码类任务，则应回到模型自己的输入约定。配好方向后，把 attention_mask、pad_token_id 一起纳入配置，排查范围会清晰很多。

常见问题

只有一条输入时，还要设置 padding_side 吗？

通常不需要因为单条输入专门补齐。可以保留统一的 tokenizer 配置，但真正产生差别的是同一批中存在不同长度的序列。

把 right 改成 left 后就一定能解决异常输出吗？

不一定。还要确认 attention_mask、pad_token_id、chat template、模型架构和截断设置。左填充只解决批量对齐中的一个关键边界。

为什么不能只传 input_ids 给 generate？

因为批量填充后，模型需要 mask 区分真实 token 与 pad token。保留 tokenizer 返回的完整输入字典，通常比手工只抽取一个字段更稳妥。