Transformers documentation
mLUKE
このモデルは2021年10月15日にHF papersで公開され、2021年12月7日に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をベースとし、エンティティ埋め込みを追加することで、名前付きエンティティ認識、抽出型質問応答、関係分類、クローズ型知識補完など、エンティティに関する推論を含むさまざまな下流タスクでのパフォーマンス向上に貢献します。
論文の抄録は以下の通りです。
最近の研究により、多言語事前学習言語モデルは、Wikipediaエンティティからのクロスリンガル整列情報を用いることで効果的に改善できることが示されています。しかし、既存の方法は事前学習においてエンティティ情報を利用するのみであり、下流タスクにおいてエンティティを明示的に使用していません。本研究では、下流のクロスリンガルタスクにおいてエンティティ表現を活用する有効性を検討します。エンティティ表現を用いて24言語の多言語言語モデルを訓練し、さまざまなクロスリンガル転移タスクにおいて、単語ベースの事前学習モデルを一貫して上回る性能を示すことを確認しました。また、モデルを分析した結果、入力にエンティティ表現を組み込むことで、より言語非依存の特徴を抽出できることが重要な知見として得られました。さらに、mLAMAデータセットを用いた多言語クローズプロンプトタスクでモデルを評価しました。エンティティベースのプロンプトは、単語表現のみを使用する場合よりも、正しい事実知識を引き出しやすいことを示しました。
このモデルは ryo0634 によって提供されました。元のコードは こちら で確認できます。
使用のコツ
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
クラス 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 (
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、任意、デフォルトは 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 ラッパー は、次のような設定を行うために使用できます:-
enable_sampling: サブワード正規化を有効にします。 -
nbest_size: unigramのサンプリングパラメータ。BPE-Dropoutでは無効です。nbest_size = {0,1}: サンプリングは行われません。nbest_size > 1: nbest_size 個の結果からサンプリングします。nbest_size < 0: nbest_size が無限大であると仮定し、forward-filtering-and-backward-sampling アルゴリズムを使用して、すべての仮説（ラティス）からサンプリングします。
-
alpha: 単一語サンプリングの平滑化パラメータ、および BPE-dropout におけるマージ操作のドロップアウト確率。
-
- sp_model (
SentencePieceProcessor) — すべての変換（文字列、トークン、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 — モデルに与えるトークン ID のリスト。
-
token_type_ids — モデルに渡すトークンタイプIDのリスト（
return_token_type_ids=Trueの場合、またはself.model_input_namesに“token_type_ids”が含まれている場合）。 -
attention_mask — モデルがどのトークンに注意を向けるべきかを指定するインデックスのリスト（
return_attention_mask=Trueの場合、またはself.model_input_namesに “attention_mask” が含まれている場合）。 -
entity_ids — モデルに渡すエンティティIDのリスト。
-
entity_position_ids — モデルに入力される入力シーケンス内のエンティティの位置のリスト。
-
entity_token_type_ids — モデルに渡すエンティティトークンタイプIDのリスト（
return_token_type_ids=Trueの場合、またはself.model_input_namesに “entity_token_type_ids” が含まれている場合）。 -
entity_attention_mask — モデルがどのエンティティに注意を払うべきかを指定するインデックスのリスト（
return_attention_mask=Trueの場合、またはself.model_input_namesに“entity_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、省略可、デフォルトは False):
パディングを有効化し、制御します。以下の値を受け入れます:
Trueまたは'longest': バッチ内の最長のシーケンスの長さにパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。'max_length': 引数max_lengthで指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。Falseまたは'do_not_pad'（デフォルト）: パディングを行いません（つまり、長さが異なるシーケンスのバッチを出力できます）。 truncation (bool、strまたは 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、任意):
設定すると、Python の整数のリストの代わりにテンソルを返します。許容される値は以下の通りです:
'pt': PyTorchのtorch.Tensorオブジェクトを返します。'np': Numpy のnp.ndarrayオブジェクトを返します。
return_token_type_ids (bool, 任意):
トークンタイプIDを返すかどうか。デフォルトのままにすると、return_outputs 属性によって定義される特定のトークナイザーのデフォルトに従って、トークンタイプIDを返します。
トークンタイプIDとは? 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() メソッドに渡されます
エンティティの語彙ファイルのみを保存します。tokenizer.jsonは、親のTokenizersBackendによって保存されます。