# mLUKE

## 概述

mLUKE 模型由 Ryokan Ri、Ikuya Yamada 和 Yoshimasa Tsuruoka 在 [mLUKE: The Power of Entity Representations in Multilingual Pretrained Language Models](https://huggingface.co/papers/2110.08151) 中提出。它是基于 XLM-RoBERTa 训练的 [LUKE 模型](https://huggingface.co/papers/2010.01057) 的多语言扩展版本。

它基于 XLM-RoBERTa，并添加了实体嵌入，这有助于提升涉及实体推理的各种下游任务的性能，例如命名实体识别、抽取式问答、关系分类和完形填空式知识补全。

该论文的摘要如下：

*近期研究表明，利用维基百科实体中的跨语言对齐信息，可以有效提升多语言预训练语言模型的性能。然而，现有方法仅在预训练阶段利用实体信息，并未在下游任务中显式使用实体。在本研究中，我们探讨了利用实体表示来执行下游跨语言任务的有效性。我们训练了一个包含 24 种语言、并融合了实体表示的多语言语言模型，结果表明该模型在各种跨语言迁移任务中始终优于基于词元的预训练模型。我们还对该模型进行了分析，关键洞察在于：将实体表示纳入输入，使我们能够提取出更多与语言无关的特征。此外，我们使用 mLAMA 数据集，通过多语言完形填空提示任务对该模型进行了评估。结果表明，与仅使用词元表示相比，基于实体的提示更有可能激发出正确的事实知识。*

该模型由 [ryo0634](https://huggingface.co/ryo0634) 贡献。原始代码可在[此处](https://github.com/studio-ousia/luke)找到。

## 使用技巧

可以直接将 mLUKE 的权重加载到 LUKE 模型中，如下所示：

```python
from transformers import LukeModel

model = LukeModel.from_pretrained("studio-ousia/mluke-base", device_map="auto")
```

请注意，mLUKE 拥有自己的分词器 [MLukeTokenizer](/docs/transformers/main/zh/model_doc/mluke#transformers.MLukeTokenizer)。您可以按以下方式对其进行初始化：

```python
from transformers import MLukeTokenizer

tokenizer = MLukeTokenizer.from_pretrained("studio-ousia/mluke-base")
```

由于 mLUKE 的架构与 LUKE 相同，有关所有技巧、代码示例和笔记本，请参阅 [LUKE 的文档页面](luke)。

## MLukeTokenizer[[transformers.MLukeTokenizer]]

#### transformers.MLukeTokenizer[[transformers.MLukeTokenizer]]

```python
transformers.MLukeTokenizer(bos_token = '<s>', eos_token = '</s>', sep_token = '</s>', cls_token = '<s>', unk_token = '<unk>', pad_token = '<pad>', mask_token = '<mask>', task = None, max_entity_length = 32, max_mention_length = 30, entity_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 = None, entity_vocab: str | dict | list | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L129)

**参数：**

vocab_file (`str`) : 词汇表文件的路径。

entity_vocab_file (`str`) : 实体词汇表文件的路径。

bos_token (`str`, *可选*, 默认为 `"<s>"`) : 预训练期间使用的序列起始标记。可用作序列分类标记。 在使用特殊标记构建序列时，序列起始处使用的并非此标记，而是 `cls_token`。

eos_token (`str`, *可选*, 默认为 `"</s>"`) : 序列结束标记。 在使用特殊标记构建序列时，序列结束使用的标记并非此标记，而是 `sep_token`。

sep_token (`str`，*可选*，默认为 `"</s>"`)：分隔符标记，用于从多个序列构建序列时，例如用于序列分类的两个序列，或用于问答的文本和问题。它也用作使用特殊标记构建的序列的最后一个标记。

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 封装](https://github.com/google/sentencepiece/tree/master/python) 可用于设置以下参数： - `enable_sampling`：启用子词正则化。 - `nbest_size`：unigram 的采样参数。对 BPE-Dropout 无效。  - `nbest_size = {0,1}`：不执行采样。 - `nbest_size > 1`：从 nbest_size 个结果中进行采样。 - `nbest_size < 0`：假设 nbest_size 为无穷大，并使用前向过滤与后向采样算法从所有假设（格）中进行采样。  - `alpha`：unigram 采样的平滑参数，以及 BPE-dropout 中合并操作的 dropout 概率。

sp_model (`SentencePieceProcessor`)：用于所有转换（字符串、token 和 ID）的 *SentencePiece* 处理器。

改编自 [XLMRobertaTokenizer](/docs/transformers/main/zh/model_doc/xlm-roberta#transformers.XLMRobertaTokenizer) 和 [LukeTokenizer](/docs/transformers/main/zh/model_doc/luke#transformers.LukeTokenizer)。基于 [SentencePiece](https://github.com/google/sentencepiece)。

该分词器继承自 [PreTrainedTokenizer](/docs/transformers/main/zh/main_classes/tokenizer#transformers.PythonBackend)，后者包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。

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

```python
__call__(text: str | list[str], text_pair: str | list[str] | None = None, entity_spans: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entity_spans_pair: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entities: list[str] | list[list[str]] | None = None, entities_pair: list[str] | list[list[str]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = None, max_length: int | None = None, max_entity_length: int | None = None, stride: int = 0, is_split_into_words: bool | None = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L469)

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

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

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

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

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

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

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

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

- **entity_ids** -- 要输入模型的实体 ID 列表。

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

- **entity_position_ids** -- 输入序列中要提供给模型的实体位置列表。

- **entity_token_type_ids** -- 要输入模型的实体 token 类型 id 列表（当 `return_token_type_ids=True` 或 *"entity_token_type_ids"* 位于 `self.model_input_names` 中时）。

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

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

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

- **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](/docs/transformers/main/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：启用并控制填充。接受以下值：

- `True` 或 `'longest'`：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。
- `'max_length'`：填充至参数 `max_length` 指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。
- `False` 或 `'do_not_pad'`（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
truncation (`bool`、`str` 或 [TruncationStrategy](/docs/transformers/main/zh/internal/tokenization_utils#transformers.tokenization_utils_base.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](/docs/transformers/main/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为：

- `'pt'`：返回 PyTorch `torch.Tensor` 对象。
- `'np'`：返回 Numpy `np.ndarray` 对象。

return_token_type_ids (`bool`，*可选*)：是否返回 token 类型 ID。如果保持默认值，则根据特定分词器的默认设置返回 token 类型 ID，该设置由 `return_outputs` 属性定义。

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

[什么是注意力掩码？](../glossary#attention-mask) 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](/docs/transformers/main/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的快速分词器；如果使用 Python 分词器，此方法将引发 `NotImplementedError`。return_length (`bool`，*可选*，默认为 `False`)：是否返回编码输入的长度。verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。**kwargs：传递给 `self.tokenize()` 方法

#### save_vocabulary[[transformers.MLukeTokenizer.save_vocabulary]]

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

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L1703)

仅保存实体词汇表文件。tokenizer.json 由父级 TokenizersBackend 保存。

