# NLLB-MOE

## Aperçu

Le modèle NLLB a été présenté dans [No Language Left Behind: Scaling Human-Centered Machine Translation](https://huggingface.co/papers/2207.04672) par Marta R. Costa-jussà, James Cross, Onur Çelebi, Maha Elbayad, Kenneth Heafield, Kevin Heffernan, Elahe Kalbassi, Janice Lam, Daniel Licht, Jean Maillard, Anna Sun, Skyler Wang, Guillaume Wenzek, Al Youngblood, Bapi Akula, Loic Barrault, Gabriel Mejia Gonzalez, Prangthip Hansanti, John Hoffman, Semarley Jarrett, Kaushik Ram Sadagopan, Dirk Rowe, Shannon Spruit, Chau Tran, Pierre Andrews, Necip Fazil Ayan, Shruti Bhosale, Sergey Edunov, Angela Fan, Cynthia Gao, Vedanuj Goswami, Francisco Guzmán, Philipp Koehn, Alexandre Mourachko, Christophe Ropers, Safiyyah Saleem, Holger Schwenk et Jeff Wang.

L’abstract de l’article est le suivant :

*Portée par l’objectif d’éliminer les barrières linguistiques à l’échelle mondiale, la traduction automatique s’est imposée comme un axe majeur de la recherche en intelligence artificielle. Toutefois, ces efforts se sont concentrés sur un petit sous-ensemble de langues, laissant de côté la grande majorité des langues à faibles ressources. Que faut-il pour franchir la barrière des 200 langues tout en garantissant des résultats sûrs et de haute qualité, et en gardant à l’esprit les considérations éthiques ? Dans No Language Left Behind, nous avons relevé ce défi en contextualisant d’abord le besoin de prise en charge de la traduction des langues à faibles ressources grâce à des interviews exploratoires avec des locuteurs natifs. Ensuite, nous avons créé des jeux de données et des modèles visant à réduire l’écart de performance entre les langues à faibles et à fortes ressources. Plus précisément, nous avons développé un modèle de calcul conditionnel basé sur Sparsely Gated Mixture of Experts, entraîné sur des données obtenues grâce à de nouvelles techniques de data mining efficaces, adaptées aux langues à faibles ressources. Nous proposons plusieurs améliorations architecturales et d’entraînement pour contrer le surapprentissage lors de l’entraînement sur des milliers de tâches. De manière cruciale, nous avons évalué la performance de plus de 40 000 directions de traduction différentes à l’aide d’un benchmark traduit par des humains, Flores-200, et combiné l’évaluation humaine avec un nouveau benchmark de toxicité couvrant toutes les langues de Flores-200 afin d’évaluer la sécurité des traductions. Notre modèle atteint une amélioration de 44 % de BLEU par rapport à l’état de l’art précédent, posant des bases importantes vers la réalisation d’un système de traduction universel.*

Ce modèle a été contribué par [Arthur Zucker](https://huggingface.co/ArthurZ). Le code d'origine peut être trouvé [ici](https://github.com/facebookresearch/fairseq).

## Conseils d'utilisation

- M2M100ForConditionalGeneration est le modèle de base à la fois pour NLLB et NLLB MoE
- Le NLLB-MoE est très similaire au modèle NLLB, mais sa couche de propagation avant est basée sur l’implémentation de SwitchTransformers.
- Le tokenizer est le même que pour les modèles NLLB.

## Différences d'implémentation par rapport à SwitchTransformers

La plus grande différence réside dans la manière dont les jetons sont acheminés. NLLB-MoE utilise une `top-2-gate`, ce qui signifie que pour chaque entrée, seuls les deux experts ayant les probabilités prédites les plus élevées par le réseau de routage sont sélectionnés, et les experts restants sont ignorés. Dans `SwitchTransformers`, seules les probabilités top-1 sont calculées, ce qui signifie que les jetons ont moins de probabilité d'être transmis. De plus, si un jeton n'est acheminé vers aucun expert, `SwitchTransformers` ajoute tout de même ses états cachés non modifiés (un peu comme une connexion résiduelle), tandis qu'ils sont masqués dans le mécanisme de routage top-2 de `NLLB`.

## Génération avec NLLB-MoE

Les points de contrôle disponibles nécessitent environ 350 Go d'espace de stockage. Assurez-vous d'utiliser `accelerate` si votre machine ne dispose pas de suffisamment de RAM.

Lors de la génération du texte cible, définissez `forced_bos_token_id` sur l’identifiant de la langue cible. L’exemple suivant montre comment traduire de l’anglais au français à l’aide du modèle *facebook/nllb-200-distilled-600M*.

Notez que nous utilisons le code BCP-47 pour le français `fra_Latn`. Consultez [ici](https://github.com/facebookresearch/flores/blob/main/flores200/README.md#languages-in-flores-200) pour la liste de tous les BCP-47 du jeu de données Flores 200.

```python
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("facebook/nllb-moe-54b")
model = AutoModelForSeq2SeqLM.from_pretrained("facebook/nllb-moe-54b", device_map="auto")

article = "Previously, Ring's CEO, Jamie Siminoff, remarked the company started when his doorbell wasn't audible from his shop in his garage."
inputs = tokenizer(article, return_tensors="pt").to(model.device)

translated_tokens = model.generate(
    **inputs, forced_bos_token_id=tokenizer.lang_code_to_id["fra_Latn"], max_length=50
)
tokenizer.batch_decode(translated_tokens, skip_special_tokens=True)[0]
"Auparavant, le PDG de Ring, Jamie Siminoff, a fait remarquer que la société avait commencé lorsque sa sonnette n'était pas audible depuis son magasin dans son garage."
```

### Générer à partir d'une autre langue que l'anglais

English (`eng_Latn`) est défini comme langue source par défaut de la traduction. Pour indiquer que vous souhaitez traduire depuis une autre langue, vous devez spécifier le code BCP-47 dans l'argument de mot-clé `src_lang` de l'initialisation du tokenizer.

Voir l'exemple ci-dessous pour une traduction du roumain vers l'allemand :

```python
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("facebook/nllb-moe-54b", src_lang="ron_Latn")
model = AutoModelForSeq2SeqLM.from_pretrained("facebook/nllb-moe-54b", device_map="auto")

article = "Şeful ONU spune că nu există o soluţie militară în Siria"
inputs = tokenizer(article, return_tensors="pt").to(model.device)

translated_tokens = model.generate(
    **inputs, forced_bos_token_id=tokenizer.lang_code_to_id["deu_Latn"], max_length=30
)
tokenizer.batch_decode(translated_tokens, skip_special_tokens=True)[0]
```

## Ressources

- [Guide de la tâche de traduction](../tasks/translation)
- [Guide de la tâche de résumés](../tasks/summarization)

## NllbMoeConfig[[transformers.NllbMoeConfig]]

#### transformers.NllbMoeConfig[[transformers.NllbMoeConfig]]

```python
transformers.NllbMoeConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, vocab_size: int = 128112, max_position_embeddings: int = 1024, encoder_layers: int = 12, encoder_ffn_dim: int = 4096, encoder_attention_heads: int = 16, decoder_layers: int = 12, decoder_ffn_dim: int = 4096, decoder_attention_heads: int = 16, encoder_layerdrop: float | int = 0.05, decoder_layerdrop: float | int = 0.05, use_cache: bool = True, activation_function: str = 'relu', d_model: int = 1024, dropout: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.0, init_std: float = 0.02, decoder_start_token_id: int | None = 2, scale_embedding: bool = True, router_bias: bool = False, router_dtype: typing.Literal['float32', 'float16', 'bfloat16'] = 'float32', router_ignore_padding_tokens: bool = False, num_experts: int = 128, expert_capacity: int = 64, encoder_sparse_step: int = 4, decoder_sparse_step: int = 4, router_z_loss_coef: float = 0.001, router_aux_loss_coef: float = 0.001, second_expert_policy: str = 'all', normalize_router_prob_before_dropping: bool = False, batch_prioritized_routing: bool = False, moe_eval_capacity_token_fraction: float = 1.0, moe_token_dropout: float | int = 0.2, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, tie_word_embeddings: bool = True, output_router_logits: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/configuration_nllb_moe.py#L26)

**Paramètres :**

is_encoder_decoder (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le modèle est utilisé comme encodeur/décodeur ou non.

vocab_size (`int`, *facultatif*, valeur par défaut `128112`) : Taille du vocabulaire du modèle. Définit le nombre de jetons différents qui peuvent être représentés par `input_ids`.

max_position_embeddings (`int`, *facultatif*, valeur par défaut `1024`) : La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé.

encoder_layers (`int`, *facultatif*, valeur par défaut `12`) : Nombre de couches cachées dans l'encodeur Transformer. Utilise la même valeur que `num_layers` si non défini.

encoder_ffn_dim (`int`, *facultatif*, valeur par défaut `4096`) : Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) dans l'encodeur.

encoder_attention_heads (`int`, *facultatif*, valeur par défaut `16`) : Nombre de têtes d'attention pour chaque couche d'attention dans l'encodeur Transformer.

decoder_layers (`int`, *facultatif*, valeur par défaut `12`) : Nombre de couches cachées dans le décodeur Transformer. Utilise la même valeur que `num_layers` si non défini.

decoder_ffn_dim (`int`, *facultatif*, valeur par défaut `4096`) : Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) du décodeur.

decoder_attention_heads (`int`, *facultatif*, valeur par défaut `16`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.

encoder_layerdrop (`Union[float, int]`, *facultatif*, valeur par défaut `0.05`) : Probabilité de LayerDrop pour l'encodeur. Consultez l'article [LayerDrop](see https://huggingface.co/papers/1909.11556) pour plus de détails.

decoder_layerdrop (`Union[float, int]`, *facultatif*, valeur par défaut `0.05`) : La probabilité de LayerDrop pour le décodeur. Consultez l'article [LayerDrop](see https://huggingface.co/papers/1909.11556) pour plus de détails.

use_cache (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le modèle doit retourner les dernières attentions clés/valeurs (non utilisé par tous les modèles). Pertinent uniquement si `config.is_decoder=True` ou si le modèle est un modèle génératif de type décodeur uniquement.

activation_function (`str`, *facultatif*, par défaut `relu`) : Fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

d_model (`int`, *facultatif*, valeur par défaut `1024`) : Taille des couches d'encodeur et de la couche pooler.

dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.1`) : Le ratio pour toutes les couches de dropout.

attention_dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.1`) : Le taux de dropout appliqué aux probabilités d'attention.

activation_dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Le taux de dropout pour les activations à l'intérieur de la couche entièrement connectée.

init_std (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

decoder_start_token_id (`int`, *facultatif*, valeur par défaut `2`) : si un modèle encodeur-décodeur commence le décodage avec un jeton différent de `bos`, l'identifiant de ce jeton.

scale_embedding (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut mettre à l'échelle les embeddings en les divisant par sqrt(d_model).

router_bias (`bool`, *facultatif*, par défaut `False`) : Indique si le classifieur du routeur doit avoir un biais.

router_dtype (`str`, *facultatif*, par défaut `"float32"`) : le `dtype` utilisé pour les routeurs. Il est préférable de conserver le `dtype` en `"float32"`, comme indiqué dans la discussion sur la *précision sélective* dans [l'article](https://huggingface.co/papers/2101.03961).

router_ignore_padding_tokens (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut ignorer les jetons de bourrage lors du routage. Si `False`, les jetons de bourrage ne sont routés vers aucun expert.

num_experts (`int`, *facultatif*, valeur par défaut `128`) : Nombre d'experts routés dans les couches MoE.

expert_capacity (`int`, *facultatif*, valeur par défaut : 64) : Nombre de jetons pouvant être stockés dans chaque expert.

encoder_sparse_step (`int`, *facultatif*, valeur par défaut : 4) : Fréquence des couches creuses dans l'encodeur. 4 signifie qu'une couche sur quatre sera creuse.

decoder_sparse_step (`int`, *facultatif*, valeur par défaut : 4) : Fréquence des couches creuses dans le décodeur. 4 signifie qu'une couche sur quatre sera creuse.

router_z_loss_coef (`float`, *facultatif*, valeur par défaut `0.001`) : Coefficient de la perte z du routeur, qui pénalise les logits de routeur élevés afin d'améliorer la stabilité de l'entraînement.

router_aux_loss_coef (`float`, *facultatif*, valeur par défaut `0.001`) : Coefficient de la perte auxiliaire d'équilibrage de charge. Utilisé pour pénaliser un routage inégal des experts dans les modèles MoE.

second_expert_policy (`str`, *facultatif*, par défaut `"all"`) : La politique utilisée pour l'échantillonnage de la probabilité d'être échantillonné vers un second expert pour chaque jeton.

normalize_router_prob_before_dropping (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut normaliser les probabilités du routeur avant d'appliquer un masque basé sur la capacité des experts (capacity dropping).

batch_prioritized_routing (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut ou non trier les jetons selon leurs probabilités de routage avant l'abandon de capacité. Cela signifie que les jetons ayant les probabilités les plus élevées seront routés avant d'autres jetons qui pourraient se trouver plus loin dans la séquence.

moe_eval_capacity_token_fraction (`float`, *facultatif*, valeur par défaut 1.0) : Fraction de jetons utilisée comme capacité pendant la validation. Si la valeur est négative, la même que celle utilisée lors de l’entraînement est appliquée. La valeur doit être comprise dans l’intervalle : (0.0, 1.0].

moe_token_dropout (`float`, *facultatif*, valeur par défaut 0,2) : Taux de masquage pour le masquage des sorties des experts MoE (EOM), implémenté via un Dropout2d sur les sorties des experts.

pad_token_id (`int`, *facultatif*, valeur par défaut `1`) : Identifiant du jeton utilisé pour le bourrage dans le vocabulaire.

bos_token_id (`int`, *facultatif*, valeur par défaut `0`) : Identifiant du jeton utilisé pour le début de flux dans le vocabulaire.

eos_token_id (`Union[int, list[int]]`, *facultatif*, valeur par défaut `2`) : Identifiant de jeton utilisé pour la fin de flux dans le vocabulaire.

tie_word_embeddings (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut lier les embeddings de poids selon la correspondance `tied_weights_keys` du modèle.

output_router_logits (`bool`, *facultatif*, valeur par défaut `False`) : Indique si les logits du routeur doivent être renvoyés par le modèle. L'activation de cette option permet également au modèle de produire la perte auxiliaire, incluant la perte d'équilibrage de charge et la perte z du routeur.

Ceci est la classe de configuration destinée à stocker la configuration d'un modèle Nllb Moe. Elle est utilisée pour instancier un modèle Nllb Moe en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [facebook/nllb-moe-54b](https://huggingface.co/facebook/nllb-moe-54b)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

```python
>>> from transformers import NllbMoeModel, NllbMoeConfig

>>> # Initializing a NllbMoe facebook/nllb-moe-54b style configuration
>>> configuration = NllbMoeConfig()

>>> # Initializing a model from the facebook/nllb-moe-54b style configuration
>>> model = NllbMoeModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## NllbMoeTop2Router[[transformers.NllbMoeTop2Router]]

#### transformers.NllbMoeTop2Router[[transformers.NllbMoeTop2Router]]

```python
transformers.NllbMoeTop2Router(config: NllbMoeConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L168)

Le routeur utilisant des jetons choisit l’attribution des deux meilleurs experts.

Ce routeur utilise le même mécanisme que celui de NLLB-MoE dans le dépôt fairseq. Les éléments sont triés selon router_probs puis acheminés vers leur expert de choix jusqu’à ce que la valeur de expert_capacity de l’expert soit atteinte. **Il n’est pas garanti que chaque jeton soit traité par un expert**, ni que chaque expert reçoive au moins un jeton.

Les poids de combinaison du routeur sont également renvoyés afin de s'assurer que les états non mis à jour seront masqués.

#### route_tokens[[transformers.NllbMoeTop2Router.route_tokens]]

```python
route_tokens(router_logits: Tensor, input_dtype: dtype = torch.float32, padding_mask: typing.Optional[torch.LongTensor] = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L209)

Calcule le `dispatch_mask` et les `dispatch_weights` pour chaque expert. Les masques sont adaptés à la capacité de l'expert.

#### forward[[transformers.NllbMoeTop2Router.forward]]

```python
forward(hidden_states: Tensor, padding_mask: typing.Optional[torch.LongTensor] = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L294)

**Paramètres :**

hidden_states (`torch.Tensor`) : (batch_size, sequence_length, hidden_dim) à partir duquel les probabilités du routeur sont calculées.

**Retourne :** top_1_mask (`torch.Tensor` de forme (batch_size, sequence_length))

Tenseur d’index de forme [batch_size, sequence_length] correspondant à l’expert sélectionné pour chaque jeton à l’aide des probabilités top1 du routeur. router_probabilities (`torch.Tensor` de forme (batch_size, sequence_length, nump_experts)) : Tenseur de forme (batch_size, sequence_length, num_experts) correspondant aux probabilités pour chaque jeton et chaque expert. Utilisé pour acheminer les jetons vers les experts. router_logits (`torch.Tensor` de forme (batch_size, sequence_length)) : Tenseur de logits de forme (batch_size, sequence_length, num_experts) correspondant aux logits bruts du routeur. Utilisé ultérieurement pour le calcul de la perte z du routeur.

Les états cachés sont redimensionnés afin de simplifier le calcul des probabilités du routeur (en combinant les poids de chaque expert).

## NllbMoeSparseMLP[[transformers.NllbMoeSparseMLP]]

#### transformers.NllbMoeSparseMLP[[transformers.NllbMoeSparseMLP]]

```python
transformers.NllbMoeSparseMLP(config: NllbMoeConfig, ffn_dim: int)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L370)

Implémentation du module MLP creux de NLLB-MoE.

#### forward[[transformers.NllbMoeSparseMLP.forward]]

```python
forward(hidden_states: Tensor, padding_mask: typing.Optional[torch.Tensor] = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L381)

## NllbMoeModel[[transformers.NllbMoeModel]]

#### transformers.NllbMoeModel[[transformers.NllbMoeModel]]

```python
transformers.NllbMoeModel(config: NllbMoeConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L865)

**Paramètres :**

config ([NllbMoeConfig](/docs/transformers/v5.23.0/fr/model_doc/nllb-moe#transformers.NllbMoeConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle Nllb Moe brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

#### forward[[transformers.NllbMoeModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L892)

**Paramètres :**

input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée du décodeur dans le vocabulaire. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Quelles sont les identifiants d'entrée du décodeur ?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention à certains indices de jetons. Par défaut, un masque causal est utilisé afin de s'assurer que le modèle ne peut consulter que les entrées précédentes pour prédire le futur.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *facultatif*) : le tuple est composé de (`last_hidden_state`, *facultatif* : `hidden_states`, *facultatif* : `attentions`) `last_hidden_state` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) est une séquence d'états cachés à la sortie de la dernière couche de l'encodeur. Utilisé dans l'attention croisée du décodeur.

past_key_values (`~cache_utils.Cache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement des `past_key_values` renvoyés par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`.  Seule une instance de [Cache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, voir notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `past_key_values` n'est transmis, [DynamicCache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.DynamicCache) est initialisé par défaut.  Le modèle renverra le même format de cache que celui fourni en entrée.  Si `past_key_values` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux pour lesquels les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

decoder_inputs_embeds (`torch.Tensor` de forme `(batch_size, target_sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `decoder_input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Si `past_key_values` est utilisé, il est facultatif de n'entrer que les derniers `decoder_inputs_embeds` (voir `past_key_values`). Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `decoder_input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle. Si `decoder_input_ids` et `decoder_inputs_embeds` sont tous deux non définis, `decoder_inputs_embeds` prend la valeur de `inputs_embeds`.

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`).

**Retourne :** `Seq2SeqMoEModelOutput` ou `tuple(torch.Tensor)`

Un `Seq2SeqMoEModelOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments en fonction de la configuration (`None`) et des entrées.

La méthode forward du modèle [NllbMoeModel](/docs/transformers/v5.23.0/fr/model_doc/nllb-moe#transformers.NllbMoeModel) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`) -- Séquence d'états cachés à la sortie de la dernière couche du décodeur du modèle.

  Si `past_key_values` est utilisé, seule la dernière hidden-state des séquences de forme `(batch_size, 1, hidden_size)` est renvoyée.
- **past_key_values** (`EncoderDecoderCache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [EncoderDecoderCache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.EncoderDecoderCache). Pour plus de détails, consultez notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée `past_key_values`) pour accélérer le décodage séquentiel.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du décodeur à la sortie de chaque couche, plus les sorties d'incorporation initiale facultatives.
- **decoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **decoder_router_logits** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_router_logits=True` est passé ou lorsque `config.add_router_probs=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, sequence_length, num_experts)`.

  Logits du routeur du modèle décodeur, utiles pour calculer la perte auxiliaire des modèles Mixture of Experts.
- **cross_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée.
- **encoder_last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche de l'encodeur du modèle.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés de l'encodeur à la sortie de chaque couche, plus les sorties d'incorporation initiales facultatives.
- **encoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **encoder_router_logits** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_router_logits=True` est passé ou lorsque `config.add_router_probs=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, sequence_length, num_experts)`.

  Logits du routeur du modèle encodeur, utiles pour calculer la perte auxiliaire et la z_loss des modules creux.

## NllbMoeForConditionalGeneration[[transformers.NllbMoeForConditionalGeneration]]

#### transformers.NllbMoeForConditionalGeneration[[transformers.NllbMoeForConditionalGeneration]]

```python
transformers.NllbMoeForConditionalGeneration(config: NllbMoeConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L1044)

**Paramètres :**

config ([NllbMoeConfig](/docs/transformers/v5.23.0/fr/model_doc/nllb-moe#transformers.NllbMoeConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle NllbMoe avec une tête de modélisation de langage. Peut être utilisé pour la résumés.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

#### forward[[transformers.NllbMoeForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, output_router_logits: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L1060)

**Paramètres :**

input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée du décodeur dans le vocabulaire. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Quelles sont les identifiants d'entrée du décodeur ?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention à certains indices de jetons. Par défaut, un masque causal est utilisé afin de s'assurer que le modèle ne peut consulter que les entrées précédentes pour prédire le futur.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *facultatif*) : le tuple est composé de (`last_hidden_state`, *facultatif* : `hidden_states`, *facultatif* : `attentions`) `last_hidden_state` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) est une séquence d'états cachés à la sortie de la dernière couche de l'encodeur. Utilisé dans l'attention croisée du décodeur.

past_key_values (`~cache_utils.Cache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement des `past_key_values` renvoyés par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`.  Seule une instance de [Cache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, voir notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `past_key_values` n'est transmis, [DynamicCache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.DynamicCache) est initialisé par défaut.  Le modèle renverra le même format de cache que celui fourni en entrée.  Si `past_key_values` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux pour lesquels les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

decoder_inputs_embeds (`torch.Tensor` de forme `(batch_size, target_sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `decoder_input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Si `past_key_values` est utilisé, il est facultatif de n'entrer que les derniers `decoder_inputs_embeds` (voir `past_key_values`). Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `decoder_input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle. Si `decoder_input_ids` et `decoder_inputs_embeds` sont tous deux non définis, `decoder_inputs_embeds` prend la valeur de `inputs_embeds`.

labels (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Étiquettes pour le calcul de la perte de modélisation de langage masquée. Les indices doivent être compris dans `[0, ..., config.vocab_size]` ou égaux à -100 (voir la docstring de `input_ids`). Les jetons dont l'indice est défini sur `-100` sont ignorés (masqués) ; la perte n'est calculée que pour les jetons dont l'étiquette est comprise dans `[0, ..., config.vocab_size]`.

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`).

output_router_logits (`bool`, *facultatif*) : Indique s'il faut retourner les logits de tous les routeurs. Ils sont utiles pour calculer la perte du routeur et ne doivent pas être retournés lors de l'inférence.

**Retourne :** `Seq2SeqMoEOutput` ou `tuple(torch.Tensor)`

Un `Seq2SeqMoEOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([NllbMoeConfig](/docs/transformers/v5.23.0/fr/model_doc/nllb-moe#transformers.NllbMoeConfig)) et les entrées.

La méthode forward de [NllbMoeForConditionalGeneration](/docs/transformers/v5.23.0/fr/model_doc/nllb-moe#transformers.NllbMoeForConditionalGeneration) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni) -- Perte de modélisation du langage.
- **logits** (`torch.Tensor` de forme `(batch_size, sequence_length, config.vocab_size)`) -- Scores de prédiction de la tête de modélisation du langage (scores pour chaque jeton du vocabulaire avant SoftMax).
- **past_key_values** (`EncoderDecoderCache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [EncoderDecoderCache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.EncoderDecoderCache). Pour plus de détails, consultez notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée `past_key_values`) pour accélérer le décodage séquentiel.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du décodeur à la sortie de chaque couche, plus les sorties de l'intégration initiale.
- **decoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **decoder_router_logits** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_router_logits=True` est passé ou lorsque `config.add_router_probs=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, sequence_length, num_experts)`.

  Logits du routeur du modèle décodeur, utiles pour calculer la perte auxiliaire des modèles Mixture of Experts.
- **cross_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée.
- **encoder_last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche de l'encodeur du modèle.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés de l'encodeur à la sortie de chaque couche, plus les sorties des embeddings initiaux.
- **encoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **encoder_router_logits** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_router_logits=True` est passé ou lorsque `config.add_router_probs=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, sequence_length, num_experts)`.

  Logits du routeur du modèle encodeur, utiles pour calculer la perte auxiliaire et z_loss pour les modèles Mixture of Experts.

Exemple :

```python
```

