# 分词器

分词器负责为模型准备输入。该库包含了所有模型的分词器。大多数分词器提供两种实现：完整的 Python 实现，以及基于 Rust 库 [🤗 Tokenizers](https://github.com/huggingface/tokenizers) 的“Fast”实现。“Fast”实现支持：

1. 在批量分词时尤为显著的速度提升
2. 用于在原始字符串（字符和单词）与 token 空间之间进行映射的额外方法（例如，获取包含特定字符的 token 的索引，或获取与特定 token 对应的字符范围）。

基类 [PreTrainedTokenizer](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.PythonBackend) 和 [PreTrainedTokenizerFast](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 实现了将字符串输入编码为模型输入（见下文）的通用方法，并支持从本地文件或目录，或从库提供的预训练分词器（从 HuggingFace 的 AWS S3 仓库下载）实例化和保存 Python 及 "Fast" 分词器。它们都依赖于包含通用方法的 [PreTrainedTokenizerBase](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase)。

因此，[PreTrainedTokenizer](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.PythonBackend) 和 [PreTrainedTokenizerFast](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 实现了使用所有分词器的主要方法：

- Tokenizing （在子词标记字符串中拆分字符串）、将标记字符串转换为 ID 及反向转换，以及编码/解码（即分词并转换为整数）。
- 以独立于底层结构（BPE、SentencePiece……）的方式向词表中添加新标记。
- 管理特殊标记（如 mask、句首标记等）：添加这些标记，将它们分配给分词器的属性以便轻松访问，并确保它们在分词过程中不会被拆分。

[decode()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) 接受单个 id 序列或一批序列。[batch_decode()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.batch_decode) 为保持向后兼容而保留，并期望接收一个批次：空批次返回空列表，传入单个序列已被弃用，请改用 `decode`。

[BatchEncoding](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.BatchEncoding) 保存了 [PreTrainedTokenizerBase](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) 编码方法（`__call__`、`encode_plus` 和 `batch_encode_plus`）的输出，并派生自 Python 字典。当分词器是纯 Python 分词器时，该类表现得与标准 Python 字典完全一致，并保存这些方法计算出的各种模型输入（`input_ids`、`attention_mask` 等）。当分词器是“Fast”分词器（即由 HuggingFace [tokenizers library](https://github.com/huggingface/tokenizers) 提供支持）时，该类还额外提供了一些高级对齐方法，可用于在原始字符串（字符和单词）与 token 空间之间进行映射（例如，获取包含某个给定字符的 token 的索引，或获取某个给定 token 对应的字符范围）。

## 多模态分词器

除此之外，每个分词器都可以是“多模态”分词器，这意味着分词器会将所有相关的特殊标记作为分词器属性保存，以便更轻松地访问。例如，如果分词器是从 LLaVA 等视觉语言模型加载的，你就可以通过访问 `tokenizer.image_token_id` 来获取用作占位符的特殊图像标记。

要为任意类型的分词器启用额外的特殊标记，您需要添加以下代码行并保存分词器。额外的特殊标记不一定与模态相关，可以是模型经常需要访问的任何内容。在下面的代码中，位于 `output_dir` 的分词器将可以直接访问三个额外的特殊标记。

```python
vision_tokenizer = AutoTokenizer.from_pretrained(
    "llava-hf/llava-1.5-7b-hf",
    extra_special_tokens={"image_token": "<image>", "boi_token": "<image_start>", "eoi_token": "<image_end>"}
)
print(vision_tokenizer.image_token, vision_tokenizer.image_token_id)
("<image>", 32000)
```

## PreTrainedTokenizer[[transformers.PythonBackend]]

#### transformers.PythonBackend[[transformers.PythonBackend]]

```python
transformers.PythonBackend(**kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L405)

**参数：**

model_max_length (`int`，*可选*)：输入到 transformer 模型的最大长度（以 token 数量计）。当使用 [from_pretrained()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.from_pretrained) 加载分词器时，此值将设置为 `max_model_input_sizes` 中为关联模型存储的值（见上文）。如果未提供值，则默认为 VERY_LARGE_INTEGER（`int(1e30)`）。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

truncation_side (`str`, *可选*) : 模型应应用截断的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

chat_template (`str`, *可选*) : 一个 Jinja 模板字符串，用于格式化聊天消息列表。完整说明请参阅 https://huggingface.co/docs/transformers/chat_templating。

model_input_names (`list[string]`, *可选*) : 模型前向传播接受的输入列表（例如 `"token_type_ids"` 或 `"attention_mask"`）。默认值取自同名的类属性。

bos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子开头的特殊标记。

eos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子结束的特殊标记。

unk_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示词表外（out-of-vocabulary）token 的特殊 token。

sep_token (`str` 或 `tokenizers.AddedToken`，*可选*)：用于分隔同一输入中两个不同句子的特殊标记（例如 BERT 使用）。

pad_token (`str` 或 `tokenizers.AddedToken`，*可选*)：一种特殊标记，用于在批处理时将标记数组调整为相同大小。随后，注意力机制或损失计算会忽略该标记。

cls_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示输入类别的特殊标记（例如 BERT 使用）。

mask_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示掩码 token 的特殊 token（用于掩码语言建模预训练目标，例如 BERT）。将关联到 `self.mask_token` 和 `self.mask_token_id`。

extra_special_tokens （`str` 或 `tokenizers.AddedToken` 的列表，*可选*）：一组额外的模型特定特殊标记。在此处添加它们，以确保在将 `skip_special_tokens` 设置为 True 进行解码时跳过这些标记。如果它们不属于词表的一部分，则会被追加到词表的末尾。

split_special_tokens (`bool`，*可选*，默认为 `False`)：在分词过程中是否应拆分特殊标记。传入该参数会影响分词器的内部状态。默认行为是不拆分特殊标记。这意味着，如果 `<s>` 是 `bos_token`，则 `tokenizer.tokenize("<s>") = ['<s>`]。否则，如果 `split_special_tokens=True`，则 `tokenizer.tokenize("<s>")` 将返回 `['<','s', '>']`。

所有慢速分词器的基类。

继承自 [PreTrainedTokenizerBase](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase)。

处理分词和特殊标记的所有共享方法，以及下载/缓存/加载预训练分词器以及向词表中添加标记的方法。

该类还以统一的方式在所有分词器之上包含新增的 token，因此我们无需处理各种底层字典结构（BPE、sentencepiece 等）特有的词表扩展方法。

类属性（由派生类重写）

- **vocab_files_names** (`dict[str, str]`) -- 一个字典，其键为模型所需的每个词汇文件在 `__init__` 中的关键字参数名，对应的值为用于保存该文件的文件名（字符串）。
- **pretrained_vocab_files_map** (`dict[str, dict[str, str]]`) -- 一个字典的字典，其中顶层键是模型所需的每个词汇文件在 `__init__` 中的关键字参数名，底层键是预训练模型的 `short-cut-names`，对应的值为关联的预训练词汇文件的 `url`。
- **model_input_names** (`list[str]`) -- 模型前向传播中预期的输入列表。
- **padding_side** (`str`) -- 模型应应用填充的一侧的默认值。应为 `'right'` 或 `'left'`。
- **truncation_side** (`str`) -- 模型应应用截断的一侧的默认值。应为 `'right'` 或 `'left'`。

#### __调用__[[transformers.PythonBackend.__call__]]

```python
__call__(text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, add_special_tokens: bool = True, padding: bool | str | PaddingStrategy = False, truncation: bool | str | TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, is_split_into_words: bool = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, tokenizer_kwargs: dict[str, Any] | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2458)

**参数：**

text (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_pair (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_target (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码为目标文本的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）的形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_pair_target (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码为目标文本的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）的形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

tokenizer_kwargs (`dict[str, Any]`, *可选*) : 传递给 tokenizer 的额外 kwargs。这些 kwargs 将与显式参数及其他 kwargs 合并，其中显式参数具有更高的优先级。

add_special_tokens (`bool`，*可选*，默认为 `True`)：在编码序列时是否添加特殊标记。此操作将使用底层的 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 函数，该函数定义了哪些标记会自动添加到输入 ID 中。如果您希望自动添加 `bos` 或 `eos` 标记，此功能非常有用。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。 - `'max_length'`：填充至由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充至模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认值）：不进行填充（即，可以输出包含不同长度序列的批次）。

truncation (`bool`、`str` 或 [TruncationStrategy](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)，*optional*，默认为 `False`)：启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认）：不截断（即，可以输出序列长度大于模型最大允许输入大小的批次）。

max_length (`int`, *可选*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

stride (`int`，*可选*，默认为 0)：如果与 `max_length` 一起设置为某个数值，则当 `return_overflowing_tokens=True` 时，返回的溢出 token 将包含来自截断序列末尾的若干 token，以在截断序列和溢出序列之间提供一定的重叠。该参数的值定义了重叠 token 的数量。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。需要启用 `padding`。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

return_token_type_ids (`bool`，*可选*)：是否返回 token type ID。如果保持默认值，则根据特定 tokenizer 的默认设置返回 token type ID，该设置由 `return_outputs` 属性定义。[什么是 token type ID？](../glossary#token-type-ids)

return_attention_mask (`bool`，*可选*)：是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由 `return_outputs` 属性定义。[什么是注意力掩码？](../glossary#attention-mask)

return_overflowing_tokens (`bool`，*可选*，默认为 `False`)：是否返回溢出的 token 序列。如果提供了输入 id 的序列对（或序列对的批次），并且 `truncation_strategy = longest_first` 或 `True`，则会引发错误，而不是返回溢出的 token。

return_special_tokens_mask (`bool`，*可选*，默认为 `False`)：是否返回特殊标记掩码信息。

return_offsets_mapping (`bool`，*可选*，默认为 `False`)：是否返回每个 token 的 `(char_start, char_end)`。此功能仅适用于继承自 [PreTrainedTokenizerFast](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的快速分词器；如果使用 Python 分词器，此方法将抛出 `NotImplementedError`。

return_length (`bool`，*可选*，默认为 `False`)：是否返回编码后输入的长度。

verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。

- ****kwargs** : 传递给 `self.tokenize()` 方法

**返回：** [BatchEncoding](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.BatchEncoding)

一个包含以下字段的 [BatchEncoding](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.BatchEncoding)：

- **input_ids** -- 输入模型的 token id 列表。

  [什么是输入 ID？](../glossary#input-ids)

- **token_type_ids** -- 要输入模型的 token 类型 ID 列表（当 `return_token_type_ids=True` 或 `self.model_input_names` 中包含 *"token_type_ids"* 时）。

  [什么是 token type ID？](../glossary#token-type-ids)

- **attention_mask** -- 指定模型应关注哪些 token 的索引列表（当 `return_attention_mask=True` 或 *"attention_mask"* 位于 `self.model_input_names` 中时）。

  [什么是注意力掩码？](../glossary#attention-mask)

- **overflowing_tokens** -- 溢出 token 序列的列表（当指定了 `max_length` 且 `return_overflowing_tokens=True` 时）。
- **num_truncated_tokens** -- 被截断的 token 数量（当指定了 `max_length` 且 `return_overflowing_tokens=True` 时）。
- **special_tokens_mask** -- 由 0 和 1 组成的列表，其中 1 表示添加的特殊标记，0 表示常规序列标记（当 `add_special_tokens=True` 且 `return_special_tokens_mask=True` 时）。
- **length** -- 输入的长度（当 `return_length=True` 时）

用于对一条或多条序列，或一对或多对序列进行分词并准备输入模型的主要方法。

#### add_tokens[[transformers.PythonBackend.add_tokens]]

```python
add_tokens(new_tokens: str | AddedToken | Sequence[str | AddedToken], special_tokens: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L1227)

**参数：**

new_tokens (`str`、`tokenizers.AddedToken` 或 *str* 或 `tokenizers.AddedToken` 的序列)：仅当词元尚不存在于词汇表中时，才会将其添加。 `tokenizers.AddedToken` 用于封装字符串词元，以便自定义其行为：例如该词元是否仅匹配单个单词、是否应去除左侧所有潜在空白、是否应去除右侧所有潜在空白等。

special_tokens (`bool`，*可选*，默认为 `False`)：指定该 token 是否为特殊 token。这主要会改变归一化行为。有关 `tokenizers.AddedToken` 的详细信息，请参阅 HuggingFace tokenizers 库。

**返回：** `int`

添加到词汇表中的标记数量。

#TODO 从此处移除！PreTrainedTokenizerBase 应当与 AddedToken 无关。

添加一组新标记。如果这些新标记不在词汇表中，它们将被追加到末尾。因此，添加的标记与分词算法词汇表中的标记不会以相同的方式处理。

使用 `prepend_scheme="always"`（例如 NLLB）的 `Metaspace` 预分词器，会在添加的 token 之后的文本前添加 `"▁"`。执行 `tokenizer.add_tokens(["abcd"])` 后，`"abcdgym"` 会被分词为 `["abcd", "▁gym"]`，并解码为 `"abcd gym"`。如果添加的 token 可能出现在单词内部，请切换预分词器

改为 `prepend_scheme="first"`，这样只有输入的开头会被添加前缀：

```python
from tokenizers import pre_tokenizers

pre_tokenizer = tokenizer.backend_tokenizer.pre_tokenizer
tokenizer.backend_tokenizer.pre_tokenizer = pre_tokenizers.Metaspace(
    replacement=pre_tokenizer.replacement, prepend_scheme="first", split=pre_tokenizer.split
)
```

示例：

```python
# Let's see how to increase the vocabulary of Bert model and tokenizer
tokenizer = BertTokenizerFast.from_pretrained("google-bert/bert-base-uncased")
model = BertModel.from_pretrained("google-bert/bert-base-uncased")

num_added_toks = tokenizer.add_tokens(["new_tok1", "my_new-tok2"])
print("We have added", num_added_toks, "tokens")
# Notice: resize_token_embeddings expect to receive the full size of the new vocabulary, i.e., the length of the tokenizer.
model.resize_token_embeddings(len(tokenizer))
```

#### add_special_tokens[[transformers.PythonBackend.add_special_tokens]]

```python
add_special_tokens(special_tokens_dict: dict[str, str | AddedToken | Sequence[str | AddedToken]], replace_extra_special_tokens = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L1122)

**参数：**

special_tokens_dict （*str* 到 *str*、`tokenizers.AddedToken` 或 `Sequence[Union[str, AddedToken]]` 的字典）：键应为预定义特殊属性列表中的项：[`bos_token`、`eos_token`、`unk_token`、`sep_token`、`pad_token`、`cls_token`、`mask_token`、`extra_special_tokens`]。仅当这些标记尚未存在于词汇表中时才会被添加（通过检查分词器是否为其分配了 `unk_token` 的索引来测试）。

replace_extra_special_tokens (`bool`，*可选*，默认为 `True`)：如果为 `True`，现有的额外特殊标记列表将被 `special_tokens_dict` 中提供的列表替换。否则，`extra_special_tokens` 将被扩展。在前一种情况下，这些标记不会从分词器的完整词汇表中移除，只是被标记为非特殊标记。请记住，这仅影响解码期间跳过哪些标记，而不影响 `added_tokens_encoder` 和 `added_tokens_decoder`。这意味着之前的 `extra_special_tokens` 仍然是已添加的标记，模型不会对其进行拆分。

**返回：** `int`

添加到词汇表中的标记数量。

将特殊标记（eos、pad、cls 等）的字典添加到编码器中，并将其链接到类属性。如果特殊标记不在词汇表中，则将其添加到词汇表中（索引从当前词汇表的最后一个索引开始）。

在向词表中添加新标记时，您应确保同时调整模型的标记嵌入矩阵大小，使其嵌入矩阵与分词器相匹配。

为此，请使用 [resize_token_embeddings()](/docs/transformers/v5.24.0/zh/main_classes/model#transformers.PreTrainedModel.resize_token_embeddings) 方法。

使用 `add_special_tokens` 可确保您的特殊标记能以多种方式使用：

- 在解码时，可以通过设置 `skip_special_tokens = True` 来跳过特殊标记。
- 特殊标记由分词器仔细处理（它们永远不会被拆分），与 `AddedTokens` 类似。
- 您可以轻松使用分词器类的属性（例如 `tokenizer.cls_token`）来引用特殊标记。这使得开发与模型无关的训练和微调脚本变得十分便捷。

在可能的情况下，所提供的预训练模型已经注册了特殊标记（例如 [BertTokenizer](/docs/transformers/v5.24.0/zh/model_doc/lxmert#transformers.BertTokenizer) 的 `cls_token` 已注册为 `'[CLS]'`，XLM 的也已注册为 `'</s>'`）。

示例：

```python
# Let's see how to add a new classification token to GPT-2
tokenizer = GPT2Tokenizer.from_pretrained("openai-community/gpt2")
model = GPT2Model.from_pretrained("openai-community/gpt2")

special_tokens_dict = {"cls_token": "<CLS>"}

num_added_toks = tokenizer.add_special_tokens(special_tokens_dict)
print("We have added", num_added_toks, "tokens")
# Notice: resize_token_embeddings expect to receive the full size of the new vocabulary, i.e., the length of the tokenizer.
model.resize_token_embeddings(len(tokenizer))

assert tokenizer.cls_token == "<CLS>"
```

#### apply_chat_template[[transformers.PythonBackend.apply_chat_template]]

```python
apply_chat_template(conversation: list[dict[str, str]] | list[list[dict[str, str]]], tools: list[dict | Callable] | None = None, documents: list[dict[str, str]] | None = None, chat_template: str | None = None, add_generation_prompt: bool = False, continue_final_message: bool | str = False, tokenize: bool = True, sanitize_control_tokens: bool = False, padding: bool | str | PaddingStrategy = False, truncation: bool = False, max_length: int | None = None, return_tensors: str | TensorType | None = None, return_dict: bool = True, return_assistant_tokens_mask: bool = False, tokenizer_kwargs: dict[str, Any] | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L3040)

**参数：**

conversation (Union[list[dict[str, str]], list[list[dict[str, str]]]]) : 一个包含 "role" 和 "content" 键的字典列表，表示迄今为止的聊天历史记录。

tools (`list[Union[Dict, Callable]]`，*可选*)：一个工具（可调用函数）列表，模型可以访问这些工具。如果模板不支持函数调用，此参数将不起作用。每个工具应以 JSON Schema 的形式传入，提供工具的名称、描述和参数类型。有关更多信息，请参阅我们的[工具使用指南](https://huggingface.co/docs/transformers/en/chat_extras#passing-tools)。

documents (`list[dict[str, str]]`，*可选*)：一个字典列表，表示文档。如果模型正在执行 RAG（检索增强生成），这些文档将对模型可访问。如果模板不支持 RAG，此参数将不起作用。我们建议每个文档应为一个包含 "title" 和 "text" 键的字典。

chat_template (`str`，*可选*)：用于此转换的 Jinja 模板。通常无需为此参数传入任何值，因为默认会使用模型的模板。

add_generation_prompt (bool, *optional*) : 如果设置了此参数，将在格式化输出末尾追加一个包含指示助手消息起始的 token 的提示。当您希望从模型生成回复时，此功能非常有用。请注意，此参数会传递给聊天模板，因此模板必须支持该参数，此参数才能生效。

continue_final_message (bool 或 str，*可选*) : 如果设置了此参数，聊天将被格式化，使得聊天中的最后一条消息是开放式的，不包含任何 EOS token。模型将继续该消息，而不是开始一条新消息。这允许你为模型的响应“预填充”部分内容。如果传入字符串，它将用作要继续的字段的关键字（例如 "reasoning_content"）。不能与 `add_generation_prompt` 同时使用。

tokenize (`bool`，默认为 `True`)：是否对输出进行分词。如果为 `False`，输出将是一个字符串。

sanitize_control_tokens (`bool`，默认为 `False`) : 如果设置为 True，则出现在消息、工具、文档或作为 `**kwargs` 传递的模板变量中的控制标记将被编码为普通文本，因此只有聊天模板本身写入的控制标记才会被编码为标记。控制标记包括分词器的特殊标记，以及 `tokenizer.chat_control_tokens` 中的已添加标记。如果未设置该变量，则从聊天模板文本和字符串字面量中出现的已添加标记推断控制标记。仅对整个控制标记进行清理，因此如果模板将输入中的字符串拼接成控制标记（例如 `'<|' + message['role'] + '|>'`），则必须单独验证这些字符串。字典键也不会被清理。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：选择一种策略来填充返回的序列（根据模型的填充方向和填充索引），可选策略如下： - `True` 或 `'longest'`：填充到批次中最长的序列（如果只提供了单个序列，则不进行填充）。 - `'max_length'`：填充到由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认）：不进行填充（即可以输出包含不同长度序列的批次）。

truncation (`bool`，默认为 `False`)：是否在最大长度处截断序列。如果 tokenize 为 `False`，则此参数无效。

max_length (`int`, *可选*) : 用于填充或截断的最大长度（以 token 计）。如果 tokenize 为 `False`，则此参数无效。如果未指定，将使用分词器的 `max_length` 属性作为默认值。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。如果 tokenize 为 `False`，则无效。可接受的值为：- `'pt'`：返回 PyTorch `torch.Tensor` 对象。- `'np'`：返回 NumPy `np.ndarray` 对象。

return_dict (`bool`，默认为 `True`)：是否返回包含命名输出的字典。如果 tokenize 为 `False`，则此参数无效。

tokenizer_kwargs (`dict[str : Any]`，*可选*)：传递给 tokenizer 的额外 kwargs。

return_assistant_tokens_mask (`bool`，默认为 `False`)：是否返回助手生成 token 的掩码。对于助手生成的 token，掩码中对应位置为 1；对于用户和系统 token，掩码中对应位置为 0。此功能仅适用于通过 `{% generation %}` 关键字支持该功能的聊天模板。

- ****kwargs** : 传递给模板渲染器的额外 kwargs。聊天模板可以访问这些参数。

**返回：** `Union[list[int], Dict]`

一个表示迄今为止已分词对话的 token id 列表，包括控制 token。此输出可直接传递给模型，或通过 `generate()` 等方法传递。如果设置了 `return_dict`，则返回一个包含分词器输出的字典。

将包含 `"role"` 和 `"content"` 键的字典列表转换为 token id 列表。此方法旨在与聊天模型配合使用，它会读取分词器的 chat_template 属性，以确定转换时所使用的格式和控制 token。

#### batch_decode[[transformers.PythonBackend.batch_decode]]

```python
batch_decode(sequences: list[int] | list[list[int]] | np.ndarray | torch.Tensor, skip_special_tokens: bool = False, clean_up_tokenization_spaces: bool | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2942)

**参数：**

sequences (`Union[list[int], list[list[int]], np.ndarray, torch.Tensor]`) : 标记化输入 ID 的列表。可通过 `__call__` 方法获取。

skip_special_tokens (`bool`，*可选*，默认为 `False`)：是否在解码过程中移除特殊标记。

clean_up_tokenization_spaces (`bool`，*可选*)：是否清理分词空格。如果为 `None`，则默认为 `self.clean_up_tokenization_spaces`。

kwargs （额外的关键字参数，*可选*）：将传递给底层模型特定的解码方法。

**返回：** `list[str]`

解码后的句子列表。

通过调用 decode，将 token id 的列表的列表转换为字符串列表。

此方法是为了向后兼容而提供的。`decode` 方法现在原生支持批量输入，因此您可以直接使用 `decode` 而无需使用 `batch_decode`。

#### decode[[transformers.PythonBackend.decode]]

```python
decode(token_ids: int | list[int] | list[list[int]] | np.ndarray | torch.Tensor, skip_special_tokens: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2894)

**参数：**

token_ids (`Union[int, list[int], list[list[int]], np.ndarray, torch.Tensor]`) : 单个序列或一批（序列列表）的标记化输入 ID。可通过 `__call__` 方法获取。

skip_special_tokens (`bool`，*可选*，默认为 `False`)：是否在解码过程中移除特殊标记。

kwargs （额外的关键字参数，*可选*）：将传递给底层模型特定的解码方法。

**返回：** `Union[str, list[str]]`

单个序列的解码字符串，或一批序列的解码字符串列表。

使用分词器和词汇表，将 id 序列转换为字符串，或将序列列表转换为字符串列表，并可选择移除特殊标记和清理分词空格。

类似于执行 `self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))`。

#### encode[[transformers.PythonBackend.encode]]

```python
encode(text: TextInput | PreTokenizedInput | EncodedInput, text_pair: TextInput | PreTokenizedInput | EncodedInput | None = None, add_special_tokens: bool = True, padding: bool | str | PaddingStrategy = False, truncation: bool | str | TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, padding_side: str | None = None, return_tensors: str | TensorType | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2272)

**参数：**

text (`str`、`list[str]` 或 `list[int]`)：要编码的第一个序列。它可以是一个字符串、一个字符串列表（使用 `tokenize` 方法分词后的字符串）或一个整数列表（使用 `convert_tokens_to_ids` 方法转换后的 token ID）。

text_pair (`str`、`list[str]` 或 `list[int]`，*可选*)：要编码的可选第二个序列。它可以是一个字符串、一个字符串列表（使用 `tokenize` 方法分词后的字符串）或一个整数列表（使用 `convert_tokens_to_ids` 方法得到的分词字符串 ID）。

add_special_tokens (`bool`，*可选*，默认为 `True`)：在编码序列时是否添加特殊标记。此操作将使用底层的 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 函数，该函数定义了哪些标记会自动添加到输入 ID 中。如果您希望自动添加 `bos` 或 `eos` 标记，此功能非常有用。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。 - `'max_length'`：填充至由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充至模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认值）：不进行填充（即，可以输出包含不同长度序列的批次）。

truncation (`bool`、`str` 或 [TruncationStrategy](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)，*optional*，默认为 `False`)：启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认）：不截断（即，可以输出序列长度大于模型最大允许输入大小的批次）。

max_length (`int`, *可选*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

stride (`int`，*可选*，默认为 0)：如果与 `max_length` 一起设置为某个数值，则当 `return_overflowing_tokens=True` 时，返回的溢出 token 将包含来自截断序列末尾的若干 token，以在截断序列和溢出序列之间提供一定的重叠。该参数的值定义了重叠 token 的数量。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。需要启用 `padding`。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

- ****kwargs** : 传递给 `.tokenize()` 方法。

**返回：** `list[int]`、`torch.Tensor` 或 `np.ndarray`

文本的标记化 ID。

使用分词器和词汇表将字符串转换为 id（整数）序列。

与执行 `self.convert_tokens_to_ids(self.tokenize(text))` 相同。

#### push_to_hub[[transformers.PythonBackend.push_to_hub]]

```python
push_to_hub(repo_id: str, commit_message: str | None = None, commit_description: str | None = None, private: bool | None = None, token: bool | str | None = None, revision: str | None = None, create_pr: bool = False, max_shard_size: int | str | None = '50GB', tags: list[str] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/utils/hub.py#L822)

**参数：**

repo_id (`str`) : 要推送分词器的仓库名称。推送到特定组织时，应包含该组织的名称。

commit_message (`str`, *可选*) : 推送时提交的说明信息。默认值为 `"Upload tokenizer"`。

commit_description (`str`, *可选*) : 将创建的提交的描述

private (`bool`，*可选*)：是否将仓库设为私有。如果为 `None`（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。

token (`bool` 或 `str`，*可选*) : 用于远程文件的 HTTP bearer 授权令牌。如果为 `True`（默认值），将使用运行 `hf auth login` 时生成的令牌（存储在 `~/.huggingface` 中）。

revision (`str`, *可选*) : 推送上传文件的目标分支。

create_pr (`bool`，*可选*，默认为 `False`)：是否使用上传的文件创建 PR，还是直接提交。

max_shard_size (`int` 或 `str`，*可选*，默认为 `"50GB"`)：仅适用于模型。在分片之前，检查点（checkpoint）的最大大小。分片后的每个检查点大小都将小于此值。如果以字符串形式表示，则必须为数字后跟单位（例如 `"5MB"`）。

tags (`list[str]`，*可选*)：要推送到 Hub 的标签列表。

将分词器文件上传到 🤗 Model Hub。

示例：

```python
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-cased")

# Push the tokenizer to your namespace with the name "my-finetuned-bert".
tokenizer.push_to_hub("my-finetuned-bert")

# Push the tokenizer to an organization with the name "my-finetuned-bert".
tokenizer.push_to_hub("huggingface/my-finetuned-bert")
```

#### build_inputs_with_special_tokens[[transformers.PythonBackend.build_inputs_with_special_tokens]]

```python
build_inputs_with_special_tokens(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L872)

**参数：**

token_ids_0 (`list[int]`) : 将添加特殊标记的 ID 列表。

token_ids_1 (`list[int]`, *可选*) : 用于序列对的可选第二个 ID 列表。

**返回：** `list[int]`

包含相应特殊标记的输入 ID 列表。

通过添加特殊标记，从单个序列或序列对构建模型输入。

该方法会根据分词器的 `special_tokens_pattern` 动态构建输入：
- `"none"`：无特殊标记
- `"cls_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] seq1 [SEP]
- `"eos"`：seq0 [EOS] 或 seq0 [EOS] seq1 [EOS]
- `"bos"`：[BOS] seq0 或 [BOS] seq0 [BOS] seq1
- `"bos_eos"`：[BOS] seq0 [EOS] 或 [BOS] seq0 [EOS] seq1 [EOS]
- `"cls_double_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] [SEP] seq1 [SEP]
- `"prefix_suffix"`：`<prefix_tokens> seq0 [seq1] <suffix_tokens>`（自定义前缀/后缀，存储在分词器中）

#### create_token_type_ids_from_sequences[[transformers.PythonBackend.create_token_type_ids_from_sequences]]

```python
create_token_type_ids_from_sequences(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1305)

**参数：**

token_ids_0 (`list[int]`) : ID 列表。

token_ids_1 (`list[int]`, *可选*) : 用于序列对的可选第二个 ID 列表。

**返回：** `list[int]`

根据配置的模式生成的 Token 类型 ID。

创建一个掩码，该掩码由传入的两个序列生成，用于序列对分类任务。

此方法根据分词器的配置属性动态构建 token 类型 ID：
- `token_type_ids_pattern`：要使用的模式（"all_zeros" 或 "bert_style"）
- `token_type_ids_include_special_tokens`：在长度计算中是否考虑特殊标记

示例：
```python
# All zeros pattern (default, used by RoBERTa, BART, etc.)
tokenizer.token_type_ids_pattern = "all_zeros"
# Returns: [0, 0, 0, ...] for both sequences

# BERT-style pattern (first sequence gets 0s, second gets 1s)
tokenizer.token_type_ids_pattern = "bert_style"
# Returns: [0, 0, 0, ..., 1, 1, 1, ...] for sequence pairs
```

#### get_added_vocab[[transformers.PythonBackend.get_added_vocab]]

```python
get_added_vocab()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L493)

**返回：** `dict[str, int]`

添加的标记。

以字典形式返回词表中新增的 token 及其对应的索引。由于目前即使 token 已存在于词表中，我们仍会将其添加，因此结果可能与快速调用不同。这一点应当改进。

#### get_special_tokens_mask[[transformers.PythonBackend.get_special_tokens_mask]]

```python
get_special_tokens_mask(token_ids_0: list, token_ids_1: list | None = None, already_has_special_tokens: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L976)

**参数：**

token_ids_0 (`list[int]`) : 第一个序列的 id 列表。

token_ids_1 (`list[int]`, *可选*) : 第二个序列的 id 列表。

already_has_special_tokens (`bool`，*可选*，默认为 `False`)：标记列表是否已使用模型的特殊标记进行格式化。

**返回：** 一个包含 [0, 1] 范围内整数的列表

1 表示特殊标记，0 表示序列标记。

从未添加特殊标记的标记列表中获取序列 ID。当使用分词器的 `prepare_for_model` 或 `encode_plus` 方法添加特殊标记时，会调用此方法。

此方法会根据分词器的 `special_tokens_pattern` 动态构建特殊标记掩码：
- `"none"`：不使用特殊标记（默认值，返回全 0）
- `"cls_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] seq1 [SEP]
- `"eos"`：seq0 [EOS] 或 seq0 [EOS] seq1 [EOS]
- `"bos"`：[BOS] seq0 或 [BOS] seq0 [BOS] seq1
- `"bos_eos"`：[BOS] seq0 [EOS] 或 [BOS] seq0 [EOS] seq1 [EOS]
- `"cls_double_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] [SEP] seq1 [SEP]
- `"prefix_suffix"`: `<prefix_tokens> seq0 [seq1] <suffix_tokens>`

#### num_special_tokens_to_add[[transformers.PythonBackend.num_special_tokens_to_add]]

```python
num_special_tokens_to_add(pair: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L607)

**参数：**

pair (`bool`，*可选*，默认为 `False`)：在序列对或单个序列的情况下，是否应计算所添加的 token 数量。

**返回：** `int`

添加到序列中的特殊标记数量。

在编码包含特殊标记的序列时，返回所添加标记的数量。

这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放入训练循环中。

#### prepare_for_model[[transformers.PythonBackend.prepare_for_model]]

```python
prepare_for_model(ids: list[int], pair_ids: list[int] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = False, max_length: int | None = None, stride: int = 0, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_length: bool = False, verbose: bool = True, prepend_batch_axis: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1128)

**参数：**

ids : 第一个序列的标记化输入 ID。

pair_ids : 第二个序列的标记化输入 ID（可选）。

准备输入 ID 序列，以便模型使用。添加特殊标记，并进行截断和填充。

#### prepare_for_tokenization[[transformers.PythonBackend.prepare_for_tokenization]]

```python
prepare_for_tokenization(text: str, is_split_into_words: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L848)

**参数：**

text (`str`) : 要处理的文本。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

kwargs (`dict[str, Any]`，*可选*)：用于分词的关键词参数。

**返回：** `tuple[str, dict[str, Any]]`

准备好的文本和未使用的 kwargs。

在分词之前执行任何必要的转换。

该方法应从 `kwargs` 中弹出参数，并返回剩余的 `kwargs`。我们还会在编码流程结束时检查 `kwargs`，以确保所有参数都已被使用。

#### save_vocabulary[[transformers.PythonBackend.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1369)

**参数：**

save_directory (`str`) : 用于保存词汇表的目录。

filename_prefix (`str`, *可选*) : 一个可选的前缀，用于添加到保存文件的名称中。

**返回：** `tuple[str, ...]`

已保存文件的路径，如果没有保存任何文件，则为空元组。

用于常见词汇表保存模式的默认实现。将 self.encoder/self.vocab 保存为 JSON，可选地将 self.bpe_ranks 作为合并规则一并保存。如果不存在词汇表，则返回空元组。

如果分词器需要自定义保存逻辑（例如 SentencePiece 模型、多个词汇文件或特殊文件格式），请重写此方法。

#### tokenize[[transformers.PythonBackend.tokenize]]

```python
tokenize(text: str, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L630)

**参数：**

text : 要编码的序列。

- ****kwargs** : 传递给模型特定的 `prepare_for_tokenization` 预处理方法。

**返回值：**

令牌列表。

使用分词器将字符串转换为标记序列。

#### truncate_sequences[[transformers.PythonBackend.truncate_sequences]]

```python
truncate_sequences(ids: list[int], pair_ids: list[int] | None = None, num_tokens_to_remove: int = 0, truncation_strategy: str | transformers.tokenization_utils_base.TruncationStrategy = 'longest_first', stride: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1238)

根据指定的策略截断序列。

## PreTrainedTokenizerFast[[transformers.TokenizersBackend]]

[PreTrainedTokenizerFast](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 依赖于 [tokenizers](https://huggingface.co/docs/tokenizers) 库。从 🤗 tokenizers 库获取的分词器可以非常简单地加载到 🤗 transformers 中。请查看 [使用 🤗 tokenizers 中的分词器](../fast_tokenizers) 页面，了解具体操作方式。

#### transformers.TokenizersBackend[[transformers.TokenizersBackend]]

```python
transformers.TokenizersBackend(*args, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L87)

**参数：**

model_max_length (`int`，*可选*)：输入到 transformer 模型的最大长度（以 token 数量计）。当使用 [from_pretrained()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.from_pretrained) 加载分词器时，此值将设置为 `max_model_input_sizes` 中为关联模型存储的值（见上文）。如果未提供值，则默认为 VERY_LARGE_INTEGER（`int(1e30)`）。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

truncation_side (`str`, *可选*) : 模型应应用截断的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

chat_template (`str`, *可选*) : 一个 Jinja 模板字符串，用于格式化聊天消息列表。完整说明请参阅 https://huggingface.co/docs/transformers/chat_templating。

model_input_names (`list[string]`, *可选*) : 模型前向传播接受的输入列表（例如 `"token_type_ids"` 或 `"attention_mask"`）。默认值取自同名的类属性。

bos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子开头的特殊标记。

eos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子结束的特殊标记。

unk_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示词表外（out-of-vocabulary）token 的特殊 token。

sep_token (`str` 或 `tokenizers.AddedToken`，*可选*)：用于分隔同一输入中两个不同句子的特殊标记（例如 BERT 使用）。

pad_token (`str` 或 `tokenizers.AddedToken`，*可选*)：一种特殊标记，用于在批处理时将标记数组调整为相同大小。随后，注意力机制或损失计算会忽略该标记。

cls_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示输入类别的特殊标记（例如 BERT 使用）。

mask_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示掩码 token 的特殊 token（用于掩码语言建模预训练目标，例如 BERT）。将关联到 `self.mask_token` 和 `self.mask_token_id`。

extra_special_tokens （`str` 或 `tokenizers.AddedToken` 的列表，*可选*）：一组额外的模型特定特殊标记。在此处添加它们，以确保在将 `skip_special_tokens` 设置为 True 进行解码时跳过这些标记。如果它们不属于词表的一部分，则会被追加到词表的末尾。

split_special_tokens (`bool`，*可选*，默认为 `False`)：在分词过程中是否应拆分特殊标记。传入该参数会影响分词器的内部状态。默认行为是不拆分特殊标记。这意味着，如果 `<s>` 是 `bos_token`，则 `tokenizer.tokenize("<s>") = ['<s>`]。否则，如果 `split_special_tokens=True`，则 `tokenizer.tokenize("<s>")` 将返回 `['<','s', '>']`。

tokenizer_object (`tokenizers.Tokenizer`)：用于实例化的来自 🤗 tokenizers 的 `tokenizers.Tokenizer` 对象。有关更多信息，请参阅 [使用 🤗 tokenizers 中的分词器](../fast_tokenizers)。

tokenizer_file (`str`) : 指向本地 JSON 文件的路径，该文件表示之前序列化的来自 🤗 tokenizers 的 `tokenizers.Tokenizer` 对象。

所有快速分词器（封装 HuggingFace tokenizers 库）的基类。

继承自 [PreTrainedTokenizerBase](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase)。

处理分词和特殊标记的所有共享方法，以及用于下载/缓存/加载预训练分词器的方法，还包括向词表中添加标记的方法。

该类以统一的方式在所有分词器之上包含新增的 token，因此我们无需处理各种底层字典结构（BPE、sentencepiece 等）特有的词表扩展方法。

类属性（由派生类重写）

- **vocab_files_names** (`dict[str, str]`) -- 一个字典，其键为模型所需的每个词汇文件在 `__init__` 中的关键字参数名，对应的值为用于保存该文件的文件名（字符串）。
- **pretrained_vocab_files_map** (`dict[str, dict[str, str]]`) -- 一个字典的字典，其中顶层键是模型所需的每个词汇文件在 `__init__` 中的关键字参数名，底层键是预训练模型的 `short-cut-names`，对应的值为关联的预训练词汇文件的 `url`。
- **model_input_names** (`list[str]`) -- 模型前向传播中预期的输入列表。
- **padding_side** (`str`) -- 模型应应用填充的一侧的默认值。应为 `'right'` 或 `'left'`。
- **truncation_side** (`str`) -- 模型应应用截断的一侧的默认值。应为 `'right'` 或 `'left'`。

#### __调用__[[transformers.TokenizersBackend.__call__]]

```python
__call__(text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, add_special_tokens: bool = True, padding: bool | str | PaddingStrategy = False, truncation: bool | str | TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, is_split_into_words: bool = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, tokenizer_kwargs: dict[str, Any] | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2458)

**参数：**

text (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_pair (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_target (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码为目标文本的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）的形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_pair_target (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码为目标文本的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）的形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

tokenizer_kwargs (`dict[str, Any]`, *可选*) : 传递给 tokenizer 的额外 kwargs。这些 kwargs 将与显式参数及其他 kwargs 合并，其中显式参数具有更高的优先级。

add_special_tokens (`bool`，*可选*，默认为 `True`)：在编码序列时是否添加特殊标记。此操作将使用底层的 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 函数，该函数定义了哪些标记会自动添加到输入 ID 中。如果您希望自动添加 `bos` 或 `eos` 标记，此功能非常有用。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。 - `'max_length'`：填充至由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充至模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认值）：不进行填充（即，可以输出包含不同长度序列的批次）。

truncation (`bool`、`str` 或 [TruncationStrategy](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)，*optional*，默认为 `False`)：启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认）：不截断（即，可以输出序列长度大于模型最大允许输入大小的批次）。

max_length (`int`, *可选*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

stride (`int`，*可选*，默认为 0)：如果与 `max_length` 一起设置为某个数值，则当 `return_overflowing_tokens=True` 时，返回的溢出 token 将包含来自截断序列末尾的若干 token，以在截断序列和溢出序列之间提供一定的重叠。该参数的值定义了重叠 token 的数量。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。需要启用 `padding`。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

return_token_type_ids (`bool`，*可选*)：是否返回 token type ID。如果保持默认值，则根据特定 tokenizer 的默认设置返回 token type ID，该设置由 `return_outputs` 属性定义。[什么是 token type ID？](../glossary#token-type-ids)

return_attention_mask (`bool`，*可选*)：是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由 `return_outputs` 属性定义。[什么是注意力掩码？](../glossary#attention-mask)

return_overflowing_tokens (`bool`，*可选*，默认为 `False`)：是否返回溢出的 token 序列。如果提供了输入 id 的序列对（或序列对的批次），并且 `truncation_strategy = longest_first` 或 `True`，则会引发错误，而不是返回溢出的 token。

return_special_tokens_mask (`bool`，*可选*，默认为 `False`)：是否返回特殊标记掩码信息。

return_offsets_mapping (`bool`，*可选*，默认为 `False`)：是否返回每个 token 的 `(char_start, char_end)`。此功能仅适用于继承自 [PreTrainedTokenizerFast](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的快速分词器；如果使用 Python 分词器，此方法将抛出 `NotImplementedError`。

return_length (`bool`，*可选*，默认为 `False`)：是否返回编码后输入的长度。

verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。

- ****kwargs** : 传递给 `self.tokenize()` 方法

**返回：** [BatchEncoding](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.BatchEncoding)

一个包含以下字段的 [BatchEncoding](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.BatchEncoding)：

- **input_ids** -- 输入模型的 token id 列表。

  [什么是输入 ID？](../glossary#input-ids)

- **token_type_ids** -- 要输入模型的 token 类型 ID 列表（当 `return_token_type_ids=True` 或 `self.model_input_names` 中包含 *"token_type_ids"* 时）。

  [什么是 token type ID？](../glossary#token-type-ids)

- **attention_mask** -- 指定模型应关注哪些 token 的索引列表（当 `return_attention_mask=True` 或 *"attention_mask"* 位于 `self.model_input_names` 中时）。

  [什么是注意力掩码？](../glossary#attention-mask)

- **overflowing_tokens** -- 溢出 token 序列的列表（当指定了 `max_length` 且 `return_overflowing_tokens=True` 时）。
- **num_truncated_tokens** -- 被截断的 token 数量（当指定了 `max_length` 且 `return_overflowing_tokens=True` 时）。
- **special_tokens_mask** -- 由 0 和 1 组成的列表，其中 1 表示添加的特殊标记，0 表示常规序列标记（当 `add_special_tokens=True` 且 `return_special_tokens_mask=True` 时）。
- **length** -- 输入的长度（当 `return_length=True` 时）

用于对一条或多条序列，或一对或多对序列进行分词并准备输入模型的主要方法。

#### add_tokens[[transformers.TokenizersBackend.add_tokens]]

```python
add_tokens(new_tokens: str | AddedToken | Sequence[str | AddedToken], special_tokens: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L1227)

**参数：**

new_tokens (`str`、`tokenizers.AddedToken` 或 *str* 或 `tokenizers.AddedToken` 的序列)：仅当词元尚不存在于词汇表中时，才会将其添加。 `tokenizers.AddedToken` 用于封装字符串词元，以便自定义其行为：例如该词元是否仅匹配单个单词、是否应去除左侧所有潜在空白、是否应去除右侧所有潜在空白等。

special_tokens (`bool`，*可选*，默认为 `False`)：指定该 token 是否为特殊 token。这主要会改变归一化行为。有关 `tokenizers.AddedToken` 的详细信息，请参阅 HuggingFace tokenizers 库。

**返回：** `int`

添加到词汇表中的标记数量。

#TODO 从此处移除！PreTrainedTokenizerBase 应当与 AddedToken 无关。

添加一组新标记。如果这些新标记不在词汇表中，它们将被追加到末尾。因此，添加的标记与分词算法词汇表中的标记不会以相同的方式处理。

使用 `prepend_scheme="always"`（例如 NLLB）的 `Metaspace` 预分词器，会在添加的 token 之后的文本前添加 `"▁"`。执行 `tokenizer.add_tokens(["abcd"])` 后，`"abcdgym"` 会被分词为 `["abcd", "▁gym"]`，并解码为 `"abcd gym"`。如果添加的 token 可能出现在单词内部，请切换预分词器

改为 `prepend_scheme="first"`，这样只有输入的开头会被添加前缀：

```python
from tokenizers import pre_tokenizers

pre_tokenizer = tokenizer.backend_tokenizer.pre_tokenizer
tokenizer.backend_tokenizer.pre_tokenizer = pre_tokenizers.Metaspace(
    replacement=pre_tokenizer.replacement, prepend_scheme="first", split=pre_tokenizer.split
)
```

示例：

```python
# Let's see how to increase the vocabulary of Bert model and tokenizer
tokenizer = BertTokenizerFast.from_pretrained("google-bert/bert-base-uncased")
model = BertModel.from_pretrained("google-bert/bert-base-uncased")

num_added_toks = tokenizer.add_tokens(["new_tok1", "my_new-tok2"])
print("We have added", num_added_toks, "tokens")
# Notice: resize_token_embeddings expect to receive the full size of the new vocabulary, i.e., the length of the tokenizer.
model.resize_token_embeddings(len(tokenizer))
```

#### add_special_tokens[[transformers.TokenizersBackend.add_special_tokens]]

```python
add_special_tokens(special_tokens_dict: dict[str, str | AddedToken | Sequence[str | AddedToken]], replace_extra_special_tokens = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L1122)

**参数：**

special_tokens_dict （*str* 到 *str*、`tokenizers.AddedToken` 或 `Sequence[Union[str, AddedToken]]` 的字典）：键应为预定义特殊属性列表中的项：[`bos_token`、`eos_token`、`unk_token`、`sep_token`、`pad_token`、`cls_token`、`mask_token`、`extra_special_tokens`]。仅当这些标记尚未存在于词汇表中时才会被添加（通过检查分词器是否为其分配了 `unk_token` 的索引来测试）。

replace_extra_special_tokens (`bool`，*可选*，默认为 `True`)：如果为 `True`，现有的额外特殊标记列表将被 `special_tokens_dict` 中提供的列表替换。否则，`extra_special_tokens` 将被扩展。在前一种情况下，这些标记不会从分词器的完整词汇表中移除，只是被标记为非特殊标记。请记住，这仅影响解码期间跳过哪些标记，而不影响 `added_tokens_encoder` 和 `added_tokens_decoder`。这意味着之前的 `extra_special_tokens` 仍然是已添加的标记，模型不会对其进行拆分。

**返回：** `int`

添加到词汇表中的标记数量。

将特殊标记（eos、pad、cls 等）的字典添加到编码器中，并将其链接到类属性。如果特殊标记不在词汇表中，则将其添加到词汇表中（索引从当前词汇表的最后一个索引开始）。

在向词表中添加新标记时，您应确保同时调整模型的标记嵌入矩阵大小，使其嵌入矩阵与分词器相匹配。

为此，请使用 [resize_token_embeddings()](/docs/transformers/v5.24.0/zh/main_classes/model#transformers.PreTrainedModel.resize_token_embeddings) 方法。

使用 `add_special_tokens` 可确保您的特殊标记能以多种方式使用：

- 在解码时，可以通过设置 `skip_special_tokens = True` 来跳过特殊标记。
- 特殊标记由分词器仔细处理（它们永远不会被拆分），与 `AddedTokens` 类似。
- 您可以轻松使用分词器类的属性（例如 `tokenizer.cls_token`）来引用特殊标记。这使得开发与模型无关的训练和微调脚本变得十分便捷。

在可能的情况下，所提供的预训练模型已经注册了特殊标记（例如 [BertTokenizer](/docs/transformers/v5.24.0/zh/model_doc/lxmert#transformers.BertTokenizer) 的 `cls_token` 已注册为 `'[CLS]'`，XLM 的也已注册为 `'</s>'`）。

示例：

```python
# Let's see how to add a new classification token to GPT-2
tokenizer = GPT2Tokenizer.from_pretrained("openai-community/gpt2")
model = GPT2Model.from_pretrained("openai-community/gpt2")

special_tokens_dict = {"cls_token": "<CLS>"}

num_added_toks = tokenizer.add_special_tokens(special_tokens_dict)
print("We have added", num_added_toks, "tokens")
# Notice: resize_token_embeddings expect to receive the full size of the new vocabulary, i.e., the length of the tokenizer.
model.resize_token_embeddings(len(tokenizer))

assert tokenizer.cls_token == "<CLS>"
```

#### apply_chat_template[[transformers.TokenizersBackend.apply_chat_template]]

```python
apply_chat_template(conversation: list[dict[str, str]] | list[list[dict[str, str]]], tools: list[dict | Callable] | None = None, documents: list[dict[str, str]] | None = None, chat_template: str | None = None, add_generation_prompt: bool = False, continue_final_message: bool | str = False, tokenize: bool = True, sanitize_control_tokens: bool = False, padding: bool | str | PaddingStrategy = False, truncation: bool = False, max_length: int | None = None, return_tensors: str | TensorType | None = None, return_dict: bool = True, return_assistant_tokens_mask: bool = False, tokenizer_kwargs: dict[str, Any] | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L3040)

**参数：**

conversation (Union[list[dict[str, str]], list[list[dict[str, str]]]]) : 一个包含 "role" 和 "content" 键的字典列表，表示迄今为止的聊天历史记录。

tools (`list[Union[Dict, Callable]]`，*可选*)：一个工具（可调用函数）列表，模型可以访问这些工具。如果模板不支持函数调用，此参数将不起作用。每个工具应以 JSON Schema 的形式传入，提供工具的名称、描述和参数类型。有关更多信息，请参阅我们的[工具使用指南](https://huggingface.co/docs/transformers/en/chat_extras#passing-tools)。

documents (`list[dict[str, str]]`，*可选*)：一个字典列表，表示文档。如果模型正在执行 RAG（检索增强生成），这些文档将对模型可访问。如果模板不支持 RAG，此参数将不起作用。我们建议每个文档应为一个包含 "title" 和 "text" 键的字典。

chat_template (`str`，*可选*)：用于此转换的 Jinja 模板。通常无需为此参数传入任何值，因为默认会使用模型的模板。

add_generation_prompt (bool, *optional*) : 如果设置了此参数，将在格式化输出末尾追加一个包含指示助手消息起始的 token 的提示。当您希望从模型生成回复时，此功能非常有用。请注意，此参数会传递给聊天模板，因此模板必须支持该参数，此参数才能生效。

continue_final_message (bool 或 str，*可选*) : 如果设置了此参数，聊天将被格式化，使得聊天中的最后一条消息是开放式的，不包含任何 EOS token。模型将继续该消息，而不是开始一条新消息。这允许你为模型的响应“预填充”部分内容。如果传入字符串，它将用作要继续的字段的关键字（例如 "reasoning_content"）。不能与 `add_generation_prompt` 同时使用。

tokenize (`bool`，默认为 `True`)：是否对输出进行分词。如果为 `False`，输出将是一个字符串。

sanitize_control_tokens (`bool`，默认为 `False`) : 如果设置为 True，则出现在消息、工具、文档或作为 `**kwargs` 传递的模板变量中的控制标记将被编码为普通文本，因此只有聊天模板本身写入的控制标记才会被编码为标记。控制标记包括分词器的特殊标记，以及 `tokenizer.chat_control_tokens` 中的已添加标记。如果未设置该变量，则从聊天模板文本和字符串字面量中出现的已添加标记推断控制标记。仅对整个控制标记进行清理，因此如果模板将输入中的字符串拼接成控制标记（例如 `'<|' + message['role'] + '|>'`），则必须单独验证这些字符串。字典键也不会被清理。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：选择一种策略来填充返回的序列（根据模型的填充方向和填充索引），可选策略如下： - `True` 或 `'longest'`：填充到批次中最长的序列（如果只提供了单个序列，则不进行填充）。 - `'max_length'`：填充到由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认）：不进行填充（即可以输出包含不同长度序列的批次）。

truncation (`bool`，默认为 `False`)：是否在最大长度处截断序列。如果 tokenize 为 `False`，则此参数无效。

max_length (`int`, *可选*) : 用于填充或截断的最大长度（以 token 计）。如果 tokenize 为 `False`，则此参数无效。如果未指定，将使用分词器的 `max_length` 属性作为默认值。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。如果 tokenize 为 `False`，则无效。可接受的值为：- `'pt'`：返回 PyTorch `torch.Tensor` 对象。- `'np'`：返回 NumPy `np.ndarray` 对象。

return_dict (`bool`，默认为 `True`)：是否返回包含命名输出的字典。如果 tokenize 为 `False`，则此参数无效。

tokenizer_kwargs (`dict[str : Any]`，*可选*)：传递给 tokenizer 的额外 kwargs。

return_assistant_tokens_mask (`bool`，默认为 `False`)：是否返回助手生成 token 的掩码。对于助手生成的 token，掩码中对应位置为 1；对于用户和系统 token，掩码中对应位置为 0。此功能仅适用于通过 `{% generation %}` 关键字支持该功能的聊天模板。

- ****kwargs** : 传递给模板渲染器的额外 kwargs。聊天模板可以访问这些参数。

**返回：** `Union[list[int], Dict]`

一个表示迄今为止已分词对话的 token id 列表，包括控制 token。此输出可直接传递给模型，或通过 `generate()` 等方法传递。如果设置了 `return_dict`，则返回一个包含分词器输出的字典。

将包含 `"role"` 和 `"content"` 键的字典列表转换为 token id 列表。此方法旨在与聊天模型配合使用，它会读取分词器的 chat_template 属性，以确定转换时所使用的格式和控制 token。

#### batch_decode[[transformers.TokenizersBackend.batch_decode]]

```python
batch_decode(sequences: list[int] | list[list[int]] | np.ndarray | torch.Tensor, skip_special_tokens: bool = False, clean_up_tokenization_spaces: bool | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2942)

**参数：**

sequences (`Union[list[int], list[list[int]], np.ndarray, torch.Tensor]`) : 标记化输入 ID 的列表。可通过 `__call__` 方法获取。

skip_special_tokens (`bool`，*可选*，默认为 `False`)：是否在解码过程中移除特殊标记。

clean_up_tokenization_spaces (`bool`，*可选*)：是否清理分词空格。如果为 `None`，则默认为 `self.clean_up_tokenization_spaces`。

kwargs （额外的关键字参数，*可选*）：将传递给底层模型特定的解码方法。

**返回：** `list[str]`

解码后的句子列表。

通过调用 decode，将 token id 的列表的列表转换为字符串列表。

此方法是为了向后兼容而提供的。`decode` 方法现在原生支持批量输入，因此您可以直接使用 `decode` 而无需使用 `batch_decode`。

#### decode[[transformers.TokenizersBackend.decode]]

```python
decode(token_ids: int | list[int] | list[list[int]] | np.ndarray | torch.Tensor, skip_special_tokens: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2894)

**参数：**

token_ids (`Union[int, list[int], list[list[int]], np.ndarray, torch.Tensor]`) : 单个序列或一批（序列列表）的标记化输入 ID。可通过 `__call__` 方法获取。

skip_special_tokens (`bool`，*可选*，默认为 `False`)：是否在解码过程中移除特殊标记。

kwargs （额外的关键字参数，*可选*）：将传递给底层模型特定的解码方法。

**返回：** `Union[str, list[str]]`

单个序列的解码字符串，或一批序列的解码字符串列表。

使用分词器和词汇表，将 id 序列转换为字符串，或将序列列表转换为字符串列表，并可选择移除特殊标记和清理分词空格。

类似于执行 `self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))`。

#### encode[[transformers.TokenizersBackend.encode]]

```python
encode(text: TextInput | PreTokenizedInput | EncodedInput, text_pair: TextInput | PreTokenizedInput | EncodedInput | None = None, add_special_tokens: bool = True, padding: bool | str | PaddingStrategy = False, truncation: bool | str | TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, padding_side: str | None = None, return_tensors: str | TensorType | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L2272)

**参数：**

text (`str`、`list[str]` 或 `list[int]`)：要编码的第一个序列。它可以是一个字符串、一个字符串列表（使用 `tokenize` 方法分词后的字符串）或一个整数列表（使用 `convert_tokens_to_ids` 方法转换后的 token ID）。

text_pair (`str`、`list[str]` 或 `list[int]`，*可选*)：要编码的可选第二个序列。它可以是一个字符串、一个字符串列表（使用 `tokenize` 方法分词后的字符串）或一个整数列表（使用 `convert_tokens_to_ids` 方法得到的分词字符串 ID）。

add_special_tokens (`bool`，*可选*，默认为 `True`)：在编码序列时是否添加特殊标记。此操作将使用底层的 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 函数，该函数定义了哪些标记会自动添加到输入 ID 中。如果您希望自动添加 `bos` 或 `eos` 标记，此功能非常有用。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。 - `'max_length'`：填充至由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充至模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认值）：不进行填充（即，可以输出包含不同长度序列的批次）。

truncation (`bool`、`str` 或 [TruncationStrategy](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)，*optional*，默认为 `False`)：启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认）：不截断（即，可以输出序列长度大于模型最大允许输入大小的批次）。

max_length (`int`, *可选*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

stride (`int`，*可选*，默认为 0)：如果与 `max_length` 一起设置为某个数值，则当 `return_overflowing_tokens=True` 时，返回的溢出 token 将包含来自截断序列末尾的若干 token，以在截断序列和溢出序列之间提供一定的重叠。该参数的值定义了重叠 token 的数量。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。需要启用 `padding`。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

- ****kwargs** : 传递给 `.tokenize()` 方法。

**返回：** `list[int]`、`torch.Tensor` 或 `np.ndarray`

文本的标记化 ID。

使用分词器和词汇表将字符串转换为 id（整数）序列。

与执行 `self.convert_tokens_to_ids(self.tokenize(text))` 相同。

#### push_to_hub[[transformers.TokenizersBackend.push_to_hub]]

```python
push_to_hub(repo_id: str, commit_message: str | None = None, commit_description: str | None = None, private: bool | None = None, token: bool | str | None = None, revision: str | None = None, create_pr: bool = False, max_shard_size: int | str | None = '50GB', tags: list[str] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/utils/hub.py#L822)

**参数：**

repo_id (`str`) : 要推送分词器的仓库名称。推送到特定组织时，应包含该组织的名称。

commit_message (`str`, *可选*) : 推送时提交的说明信息。默认值为 `"Upload tokenizer"`。

commit_description (`str`, *可选*) : 将创建的提交的描述

private (`bool`，*可选*)：是否将仓库设为私有。如果为 `None`（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。

token (`bool` 或 `str`，*可选*) : 用于远程文件的 HTTP bearer 授权令牌。如果为 `True`（默认值），将使用运行 `hf auth login` 时生成的令牌（存储在 `~/.huggingface` 中）。

revision (`str`, *可选*) : 推送上传文件的目标分支。

create_pr (`bool`，*可选*，默认为 `False`)：是否使用上传的文件创建 PR，还是直接提交。

max_shard_size (`int` 或 `str`，*可选*，默认为 `"50GB"`)：仅适用于模型。在分片之前，检查点（checkpoint）的最大大小。分片后的每个检查点大小都将小于此值。如果以字符串形式表示，则必须为数字后跟单位（例如 `"5MB"`）。

tags (`list[str]`，*可选*)：要推送到 Hub 的标签列表。

将分词器文件上传到 🤗 Model Hub。

示例：

```python
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-cased")

# Push the tokenizer to your namespace with the name "my-finetuned-bert".
tokenizer.push_to_hub("my-finetuned-bert")

# Push the tokenizer to an organization with the name "my-finetuned-bert".
tokenizer.push_to_hub("huggingface/my-finetuned-bert")
```

#### convert_to_native_format[[transformers.TokenizersBackend.convert_to_native_format]]

```python
convert_to_native_format(trust_remote_code = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L104)

从可用的序列化文件（tokenizer.json、sentencepiece 模型、tekken.json、vocab/merges）构建 `tokenizers.Tokenizer` 后端。

#### get_added_vocab[[transformers.TokenizersBackend.get_added_vocab]]

```python
get_added_vocab()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L749)

**返回：** `dict[str, int]`

添加的标记。

以字典形式返回词汇表中新增的 token 及其对应的索引。

#### num_special_tokens_to_add[[transformers.TokenizersBackend.num_special_tokens_to_add]]

```python
num_special_tokens_to_add(pair: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L846)

**参数：**

pair (`bool`，*可选*，默认为 `False`)：在序列对或单个序列的情况下，是否应计算所添加的 token 数量。

**返回：** `int`

添加到序列中的特殊标记数量。

在编码包含特殊标记的序列时，返回所添加标记的数量。

这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放入训练循环中。

#### save_pretrained[[transformers.TokenizersBackend.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, legacy_format: bool | None = None, filename_prefix: str | None = None, push_to_hub: bool = False, save_format: str | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L568)

**参数：**

save_format (`str`, *可选*) : `"mistral"` 表示通过复制原始文件以原生 `tekken.json` 格式保存（需要原始 tekken 词汇文件可用）。保存时，名称会被规范化为 `tekken.json`，并且实例化的分词器必须与其完全匹配。`"hf"` 或 `None` 表示使用默认的 HuggingFace 格式。

kwargs (`dict[str, Any]`，*可选*)：传递给 [push_to_hub()](/docs/transformers/v5.24.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 方法的额外关键字参数。

**返回：** 一个 `str` 元组

已保存的文件。

保存完整的分词器状态。

扩展了 [save_pretrained()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) 以支持 `save_format`，适用于从原生词汇表文件（例如 Mistral 的 `tekken.json`）转换而来的分词器。有关 `legacy_format`、`filename_prefix` 和 `push_to_hub`，请参阅基础方法。

#### set_truncation_and_padding[[transformers.TokenizersBackend.set_truncation_and_padding]]

```python
set_truncation_and_padding(padding_strategy: PaddingStrategy, truncation_strategy: TruncationStrategy, max_length: int, stride: int, pad_to_multiple_of: int | None, padding_side: str | None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L905)

**参数：**

padding_strategy ([PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy))：将应用于输入的填充类型

truncation_strategy ([TruncationStrategy](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy))：将应用于输入的截断类型

max_length (`int`) : 序列的最大长度。

stride (`int`) : 处理溢出时使用的步长。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

为快速分词器（由 HuggingFace tokenizers 库提供）定义截断和填充策略，并在之后恢复分词器的设置。

提供的分词器在受管代码段之前没有设置填充/截断策略。如果分词器之前已设置了填充/截断策略，那么在退出受管代码段时，该策略将被重置为无填充/无截断。

#### train_new_from_iterator[[transformers.TokenizersBackend.train_new_from_iterator]]

```python
train_new_from_iterator(text_iterator, vocab_size, length = None, new_special_tokens = None, special_tokens_map = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L1218)

**参数：**

text_iterator （`list[str]` 的生成器）：训练语料库。应为文本批次的生成器，例如，如果所有数据都在内存中，则可以是文本列表的列表。

vocab_size (`int`) : 您希望分词器使用的词汇表大小。

length (`int`，*可选*)：迭代器中序列的总数。用于提供有意义的进度跟踪

new_special_tokens （`str` 或 `AddedToken` 的列表，*可选*）：要添加到正在训练的 tokenizer 中的新特殊标记列表。

special_tokens_map (`dict[str, str]`, *可选*) : 如果您想重命名该分词器使用的某些特殊标记，请在此参数中传入一个映射，将旧的特殊标记名称映射到新的特殊标记名称。

kwargs (`dict[str, Any]`，*可选*)：从 🤗 Tokenizers 库传递给 trainer 的额外关键字参数。

**返回：** [PreTrainedTokenizerFast](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.TokenizersBackend)

一个与原始分词器类型相同的新分词器，在 `text_iterator` 上训练。

使用与当前分词器相同的默认设置（包括特殊标记和分词流程），在新的语料库上训练分词器。

#### update_post_processor[[transformers.TokenizersBackend.update_post_processor]]

```python
update_post_processor()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L636)

使用当前的 `bos_token` 和 `eos_token` 更新底层的后处理器。

## PythonBackend[[transformers.PythonBackend]]

#### transformers.PythonBackend[[transformers.PythonBackend]]

```python
transformers.PythonBackend(**kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L405)

**参数：**

model_max_length (`int`，*可选*)：输入到 transformer 模型的最大长度（以 token 数量计）。当使用 [from_pretrained()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.from_pretrained) 加载分词器时，此值将设置为 `max_model_input_sizes` 中为关联模型存储的值（见上文）。如果未提供值，则默认为 VERY_LARGE_INTEGER（`int(1e30)`）。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

truncation_side (`str`, *可选*) : 模型应应用截断的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

chat_template (`str`, *可选*) : 一个 Jinja 模板字符串，用于格式化聊天消息列表。完整说明请参阅 https://huggingface.co/docs/transformers/chat_templating。

model_input_names (`list[string]`, *可选*) : 模型前向传播接受的输入列表（例如 `"token_type_ids"` 或 `"attention_mask"`）。默认值取自同名的类属性。

bos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子开头的特殊标记。

eos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子结束的特殊标记。

unk_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示词表外（out-of-vocabulary）token 的特殊 token。

sep_token (`str` 或 `tokenizers.AddedToken`，*可选*)：用于分隔同一输入中两个不同句子的特殊标记（例如 BERT 使用）。

pad_token (`str` 或 `tokenizers.AddedToken`，*可选*)：一种特殊标记，用于在批处理时将标记数组调整为相同大小。随后，注意力机制或损失计算会忽略该标记。

cls_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示输入类别的特殊标记（例如 BERT 使用）。

mask_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示掩码 token 的特殊 token（用于掩码语言建模预训练目标，例如 BERT）。将关联到 `self.mask_token` 和 `self.mask_token_id`。

extra_special_tokens （`str` 或 `tokenizers.AddedToken` 的列表，*可选*）：一组额外的模型特定特殊标记。在此处添加它们，以确保在将 `skip_special_tokens` 设置为 True 进行解码时跳过这些标记。如果它们不属于词表的一部分，则会被追加到词表的末尾。

split_special_tokens (`bool`，*可选*，默认为 `False`)：在分词过程中是否应拆分特殊标记。传入该参数会影响分词器的内部状态。默认行为是不拆分特殊标记。这意味着，如果 `<s>` 是 `bos_token`，则 `tokenizer.tokenize("<s>") = ['<s>`]。否则，如果 `split_special_tokens=True`，则 `tokenizer.tokenize("<s>")` 将返回 `['<','s', '>']`。

所有慢速分词器的基类。

继承自 [PreTrainedTokenizerBase](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase)。

处理分词和特殊标记的所有共享方法，以及下载/缓存/加载预训练分词器以及向词表中添加标记的方法。

该类还以统一的方式在所有分词器之上包含新增的 token，因此我们无需处理各种底层字典结构（BPE、sentencepiece 等）特有的词表扩展方法。

类属性（由派生类重写）

- **vocab_files_names** (`dict[str, str]`) -- 一个字典，其键为模型所需的每个词汇文件在 `__init__` 中的关键字参数名，对应的值为用于保存该文件的文件名（字符串）。
- **pretrained_vocab_files_map** (`dict[str, dict[str, str]]`) -- 一个字典的字典，其中顶层键是模型所需的每个词汇文件在 `__init__` 中的关键字参数名，底层键是预训练模型的 `short-cut-names`，对应的值为关联的预训练词汇文件的 `url`。
- **model_input_names** (`list[str]`) -- 模型前向传播中预期的输入列表。
- **padding_side** (`str`) -- 模型应应用填充的一侧的默认值。应为 `'right'` 或 `'left'`。
- **truncation_side** (`str`) -- 模型应应用截断的一侧的默认值。应为 `'right'` 或 `'left'`。

#### build_inputs_with_special_tokens[[transformers.PythonBackend.build_inputs_with_special_tokens]]

```python
build_inputs_with_special_tokens(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L872)

**参数：**

token_ids_0 (`list[int]`) : 将添加特殊标记的 ID 列表。

token_ids_1 (`list[int]`, *可选*) : 用于序列对的可选第二个 ID 列表。

**返回：** `list[int]`

包含相应特殊标记的输入 ID 列表。

通过添加特殊标记，从单个序列或序列对构建模型输入。

该方法会根据分词器的 `special_tokens_pattern` 动态构建输入：
- `"none"`：无特殊标记
- `"cls_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] seq1 [SEP]
- `"eos"`：seq0 [EOS] 或 seq0 [EOS] seq1 [EOS]
- `"bos"`：[BOS] seq0 或 [BOS] seq0 [BOS] seq1
- `"bos_eos"`：[BOS] seq0 [EOS] 或 [BOS] seq0 [EOS] seq1 [EOS]
- `"cls_double_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] [SEP] seq1 [SEP]
- `"prefix_suffix"`：`<prefix_tokens> seq0 [seq1] <suffix_tokens>`（自定义前缀/后缀，存储在分词器中）

#### create_token_type_ids_from_sequences[[transformers.PythonBackend.create_token_type_ids_from_sequences]]

```python
create_token_type_ids_from_sequences(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1305)

**参数：**

token_ids_0 (`list[int]`) : ID 列表。

token_ids_1 (`list[int]`, *可选*) : 用于序列对的可选第二个 ID 列表。

**返回：** `list[int]`

根据配置的模式生成的 Token 类型 ID。

创建一个掩码，该掩码由传入的两个序列生成，用于序列对分类任务。

此方法根据分词器的配置属性动态构建 token 类型 ID：
- `token_type_ids_pattern`：要使用的模式（"all_zeros" 或 "bert_style"）
- `token_type_ids_include_special_tokens`：在长度计算中是否考虑特殊标记

示例：
```python
# All zeros pattern (default, used by RoBERTa, BART, etc.)
tokenizer.token_type_ids_pattern = "all_zeros"
# Returns: [0, 0, 0, ...] for both sequences

# BERT-style pattern (first sequence gets 0s, second gets 1s)
tokenizer.token_type_ids_pattern = "bert_style"
# Returns: [0, 0, 0, ..., 1, 1, 1, ...] for sequence pairs
```

#### get_added_vocab[[transformers.PythonBackend.get_added_vocab]]

```python
get_added_vocab()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L493)

**返回：** `dict[str, int]`

添加的标记。

以字典形式返回词表中新增的 token 及其对应的索引。由于目前即使 token 已存在于词表中，我们仍会将其添加，因此结果可能与快速调用不同。这一点应当改进。

#### get_special_tokens_mask[[transformers.PythonBackend.get_special_tokens_mask]]

```python
get_special_tokens_mask(token_ids_0: list, token_ids_1: list | None = None, already_has_special_tokens: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L976)

**参数：**

token_ids_0 (`list[int]`) : 第一个序列的 id 列表。

token_ids_1 (`list[int]`, *可选*) : 第二个序列的 id 列表。

already_has_special_tokens (`bool`，*可选*，默认为 `False`)：标记列表是否已使用模型的特殊标记进行格式化。

**返回：** 一个包含 [0, 1] 范围内整数的列表

1 表示特殊标记，0 表示序列标记。

从未添加特殊标记的标记列表中获取序列 ID。当使用分词器的 `prepare_for_model` 或 `encode_plus` 方法添加特殊标记时，会调用此方法。

此方法会根据分词器的 `special_tokens_pattern` 动态构建特殊标记掩码：
- `"none"`：不使用特殊标记（默认值，返回全 0）
- `"cls_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] seq1 [SEP]
- `"eos"`：seq0 [EOS] 或 seq0 [EOS] seq1 [EOS]
- `"bos"`：[BOS] seq0 或 [BOS] seq0 [BOS] seq1
- `"bos_eos"`：[BOS] seq0 [EOS] 或 [BOS] seq0 [EOS] seq1 [EOS]
- `"cls_double_sep"`：[CLS] seq0 [SEP] 或 [CLS] seq0 [SEP] [SEP] seq1 [SEP]
- `"prefix_suffix"`: `<prefix_tokens> seq0 [seq1] <suffix_tokens>`

#### num_special_tokens_to_add[[transformers.PythonBackend.num_special_tokens_to_add]]

```python
num_special_tokens_to_add(pair: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L607)

**参数：**

pair (`bool`，*可选*，默认为 `False`)：在序列对或单个序列的情况下，是否应计算所添加的 token 数量。

**返回：** `int`

添加到序列中的特殊标记数量。

在编码包含特殊标记的序列时，返回所添加标记的数量。

这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放入训练循环中。

#### prepare_for_model[[transformers.PythonBackend.prepare_for_model]]

```python
prepare_for_model(ids: list[int], pair_ids: list[int] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = False, max_length: int | None = None, stride: int = 0, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_length: bool = False, verbose: bool = True, prepend_batch_axis: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1128)

**参数：**

ids : 第一个序列的标记化输入 ID。

pair_ids : 第二个序列的标记化输入 ID（可选）。

准备输入 ID 序列，以便模型使用。添加特殊标记，并进行截断和填充。

#### prepare_for_tokenization[[transformers.PythonBackend.prepare_for_tokenization]]

```python
prepare_for_tokenization(text: str, is_split_into_words: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L848)

**参数：**

text (`str`) : 要处理的文本。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

kwargs (`dict[str, Any]`，*可选*)：用于分词的关键词参数。

**返回：** `tuple[str, dict[str, Any]]`

准备好的文本和未使用的 kwargs。

在分词之前执行任何必要的转换。

该方法应从 `kwargs` 中弹出参数，并返回剩余的 `kwargs`。我们还会在编码流程结束时检查 `kwargs`，以确保所有参数都已被使用。

#### save_vocabulary[[transformers.PythonBackend.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1369)

**参数：**

save_directory (`str`) : 用于保存词汇表的目录。

filename_prefix (`str`, *可选*) : 一个可选的前缀，用于添加到保存文件的名称中。

**返回：** `tuple[str, ...]`

已保存文件的路径，如果没有保存任何文件，则为空元组。

用于常见词汇表保存模式的默认实现。将 self.encoder/self.vocab 保存为 JSON，可选地将 self.bpe_ranks 作为合并规则一并保存。如果不存在词汇表，则返回空元组。

如果分词器需要自定义保存逻辑（例如 SentencePiece 模型、多个词汇文件或特殊文件格式），请重写此方法。

#### tokenize[[transformers.PythonBackend.tokenize]]

```python
tokenize(text: str, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L630)

**参数：**

text : 要编码的序列。

- ****kwargs** : 传递给模型特定的 `prepare_for_tokenization` 预处理方法。

**返回值：**

令牌列表。

使用分词器将字符串转换为标记序列。

#### truncate_sequences[[transformers.PythonBackend.truncate_sequences]]

```python
truncate_sequences(ids: list[int], pair_ids: list[int] | None = None, num_tokens_to_remove: int = 0, truncation_strategy: str | transformers.tokenization_utils_base.TruncationStrategy = 'longest_first', stride: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_python.py#L1238)

根据指定的策略截断序列。

## TokenizersBackend[[transformers.TokenizersBackend]]

#### transformers.TokenizersBackend[[transformers.TokenizersBackend]]

```python
transformers.TokenizersBackend(*args, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L87)

**参数：**

model_max_length (`int`，*可选*)：输入到 transformer 模型的最大长度（以 token 数量计）。当使用 [from_pretrained()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.from_pretrained) 加载分词器时，此值将设置为 `max_model_input_sizes` 中为关联模型存储的值（见上文）。如果未提供值，则默认为 VERY_LARGE_INTEGER（`int(1e30)`）。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

truncation_side (`str`, *可选*) : 模型应应用截断的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

chat_template (`str`, *可选*) : 一个 Jinja 模板字符串，用于格式化聊天消息列表。完整说明请参阅 https://huggingface.co/docs/transformers/chat_templating。

model_input_names (`list[string]`, *可选*) : 模型前向传播接受的输入列表（例如 `"token_type_ids"` 或 `"attention_mask"`）。默认值取自同名的类属性。

bos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子开头的特殊标记。

eos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子结束的特殊标记。

unk_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示词表外（out-of-vocabulary）token 的特殊 token。

sep_token (`str` 或 `tokenizers.AddedToken`，*可选*)：用于分隔同一输入中两个不同句子的特殊标记（例如 BERT 使用）。

pad_token (`str` 或 `tokenizers.AddedToken`，*可选*)：一种特殊标记，用于在批处理时将标记数组调整为相同大小。随后，注意力机制或损失计算会忽略该标记。

cls_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示输入类别的特殊标记（例如 BERT 使用）。

mask_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示掩码 token 的特殊 token（用于掩码语言建模预训练目标，例如 BERT）。将关联到 `self.mask_token` 和 `self.mask_token_id`。

extra_special_tokens （`str` 或 `tokenizers.AddedToken` 的列表，*可选*）：一组额外的模型特定特殊标记。在此处添加它们，以确保在将 `skip_special_tokens` 设置为 True 进行解码时跳过这些标记。如果它们不属于词表的一部分，则会被追加到词表的末尾。

split_special_tokens (`bool`，*可选*，默认为 `False`)：在分词过程中是否应拆分特殊标记。传入该参数会影响分词器的内部状态。默认行为是不拆分特殊标记。这意味着，如果 `<s>` 是 `bos_token`，则 `tokenizer.tokenize("<s>") = ['<s>`]。否则，如果 `split_special_tokens=True`，则 `tokenizer.tokenize("<s>")` 将返回 `['<','s', '>']`。

tokenizer_object (`tokenizers.Tokenizer`)：用于实例化的来自 🤗 tokenizers 的 `tokenizers.Tokenizer` 对象。有关更多信息，请参阅 [使用 🤗 tokenizers 中的分词器](../fast_tokenizers)。

tokenizer_file (`str`) : 指向本地 JSON 文件的路径，该文件表示之前序列化的来自 🤗 tokenizers 的 `tokenizers.Tokenizer` 对象。

所有快速分词器（封装 HuggingFace tokenizers 库）的基类。

继承自 [PreTrainedTokenizerBase](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase)。

处理分词和特殊标记的所有共享方法，以及用于下载/缓存/加载预训练分词器的方法，还包括向词表中添加标记的方法。

该类以统一的方式在所有分词器之上包含新增的 token，因此我们无需处理各种底层字典结构（BPE、sentencepiece 等）特有的词表扩展方法。

类属性（由派生类重写）

- **vocab_files_names** (`dict[str, str]`) -- 一个字典，其键为模型所需的每个词汇文件在 `__init__` 中的关键字参数名，对应的值为用于保存该文件的文件名（字符串）。
- **pretrained_vocab_files_map** (`dict[str, dict[str, str]]`) -- 一个字典的字典，其中顶层键是模型所需的每个词汇文件在 `__init__` 中的关键字参数名，底层键是预训练模型的 `short-cut-names`，对应的值为关联的预训练词汇文件的 `url`。
- **model_input_names** (`list[str]`) -- 模型前向传播中预期的输入列表。
- **padding_side** (`str`) -- 模型应应用填充的一侧的默认值。应为 `'right'` 或 `'left'`。
- **truncation_side** (`str`) -- 模型应应用截断的一侧的默认值。应为 `'right'` 或 `'left'`。

#### convert_to_native_format[[transformers.TokenizersBackend.convert_to_native_format]]

```python
convert_to_native_format(trust_remote_code = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L104)

从可用的序列化文件（tokenizer.json、sentencepiece 模型、tekken.json、vocab/merges）构建 `tokenizers.Tokenizer` 后端。

#### get_added_vocab[[transformers.TokenizersBackend.get_added_vocab]]

```python
get_added_vocab()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L749)

**返回：** `dict[str, int]`

添加的标记。

以字典形式返回词汇表中新增的 token 及其对应的索引。

#### num_special_tokens_to_add[[transformers.TokenizersBackend.num_special_tokens_to_add]]

```python
num_special_tokens_to_add(pair: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L846)

**参数：**

pair (`bool`，*可选*，默认为 `False`)：在序列对或单个序列的情况下，是否应计算所添加的 token 数量。

**返回：** `int`

添加到序列中的特殊标记数量。

在编码包含特殊标记的序列时，返回所添加标记的数量。

这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放入训练循环中。

#### save_pretrained[[transformers.TokenizersBackend.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, legacy_format: bool | None = None, filename_prefix: str | None = None, push_to_hub: bool = False, save_format: str | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L568)

**参数：**

save_format (`str`, *可选*) : `"mistral"` 表示通过复制原始文件以原生 `tekken.json` 格式保存（需要原始 tekken 词汇文件可用）。保存时，名称会被规范化为 `tekken.json`，并且实例化的分词器必须与其完全匹配。`"hf"` 或 `None` 表示使用默认的 HuggingFace 格式。

kwargs (`dict[str, Any]`，*可选*)：传递给 [push_to_hub()](/docs/transformers/v5.24.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 方法的额外关键字参数。

**返回：** 一个 `str` 元组

已保存的文件。

保存完整的分词器状态。

扩展了 [save_pretrained()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) 以支持 `save_format`，适用于从原生词汇表文件（例如 Mistral 的 `tekken.json`）转换而来的分词器。有关 `legacy_format`、`filename_prefix` 和 `push_to_hub`，请参阅基础方法。

#### set_truncation_and_padding[[transformers.TokenizersBackend.set_truncation_and_padding]]

```python
set_truncation_and_padding(padding_strategy: PaddingStrategy, truncation_strategy: TruncationStrategy, max_length: int, stride: int, pad_to_multiple_of: int | None, padding_side: str | None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L905)

**参数：**

padding_strategy ([PaddingStrategy](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.utils.PaddingStrategy))：将应用于输入的填充类型

truncation_strategy ([TruncationStrategy](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy))：将应用于输入的截断类型

max_length (`int`) : 序列的最大长度。

stride (`int`) : 处理溢出时使用的步长。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

为快速分词器（由 HuggingFace tokenizers 库提供）定义截断和填充策略，并在之后恢复分词器的设置。

提供的分词器在受管代码段之前没有设置填充/截断策略。如果分词器之前已设置了填充/截断策略，那么在退出受管代码段时，该策略将被重置为无填充/无截断。

#### train_new_from_iterator[[transformers.TokenizersBackend.train_new_from_iterator]]

```python
train_new_from_iterator(text_iterator, vocab_size, length = None, new_special_tokens = None, special_tokens_map = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L1218)

**参数：**

text_iterator （`list[str]` 的生成器）：训练语料库。应为文本批次的生成器，例如，如果所有数据都在内存中，则可以是文本列表的列表。

vocab_size (`int`) : 您希望分词器使用的词汇表大小。

length (`int`，*可选*)：迭代器中序列的总数。用于提供有意义的进度跟踪

new_special_tokens （`str` 或 `AddedToken` 的列表，*可选*）：要添加到正在训练的 tokenizer 中的新特殊标记列表。

special_tokens_map (`dict[str, str]`, *可选*) : 如果您想重命名该分词器使用的某些特殊标记，请在此参数中传入一个映射，将旧的特殊标记名称映射到新的特殊标记名称。

kwargs (`dict[str, Any]`，*可选*)：从 🤗 Tokenizers 库传递给 trainer 的额外关键字参数。

**返回：** [PreTrainedTokenizerFast](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.TokenizersBackend)

一个与原始分词器类型相同的新分词器，在 `text_iterator` 上训练。

使用与当前分词器相同的默认设置（包括特殊标记和分词流程），在新的语料库上训练分词器。

#### update_post_processor[[transformers.TokenizersBackend.update_post_processor]]

```python
update_post_processor()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_tokenizers.py#L636)

使用当前的 `bos_token` 和 `eos_token` 更新底层的后处理器。

## SentencePieceBackend[[transformers.SentencePieceBackend]]

#### transformers.SentencePieceBackend[[transformers.SentencePieceBackend]]

```python
transformers.SentencePieceBackend(**kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_sentencepiece.py#L45)

**参数：**

model_max_length (`int`，*可选*)：输入到 transformer 模型的最大长度（以 token 数量计）。当使用 [from_pretrained()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.from_pretrained) 加载分词器时，此值将设置为 `max_model_input_sizes` 中为关联模型存储的值（见上文）。如果未提供值，则默认为 VERY_LARGE_INTEGER（`int(1e30)`）。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

truncation_side (`str`, *可选*) : 模型应应用截断的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

chat_template (`str`, *可选*) : 一个 Jinja 模板字符串，用于格式化聊天消息列表。完整说明请参阅 https://huggingface.co/docs/transformers/chat_templating。

model_input_names (`list[string]`, *可选*) : 模型前向传播接受的输入列表（例如 `"token_type_ids"` 或 `"attention_mask"`）。默认值取自同名的类属性。

bos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子开头的特殊标记。

eos_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示句子结束的特殊标记。

unk_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示词表外（out-of-vocabulary）token 的特殊 token。

sep_token (`str` 或 `tokenizers.AddedToken`，*可选*)：用于分隔同一输入中两个不同句子的特殊标记（例如 BERT 使用）。

pad_token (`str` 或 `tokenizers.AddedToken`，*可选*)：一种特殊标记，用于在批处理时将标记数组调整为相同大小。随后，注意力机制或损失计算会忽略该标记。

cls_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示输入类别的特殊标记（例如 BERT 使用）。

mask_token (`str` 或 `tokenizers.AddedToken`，*可选*)：表示掩码 token 的特殊 token（用于掩码语言建模预训练目标，例如 BERT）。将关联到 `self.mask_token` 和 `self.mask_token_id`。

extra_special_tokens （`str` 或 `tokenizers.AddedToken` 的列表，*可选*）：一组额外的模型特定特殊标记。在此处添加它们，以确保在将 `skip_special_tokens` 设置为 True 进行解码时跳过这些标记。如果它们不属于词表的一部分，则会被追加到词表的末尾。

split_special_tokens (`bool`，*可选*，默认为 `False`)：在分词过程中是否应拆分特殊标记。传入该参数会影响分词器的内部状态。默认行为是不拆分特殊标记。这意味着，如果 `<s>` 是 `bos_token`，则 `tokenizer.tokenize("<s>") = ['<s>`]。否则，如果 `split_special_tokens=True`，则 `tokenizer.tokenize("<s>")` 将返回 `['<','s', '>']`。

基于 SentencePiece 的分词器基类，从 sentencepiece.model 文件加载。

继承自 [PreTrainedTokenizer](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.PythonBackend)。

处理分词和特殊标记的所有共享方法，以及下载/缓存/加载预训练分词器以及向词表中添加标记的方法。

该类还以统一的方式在所有分词器之上包含新增的 token，因此我们无需处理各种底层字典结构（BPE、sentencepiece 等）特有的词表扩展方法。

类属性（由派生类重写）

- **vocab_files_names** (`dict[str, str]`) -- 一个字典，其键为模型所需的每个词汇文件在 `__init__` 中的关键字参数名，对应的值为用于保存该文件的文件名（字符串）。
- **pretrained_vocab_files_map** (`dict[str, dict[str, str]]`) -- 一个字典的字典，其中顶层键是模型所需的每个词汇文件在 `__init__` 中的关键字参数名，底层键是预训练模型的 `short-cut-names`，对应的值为关联的预训练词汇文件的 `url`。
- **model_input_names** (`list[str]`) -- 模型前向传播中预期的输入列表。
- **padding_side** (`str`) -- 模型应应用填充的一侧的默认值。应为 `'right'` 或 `'left'`。
- **truncation_side** (`str`) -- 模型应应用截断的一侧的默认值。应为 `'right'` 或 `'left'`。

#### convert_tokens_to_string[[transformers.SentencePieceBackend.convert_tokens_to_string]]

```python
convert_tokens_to_string(tokens: list[str])
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_sentencepiece.py#L232)

将单个字符串中的标记序列（字符串）进行转换。

#### get_vocab[[transformers.SentencePieceBackend.get_vocab]]

```python
get_vocab()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_sentencepiece.py#L104)

以字典形式返回词汇表

#### save_vocabulary[[transformers.SentencePieceBackend.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_sentencepiece.py#L237)

**参数：**

save_directory (`str`) : 用于保存词汇表的目录。

filename_prefix (`str`, *可选*) : 一个可选的前缀，用于添加到保存文件的名称中。

**返回：** `tuple(str)`

已保存文件的路径。

将 sentencepiece 词表（复制原始文件）保存到一个目录中。

## BatchEncoding[[transformers.BatchEncoding]]

#### transformers.BatchEncoding[[transformers.BatchEncoding]]

```python
transformers.BatchEncoding(data: dict[str, Any] | None = None, encoding: EncodingFast | Sequence[EncodingFast] | None = None, tensor_type: None | str | TensorType = None, prepend_batch_axis: bool = False, n_sequences: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L210)

**参数：**

data (`dict`, *可选*) : 由 `__call__`/`encode_plus`/`batch_encode_plus` 方法返回的列表/数组/张量字典（'input_ids'、'attention_mask' 等）。

encoding (`tokenizers.Encoding` 或 `Sequence[tokenizers.Encoding]`，*可选*)：如果分词器是输出额外信息（例如从词/字符空间到 token 空间的映射）的 fast tokenizer，则 `tokenizers.Encoding` 实例或实例列表（用于批次）将保存这些信息。

tensor_type (`Union[None, str, TensorType]`，*可选*)：您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。

prepend_batch_axis (`bool`，*可选*，默认为 `False`)：在转换为张量时是否添加批次维度（参见上方的 `tensor_type`）。请注意，仅当参数 `tensor_type` 被设置时，此参数才会生效，*否则无效*。

n_sequences (`Optional[int]`, *可选*) : 每个编码所表示的输入序列数量（`None` 表示未知，`1` 表示单个序列，`2` 表示一对序列）。

保存 [__call__()](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)、`~tokenization_utils_base.PreTrainedTokenizerBase.encode_plus` 和 `~tokenization_utils_base.PreTrainedTokenizerBase.batch_encode_plus` 方法的输出（tokens、attention_masks 等）。

该类继承自 Python 字典，可用作字典。此外，该类还暴露了实用方法，用于将词/字符空间映射到 token 空间。

#### char_to_token[[transformers.BatchEncoding.char_to_token]]

```python
char_to_token(batch_or_char_index: int, char_index: int | None = None, sequence_index: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L556)

**参数：**

batch_or_char_index (`int`) : 序列在批次中的索引。如果批次仅包含一个序列，则可以是序列中字符的索引

char_index (`int`，*可选*)：如果在 *batch_or_char_index* 中提供了批次索引，则此值可以是序列中字符的索引。

sequence_index (`int`，*可选*，默认为 0)：如果批次中编码了一对序列，此参数可用于指定所提供的字符索引属于该对中的哪个序列（0 或 1）。

**返回：** `int`

该 token 的索引；如果字符索引仅指向一个空白 token，且使用 `trim_offsets=True` 修剪了空白，则为 None。

获取批次中某个序列的编码输出中，包含原始字符串中某个字符的 token 的索引。

可以按以下方式调用：

- 当 batch size 为 1 时，`self.char_to_token(char_index)`
- 当 batch size 大于或等于 1 时，`self.char_to_token(batch_index, char_index)`

当输入序列以预先分词的形式提供（即单词由用户定义）时，此方法尤为适用。在这种情况下，它可以轻松地将编码后的 token 与提供的分词单词进行关联。

#### char_to_word[[transformers.BatchEncoding.char_to_word]]

```python
char_to_word(batch_or_char_index: int, char_index: int | None = None, sequence_index: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L641)

**参数：**

batch_or_char_index (`int`) : 序列在批次中的索引。如果批次仅包含一个序列，则此值可以是原始字符串中字符的索引。

char_index (`int`，*可选*)：如果在 *batch_or_char_index* 中提供了批次索引，则此值可以是原始字符串中字符的索引。

sequence_index (`int`，*可选*，默认为 0)：如果批次中编码了一对序列，此参数可用于指定所提供的字符索引属于该对中的哪个序列（0 或 1）。

**返回：** `int`

包含该字符的单词的索引。

获取批次中某个序列的原始字符串中，与原始字符串中某个字符相对应的单词。

可以按以下方式调用：

- 当 batch size 为 1 时，`self.char_to_word(char_index)`
- 当批大小大于 1 时，使用 `self.char_to_word(batch_index, char_index)`

当输入序列以预先分词的形式提供（即单词由用户定义）时，此方法尤为适用。在这种情况下，它可以轻松地将编码后的 token 与提供的分词单词进行关联。

#### convert_to_tensors[[transformers.BatchEncoding.convert_to_tensors]]

```python
convert_to_tensors(tensor_type: str | TensorType | None = None, prepend_batch_axis: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L680)

**参数：**

tensor_type (`str` 或 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType)，*可选*) : 要使用的张量类型。如果为 `str`，则应为枚举 [TensorType](/docs/transformers/v5.24.0/zh/internal/file_utils#transformers.TensorType) 的某个值。如果为 `None`，则不进行任何修改。

prepend_batch_axis (`bool`，*可选*，默认为 `False`)：是否在转换过程中添加批次维度。

将内部内容转换为张量。

#### sequence_ids[[transformers.BatchEncoding.sequence_ids]]

```python
sequence_ids(batch_index: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L350)

**参数：**

batch_index (`int`，*可选*，默认为 0)：要访问的批次中的索引。

**返回：** `list[Optional[int]]`

一个列表，指示每个 token 对应的序列 ID。由分词器添加的特殊 token 映射为 `None`，其他 token 则映射为其对应序列的索引。

返回一个列表，将每个 token 映射到其原始句子的 id：

- `None` 表示添加在序列周围或序列之间的特殊标记，
- `0` 表示对应于第一个序列中单词的 token，
- `1` 表示在联合编码序列对时，对应于第二个序列中单词的 token。

#### 到[[transformers.BatchEncoding.to]]

```python
to(device: str | torch.device | int, non_blocking: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L774)

**参数：**

device (`str` 或 `torch.device` 或 `int`)：用于放置张量的设备。

non_blocking (`bool`) : 是否异步执行复制。

**返回：** [BatchEncoding](/docs/transformers/v5.24.0/zh/main_classes/tokenizer#transformers.BatchEncoding)

修改后的同一实例。

通过调用 `v.to(device, non_blocking=non_blocking)` 将所有值发送到设备（仅限 PyTorch）。

#### token_to_chars[[transformers.BatchEncoding.token_to_chars]]

```python
token_to_chars(batch_or_token_index: int, token_index: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L517)

**参数：**

batch_or_token_index (`int`) : 序列在批次中的索引。如果批次仅包含一个序列，则此值可以是该序列中令牌的索引。

token_index (`int`，*可选*)：如果在 *batch_or_token_index* 中提供了批次索引，则此值可以是序列中一个或多个 token 的索引。

**返回：** [CharSpan](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.CharSpan)

原始字符串中字符的跨度，或者 None（如果该 token（例如 , ）在原始字符串中不对应任何字符）。

获取批次中序列里编码 token 对应的字符跨度。

字符跨度以 [CharSpan](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.CharSpan) 的形式返回，包含：

- **start** -- 与标记关联的原始字符串中第一个字符的索引。
- **end** -- 与标记关联的原始字符串中最后一个字符之后的字符索引。

可以按以下方式调用：

- 当 batch size 为 1 时，`self.token_to_chars(token_index)`
- 当 batch size 大于或等于 1 时，`self.token_to_chars(batch_index, token_index)`

#### token_to_sequence[[transformers.BatchEncoding.token_to_sequence]]

```python
token_to_sequence(batch_or_token_index: int, token_index: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L387)

**参数：**

batch_or_token_index (`int`) : 序列在批次中的索引。如果批次仅包含一个序列，则此值可以是该序列中令牌的索引。

token_index (`int`，*可选*)：如果在 *batch_or_token_index* 中提供了批次索引，则此值可以是序列中令牌的索引。

**返回：** `int`

包含该 token 的输入序列的索引（对于成对序列中的第一个序列为 `0`，第二个序列为 `1`）。

获取给定 token 所表示的序列的索引。在一般使用场景中，此方法对于单个序列或序列对的第一个序列返回 `0`，对于序列对的第二个序列返回 `1`

可以按以下方式调用：

- 当批处理大小为 1 时，`self.token_to_sequence(token_index)`
- 当 batch size 大于 1 时，使用 `self.token_to_sequence(batch_index, token_index)`

当输入序列以预先分词的形式提供（即单词由用户定义）时，此方法尤为适用。在这种情况下，它可以轻松地将编码后的 token 与提供的分词单词进行关联。

#### token_to_word[[transformers.BatchEncoding.token_to_word]]

```python
token_to_word(batch_or_token_index: int, token_index: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L426)

**参数：**

batch_or_token_index (`int`) : 序列在批次中的索引。如果批次仅包含一个序列，则此值可以是该序列中令牌的索引。

token_index (`int`，*可选*)：如果在 *batch_or_token_index* 中提供了批次索引，则此值可以是序列中令牌的索引。

**返回：** `int`

输入序列中该词的索引。

获取批次中序列里与某个编码 token 相对应（即包含该 token）的单词的索引。

可以按以下方式调用：

- 当批处理大小为 1 时，`self.token_to_word(token_index)`
- 当 batch size 大于 1 时，使用 `self.token_to_word(batch_index, token_index)`

当输入序列以预先分词的形式提供（即单词由用户定义）时，此方法尤为适用。在这种情况下，它可以轻松地将编码后的 token 与提供的分词单词进行关联。

#### tokens[[transformers.BatchEncoding.tokens]]

```python
tokens(batch_index: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L335)

**参数：**

batch_index (`int`，*可选*，默认为 0)：要访问的批次中的索引。

**返回：** `list[str]`

该索引处的 token 列表。

返回给定批次索引处的 token 列表（即输入字符串经过词/子词拆分后、转换为整数索引之前的子部分）（仅适用于快速分词器的输出）。

#### word_ids[[transformers.BatchEncoding.word_ids]]

```python
word_ids(batch_index: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L371)

**参数：**

batch_index (`int`，*可选*，默认为 0)：要访问的批次中的索引。

**返回：** `list[Optional[int]]`

一个列表，指示每个 token 对应的单词。分词器添加的特殊 token 映射为 `None`，其他 token 映射为其对应单词的索引（如果多个 token 是同一个单词的组成部分，它们将映射到相同的单词索引）。

返回一个列表，将快速分词器（fast tokenizer）中的 token 映射到初始句子中对应的实际单词。

#### word_to_chars[[transformers.BatchEncoding.word_to_chars]]

```python
word_to_chars(batch_or_word_index: int, word_index: int | None = None, sequence_index: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L596)

**参数：**

batch_or_word_index (`int`) : 序列在批次中的索引。如果批次仅包含一个序列，则可以是该序列中单词的索引

word_index (`int`，*可选*)：如果在 *batch_or_word_index* 中提供了批次索引，则此值可以是序列中单词的索引。

sequence_index (`int`，*可选*，默认为 0)：如果批次中编码了一对序列，此参数可用于指定所提供的单词索引属于该对中的哪个序列（0 或 1）。

**返回：** `CharSpan`

字符串中关联字符的跨度。CharSpan 是一个 NamedTuple，包含：

- start：原始字符串中与该单词关联的第一个字符的索引
- end：原始字符串中与该单词关联的最后一个字符之后的字符的索引

获取批次中给定序列里指定单词在原始字符串中对应的字符跨度。

字符跨度以 CharSpan 命名元组的形式返回，其中包含：

- start：原始字符串中第一个字符的索引
- end：原始字符串中最后一个字符之后的字符的索引

可以按以下方式调用：

- 当 batch size 为 1 时，`self.word_to_chars(word_index)`
- 当批次大小大于或等于 1 时，`self.word_to_chars(batch_index, word_index)`

#### word_to_tokens[[transformers.BatchEncoding.word_to_tokens]]

```python
word_to_tokens(batch_or_word_index: int, word_index: int | None = None, sequence_index: int = 0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/tokenization_utils_base.py#L464)

**参数：**

batch_or_word_index (`int`) : 序列在批次中的索引。如果批次仅包含一个序列，则可以是该序列中单词的索引。

word_index (`int`，*可选*)：如果在 *batch_or_word_index* 中提供了批次索引，则此值可以是序列中单词的索引。

sequence_index (`int`，*可选*，默认为 0)：如果批次中编码了一对序列，此参数可用于指定所提供的单词索引属于该对中的哪个序列（0 或 1）。

**返回：** ([TokenSpan](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.TokenSpan), *optional*)

编码序列中 token 的跨度。如果没有 token 对应该单词，则返回 `None`。这种情况尤其可能发生在该 token 是用于格式化分词的特殊 token 时。例如，当我们在分词的最开头添加一个类别 token 时。

获取批次中序列里某个单词对应的编码 token 跨度。

Token 跨度以 [TokenSpan](/docs/transformers/v5.24.0/zh/internal/tokenization_utils#transformers.TokenSpan) 的形式返回，包含：

- **start** -- 第一个 token 的索引。
- **end** -- 最后一个 token 之后那个 token 的索引。

可以按以下方式调用：

- 如果批处理大小为 1，则使用 `self.word_to_tokens(word_index, sequence_index: int = 0)`
- 如果批大小大于或等于 1，则使用 `self.word_to_tokens(batch_index, word_index, sequence_index: int = 0)`

当输入序列以预先分词的形式提供（即单词由用户定义）时，此方法尤为适用。在这种情况下，它可以轻松地将编码后的 token 与提供的分词单词进行关联。

