# Autoformer

## Visão geral

O modelo Autoformer foi proposto em [Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting](https://huggingface.co/papers/2106.13008) por Haixu Wu, Jiehui Xu, Jianmin Wang, Mingsheng Long.

Este modelo amplia o Transformer como uma arquitetura de decomposição profunda, que pode decompor progressivamente os componentes de tendência e sazonal durante o processo de previsão.

O resumo do artigo é o seguinte:

*Estender o horizonte de previsão é uma demanda crítica para aplicações reais, como o alerta precoce de eventos climáticos extremos e o planejamento de longo prazo do consumo de energia. Este artigo estuda o problema de previsão de longo prazo em séries temporais. Modelos baseados em Transformer anteriores adotam diversos mecanismos de autoatenção para descobrir dependências de longo alcance. No entanto, os padrões temporais intrincados do futuro de longo prazo impedem o modelo de encontrar dependências confiáveis. Além disso, os Transformers precisam adotar versões esparsas das autoatensões ponto a ponto para eficiência em séries longas, o que resulta em um gargalo na utilização de informações. Indo além dos Transformers, projetamos o Autoformer como uma nova arquitetura de decomposição com um mecanismo de Auto-Correlation. Rompemos com a convenção de pré-processamento de decomposição de séries e a renovamos como um bloco interno básico de modelos profundos. Esse design capacita o Autoformer com capacidades de decomposição progressiva para séries temporais complexas. Além disso, inspirados na teoria dos processos estocásticos, projetamos o mecanismo de Auto-Correlation com base na periodicidade da série, que realiza a descoberta de dependências e a agregação de representações no nível de sub-séries. A Auto-Correlation supera a autoatenção tanto em eficiência quanto em precisão. Na previsão de longo prazo, o Autoformer atinge a precisão do estado da arte, com uma melhoria relativa de 38% em seis benchmarks, cobrindo cinco aplicações práticas: energia, tráfego, economia, clima e doenças.*

Este modelo foi contribuído por [elisim](https://huggingface.co/elisim) e [kashif](https://huggingface.co/kashif). O código original pode ser encontrado [aqui](https://github.com/thuml/Autoformer).

## Recursos

Uma lista de recursos oficiais do Hugging Face e da comunidade (indicados por 🌎) para ajudar você a começar. Se você tiver interesse em enviar um recurso para ser incluído aqui, sinta-se à vontade para abrir um Pull Request e faremos a revisão! O recurso deve, idealmente, demonstrar algo novo, em vez de duplicar um recurso existente.

- Confira o post no blog do HuggingFace sobre o Autoformer: [Sim, Transformers são eficazes para previsão de séries temporais (+ Autoformer)](https://huggingface.co/blog/autoformer)

## AutoformerConfig[[transformers.AutoformerConfig]]

#### transformers.AutoformerConfig[[transformers.AutoformerConfig]]

```python
transformers.AutoformerConfig(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, prediction_length: int | None = None, context_length: int | None = None, distribution_output: str = 'student_t', loss: str = 'nll', input_size: int = 1, lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7), scaling: bool | str = True, num_time_features: int = 0, num_dynamic_real_features: int = 0, num_static_categorical_features: int = 0, num_static_real_features: int = 0, cardinality: list[int] | None = None, embedding_dimension: list[int] | None = None, d_model: int = 64, encoder_attention_heads: int = 2, decoder_attention_heads: int = 2, encoder_layers: int = 2, decoder_layers: int = 2, encoder_ffn_dim: int = 32, decoder_ffn_dim: int = 32, activation_function: str = 'gelu', dropout: float | int = 0.1, encoder_layerdrop: float | int = 0.1, decoder_layerdrop: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.1, num_parallel_samples: int = 100, init_std: float = 0.02, use_cache: bool = True, label_length: int = 10, moving_average: int = 25, autocorrelation_factor: int = 3)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/autoformer/configuration_autoformer.py#L24)

**Parâmetros:**

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

prediction_length (`int`, *opcional*) : O comprimento da previsão para o decodificador. Em outras palavras, o horizonte de previsão do modelo.

context_length (`int`, *opcional*, padrão `prediction_length`) : O comprimento do contexto para o codificador. Se não for definido, o comprimento do contexto será o mesmo que o `prediction_length`.

distribution_output (`string`, *opcional*, padrão `"student_t"`) : A cabeça de emissão de distribuição do modelo. Pode ser "student_t", "normal" ou "negative_binomial".

loss (`string`, *opcional*, padrão `"nll"`) : A função de perda do modelo correspondente ao cabeçalho `distribution_output`. Para distribuições paramétricas, é a log-verossimilhança negativa (nll) - que atualmente é a única suportada.

input_size (`int`, *opcional*, padrão 1) : O tamanho da variável alvo, que por padrão é 1 para alvos univariados. Será > 1 no caso de alvos multivariados.

lags_sequence (`list[int]`, *opcional*, padrão `[1, 2, 3, 4, 5, 6, 7]`) : Os defasagens da série temporal de entrada como covariáveis, frequentemente determinados pela frequência. O padrão é `[1, 2, 3, 4, 5, 6, 7]`.

scaling (`bool`, *opcional*, padrão `True`) : Se deve escalar os alvos de entrada.

num_time_features (`int`, *opcional*, padrão 0) : O número de recursos temporais na série temporal de entrada.

num_dynamic_real_features (`int`, *opcional*, padrão 0) : O número de recursos dinâmicos com valores reais.

num_static_categorical_features (`int`, *opcional*, padrão 0) : O número de características categóricas estáticas.

num_static_real_features (`int`, *opcional*, padrão 0) : O número de características reais estáticas.

cardinality (`list[int]`, *opcional*) : A cardinalidade (número de valores distintos) para cada uma das características categóricas estáticas. Deve ser uma lista de inteiros, com o mesmo comprimento que `num_static_categorical_features`. Não pode ser `None` se `num_static_categorical_features` for > 0.

embedding_dimension (`list[int]`, *opcional*) : Dimensionalidade dos embeddings e dos estados ocultos.

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

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

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

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

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

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

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

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

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

encoder_layerdrop (`Union[float, int]`, *opcional*, padrão `0.1`) : 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.1`) : A probabilidade de LayerDrop para o decodificador. Consulte o [artigo do LayerDrop](see https://huggingface.co/papers/1909.11556) para mais detalhes.

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.1`) : A taxa de dropout para as ativações dentro da camada totalmente conectada.

num_parallel_samples (`int`, *opcional*, padrão 100) : O número de amostras a serem geradas em paralelo para cada passo de tempo da inferência.

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

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.

label_length (`int`, *opcional*, padrão 10) : Comprimento do token inicial do decodificador do Autoformer, usado para previsão multietapa direta (ou seja, geração não autoregressiva).

moving_average (`int`, *opcional*, padrão 25) : O tamanho da janela da média móvel. Na prática, é o tamanho do kernel em AvgPool1d da Camada de Decomposição.

autocorrelation_factor (`int`, *opcional*, padrão 3) : fator de "Attention" (ou seja, mecanismo de AutoCorrelation) usado para encontrar os k maiores atrasos de autocorrelação. O artigo recomenda definir esse valor entre 1 e 5.

Esta é a classe de configuração para armazenar a configuração de um AutoformerModel. Ela é usada para instanciar um modelo Autoformer de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os valores padrão resultará em uma configuração semelhante à do [huggingface/autoformer-tourism-monthly](https://huggingface.co/huggingface/autoformer-tourism-monthly)

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 AutoformerConfig, AutoformerModel

>>> # Initializing a default Autoformer configuration
>>> configuration = AutoformerConfig()

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = AutoformerModel(configuration)

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

## AutoformerModel[[transformers.AutoformerModel]]

#### transformers.AutoformerModel[[transformers.AutoformerModel]]

```python
transformers.AutoformerModel(config: AutoformerConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/autoformer/modeling_autoformer.py#L1013)

**Parâmetros:**

config ([AutoformerConfig](/docs/transformers/main/pt/model_doc/autoformer#transformers.AutoformerConfig)) : 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 Autoformer 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.AutoformerModel.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/autoformer/modeling_autoformer.py#L1181)

**Parâmetros:**

past_values (`torch.Tensor` de forma `(batch_size, sequence_length)`) : Valores passados da série temporal, que servem como contexto para prever o futuro. Esses valores podem conter lags, ou seja, valores adicionais do passado que são incluídos para servir como "contexto extra". O `past_values` é o que o encoder do Transformer recebe como entrada (com features adicionais opcionais, como `static_categorical_features`, `static_real_features`, `past_time_features`). O comprimento da sequência aqui é igual a `context_length` + `max(config.lags_sequence)`. Valores ausentes precisam ser substituídos por zeros.

past_time_features (`torch.Tensor` de forma `(batch_size, sequence_length, num_features)`, *opcional*) : Recursos temporais opcionais, que o modelo adicionará internamente a `past_values`. Podem ser coisas como "mês do ano", "dia do mês", etc., codificados como vetores (por exemplo, como recursos de Fourier). Também podem ser os chamados recursos de "idade", que basicamente ajudam o modelo a saber "em que ponto da vida" uma série temporal se encontra. Recursos de idade têm valores pequenos para passos de tempo distantes no passado e aumentam monotonicamente à medida que nos aproximamos do passo de tempo atual. Esses recursos funcionam como as "codificações posicionais" das entradas. Portanto, ao contrário de um modelo como o BERT, onde as codificações posicionais são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige que sejam fornecidos recursos temporais adicionais. O Autoformer apenas aprende embeddings adicionais para `static_categorical_features`.

past_observed_mask (`torch.BoolTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara booleana para indicar quais `past_values` foram observados e quais estavam ausentes. Valores da máscara selecionados em `[0, 1]`:  - 1 para valores que são **observados**, - 0 para valores que estão **ausentes** (ou seja, NaNs que foram substituídos por zeros).

static_categorical_features (`torch.LongTensor` de forma `(batch_size, number of static categorical features)`, *opcional*) : Características categóricas estáticas opcionais para as quais o modelo aprenderá um embedding, que será adicionado aos valores da série temporal. Características categóricas estáticas são aquelas que possuem o mesmo valor para todos os passos de tempo (estáticas ao longo do tempo). Um exemplo típico de uma característica categórica estática é um ID de série temporal.

static_real_features (`torch.Tensor` de forma `(batch_size, number of static real features)`, *opcional*) : Recursos estáticos reais opcionais que o modelo adicionará aos valores da série temporal.  Recursos estáticos reais são recursos que possuem o mesmo valor para todos os passos de tempo (estáticos ao longo do tempo).  Um exemplo típico de recurso estático real é a informação de promoção.

future_values (`torch.Tensor` de forma `(batch_size, prediction_length)`) : Valores futuros da série temporal, que servem como rótulos para o modelo. O `future_values` é o que o Transformer precisa aprender a produzir, dado o `past_values`. Veja o notebook de demonstração e os trechos de código para mais detalhes. Valores ausentes precisam ser substituídos por zeros.

future_time_features (`torch.Tensor` de forma `(batch_size, prediction_length, num_features)`, *opcional*) : Recursos temporais opcionais, que o modelo adicionará internamente a `future_values`. Podem ser coisas como "mês do ano", "dia do mês", etc., codificados como vetores (por exemplo, como recursos de Fourier). Também podem ser os chamados recursos de "idade", que basicamente ajudam o modelo a saber "em que ponto da vida" uma série temporal se encontra. Recursos de idade têm valores pequenos para passos de tempo distantes no passado e aumentam monotonicamente à medida que nos aproximamos do passo de tempo atual. Esses recursos funcionam como as "codificações posicionais" das entradas. Portanto, ao contrário de um modelo como o BERT, onde as codificações posicionais são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige que recursos adicionais sejam fornecidos. O Autoformer apenas aprende embeddings adicionais para `static_categorical_features`.

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`, `hidden_states` (*opcional*) e `attentions` (*opcional*) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)` (*opcional*) é uma sequência de estados ocultos na saída da última camada do codificador. Usado na atenção cruzada do decodificador.

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

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

Um `AutoformerModelOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo diversos elementos, dependendo da configuração ([AutoformerConfig](/docs/transformers/main/pt/model_doc/autoformer#transformers.AutoformerConfig)) e das entradas.

O método forward do [AutoformerModel](/docs/transformers/main/pt/model_doc/autoformer#transformers.AutoformerModel) 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.
- **trend** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Tensor de tendência para cada série temporal.
- **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). 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.
- **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.
- **loc** (`torch.Tensor` de forma `(batch_size,)` ou `(batch_size, input_size)`, *opcional*) -- Desloca os valores da janela de contexto de cada série temporal, o que é usado para fornecer ao modelo entradas da mesma magnitude e, em seguida, para desfazer o deslocamento e voltar à magnitude original.
- **scale** (`torch.Tensor` de forma `(batch_size,)` ou `(batch_size, input_size)`, *opcional*) -- Valores de escala da janela de contexto de cada série temporal, usados para fornecer ao modelo entradas da mesma magnitude e, em seguida, para reescalar de volta à magnitude original. static_features: (`torch.Tensor` de forma `(batch_size, feature size)`, *opcional*): Recursos estáticos de cada série temporal em um lote, que são copiados para as covariáveis no momento da inferência.
- **static_features** (`torch.Tensor` de forma `(batch_size, feature size)`, *opcional*) -- Recursos estáticos de cada série temporal em um lote que são copiados para as covariáveis no momento da inferência.

Exemplos:

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = AutoformerModel.from_pretrained("huggingface/autoformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state
```

## AutoformerForPrediction[[transformers.AutoformerForPrediction]]

#### transformers.AutoformerForPrediction[[transformers.AutoformerForPrediction]]

```python
transformers.AutoformerForPrediction(config: AutoformerConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/autoformer/modeling_autoformer.py#L1379)

**Parâmetros:**

config ([AutoformerConfig](/docs/transformers/main/pt/model_doc/autoformer#transformers.AutoformerConfig)) : 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 Autoformer com uma cabeça de distribuição no topo para previsão de séries temporais.

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.AutoformerForPrediction.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, future_observed_mask: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/autoformer/modeling_autoformer.py#L1413)

**Parâmetros:**

past_values (`torch.Tensor` de forma `(batch_size, sequence_length)`) : Valores passados da série temporal, que servem como contexto para prever o futuro. Esses valores podem conter lags, ou seja, valores adicionais do passado que são incluídos para servir como "contexto extra". O `past_values` é o que o encoder do Transformer recebe como entrada (com features adicionais opcionais, como `static_categorical_features`, `static_real_features`, `past_time_features`). O comprimento da sequência aqui é igual a `context_length` + `max(config.lags_sequence)`. Valores ausentes precisam ser substituídos por zeros.

past_time_features (`torch.Tensor` de forma `(batch_size, sequence_length, num_features)`, *opcional*) : Recursos temporais opcionais, que o modelo adicionará internamente a `past_values`. Podem ser coisas como "mês do ano", "dia do mês", etc., codificados como vetores (por exemplo, como recursos de Fourier). Também podem ser os chamados recursos de "idade", que basicamente ajudam o modelo a saber "em que ponto da vida" uma série temporal se encontra. Recursos de idade têm valores pequenos para passos de tempo distantes no passado e aumentam monotonicamente à medida que nos aproximamos do passo de tempo atual. Esses recursos funcionam como as "codificações posicionais" das entradas. Portanto, ao contrário de um modelo como o BERT, onde as codificações posicionais são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige que sejam fornecidos recursos temporais adicionais. O Autoformer apenas aprende embeddings adicionais para `static_categorical_features`.

past_observed_mask (`torch.BoolTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara booleana para indicar quais `past_values` foram observados e quais estavam ausentes. Valores da máscara selecionados em `[0, 1]`:  - 1 para valores que são **observados**, - 0 para valores que estão **ausentes** (ou seja, NaNs que foram substituídos por zeros).

static_categorical_features (`torch.LongTensor` de forma `(batch_size, number of static categorical features)`, *opcional*) : Características categóricas estáticas opcionais para as quais o modelo aprenderá um embedding, que será adicionado aos valores da série temporal. Características categóricas estáticas são aquelas que possuem o mesmo valor para todos os passos de tempo (estáticas ao longo do tempo). Um exemplo típico de uma característica categórica estática é um ID de série temporal.

static_real_features (`torch.Tensor` de forma `(batch_size, number of static real features)`, *opcional*) : Recursos estáticos reais opcionais que o modelo adicionará aos valores da série temporal.  Recursos estáticos reais são recursos que possuem o mesmo valor para todos os passos de tempo (estáticos ao longo do tempo).  Um exemplo típico de recurso estático real é a informação de promoção.

future_values (`torch.Tensor` de forma `(batch_size, prediction_length)`) : Valores futuros da série temporal, que servem como rótulos para o modelo. O `future_values` é o que o Transformer precisa aprender a produzir, dado o `past_values`. Veja o notebook de demonstração e os trechos de código para mais detalhes. Valores ausentes precisam ser substituídos por zeros.

future_time_features (`torch.Tensor` de forma `(batch_size, prediction_length, num_features)`, *opcional*) : Recursos temporais opcionais, que o modelo adicionará internamente a `future_values`. Podem ser coisas como "mês do ano", "dia do mês", etc., codificados como vetores (por exemplo, como recursos de Fourier). Também podem ser os chamados recursos de "idade", que basicamente ajudam o modelo a saber "em que ponto da vida" uma série temporal se encontra. Recursos de idade têm valores pequenos para passos de tempo distantes no passado e aumentam monotonicamente à medida que nos aproximamos do passo de tempo atual. Esses recursos funcionam como as "codificações posicionais" das entradas. Portanto, ao contrário de um modelo como o BERT, onde as codificações posicionais são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige que recursos adicionais sejam fornecidos. O Autoformer apenas aprende embeddings adicionais para `static_categorical_features`.

future_observed_mask (`torch.BoolTensor` de forma `(batch_size, sequence_length)` ou `(batch_size, sequence_length, input_size)`, *opcional*) : Máscara booleana para indicar quais `future_values` foram observados e quais estavam ausentes. Valores da máscara selecionados em `[0, 1]`:  - 1 para valores que são **observados**, - 0 para valores que estão **ausentes** (ou seja, NaNs que foram substituídos por zeros).  Esta máscara é usada para filtrar os valores ausentes no cálculo final da perda.

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`, `hidden_states` (*opcional*) e `attentions` (*opcional*) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)` (*opcional*) é uma sequência de estados ocultos na saída da última camada do codificador. Usado na atenção cruzada do decodificador.

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

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:** [Seq2SeqTSPredictionOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.Seq2SeqTSPredictionOutput) ou `tuple(torch.Tensor)`

Um [Seq2SeqTSPredictionOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.Seq2SeqTSPredictionOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`), composto por diversos elementos, dependendo da configuração ([AutoformerConfig](/docs/transformers/main/pt/model_doc/autoformer#transformers.AutoformerConfig)) e das entradas.

O método forward de [AutoformerForPrediction](/docs/transformers/main/pt/model_doc/autoformer#transformers.AutoformerForPrediction) 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 `future_values` é fornecido) -- Perda distribucional.
- **params** (`torch.Tensor` de forma `(batch_size, num_samples, num_params)`) -- Parâmetros da distribuição escolhida.
- **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.
- **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.
- **loc** (`torch.Tensor` de forma `(batch_size,)` ou `(batch_size, input_size)`, *opcional*) -- Desloca os valores da janela de contexto de cada série temporal, o que é usado para fornecer ao modelo entradas da mesma magnitude e, em seguida, para desfazer o deslocamento e voltar à magnitude original.
- **scale** (`torch.Tensor` de forma `(batch_size,)` ou `(batch_size, input_size)`, *opcional*) -- Valores de escala da janela de contexto de cada série temporal, usados para fornecer ao modelo entradas da mesma magnitude e, em seguida, para reescalar de volta à magnitude original.
- **static_features** (`torch.Tensor` de forma `(batch_size, feature size)`, *opcional*) -- Recursos estáticos de cada série temporal em um lote que são copiados para as covariáveis no momento da inferência.

Exemplos:

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = AutoformerForPrediction.from_pretrained("huggingface/autoformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_time_features=batch["future_time_features"],
... )

>>> mean_prediction = outputs.sequences.mean(dim=1)
```

O AutoformerForPrediction também pode usar static_real_features. Para isso, defina num_static_real_features em AutoformerConfig com base no número de recursos desse tipo no conjunto de dados (no caso do conjunto de dados tourism_monthly, ele

é igual a 1), inicialize o modelo e chame conforme mostrado abaixo:

```
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerConfig, AutoformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> # check number of static real features
>>> num_static_real_features = batch["static_real_features"].shape[-1]

>>> # load configuration of pretrained model and override num_static_real_features
>>> configuration = AutoformerConfig.from_pretrained(
...     "huggingface/autoformer-tourism-monthly",
...     num_static_real_features=num_static_real_features,
... )
>>> # we also need to update feature_size as it is not recalculated
>>> configuration.feature_size += num_static_real_features

>>> model = AutoformerForPrediction(configuration)

>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )
```