Transformers tokenizer return_tensors 怎样避免批量输入无法组装

在批量文本推理中，最容易误解的一点是：return_tensors="pt" 只决定 tokenizer 返回 PyTorch 张量，并不会替不同长度的样本自动补齐。若同一批文本编码后的 token 数不同，直接组装张量就可能出现“无法创建 tensor，建议启用 padding 和 truncation”的错误。

官方文档：https://huggingface.co/docs/transformers/main_classes/tokenizer

这篇文章只解决批量输入的长度对齐问题，不讨论 padding_side 对生成方向的影响。记住一句话：先用 padding 让同批序列形状一致，再用 truncation 和 max_length 把长度限制在模型能接受的范围内，最后才交给 return_tensors 转成张量。

先区分 return_tensors 与长度对齐

把两段长短不同的文本放进列表时，tokenizer 得到的 input_ids 也可能是一长一短。Python 列表可以容纳这两行，但规则张量通常需要一个规则的二维形状，所以“返回 PyTorch 张量”和“让每行长度一致”是两个不同职责。

下面的写法故意把几个关键参数放在一起，作为文章中的最小配置示例：

from transformers import AutoTokenizer

# 使用公开模型名演示批量输入；示例只说明参数关系，不代表本机已执行。
tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased")
texts = ["short input", "a longer input with more tokens"]

# padding 让同一批的序列长度一致，truncation 负责限制过长文本。
batch = tokenizer(
    texts,
    padding=True,
    truncation=True,
    max_length=128,
    return_tensors="pt",
)

# input_ids 与 attention_mask 共享批量维度，才能交给模型。
print(batch["input_ids"].shape)
print(batch["attention_mask"].shape)

这里的关键不是 print 会输出什么，而是两个字段都应保留批量维度，并且第二维能够对齐。return_tensors="pt" 负责最终容器类型，不能代替 padding。

用动态 padding 组装同批输入

padding=True 通常表示按当前 batch 中最长的序列补齐。它适合样本长度差异不大、希望减少无效计算的在线批处理。补齐位置由 tokenizer 的配置决定，模型会通过 attention_mask 区分有效 token 与补齐位置。

如果只想让输入能组装，优先从这组参数开始：

# 动态补齐到当前批次的最长样本，避免为整批预留过大的固定长度。
batch = tokenizer(
    texts,
    padding=True,
    truncation=True,
    max_length=512,
    return_tensors="pt",
)

# 将字段整体送给模型，避免漏传 attention_mask。
outputs = model(**batch)

如果报错仍然出现，先看是否把字符串列表误写成了嵌套结构、是否对不同字段单独做了二次切片，以及 input_ids 和 attention_mask 的第二维是否一致。不要为了绕过报错而直接把列表强行转换成对象数组，那只会把形状问题推迟到模型调用处。

用 truncation 和 max_length 控制上限

padding 解决的是“同批样本不一样长”，truncation=True 解决的是“单个样本超过允许长度”。max_length 给这两个策略提供目标上限：没有截断时，过长文本仍可能超过模型最大输入；没有 padding 时，固定长度也不会自动产生统一的张量。

# 固定输入上限，过长文本按 tokenizer 的截断策略缩短。
max_length = 256
batch = tokenizer(
    texts,
    padding="max_length",
    truncation=True,
    max_length=max_length,
    return_tensors="pt",
)

# 训练或推理前保留 mask，让模型忽略 padding 位置。
input_ids = batch["input_ids"]
attention_mask = batch["attention_mask"]

固定长度会带来更稳定的形状，适合需要统一 batch、静态图编译或硬件对齐的场景；代价是短文本会产生更多 padding。在线请求长度波动明显时，动态 padding 往往更省无效计算。

动态长度、固定长度和倍数补齐怎么选

选择时先问两个问题：模型允许的最大长度是多少，以及同一批文本的长度差异有多大。不要把 max_length 当成越大越安全；它会直接影响显存、吞吐和被截断的信息量。

遇到批量组装错误时检查这几个边界

1. 是否启用了 padding。 只有 return_tensors 而没有补齐策略，最容易导致长度不一致。
2. 是否启用了 truncation。 批次内部形状一致，不代表文本没有超过模型输入上限。
3. 是否存在 pad token。 某些 tokenizer 没有预设补齐 token，需要依据具体模型文档显式配置，不能盲目把任意 token 当作 pad token。
4. 是否整批传递字段。 使用 model(**batch) 通常比只传 input_ids 更不容易漏掉 attention_mask。

把这几个边界分开后，排查路径就很清楚：先确认输入是“批量文本”，再确认补齐与截断策略，最后确认每个字段的批量维度一致。这样解决的是 tokenizer 的输入契约，而不是用张量转换掩盖数据形状问题。

相关问题

为什么 padding=True 还需要 truncation=True？ 前者只保证当前 batch 能补齐，后者负责限制过长文本；两者解决不同问题。

padding="max_length" 会不会更快？ 它让形状稳定，但可能为大量短文本补齐无效位置，是否更快取决于硬件和批次分布。

attention_mask 可以省略吗？ 不建议默认省略。它是模型区分有效 token 与 padding 位置的重要输入字段，应随 BatchEncoding 一起传递。