Tokenizers offset mapping 怎么映射回原始文本位置

做实体抽取或文本高亮时，真正要保存的不是 token 字符串，而是它在原始输入里的区间。Tokenizers 的 offset_mapping 就是这座桥：每个普通 token 返回一个半开区间 [start, end)，可以直接用 text[start:end] 取回原文片段。实际使用时要先确认是 Fast Tokenizer，再把特殊 token、空白和长文本窗口单独处理。

先用原文切片验证 offset mapping

不要把 tokenizer.convert_ids_to_tokens() 返回的 token 直接拼回原文。ByteLevel、大小写处理、重音符号和空白策略都可能让 token 展示形式与输入不同。验证映射时，以 offset_mapping 为准：

from transformers import AutoTokenizer

# Fast Tokenizer 才能提供字符对齐能力；模型名只是示例，可替换为已使用的模型。
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased", use_fast=True)
text = "Hugging Face tokenizers map tokens back to text."

# 返回每个 token 在原始字符串中的半开区间 [start, end)。
encoded = tokenizer(text, return_offsets_mapping=True, add_special_tokens=True)
tokens = tokenizer.convert_ids_to_tokens(encoded["input_ids"])

for token, (start, end) in zip(tokens, encoded["offset_mapping"]):
    # 特殊 token 通常没有原文字符，(0, 0) 不能当作第一个字符。
    source_piece = "" if start == end else text[start:end]
    print(token, (start, end), repr(source_piece))

这里的 end 是排他边界，所以 text[start:end] 正好覆盖映射片段。若输出里出现 [CLS]、[SEP] 或补齐 token，不要拿它们的零宽区间去高亮原文。

字符、token 和预分词输入要分三种定位

如果已知某个字符位置，可以用 char_to_token 反查 token；如果已知 token 下标，则用 token_to_chars 取原文区间。空白位置可能返回 None，这不是映射失效，而是该字符没有被保留在可见 token 区间中。

# 用字符位置找到 token，再取回它覆盖的原文区间。
char_index = text.index("tokenizers")
token_index = encoded.char_to_token(char_index)
if token_index is not None:
    span = encoded.token_to_chars(token_index)
    print(text[span.start:span.end])

# 预分词输入需要 word_ids；多个子 token 可以共享一个 word id。
words = ["Hugging", "Face", "tokenizers"]
pretokenized = tokenizer(words, is_split_into_words=True,
                         return_offsets_mapping=True)
print(pretokenized.word_ids())  # 特殊 token 为 None，子词可指向同一个单词

做序列标注时，优先用 word_ids() 把子词预测合并回输入单词；做原文高亮时，使用 token_to_chars 或 offsets。两种索引解决的是不同问题，混用会造成偏移一位或重复高亮。

规范化和长文本会改变判断方式

Tokenizers 的流程通常包含规范化、预分词、模型切分和后处理。规范化可能把一个输入字符展开、合并或去除重音，因此“token 看起来是什么”与“它来自原文哪里”不能互相替代。需要审计原文时，始终保存原始 text，并用区间切片回填。

长文本开启截断和溢出窗口后，每个窗口都有自己的 token 序列。处理批量结果时，结合 overflow_to_sample_mapping 确认窗口属于哪条原文，再读取该窗口的 offsets；不要把第二个窗口的 token 下标直接当成全局 token 下标。跨窗口实体还要用字符区间去重或合并。

一张表排查常见错位

相关问题

offset mapping 是 token 的字节位置吗？

常规 Fast Tokenizer API 里它表示原始字符串的字符跨度，不是 token ID，也不是展示 token 的字节数组。最终仍应以当前库版本和具体 tokenizer 的文档为准。

为什么特殊 token 也有 offset？

为了保持输出数组对齐，后处理加入的特殊 token 也会占一个位置；它没有对应原文字符时通常用零宽区间表示。

只用 token 字符串能恢复原文吗？

不可靠。规范化、空白、ByteLevel 和特殊 token 都可能破坏简单拼接，原文定位应保存 offsets 并按区间切片。