Transformers documentation
分词器
分词器
分词器负责为模型准备输入。该库包含了所有模型的分词器。大多数分词器提供两种实现：完整的 Python 实现，以及基于 Rust 库 🤗 Tokenizers 的“Fast”实现。“Fast”实现支持：
- 在批量分词时尤为显著的速度提升
- 用于在原始字符串（字符和单词）与 token 空间之间进行映射的额外方法（例如，获取包含特定字符的 token 的索引，或获取与特定 token 对应的字符范围）。
基类 PreTrainedTokenizer 和 PreTrainedTokenizerFast 实现了将字符串输入编码为模型输入（见下文）的通用方法，并支持从本地文件或目录，或从库提供的预训练分词器（从 HuggingFace 的 AWS S3 仓库下载）实例化/保存 Python 和 “Fast” 分词器。它们都依赖于包含通用方法的 PreTrainedTokenizerBase。
因此，PreTrainedTokenizer 和 PreTrainedTokenizerFast 实现了使用所有分词器的主要方法：
- 分词（将字符串拆分为子词 token 字符串）、将 token 字符串转换为 id 以及反向转换，以及编码/解码（即分词并转换为整数）。
- 以独立于底层结构（BPE、SentencePiece……）的方式向词表中添加新标记。
- 管理特殊标记（如 mask、句首标记等）：添加这些标记，将它们分配给 tokenizer 的属性以便轻松访问，并确保在标记化过程中它们不会被拆分。
BatchEncoding 保存了 PreTrainedTokenizerBase 编码方法（__call__、encode_plus 和 batch_encode_plus）的输出，并派生自 Python 字典。当分词器是纯 Python 分词器时，该类表现得与标准 Python 字典完全一致，并保存由这些方法计算出的各种模型输入（input_ids、attention_mask…）。当分词器是“Fast”分词器（即由 HuggingFace tokenizers 库提供支持）时，该类还额外提供了若干高级对齐方法，可用于在原始字符串（字符和单词）与 token 空间之间进行映射（例如，获取包含某个给定字符的 token 的索引，或获取与某个给定 token 对应的字符范围）。
多模态分词器
除此之外，每个 tokenizer 都可以是一个“多模态”tokenizer，这意味着 tokenizer 会将所有相关的特殊 token 作为 tokenizer 的属性保存起来，以便更轻松地访问。例如，如果 tokenizer 是从 LLaVA 这样的视觉-语言模型加载的，你就可以通过访问 tokenizer.image_token_id 来获取用作占位符的特殊图像 token。
要为任意类型的分词器启用额外的特殊标记，您需要添加以下代码行并保存分词器。额外的特殊标记不一定与模态相关，可以是模型经常需要访问的任何内容。在下面的代码中，位于 output_dir 的分词器将可以直接访问三个额外的特殊标记。
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
class transformers.PythonBackend
< source >( **kwargs )
参数
- model_max_length (
int, 可选) — 输入到 transformer 模型的最大长度（以 token 数量计）。当使用 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）词元的特殊词元。 - 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', '>']。
所有慢速分词器的基类。
处理分词和特殊标记的所有共享方法，以及下载、缓存和加载预训练分词器，还有向词表中添加标记的方法。
该类还以统一的方式在所有分词器之上包含新增的 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'。
__call__
< source >( text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Nonetext_pair: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Nonetext_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Nonetext_pair_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Noneadd_special_tokens: bool = Truepadding: bool | str | PaddingStrategy = Falsetruncation: bool | str | TruncationStrategy | None = Nonemax_length: int | None = Nonestride: int = 0is_split_into_words: bool = Falsepad_to_multiple_of: int | None = Nonepadding_side: str | None = Nonereturn_tensors: str | TensorType | None = Nonereturn_token_type_ids: bool | None = Nonereturn_attention_mask: bool | None = Nonereturn_overflowing_tokens: bool = Falsereturn_special_tokens_mask: bool = Falsereturn_offsets_mapping: bool = Falsereturn_length: bool = Falseverbose: bool = Truetokenizer_kwargs: dict[str, Any] | None = None**kwargs ) → BatchEncoding
参数
- 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, ，可选, ，默认为False) — 启用并控制填充。接受以下值：True或'longest'：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。'max_length'：填充至由参数max_length指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。False或'do_not_pad'（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
- truncation (
bool,str或 TruncationStrategy, ，可选, ，默认为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），则禁用截断/填充到最大长度的功能。如果未设置或设置为
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, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.ndarray对象。
- return_token_type_ids (
bool, 可选) — 是否返回 token type ID。如果保持默认值，将根据特定分词器的默认设置返回 token type ID，该设置由return_outputs属性定义。 - return_attention_mask (
bool, 可选) — 是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由return_outputs属性定义。 - return_overflowing_tokens (
bool，可选，默认为False) — 是否返回溢出的 token 序列。如果提供了输入 id 的序列对（或序列对批次），且truncation_strategy = longest_first或True，则会抛出错误，而不是返回溢出的 token。 - return_special_tokens_mask (
bool，可选，默认为False) — 是否返回特殊 token 掩码信息。 - return_offsets_mapping (
bool, 可选, 默认为False) — 是否返回(char_start, char_end)每个 token 的。此功能仅在继承自 PreTrainedTokenizerFast 的快速分词器上可用。如果使用 Python 分词器，此方法将抛出
NotImplementedError。 - return_length (
bool，可选，默认为False) — 是否返回编码后输入的长度。 - verbose (
bool，可选，默认为True) — 是否打印更多信息和警告。 - **kwargs — 传递给
self.tokenize()方法
返回值
一个包含以下字段的 BatchEncoding：
-
input_ids — 要输入模型的 token id 列表。
-
token_type_ids — 要输入模型的 token 类型 ID 列表（当
return_token_type_ids=True或self.model_input_names中包含 “token_type_ids” 时）。 -
attention_mask — 索引列表，指定模型应关注哪些 token（当
return_attention_mask=True或 “attention_mask” 位于self.model_input_names中时）。 -
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
< source >( new_tokens: str | AddedToken | Sequence[str | AddedToken]special_tokens: bool = False ) → int
参数
- new_tokens (
str、tokenizers.AddedToken或 str 或tokenizers.AddedToken的序列) — 仅当这些 token 尚未存在于词表中时，才会将其添加进去。tokenizers.AddedToken用于封装字符串 token，以便自定义其行为：例如该 token 是否仅匹配单个单词、是否应去除左侧所有可能的空白字符、是否应去除右侧所有可能的空白字符等。 - 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 可能出现在单词内部，请切换预分词器
示例：
# 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
< source >( special_tokens_dict: dict[str, str | AddedToken | Sequence[str | AddedToken]]replace_extra_special_tokens = True ) → int
参数
- 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 的索引来测试）。bos_token,eos_token,unk_token,sep_token,pad_token,cls_token,mask_token,extra_special_tokens].只有当 Token 尚未存在于词汇表中时（通过检查分词器是否为其分配了
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 等）的字典添加到编码器中，并将其链接到类属性。如果特殊标记不在词汇表中，则将其添加到词汇表中（索引从当前词汇表的最后一个索引开始）。
在向词汇表中添加新 token 时，您应确保同时调整模型的 token 嵌入矩阵大小，使其嵌入矩阵与分词器相匹配。
为此，请使用 resize_token_embeddings() 方法。
使用 add_special_tokens 可确保您的特殊标记能以多种方式使用：
- 在解码时，可以通过设置
skip_special_tokens = True来跳过特殊标记。 - 特殊标记由分词器仔细处理（它们永远不会被拆分），与
AddedTokens类似。 - 您可以轻松使用分词器类的属性（例如
tokenizer.cls_token）来引用特殊标记。这使得开发与模型无关的训练和微调脚本变得十分便捷。
在可能的情况下，所提供的预训练模型已经注册了特殊标记（例如 BertTokenizer 的 cls_token 已注册为 '[CLS]'，XLM 的也已注册为 '</s>'）。
示例：
# 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
< source >( conversation: list[dict[str, str]] | list[list[dict[str, str]]]tools: list[dict | Callable] | None = Nonedocuments: list[dict[str, str]] | None = Nonechat_template: str | None = Noneadd_generation_prompt: bool = Falsecontinue_final_message: bool | str = Falsetokenize: bool = Truesanitize_control_tokens: bool = Falsepadding: bool | str | PaddingStrategy = Falsetruncation: bool = Falsemax_length: int | None = Nonereturn_tensors: str | TensorType | None = Nonereturn_dict: bool = Truereturn_assistant_tokens_mask: bool = Falsetokenizer_kwargs: dict[str, Any] | None = None**kwargs ) → Union[list[int], Dict]
参数
- conversation (Union[list[dict[str, str]], list[list[dict[str, str]]]]) — 一个字典列表，其中每个字典包含 “role” 和 “content” 键，表示迄今为止的聊天历史记录。
- tools (
list[Union[Dict, Callable]], 可选) — 模型可访问的工具（可调用函数）列表。如果模板不支持函数调用，此参数将不生效。每个工具应以 JSON Schema 形式传入，提供该工具的名称、描述和参数类型。更多信息请参阅我们的 工具使用指南。 - documents (
list[dict[str, str]], 可选) — 一个字典列表，表示在执行 RAG（检索增强生成）时模型可访问的文档。如果模板不支持 RAG，此参数将不起作用。我们建议每个文档应为一个包含 “title” 和 “text” 键的字典。 - chat_template (
str，可选) — 用于此转换的 Jinja 模板。通常无需向此参数传入任何值，因为默认会使用模型的模板。 - add_generation_prompt (bool, 可选) — 如果设置此参数，将在格式化输出的末尾追加一个包含指示助手消息起始的 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, 可选, 默认为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, 可选) — 如果设置，将返回特定框架的张量。如果 tokenize 为False. ，则无效。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 NumPynp.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]
一个令牌 ID 列表，表示迄今为止已分词的聊天内容，包括控制令牌。此输出可直接传递给模型，或通过 generate() 等方法进行传递。如果设置了 return_dict，则返回一个包含分词器输出的字典。
将包含 "role" 和 "content" 键的字典列表转换为 token id 列表。此方法旨在与聊天模型配合使用，它会读取分词器的 chat_template 属性，以确定转换时所使用的格式和控制 token。
batch_decode
< source >( sequences: list[int] | list[list[int]] | np.ndarray | torch.Tensorskip_special_tokens: bool = Falseclean_up_tokenization_spaces: bool | None = None**kwargs ) → list[str]
参数
- 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
< source >( token_ids: int | list[int] | list[list[int]] | np.ndarray | torch.Tensorskip_special_tokens: bool = False**kwargs ) → Union[str, list[str]]
使用分词器和词汇表将 id 序列转换为字符串，或将序列列表转换为字符串列表，并支持移除特殊标记和清理分词空格等选项。
类似于执行 self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))。
encode
< source >( text: TextInput | PreTokenizedInput | EncodedInputtext_pair: TextInput | PreTokenizedInput | EncodedInput | None = Noneadd_special_tokens: bool = Truepadding: bool | str | PaddingStrategy = Falsetruncation: bool | str | TruncationStrategy | None = Nonemax_length: int | None = Nonestride: int = 0padding_side: str | None = Nonereturn_tensors: str | TensorType | None = None**kwargs ) → list[int], torch.Tensor, or np.ndarray
参数
- text (
str、list[str]或list[int]) — 要编码的第一个序列。它可以是一个字符串、一个字符串列表（使用tokenize方法分词后的字符串）或一个整数列表（使用convert_tokens_to_ids方法得到的分词字符串 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, ，可选, ，默认为False) — 启用并控制填充。接受以下值：True或'longest'：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。'max_length'：填充至由参数max_length指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。False或'do_not_pad'（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
- truncation (
bool,str或 TruncationStrategy, ，可选, ，默认为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），则禁用截断/填充到最大长度的功能。如果未设置或设置为
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, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.ndarray对象。
- **kwargs — 传递给
.tokenize()方法。
返回值
list[int]、torch.Tensor 或 np.ndarray
文本的标记化 ID。
使用分词器和词汇表将字符串转换为 id（整数）序列。
与执行 self.convert_tokens_to_ids(self.tokenize(text)) 相同。
push_to_hub
< source >( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )
参数
- repo_id (
str) — 要推送分词器（tokenizer）的仓库名称。推送到特定组织时，应包含该组织的名称。 - 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") — 仅适用于模型。分片前检查点的最大大小。分片后的每个检查点大小都将小于该值。如果以字符串形式表示，则必须为数字后跟单位（例如"5MB"）。 - tags (
list[str]，可选) — 要推送到 Hub 的标签列表。
将分词器文件上传到 🤗 Model Hub。
示例：
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
< source >( token_ids_0: list[int]token_ids_1: list[int] | None = None ) → list[int]
通过添加特殊标记，从单个序列或序列对构建模型输入。
该方法会根据分词器的 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
< source >( token_ids_0: list[int]token_ids_1: list[int] | None = None ) → list[int]
创建一个掩码，该掩码由传入的两个序列生成，用于序列对分类任务。
此方法会根据分词器的配置属性动态构建 token 类型 ID：
token_type_ids_pattern：要使用的模式（“all_zeros”或“bert_style”）token_type_ids_include_special_tokens：在长度计算中是否考虑特殊标记
示例：
# 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以 token 到索引的字典形式返回词汇表中新增的 token。由于目前即使 token 已存在于词汇表中，我们仍会将其添加，因此结果可能与快速调用不同。这一点应当改进。
get_special_tokens_mask
< source >( token_ids_0: listtoken_ids_1: list | None = Nonealready_has_special_tokens: bool = False ) → A list of integers in the range [0, 1]
从未添加特殊标记的标记列表中获取序列 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
< source >( pair: bool = False ) → int
在编码包含特殊标记的序列时，返回所添加标记的数量。
这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放在训练循环内部。
prepare_for_model
< source >( ids: list[int]pair_ids: list[int] | None = Noneadd_special_tokens: bool = Truepadding: bool | str | transformers.utils.generic.PaddingStrategy = Falsetruncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = Falsemax_length: int | None = Nonestride: int = 0pad_to_multiple_of: int | None = Nonepadding_side: str | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonereturn_token_type_ids: bool | None = Nonereturn_attention_mask: bool | None = Nonereturn_overflowing_tokens: bool = Falsereturn_special_tokens_mask: bool = Falsereturn_length: bool = Falseverbose: bool = Trueprepend_batch_axis: bool = False**kwargs )
准备输入 ID 序列，以便模型使用。添加特殊标记，并进行截断和填充。
prepare_for_tokenization
< source >( text: stris_split_into_words: bool = False**kwargs ) → tuple[str, dict[str, Any]]
在分词之前执行任何必要的转换。
该方法应从 kwargs 中弹出参数，并返回剩余的 kwargs。我们还会在编码流程结束时检查 kwargs，以确保所有参数都已被使用。
save_vocabulary
< source >( save_directory: strfilename_prefix: str | None = None ) → tuple[str, ...]
通用词汇保存模式的默认实现。 将 self.encoder/self.vocab 保存为 JSON，可选地将 self.bpe_ranks 作为合并规则一并保存。 如果不存在词汇表，则返回空元组。
如果分词器需要自定义保存逻辑（例如 SentencePiece 模型、多个词汇表文件或特殊文件格式），请重写此方法。
tokenize
< source >( text: str**kwargs )
使用分词器将字符串转换为标记序列。
truncate_sequences
< source >( ids: list[int]pair_ids: list[int] | None = Nonenum_tokens_to_remove: int = 0truncation_strategy: str | transformers.tokenization_utils_base.TruncationStrategy = 'longest_first'stride: int = 0 )
根据指定的策略截断序列。
PreTrainedTokenizerFast
PreTrainedTokenizerFast 依赖于 tokenizers 库。从 🤗 tokenizers 库获取的 tokenizer 可以非常简单地加载到 🤗 transformers 中。请查看 使用 🤗 tokenizers 中的 tokenizer 页面以了解具体操作方式。
class transformers.TokenizersBackend
< source >( *args**kwargs )
参数
- model_max_length (
int, 可选) — 输入到 transformer 模型的最大长度（以 token 数量计）。当使用 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）词元的特殊词元。 - 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 中的分词器。 - tokenizer_file (
str) — 指向本地 JSON 文件的路径，该文件表示之前序列化的来自 🤗 tokenizers 的tokenizers.Tokenizer对象。
所有快速分词器（封装 HuggingFace tokenizers 库）的基类。
处理分词和特殊标记的所有共享方法，以及用于下载/缓存/加载预训练分词器的方法，还有向词表中添加标记的方法。
该类以统一的方式在所有分词器之上包含新增的 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'。
__call__
< source >( text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Nonetext_pair: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Nonetext_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Nonetext_pair_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = Noneadd_special_tokens: bool = Truepadding: bool | str | PaddingStrategy = Falsetruncation: bool | str | TruncationStrategy | None = Nonemax_length: int | None = Nonestride: int = 0is_split_into_words: bool = Falsepad_to_multiple_of: int | None = Nonepadding_side: str | None = Nonereturn_tensors: str | TensorType | None = Nonereturn_token_type_ids: bool | None = Nonereturn_attention_mask: bool | None = Nonereturn_overflowing_tokens: bool = Falsereturn_special_tokens_mask: bool = Falsereturn_offsets_mapping: bool = Falsereturn_length: bool = Falseverbose: bool = Truetokenizer_kwargs: dict[str, Any] | None = None**kwargs ) → BatchEncoding
参数
- 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, ，可选, ，默认为False) — 启用并控制填充。接受以下值：True或'longest'：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。'max_length'：填充至由参数max_length指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。False或'do_not_pad'（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
- truncation (
bool,str或 TruncationStrategy, ，可选, ，默认为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），则禁用截断/填充到最大长度的功能。如果未设置或设置为
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, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.ndarray对象。
- return_token_type_ids (
bool, 可选) — 是否返回 token type ID。如果保持默认值，将根据特定分词器的默认设置返回 token type ID，该设置由return_outputs属性定义。 - return_attention_mask (
bool, 可选) — 是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由return_outputs属性定义。 - return_overflowing_tokens (
bool，可选，默认为False) — 是否返回溢出的 token 序列。如果提供了输入 id 的序列对（或序列对批次），且truncation_strategy = longest_first或True，则会抛出错误，而不是返回溢出的 token。 - return_special_tokens_mask (
bool，可选，默认为False) — 是否返回特殊 token 掩码信息。 - return_offsets_mapping (
bool, 可选, 默认为False) — 是否返回(char_start, char_end)每个 token 的。此功能仅在继承自 PreTrainedTokenizerFast 的快速分词器上可用。如果使用 Python 分词器，此方法将抛出
NotImplementedError。 - return_length (
bool，可选，默认为False) — 是否返回编码后输入的长度。 - verbose (
bool，可选，默认为True) — 是否打印更多信息和警告。 - **kwargs — 传递给
self.tokenize()方法
返回值
一个包含以下字段的 BatchEncoding：
-
input_ids — 要输入模型的 token id 列表。
-
token_type_ids — 要输入模型的 token 类型 ID 列表（当
return_token_type_ids=True或self.model_input_names中包含 “token_type_ids” 时）。 -
attention_mask — 索引列表，指定模型应关注哪些 token（当
return_attention_mask=True或 “attention_mask” 位于self.model_input_names中时）。 -
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
< source >( new_tokens: str | AddedToken | Sequence[str | AddedToken]special_tokens: bool = False ) → int
参数
- new_tokens (
str、tokenizers.AddedToken或 str 或tokenizers.AddedToken的序列) — 仅当这些 token 尚未存在于词表中时，才会将其添加进去。tokenizers.AddedToken用于封装字符串 token，以便自定义其行为：例如该 token 是否仅匹配单个单词、是否应去除左侧所有可能的空白字符、是否应去除右侧所有可能的空白字符等。 - 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 可能出现在单词内部，请切换预分词器
示例：
# 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
< source >( special_tokens_dict: dict[str, str | AddedToken | Sequence[str | AddedToken]]replace_extra_special_tokens = True ) → int
参数
- 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 的索引来测试）。bos_token,eos_token,unk_token,sep_token,pad_token,cls_token,mask_token,extra_special_tokens].只有当 Token 尚未存在于词汇表中时（通过检查分词器是否为其分配了
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 等）的字典添加到编码器中，并将其链接到类属性。如果特殊标记不在词汇表中，则将其添加到词汇表中（索引从当前词汇表的最后一个索引开始）。
在向词汇表中添加新 token 时，您应确保同时调整模型的 token 嵌入矩阵大小，使其嵌入矩阵与分词器相匹配。
为此，请使用 resize_token_embeddings() 方法。
使用 add_special_tokens 可确保您的特殊标记能以多种方式使用：
- 在解码时，可以通过设置
skip_special_tokens = True来跳过特殊标记。 - 特殊标记由分词器仔细处理（它们永远不会被拆分），与
AddedTokens类似。 - 您可以轻松使用分词器类的属性（例如
tokenizer.cls_token）来引用特殊标记。这使得开发与模型无关的训练和微调脚本变得十分便捷。
在可能的情况下，所提供的预训练模型已经注册了特殊标记（例如 BertTokenizer 的 cls_token 已注册为 '[CLS]'，XLM 的也已注册为 '</s>'）。
示例：
# 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
< source >( conversation: list[dict[str, str]] | list[list[dict[str, str]]]tools: list[dict | Callable] | None = Nonedocuments: list[dict[str, str]] | None = Nonechat_template: str | None = Noneadd_generation_prompt: bool = Falsecontinue_final_message: bool | str = Falsetokenize: bool = Truesanitize_control_tokens: bool = Falsepadding: bool | str | PaddingStrategy = Falsetruncation: bool = Falsemax_length: int | None = Nonereturn_tensors: str | TensorType | None = Nonereturn_dict: bool = Truereturn_assistant_tokens_mask: bool = Falsetokenizer_kwargs: dict[str, Any] | None = None**kwargs ) → Union[list[int], Dict]
参数
- conversation (Union[list[dict[str, str]], list[list[dict[str, str]]]]) — 一个字典列表，其中每个字典包含 “role” 和 “content” 键，表示迄今为止的聊天历史记录。
- tools (
list[Union[Dict, Callable]], 可选) — 模型可访问的工具（可调用函数）列表。如果模板不支持函数调用，此参数将不生效。每个工具应以 JSON Schema 形式传入，提供该工具的名称、描述和参数类型。更多信息请参阅我们的 工具使用指南。 - documents (
list[dict[str, str]], 可选) — 一个字典列表，表示在执行 RAG（检索增强生成）时模型可访问的文档。如果模板不支持 RAG，此参数将不起作用。我们建议每个文档应为一个包含 “title” 和 “text” 键的字典。 - chat_template (
str，可选) — 用于此转换的 Jinja 模板。通常无需向此参数传入任何值，因为默认会使用模型的模板。 - add_generation_prompt (bool, 可选) — 如果设置此参数，将在格式化输出的末尾追加一个包含指示助手消息起始的 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, 可选, 默认为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, 可选) — 如果设置，将返回特定框架的张量。如果 tokenize 为False. ，则无效。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 NumPynp.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]
一个令牌 ID 列表，表示迄今为止已分词的聊天内容，包括控制令牌。此输出可直接传递给模型，或通过 generate() 等方法进行传递。如果设置了 return_dict，则返回一个包含分词器输出的字典。
将包含 "role" 和 "content" 键的字典列表转换为 token id 列表。此方法旨在与聊天模型配合使用，它会读取分词器的 chat_template 属性，以确定转换时所使用的格式和控制 token。
batch_decode
< source >( sequences: list[int] | list[list[int]] | np.ndarray | torch.Tensorskip_special_tokens: bool = Falseclean_up_tokenization_spaces: bool | None = None**kwargs ) → list[str]
参数
- 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
< source >( token_ids: int | list[int] | list[list[int]] | np.ndarray | torch.Tensorskip_special_tokens: bool = False**kwargs ) → Union[str, list[str]]
使用分词器和词汇表将 id 序列转换为字符串，或将序列列表转换为字符串列表，并支持移除特殊标记和清理分词空格等选项。
类似于执行 self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))。
encode
< source >( text: TextInput | PreTokenizedInput | EncodedInputtext_pair: TextInput | PreTokenizedInput | EncodedInput | None = Noneadd_special_tokens: bool = Truepadding: bool | str | PaddingStrategy = Falsetruncation: bool | str | TruncationStrategy | None = Nonemax_length: int | None = Nonestride: int = 0padding_side: str | None = Nonereturn_tensors: str | TensorType | None = None**kwargs ) → list[int], torch.Tensor, or np.ndarray
参数
- text (
str、list[str]或list[int]) — 要编码的第一个序列。它可以是一个字符串、一个字符串列表（使用tokenize方法分词后的字符串）或一个整数列表（使用convert_tokens_to_ids方法得到的分词字符串 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, ，可选, ，默认为False) — 启用并控制填充。接受以下值：True或'longest'：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。'max_length'：填充至由参数max_length指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。False或'do_not_pad'（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
- truncation (
bool,str或 TruncationStrategy, ，可选, ，默认为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），则禁用截断/填充到最大长度的功能。如果未设置或设置为
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, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.ndarray对象。
- **kwargs — 传递给
.tokenize()方法。
返回值
list[int]、torch.Tensor 或 np.ndarray
文本的标记化 ID。
使用分词器和词汇表将字符串转换为 id（整数）序列。
与执行 self.convert_tokens_to_ids(self.tokenize(text)) 相同。
push_to_hub
< source >( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )
参数
- repo_id (
str) — 要推送分词器（tokenizer）的仓库名称。推送到特定组织时，应包含该组织的名称。 - 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") — 仅适用于模型。分片前检查点的最大大小。分片后的每个检查点大小都将小于该值。如果以字符串形式表示，则必须为数字后跟单位（例如"5MB"）。 - tags (
list[str]，可选) — 要推送到 Hub 的标签列表。
将分词器文件上传到 🤗 Model Hub。
示例：
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")从可用的序列化文件（tokenizer.json、sentencepiece 模型、tekken.json、vocab/merges）构建 tokenizers.Tokenizer 后端。
以字典形式返回词汇表中新增的 token 及其对应的索引。
num_special_tokens_to_add
< source >( pair: bool = False ) → int
在编码包含特殊标记的序列时，返回所添加标记的数量。
这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放在训练循环内部。
save_pretrained
< source >( save_directory: str | os.PathLikelegacy_format: bool | None = Nonefilename_prefix: str | None = Nonepush_to_hub: bool = Falsesave_format: str | None = None**kwargs ) → A tuple of str
参数
- save_format (
str, 可选) —"mistral"表示通过复制原始文件以原生tekken.json格式保存（要求原始 tekken 词汇文件可用）。保存时文件名会规范化为tekken.json，且实例化的分词器必须与其完全匹配。"hf"或None表示使用默认的 HuggingFace 格式。 - kwargs (
dict[str, Any]，可选) — 传递给 push_to_hub() 方法的额外关键字参数。
返回值
str 的元组
已保存的文件。
保存完整的分词器状态。
扩展了 save_pretrained() 以支持 save_format，适用于从原生词汇表文件（例如 Mistral 的 tekken.json）转换而来的分词器。有关 legacy_format、filename_prefix 和 push_to_hub，请参阅基础方法。
set_truncation_and_padding
< source >( padding_strategy: PaddingStrategytruncation_strategy: TruncationStrategymax_length: intstride: intpad_to_multiple_of: int | Nonepadding_side: str | None )
参数
- padding_strategy (PaddingStrategy) — 将应用于输入的填充类型
- truncation_strategy (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
< source >( text_iteratorvocab_sizelength = Nonenew_special_tokens = Nonespecial_tokens_map = None**kwargs ) → PreTrainedTokenizerFast
参数
- 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 的额外关键字参数。
一个与原始分词器类型相同的新分词器，在 text_iterator 上训练得到。
使用与当前分词器相同的默认设置（包括特殊标记和分词流程），在新的语料库上训练一个分词器。
使用当前的 bos_token 和 eos_token 更新底层的后处理器。
PythonBackend
class transformers.PythonBackend
< source >( **kwargs )
参数
- model_max_length (
int, 可选) — 输入到 transformer 模型的最大长度（以 token 数量计）。当使用 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）词元的特殊词元。 - 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', '>']。
所有慢速分词器的基类。
处理分词和特殊标记的所有共享方法，以及下载、缓存和加载预训练分词器，还有向词表中添加标记的方法。
该类还以统一的方式在所有分词器之上包含新增的 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
< source >( token_ids_0: list[int]token_ids_1: list[int] | None = None ) → list[int]
通过添加特殊标记，从单个序列或序列对构建模型输入。
该方法会根据分词器的 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
< source >( token_ids_0: list[int]token_ids_1: list[int] | None = None ) → list[int]
创建一个掩码，该掩码由传入的两个序列生成，用于序列对分类任务。
此方法会根据分词器的配置属性动态构建 token 类型 ID：
token_type_ids_pattern：要使用的模式（“all_zeros”或“bert_style”）token_type_ids_include_special_tokens：在长度计算中是否考虑特殊标记
示例：
# 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以 token 到索引的字典形式返回词汇表中新增的 token。由于目前即使 token 已存在于词汇表中，我们仍会将其添加，因此结果可能与快速调用不同。这一点应当改进。
get_special_tokens_mask
< source >( token_ids_0: listtoken_ids_1: list | None = Nonealready_has_special_tokens: bool = False ) → A list of integers in the range [0, 1]
从未添加特殊标记的标记列表中获取序列 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
< source >( pair: bool = False ) → int
在编码包含特殊标记的序列时，返回所添加标记的数量。
这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放在训练循环内部。
prepare_for_model
< source >( ids: list[int]pair_ids: list[int] | None = Noneadd_special_tokens: bool = Truepadding: bool | str | transformers.utils.generic.PaddingStrategy = Falsetruncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = Falsemax_length: int | None = Nonestride: int = 0pad_to_multiple_of: int | None = Nonepadding_side: str | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonereturn_token_type_ids: bool | None = Nonereturn_attention_mask: bool | None = Nonereturn_overflowing_tokens: bool = Falsereturn_special_tokens_mask: bool = Falsereturn_length: bool = Falseverbose: bool = Trueprepend_batch_axis: bool = False**kwargs )
准备输入 ID 序列，以便模型使用。添加特殊标记，并进行截断和填充。
prepare_for_tokenization
< source >( text: stris_split_into_words: bool = False**kwargs ) → tuple[str, dict[str, Any]]
在分词之前执行任何必要的转换。
该方法应从 kwargs 中弹出参数，并返回剩余的 kwargs。我们还会在编码流程结束时检查 kwargs，以确保所有参数都已被使用。
save_vocabulary
< source >( save_directory: strfilename_prefix: str | None = None ) → tuple[str, ...]
通用词汇保存模式的默认实现。 将 self.encoder/self.vocab 保存为 JSON，可选地将 self.bpe_ranks 作为合并规则一并保存。 如果不存在词汇表，则返回空元组。
如果分词器需要自定义保存逻辑（例如 SentencePiece 模型、多个词汇表文件或特殊文件格式），请重写此方法。
tokenize
< source >( text: str**kwargs )
使用分词器将字符串转换为标记序列。
truncate_sequences
< source >( ids: list[int]pair_ids: list[int] | None = Nonenum_tokens_to_remove: int = 0truncation_strategy: str | transformers.tokenization_utils_base.TruncationStrategy = 'longest_first'stride: int = 0 )
根据指定的策略截断序列。
TokenizersBackend
class transformers.TokenizersBackend
< source >( *args**kwargs )
参数
- model_max_length (
int, 可选) — 输入到 transformer 模型的最大长度（以 token 数量计）。当使用 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）词元的特殊词元。 - 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 中的分词器。 - tokenizer_file (
str) — 指向本地 JSON 文件的路径，该文件表示之前序列化的来自 🤗 tokenizers 的tokenizers.Tokenizer对象。
所有快速分词器（封装 HuggingFace tokenizers 库）的基类。
处理分词和特殊标记的所有共享方法，以及用于下载/缓存/加载预训练分词器的方法，还有向词表中添加标记的方法。
该类以统一的方式在所有分词器之上包含新增的 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'。
从可用的序列化文件（tokenizer.json、sentencepiece 模型、tekken.json、vocab/merges）构建 tokenizers.Tokenizer 后端。
以字典形式返回词汇表中新增的 token 及其对应的索引。
num_special_tokens_to_add
< source >( pair: bool = False ) → int
在编码包含特殊标记的序列时，返回所添加标记的数量。
这会编码一个虚拟输入并检查新增的 token 数量，因此效率不高。请勿将其放在训练循环内部。
save_pretrained
< source >( save_directory: str | os.PathLikelegacy_format: bool | None = Nonefilename_prefix: str | None = Nonepush_to_hub: bool = Falsesave_format: str | None = None**kwargs ) → A tuple of str
参数
- save_format (
str, 可选) —"mistral"表示通过复制原始文件以原生tekken.json格式保存（要求原始 tekken 词汇文件可用）。保存时文件名会规范化为tekken.json，且实例化的分词器必须与其完全匹配。"hf"或None表示使用默认的 HuggingFace 格式。 - kwargs (
dict[str, Any]，可选) — 传递给 push_to_hub() 方法的额外关键字参数。
返回值
str 的元组
已保存的文件。
保存完整的分词器状态。
扩展了 save_pretrained() 以支持 save_format，适用于从原生词汇表文件（例如 Mistral 的 tekken.json）转换而来的分词器。有关 legacy_format、filename_prefix 和 push_to_hub，请参阅基础方法。
set_truncation_and_padding
< source >( padding_strategy: PaddingStrategytruncation_strategy: TruncationStrategymax_length: intstride: intpad_to_multiple_of: int | Nonepadding_side: str | None )
参数
- padding_strategy (PaddingStrategy) — 将应用于输入的填充类型
- truncation_strategy (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
< source >( text_iteratorvocab_sizelength = Nonenew_special_tokens = Nonespecial_tokens_map = None**kwargs ) → PreTrainedTokenizerFast
参数
- 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 的额外关键字参数。
一个与原始分词器类型相同的新分词器，在 text_iterator 上训练得到。
使用与当前分词器相同的默认设置（包括特殊标记和分词流程），在新的语料库上训练一个分词器。
使用当前的 bos_token 和 eos_token 更新底层的后处理器。
SentencePieceBackend
class transformers.SentencePieceBackend
< source >( **kwargs )
参数
- model_max_length (
int, 可选) — 输入到 transformer 模型的最大长度（以 token 数量计）。当使用 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）词元的特殊词元。 - 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。
处理分词和特殊标记的所有共享方法，以及下载、缓存和加载预训练分词器，还有向词表中添加标记的方法。
该类还以统一的方式在所有分词器之上包含新增的 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'。
将单个字符串中的标记序列（字符串）进行转换。
以字典形式返回词汇表
save_vocabulary
< source >( save_directory: strfilename_prefix: str | None = None ) → tuple(str)
将 sentencepiece 词表（复制原始文件）保存到一个目录中。
BatchEncoding
类 transformers.BatchEncoding
< source >( data: dict[str, Any] | None = Noneencoding: EncodingFast | Sequence[EncodingFast] | None = Nonetensor_type: None | str | TensorType = Noneprepend_batch_axis: bool = Falsen_sequences: int | None = None )
参数
- data (
dict, 可选) — 由__call__/encode_plus/batch_encode_plus方法返回的列表/数组/张量字典（‘input_ids’、‘attention_mask’ 等）。 - encoding（
tokenizers.Encoding或Sequence[tokenizers.Encoding]，可选） — 如果分词器是快速分词器，并且会输出诸如从单词/字符空间到 token 空间的映射等附加信息，则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()、~tokenization_utils_base.PreTrainedTokenizerBase.encode_plus 和 ~tokenization_utils_base.PreTrainedTokenizerBase.batch_encode_plus 方法的输出（tokens、attention_masks 等）。
该类派生自 Python 字典，可用作字典。此外，该类还暴露了实用方法，用于将词/字符空间映射到 token 空间。
char_to_token
< source >( batch_or_char_index: intchar_index: int | None = Nonesequence_index: int = 0 ) → int
获取批次中某个序列的编码输出中，包含原始字符串中某个字符的 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
< source >( batch_or_char_index: intchar_index: int | None = Nonesequence_index: int = 0 ) → int
获取批次中某个序列的原始字符串中，与原始字符串中某个字符相对应的单词。
可以按以下方式调用：
- 当 batch size 为 1 时，
self.char_to_word(char_index) - 当批大小大于 1 时，使用
self.char_to_word(batch_index, char_index)
当输入序列以预分词序列的形式提供（即单词由用户定义）时，此方法尤为适用。在这种情况下，它可以轻松地将编码后的 token 与提供的分词单词进行关联。
convert_to_tensors
< source >( tensor_type: str | TensorType | None = Noneprepend_batch_axis: bool = False )
参数
- tensor_type (
str或 TensorType，可选) — 要使用的张量类型。如果为str，则应为枚举 TensorType 的某个值。如果为None，则不进行任何修改。 - prepend_batch_axis (
bool，可选，默认为False) — 是否在转换过程中添加批次维度。
将内部内容转换为张量。
sequence_ids
< source >( batch_index: int = 0 ) → list[Optional[int]]
返回一个列表，将每个 token 映射到其原始句子的 id：
None表示添加在序列周围或序列之间的特殊标记，0表示对应于第一个序列中单词的 token，1表示在联合编码序列对时，对应于第二个序列中单词的 token。
到
< source >( device: str | torch.device | intnon_blocking: bool = False ) → BatchEncoding
参数
返回值
修改后的同一实例。
通过调用 v.to(device, non_blocking=non_blocking) 将所有值发送到设备（仅限 PyTorch）。
token_to_chars
< source >( batch_or_token_index: inttoken_index: int | None = None ) → CharSpan
获取批次中序列里编码 token 对应的字符跨度。
字符跨度以 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
< source >( batch_or_token_index: inttoken_index: int | None = None ) → int
获取给定 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
< source >( batch_or_token_index: inttoken_index: int | None = None ) → int
获取批次中序列里与某个编码 token 相对应（即包含该 token）的单词的索引。
可以按以下方式调用：
- 当批处理大小为 1 时，
self.token_to_word(token_index) - 当 batch size 大于 1 时，使用
self.token_to_word(batch_index, token_index)
当输入序列以预分词序列的形式提供（即单词由用户定义）时，此方法尤为适用。在这种情况下，它可以轻松地将编码后的 token 与提供的分词单词进行关联。
令牌
< source >( batch_index: int = 0 ) → list[str]
返回给定批次索引处的 token 列表（即输入字符串经过分词/子词切分后、转换为整数索引之前的子部分）（仅适用于快速分词器的输出）。
word_ids
< source >( batch_index: int = 0 ) → list[Optional[int]]
返回一个列表，将快速分词器（fast tokenizer）中的 token 映射到初始句子中对应的实际单词。
word_to_chars
< source >( batch_or_word_index: intword_index: int | None = Nonesequence_index: int = 0 ) → CharSpan
参数
- 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
< source >( batch_or_word_index: intword_index: int | None = Nonesequence_index: int = 0 ) → (TokenSpan, optional)
参数
- batch_or_word_index (
int) — 批次中序列的索引。如果批次仅包含一个序列，则可以是序列中单词的索引。 - word_index (
int, 可选) — 如果在 batch_or_word_index 中提供了批次索引，则此参数可以是序列中单词的索引。 - sequence_index (
int，可选，默认为 0) — 如果批次中编码了一对序列，可以使用此参数来指定所提供的单词索引属于该对中的哪个序列（0 或 1）。
返回值
(TokenSpan，可选)
编码序列中 token 的跨度。如果没有 token 对应该单词，则返回 None。这种情况尤其可能发生在该 token 是用于格式化分词的特殊 token 时。例如，当我们在分词的最开头添加一个类别 token 时。
获取批次中序列里某个单词对应的编码 token 跨度。
Token 跨度以 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 与提供的分词单词进行关联。