tokenizers 库相关参数

介绍 tokenizers 库的四大方法与参数使用

• tokenizer 是 HuggingFace 的 transformers 库中提供的分词、编解码工具

• 包括四大主要用法

方法	输入	输出	作用层级	是否支持批量	是否自动 padding/truncation	常用场景
tokenizer.tokenize	文本(str)	token 字符串列表	分词	否	否	调试分词行为、研究 token 切分
tokenizer.encode	文本(str)	token ID 列表	将文本进行分词并编码到 ID	否	否	推理循环、dataset 预处理
tokenizer.decode	token ID 列表	文本(str)	将 ID 解码为文本	否	无意义	将输出 token 还原文本
tokenizer(…)	文本/文本列表	BatchEncoding（含 input_ids、attention_mask 等）	完整模型输入构建	是	是	训练/推理一般使用方式

tokenizer.tokenize — 分词接口

• 执行 纯分词，不执行 ID 映射，不加 BOS/EOS，不做 padding

• 代码示例

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

text = "Hello, I'm reading Transformers."

tokens = tokenizer.tokenize(text)
print(tokens)

• 输出示例：

['hello', ',', 'i', "'", 'm', 'reading', 'transformers', '.']

tokenizer.encode — 文本 → token IDs

• 执行 tokenize → convert_tokens_to_ids → 添加 special tokens（可控），但不做 padding、mask、batch

• 代码示例，只支持单条输入

ids = tokenizer.encode(
    "Hello world!",
    add_special_tokens=True,  # 添加 [CLS] [SEP] 等
    max_length=10,			  
    truncation=True,          # 超长时截断
)
print(ids)

• 输出返回 list[int]

[101, 7592, 2088, 999, 102]

tokenizer.decode — token IDs → 文本

• 进行 ID → token → 文本的完整反向过程

• 代码示例：

decoded = tokenizer.decode(
    ids,
    skip_special_tokens=True,   # 去掉 [CLS],[SEP],<pad> 等
    clean_up_tokenization_spaces=True  # 删除多余空格
)
print(decoded)

• 输出示例：

Hello world!

tokenizer(…) — 完整的模型输入构建接口

• tokenizer(text) 等价于调用 tokenizer.__call__()，是最常用的接口

• 功能列表

  • padding：自动 padding

  • truncation：输入长度超过上下文限制时，自动 truncation

  • 自动生成 attention_mask

  • 支持批量输入

  • 支持返回 PyTorch/TensorFlow tensors

  • 返回 BatchEncoding 对象（类 dict）

示例 1：单条文本

out = tokenizer(
    "Hello world!",
    padding=False,
    truncation=True
)

print(out)

输出：

{
  'input_ids': [101, 7592, 2088, 999, 102],
  'attention_mask': [1, 1, 1, 1, 1]
}

示例 2：批量文本 + padding + truncation

batch = tokenizer(
    ["Hello world!", "Transformers are amazing."],
    padding=True,           # pad 多个句子到统一长度
    truncation=True,        # 自动截断过长的句子
    max_length=16,			
    return_tensors="pt"     # 返回 PyTorch tensor，可选 tf、np
)

print(batch)

输出（示例）：

{
 'input_ids': tensor([[ 101, 7592, 2088,  999, 102,    0,    0],
                      [ 101, 19081, 2024, 6429, 1012, 102,    0]]),
 'attention_mask': tensor([[1, 1, 1, 1, 1, 0, 0],
                           [1, 1, 1, 1, 1, 1, 0]])
}

示例 3：返回 offset_mapping（NER / span tasks）

out = tokenizer(
    "Hello world!",
    return_offsets_mapping=True
)

print(out["offset_mapping"])

输出：

[(0,5), (6,11)]

适用于字符级对齐任务。

示例 4：返回 special tokens mask

out = tokenizer(
    "Hello world!",
    return_special_tokens_mask=True
)

print(out["special_tokens_mask"])

四种方法的对照代码

text = "Hello world!"

# 1. 分词（只分词，不转 ID）
tokens = tokenizer.tokenize(text)
print("tokenize:", tokens)

# 2. 编码成 token ID 列表
ids = tokenizer.encode(text, add_special_tokens=True)
print("encode:", ids)

# 3. 解码成文本
decoded = tokenizer.decode(ids, skip_special_tokens=True)
print("decode:", decoded)

# 4. 模型输入构建（最常用）
inputs = tokenizer(
    text,
    padding=True,
    truncation=True,
    return_tensors="pt"
)
print("tokenizer():", inputs)

Tokenizer 主要参数表

参数名	类型	默认值	功能分类	专业解释
text / text_pair	str / list[str]	必填	输入文本	主输入文本与可选的配对文本（如句对任务）
add_special_tokens	bool	True	输入控制	是否在序列开头/结尾添加特殊 tokens，如 [CLS] / [SEP] / <bos> / <eos>
padding	bool / str	False	填充控制	是否进行 padding。可选 "max_length"、"longest" 或 False
truncation	bool / str	False	截断控制	是否截断文本。可选True、"longest_first"、"only_first"、"only_second"
max_length	int	None	长度控制	输出序列最大长度（包含特殊 token），超长序列可截断或滑窗处理
stride	int	0	长文本滑窗	滑动窗口步长，用于长文本 split，配合 return_overflowing_tokens=True 使用
return_overflowing_tokens	bool	False	长文本处理	返回因滑窗产生的多个子序列
return_length	bool	False	输出信息	返回编码后序列长度
return_token_type_ids	bool	True	输入控制	是否返回 segment IDs（BERT 类型模型用于句对区分）
return_attention_mask	bool	True	输入控制	返回 attention mask，用于标识 padding token
return_special_tokens_mask	bool	False	输入控制	返回特殊 token mask（1 表示特殊 token）
return_offsets_mapping	bool	False	输入控制	返回原始文本字符级 offset，用于 span、NER 等任务
return_tensors	str	None	输出控制	返回张量类型，可选 "pt"、"tf"、"np"
pad_to_multiple_of	int	None	填充控制	将长度填充到指定倍数，通常用于 GPU/TPU 加速
is_split_into_words	bool	False	输入控制	当输入已分词时，保持词边界信息
verbose	bool	True	调试	是否打印 tokenizer 警告信息
return_dict	bool	True	输出控制	是否返回 BatchEncoding 对象；False 返回 tuple
add_prefix_space	bool	False	GPT 类型模型	对 GPT2 tokenizer 在开头加空格，以保证首 token 切分正确
padding_side	str	"right"	填充控制	padding 方向，可选 "left" 或 "right"
truncation_side	str	"right"	截断控制	截断方向，可选 "left" 或 "right"
max_len	int	tokenizer.max_len	长度控制	旧参数，最大序列长度，已被 max_length 替代

使用示例：

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

batch = tokenizer(
    ["Hello world!", "Transformers are amazing."],
    add_special_tokens=True,       # 添加 CLS/SEP
    padding="max_length",          # 填充到 max_length
    truncation=True,               # 超长截断
    max_length=10,                 # 最大输出长度 10
    return_tensors="pt",           # 返回 PyTorch tensor
    return_attention_mask=True,    # 返回 attention mask
    return_token_type_ids=True,    # 返回 token_type_ids
    return_special_tokens_mask=True,
)

输出（示例）：

{
 'input_ids': tensor([[ 101, 7592, 2088,  999, 102,    0,    0,    0,    0,    0],
                      [ 101, 19081, 2024, 6429, 1012, 102,    0,    0,    0,    0]]),
 'attention_mask': tensor([[1, 1, 1, 1, 1, 0, 0, 0, 0, 0],
                           [1, 1, 1, 1, 1, 1, 0, 0, 0, 0]]),
 'token_type_ids': tensor([[0,0,0,0,0,0,0,0,0,0],
                           [0,0,0,0,0,0,0,0,0,0]]),
 'special_tokens_mask': tensor([[1,0,0,0,1,1,1,1,1,1],
                                [1,0,0,0,0,1,1,1,1,1]])
}

attention_mask 的作用

attention_mask 的作用

在 Transformer 中，模型通过 自注意力（Self-Attention） 来计算 token 间关系。为了避免模型关注 padding token，需要一个 mask：

• 值为 1 的位置：表示对应 token 是有效的，可以参与 attention

• 值为 0 的位置：表示对应 token 是 padding，不参与 attention

公式上，在自注意力中，原始的注意力权重计算为：

$$A = \text{softmax}\Big(\frac{Q K^T}{\sqrt{d_k}}\Big)$$

加入 mask 后，计算变为：

$$A'_{ij} = \begin{cases} \frac{\exp(Q_i \cdot K_j / \sqrt{d_k})}{\sum_{k \in \text{valid}} \exp(Q_i \cdot K_k / \sqrt{d_k})}, & j \in \text{valid positions} \\ 0, & j \in \text{padding positions} \end{cases}$$

或者在实现中常见做法：

$$A' = \text{softmax}\Big(\frac{Q K^T}{\sqrt{d_k}} + M\Big)$$

其中 (M) 为 mask matrix：

$$M_{ij} = \begin{cases} 0, & \text{token } j \text{是有效 token} \\ -10^9 \text{或}-\infty, & \text{token } j \text{是 padding} \end{cases}$$

这样 softmax 后 padding token 对注意力输出几乎无贡献。

attention_mask 的生成机制

在 tokenizer 中，attention_mask 是根据 input_ids 生成：

out = tokenizer(
    ["Hello world!", "Transformers!"],
    padding=True,
    truncation=True,
    max_length=5,
)
print(out["input_ids"])
print(out["attention_mask"])

假设输出：

input_ids: [[101, 7592, 2088, 102, 0],
            [101, 19081, 999, 102, 0]]
attention_mask: [[1, 1, 1, 1, 0],
                 [1, 1, 1, 1, 0]]

原理：

1. padding token id：tokenizer 定义 pad_token_id（如 BERT=0，GPT2=None）

2. mask 生成规则：

attention_mask[i][j] = 1 if input_ids[i][j] != pad_token_id else 0

• 对每个 batch 中的序列都执行

• 可直接作为 Transformer 的输入

特殊情况

1. GPT 类模型：通常没有 pad token，attention_mask 全为 1

2. 左 padding / 右 padding：

   • padding_side="right" → mask 右边 padding 为 0

   • padding_side="left" → mask 左边 padding 为 0

示意：

input_ids (right padding): [101, 7592, 2088, 102, 0]
attention_mask:            [1,    1,    1,    1, 0]

input_ids (left padding):  [0, 101, 7592, 2088, 102]
attention_mask:            [0, 1,    1,    1,    1]

公式化

给定 batch 的 input_ids：

$$X = [x_1, x_2, ..., x_L], \quad x_i \in \text{vocab ids}$$

定义 pad_token_id：

$$\text{pad\_id} \in \text{vocab}$$

则 attention_mask 生成公式：

$$\text{attention\_mask}_i = \begin{cases} 1, & x_i \neq \text{pad\_id} \\ 0, & x_i = \text{pad\_id} \end{cases}$$

注意事项

• attention_mask 是 每层 Transformer 公用，会被直接加入 self-attention 计算

• 可用于 padding、截断、多长度序列

• 与 token_type_ids / position_ids 配合使用，确保模型识别有效 token 和 segment