四、Tokenizer 库的应用

发布于 2023-07-17 23:38:23 字数 48844 浏览 0 评论 0 收藏 0

安装：


xxxxxxxxxx
pip install tokenizers

使用不同 subword tokenization 算法的 Transformer-based 模型：
- GPT, GPT-2, RoBERTa, BART, DeBERTa 等模型使用了 BPE，其中 GPT-2 使用了 byte-level BPE 。
- BERT, DistilBERT, MobileBERT, Funnel Transformers, MPNET 等模型使用了 WordPiece。
  注意，Google 从未开源 WordPiece 训练算法的实现，因此 Hugging Face 中的实现是 Hugging Face 基于已发表文献的最佳猜测，它可能不是 100% 正确的。
- AlBERT, T5, mBART, Big Bird, XLNet 等模型使用了 Unigram 。
tokenizer应用于文本的流程如下，其中包括：
- Normalization：标准化步骤，包括一些常规清理，例如删除不必要的空格、小写、以及删除重音符号。
  Transformers tokenizer 有一个属性叫做 backend_tokenizer 它提供了对 Tokenizers 库中底层tokenizer的访问。backend_tokenizer 的 normalizer 属性可以获取执行标准化的 normalizer 。而 normalizer 的 normalize_str() 方法执行标准化。
```
xxxxxxxxxx
from transformers import AutoTokenizer


tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
print(type(tokenizer.backend_tokenizer))
# <class 'tokenizers.Tokenizer'>


normalizer = tokenizer.backend_tokenizer.normalizer
print(normalizer.normalize_str("Héllò hôw are ü?"))
# hello how are u?
```
- Pre-tokenization：tokenizer 不能单独在原始文本上进行训练。相反，我们首先需要将文本拆分为小的单元，例如单词。这就是pre-tokenization 步骤。基于单词的tokenizer可以简单地基于空白和标点符号将原始文本拆分为单词。这些词将是tokenizer在训练期间可以学习的子词边界。
  backend_tokenizer 的 pre_tokenizer 属性可以获取执行 pre-tokenization 的 pre_tokenizer 。而 pre_tokenizer 的 pre_tokenize_str() 方法执行 pre-tokenization 。
```
xxxxxxxxxx
from transformers import AutoTokenizer


tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
print(type(tokenizer.backend_tokenizer))
# <class 'tokenizers.Tokenizer'>


pre_tokenizer = tokenizer.backend_tokenizer.pre_tokenizer
print(pre_tokenizer.pre_tokenize_str("hello how are  u?")) # are 和 u 之间是双空格
# [('hello', (0, 5)), ('how', (6, 9)), ('are', (10, 13)), ('u', (15, 16)), ('?', (16, 17))]
```
  请注意 tokenizer 如何跟踪单词的偏移量。
  由于我们使用的是BERT tokenizer ， pre_tokenizer 涉及对空格和标点符号进行拆分。而其他 tokenizer 可以有不同的规则。例如，GPT-2 tokenizer 和 T5 tokenizer：
```
xxxxxxxxxx
AutoTokenizer.from_pretrained("gpt2").backend_tokenizer.pre_tokenizer.pre_tokenize_str("hello how are u?")  # are 和 u 之间是双空格
# [('hello', (0, 5)),
#  ('Ġhow', (5, 9)),
#  ('Ġare', (9, 13)),
#  ('Ġ', (13, 14)),
#  ('Ġu', (14, 16)),
#  ('?', (16, 17))]
AutoTokenizer.from_pretrained("t5-small").backend_tokenizer.pre_tokenizer.pre_tokenize_str("hello how are u?")  # are 和 u 之间是双空格
# [('▁hello', (0, 5)), ('▁how', (6, 9)), ('▁are', (10, 13)), ('▁u?', (15, 17))]
```
  GPT-2 tokenizer 也会在空格和标点符号上拆分，但它会保留空格并将它们替换为 Ġ 符号。注意，与 BERT tokenizer 不同，GPT-2 tokenizer 不会忽略双空格。
  与 GPT-2 tokenizer 一样， T-5 tokenizer 保留空格并用特定 token （即 "_"）替换它们。但是， T-5 tokenizer 只在空格上拆分，而不拆分标点符号。注意， T-5 tokenizer 默认在句子的开头添加了一个空格（即，_hello），并忽略了 are 和 u 之间的双空格。
- Model：执行 tokenization 从而生成 token 序列。
- Postprocessor：针对具体的任务插入 special token ，以及生成 attention mask 和 token-type ID 。
Tokenizers 库 旨在为每个步骤提供多个选项，从而方便用于自由地组合。

3.1 Normalizers

class tokenizers.normalizers.Normalizer：所有 normalizer 的基类。
方法：
- normalize(normalized)：执行标准化（原地操作）。如果你仅仅想知道在原始字符串上执行标准化的结果，建议使用 normalize_str() 。
  参数：normalized，被执行标准化的字符串。
- normalize_str(sequence) -> str：执行标准化，返回标准化后的字符串。
  参数：sequence，被执行标准化的字符串。
class tokenizers.normalizers.BertNormalizer：Bert normalizer ，包括清理文本（移除控制字符并替代以空格）、移除重音、处理中文字符（中文字符周围添加空格）、字母转小写。
```
xxxxxxxxxx
class tokenizers.normalizers.BertNormalizer( clean_text = True, handle_chinese_chars = True, strip_accents = None, lowercase = True )
```

其它的一些 normalizer：


xxxxxxxxxx
class tokenizers.normalizers.Lowercase() # Lowercase Normalizer
class tokenizers.normalizers.NFC() # NFC Unicode Normalizer
class tokenizers.normalizers.NFD() # NFD Unicode Normalizer
class tokenizers.normalizers.NFKC() # NFKC Unicode Normalizer
class tokenizers.normalizers.NFKD() # NFKD Unicode Normalizer
class tokenizers.normalizers.Nmt() # Nmt normalizer
class tokenizers.normalizers.StripAccents() # StripAccents normalizer
class tokenizers.normalizers.Strip(left = True, right = True ) # Strip normalizer
class tokenizers.normalizers.Replace(pattern, content ) # Replace normalizer

class tokenizers.normalizers.Sequence(normalizers)：将一组 normalizer 拼成一个序列，以给定的顺序依次执行各个 normalizer 。

示例：


xxxxxxxxxx
normalizer_map = {
    'BertNormalizer()': BertNormalizer(),
    'Lowercase()': Lowercase(),
    'NFC()': NFC(),
    'NFD()': NFD(),
    'NFKC()': NFKC(),
    'NFKD()':NFKD(),
    'Nmt()': Nmt(),
    'StripAccents()': StripAccents(),
    'Strip()': Strip(),
    "Replace('I','you')":Replace('I','you'),
}
string = " Héllò, I like play football "
for (name, normalizer) in normalizer_map.items():
    normalized_str = normalizer.normalize_str(string)
    print("%s -> '%s'"%(name,normalized_str))
# BertNormalizer() -> ' hello, i like play football '
# Lowercase() -> ' héllò, i like play football '
# NFC() -> ' Héllò, I like play football '
# NFD() -> ' Héllò, I like play football '
# NFKC() -> ' Héllò, I like play football '
# NFKD() -> ' Héllò, I like play football '
# Nmt() -> ' Héllò, I like play football '
# StripAccents() -> ' Héllò, I like play football '
# Strip() -> 'Héllò, I like play football'
# Replace('I','you') -> ' Héllò, you like play football '

3.2 Pre-tokenizers

class tokenizers.pre_tokenizers.PreTokenizer()：所有 pre-tokenizer 的基类。
方法：
- pre_tokenize(pretok)：执行pre-tokenize（原地操作）。如果你仅仅想知道在原始字符串上执行 pre-tokenize 的结果，建议使用 pre_tokenize_str() 。
  参数：pretok，被执行标准化的字符串。
- pre_tokenize_str(sequence) -> List[Tuple[str, Offsets]]：执行 pre-tokenize ，返回结果字符串序列以及每个结果的偏移量。
  参数：sequence，被执行pre-tokenize 的字符串。
class tokenizers.pre_tokenizers.BertPreTokenizer() ：BertPreTokenizer，在每个空格和标点符号上拆分。每个标点符号被视为一个独立的单元。
class tokenizers.pre_tokenizers.ByteLevel(add_prefix_space = True, use_regex = True)：ByteLevel PreTokenizer ，将给定字符串的所有字节替换为相应的表示并拆分为单词。
参数：
- add_prefix_space：是否在第一个单词前面添加空格，如果第一个单词前面目前还没有空格。
- use_regex：如果为 False 则阻止该 pre_tokenizer 使用 GPT2 的正则表达式来在空格上拆分。
方法：
- alphabet() -> List[str]：返回所有字母组成的字符的列表。由于 ByteLevel PreTokenizer 作用在 byte level，因此字母表里有 256 个不同的字符。
class tokenizers.pre_tokenizers.CharDelimiterSplit(delimiter) ：CharDelimiterSplit，简单地在给定的 char 上拆分，类似于 .split(delimiter) 。
参数：delimiter：一个字符，指定拆分的分隔符。
class tokenizers.pre_tokenizers.Digits(individual_digits = False)：Digits，利用数字来拆分。
参数：individual_digits，一个布尔值，如果为 True 则每个数字都单独处理（如 "123" 被拆分为 "1", "2", "3" ）；否则数字被整体处理（如 "123" 被视为一个整体）。
class tokenizers.pre_tokenizers.Metaspace(replacement = '_', add_prefix_space = True ) ：Metaspace pre-tokenizer，用给定的 replacement 字符来代替任意空白符，并在空白符上执行拆分。
参数：
- replacement：一个字符串，指定替换字符，必须只有一个字符。默认为 SentencePiece 中的配置。
- add_prefix_space：一个布尔值，是否在首个单词之前没有空格的时候添加一个空格。
class tokenizers.pre_tokenizers.Punctuation( behavior = 'isolated' )：Punctuation pre-tokenizer ，在标点符号上进行拆分。
参数：behavior：指定拆分之后如何处理标点符号。可以为 "removed", "isolated", "merged_with_previous", "merged_with_next", "contiguous" 。
class tokenizers.pre_tokenizers.Split( pattern, behavior, invert = False ) ：Split PreTokenizer ，基于指定的模式和行为来拆分。
参数：
- pattern：一个字符串或正则表达式，指定拆分模式。
- behavior：一个字符串，指定拆分之后如何处理这个模式。可以为 "removed", "isolated", "merged_with_previous", "merged_with_next", "contiguous" 。
- invert：一个布尔值，指定是否翻转 pattern 。
class class tokenizers.pre_tokenizers.UnicodeScripts() ：这个 pre-tokenizer 在不同的 language family 上进行拆分。遵从 SentencePiece Unigram 的实现。
class tokenizers.pre_tokenizers.Whitespace()：这个 pre-tokenizer 在使用如下的正则表达式进行拆分：\w+|[^\w\s]+ 。
class tokenizers.pre_tokenizers.WhitespaceSplit()：这个 pre-tokenizer 在空格上拆分，类似于 .split() 。

示例：


xxxxxxxxxx
pre_tokenizer_map = {
    'BertPreTokenizer()': BertPreTokenizer(),
    'ByteLevel()': ByteLevel(),
    "CharDelimiterSplit('n')": CharDelimiterSplit('n'),
    'Digits()': Digits(),
    'Metaspace()': Metaspace(),
    'Punctuation()':Punctuation(),
    "Split('e','isolated')": Split('e','isolated'),
    'UnicodeScripts()': UnicodeScripts(),
    'Whitespace()': Whitespace(),
    "WhitespaceSplit()":WhitespaceSplit(),
}
string = "English line; 中文的；And 123456."
for (name, pre_tokenizer) in pre_tokenizer_map.items():
    pre_tokenized_str = pre_tokenizer.pre_tokenize_str(string)
    print("%s -> '%s'"%(name,pre_tokenized_str))
    
# BertPreTokenizer() -> '[('English', (0, 7)), ('line', (8, 12)), (';', (12, 13)), ('中文的', (14, 17)), ('；', (17, 18)), ('And', (18, 21)), ('123456', (22, 28)), ('.', (28, 29))]'
# ByteLevel() -> '[('ĠEnglish', (0, 7)), ('Ġline', (7, 12)), (';', (12, 13)), ('Ġä¸ŃæĸĩçļĦ', (13, 17)), ('ï¼Ľ', (17, 18)), ('And', (18, 21)), ('Ġ123456', (21, 28)), ('.', (28, 29))]'
# CharDelimiterSplit('n') -> '[('E', (0, 1)), ('glish li', (2, 10)), ('e; 中文的；A', (11, 19)), ('d 123456.', (20, 29))]'
# Digits() -> '[('English line; 中文的；And ', (0, 22)), ('123456', (22, 28)), ('.', (28, 29))]'
# Metaspace() -> '[('▁English', (0, 7)), ('▁line;', (7, 13)), ('▁中文的；And', (13, 21)), ('▁123456.', (21, 29))]'
# Punctuation() -> '[('English line', (0, 12)), (';', (12, 13)), (' 中文的', (13, 17)), ('；', (17, 18)), ('And 123456', (18, 28)), ('.', (28, 29))]'
# Split('e','isolated') -> '[('English lin', (0, 11)), ('e', (11, 12)), ('; 中文的；And 123456.', (12, 29))]'
# UnicodeScripts() -> '[('English line', (0, 12)), ('; ', (12, 14)), ('中文的', (14, 17)), ('；', (17, 18)), ('And ', (18, 22)), ('123456.', (22, 29))]'
# Whitespace() -> '[('English', (0, 7)), ('line', (8, 12)), (';', (12, 13)), ('中文的', (14, 17)), ('；', (17, 18)), ('And', (18, 21)), ('123456', (22, 28)), ('.', (28, 29))]'
# WhitespaceSplit() -> '[('English', (0, 7)), ('line;', (8, 13)), ('中文的；And', (14, 21)), ('123456.', (22, 29))]'

3.3 Models

class tokenizers.models.Model() ：所有 Model 的基类。
每个 model 代表一个实际的 tokenization 算法。
方法：
- get_trainer() -> Trainer：返回关联的 Trainer ，该 Trainer 用于训练该 model。
- id_to_token(id) -> str：返回 id 关联的 token 字符串。
  参数：id：待转换的 ID 。
- token_to_id(token) -> int ：返回 token 字符串关联的整数 id 。
  参数：token：待转换的 token 字符串。
- tokenize( sequence ) -> A List of Token：把给定的字符串执行 tokenize ，返回一个 token 序列。
  参数：sequence：一个字符串。
- save( folder, prefix) -> List[str]：在指定的目录中保存 model 。其中被创建的文件使用指定的前缀。如果目录中已有同名的文件，则直接覆盖同名文件。
  参数：
  - folder：模型保存的目录。
  - prefix：一个字符串，指定被保存的各种文件的文件名前缀。
  返回值：一个字符串列表，表示被保存的各种文件的文件名。
class tokenizers.models.BPE：BPE 模型。
```
xxxxxxxxxx
class tokenizers.models.BPE( vocab = None, merges = None, cache_capacity = None, dropout = None, unk_token = None, continuing_subword_prefix = None, end_of_word_suffix = None, fuse_unk = None )
```
参数：
- vocab：一个字典 Dict[str, int]，指定字符串 key 及其 id ，表示词表。
- merges：token pair 的列表 List[Tuple[str, str]]，表示 merge 规则。
- cache_capacity：一个整数，指定 BPE cache 包含的单词数量。 BPE cache 能够通过保存多个单词的 merge 操作的结果来加速该过程。
- dropout：一个浮点数，指定 BPE dropout 比例。取值在 0.0 ~ 1.0 之间。
- unk_token：一个字符串，指定 unknown token 。
- continuing_subword_prefix：一个字符串，指定当该子词不是单词的首个子词时，子词的前缀，。
- end_of_word_suffix：一个字符串，指定当该子词是单词的最后一个子词时，子词的后缀。
- fuse_unk：一个布尔值，指定是否将连续的多个 unknown token 合并为单个 unknown token 。
方法：
- from_file( vocab, merges, **kwargs) -> BPE：从文件中初始化一个 BPE 。
  参数：
  - vocab：vocab.json 文件的路径。
  - merges：merges.txt 文件的路径。
  该方法等价于：
```
xxxxxxxxxx
vocab, merges = BPE.read_file(vocab_filename, merges_filename)
bpe = BPE(vocab, merges)
```
- read_file( vocab, merges) -> A Tuple ：从文件中加载词表和 merge 规则。
  参数：参考 from_file() 。
class tokenizers.models.Unigram( vocab )：Unigram 模型。
参数：
- vocab：由字符串和浮点数组成的元组的列表 List[Tuple[str, float]] ，指定 token 及其 score，如 [("am", -0.2442), ...]
class tokenizers.models.WordLevel( vocab, unk_token )：WordLevel 模型。
参数：参考 BPE 模型。
方法：
- from_file( vocab, un_token) -> WordLevel：从文件中初始化一个 WordLevel 。
  参数：
  - vocab：vocab.json 文件的路径。
  - un_token：一个字符串，指定 unknown token 。
- read_file(vocab) -> Dict[str, int] ：从文件中读取词表。
  参数：参考 from_file 。
class tokenizers.models.WordPiece( vocab, unk_token, max_input_chars_per_word)：WordPiece 模型。
参数：
- vocab：一个字典 Dict[str, int]，指定字符串 key 及其 id ，表示词表。
- unk_token：一个字符串，指定 unknown token 。
- max_input_chars_per_word：一个整数，指定一个单词中允许的最大字符数。
方法：
- from_file(vocab, **kwargs) -> WordPiece：从文件中初始化一个 WordPiece 。
  参数：vocab：vocab.json 文件的路径。
- read_file(vocab) -> Dict[Str, int]：从文件中读取词表。
  参数：参考 from_file 。

3.4 Trainers

class tokenizers.trainers.BpeTrainer：BPE Trainer，用于训练 BPE 模型。
```
xxxxxxxxxx
class tokenizers.trainers.BpeTrainer(vocab_size=30000, min_frequency=0, show_progress=True, special_tokens=[], limit_alphabet=None, initial_alphabet=[], continuing_subword_prefix=None, end_of_word_suffix=None)
```
参数：
- vocab_size：一个整数，表示final vocabulary 大小，包括所有的 token 和字母表 alphabet 。
- min_frequency：一个整数，表示一个 pair 的频次至少为多少时才考虑被 merge 。
- show_progress：一个布尔值，指定在训练期间是否展示进度条。
- special_tokens：一个字符串列表，指定 special token 。
- limit_alphabet：一个整数，指定字母表中最多保持多少个不同的字符。
- initial_alphabet：一个字符串列表，指定初始的字母表。如果字符串包含多个字符，那么仅考虑首个字符。这个字母表可以包含训练数据集中不存在的字符。
- continuing_subword_prefix：一个字符串，如果子词不是单词的首个子词，那么添加这个前缀。
- end_of_word_suffix：一个字符串，如果子词是单词的末尾子词，那么添加这个后缀。
class tokenizers.trainers.UnigramTrainer：Unigram Trainer，用于训练 Unigram 模型。
```
xxxxxxxxxx
class UnigramTrainer(vocab_size=8000, show_progress=True, special_tokens=[], shrinking_factor=0.75, unk_token=None, max_piece_length=16, n_sub_iterations=2)
```
参数：
- vocab_size, show_progress, special_tokens：参考 BpeTrainer 。
- shrinking_factor：一个浮点数，指定在训练的每个 step 需要对词表规模缩放多少比例（即，保留 top 的多少）。
- unk_token：一个字符串，指定 unknown token 。
- max_piece_length：一个整数，指定 token 的最大长度（字符个数）。
- n_sub_iterations：一个整数，指定裁剪词表之前执行 EM 算法的迭代次数。

class tokenizers.trainers.WordLevelTrainer：WordLevel Trainer，用于训练 WordLevel 模型。


xxxxxxxxxx
class tokenizers.trainers.WordLevelTrainer(vocab_size=30000, min_frequency=0, show_progress=True, special_tokens=[])

参数：参考 BpeTrainer 。

class tokenizers.trainers.WordPieceTrainer ： WordPiece Trainer，用于训练 WordPiece 模型。


xxxxxxxxxx
class  WordPieceTrainer(vocab_size=30000, min_frequency=0, show_progress=True, special_tokens=[], limit_alphabet=None, initial_alphabet=[], continuing_subword_prefix='##', end_of_word_suffix=None)

参数：参考 BpeTrainer 。

3.5 Post-processors

class tokenizers.processors.BertProcessing( sep, cls)：BERT 的 Post-processor 。
参数：
- sep：一个 (str, int) 的元组，给出 [SEP] token 及其 id 。
- cls：一个 (str, int) 的元组，给出 [CLS] token 及其 id 。
方法：
- num_special_tokens_to_add(is_pair)：返回需要添加到 single/pair 句子的 special token 的数量。
  参数：is_pair：一个布尔值，指定预期的输入是单个句子还是句子对。
- process(encoding, pair=None, add_special_tokens=True)：对指定的 encoding 执行后处理。
  参数：
  - encoding：单个句子的 encoding，类型为 tokenizer.Encoding 。
  - pair：一对句子的 encoding，类型为 tokenizer.Encoding 。
  - add_special_tokens：一个布尔值，指定是否添加 special token 。
BertProcessing 会把 [SEP] token 和 [CLS] token 添加到被 tokenized 的 token 序列中。
class tokenizers.processors.ByteLevel( trim_offsets = True)：ByteLevel BPE 的 Post-processor 。
参数：
- trim_offsets：一个布尔值，是否从生成的 offsets 中移除空格。
方法：参考 BertProcessing 。
这个 Post-processor 会小心地裁剪 offsets 。默认情况下，ByteLevel BPE 可能会在生成的 token 中包含空格。如果你不希望 offsets 中包含这些空格，则可以使用这个 Post-processor 。
class tokenizers.processors.RobertaProcessing( sep, cls, trim_offsets=True, add_prefix_space=True)：Roberta 的 Post-processor 。
参数：
- sep,cls：参考 BertProcessing。
- trim_offsets：参考 ByteLevel 。
- add_prefix_space：一个布尔值，指定是否在 pre-tokenization 阶段启用了 add_prefix_space 。这个参数是为了配合 trim_offsets 使用。
方法：参考 BertProcessing 。
class tokenizers.processors.TemplateProcessing(single, pair, special_tokens)：这是一个 Post-processor 的模板，以便将 special token 添加到相关的每个输入序列。、
参数：
- single：一个模板字符串或模板字符串列表，用于单个输入序列。如果是字符串，那么使用空格来拆分 token 。
- pair：一个模板字符串或模板字符串列表，用于一对输入序列。如果是字符串，那么使用空格来拆分 token 。
  模板的标准格式为 <identifier>(:<type_id>) 。
  - 模板中可以基于 type_id 来占位，如 "[CLS] $0, $1, $2 [SEP]" ，此时 identifier 默认为 A 。
  - 模板中也可以基于 sequence identifier 来占位，如 "[CLS] $A, $B [SEP]" ，此时 type_id 默认为 0 。
  - 模板中也可以同时使用 type_id 和 sequence 来占位，如 "[CLS] $A:0 [SEP]" 。
- special_tokens：一个元组序列，指定每个模板字符串使用的 special token 及其id 。
  或者是一个字典，键包括："id" ，指定 special token id；"ids"，指定关联的 ID；"tokens"：指定关联的 token 。
方法：参考 BertProcessing 。
以 BERT tokenizer 为例，它需要两个 special token ：[CLS] （用于第一个句子的开头）、 [SEP] （用于每个句子的结尾）。最终结果看起来如下所示：
```
xxxxxxxxxx
"[CLS] Hello there [SEP]"  # 单个输入序列
"[CLS] My name is Anthony [SEP] What is my name? [SEP]" # 一对输入序列
```
其中这一对输入序列的 type-id 如下：
```
xxxxxxxxxx
[CLS]   ...   [SEP]   ...   [SEP]
0      0      0      1      1
```
此时可以应用 TemplateProcessing 为：
```
xxxxxxxxxx
TemplateProcessing(
    single="[CLS] $0 [SEP]",
    pair="[CLS] $A [SEP] $B:1 [SEP]:1",
    special_tokens=[("[CLS]", 1), ("[SEP]", 0)],
)
```
注意：[SEP]:1 表示最后一个 [SEP] 的 type_id = 1 。

3.6 Decoders

class tokenizers.decoders.BPEDecoder(suffix = '</w>')：BPE 解码器。
参数：suffix ：一个字符串，用来表示单词结尾的后缀。在解码过程中，这个后缀将被替换为空格。
方法：
- decode(tokens)：解码给定的 token 列表，返回解码后的字符串。
class tokenizers.decoders.ByteLevel()：ByteLevel 解码器，用于 ByteLevel PreTokenizer 配合使用。
方法：参考 BPEDecoder 。
class tokenizers.decoders.CTC( pad_token = '<pad>', word_delimiter_token = '|', cleanup = True) ：CTC 解码器。
参数：
- pad_token：一个字符串，由 CTC 使用来分隔一个新的 token 。
- word_delimiter_token：一个字符串，表示单词的分隔符 token，它将被空格符替代。
- cleanup：一个字符串，指定是否清理一些人工增加的 token ，如标点符号之前的空格。
方法：参考 BPEDecoder 。
class tokenizers.decoders.Metaspace(replacement='▁', add_prefix_space =True) ：Metaspace 解码器。
参数：
- replacement：一个字符串，指定编码时的替换字符（必须为单个字符）。默认为 '▁' （U+2581），被 SentencePiece 所使用。
- add_prefix_space：一个布尔值，指定编码时是否启用了 add_prefix_space 。
方法：参考 BPEDecoder 。
class tokenizers.decoders.WordPiece(prefix='##', cleanup=True)：WordPiece 编码器。
参数：
- prefix：一个字符串，指定编码时的 prefix。
- cleanup：一个布尔值，指定是否清理一些人工增加的 token ，如标点符号之前的空格。
方法：参考 BPEDecoder 。

3.7 Tokenizer

class tokenizers.Tokenizer(model)：Tokenizer，它处理原始文本输入并输出一个 Encoding 对象。
参数：
- model：一个 Model 对象，代表 Tokenizer 使用到的核心算法，如 tokenizers.models.BPE 等等。
属性：
- decoder：一个 Decoder 对象，代表 Tokenizer 使用到的解码器，如 tokenizers.decoders.BPEDecoder 。
- model：一个 Model 对象，代表 Tokenizer 使用到的核心算法。
- normalizer：一个 Normalizer 对象，用于对输入进行标准化。
- padding：一个字典，如果开启 padding，则它给出当前的 padding 参数。
  该属性无法被 set，可以用 enable_padding() 来开启。
- post_processor：一个 PostProcessor 对象，用于后处理。
- pre_tokenizer：一个 PreTokenizer 对象，用于前处理。
- truncation：一个字典，如果开启 truncation，则它给出当前的 truncation 参数。
  该属性无法被 set，可以用 enable_truncation() 来开启。
方法：
- add_special_tokens(tokens) -> int：添加指定的 special token 到 Tokenizer。
  参数： tokens：一个字符串列表或 AddedToken 列表，指定被添加的 special token 。这些 special token 被添加到词表。
  返回值：词表中被新增的 token 数量。如果 special token 已经位于词表中，那么它就不是新增的了。
  这些 special token 不会被 model 处理（即，不会被拆分为多个 token），并且在解码期间从输出中被删除。
- add_tokens(tokens) -> int ：添加指定的 token 到 Tokenizer。
  参数和返回值：参考 add_special_tokens 。
  这些 token 不会被 model 处理（即，不会被拆分为多个 token）。
- decode( ids, skip_special_tokens = True) -> str：解码得到字符串。
  参数：
  - ids：一个整数序列，表示待解码的 token id 。
  - skip_special_tokens：一个布尔值，指定是否从解码结果中移除 special token 。
- decode_batch( sequences, skip_special_tokens = True) -> List[str] ：解码一个 batch 的字符串。
  参数：
  - sequences：一个 batch 的整数序列，表示待解码的 token id 。
  - skip_special_tokens：参考 decode 。
- enable_padding(direction = 'right', pad_id = 0, pad_type_id = 0, pad_token = '[PAD]', length = None, pad_to_multiple_of = None)：启用 padding 功能。
  参数：
  - direction：一个字符串，指定填充方式，可以是左填充 'left' 或右填充 'right' 。
  - pad_id：一个整数，指定 pad token 的 id 。
  - pad_token：一个字符串，指定 pad token 字符串。
  - length：一个整数，指定填充后的字符串长度。如果为 None，则选择 batch 中的最长序列的长度。
  - pad_to_multiple_of：一个整数，假设为 $n$ $ n $ ，那么填充后的长度与 $2^{n}$ $ 2^n $ 对齐。例如，length=250，但是 pad_to_multiple_of=8，那么将填充到长度为 256 。
- enable_truncation( max_length, stride=0, strategy = 'longest_first', direction='right') ：启用 truncation 功能。
  参数：
  - max_length：一个整数，指定截断后的字符串长度。
  - stride：一个整数，指定在溢出序列中，需要包含前一个序列的长度。
    溢出序列指的是被截断后的尾部序列。如 abcdefg，截断长度为 4，stride=2，那么截断方式为：abcd, cdef, efg 。
  - strategy：一个字符串，指定截断的策略。可以为："longest_first"、"only_first "、"only_second" 。
    其中 "only_first "、"only_second" 用于句子对，仅对第一个句子或第二个句子进行截断。
  - direction：一个字符串，指定截断方向。可以为："left"、"right" 。
- encode(sequence, pair = None, is_pretokenized = False, add_special_tokens = True) -> Encoding ：编码指定的句子或句子对，返回编码结果。
  参数：
  - sequence：一个 InputSequence 对象，指定输入的句子。如果 is_pretokenized =True，那么 sequence 是 PreTokenizedInputSequence 对象；否则是 TextInputSequence 对象。
  - pair：一个 InputSequence 对象，指定输入的句子pair 。如果 is_pretokenized =True，那么 sequence 是 PreTokenizedInputSequence 对象；否则是 TextInputSequence 对象。
  - is_pretokenized：一个布尔值，指定输入是否已经被 pre-tokenized 。
  - add_special_tokens：一个布尔值，指定是否添加 special token 。
- encode_batch(input, is_pretokenized = False, add_special_tokens = True) -> List[Encoding] ：编码一个 batch 的句子或句子对，返回编码结果。
  参数：
  - input： TextInputSequence 或者 PreTokenizedInputSequence 的一个列表。参考 encode() 。
  - is_pretokenized/add_special_tokens：参考 encode() 。
- from_buffer( buffer ) -> Tokenizer：从 buffer 中创建并返回一个 Tokenizer 。
  参数：buffer：一个 bytes ，包含了已经序列化好的 Tokenizer 。
- from_file( path) -> Tokenizer：从文件中创建并返回一个 Tokenizer 。
  参数：path：一个本地 JSON 文件，包含了已经序列化好的 Tokenizer 。
- from_pretrained(identifier, revision = 'main', auth_token = None) -> Tokenizer ：从 Hugging Face Hub 上的已有文件来创建并返回一个 Tokenizer 。
  参数：
  - identifier：一个字符串，用于指定 Hugging Face Hub 上的一个模型，它包含一个 tokenizer.json 文件。
  - revision：指定选择 Hugging Face Hub 上的模型的哪个 git branch 或者 git commit id 。
  - auth_token：一个字符串，指定 auth token 从而用于访问 Hugging Face Hub 上的私有 repository 。
- from_str(json) -> Tokenizer：从字符串中创建并返回一个 Tokenizer 。
  参数：json：一个有效的 JSON 字符串，表示已经序列化好的 Tokenizer 。
- get_vocab( with_added_tokens = True) -> Dict[str, int] ：返回词表（token 及其 id ）。
  参数：
  - with_added_tokens：一个布尔值，指定是否包含 added token 。
- get_vocab_size( with_added_tokens = True) ->int ：返回词表的大小。
  参数：参考 get_vocab() 。
- id_to_token(id) -> str：将 id 转换回字符串。如果 id 不在词表中，则返回 None 。
  参数：id：一个整数，表示要转换的 id 。
- no_padding()：关闭 padding 。
- no_truncation()：关闭 truncation 。
- num_special_tokens_to_add( is_pair)：返回预期要添加到单个句子或者句子对中的 special token 的数量。
  参数：is_pair：一个布尔值，表示要计算单个句子的还是句子对的 special token 数量。
- post_process(encoding, pair = None, add_special_tokens = True ) -> Encoding：final 后处理。
  参数：
  - encoding：一个 Encoding 对象，表示对单个句子的编码结果。
  - pair：一个 Encoding 对象，表示对句子对的编码结果。
  - add_special_tokens：一个布尔值，指定是否添加 special token 。
  后处理步骤包括：
  - 根据 truncation 参数执行截断（根据 enable_truncation()来开启）。
  - 应用 PostProcessor 。
  - 根据 padding 参数执行填充（根据 enable_padding() 来开启）。
- save(path, pretty=True)：将 Tokenizer 保存到指定路径的文件。
  参数：
  - path：一个字符串，指定保存文件的路径。
  - pretty：一个布尔值，指定保存的 JSON 文件是否需要被 pretty formated 。
- to_str(pretty = False) -> str：返回一个字符串代表被序列化的 Tokenizer 。
- token_to_id(token) -> int：将给定的 token 转换为对应的 id。如果 token 不在词表中，则返回 None 。
  参数：token：一个字符串，指定待转换的 token 。
- train(files, trainer = None)：利用给定的文件来训练 Tokenizer 。
  参数：
  - files：一个字符串列表，指定用于训练 Tokenizer 的文件路径。
  - trainer：一个 Trainer 对象，指定用于训练 Model 的 trainer 。
  该方法从文件中一行一行地读取，保留所有的空格和换行符。
- train_from_iterator(iterator, trainer=None, length=None)：利用给定的迭代器来训练 Tokenizer 。
  参数：
  - iterator：一个 Iterator 对象，对它迭代的结果返回字符串或者字符串列表。
  - trainer：一个 Trainer 对象，指定用于训练 Model 的 trainer 。
  - length：一个整数，指定 iterator 中的序列数量，这用于提供有意义的进度跟踪。
tokenizers.InputSequence：代表所有类型的输入序列，作为 Tokenizer 的输入。
如果 is_pretokenized=False，则为 TextInputSequence；如果 is_pretokenized=True，则为 PreTokenizedInputSequence 。
- tokenizers.TextInputSequence：一个字符串，代表一个输入序列。
  TextInputSequence 就是 str 的别名。
- tokenizers.PreTokenizedInputSequence：一个 pre-tokenized 的输入序列，可以为一个字符串列表、或者一个字符串元组。
  PreTokenizedInputSequence 是 Union[List[str], Tuple[str]] 的别名。
tokenizers.EncodeInput ：代表所有类型的、用于 batch 编码的输入序列，作为 Tokenizer 的 batch 编码的输入。
如果 is_pretokenized=False，则为 TextEncodeInput；如果 is_pretokenized=True，则为 PreTokenizedEncodeInput 。
- tokenizers.TextEncodeInput：用于编码的文本输入，可以为 TextInputSequence 的一个元组、或者长度为 2 的列表。
  TextEncodeInput 是 Union[str, Tuple[str, str], List[str]] 的别名。
- tokenizers.PreTokenizedEncodeInput： pre-tokenized 的、用于编码的文本输入。可以为 PreTokenizedInputSequence 的一个序列、或者一对序列（每个元素为 PreTokenizedInputSequence 的元组或者长度为 2 的列表）。
  PreTokenizedEncodeInput 是 Union[List[str], Tuple[str], Tuple[Union[List[str], Tuple[str]], Union[List[str], Tuple[str]]], List[Union[List[str], Tuple[str]]]] 的别名。
class tokenizers.AddedToken(content, single_word=False, lstrip=False, rstrip=False, normalized=True)：代表要被添加到 Tokenizer 中的一个 token 。
参数：
- content：一个字符串，指定 token 的内容。
- single_word：一个布尔值，指定该 token 是否仅匹配单个 word 。例如，该值为 True 时，"ing" 不会匹配单词 "playing" ；改值为 False 时，"ing" 可以匹配单词 "playing" 。
- lstrip：一个布尔值，指定是否移除该 token 的所有左侧空格。
- rstrip：一个布尔值，指定是否移除该 token 的所有右侧空格。
- normalized：一个布尔值，指定该 token 是否匹配输入文本的 normalized 版本。
class tokenizers.Encoding()：Encoding 代表 Tokenizer 的输出。
属性：
- attention_mask：一个整数列表，给出attention mask ，表示哪些 token 应该被 attended （1 对应的）、哪些不应该被 attended （0 对应的）。
- ids：一个整数列表，给出编码后的 ID 列表。
- n_sequences：一个整数，返回 Encoding 中包含多少个句子。
- offsets：元组(int, int) 的一个列表，指定每个 token 的偏移量（相对于文本开头）。通过这个 offsets 以及给定的文本，你可以获取对应的 token 。
- overflowing： overflowing Encoding 的一个列表。当使用截断时， Tokenizer 会根据需要将输出分成尽可能多的部分，从而匹配指定的 max length 。这个字段允许你检索所有截断之后的、后续的片段。
  当你使用句子对时，overflowing pieces 将包含足够多的变化，从而覆盖所有可能的组合，同时考虑到所提供的 max length 。
- sequence_ids：一个整数列表，表示序列的 id （一个序列就是一个句子）。每个 id 代表一个句子并关联到该句子的每个 token 。
  注意，如果 token 属于任何句子（如 special token ），那么它的 sequence_id 为 None 。
- special_token_mask：一个整数列表，指定哪些 token 是 special token、哪些不是。
- tokens：一个字符串列表，表示生成的 token 序列。
- type_ids：一个整数列表，表示生成的 type ID。常用于序列分类或问答任务，使得语言模型知道每个 token 来自于哪个输入序列。
  它和 sequence_ids 相同的功能。
- word_ids：一个整数列表，指定每个单词的位置编号（用于指示哪些 token 是属于同一个单词）。它们表示每个 token 关联的单词的位置。
  如果输入是 pre-tokenized，那么它们对应于给定的 input label 的 ID；否则它们对应于所使用的 PreTokenizer 定义的单词索引。
  例如，如果 word_ids = [0,0,0,1] ，那么表明前三个 token 都属于同一个单词，第四个 token 属于另一个单词。
- words：一个整数的列表，指定生成的单词的索引。将来被废弃，推荐使用 word_ids 属性。
方法：
- char_to_token(char_pos, sequence_index=0) -> int：返回包含指定字符的 token 是 token 序列中的第几个 token 。
  参数：
  - char_pos：一个整数，指定目标字符在输入序列的哪个位置。
  - sequence_index：一个整数，指定目标字符位于哪个句子。
- char_to_word(char_pos, sequence_index=0) -> int ：返回包含指定字符是该句子中的第几个单词。
  参数：参考 char_to_token() 。
- merge( encodings, growing_offsets = True ) -> Encoding：合并 encoding 列表到 final Encoding 。
  参数：
  - encodings：一个 Encoding 列表，表示待合并的 encoding 。
  - growing_offsets：一个布尔值，指定合并过程中，偏移量是否需要累加。
- pad(length, direction = 'right', pad_id = 0, pad_type_id = 0, pad_token = '[PAD]' ) ：将 Encoding 填充到指定长度。
  参数：
  - length：一个整数，指定要填充到的长度。
  - direction：一个字符串，指定填充方式，可以是左填充 'left' 或右填充 'right' 。
  - pad_id：一个整数，指定 pad token 的 id 。
  - pad_type_id：一个整数，指定 pad token 对应的 type ID 。
  - pad_token：一个字符串，指定 pad token 字符串。
- set_sequence_id(sequence_id)：设定为当前 Encoding 中的所有 token 设置 sequence_id 。
  参数：sequence_id：一个整数，指定 sequence_id 。
- token_to_chars(token_index) -> Tuple[int, int] ：获取指定 token 的偏移量。通过这个偏移量，我们可以从原始的输入序列中获取到该 token 。
  参数：token_index：被编码的序列中的 token 的索引。
- token_to_sequence(token_index) -> int ：获取指定 token 的 sequence id 。
  参数：token_index：被编码的序列中的 token 的索引。
  对于单个句子的输入，返回结果通常是 0 ；对于句子对的输入，如果 token 位于第一个句子则返回 0；如果位于第二个句子则返回 1 。
- token_to_word(token_index) -> int：获取包含指定 token 的单词是该句子中的第几个单词。
  参数：token_index：被编码的序列中的 token 的索引。
- truncate(max_length, stride=0, direction='right')：截断 Encoding 到指定的长度。
  参数：
  - max_length：一个整数，指定要截断到的长度。
  - stride：一个整数，指定每个 overflowing 片段包含前一个片段的长度（以 token 为基本单位）。
  - direction：一个字符串，指定截断方向。可以为 'right' 或 'left' 。
  如果 Encoding 代表多个序列，那么截断之后，这个信息被丢失。结果被认为是单个序列。
- word_to_chars(word_index, sequence_index = 0) -> Tuple(int, int) ：返回指定的单词在原始句子中的区间。
  参数：
  - word_index：一个整数，指定了目标单词的索引。
  - sequence_index：一个整数，指定目标单词位于哪个句子。
- word_to_tokens(word_index, sequence_index = 0) -> Tuple(int, int)：返回指定的单词在 token 序列中的区间。
  参数：参考 word_to_chars 。
class tokenizers.tools.Annotation(start: int, end:int, label:str)：一个 Annotation ，用于可视化。
参数：
- start：一个整数，指定位于字符串中的开始位置。
- end：一个整数，指定位于字符串中的结束位置。
- label：一个字符串，指定 label 字符串。
class tokenizers.tools.EncodingVisualizer(tokenizer: Tokenizer, default_to_notebook: bool = True, annotation_converter:typing.Union[typing.Callable[[typing.Any], tokenizers.tools.visualizer.Annotation], NoneType] = None )：构建一个 EncodingVisualizer 。
参数：
- tokenizer：一个Tokenizer 对象，表示 tokenizer 实例。
- default_to_notebook：一个布尔值，指定是否渲染 html 输出从而适配 notebook 。
- annotation_converter：一个可调用对象，它通常是一个 lambda 函数，接受一个任意类型的输入并返回一个 Annotation 对象。
方法：
- __call__(text: str, annotations: typing.List[tokenizers.tools.visualizer.Annotation] = [], default_to_notebook: typing.Optional[bool] = None )：对给定的文本构建一个可视化。
  参数：
  - text：一个字符串，指定需要被 tokenize 的字符串。
  - annotations：text 对应的一个列表的注解。可以是一个 Annotation 类，或者通过一个转换函数返回一个 Annotation 。
  - default_to_notebook：一个布尔值，如果为 True 则渲染 html 字符串到 notebook；否则直接返回一个 html 字符串。