Hugging Face tokenizer 怎样按 special tokens 判断截断边界

Hugging Face tokenizer 的 special tokens 可以帮助辨认序列包装位置，但不能单独证明正文有没有被截断。正确判断要把未截断编码的长度、模型专属的特殊标记数量，以及截断后的 special_tokens_mask 放在一起看。末尾仍有 SEP 或 EOS，并不表示原文尾部还在。

官方地址：https://huggingface.co/

分词器文档：https://huggingface.co/docs/transformers/main_classes/tokenizer

以下限定 Transformers 中常规文本或文本对编码，不讨论聊天模板、多模态占位符或生成停止条件。代码以本地已准备好的 tokenizer 目录为输入，只作教学示例；本文没有运行它，也不展示虚构的 token ID 或实测输出。

先把特殊标记位置与正文是否丢失分开

排查时先区分三种对象：input_ids 是最终编码序列，special_tokens_mask 标识本次编码中的特殊位置，attention_mask 用于区分有效位置与填充位置。它们都不是“被删除原文”的备份。

以常见的 BERT 风格包装为例，截断正文后仍可存在起始与分隔标记。不能把“最后一个 ID 等于 sep_token_id”写成全文完整的判定规则，更不能假设所有模型都是相同的两个特殊标记。文本对的包装开销也可能与单文本不同。

还应避免直接切 input_ids[:max_length]：这可能把必要的结构标记一起切掉。如果需要模型规定的包装，就把截断交给相应 tokenizer 的正式接口处理，而不是截完列表后猜着补一个 EOS。

让 tokenizer 处理完整输入长度预算

先固定模型对应的 tokenizer 与明确的 max_length，再决定是否添加特殊标记。启用 add_special_tokens 时，最大输入长度的预算要包含包装；普通内容可用空间因此会减少。不要通过关闭必要标记来掩盖超长问题。

import sys
from transformers import AutoTokenizer

# 传入本地已准备好的分词器目录；不下载模型，不加载远程自定义代码
if len(sys.argv) != 2:
    raise SystemExit("请传入本地 tokenizer 目录")
tok = AutoTokenizer.from_pretrained(
    sys.argv[1], use_fast=True, local_files_only=True,
    trust_remote_code=False
)

text = "A short note about library opening hours. " * 12
limit = 32  # 教学预算，实际值须符合模型及任务约束
extra = tok.num_special_tokens_to_add(pair=False)
if limit  len(cut["input_ids"]))

# 保留标记视图；不要用去标记后的字符串判断结构是否完整
pieces = tok.convert_ids_to_tokens(cut["input_ids"])
for i, (piece, special, active) in enumerate(zip(
    pieces, cut["special_tokens_mask"], cut["attention_mask"]
)):
    print(i, piece, special, active)

这个例子没有 padding、溢出窗口和聊天模板，且只有是否截断的参数差异，因此长度缩减可以帮助判断该次调用是否丢掉了输入 token。长度等于 limit 只说明碰到了数值上限，原始输入刚好等长时也可能没有删除；应与 full 对照，而不是单看 cut。

num_special_tokens_to_add 适合在初始化或诊断时了解开销，不应放进每条训练样本的热循环重复计算。预留预算时要使用当前 tokenizer 的结果，不硬编码“永远减二”。

用配对输入确认该截哪一段

文本对里，truncation=True 通常采用 longest_first；如果要完整保留短问题，仅截掉长文档，可使用 only_second。此时先确认第一段加包装没有耗尽总预算，否则策略无法凭空为第二段创造空间。

# 接续前例：问题保持完整，长材料作为第二段
question = "Which days is the library open?"
document = "The library opens on weekdays and closes on holidays. " * 20
limit = 48

# 用相同分词器、不加包装估算固定第一段所占空间
first_ids = tok(question, add_special_tokens=False)["input_ids"]
pair_extra = tok.num_special_tokens_to_add(pair=True)
if len(first_ids) + pair_extra >= limit:
    raise ValueError("第一段与包装已占满预算，请先调整输入或上限")

pair = tok(
    question, document, add_special_tokens=True,
    truncation="only_second", max_length=limit, padding=False,
    return_special_tokens_mask=True
)
# sequence_ids依赖fast tokenizer，返回每个位置所属的输入段
if not tok.is_fast:
    raise ValueError("此定位示例要求 fast tokenizer")
pieces = tok.convert_ids_to_tokens(pair["input_ids"])
for i, (piece, seq, special) in enumerate(zip(
    pieces, pair.sequence_ids(), pair["special_tokens_mask"]
)):
    print(i, piece, seq, special)

本例中 sequence_ids 的 0 对应问题、1 对应文档，包装特殊标记对应 None。None 是结构归属信息，不是“这个位置发生了截断”的标志。若以后加入 padding，也不能把所有 None 都解释为内容分隔符。

截断方向还受 truncation_side 影响：保留前部还是后部，要看当前配置。需要定位原文位置时，可在支持的 fast tokenizer 上请求 offset_mapping；偏移用于文本定位，不代表被截掉内容会出现在最终序列中，也不能脱离当前 tokenizer 的正规化规则解读。

保留可解释的边界记录而不是猜测

用于复现的记录应包含 tokenizer 标识或固定版本、max_length、add_special_tokens、截断策略、truncation_side 和 padding 方式。保留必要长度与掩码即可，真实业务中不要为诊断随意记录隐私原文。

decode 时看不到 SEP，是不是它没加上？先检查是否用了 skip_special_tokens=True。那会隐藏特殊标记，不是证明编码缺失。结构诊断优先看 ID 与 token 视图。

有 EOS 就表示没截断吗？不是。输入包装与正文完整是两个问题；生成模型输出中的 EOS、停止序列和生成长度限制又是另一套边界，不能混在一起。

为什么修改 tokenizer 后原来的减二公式不对了？包装规则依赖 tokenizer 和单段/配对模式。重新计算专属预算，并检查模板是否已自带特殊标记；聊天模板不属于本文公式可直接套用的范围。

判断顺序可以归纳为：先固定输入方式与上限，再看模型包装开销，最后对照未截断输入与最终编码。special tokens 是理解边界的线索，不是全文未丢失的证明。

参考：Transformers Tokenizer 接口、Padding 与 truncation 官方说明。