Tokenizers 怎样批量编码并返回 attention mask

Hugging Face Tokenizers 的 Python 接口可以用 encode_batch 一次编码多条文本，再从每条 Encoding 读取 ids 和 attention_mask。需要拼成等长批次时，先配置 padding；掩码中的填充位置为 0，保留的有效位置为 1。不要把批量返回值误当成 Transformers 的字典接口。

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

本文明确以 Tokenizers 0.20.3 的 Python API 为示例基准，不将它宣称为最新版。官方新版本页面与该版本的绑定接口存在差异，已有项目应按安装版本选择文档。示例只构造本地小词表，不下载模型、不接收外部文件；代码未在本文环境执行。

最小示例：每条 Encoding 分别取字段

下面把“ship”与“ship parcel today”组成文本批次，通过一个自建 WordLevel 分词器说明返回对象。词表和切分规则仅服务于接口演示，不能替换预训练模型自带的 tokenizer。

from tokenizers import Tokenizer
from tokenizers.models import WordLevel
from tokenizers.pre_tokenizers import Whitespace

# 固定的小词表只演示字段结构，编号与任何预训练模型无关。
vocab = {"[UNK]": 0, "[PAD]": 1, "ship": 2, "parcel": 3, "today": 4}
tokenizer = Tokenizer(WordLevel(vocab=vocab, unk_token="[UNK]"))
tokenizer.pre_tokenizer = Whitespace()

# 明确采用右侧填充；固定长度便于观察短句中的填充位置。
tokenizer.enable_truncation(max_length=8)
tokenizer.enable_padding(
    direction="right", pad_id=1, pad_token="[PAD]", length=8
)
texts = ["ship", "ship parcel today"]
encodings = tokenizer.encode_batch(texts)

# 每条 Encoding 都有相互对齐的字段，整理成下游常用的批次字典。
batch = {
    "input_ids": [item.ids for item in encodings],
    "attention_mask": [item.attention_mask for item in encodings],
}

代码里的 Encoding 列表与输入顺序对应，单条 Encoding 的 ids 和 attention_mask 按位置对应。本例按固定长度 8 对齐；根据给出的词表和空白切分，短句“ship”的有效位置只有开头一项，其余是填充。这是代码语义说明，不是粘贴的实际运行输出。

如果改成真实模型，必须使用它配套的词表、预处理与特殊标记规则，并使用正确 pad_id。不要为了得到矩形数组，随意把某个常见数字当作填充编号。

分清 attention_mask 与其他标记

没有填充时，掩码都为 1 可能完全正常。添加了模型需要的特殊 token，也不能据此把它的注意力掩码自动改成 0。语言模型内部的因果约束、训练标签是否计算损失，以及这里的填充标记，是不同层面的控制。

代码最终构造的是 Python 嵌套列表。若下游框架需要张量，在完成对齐后再按框架接口转换；不要把“拿到了 mask”误认为已经完成设备放置、数据类型选择或模型输入准备。

把长度控制和填充配置放在同一边界内

批量接口的主要工程风险是资源放大：一条极长输入会增加分词工作量，动态 padding 又可能把同批短句都补到长句长度。因此在进入 encode_batch 前，分别限制批大小上限和原文长度上限，再由 token 上限控制编码长度。

# 请求入口的业务限制示例，应按实际容量调整。
MAX_BATCH = 32
MAX_TEXT_CHARS = 4000

def encode_request(texts, configured_tokenizer):
    # 先限制条数和原文长度，避免把无限输入交给分词器。
    if not isinstance(texts, list) or not 1  MAX_TEXT_CHARS for text in texts):
        raise ValueError("文本类型或长度不符合约定")
    # 分词器应已固定 truncation 和 padding 配置，处理期间不要并发修改。
    rows = configured_tokenizer.encode_batch(texts)
    return {
        "input_ids": [row.ids for row in rows],
        "attention_mask": [row.attention_mask for row in rows],
    }

字符数限制不等于 token 数限制，也不能替代请求体字节数限制；它只是额外的业务防线。上例阈值为演示值，不是容量承诺。固定 padding 长度时应配合相同 token 上限的截断；只设置 padding 不是截断长文本的办法。

若删除固定 length，该版本可按批内最长序列动态填充。它减少短批次浪费，但会使不同批次的宽度变化。需要稳定形状的下游与允许动态形状的下游，应明确采用不同约定，而不是临时修改共享实例。

保留哪些记录，才能解释异常批次

接入服务时，可记录分词器版本、配置标识、输入条数、各行编码长度与截断策略。不把原始用户文本、完整 token 序列或可能包含敏感内容的请求直接写进常规日志。遇到模型异常，先看批次约定是否一致，再在受控样本上复现。

交给模型前，应用可以检查每行 ids 与 attention_mask 等长，固定长度模式下各行宽度是否一致；空批次如何处理、超长文本是拒绝还是截断，都应作为接口约定。本例在入口拒绝空批次，不替调用方猜测意图。这些是供读者实现的应用约束，本文没有运行测试或生成测试报告。

为什么返回值没有 input_ids 键？

原生 Tokenizers 的 encode_batch 返回 Encoding 列表；示例中的 input_ids 是我们整理时起的字典键。不要直接照搬 Transformers tokenizer 调用的返回形式。

attention_mask 能自动过滤提示词攻击吗？

不能。它标记编码位置，不判断文本内容是否可信，也不替代模型应用的权限和内容处理规则。

真实模型没有 PAD 怎么办？

按模型和推理框架文档决定填充策略；新增词表项可能还涉及模型嵌入大小与配置同步。不要只修改 Tokenizers 的 pad_id 就认为模型也支持了新 token。

对应版本 Tokenizer API：https://huggingface.co/docs/tokenizers/v0.20.3/en/api/tokenizer

对应版本 Encoding API：https://huggingface.co/docs/tokenizers/v0.20.3/en/api/encoding