Transformers 文本超过最大长度怎么分段处理

Transformers 遇到超过模型输入上限的文本时，不能只把 truncation=True 打开就结束，因为那会直接丢掉后半段内容。更稳妥的做法是让 tokenizer 以 token 为单位生成多个窗口：设置 max_length 控制每个窗口的上限，用 stride 保留相邻窗口的重叠，再开启 return_overflowing_tokens=True 取得全部分段。这样既不会把中文字符数误当成 token 数，也能在批量任务里追溯每个分段属于哪一条原文。

先分清截断、填充和真正的分段

模型报输入过长时，常见的三个参数解决的是不同问题。truncation 负责把过长序列压到上限；padding 负责把一个批次里的短序列补到相同长度；max_length 同时为两者提供目标长度。只写 tokenizer(text, truncation=True, max_length=256)，返回的通常只有前 256 个 token，后面的内容已经被舍弃。

用 tokenizer 返回带重叠的多个窗口

下面的例子使用单条文本。stride=32 表示下一个窗口会带上前一个窗口末尾的一部分 token，适合避免句子刚好在窗口边界被切开。return_length=True 只是为了便于记录长度，实际推理可以省略。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")
text = "这里放一篇可能超过模型输入上限的长文档……"

max_length = 256
encoded = tokenizer(
    text,
    truncation=True,
    max_length=max_length,
    stride=32,
    return_overflowing_tokens=True,
    return_attention_mask=True,
    return_special_tokens_mask=True,
    return_length=True,
    padding=False,
)

chunks = []
for input_ids, mask, length in zip(
    encoded["input_ids"],
    encoded["attention_mask"],
    encoded["length"],
):
    chunks.append({
        "input_ids": input_ids,
        "attention_mask": mask,
        "length": length,
    })

print("窗口数量:", len(chunks))
print("首个窗口长度:", chunks[0]["length"])

这里的 input_ids 已经是可以送给模型的 token id 列表，窗口边界由 tokenizer 负责处理。不要先按“每 256 个中文字符”切文本再把结果交给 tokenizer，因为一个字符可能对应不同数量的 token，中文、英文、数字和标点混合时尤其容易超限。

批量文本要保留原文映射

如果一次处理多条文档，返回结果会比输入条数更多：一条长文档可能展开成多个窗口。Fast tokenizer 会提供 overflow_to_sample_mapping，它把每个窗口映射回输入批次中的原始下标。后续做分类投票、检索排序或摘要拼接时，应先按这个下标聚合。

texts = [
    "第一条较长文档……",
    "第二条文档……",
]

batch = tokenizer(
    texts,
    truncation=True,
    max_length=256,
    stride=32,
    return_overflowing_tokens=True,
    padding="max_length",
    return_tensors="pt",
)

sample_ids = batch["overflow_to_sample_mapping"]
for chunk_index, sample_index in enumerate(sample_ids.tolist()):
    print(chunk_index, "属于原文", sample_index)

这里使用 padding="max_length" 是为了让张量形状固定；如果不需要立刻组成张量，可以先用 padding=False，在整理 batch 时再动态填充。无论哪种方式，都应把 attention_mask 交给模型，让它忽略补出来的 token。

stride 怎么选，结果怎么合并

stride 不是越大越好。它越大，窗口之间重复计算越多；太小则容易让实体、句子或段落关系在边界处断开。短文本分类可以从 16～32 个 token 起步，检索或需要保留上下文的任务可适当增加，再用实际召回和推理成本调整。这个范围是工程起点，不是 Transformers 的固定规定。

窗口级结果还要按任务合并：分类可对同一原文的窗口做最大概率或投票；检索可保留窗口分数并回传原文 id；摘要和生成任务不能简单把多个输出拼接，应该先按段落切分、分别生成，再设计去重和顺序恢复规则。

常见问题

为什么设置了 max_length 仍然报输入过长？

先检查是否真的启用了 truncation=True，以及传入模型的是否是同一个 tokenizer 产生的字段。还要留意成对输入的特殊 token 和模型自己的长度限制。

return_overflowing_tokens 为什么没有多个窗口？

文本本身没有超过 max_length 时只会返回一个窗口；另外，成对输入要明确截断策略，批量任务应使用支持 overflow 的 Fast tokenizer。

padding 会不会把补位内容送进模型？

补位 token 会出现在张量里，但正确的 attention_mask 会把它标成无效位置。不要依据 input_ids 长度判断原文长度，应结合 mask 或返回的 length。

官方文档把 padding、truncation 和 max_length 作为处理批量变长输入的核心参数；tokenizer API 还提供 stride、return_overflowing_tokens 与 overflow_to_sample_mapping 来组织溢出窗口。需要换模型时，先重新读取对应 tokenizer 的最大输入长度，再决定窗口大小。