# NLLB-MOE

## Visão geral

O modelo NLLB foi apresentado em [No Language Left Behind: Scaling Human-Centered Machine Translation](https://huggingface.co/papers/2207.04672) por 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 e Jeff Wang.

O resumo do artigo é o seguinte:

*Impulsionada pelo objetivo de erradicar as barreiras linguísticas em escala global, a tradução automática se consolidou como um foco central da pesquisa em inteligência artificial hoje em dia. No entanto, esses esforços se concentraram em um pequeno subconjunto de idiomas, deixando para trás a grande maioria dos idiomas de baixo recurso. O que é necessário para quebrar a barreira dos 200 idiomas garantindo resultados seguros e de alta qualidade, tudo isso mantendo em mente as considerações éticas? Em No Language Left Behind, assumimos esse desafio ao primeiro contextualizar a necessidade de suporte à tradução de idiomas de baixo recurso por meio de entrevistas exploratórias com falantes nativos. Em seguida, criamos conjuntos de dados e modelos voltados para reduzir a lacuna de desempenho entre idiomas de baixo e alto recurso. Mais especificamente, desenvolvemos um modelo de computação condicional baseado em Sparsely Gated Mixture of Experts que é treinado com dados obtidos por meio de técnicas inovadoras e eficazes de mineração de dados adaptadas para idiomas de baixo recurso. Propomos melhorias arquitetônicas e de treinamento para contrabalançar o overfitting durante o treinamento em milhares de tarefas. Criticamente, avaliamos o desempenho de mais de 40.000 direções de tradução diferentes usando um benchmark traduzido por humanos, o Flores-200, e combinamos a avaliação humana com um novo benchmark de toxicidade que cobre todos os idiomas do Flores-200 para avaliar a segurança da tradução. Nosso modelo alcança uma melhoria de 44% em BLEU em relação ao estado da arte anterior, estabelecendo uma base importante para a realização de um sistema de tradução universal.*

Este modelo foi contribuído por [Arthur Zucker](https://huggingface.co/ArthurZ). O código original pode ser encontrado [aqui](https://github.com/facebookresearch/fairseq).

## Dicas de uso

- M2M100ForConditionalGeneration é o modelo base tanto para o NLLB quanto para o NLLB MoE
- O NLLB-MoE é muito semelhante ao modelo NLLB, mas sua camada feed forward é baseada na implementação do SwitchTransformers.
- O tokenizer é o mesmo dos modelos NLLB.

## Diferenças de implementação em relação ao SwitchTransformers

A maior diferença está na forma como os tokens são roteados. O NLLB-MoE usa um `top-2-gate`, o que significa que, para cada entrada, apenas os dois especialistas com as maiores probabilidades previstas pela rede de roteamento são selecionados, e os demais especialistas são ignorados. No `SwitchTransformers`, apenas as probabilidades top-1 são calculadas, o que significa que os tokens têm menor probabilidade de serem encaminhados. Além disso, se um token não for roteado para nenhum especialista, o `SwitchTransformers` ainda adiciona seus estados ocultos não modificados (algo como uma conexão residual), enquanto eles são mascarados no mecanismo de roteamento top-2 do `NLLB`.

## Gerando com NLLB-MoE

Os checkpoints disponíveis exigem cerca de 350GB de armazenamento. Certifique-se de usar `accelerate` caso não tenha RAM suficiente na sua máquina.

Ao gerar o texto de destino, defina o `forced_bos_token_id` para o id do idioma de destino. O exemplo a seguir mostra como traduzir do inglês para o francês usando o modelo *facebook/nllb-200-distilled-600M*.

Observe que estamos usando o código BCP-47 para o francês `fra_Latn`. Veja [aqui](https://github.com/facebookresearch/flores/blob/main/flores200/README.md#languages-in-flores-200) a lista de todos os BCP-47 no conjunto de dados 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."
```

### Gerar a partir de qualquer outro idioma que não seja o inglês

English (`eng_Latn`) é definido como o idioma padrão de origem para a tradução. Para especificar que você deseja traduzir de um idioma diferente, você deve especificar o código BCP-47 no argumento de palavra-chave `src_lang` da inicialização do tokenizer.

Veja o exemplo abaixo para uma tradução do romeno para o alemão:

```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]
```

## Recursos

- [Guia de tarefa de tradução](../tasks/translation)
- [Guia da tarefa de sumarização](../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)
```

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

**Parâmetros:**

is_encoder_decoder (`bool`, *opcional*, padrão `True`) : Indica se o modelo é usado como codificador/decodificador ou não.

vocab_size (`int`, *opcional*, padrão `128112`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`.

max_position_embeddings (`int`, *opcional*, padrão `1024`) : O comprimento máximo de sequência com o qual este modelo pode ser usado.

encoder_layers (`int`, *opcional*, padrão `12`) : Número de camadas ocultas no codificador do Transformer. Usará o mesmo valor de `num_layers` se não for definido.

encoder_ffn_dim (`int`, *opcional*, padrão `4096`) : Dimensionalidade da camada "intermediária" (frequentemente chamada de feed-forward) no codificador.

encoder_attention_heads (`int`, *opcional*, padrão `16`) : Número de cabeças de atenção para cada camada de atenção no codificador do Transformer.

decoder_layers (`int`, *opcional*, padrão `12`) : Número de camadas ocultas no decodificador do Transformer. Usará o mesmo valor de `num_layers` se não for definido.

decoder_ffn_dim (`int`, *opcional*, padrão `4096`) : Dimensionalidade da camada "intermediária" (frequentemente chamada de feed-forward) no decodificador.

decoder_attention_heads (`int`, *opcional*, padrão `16`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

encoder_layerdrop (`Union[float, int]`, *opcional*, padrão `0.05`) : A probabilidade de LayerDrop para o codificador. Consulte o [artigo do LayerDrop](see https://huggingface.co/papers/1909.11556) para mais detalhes.

decoder_layerdrop (`Union[float, int]`, *opcional*, padrão `0.05`) : A probabilidade de LayerDrop para o decodificador. Consulte o [artigo do LayerDrop](see https://huggingface.co/papers/1909.11556) para mais detalhes.

use_cache (`bool`, *opcional*, padrão `True`) : Indica se o modelo deve retornar as últimas atenções de chave/valor (não utilizado por todos os modelos). Relevante apenas se `config.is_decoder=True` ou quando o modelo for um modelo generativo somente de decodificador.

activation_function (`str`, *opcional*, padrão `relu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

d_model (`int`, *opcional*, padrão `1024`) : Tamanho das camadas do codificador e da camada pooler.

dropout (`Union[float, int]`, *opcional*, padrão `0.1`) : A proporção para todas as camadas de dropout.

attention_dropout (`Union[float, int]`, *opcional*, padrão `0.1`) : A taxa de dropout para as probabilidades de atenção.

activation_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as ativações dentro da camada totalmente conectada.

init_std (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

decoder_start_token_id (`int`, *opcional*, padrão `2`) : Se um modelo encoder-decoder inicia a decodificação com um token diferente de `bos`, o id desse token.

scale_embedding (`bool`, *opcional*, padrão `True`) : Se as embeddings devem ser escalonadas dividindo por sqrt(d_model).

router_bias (`bool`, *opcional*, padrão `False`) : Se o classificador do roteador deve ter um viés.

router_dtype (`str`, *opcional*, padrão `"float32"`) : O `dtype` usado para os roteadores. É preferível manter o `dtype` como `"float32"`, conforme especificado na discussão sobre *precisão seletiva* em [o artigo](https://huggingface.co/papers/2101.03961).

router_ignore_padding_tokens (`bool`, *opcional*, padrão `False`) : Se deve ignorar tokens de preenchimento ao rotear. Se `False`, os tokens de preenchimento não são roteados para nenhum especialista.

num_experts (`int`, *opcional*, padrão `128`) : Número de especialistas roteados nas camadas MoE.

expert_capacity (`int`, *opcional*, padrão 64) : Número de tokens que podem ser armazenados em cada especialista.

encoder_sparse_step (`int`, *opcional*, padrão 4) : Frequência das camadas esparsas no codificador. 4 significa que uma a cada 4 camadas será esparsa.

decoder_sparse_step (`int`, *opcional*, padrão 4) : Frequência das camadas esparsas no decodificador. 4 significa que uma a cada 4 camadas será esparsa.

router_z_loss_coef (`float`, *opcional*, padrão `0.001`) : Coeficiente para a perda z do roteador, que penaliza logits grandes do roteador para melhorar a estabilidade do treinamento.

router_aux_loss_coef (`float`, *opcional*, padrão `0.001`) : Coeficiente da perda auxiliar de balanceamento de carga. Usado para penalizar o roteamento desigual de especialistas em modelos MoE.

second_expert_policy (`str`, *opcional*, padrão `"all"`) : A política usada para a amostragem da probabilidade de ser amostrado para um segundo especialista para cada token.

normalize_router_prob_before_dropping (`bool`, *opcional*, padrão `True`) : Se as probabilidades do roteador devem ser normalizadas antes de aplicar uma máscara com base na capacidade dos especialistas (descarte de capacidade).

batch_prioritized_routing (`bool`, *opcional*, padrão `True`) : Se os tokens devem ou não ser ordenados pelas probabilidades do roteador antes do descarte por capacidade. Isso significa que os tokens com as maiores probabilidades serão roteados antes de outros tokens que possam estar mais à frente na sequência.

moe_eval_capacity_token_fraction (`float`, *opcional*, padrão 1.0) : Fração de tokens como capacidade durante a validação; se definido como negativo, usa o mesmo valor do treinamento. Deve estar no intervalo: (0.0, 1.0].

moe_token_dropout (`float`, *opcional*, padrão 0.2) : Taxa de mascaramento para o mascaramento de saída de especialistas MoE (EOM), implementado por meio de um Dropout2d nas saídas dos especialistas.

pad_token_id (`int`, *opcional*, padrão `1`) : ID do token usado para preenchimento no vocabulário.

bos_token_id (`int`, *opcional*, padrão `0`) : ID do token usado para o início do fluxo no vocabulário.

eos_token_id (`Union[int, list[int]]`, *opcional*, padrão `2`) : ID do token usado para o fim do fluxo no vocabulário.

tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo.

output_router_logits (`bool`, *opcional*, padrão `False`) : Indica se os logits do roteador devem ser retornados pelo modelo. Ativar essa opção também permite que o modelo outpute a perda auxiliar, incluindo a perda de balanceamento de carga e a perda z do roteador.

Esta é a classe de configuração para armazenar a configuração de um Nllb MoeModel. Ela é usada para instanciar um modelo Nllb Moe de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [facebook/nllb-moe-54b](https://huggingface.co/facebook/nllb-moe-54b)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

```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)
```

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

O roteador que usa tokens escolhe a atribuição dos 2 melhores especialistas.

Este roteador usa o mesmo mecanismo do NLLB-MoE do repositório fairseq. Os itens são ordenados por router_probs e, em seguida, roteados para o especialista de sua escolha até que o expert_capacity do especialista seja atingido. **Não há garantia de que cada token seja processado por um especialista**, nem de que cada especialista receba pelo menos um token.

Os pesos de combinação do roteador também são retornados para garantir que os estados que não são atualizados sejam mascarados.

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

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

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

Calcula o `dispatch_mask` e os `dispatch_weights` para cada expert. As máscaras são adaptadas à capacidade do expert.

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

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

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

**Parâmetros:**

hidden_states (`torch.Tensor`) : (batch_size, sequence_length, hidden_dim) a partir do qual as probabilidades do roteador são calculadas.

**Retorna:** top_1_mask (`torch.Tensor` de forma (batch_size, sequence_length))

Tensor de índice de forma [batch_size, sequence_length] correspondente ao especialista selecionado para cada token usando as probabilidades top1 do roteador. router_probabilities (`torch.Tensor` de forma (batch_size, sequence_length, nump_experts)): Tensor de forma (batch_size, sequence_length, num_experts) correspondente às probabilidades para cada token e especialista. Usado para rotear tokens para especialistas. router_logits (`torch.Tensor` de forma (batch_size, sequence_length))): Tensor de logits de forma (batch_size, sequence_length, num_experts) correspondente aos logits brutos do roteador. Isso é usado posteriormente para calcular a perda z do roteador.

Os estados ocultos são remodelados para simplificar o cálculo das probabilidades do roteador (combinando os pesos de cada especialista).

## NllbMoeSparseMLP[[transformers.NllbMoeSparseMLP]]

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

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

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

Implementação do módulo de MLP esparsa do NLLB-MoE.

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

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

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

## NllbMoeModel[[transformers.NllbMoeModel]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L863)

**Parâmetros:**

config ([NllbMoeConfig](/docs/transformers/main/pt/model_doc/nllb-moe#transformers.NllbMoeConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Nllb Moe puro, que gera estados ocultos brutos sem nenhum cabeçalho específico no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### 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'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L890)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada do decodificador no vocabulário. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada do decodificador?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção em determinados índices de tokens. Por padrão, uma máscara causal será usada, para garantir que o modelo só possa olhar para entradas anteriores a fim de prever o futuro.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *opcional*) : A tupla consiste em (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de hidden-states na saída da última camada do encoder. Usado na cross-attention do decoder.

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

decoder_inputs_embeds (`torch.Tensor` de forma `(batch_size, target_sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `decoder_input_ids`, você pode escolher passar diretamente uma representação incorporada. Se `past_key_values` for usado, opcionalmente apenas o último `decoder_inputs_embeds` precisa ser inserido (veja `past_key_values`). Isso é útil se você quiser ter mais controle sobre como converter os índices de `decoder_input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo. Se `decoder_input_ids` e `decoder_inputs_embeds` estiverem ambos não definidos, `decoder_inputs_embeds` assume o valor de `inputs_embeds`.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

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

Um `Seq2SeqMoEModelOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração (`None`) e das entradas.

O método forward do [NllbMoeModel](/docs/transformers/main/pt/model_doc/nllb-moe#transformers.NllbMoeModel) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do decoder do modelo.

  Se `past_key_values` for usado, apenas o último hidden-state das sequências, com forma `(batch_size, 1, hidden_size)`, é retornado.
- **past_key_values** (`EncoderDecoderCache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- É uma instância de [EncoderDecoderCache](/docs/transformers/main/pt/internal/generation_utils#transformers.EncoderDecoderCache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do decodificador na saída de cada camada, além das saídas opcionais do embedding inicial.
- **decoder_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) com forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **decoder_router_logits** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_router_logits=True` é passado ou quando `config.add_router_probs=True`) -- Tupla de `torch.Tensor` (um para cada camada) com forma `(batch_size, sequence_length, num_experts)`.

  Logits do roteador do modelo decodificador, úteis para calcular a perda auxiliar em modelos Mixture of Experts.
- **cross_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção da camada de atenção cruzada do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do encoder do modelo.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do codificador na saída de cada camada, além das saídas opcionais do embedding inicial.
- **encoder_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do codificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **encoder_router_logits** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_router_logits=True` é passado ou quando `config.add_router_probs=True`) -- Tupla de `torch.Tensor` (um para cada camada) com forma `(batch_size, sequence_length, num_experts)`.

  Logits do roteador do modelo codificador, úteis para calcular a perda auxiliar e a z_loss para os módulos esparsos.

## NllbMoeForConditionalGeneration[[transformers.NllbMoeForConditionalGeneration]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L1042)

**Parâmetros:**

config ([NllbMoeConfig](/docs/transformers/main/pt/model_doc/nllb-moe#transformers.NllbMoeConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo NllbMoe com uma cabeça de modelagem de linguagem. Pode ser usado para sumarização.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### 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'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L1058)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada do decodificador no vocabulário. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada do decodificador?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção em determinados índices de tokens. Por padrão, uma máscara causal será usada, para garantir que o modelo só possa olhar para entradas anteriores a fim de prever o futuro.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *opcional*) : A tupla consiste em (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de hidden-states na saída da última camada do encoder. Usado na cross-attention do decoder.

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

decoder_inputs_embeds (`torch.Tensor` de forma `(batch_size, target_sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `decoder_input_ids`, você pode escolher passar diretamente uma representação incorporada. Se `past_key_values` for usado, opcionalmente apenas o último `decoder_inputs_embeds` precisa ser inserido (veja `past_key_values`). Isso é útil se você quiser ter mais controle sobre como converter os índices de `decoder_input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo. Se `decoder_input_ids` e `decoder_inputs_embeds` estiverem ambos não definidos, `decoder_inputs_embeds` assume o valor de `inputs_embeds`.

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

output_router_logits (`bool`, *opcional*) : Indica se os logits de todos os roteadores devem ser retornados. Eles são úteis para calcular a perda do roteador e não devem ser retornados durante a inferência.

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

Um `Seq2SeqMoEOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([NllbMoeConfig](/docs/transformers/main/pt/model_doc/nllb-moe#transformers.NllbMoeConfig)) e das entradas.

O método forward de [NllbMoeForConditionalGeneration](/docs/transformers/main/pt/model_doc/nllb-moe#transformers.NllbMoeForConditionalGeneration) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem.
- **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem (pontuações para cada token do vocabulário antes do SoftMax).
- **past_key_values** (`EncoderDecoderCache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- É uma instância de [EncoderDecoderCache](/docs/transformers/main/pt/internal/generation_utils#transformers.EncoderDecoderCache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do decodificador na saída de cada camada, além das saídas do embedding inicial.
- **decoder_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) com forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **decoder_router_logits** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_router_logits=True` é passado ou quando `config.add_router_probs=True`) -- Tupla de `torch.Tensor` (um para cada camada) com forma `(batch_size, sequence_length, num_experts)`.

  Logits do roteador do modelo decodificador, úteis para calcular a perda auxiliar em modelos Mixture of Experts.
- **cross_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção da camada de atenção cruzada do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do encoder do modelo.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do codificador na saída de cada camada, além das saídas do embedding inicial.
- **encoder_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do codificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **encoder_router_logits** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_router_logits=True` é passado ou quando `config.add_router_probs=True`) -- Tupla de `torch.Tensor` (um para cada camada) com forma `(batch_size, sequence_length, num_experts)`.

  Logits do roteador do modelo codificador, úteis para calcular a perda auxiliar e a z_loss para modelos Mixture of Experts.

Exemplo:

```python
```