# mLUKE ## Aperçu Le modèle mLUKE a été proposé dans [mLUKE: The Power of Entity Representations in Multilingual Pretrained Language Models](https://huggingface.co/papers/2110.08151) par Ryokan Ri, Ikuya Yamada et Yoshimasa Tsuruoka. Il s'agit d'une extension multilingue du [modèle LUKE](https://huggingface.co/papers/2010.01057), entraînée sur la base de XLM-RoBERTa. Il est basé sur XLM-RoBERTa et ajoute des embeddings d’entités, ce qui contribue à améliorer les performances sur diverses tâches en aval impliquant le raisonnement sur des entités, telles que la reconnaissance d’entités nommées, la réponse à des questions extractives, la classification de relations et la complétion de connaissances de type cloze. L'abstract de l'article est le suivant : *Des études récentes ont montré que les modèles de langage pré-entraînés multilingues peuvent être efficacement améliorés grâce à des informations d’alignement interlingual issues des entités de Wikipédia. Toutefois, les méthodes existantes n’exploitent les informations sur les entités que lors de la pré-entraînement et n’utilisent pas explicitement les entités dans les tâches en aval. Dans cette étude, nous explorons l’efficacité de l’exploitation des représentations d’entités pour les tâches interlinguales en aval. Nous entraînons un modèle de langage multilingue couvrant 24 langues avec des représentations d’entités et montrons que ce modèle surpasse systématiquement les modèles pré-entraînés basés sur les mots dans diverses tâches de transfert interlingual. Nous analysons également le modèle, et l’insight clé est que l’intégration des représentations d’entités dans l’entrée nous permet d’extraire des caractéristiques plus indépendantes de la langue. Nous évaluons également le modèle sur une tâche de prompt multilingue de type cloze avec le jeu de données mLAMA. Nous montrons qu’un prompt basé sur les entités suscite plus souvent des connaissances factuelles correctes qu’un prompt utilisant uniquement des représentations de mots.* Ce modèle a été contribué par [ryo0634](https://huggingface.co/ryo0634). Le code d'origine peut être trouvé [ici](https://github.com/studio-ousia/luke). ## Conseils d'utilisation On peut directement insérer les poids de mLUKE dans un modèle LUKE, comme suit : ```python from transformers import LukeModel model = LukeModel.from_pretrained("studio-ousia/mluke-base", device_map="auto") ``` Notez que mLUKE possède son propre tokenizer, [MLukeTokenizer](/docs/transformers/main/fr/model_doc/mluke#transformers.MLukeTokenizer). Vous pouvez l'initialiser comme suit : ```python from transformers import MLukeTokenizer tokenizer = MLukeTokenizer.from_pretrained("studio-ousia/mluke-base") ``` L’architecture de mLUKE étant équivalente à celle de LUKE, on peut se reporter à la [page de documentation de LUKE](luke) pour tous les conseils, exemples de code et notebooks. ## MLukeTokenizer[[transformers.MLukeTokenizer]] #### transformers.MLukeTokenizer[[transformers.MLukeTokenizer]] ```python transformers.MLukeTokenizer(bos_token = '~~', eos_token = '~~', sep_token = '', cls_token = '', unk_token = '', pad_token = '', mask_token = '', task = None, max_entity_length = 32, max_mention_length = 30, entity_1_token = '', entity_2_token = '', 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) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L129) **Paramètres :** vocab_file (`str`) : Chemin vers le fichier de vocabulaire. entity_vocab_file (`str`) : Chemin vers le fichier de vocabulaire des entités. bos_token (`str`, *facultatif*, valeur par défaut `""`) : Jeton de début de séquence utilisé lors de la préformation. Peut être utilisé comme jeton de classifieur de séquence. Lors de la construction d'une séquence à l'aide de jetons spéciaux, ce n'est pas le jeton utilisé pour le début de séquence. Le jeton utilisé est `cls_token`. eos_token (`str`, *facultatif*, par défaut `""`) : Jeton de fin de séquence. Lors de la construction d'une séquence à l'aide de jetons spéciaux, ce n'est pas le jeton utilisé pour la fin de séquence. Le jeton utilisé est le `sep_token`. sep_token (`str`, *facultatif*, valeur par défaut `""`) : le jeton séparateur, utilisé lors de la construction d'une séquence à partir de plusieurs séquences, par exemple deux séquences pour la classification de séquences ou un texte et une question pour le question answering. Il est également utilisé comme dernier jeton d'une séquence construite avec des jetons spéciaux. cls_token (`str`, *facultatif*, valeur par défaut `""`) : le jeton de classifieur utilisé lors de la classification de séquence (classification de la séquence entière plutôt que la classification par jeton). C'est le premier jeton de la séquence lorsqu'elle est construite avec des jetons spéciaux. unk_token (`str`, *facultatif*, par défaut `""`) : Le jeton inconnu. Un jeton qui n'est pas dans le vocabulaire ne peut pas être converti en identifiant et est remplacé par ce jeton. pad_token (`str`, *facultatif*, par défaut `""`) : le jeton utilisé pour le bourrage, par exemple lors du groupement de séquences de longueurs différentes. mask_token (`str`, *facultatif*, valeur par défaut `""`) : Le jeton utilisé pour masquer les valeurs. C'est le jeton utilisé lors de l'entraînement de ce modèle avec le modélisation de langage masquée. C'est le jeton que le modèle cherchera à prédire. task (`str`, *facultatif*) : Tâche pour laquelle vous souhaitez préparer les séquences. L'une des valeurs `"entity_classification"`, `"entity_pair_classification"` ou `"entity_span_classification"`. Si vous spécifiez cet argument, la séquence d'entités est automatiquement créée sur la base de l'intervalle d'entités fourni. max_entity_length (`int`, *facultatif*, valeur par défaut : 32) : La longueur maximale de `entity_ids`. max_mention_length (`int`, *facultatif*, valeur par défaut : 30) : Nombre maximal de jetons à l'intérieur d'une entité. entity_1_token (`str`, *facultatif*, valeur par défaut ``) : Le jeton spécial utilisé pour représenter une portée d'entité dans une séquence de jetons de mots. Ce jeton n'est utilisé que lorsque `task` est défini sur `"entity_classification"` ou `"entity_pair_classification"`. entity_2_token (`str`, *facultatif*, valeur par défaut ``) : Jeton spécial utilisé pour représenter une portée d'entité dans une séquence de jetons de mots. Ce jeton n'est utilisé que lorsque `task` est défini sur `"entity_pair_classification"`. additional_special_tokens (`list[str]`, *facultatif*, par défaut `["~~NOTUSED", "~~NOTUSED"]`) : Jetons spéciaux supplémentaires utilisés par le tokeniseur. sp_model_kwargs (`dict`, *facultatif*) : Sera transmis à la méthode `SentencePieceProcessor.__init__()`. Le [Python wrapper for SentencePiece](https://github.com/google/sentencepiece/tree/master/python) peut notamment être utilisé pour définir : - `enable_sampling` : Active la régularisation des sous-mots. - `nbest_size` : Paramètres d'échantillonnage pour unigramme. Invalide pour BPE-Dropout. - `nbest_size = {0,1}` : Aucun échantillonnage n'est effectué. - `nbest_size > 1` : échantillonne à partir des résultats nbest_size. - `nbest_size < 0` : suppose que nbest_size est infini et échantillonne à partir de toutes les hypothèses (lattice) en utilisant l'algorithme forward-filtering-and-backward-sampling. - `alpha` : Paramètre de lissage pour l'échantillonnage unigramme, et probabilité de dropout des opérations de fusion pour BPE-dropout. sp_model (`SentencePieceProcessor`) : le processeur *SentencePiece* utilisé pour chaque conversion (chaîne, jetons et identifiants). Adapté de [XLMRobertaTokenizer](/docs/transformers/main/fr/model_doc/xlm-roberta#transformers.XLMRobertaTokenizer) et [LukeTokenizer](/docs/transformers/main/fr/model_doc/luke#transformers.LukeTokenizer). Basé sur [SentencePiece](https://github.com/google/sentencepiece). Ce tokenizer hérite de [PreTrainedTokenizer](/docs/transformers/main/fr/main_classes/tokenizer#transformers.PythonBackend), qui contient la plupart des méthodes principales. Les utilisateurs doivent se reporter à cette superclasse pour plus d’informations sur ces méthodes. #### __appel__[[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) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L469) **Retourne :** [BatchEncoding](/docs/transformers/main/fr/main_classes/tokenizer#transformers.BatchEncoding) Un [BatchEncoding](/docs/transformers/main/fr/main_classes/tokenizer#transformers.BatchEncoding) avec les champs suivants : - **input_ids** -- Liste des identifiants de jetons à fournir au modèle. [Qu'est-ce que les identifiants d'entrée ?](../glossary#input-ids) - **token_type_ids** -- Liste des identifiants de type de jeton à fournir au modèle (lorsque `return_token_type_ids=True` ou si *"token_type_ids"* est présent dans `self.model_input_names`). [Qu'est-ce que les identifiants de type de jeton ?](../glossary#token-type-ids) - **attention_mask** -- Liste d'indices spécifiant les jetons auxquels le modèle doit prêter attention (lorsque `return_attention_mask=True` ou si *"attention_mask"* est présent dans `self.model_input_names`). [Qu'est-ce que les masques d'attention ?](../glossary#attention-mask) - **entity_ids** -- Liste des identifiants d'entités à fournir à un modèle. [Qu'est-ce que les identifiants d'entrée ?](../glossary#input-ids) - **entity_position_ids** -- Liste des positions des entités dans la séquence d'entrée à fournir au modèle. - **entity_token_type_ids** -- Liste des identifiants de type d'entité des jetons à fournir au modèle (lorsque `return_token_type_ids=True` ou si *"entity_token_type_ids"* est présent dans `self.model_input_names`). [Qu'est-ce que les identifiants de type de jeton ?](../glossary#token-type-ids) - **entity_attention_mask** -- Liste d'indices spécifiant les entités auxquelles le modèle doit prêter attention (lorsque `return_attention_mask=True` ou si *"entity_attention_mask"* est présent dans `self.model_input_names`). [Qu'est-ce que les masques d'attention ?](../glossary#attention-mask) - **entity_start_positions** -- Liste des positions de début des entités dans la séquence de jetons de mots (lorsque `task="entity_span_classification"`). - **entity_end_positions** -- Liste des positions de fin des entités dans la séquence de jetons de mots (lorsque `task="entity_span_classification"`). - **overflowing_tokens** -- Liste des séquences de jetons en dépassement (lorsqu'une `max_length` est spécifiée et `return_overflowing_tokens=True`). - **num_truncated_tokens** -- Nombre de jetons tronqués (lorsqu'une `max_length` est spécifiée et `return_overflowing_tokens=True`). - **special_tokens_mask** -- Liste de 0 et de 1, où 1 indique les jetons spéciaux ajoutés et 0 indique les jetons de séquence réguliers (lorsque `add_special_tokens=True` et `return_special_tokens_mask=True`). - **length** -- La longueur des entrées (lorsque `return_length=True`) add_special_tokens (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut ajouter des jetons spéciaux lors de l'encodage des séquences. Cette opération utilise la fonction sous-jacente `PretrainedTokenizerBase.build_inputs_with_special_tokens`, qui définit les jetons ajoutés automatiquement aux identifiants d'entrée. Cela est utile si vous souhaitez ajouter automatiquement des jetons `bos` ou `eos`. padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/fr/internal/file_utils#transformers.utils.PaddingStrategy), *facultatif*, valeur par défaut `False`) : Active et contrôle le bourrage. Accepte les valeurs suivantes : - `True` ou `'longest'` : effectuer le bourrage jusqu'à la séquence la plus longue du lot (ou aucun bourrage si une seule séquence est fournie). - `'max_length'` : Remplir jusqu'à une longueur maximale spécifiée par l'argument `max_length` ou jusqu'à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. - `False` ou `'do_not_pad'` (par défaut) : aucun padding (c’est-à-dire qu’un lot peut contenir des séquences de longueurs différentes). truncation (`bool`, `str` ou [TruncationStrategy](/docs/transformers/main/fr/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *facultatif*, par défaut `False`) : Active et contrôle la troncature. Accepte les valeurs suivantes : - `True` ou `'longest_first'` : tronque à une longueur maximale spécifiée par l'argument `max_length` ou à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. La troncature s'effectue jeton par jeton, en retirant un jeton de la séquence la plus longue de la paire si une paire de séquences (ou un lot de paires) est fournie. - `'only_first'` : Tronque à une longueur maximale spécifiée avec l'argument `max_length` ou à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. Cela ne tronquera que la première séquence d'une paire si une paire de séquences (ou un lot de paires) est fournie. - `'only_second'` : Tronque à une longueur maximale spécifiée avec l'argument `max_length` ou à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. Cela ne tronquera que la deuxième séquence d'une paire si une paire de séquences (ou un lot de paires) est fournie. - `False` ou `'do_not_truncate'` (par défaut) : aucune troncature (c’est-à-dire que le lot peut contenir des séquences dont la longueur dépasse la taille d’entrée maximale admissible par le modèle). max_length (`int`, *facultatif*) : Contrôle la longueur maximale à utiliser par l'un des paramètres de troncature/remplissage. Si cette valeur n'est pas définie ou est définie sur `None`, la longueur maximale prédéfinie du modèle sera utilisée si l'un des paramètres de troncature/remplissage exige une longueur maximale. Si le modèle n'a pas de longueur d'entrée maximale spécifique (comme XLNet), la troncature/le remplissage à une longueur maximale sera désactivé. stride (`int`, *facultatif*, valeur par défaut 0) : Si une valeur numérique est définie avec `max_length`, les jetons en dépassement renvoyés lorsque `return_overflowing_tokens=True` contiendront certains jetons de la fin de la séquence tronquée renvoyée, afin de fournir un chevauchement entre les séquences tronquées et les séquences en dépassement. La valeur de cet argument définit le nombre de jetons en chevauchement. is_split_into_words (`bool`, *facultatif*, valeur par défaut `False`) : Indique si l'entrée est déjà pré-tokenisée (par exemple, découpée en mots). Si défini sur `True`, le tokeniseur suppose que l'entrée est déjà découpée en mots (par exemple, en la séparant sur les espaces) et la tokenisera. Cela est utile pour la NER ou la classification de jetons. pad_to_multiple_of (`int`, *facultatif*) : Si défini, remplit la séquence jusqu'à un multiple de la valeur fournie. Nécessite l'activation de `padding`. Cela est particulièrement utile pour permettre l'utilisation des Tensor Cores sur le matériel NVIDIA avec une capacité de calcul `>= 7.5` (Volta). padding_side (`str`, *facultatif*) : Le côté sur lequel le modèle doit appliquer le remplissage. Doit être choisi parmi ['right', 'left']. La valeur par défaut est choisie à partir de l'attribut de classe du même nom. return_tensors (`str` ou [TensorType](/docs/transformers/main/fr/internal/file_utils#transformers.TensorType), *facultatif*) : Si défini, renvoie des tenseurs au lieu d'une liste d'entiers Python. Les valeurs acceptables sont : - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets Numpy `np.ndarray`. return_token_type_ids (`bool`, *facultatif*) : Indique s'il faut renvoyer les identifiants de type de jeton. Si la valeur par défaut est conservée, les identifiants de type de jeton sont renvoyés selon la valeur par défaut du tokeniseur spécifique, définie par l'attribut `return_outputs`. [Qu'est-ce que les identifiants de type de jeton ?](../glossary#token-type-ids) return_attention_mask (`bool`, *facultatif*) : Indique s'il faut retourner le masque d'attention. Si la valeur par défaut est conservée, le masque d'attention est retourné selon la valeur par défaut du tokeniseur spécifique, définie par l'attribut `return_outputs`. [Qu'est-ce que les masques d'attention ?](../glossary#attention-mask) return_overflowing_tokens (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut ou non renvoyer les séquences de jetons en dépassement. Si une paire de séquences d'identifiants d'entrée (ou un lot de paires) est fournie avec `truncation_strategy = longest_first` ou `True`, une erreur est levée au lieu de renvoyer les jetons en dépassement. return_special_tokens_mask (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut ou non renvoyer les informations du masque des jetons spéciaux. return_offsets_mapping (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut ou non renvoyer `(char_start, char_end)` pour chaque jeton. Cette fonctionnalité n'est disponible que sur les tokenizers rapides héritant de [PreTrainedTokenizerFast](/docs/transformers/main/fr/main_classes/tokenizer#transformers.TokenizersBackend) ; si vous utilisez le tokenizer Python, cette méthode lève `NotImplementedError`. return_length (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut ou non retourner les longueurs des entrées encodées. verbose (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut ou non afficher plus d'informations et d'avertissements. **kwargs : transmis à la méthode `self.tokenize()` #### save_vocabulary[[transformers.MLukeTokenizer.save_vocabulary]] ```python save_vocabulary(save_directory: str, filename_prefix: str | None = None) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L1703) Enregistrez uniquement le fichier de vocabulaire des entités. Le fichier tokenizer.json est enregistré par le parent TokenizersBackend.