Transformers tokenizer offset mapping 的原文区间对齐

offset_mapping 解决的是“这个 token 在原文的哪一段”问题。使用 Hugging Face Transformers 的 Fast tokenizer，并在调用时设置 return_offsets_mapping=True，就能拿到每个 token 对应的半开字符区间 (start, end)，再用 text[start:end] 取回原文片段。

官方文档地址：https://huggingface.co/docs/transformers/main_classes/tokenizer。本文重点是对齐边界：特殊 token 通常没有真实原文区间，空白可能被裁剪，批量和句对还需要额外区分序列。

最稳妥的做法是把 offset_mapping 当成原文字符坐标，而不是 token 文本的“猜测位置”：先确认使用 Fast tokenizer，再跳过无效区间，最后按同一条输入和同一组截断结果做映射。

先确认 offset_mapping 能从哪里拿到

Transformers 文档把 tokenizer 分成普通 Python 实现和 Fast 实现。return_offsets_mapping 只适用于继承 PreTrainedTokenizerFast 的 tokenizer；如果使用慢速 Python tokenizer，调用该参数会抛出 NotImplementedError。因此，第一道门禁不是检查返回数组，而是确认 tokenizer 的实现类型。

from transformers import AutoTokenizer

# 使用 Fast tokenizer，后面才能请求原文字符区间
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased", use_fast=True)
text = "Transformers maps tokens back to text."

# 同时取 token、ID 和每个 token 的原文半开区间
encoding = tokenizer(
    text,
    add_special_tokens=True,
    return_offsets_mapping=True,
    return_special_tokens_mask=True,
)

print(encoding.tokens())
print(encoding["offset_mapping"])
print(encoding["special_tokens_mask"])

这里的 offset_mapping 与 input_ids 按位置对应：第 i 个区间属于第 i 个 token。加入 [CLS]、[SEP] 等特殊 token 后，数组仍然按编码后的位置排列，不能拿未加特殊 token 的 token 列表直接套索引。

用半开区间切回原文片段

区间 (start, end) 使用 Python 常见的半开表示法：包含 start，不包含 end。所以还原片段时直接写 text[start:end] 即可。不要用 token 的字符串长度反推原文位置，因为子词拆分、大小写归一化和空白处理都会让两者长度不同。

def token_spans(text: str, encoding) -> list[dict]:
    """返回有真实原文覆盖范围的 token 片段。"""
    tokens = encoding.tokens()
    offsets = encoding["offset_mapping"]
    special_mask = encoding.get("special_tokens_mask")
    rows = []

    for index, (token, pair) in enumerate(zip(tokens, offsets)):
        start, end = pair
        # 特殊 token 常见为 (0, 0)，也用 mask 明确排除
        is_special = special_mask is not None and special_mask[index] == 1
        if is_special or start == end:
            continue
        # 半开区间可以直接切回原文，end 不包含在片段内
        rows.append({"token_index": index, "token": token, "span": [start, end], "text": text[start:end]})

    return rows

这个函数的结果适合做高亮、实体投影或调试日志。它没有把空白区间强行变成 token，也没有因为 token 文本看起来像特殊符号就自行猜测位置；判断依据来自编码结果里的特殊 token 标记和区间本身。

特殊 token 和空白为什么要单独处理

特殊 token 是模型输入格式的一部分，不是原文字符。对 BERT 风格输入来说，开头和结尾可能出现 [CLS]、[SEP]，它们通常没有可切回原文的字符范围。把它们当作实体候选，会产生“实体从原文开头开始”的假结果。

空白也有类似陷阱。Fast tokenizer 的对齐方法可能对空白位置返回 None，尤其是在空白被裁剪时；而 offset_mapping 中的零长度区间也不应该被当作有效文本。实践中同时看 special_tokens_mask 和 start 更稳妥。

def valid_token_indices(encoding) -> list[int]:
    offsets = encoding["offset_mapping"]
    special_mask = encoding.get("special_tokens_mask", [0] * len(offsets))
    valid = []

    for index, ((start, end), is_special) in enumerate(zip(offsets, special_mask)):
        # 只保留覆盖至少一个原文字符、且不是格式化 token 的位置
        if not is_special and start 

如果应用必须保留空白，例如做精确文本编辑器标注，就不要依赖“所有空白都会有独立 token”这一假设；应以原文坐标为主，另行维护空白或标点的显示策略。

把实体字符区间映射到 token 索引

很多标注数据先给出原文实体区间，例如 [16, 27)，之后才需要传给 token 分类模型。可以用 char_to_token 找一个字符所在的 token，也可以遍历 offset_mapping，选出与实体区间相交的所有 token。后者更适合一个实体被拆成多个子词的情况。

def char_span_to_token_span(encoding, entity_start: int, entity_end: int):
    offsets = encoding["offset_mapping"]
    special_mask = encoding.get("special_tokens_mask", [0] * len(offsets))
    matched = []

    for token_index, ((start, end), is_special) in enumerate(zip(offsets, special_mask)):
        # 两个半开区间相交：token 起点在实体终点前，且 token 终点在实体起点后
        overlaps = start 

区间相交规则不会要求实体边界刚好落在某个 token 边界上。例如一个英文词被拆成两个子词时，两个子词的区间都与实体区间相交，就应该一起保留。char_to_token 找不到空白字符对应的 token 时返回 None，这不是异常，而是提示该字符没有可直接承载的 token。

批量、句对和截断要保持同一坐标系

单条文本时可以把 offset_mapping[i] 理解为第 i 个编码 token 的原文坐标；批量输入时，它先多一层样本索引。句对输入还要区分第一序列和第二序列，不能把两段文本的坐标混在一起。

texts = ["A short document.", "Another document."]

# 批量结果的每个字段都以样本为第一层；不把不同样本的区间拼接
batch = tokenizer(
    texts,
    padding=True,
    truncation=True,
    max_length=16,
    return_offsets_mapping=True,
    return_special_tokens_mask=True,
)

for sample_index, sample_offsets in enumerate(batch["offset_mapping"]):
    sample_text = texts[sample_index]
    # 每个样本都回到自己的原文字符串中切片
    for token_index, (start, end) in enumerate(sample_offsets):
        if start 

开启 truncation 后，超过 max_length 的 token 不会出现在当前编码结果里；原文里对应的尾部区间也就不会有 token 可映射。如果开启 return_overflowing_tokens=True 产生溢出窗口，还要结合返回的样本映射字段，把每个窗口归回原始样本，不能把窗口下标直接当成原文样本下标。

句对场景应使用 sequence_ids() 或 char_to_token(..., sequence_index=0/1) 识别属于哪一段。即使两个序列都从字符 0 开始，它们也是不同的原文坐标空间；对第二序列查找字符时，必须明确传入对应的序列索引。

常见误区与一张速查表

可以把整个过程记成四个动作：Fast tokenizer 负责产生对齐信息；offset_mapping 提供原文半开坐标；special_tokens_mask 排除格式化 token；实体映射按字符区间相交，而不是按 token 字符串长度猜测。

offset_mapping 是 token 的字节位置吗？

在 Transformers 的 tokenizer 接口语境中，它返回的是原文字符区间 (char_start, char_end)。使用时应按文档和当前 tokenizer 的编码行为处理，不要把它当成 UTF-8 字节偏移量直接交给字节数组。

慢速 tokenizer 能不能自己补 offset_mapping？

不建议把慢速 tokenizer 的 token 文本用长度累加来补齐。归一化、子词边界和空白裁剪都可能让这种推断失真；需要原文对齐时，优先选择对应的 Fast tokenizer。

为什么实体边界落在空格上时没有 token？

空格可能没有独立 token，或在对齐时被裁剪。实体标注应先规范为覆盖实际字符的半开区间，再根据与 token 区间的相交关系决定是否纳入。

参考：Hugging Face Transformers Tokenizer 官方文档，包含 Fast tokenizer 的字符映射能力、return_offsets_mapping 参数和 BatchEncoding.char_to_token 的说明。