# Switch Transformers

[Switch Transformers](https://huggingface.co/papers/2101.03961) é um modelo T5 esparsa no qual a camada MLP é substituída por um Mixture-of-Experts (MoE). Um mecanismo de roteamento associa cada token a um especialista, e cada especialista é um MLP denso. A esparsidade permite uma melhor escalabilidade e o mecanismo de roteamento permite que o modelo selecione pesos relevantes em tempo de execução, o que aumenta a capacidade do modelo.

Você pode encontrar todos os checkpoints originais do Switch Transformers na coleção [Switch Transformer](https://huggingface.co/collections/google/switch-transformers-release-6548c35c6507968374b56d1f).

> [!TIP]
> Este modelo foi contribuído por [ybelkada](https://huggingface.co/ybelkada) e [ArthurZ](https://huggingface.co/ArthurZ).
>
> Clique em Switch Transformers models na barra lateral à direita para ver mais exemplos de como aplicar o Switch Transformers a diferentes tarefas de linguagem natural.

O exemplo abaixo demonstra como prever o token mascarado com [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline), [AutoModel](/docs/transformers/main/pt/model_doc/auto#transformers.AutoModel) e pela linha de comando.

```python
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/switch-base-8")
model = AutoModelForSeq2SeqLM.from_pretrained("google/switch-base-8", device_map="auto")

input_text = "The capital of France is <extra_id_0>."
input_ids = tokenizer(input_text, return_tensors="pt").input_ids.to(0)

outputs = model.generate(input_ids)
print(tokenizer.decode(outputs[0]))
```

A quantização reduz a carga de memória de modelos grandes ao representar os pesos em uma precisão menor. Consulte a visão geral de [Quantização](../quantization/overview) para mais backends de quantização disponíveis.

O exemplo abaixo usa [bitsandbytes](../quantization/bitsandbytes) para quantizar apenas os pesos para 8 bits.

```python
# pip install bitsandbytes
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer, BitsAndBytesConfig

tokenizer = AutoTokenizer.from_pretrained("google/switch-base-8")
quantization_config = BitsAndBytesConfig(load_in_8bit=True)
model = AutoModelForSeq2SeqLM.from_pretrained("google/switch-base-8", device_map="auto", quantization_config=quantization_config)

input_text = "The capital of France is <extra_id_0>."
input_ids = tokenizer(input_text, return_tensors="pt").input_ids.to(0)

outputs = model.generate(input_ids)
print(tokenizer.decode(outputs[0]))
```

## SwitchTransformersConfig[[transformers.SwitchTransformersConfig]]

#### transformers.SwitchTransformersConfig[[transformers.SwitchTransformersConfig]]

```python
transformers.SwitchTransformersConfig(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 = 32128, d_model: int = 768, d_kv: int = 64, d_ff: int = 2048, expert_capacity: int = 64, num_layers: int = 12, num_sparse_encoder_layers: int = 3, num_decoder_layers: int | None = 12, num_sparse_decoder_layers: int = 3, num_heads: int = 12, num_experts: int = 8, router_bias: bool = False, router_jitter_noise: int | float = 0.01, router_dtype: typing.Literal['float32', 'float16', 'bfloat16'] = 'float32', router_ignore_padding_tokens: bool = False, relative_attention_num_buckets: int = 32, relative_attention_max_distance: int = 128, dropout_rate: float | int = 0.1, layer_norm_epsilon: float = 1e-06, router_z_loss_coef: float = 0.001, router_aux_loss_coef: float = 0.001, initializer_factor: float = 1.0, dense_act_fn: str = 'relu', add_router_probs: bool = False, use_cache: bool = True, pad_token_id: int | None = 0, eos_token_id: int | list[int] | None = 1, bos_token_id: int | None = None, tie_word_embeddings: bool = True, is_decoder: bool = False, add_cross_attention: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/configuration_switch_transformers.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 `32128`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`.

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

d_kv (`int`, *opcional*, padrão `64`) : Tamanho das projeções de chave, consulta e valor por cabeça de atenção. O `inner_dim` da camada de projeção será definido como `num_heads * d_kv`.

d_ff (`int`, *opcional*, padrão `2048`) : Dimensão das representações do MLP.

expert_capacity (`int`, *opcional*, padrão `64`) : O número de tokens que cada especialista pode processar. Se `None`, `expert_capacity` será definido como `(sequence_length / num_experts) * capacity_factor`.

num_layers (`int`, *opcional*, padrão `12`) : Número de camadas ocultas no decodificador do Transformer.

num_sparse_encoder_layers (`int`, *opcional*, padrão 3) : Número de camadas ocultas densas esparsas (MoE) na camada do codificador Transformer. Observação: Quando definido como 0 com `num_layers=1`, a implementação atual ainda pode criar uma camada esparsa devido ao cálculo do passo esparsa. Esse caso de borda não é encontrado nos checkpoints existentes.

num_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.

num_sparse_decoder_layers (`int`, *opcional*, padrão 3) : Número de camadas ocultas densas esparsas (MoE) na camada do decodificador do Transformer. Observação: quando definido como 0 com `num_decoder_layers=1`, a implementação atual ainda pode criar uma camada esparsa devido ao cálculo do passo esparsa. Esse caso de borda não é encontrado nos checkpoints existentes.

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

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

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

router_jitter_noise (`Union[int, float]`, *opcional*, padrão `0.01`) : Quantidade de ruído a ser adicionada aos logits do roteador durante o treinamento para um melhor balanceamento de carga.

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.

relative_attention_num_buckets (`int`, *opcional*, padrão 32) : O número de buckets a serem usados em cada camada de atenção.

relative_attention_max_distance (`int`, *opcional*, padrão 128) : A distância máxima das sequências mais longas para a separação em buckets.

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

layer_norm_epsilon (`float`, *opcional*, padrão `1e-06`) : O epsilon usado pelas camadas de normalização de camada.

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.

initializer_factor (`float`, *opcional*, padrão `1.0`) : Um fator para inicializar todas as matrizes de pesos (deve ser mantido em 1, usado internamente para testes de inicialização).

dense_act_fn (`string`, *opcional*, padrão `"relu"`) : Tipo de camada feed forward a ser utilizada. Deve ser um dos valores `"relu"` ou `"gated-gelu"`. O SwitchTransformersv1.1 utiliza a projeção feed forward `"gated-gelu"`. O SwitchTransformers original utiliza `"relu"`.

add_router_probs (`bool`, *opcional*, padrão `False`) : Se deve ou não exibir as probabilidades do roteador para calcular a perda auxiliar do roteador.

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.

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

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

bos_token_id (`int`, *opcional*) : ID do token usado para o início 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.

is_decoder (`bool`, *opcional*, padrão `False`) : Indica se o modelo é usado como decodificador ou não. Se `False`, o modelo é usado como codificador.

add_cross_attention (`bool`, *opcional*, padrão `False`) : Se as camadas de atenção cruzada devem ser adicionadas ao modelo.

Esta é a classe de configuração para armazenar a configuração de um SwitchTransformersModel. Ela é usada para instanciar um modelo Switch Transformers 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 [google/switch-base-8](https://huggingface.co/google/switch-base-8)

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.

## SwitchTransformersTop1Router[[transformers.SwitchTransformersTop1Router]]

#### transformers.SwitchTransformersTop1Router[[transformers.SwitchTransformersTop1Router]]

```python
transformers.SwitchTransformersTop1Router(config: SwitchTransformersConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L52)

O roteador que usa tokens escolhe a atribuição dos especialistas top-1.

Este roteador usa o mesmo mecanismo do Switch Transformer (https://huggingface.co/papers/2101.03961) e do V-MoE (https://huggingface.co/papers/2106.05974): os tokens escolhem seus especialistas principais. Os itens são ordenados por router_probs e, em seguida, roteados para o especialista escolhido 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.

#### forward[[transformers.SwitchTransformersTop1Router.forward]]

```python
forward(hidden_states: Tensor)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L72)

**Parâmetros:**

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

**Retorna:** expert_index (`torch.Tensor`)

Máscara de despacho one-hot de forma (batch_size, sequence_length, num_experts) com tokens roteados para um especialista além de sua capacidade mascarados. router_probs (`torch.Tensor`): Tensor de forma (batch_size, sequence_length, 1) com a probabilidade do especialista selecionado para cada token. Usado para escalar as saídas dos especialistas. router_logits (`torch.Tensor`): 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.

Calcula as probabilidades do roteador a partir dos estados ocultos de entrada.

## SwitchTransformersSparseMLP[[transformers.SwitchTransformersSparseMLP]]

#### transformers.SwitchTransformersSparseMLP[[transformers.SwitchTransformersSparseMLP]]

```python
transformers.SwitchTransformersSparseMLP(config: SwitchTransformersConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L182)

#### forward[[transformers.SwitchTransformersSparseMLP.forward]]

```python
forward(hidden_states: Tensor)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L188)

## SwitchTransformersModel[[transformers.SwitchTransformersModel]]

#### transformers.SwitchTransformersModel[[transformers.SwitchTransformersModel]]

```python
transformers.SwitchTransformersModel(config: SwitchTransformersConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L802)

**Parâmetros:**

config ([SwitchTransformersConfig](/docs/transformers/main/pt/model_doc/switch_transformers#transformers.SwitchTransformersConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. Inicializar 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 Switch Transformers básico, que produz 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.SwitchTransformersModel.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.BoolTensor] = 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, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L830)

**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.BoolTensor` 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 possa olhar apenas 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`.

**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 [SwitchTransformersModel](/docs/transformers/main/pt/model_doc/switch_transformers#transformers.SwitchTransformersModel) sobrescreve 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.

## SwitchTransformersForConditionalGeneration[[transformers.SwitchTransformersForConditionalGeneration]]

#### transformers.SwitchTransformersForConditionalGeneration[[transformers.SwitchTransformersForConditionalGeneration]]

```python
transformers.SwitchTransformersForConditionalGeneration(config: SwitchTransformersConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L944)

**Parâmetros:**

config ([SwitchTransformersConfig](/docs/transformers/main/pt/model_doc/switch_transformers#transformers.SwitchTransformersConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. Inicializar 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.

Modelo SWITCH_TRANSFORMERS com uma cabeça de `language modeling` 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.SwitchTransformersForConditionalGeneration.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.BoolTensor] = 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, output_router_logits: bool | None = False, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L981)

**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.BoolTensor` 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 possa olhar apenas 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]`.

output_router_logits (`bool`, *opcional*, padrão `False`) : Se deve ou não retornar os logits de todos os roteadores. 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 (`None`) e das entradas.

O método forward de [SwitchTransformersForConditionalGeneration](/docs/transformers/main/pt/model_doc/switch_transformers#transformers.SwitchTransformersForConditionalGeneration) sobrescreve 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.

## SwitchTransformersEncoderModel[[transformers.SwitchTransformersEncoderModel]]

#### transformers.SwitchTransformersEncoderModel[[transformers.SwitchTransformersEncoderModel]]

```python
transformers.SwitchTransformersEncoderModel(config: SwitchTransformersConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L1098)

#### forward[[transformers.SwitchTransformersEncoderModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, 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/switch_transformers/modeling_switch_transformers.py#L1120)

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

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.

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:** `MoEModelOutput` ou `tuple(torch.Tensor)`

Um `MoEModelOutput` 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 [SwitchTransformersEncoderModel](/docs/transformers/main/pt/model_doc/switch_transformers#transformers.SwitchTransformersEncoderModel) sobrescreve 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 modelo.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`.

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

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

  Probabilidades brutas do roteador calculadas pelos roteadores de MoE; esses termos são usados para calcular a perda auxiliar e a z_loss para modelos Mixture of Experts.