Transformers documentation
mLUKE
该模型于 2021-10-15 在 HF papers 上发布，并于 2021-12-07 贡献至 Hugging Face Transformers。
mLUKE
概述
mLUKE 模型由 Ryokan Ri、Ikuya Yamada 和 Yoshimasa Tsuruoka 在 mLUKE: The Power of Entity Representations in Multilingual Pretrained Language Models 中提出。它是基于 XLM-RoBERTa 训练的 LUKE 模型 的多语言扩展版本。
它基于 XLM-RoBERTa，并添加了实体嵌入，有助于提升涉及实体推理的各类下游任务的性能，例如命名实体识别、抽取式问答、关系分类以及填空式知识补全。
该论文的摘要如下：
近期研究表明，利用来自维基百科实体的跨语言对齐信息，可以有效提升多语言预训练语言模型的性能。然而，现有方法仅在预训练阶段利用实体信息，并未在下游任务中显式使用实体。本研究探讨了利用实体表示来执行下游跨语言任务的有效性。我们使用实体表示训练了一个涵盖 24 种语言的多语言语言模型，并证明该模型在各种跨语言迁移任务中始终优于基于词元的预训练模型。我们还对该模型进行了分析，关键洞察在于：将实体表示纳入输入有助于提取更多与语言无关的特征。此外，我们使用 mLAMA 数据集，通过多语言完形填空提示任务对该模型进行了评估。结果表明，基于实体的提示比仅使用词元表示更有可能激发正确的事实知识。
使用技巧
可以直接将 mLUKE 的权重加载到 LUKE 模型中，如下所示：
from transformers import LukeModel
model = LukeModel.from_pretrained("studio-ousia/mluke-base", device_map="auto")请注意，mLUKE 拥有自己的分词器 MLukeTokenizer。您可以按以下方式对其进行初始化：
from transformers import MLukeTokenizer
tokenizer = MLukeTokenizer.from_pretrained("studio-ousia/mluke-base")由于 mLUKE 的架构与 LUKE 相同，有关所有技巧、代码示例和笔记本，请参阅 LUKE 的文档页面。
MLukeTokenizer
class transformers.MLukeTokenizer
< source >( bos_token = '<s>'eos_token = '</s>'sep_token = '</s>'cls_token = '<s>'unk_token = '<unk>'pad_token = '<pad>'mask_token = '<mask>'task = Nonemax_entity_length = 32max_mention_length = 30entity_1_token = '<ent>'entity_2_token = '<ent2>'entity_unk_token = '[UNK]'entity_pad_token = '[PAD]'entity_mask_token = '[MASK]'entity_mask2_token = '[MASK2]'vocab: str | dict | list | None = Noneentity_vocab: str | dict | list | None = None**kwargs )
参数
- vocab_file (
str) — 词汇表文件的路径。 - entity_vocab_file (
str) — 实体词汇表文件的路径。 - bos_token (
str, 可选, 默认为"<s>") — 预训练期间使用的序列起始标记。也可用作序列分类标记。在构建序列时，如果使用了特殊标记，序列开头使用的并不是这个标记。实际使用的标记是
cls_token。 - eos_token (
str, 可选, 默认为"</s>") — 序列结束标记。在构建包含特殊标记的序列时，序列结束使用的并非此标记，而是 sep_token。在构建包含特殊标记的序列时，序列末尾使用的并不是这个标记。 实际使用的是
sep_token。 - sep_token (
str，可选，默认为"</s>") — 分隔符 token，用于从多个序列构建序列时，例如用于序列分类的两个序列，或用于问答的文本和问题。它也用作使用特殊 token 构建的序列的最后一个 token。 - cls_token (
str，可选，默认为"<s>") — 用于序列分类（对整个序列进行分类，而非逐 token 分类）的分类器 token。当使用特殊 token 构建序列时，它是序列的第一个 token。 - unk_token (
str，可选，默认为"<unk>") — 未知标记。不在词汇表中的标记无法转换为 ID，因此会被设置为该标记。 - pad_token (
str，可选，默认为"<pad>") — 用于填充的标记，例如在对长度不同的序列进行批处理时。 - mask_token (
str, 可选，默认为"<mask>") — 用于掩码值的标记。这是在以掩码语言建模方式训练该模型时所使用的标记，也是模型将尝试预测的标记。 - task (
str，可选) — 用于准备序列的任务。取值为"entity_classification"、"entity_pair_classification"或"entity_span_classification"之一。如果指定了此参数，则会根据给定的实体跨度自动创建实体序列。 - max_entity_length (
int，可选，默认为 32) —entity_ids的最大长度。 - max_mention_length (
int，可选，默认为 30) — 实体跨度内的最大 token 数量。 - entity_1_token (
str，可选，默认为<ent>) — 用于在词元序列中表示实体跨度的特殊标记。仅当task设置为"entity_classification"或"entity_pair_classification"时才会使用此标记。 - entity_2_token (
str，可选，默认为<ent2>) — 用于在词元序列中表示实体跨度的特殊标记。仅当task设置为"entity_pair_classification"时使用此标记。 - additional_special_tokens (
list[str]，可选，默认为["<s>NOTUSED", "</s>NOTUSED"]) — 分词器使用的额外特殊标记。 - sp_model_kwargs (
dict, 可选) — 将传递给SentencePieceProcessor.__init__()方法。 SentencePiece 的 Python 封装 可用于（除其他用途外）设置：-
enable_sampling：启用子词正则化。 -
nbest_size：一元模型的采样参数。对 BPE-Dropout 无效。nbest_size = {0,1}：不执行采样。nbest_size > 1：从 nbest_size 个结果中进行采样。nbest_size < 0：假设 nbest_size 为无穷大，并使用前向滤波与后向采样算法从所有假设（格）中进行采样。
-
alpha：用于一元采样（unigram sampling）的平滑参数，以及 BPE-dropout 中合并操作的 dropout 概率。
-
- sp_model (
SentencePieceProcessor) — 用于所有转换（字符串、token 和 ID）的 SentencePiece 处理器。
改编自 XLMRobertaTokenizer 和 LukeTokenizer。基于 SentencePiece。
该分词器继承自 PreTrainedTokenizer，其中包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。
__call__
< source >( text: str | list[str]text_pair: str | list[str] | None = Noneentity_spans: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = Noneentity_spans_pair: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = Noneentities: list[str] | list[list[str]] | None = Noneentities_pair: list[str] | list[list[str]] | None = Noneadd_special_tokens: bool = Truepadding: bool | str | transformers.utils.generic.PaddingStrategy = Falsetruncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = Nonemax_length: int | None = Nonemax_entity_length: int | None = Nonestride: int = 0is_split_into_words: bool | None = Falsepad_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_offsets_mapping: bool = Falsereturn_length: bool = Falseverbose: bool = True**kwargs ) → BatchEncoding
返回值
一个包含以下字段的 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中时）。 -
entity_ids — 要输入模型的实体 ID 列表。
-
entity_position_ids — 输入序列中实体位置的列表，用于提供给模型。
-
entity_token_type_ids — 要输入模型的实体 token 类型 ID 列表（当
return_token_type_ids=True或 “entity_token_type_ids” 位于self.model_input_names中时）。 -
entity_attention_mask — 一个索引列表，指定模型应关注哪些实体（当
return_attention_mask=True或 “entity_attention_mask” 位于self.model_input_names中时）。 -
entity_start_positions — 实体在词元序列中的起始位置列表（当
task="entity_span_classification"时）。 -
entity_end_positions — 实体在词元序列中的结束位置列表（当
task="entity_span_classification"时）。 -
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_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），则禁用截断/填充至最大长度的功能。
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。如果保持默认值，则根据特定 tokenizer 的默认设置返回 token type ID，该设置由 return_outputs 属性定义。
什么是 token type IDs？ return_attention_mask (bool, 可选)：
是否返回 attention mask。如果保持默认值，则根据特定 tokenizer 的默认设置返回 attention mask，该设置由 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)：
是否为每个 token 返回 (char_start, char_end)。
此功能仅适用于继承自 PreTrainedTokenizerFast 的快速分词器；如果使用 Python 分词器，此方法将引发 NotImplementedError。
return_length (bool，可选，默认为 False)：
是否返回编码后输入的长度。
verbose (bool，可选，默认为 True)：
是否打印更多信息和警告。
**kwargs：传递给 self.tokenize() 方法
仅保存实体词汇表文件。tokenizer.json 由父级 TokenizersBackend 保存。