# 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をベースとし、エンティティ埋め込みを追加しています。これにより、名前付きエンティティ認識、抽出型質問応答、関係分類、クローズ型知識補完など、エンティティに関する推論を含むさまざまな下流タスクでのパフォーマンスが向上します。

論文の抄録は以下の通りです。

*最近の研究により、多言語事前学習言語モデルは、Wikipediaエンティティからの言語間アラインメント情報を用いることで効果的に改善できることが示されています。しかし、既存の手法は事前学習においてエンティティ情報を利用するのみで、下流タスクにおいてエンティティを明示的に使用していません。本研究では、下流の言語間タスクにおいてエンティティ表現を活用する有効性を検討します。エンティティ表現を用いて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/ja/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>"`) : 区切りトークンです。複数のシーケンスからシーケンスを構築する際に使用されます。例えば、シーケンス分類では2つのシーケンス、質問応答ではテキストと質問です。また、特殊トークンを用いて構築されたシーケンスの最後のトークンとしても使用されます。

cls_token (`str`、*任意*、デフォルトは `"<s>"`) : シーケンス分類（トークンごとの分類ではなく、シーケンス全体に対する分類）を行う際に使用される分類トークンです。特殊トークンを用いて構築された場合、シーケンスの最初のトークンになります。

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`、*optional*、デフォルトは 30)：エンティティスパン内の最大トークン数。

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`: ユニグラムのサンプリングパラメータ。BPE-Dropout では無効です。  - `nbest_size = {0,1}`: サンプリングは行われません。 - `nbest_size > 1`: nbest_size 個の結果からサンプリングします。 - `nbest_size < 0`: nbest_size が無限であると仮定し、forward-filtering-and-backward-sampling アルゴリズムを使用してすべての仮説（ラティス）からサンプリングします。  - `alpha`: ユニグラムサンプリングのスムーthingパラメータ、および BPE-dropout におけるマージ操作のドロップアウト確率。

sp_model (`SentencePieceProcessor`) : すべての変換（文字列、トークン、ID）に使用される*SentencePiece*プロセッサです。

[XLMRobertaTokenizer](/docs/transformers/main/ja/model_doc/xlm-roberta#transformers.XLMRobertaTokenizer) および [LukeTokenizer](/docs/transformers/main/ja/model_doc/luke#transformers.LukeTokenizer) を基に作成しました。[SentencePiece](https://github.com/google/sentencepiece) に基づいています。

このトークナイザーは、[PreTrainedTokenizer](/docs/transformers/main/ja/main_classes/tokenizer#transformers.PythonBackend) を継承しており、主要なメソッドのほとんどが含まれています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。

#### __call__[[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/ja/main_classes/tokenizer#transformers.BatchEncoding)

以下のフィールドを持つ[BatchEncoding](/docs/transformers/main/ja/main_classes/tokenizer#transformers.BatchEncoding):

- **input_ids** -- モデルに渡すトークンIDのリスト。

  [入力IDとは何ですか？](../glossary#input-ids)

- **token_type_ids** -- モデルに渡すトークンタイプIDのリスト（`return_token_type_ids=True`の場合、または`self.model_input_names`に*"token_type_ids"*が含まれる場合）。

  [トークンタイプIDとは?](../glossary#token-type-ids)

- **attention_mask** -- モデルがどのトークンに注意すべきかを指定するインデックスのリスト（`return_attention_mask=True` の場合、または `self.model_input_names` に *"attention_mask"* が含まれている場合）。

  [アテンションマスクとは?](../glossary#attention-mask)

- **entity_ids** -- モデルに渡すエンティティIDのリスト。

  [入力IDとは何ですか？](../glossary#input-ids)

- **entity_position_ids** -- モデルに渡す入力シーケンス内のエンティティの位置のリスト。

- **entity_token_type_ids** -- モデルに渡すエンティティトークンタイプIDのリスト(`return_token_type_ids=True` の場合、または `self.model_input_names` に *"entity_token_type_ids"* が含まれている場合)。

  [トークンタイプIDとは?](../glossary#token-type-ids)

- **entity_attention_mask** -- モデルがどのエンティティに注意を払うべきかを指定するインデックスのリスト（`return_attention_mask=True`の場合、または`self.model_input_names`に*"entity_attention_mask"*が含まれている場合）。

  [アテンションマスクとは?](../glossary#attention-mask)

- **entity_start_positions** -- `task="entity_span_classification"`の場合、単語トークン列におけるエンティティの開始位置のリスト。
- **entity_end_positions** -- `task="entity_span_classification"`の場合、単語トークン列におけるエンティティの終了位置のリスト。
- **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_special_tokens (`bool`、*任意*、デフォルトは`True`): シーケンスをエンコードする際に特殊トークンを追加するかどうか。これは、入力 ID に自動的に追加されるトークンを定義する基盤となる`PretrainedTokenizerBase.build_inputs_with_special_tokens`関数を使用します。`bos`または`eos`トークンを自動的に追加したい場合に便利です。padding (`bool`、`str`または[PaddingStrategy](/docs/transformers/main/ja/internal/file_utils#transformers.utils.PaddingStrategy)、*任意*、デフォルトは`False`): パディングを有効にし、制御します。以下の値を受け入れます:

- `True` または `'longest'`: バッチ内の最長のシーケンスの長さにパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。
- `'max_length'`: 引数 `max_length` で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。
- `False` または `'do_not_pad'`（デフォルト）：パディングを行いません（つまり、長さが異なるシーケンスのバッチを出力できます）。
truncation (`bool`、`str`または[TruncationStrategy](/docs/transformers/main/ja/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)、*省略可能*、デフォルトは`False`)：切り詰めを有効化し、制御します。以下の値を受け入れます：

- `True` または `'longest_first'`: 引数 `max_length` で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れられる最大入力長まで切り詰めます。この場合、トークン単位で切り詰められ、ペアのシーケンス（またはペアのバッチ）が提供されている場合は、ペアの中で最も長いシーケンスから1トークンずつ削除します。
- `'only_first'`: 引数 `max_length` で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れられる最大入力長まで切り詰めます。この設定では、シーケンスのペア（またはペアのバッチ）が提供された場合のみ、ペアの最初のシーケンスだけが切り詰められます。
- `'only_second'`: 引数 `max_length` で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長まで切り詰めます。このモードでは、ペアのシーケンス（またはペアのバッチ）が提供された場合のみ、ペアの2番目のシーケンスが切り詰められます。
- `False` または `'do_not_truncate'`（デフォルト）: トランケーションを行いません（つまり、モデルが許容する最大入力サイズを超えるシーケンス長を持つバッチを出力する可能性があります）。
max_length (`int`, *任意*): 切り詰め/パディングのパラメータのいずれかによって使用される最大長を制御します。

未設定または`None`に設定されている場合、truncation/padding パラメータのいずれかが最大長を必要とする場合、事前定義されたモデルの最大長が使用されます。モデルに特定の最大入力長がない場合（XLNet など）、最大長への truncation/padding は無効になります。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](/docs/transformers/main/ja/internal/file_utils#transformers.TensorType), *任意*): 設定すると、Python の整数のリストの代わりにテンソルを返します。許容される値は以下の通りです:

- `'pt'`: PyTorchの`torch.Tensor`オブジェクトを返します。
- `'np'`: Numpy の `np.ndarray` オブジェクトを返します。

return_token_type_ids (`bool`, *任意*): トークンタイプIDを返すかどうか。デフォルトのままにすると、`return_outputs` 属性で定義される特定のトークナイザーのデフォルトに従って、トークンタイプIDを返します。

[トークンタイプIDとは?](../glossary#token-type-ids) return_attention_mask (`bool`, *省略可*): アテンションマスクを返すかどうか。デフォルトのままにすると、`return_outputs` 属性で定義される特定のトークナイザーのデフォルトに従って、アテンションマスクを返します。

[アテンションマスクとは?](../glossary#attention-mask) 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](/docs/transformers/main/ja/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によって保存されます。