分词器
分词器负责为模型准备输入。该库包含所有模型的分词器。大多数分词器有两种形式:完整的 Python 实现和基于 Rust 库 🤗 Tokenizers 的“快速”实现。“快速”实现允许
- 特别是在进行批量分词时显着提高速度,并且
- 提供其他方法来映射原始字符串(字符和单词)和标记空间(例如,获取包含给定字符的标记的索引或与给定标记对应的字符范围)。
基类 PreTrainedTokenizer 和 PreTrainedTokenizerFast 实现了将字符串输入编码为模型输入的常用方法(见下文)以及从本地文件或目录或从库提供的预训练分词器(从 HuggingFace 的 AWS S3 存储库下载)实例化/保存 Python 和“快速”分词器。它们都依赖于包含常用方法的 PreTrainedTokenizerBase 和 SpecialTokensMixin。
PreTrainedTokenizer 和 PreTrainedTokenizerFast 因此实现了使用所有分词器的主要方法
- 分词(将字符串拆分为子词标记字符串)、将标记字符串转换为 ID 并转换回来,以及编码/解码(即分词并转换为整数)。
- 以独立于底层结构(BPE、SentencePiece...)的方式向词汇表添加新标记。
- 管理特殊标记(如掩码、句子开头等):添加它们,将它们分配给分词器中的属性以便于访问,并确保它们在分词期间不会被拆分。
BatchEncoding 保存 PreTrainedTokenizerBase 的编码方法(__call__
、encode_plus
和 batch_encode_plus
)的输出,并且是从 Python 字典派生的。当分词器是纯 Python 分词器时,此类的行为类似于标准 Python 字典,并保存由这些方法计算的各种模型输入(input_ids
、attention_mask
...)。当分词器是“快速”分词器时(即由 HuggingFace 分词器库 支持),此类还提供了几种高级对齐方法,可用于在原始字符串(字符和单词)和标记空间之间进行映射(例如,获取包含给定字符的标记的索引或与给定标记对应的字符范围)。
PreTrainedTokenizer
类 transformers.PreTrainedTokenizer
< 源代码 >( **kwargs )
参数
- model_max_length (
int
, 可选) — Transformer 模型输入的最大长度(以标记数表示)。当使用 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
,可选) — 表示句子开头的特殊标记。将与self.bos_token
和self.bos_token_id
相关联。 - eos_token (
str
或tokenizers.AddedToken
,可选) — 表示句子结尾的特殊标记。将与self.eos_token
和self.eos_token_id
相关联。 - unk_token (
str
或tokenizers.AddedToken
,可选) — 表示词汇表外标记的特殊标记。将与self.unk_token
和self.unk_token_id
相关联。 - sep_token (
str
或tokenizers.AddedToken
,可选) — 用于分隔同一输入中两个不同句子的特殊标记(例如,BERT 使用)。将与self.sep_token
和self.sep_token_id
关联。 - pad_token (
str
或tokenizers.AddedToken
,可选) — 用于使标记数组大小相同以便进行批处理的特殊标记。然后,注意力机制或损失计算将忽略它。将与self.pad_token
和self.pad_token_id
关联。 - cls_token (
str
或tokenizers.AddedToken
,可选) — 表示输入类别的特殊标记(例如,BERT 使用)。将与self.cls_token
和self.cls_token_id
关联。 - mask_token (
str
或tokenizers.AddedToken
,可选) — 表示被掩盖标记的特殊标记(由掩盖语言建模预训练目标使用,如 BERT)。将与self.mask_token
和self.mask_token_id
关联。 - additional_special_tokens (元组或
str
或tokenizers.AddedToken
列表,可选) — 一组或一列额外的特殊标记。将它们添加到此处以确保在将skip_special_tokens
设置为 True 时解码时跳过它们。如果它们不属于词汇表,则会将它们添加到词汇表的末尾。 - clean_up_tokenization_spaces (
bool
,可选,默认为True
) — 模型是否应清除在标记化过程中拆分输入文本时添加的空格。 - split_special_tokens (
bool
,可选,默认为False
) — 是否应在标记化过程中拆分特殊标记。传递将影响标记器的内部状态。默认行为是不拆分特殊标记。这意味着如果<s>
是bos_token
,则tokenizer.tokenize("<s>") = ['<s>
]。否则,如果split_special_tokens=True
,则tokenizer.tokenize("<s>")
将给出['<','s', '>']
。
所有慢速分词器的基类。
处理用于标记化和特殊标记的所有共享方法,以及下载/缓存/加载预训练标记器以及向词汇表添加标记的方法。
此类还以统一的方式包含所有标记器之上的已添加标记,因此我们不必处理各种底层字典结构(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__
< 源代码 >( text: Union = None text_pair: Union = None text_target: Union = None text_pair_target: Union = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 is_split_into_words: bool = False pad_to_multiple_of: Optional = None padding_side: Optional = None return_tensors: Union = None return_token_type_ids: Optional = None return_attention_mask: Optional = None return_overflowing_tokens: bool = False return_special_tokens_mask: bool = False return_offsets_mapping: bool = False return_length: bool = False verbose: bool = True **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
(以消除与一批序列的歧义)。 - 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
指定的最大长度,或者如果未提供该参数,则截断到模型可接受的最大输入长度。如果提供了一对序列(或一批序列对),这将逐个标记地截断,从最长序列中删除一个标记。'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
时返回的溢出标记将包含来自返回的截断序列末尾的一些标记,以在截断序列和溢出序列之间提供一些重叠。此参数的值定义了重叠标记的数量。 - is_split_into_words (
bool
,可选,默认为False
) — 输入是否已经预先标记化(例如,按空格分割成单词)。如果设置为True
,则标记器假定输入已经分割成单词(例如,通过按空格分割),它将对其进行标记化。这对于 NER 或标记分类很有用。 - pad_to_multiple_of (
int
,可选) — 如果设置,则将序列填充到所提供值的倍数。需要激活padding
。这对于在计算能力>= 7.5
(Volta)的 NVIDIA 硬件上使用 Tensor Cores 特别有用。 - **padding_side** (
str
,*可选*) — 模型应该应用填充的一侧。应该在 ['right','left'] 中选择。默认值取自同名的类属性。 - **return_tensors** (
str
或 TensorType,*可选*) — 如果设置,将返回张量而不是 Python 整数列表。可接受的值为:'tf'
:返回 TensorFlowtf.constant
对象。'pt'
:返回 PyTorchtorch.Tensor
对象。'np'
:返回 Numpynp.ndarray
对象。
- **return_token_type_ids** (
bool
,*可选*) — 是否返回词类型 ID。如果保留默认值,将根据特定分词器的默认值返回词类型 ID,由return_outputs
属性定义。 - **return_attention_mask** (
bool
,*可选*) — 是否返回注意力掩码。如果保留默认值,将根据特定分词器的默认值返回注意力掩码,由return_outputs
属性定义。 - **return_overflowing_tokens** (
bool
,*可选*,默认为False
) — 是否返回溢出的词序列。如果提供了一对输入 ID 序列(或一批序列对),并且truncation_strategy = longest_first
或True
,则会引发错误而不是返回溢出的词。 - **return_special_tokens_mask** (
bool
,*可选*,默认为False
) — 是否返回特殊词掩码信息。 - **return_offsets_mapping** (
bool
, *可选*, 默认值为False
) — 是否为每个词返回(char_start, char_end)
。这仅在继承自 PreTrainedTokenizerFast 的快速分词器上可用,如果使用 Python 的分词器,此方法将引发
NotImplementedError
。 - **return_length** (
bool
, *可选*, 默认值为False
) — 是否返回编码输入的长度。 - **verbose** (
bool
, *可选*, 默认值为True
) — 是否打印更多信息和警告。 **kwargs — 传递给self.tokenize()
方法
返回值
一个 BatchEncoding,具有以下字段
-
**input_ids** — 要输入到模型的词 ID 列表。
-
**token_type_ids** — 要输入到模型的词类型 ID 列表(当
return_token_type_ids=True
或 “token_type_ids” 在self.model_input_names
中时)。 -
**attention_mask** — 指定模型应关注哪些词的索引列表(当
return_attention_mask=True
或 “attention_mask” 在self.model_input_names
中时)。 -
**overflowing_tokens** — 溢出词序列列表(当指定了
max_length
且return_overflowing_tokens=True
时)。 -
**num_truncated_tokens** — 被截断的词数(当指定了
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: Union special_tokens: bool = False ) → int
参数
- **new_tokens** (
str
,tokenizers.AddedToken
或 str 或tokenizers.AddedToken
的列表) — 仅当词不在词汇表中时才添加。tokenizers.AddedToken
包装字符串词以让你个性化其行为:此词是否应仅匹配单个词,此词是否应删除左侧的所有潜在空格,此词是否应删除右侧的所有潜在空格,等等。 - special_tokens (
bool
,*可选*,默认为False
) — 可用于指定词符是否是特殊词符。这主要会改变规范化行为(例如,像 CLS 或 [MASK] 这样的特殊词符通常不会被小写)。有关 HuggingFace tokenizers 库中
tokenizers.AddedToken
的详细信息,请参阅详细信息。
返回值
int
添加到词汇表中的词符数量。
将新词符列表添加到分词器类。如果新词符不在词汇表中,则将它们添加到词汇表中,索引从当前词汇表的长度开始,并在应用分词算法之前将其隔离。因此,添加的词符和来自分词算法词汇表的词符不会以相同的方式处理。
注意,在向词汇表添加新词符时,您应该确保也调整模型的词符嵌入矩阵的大小,以使其嵌入矩阵与分词器匹配。
为此,请使用 resize_token_embeddings() 方法。
示例
# 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 replace_additional_special_tokens = True ) → int
参数
- special_tokens_dict (str 到 str 或
tokenizers.AddedToken
的字典) — 键应该在预定义的特殊属性列表中: [bos_token
、eos_token
、unk_token
、sep_token
、pad_token
、cls_token
、mask_token
、additional_special_tokens
]。仅当词符尚未出现在词汇表中时才添加它们(通过检查分词器是否将
unk_token
的索引分配给它们来进行测试)。 - replace_additional_special_tokens (
bool
,*可选*,默认为True
) — 如果为True
,则现有的附加特殊词符列表将替换为special_tokens_dict
中提供的列表。否则,将仅扩展self._additional_special_tokens
。在前一种情况下,词符不会从分词器的完整词汇表中删除 - 它们仅被标记为非特殊词符。请记住,这只会影响解码过程中跳过的词符,而不会影响added_tokens_encoder
和added_tokens_decoder
。这意味着先前的additional_special_tokens
仍然是添加的词符,并且不会被模型拆分。
返回值
int
添加到词汇表中的词符数量。
向编码器添加特殊词符字典(eos、pad、cls 等),并将它们链接到类属性。如果特殊词符不在词汇表中,则将它们添加到词汇表中(索引从当前词汇表的最后一个索引开始)。
在向词汇表添加新词符时,您应该确保也调整模型的词符嵌入矩阵的大小,以使其嵌入矩阵与分词器匹配。
为此,请使用 resize_token_embeddings() 方法。
使用 add_special_tokens
将确保您的特殊词符可以通过多种方式使用
- 使用
skip_special_tokens = True
解码时,可以跳过特殊词符。 - 分词器会小心处理特殊词符(它们永远不会被拆分),类似于
AddedTokens
。 - 您可以使用分词器类属性(如
tokenizer.cls_token
)轻松引用特殊词符。这使得开发与模型无关的训练和微调脚本变得容易。
如果可能,特殊词符已为提供的预训练模型注册(例如,BertTokenizer cls_token
已注册为 :obj_“[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: Union tools: Optional = None documents: Optional = None chat_template: Optional = None add_generation_prompt: bool = False continue_final_message: bool = False tokenize: bool = True padding: bool = False truncation: bool = False max_length: Optional = None return_tensors: Union = None return_dict: bool = False return_assistant_tokens_mask: bool = False tokenizer_kwargs: Optional = None **kwargs ) → Union[List[int], Dict]
参数
- conversation (Union[List[Dict[str, str]], List[List[Dict[str, str]]]]) — 由包含“角色”和“内容”键的字典组成的列表,表示到目前为止的聊天历史记录。
- tools (
List[Dict]
, 可选) — 模型可访问的工具(可调用函数)列表。如果模板不支持函数调用,则此参数将不起作用。每个工具都应作为 JSON 模式传递,并提供工具的名称、描述和参数类型。有关更多信息,请参阅我们的 聊天模板指南。 - documents (
List[Dict[str, str]]
, 可选) — 如果模型正在执行 RAG(检索增强生成),则表示模型可访问的文档的字典列表。如果模板不支持 RAG,则此参数将不起作用。我们建议每个文档都应是包含“标题”和“文本”键的字典。请参阅 聊天模板指南 的 RAG 部分,了解使用聊天模板传递文档的示例。 - chat_template (
str
, 可选) — 用于此转换的 Jinja 模板。通常不需要向此参数传递任何内容,因为默认情况下将使用模型的模板。 - add_generation_prompt (布尔值,可选) — 如果设置为 True,则会在格式化输出的末尾添加一个提示符,其中包含指示助手消息开始的标记。这在您希望模型生成响应时非常有用。请注意,此参数将传递给聊天模板,因此模板必须支持此参数才能生效。
- continue_final_message (布尔值,可选) — 如果设置为 True,则聊天将被格式化,以便聊天中的最后一条消息是开放式的,没有任何 EOS 标记。模型将继续此消息,而不是开始新的消息。这允许您为模型“预填充”其响应的一部分。不能与
add_generation_prompt
同时使用。 - tokenize (
布尔值
,默认为True
) — 是否对输出进行分词。如果为False
,则输出将为字符串。 - padding (
布尔值
,默认为False
) — 是否将序列填充到最大长度。如果 tokenize 为False
,则无效。 - truncation (
布尔值
,默认为False
) — 是否在达到最大长度时截断序列。如果 tokenize 为False
,则无效。 - max_length (
整数
,可选) — 用于填充或截断的最大长度(以标记为单位)。如果 tokenize 为False
,则无效。如果未指定,则将使用分词器的max_length
属性作为默认值。 - return_tensors (
字符串
或 TensorType, 可选) — 如果设置,将返回特定框架的张量。如果 tokenize 为False
,则无效。可接受的值为:'tf'
: 返回 TensorFlowtf.Tensor
对象。'pt'
: 返回 PyTorchtorch.Tensor
对象。'np'
: 返回 NumPynp.ndarray
对象。'jax'
: 返回 JAXjnp.ndarray
对象。
- return_dict (
bool
,默认为False
) — 是否返回带有命名输出的字典。如果 tokenize 为False
,则无效。 - tokenizer_kwargs (
Dict[str -- Any]
, *可选*):要传递给分词器的其他关键字参数。 - return_assistant_tokens_mask (
bool
,默认为False
) — 是否返回助手生成token的掩码。对于助手生成的token,掩码将包含 1。对于用户和系统token,掩码将包含 0。此功能仅适用于通过{% generation %}
关键字支持它的聊天模板。 **kwargs — 要传递给模板渲染器的其他关键字参数。聊天模板可以访问。
返回值
Union[List[int], Dict]
表示迄今为止已分词化的聊天的token ID 列表,包括控制token。此输出已准备好传递给模型,可以直接传递,也可以通过 generate()
等方法传递。如果设置了 return_dict
,则将返回分词器输出的字典。
将包含 "role"
和 "content"
键的字典列表转换为token ID 列表。此方法适用于聊天模型,并将读取分词器的 chat_template 属性,以确定转换时要使用的格式和控制token。
batch_decode
< source >( sequences: Union skip_special_tokens: bool = False clean_up_tokenization_spaces: bool = None **kwargs ) → List[str]
参数
- sequences (
Union[List[int], List[List[int]], np.ndarray, torch.Tensor, tf.Tensor]
) — 已分词化的输入 ID 列表。可以使用__call__
方法获取。 - skip_special_tokens (
bool
, *可选*,默认为False
) — 解码时是否删除特殊token。 - clean_up_tokenization_spaces (
bool
,*可选*) — 是否清除分词空格。 如果为None
,则默认为self.clean_up_tokenization_spaces
。 - kwargs (其他关键字参数,*可选*) — 将传递到底层模型特定的解码方法。
返回值
字符串列表
解码后的句子列表。
通过调用 decode 将标记 ID 列表的列表转换为字符串列表。
decode
< source >( token_ids: Union skip_special_tokens: bool = False clean_up_tokenization_spaces: bool = None **kwargs ) → str
参数
- token_ids (
Union[int, List[int], np.ndarray, torch.Tensor, tf.Tensor]
) — 已分词化的输入 ID 列表。 可以使用__call__
方法获取。 - skip_special_tokens (
bool
,*可选*,默认为False
) — 解码时是否删除特殊标记。 - clean_up_tokenization_spaces (
bool
,*可选*) — 是否清除分词空格。 如果为None
,则默认为self.clean_up_tokenization_spaces
。 - kwargs (其他关键字参数,*可选*) — 将传递到底层模型特定的解码方法。
返回值
字符串
解码后的句子。
使用分词器和词汇表将字符串中的id序列进行转换,并提供移除特殊标记和清理分词空格的选项。
类似于执行 self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))
。
encode
< 源代码 >( text: Union text_pair: Union = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 padding_side: Optional = None return_tensors: Union = None **kwargs ) → List[int]
、torch.Tensor
、tf.Tensor
或 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
指定的最大长度,或者如果未提供该参数,则截断到模型可接受的最大输入长度。如果提供了一对序列(或一批序列对),这将逐个标记地截断,从最长序列中删除一个标记。'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
时返回的溢出标记将包含来自返回的截断序列末尾的一些标记,以在截断序列和溢出序列之间提供一些重叠。此参数的值定义重叠标记的数量。 - is_split_into_words (
bool
,可选,默认为False
) — 输入是否已预先分词(例如,按空格拆分)。如果设置为True
,则分词器假定输入已经拆分为单词(例如,通过按空格拆分),它将对其进行分词。这对于 NER 或标记分类很有用。 - pad_to_multiple_of (
int
,可选) — 如果设置,则将序列填充到所提供值的倍数。需要激活padding
。这对于在计算能力>= 7.5
(Volta)的 NVIDIA 硬件上使用 Tensor Cores 特别有用。 - padding_side (
str
,可选) — 模型应在其上应用填充的一侧。应该在 ['right','left'] 之间选择。默认值是从同名类属性中选取的。 - return_tensors (
str
或 TensorType, 可选) — 如果设置,将返回张量而不是 Python 整数列表。可接受的值为:'tf'
:返回 TensorFlowtf.constant
对象。'pt'
:返回 PyTorchtorch.Tensor
对象。'np'
:返回 Numpynp.ndarray
对象。
**kwargs — 传递给
.tokenize()
方法。
返回值
List[int]
、torch.Tensor
、tf.Tensor
或 np.ndarray
文本的标记化 ID。
使用标记器和词汇表将字符串转换为 ID 序列(整数)。
与执行 self.convert_tokens_to_ids(self.tokenize(text))
相同。
push_to_hub
< source >( repo_id: str use_temp_dir: Optional = None commit_message: Optional = None private: Optional = None token: Union = None max_shard_size: Union = '5GB' create_pr: bool = False safe_serialization: bool = True revision: str = None commit_description: str = None tags: Optional = None **deprecated_kwargs )
参数
- repo_id (
str
) — 要将您的分词器推送到哪个存储库的名称。当推送到给定组织时,它应该包含您的组织名称。 - use_temp_dir (
bool
, 可选) — 是否使用临时目录来存储保存的文件,然后再将它们推送到 Hub。如果不存在名为repo_id
的目录,则默认为True
,否则为False
。 - commit_message (
str
, 可选) — 推送时提交的消息。默认为"Upload tokenizer"
。 - private (
bool
, 可选) — 创建的存储库是否应该是私有的。 - token (
bool
或str
,可选) — 用于远程文件 HTTP Bearer 认证的令牌。如果为True
,将使用运行huggingface-cli login
生成的令牌(存储在~/.huggingface
中)。如果未指定repo_url
,则默认为True
。 - max_shard_size (
int
或str
,可选,默认为"5GB"
) — 仅适用于模型。检查点分片前的最大大小。然后,每个检查点分片的大小都将小于此大小。如果表示为字符串,则需要是数字后跟单位(例如"5MB"
)。我们默认将其设置为"5GB"
,以便用户可以在免费层的 Google Colab 实例上轻松加载模型,而不会出现任何 CPU OOM 问题。 - create_pr (
bool
,可选,默认为False
) — 是否使用上传的文件创建 PR 或直接提交。 - safe_serialization (
bool
,可选,默认为True
) — 是否将模型权重转换为 safetensors 格式以实现更安全的序列化。 - revision (
str
,可选) — 要将上传的文件推送到哪个分支。 - commit_description (
str
,可选) — 将创建的提交的描述 - tags (
List[str]
,可选) — 要在 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")
convert_ids_to_tokens
< 源代码 >( ids: Union skip_special_tokens: bool = False ) → str
或 List[str]
使用词汇表和添加的词元,将单个索引或索引序列转换为一个词元或词元序列。
convert_tokens_to_ids
< 源代码 >( tokens: Union ) → int
或 List[int]
使用词汇表将词元字符串(或词元序列)转换为单个整数 ID(或 ID 序列)。
以词元到索引的字典形式返回词汇表中添加的词元。结果可能与快速调用不同,因为目前我们总是添加词元,即使它们已经在词汇表中。这是我们应该改变的地方。
num_special_tokens_to_add
< source >( pair: bool = False ) → int
返回使用特殊标记对序列进行编码时添加的标记数量。
这将编码一个虚拟输入并检查添加的标记数量,因此效率不高。不要将此放入您的训练循环中。
prepare_for_tokenization
< source >( text: str is_split_into_words: bool = False **kwargs ) → Tuple[str, Dict[str, Any]]
在标记化之前执行任何必要的转换。
此方法应从 kwargs 中弹出参数,并返回剩余的 kwargs
。 我们在编码过程结束时测试 kwargs
,以确保所有参数都已使用。
tokenize
< source >( text: str **kwargs ) → List[str]
使用分词器将字符串转换为词符序列。
对于基于词的词汇表,按词进行拆分;对于基于子词的词汇表(BPE/SentencePieces/WordPieces),则拆分为子词。处理添加的词符。
PreTrainedTokenizerFast
PreTrainedTokenizerFast 依赖于 tokenizers 库。从 🤗 tokenizers 库获取的分词器可以非常简单地加载到 🤗 transformers 中。请查看使用 🤗 tokenizers 中的分词器页面,了解如何实现这一点。
类 transformers.PreTrainedTokenizerFast
< source >( *args **kwargs )
参数
- model_max_length (
int
, 可选) — Transformer 模型输入的最大长度(以词符数量表示)。当使用 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
,可选) — 表示句子开头的特殊标记。 将与self.bos_token
和self.bos_token_id
关联。 - eos_token (
str
或tokenizers.AddedToken
,可选) — 表示句子结尾的特殊标记。 将与self.eos_token
和self.eos_token_id
关联。 - unk_token (
str
或tokenizers.AddedToken
,可选) — 表示词汇表外标记的特殊标记。 将与self.unk_token
和self.unk_token_id
关联。 - sep_token (
str
或tokenizers.AddedToken
,可选) — 用于分隔同一输入中两个不同句子的特殊标记(例如 BERT 使用)。 将与self.sep_token
和self.sep_token_id
相关联。 - pad_token (
str
或tokenizers.AddedToken
,可选) — 用于使标记数组大小相同以进行批处理的特殊标记。 然后,注意力机制或损失计算将忽略它。 将与self.pad_token
和self.pad_token_id
相关联。 - cls_token (
str
或tokenizers.AddedToken
,可选) — 代表输入类别的特殊标记(例如 BERT 使用)。 将与self.cls_token
和self.cls_token_id
相关联。 - mask_token (
str
或tokenizers.AddedToken
,可选) — 代表被屏蔽标记的特殊标记(由诸如 BERT 之类的屏蔽语言建模预训练目标使用)。 将与self.mask_token
和self.mask_token_id
相关联。 - additional_special_tokens (元组或
str
或tokenizers.AddedToken
的列表,可选) — 元组或其他特殊标记的列表。 在这里添加它们以确保在使用skip_special_tokens
设置为 True 进行解码时跳过它们。 如果它们不属于词汇表,则将它们添加到词汇表的末尾。 - clean_up_tokenization_spaces (
bool
,可选,默认为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 分词器库)的基类。
处理所有用于分词和特殊标记的共享方法,以及用于下载/缓存/加载预训练分词器的方法,以及将标记添加到词汇表的方法。
此类还以统一的方式包含所有分词器之上的已添加标记,因此我们不必处理各种底层字典结构(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: Union = None text_pair: Union = None text_target: Union = None text_pair_target: Union = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 is_split_into_words: bool = False pad_to_multiple_of: Optional = None padding_side: Optional = None return_tensors: Union = None return_token_type_ids: Optional = None return_attention_mask: Optional = None return_overflowing_tokens: bool = False return_special_tokens_mask: bool = False return_offsets_mapping: bool = False return_length: bool = False verbose: bool = True **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
(以消除与一批序列的歧义)。 - 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
指定的最大长度,如果未提供该参数,则截断到模型可接受的最大输入长度。如果提供了一对序列(或一批序列),这将逐个标记地截断,从最长序列中删除标记。'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
时返回的溢出标记将包含来自返回的截断序列末尾的一些标记,以在截断序列和溢出序列之间提供一些重叠。此参数的值定义了重叠标记的数量。 - is_split_into_words (
bool
, 可选, 默认值为False
) — 输入是否已经预先分词(例如,通过空格分词)。如果设置为True
,则分词器假定输入已经分割成单词(例如,通过空格分割),它将对其进行分词。这对于 NER 或标记分类很有用。 - pad_to_multiple_of (
int
, 可选) — 如果设置,则序列将被填充到所提供值的倍数。需要激活padding
。这对于在计算能力>= 7.5
(Volta) 的 NVIDIA 硬件上使用 Tensor Cores 特别有用。 - padding_side (
str
, 可选) — 模型应该在哪一侧进行填充。应该在 ['right', 'left'] 中选择。默认值从同名类属性中选取。 - return_tensors (
str
或 TensorType, 可选) — 如果设置,将返回张量而不是 Python 整数列表。可接受的值为:'tf'
:返回 TensorFlowtf.constant
对象。'pt'
:返回 PyTorchtorch.Tensor
对象。'np'
:返回 Numpynp.ndarray
对象。
- return_token_type_ids (
bool
, 可选) — 是否返回标记类型 ID。如果保留默认值,将根据特定分词器的默认值(由return_outputs
属性定义)返回标记类型 ID。 - return_attention_mask (
bool
, 可选) — 是否返回注意力掩码。如果保留默认值,将根据特定分词器的默认值(由return_outputs
属性定义)返回注意力掩码。 - return_overflowing_tokens (
bool
,*可选*,默认为False
) — 是否返回溢出的标记序列。如果提供了一对输入 ID 序列(或一批 ID 对),并且truncation_strategy = longest_first
或True
,则会引发错误而不是返回溢出的标记。 - return_special_tokens_mask (
bool
,*可选*,默认为False
) — 是否返回特殊标记掩码信息。 - return_offsets_mapping (
bool
,*可选*,默认为False
) — 是否为每个标记返回(char_start, char_end)
。这仅在继承自 PreTrainedTokenizerFast 的快速分词器上可用,如果使用 Python 的分词器,此方法将引发
NotImplementedError
。 - return_length (
bool
,*可选*,默认为False
) — 是否返回编码输入的长度。 - verbose (
bool
,*可选*,默认为True
) — 是否打印更多信息和警告。 **kwargs — 传递给self.tokenize()
方法
返回值
一个 BatchEncoding,具有以下字段
-
**input_ids** — 要输入到模型的词 ID 列表。
-
**token_type_ids** — 要输入到模型的词类型 ID 列表(当
return_token_type_ids=True
或 “token_type_ids” 在self.model_input_names
中时)。 -
**attention_mask** — 指定模型应关注哪些词的索引列表(当
return_attention_mask=True
或 “attention_mask” 在self.model_input_names
中时)。 -
**overflowing_tokens** — 溢出词序列列表(当指定了
max_length
且return_overflowing_tokens=True
时)。 -
**num_truncated_tokens** — 被截断的词数(当指定了
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: Union special_tokens: bool = False ) → int
参数
- new_tokens (
str
、tokenizers.AddedToken
或 str 或tokenizers.AddedToken
的列表) — 仅当标记尚不在词汇表中时才添加。tokenizers.AddedToken
包装字符串标记,以便您个性化其行为:此标记是否应仅与单个单词匹配,此标记是否应删除左侧所有潜在的空白,此标记是否应删除右侧所有潜在的空白,等等。 - special_tokens (
bool
,可选,默认为False
)— 可用于指定该标记是否是特殊标记。这主要改变了规范化行为(例如,像 CLS 或 [MASK] 这样的特殊标记通常不会被转换为小写)。有关 HuggingFace tokenizers 库中的
tokenizers.AddedToken
的详细信息,请参阅相关文档。
返回值
int
添加到词汇表中的词符数量。
将新词符列表添加到分词器类。如果新词符不在词汇表中,则将它们添加到词汇表中,索引从当前词汇表的长度开始,并在应用分词算法之前将其隔离。因此,添加的词符和来自分词算法词汇表的词符不会以相同的方式处理。
注意,在向词汇表添加新词符时,您应该确保也调整模型的词符嵌入矩阵的大小,以使其嵌入矩阵与分词器匹配。
为此,请使用 resize_token_embeddings() 方法。
示例
# 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 replace_additional_special_tokens = True ) → int
参数
- special_tokens_dict (字典 str 到 str 或
tokenizers.AddedToken
)— 键应在预定义的特殊属性列表中:[bos_token
、eos_token
、unk_token
、sep_token
、pad_token
、cls_token
、mask_token
、additional_special_tokens
]。只有当标记不在词汇表中时才会添加它们(通过检查分词器是否为其分配了
unk_token
的索引来进行测试)。 - replace_additional_special_tokens (
bool
,可选,默认为True
)— 如果为True
,则现有的附加特殊标记列表将被special_tokens_dict
中提供的列表替换。否则,self._additional_special_tokens
只会被扩展。在前一种情况下,标记不会从分词器的完整词汇表中删除 - 它们只是被标记为非特殊标记。请记住,这只会影响在解码过程中跳过哪些标记,而不会影响added_tokens_encoder
和added_tokens_decoder
。这意味着之前的additional_special_tokens
仍然是已添加的标记,并且不会被模型拆分。
返回值
int
添加到词汇表中的词符数量。
向编码器添加特殊词符字典(eos、pad、cls 等),并将它们链接到类属性。如果特殊词符不在词汇表中,则将它们添加到词汇表中(索引从当前词汇表的最后一个索引开始)。
在向词汇表添加新词符时,您应该确保也调整模型的词符嵌入矩阵的大小,以使其嵌入矩阵与分词器匹配。
为此,请使用 resize_token_embeddings() 方法。
使用 add_special_tokens
将确保您的特殊词符可以通过多种方式使用
- 使用
skip_special_tokens = True
解码时,可以跳过特殊词符。 - 分词器会小心处理特殊词符(它们永远不会被拆分),类似于
AddedTokens
。 - 您可以使用分词器类属性(如
tokenizer.cls_token
)轻松引用特殊词符。这使得开发与模型无关的训练和微调脚本变得容易。
如果可能,特殊词符已为提供的预训练模型注册(例如,BertTokenizer cls_token
已注册为 :obj_“[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: Union tools: Optional = None documents: Optional = None chat_template: Optional = None add_generation_prompt: bool = False continue_final_message: bool = False tokenize: bool = True padding: bool = False truncation: bool = False max_length: Optional = None return_tensors: Union = None return_dict: bool = False return_assistant_tokens_mask: bool = False tokenizer_kwargs: Optional = None **kwargs ) → Union[List[int], Dict]
参数
- conversation (Union[List[Dict[str, str]], List[List[Dict[str, str]]]]) — 包含“角色”和“内容”键的字典列表,表示到目前为止的聊天历史记录。
- tools (
List[Dict]
,可选) — 模型可访问的工具(可调用函数)列表。如果模板不支持函数调用,则此参数无效。每个工具都应作为 JSON Schema 传递,给出工具的名称、描述和参数类型。有关更多信息,请参阅我们的聊天模板指南。 - documents (
List[Dict[str, str]]
,可选) — 如果模型正在执行 RAG(检索增强生成),则表示可供模型访问的文档字典列表。如果模板不支持 RAG,则此参数无效。我们建议每个文档都应该是一个包含“标题”和“文本”键的字典。有关使用聊天模板传递文档的示例,请参阅聊天模板指南的 RAG 部分。 - chat_template (
str
,可选) — 用于此转换的 Jinja 模板。通常不需要向此参数传递任何内容,因为默认情况下将使用模型的模板。 - add_generation_prompt (bool,可选) — 如果设置了此选项,则指示助手消息开头的标记的提示将附加到格式化输出中。当您想从模型生成响应时,这很有用。请注意,此参数将传递给聊天模板,因此模板必须支持此参数才能生效。
- continue_final_message (bool,可选) — 如果设置了此选项,则聊天将被格式化,以便聊天中的最后一条消息是开放式的,没有任何 EOS 标记。模型将继续此消息,而不是开始新消息。这允许您为模型“预填充”部分响应。不能与
add_generation_prompt
同时使用。 - tokenize (
bool
,默认为True
) — 是否对输出进行分词。如果为False
,则输出将是一个字符串。 - **padding** (
bool
,默认为False
) — 是否将序列填充到最大长度。如果 `tokenize` 为 `False`,则无效。 - **truncation** (
bool
,默认为False
) — 是否在最大长度处截断序列。如果 `tokenize` 为 `False`,则无效。 - **max_length** (
int
,可选) — 用于填充或截断的最大长度(以标记为单位)。如果 `tokenize` 为 `False`,则无效。如果未指定,则将使用分词器的 `max_length` 属性作为默认值。 - **return_tensors** (
str
或 TensorType,可选) — 如果设置,将返回特定框架的张量。如果 `tokenize` 为 `False`,则无效。可接受的值为:'tf'
:返回 TensorFlowtf.Tensor
对象。'pt'
:返回 PyTorchtorch.Tensor
对象。'np'
:返回 NumPynp.ndarray
对象。'jax'
:返回 JAXjnp.ndarray
对象。
- **return_dict** (
bool
,默认为False
) — 是否返回带有命名输出的字典。如果 `tokenize` 为 `False`,则无效。 - **tokenizer_kwargs** (
Dict[str -- Any]
,可选):要传递给分词器的其他关键字参数。 - **return_assistant_tokens_mask** (
bool
,默认为False
) — 是否返回助手生成的标记的掩码。对于助手生成的标记,掩码将包含 1。对于用户和系统标记,掩码将包含 0。此功能仅适用于通过 `{% generation %}` 关键字支持它的聊天模板。**kwargs — 要传递给模板渲染器的其他关键字参数。聊天模板可以访问。
返回值
Union[List[int], Dict]
表示迄今为止已分词化的聊天的token ID 列表,包括控制token。此输出已准备好传递给模型,可以直接传递,也可以通过 generate()
等方法传递。如果设置了 return_dict
,则将返回分词器输出的字典。
将包含 "role"
和 "content"
键的字典列表转换为token ID 列表。此方法适用于聊天模型,并将读取分词器的 chat_template 属性,以确定转换时要使用的格式和控制token。
batch_decode
< source >( sequences: Union skip_special_tokens: bool = False clean_up_tokenization_spaces: bool = None **kwargs ) → List[str]
参数
- sequences (
Union[List[int], List[List[int]], np.ndarray, torch.Tensor, tf.Tensor]
) — 已分词化的输入 ID 列表。可以使用__call__
方法获取。 - skip_special_tokens (
bool
, 可选, defaults toFalse
) — 解码时是否移除特殊标记。 - clean_up_tokenization_spaces (
bool
, 可选) — 是否清除分词空格。 如果为None
,则默认为self.clean_up_tokenization_spaces
。 - kwargs (其他关键字参数, 可选) — 将传递给底层模型特定的解码方法。
返回值
字符串列表
解码后的句子列表。
通过调用 decode 将标记 ID 列表的列表转换为字符串列表。
decode
< source >( token_ids: Union skip_special_tokens: bool = False clean_up_tokenization_spaces: bool = None **kwargs ) → str
参数
- token_ids (
Union[int, List[int], np.ndarray, torch.Tensor, tf.Tensor]
) — 已分词化的输入 ID 列表。可以使用__call__
方法获取。 - skip_special_tokens (
bool
, 可选, defaults toFalse
) — 解码时是否移除特殊标记。 - clean_up_tokenization_spaces (
bool
, 可选) — 是否清除分词空格。如果为None
,则默认为self.clean_up_tokenization_spaces
。 - kwargs (其他关键字参数, 可选) — 将传递给底层模型特定的解码方法。
返回值
字符串
解码后的句子。
使用分词器和词汇表将字符串中的id序列进行转换,并提供移除特殊标记和清理分词空格的选项。
类似于执行 self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))
。
encode
< source >( text: Union text_pair: Union = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 padding_side: Optional = None return_tensors: Union = None **kwargs ) → List[int]
、torch.Tensor
、tf.Tensor
或 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
指定的最大长度,或者截断到模型可接受的最大输入长度(如果未提供该参数)。如果提供了一对序列(或一批序列对),这将逐个截断标记,从最长序列中删除标记。'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
时返回的溢出标记将包含来自返回的截断序列末尾的一些标记,以在截断序列和溢出序列之间提供一些重叠。此参数的值定义重叠标记的数量。 - is_split_into_words (
bool
,可选,默认为False
)— 输入是否已预先标记化(例如,按空格分割成单词)。如果设置为True
,则分词器假定输入已经分割成单词(例如,通过按空格分割),它将对这些单词进行标记化。这对于 NER 或标记分类很有用。 - pad_to_multiple_of (
int
, 可选) — 如果设置,则将序列填充为所提供值的倍数。需要激活padding
。这对于在计算能力>= 7.5
(Volta) 的 NVIDIA 硬件上使用 Tensor Cores 特别有用。 - padding_side (
str
, 可选) — 模型应用填充的一侧。应该在 [“right”, “left”] 之间选择。默认值取自同名类属性。 - return_tensors (
str
或 TensorType, 可选) — 如果设置,将返回张量而不是 Python 整数列表。可接受的值为:'tf'
:返回 TensorFlowtf.constant
对象。'pt'
:返回 PyTorchtorch.Tensor
对象。'np'
:返回 Numpynp.ndarray
对象。
**kwargs — 传递给
.tokenize()
方法。
返回值
List[int]
、torch.Tensor
、tf.Tensor
或 np.ndarray
文本的标记化 ID。
使用标记器和词汇表将字符串转换为 ID 序列(整数)。
与执行 self.convert_tokens_to_ids(self.tokenize(text))
相同。
push_to_hub
< source >( repo_id: str use_temp_dir: Optional = None commit_message: Optional = None private: Optional = None token: Union = None max_shard_size: Union = '5GB' create_pr: bool = False safe_serialization: bool = True revision: str = None commit_description: str = None tags: Optional = None **deprecated_kwargs )
参数
- repo_id (
str
) — 您要将分词器推送到哪个存储库的名称。推送到给定组织时,它应该包含您的组织名称。 - use_temp_dir (
bool
, 可选) — 在将保存的文件推送到 Hub 之前,是否使用临时目录来存储它们。如果没有名为repo_id
的目录,则默认为True
,否则为False
。 - commit_message (
str
, 可选) — 推送时提交的消息。默认为"Upload tokenizer"
。 - private (
bool
, 可选) — 创建的仓库是否应该是私有的。 - token (
bool
或str
, 可选) — 用于远程文件的 HTTP 持有者授权的令牌。如果为True
,将使用运行huggingface-cli login
时生成的令牌(存储在~/.huggingface
中)。如果未指定repo_url
,则默认为True
。 - max_shard_size (
int
或str
, 可选, 默认为"5GB"
) — 仅适用于模型。在进行分片之前,检查点的最大大小。检查点分片的大小将小于此大小。如果表示为字符串,则需要是数字后跟单位(例如"5MB"
)。我们将其默认设置为"5GB"
,以便用户可以在免费层的 Google Colab 实例上轻松加载模型,而不会出现任何 CPU OOM 问题。 - create_pr (
bool
, 可选, 默认为False
) — 是否使用上传的文件创建 PR 或直接提交。 - safe_serialization (
bool
, 可选, 默认为True
) — 是否将模型权重转换为 safetensors 格式以进行更安全的序列化。 - revision (
str
, 可选) — 要将上传的文件推送到哪个分支。 - commit_description (
str
, 可选) — 将创建的提交的描述 - tags (
List[str]
, 可选) — 要推送到 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")
convert_ids_to_tokens
< source >( ids: Union skip_special_tokens: bool = False ) → str
或 List[str]
使用词汇表和添加的词元,将单个索引或索引序列转换为一个词元或词元序列。
convert_tokens_to_ids
< source >( tokens: Union ) → int
或 List[int]
使用词汇表将词元字符串(或词元序列)转换为单个整数 ID(或 ID 序列)。
以字典形式返回词汇表中添加的标记,键为标记,值为索引。
num_special_tokens_to_add
< source >( pair: bool = False ) → int
返回使用特殊标记对序列进行编码时添加的标记数量。
这将编码一个虚拟输入并检查添加的标记数量,因此效率不高。不要将此放入您的训练循环中。
设置截断和填充
< source >( padding_strategy: PaddingStrategy truncation_strategy: TruncationStrategy max_length: int stride: int pad_to_multiple_of: Optional padding_side: Optional )
参数
- padding_strategy (PaddingStrategy) — 将应用于输入的填充类型
- truncation_strategy (TruncationStrategy) — 将应用于输入的截断类型
- max_length (
int
) — 序列的最大长度。 - stride (
int
) — 处理溢出时使用的步幅。 - pad_to_multiple_of (
int
, 可选) — 如果设置,则将序列填充到所提供值的倍数。这对于在计算能力>= 7.5
(Volta) 的 NVIDIA 硬件上使用 Tensor Core 特别有用。 - padding_side (
str
,可选) — 模型应该应用填充的一侧。 应该在 [‘right’, ‘left’] 中选择。 默认值取自同名的类属性。
为快速分词器(由 HuggingFace 分词器库提供)定义截断和填充策略,并在之后恢复分词器设置。
在托管部分之前,提供的分词器没有填充/截断策略。 如果您的分词器之前设置了填充/截断策略,则在退出托管部分时,它将被重置为无填充/截断。
train_new_from_iterator
< source >( text_iterator vocab_size length = None new_special_tokens = None special_tokens_map = None **kwargs ) → PreTrainedTokenizerFast
参数
- text_iterator (
List[str]
的生成器) — 训练语料库。 应该是文本批次的生成器,例如,如果您将所有内容都保存在内存中,则应为文本列表的列表。 - vocab_size (
int
) — 您想要为分词器设置的词汇表大小。 - length (
int
,可选) — 迭代器中的序列总数。 这用于提供有意义的进度跟踪 - new_special_tokens (
str
或AddedToken
的列表,可选) — 要添加到您正在训练的分词器中的新特殊标记列表。 - special_tokens_map (
Dict[str, str]
,可选) — 如果你想重命名此分词器使用的一些特殊标记,请在此参数中传递一个从旧特殊标记名称到新特殊标记名称的映射。 - kwargs (
Dict[str, Any]
,可选) — 传递给 🤗 Tokenizers 库中训练器的其他关键字参数。
与原始分词器类型相同的新分词器,在 text_iterator
上训练。
使用与当前分词器相同的默认值(在特殊标记或分词管道方面)在新语料库上训练分词器。
BatchEncoding
类 transformers.BatchEncoding
< 源代码 >( data: Optional = None encoding: Union = None tensor_type: Union = None prepend_batch_axis: bool = False n_sequences: Optional = None )
参数
- data (
dict
,可选) — 由__call__
/encode_plus
/batch_encode_plus
方法返回的列表/数组/张量字典('input_ids'、'attention_mask' 等)。 - encoding (
tokenizers.Encoding
或Sequence[tokenizers.Encoding]
,可选) — 如果分词器是一个快速分词器,它会输出额外的信息,比如从单词/字符空间到标记空间的映射,那么tokenizers.Encoding
实例或实例列表(用于批处理)会保存这些信息。 - tensor_type (
Union[None, str, TensorType]
, 可选) — 您可以在此处提供一个 tensor_type,以便在初始化时将整数列表转换为 PyTorch/TensorFlow/Numpy 张量。 - prepend_batch_axis (
bool
, 可选, 默认值为False
) — 转换为张量时是否添加批处理轴(参见上面的tensor_type
)。请注意,如果设置了参数tensor_type
,则此参数才有效,*否则无效*。 - n_sequences (
Optional[int]
, 可选) — 您可以在此处提供一个 tensor_type,以便在初始化时将整数列表转换为 PyTorch/TensorFlow/Numpy 张量。
保存 call()、encode_plus() 和 batch_encode_plus() 方法的输出(标记、注意力掩码等)。
此类派生自 Python 字典,可以用作字典。此外,此类还公开了实用方法,用于从单词/字符空间映射到标记空间。
char_to_token
< source >( batch_or_char_index: int char_index: Optional = None sequence_index: int = 0 ) → int
获取编码输出中包含原始字符串中某个字符的标记的索引,用于批处理中的序列。
可以这样调用
- 如果批次大小为 1,则为
self.char_to_token(char_index)
- 如果批次大小大于或等于 1,则为
self.char_to_token(batch_index, char_index)
当输入序列作为预先标记化的序列提供(即单词由用户定义)时,此方法特别适用。在这种情况下,它允许轻松地将编码标记与提供的标记化单词相关联。
char_to_word
< source >( batch_or_char_index: int char_index: Optional = None sequence_index: int = 0 ) → int
或 List[int]
获取批处理序列的原始字符串中与原始字符串中某个字符对应的单词。
可以这样调用
- 如果批次大小为 1,则为
self.char_to_word(char_index)
- 如果批次大小大于 1,则为
self.char_to_word(batch_index, char_index)
当输入序列作为预先标记化的序列提供(即单词由用户定义)时,此方法特别适用。在这种情况下,它允许轻松地将编码标记与提供的标记化单词相关联。
convert_to_tensors
< source >( tensor_type: Union = None prepend_batch_axis: bool = False )
参数
- tensor_type (
str
或 TensorType, 可选) — 要使用的张量类型。如果为str
,则应为枚举 TensorType 中的值之一。如果为None
,则不进行任何修改。 - prepend_batch_axis (
int
, 可选, 默认值为False
) — 在转换过程中是否添加批次维度。
将内部内容转换为张量。
sequence_ids
< source >( batch_index: int = 0 ) → List[Optional[int]]
返回一个列表,将标记映射到其原始句子的 ID
- 对于在序列周围或序列之间添加的特殊标记,返回
None
, - 对于与第一个序列中的单词相对应的标记,返回
0
, - 对于在联合编码一对序列时与第二个序列中的单词相对应的标记,返回
1
。
to
< source >( device: Union ) → BatchEncoding
通过调用 v.to(device)
将所有值发送到设备(仅限 PyTorch)。
token_to_chars
< source >( batch_or_token_index: int token_index: Optional = None ) → CharSpan
获取与批处理序列中已编码标记相对应的字符范围。
字符范围作为 CharSpan 返回,其中
- start - 与标记关联的原始字符串中第一个字符的索引。
- end - 与标记关联的原始字符串中最后一个字符之后的字符的索引。
可以这样调用
- 如果批处理大小为 1,则为
self.token_to_chars(token_index)
- 如果批处理大小大于或等于 1,则为
self.token_to_chars(batch_index, token_index)
token_to_sequence
< source >( batch_or_token_index: int token_index: Optional = None ) → int
获取由给定标记表示的序列的索引。在一般用例中,此方法对单个序列或对的第一个序列返回 0
,对对的第二个序列返回 1
可以这样调用
- 如果批次大小为 1,则为
self.token_to_sequence(token_index)
- 如果批次大小大于 1,则为
self.token_to_sequence(batch_index, token_index)
当输入序列作为预先标记化的序列提供(即,单词由用户定义)时,此方法特别适用。在这种情况下,它允许轻松地将编码标记与提供的标记化单词相关联。
token_to_word
< source >( batch_or_token_index: int token_index: Optional = None ) → int
获取与批次序列中编码标记相对应的单词(即包含该标记)的索引。
可以这样调用
- 如果批次大小为 1,则为
self.token_to_word(token_index)
- 如果批次大小大于 1,则为
self.token_to_word(batch_index, token_index)
当输入序列作为预先标记化的序列提供(即,单词由用户定义)时,此方法特别适用。在这种情况下,它允许轻松地将编码标记与提供的标记化单词相关联。
tokens
< source >( batch_index: int = 0 ) → List[str]
返回给定批次索引处的标记列表(单词/子词拆分后和转换为整数索引之前的输入字符串的子部分)(仅适用于快速分词器的输出)。
word_ids
< source >( batch_index: int = 0 ) → List[Optional[int]]
返回一个列表,将标记映射到快速分词器初始句子中的实际单词。
word_to_chars
< source >( batch_or_word_index: int word_index: Optional = None sequence_index: int = 0 ) → CharSpan
或 List[CharSpan]
参数
- batch_or_word_index (
int
) — 批次中序列的索引。 如果批次仅包含一个序列,则这可以是序列中单词的索引 - word_index (
int
, 可选) — 如果在 *batch_or_token_index* 中提供了批次索引,则这可以是序列中单词的索引。 - sequence_index (
int
, 可选, 默认为 0) — 如果在批次中编码了序列对,则可以使用此选项指定所提供的单词索引属于该对中的哪个序列(0 或 1)。
返回值
CharSpan
或 List[CharSpan]
字符串中关联字符的跨度。CharSpan 是 NamedTuple,具有以下属性:
- start:与原始字符串中标记关联的第一个字符的索引
- end:原始字符串中与标记关联的最后一个字符之后的字符的索引
获取批次序列中与给定单词对应的原始字符串中的字符跨度。
字符跨度作为 CharSpan NamedTuple 返回,具有以下属性:
- start:原始字符串中第一个字符的索引
- end:原始字符串中最后一个字符之后的字符的索引
可以这样调用
- 如果批次大小为 1,则为
self.word_to_chars(word_index)
- 如果批次大小大于或等于 1,则为
self.word_to_chars(batch_index, word_index)
word_to_tokens
< 源代码 >( batch_or_word_index: int word_index: Optional = None sequence_index: int = 0 ) → (TokenSpan, 可选的)
参数
- batch_or_word_index (
int
) — 批次中序列的索引。如果批次仅包含一个序列,则这可以是序列中单词的索引。 - word_index (
int
, 可选的) — 如果在 *batch_or_token_index* 中提供了批次索引,则这可以是序列中单词的索引。 - sequence_index (
int
, 可选的, 默认为 0) — 如果在批次中对序列对进行编码,则可以使用它来指定提供的单词索引属于对中的哪个序列(0 或 1)。
返回值
(TokenSpan, 可选的)
编码序列中标记的跨度。如果没有标记对应于该词,则返回 None
。当标记是用于格式化标记化的特殊标记时,尤其可能发生这种情况。例如,当我们在标记化的开头添加一个类标记时。
获取与批处理序列中某个单词对应的编码标记跨度。
标记跨度作为 TokenSpan 返回,其中
- start — 第一个标记的索引。
- end — 最后一个标记之后的标记的索引。
可以这样调用
- 如果批次大小为 1,则为
self.word_to_tokens(word_index, sequence_index: int = 0)
- 如果批次大小大于或等于 1,则为
self.word_to_tokens(batch_index, word_index, sequence_index: int = 0)
当输入序列作为预先标记化的序列提供(即单词由用户定义)时,此方法特别适用。在这种情况下,它允许轻松地将编码标记与提供的标记化单词相关联。
单词
< 源代码 >( batch_index: int = 0 ) → List[Optional[int]]
返回一个列表,将标记映射到快速分词器初始句子中的实际单词。