Este modelo foi contribuído para o Hugging Face Transformers em 30/09/2022.

Time Series Transformer

Visão geral

O modelo Time Series Transformer é um Transformer encoder-decoder simples para previsão de séries temporais. Este modelo foi contribuído por kashif.

Dicas de uso

Assim como outros modelos na biblioteca, TimeSeriesTransformerModel é o Transformer bruto, sem nenhum head no topo, e TimeSeriesTransformerForPrediction adiciona um head de distribuição sobre o primeiro, que pode ser usado para previsão de séries temporais. Observe que este é um modelo de previsão probabilística, e não um modelo de previsão pontual. Isso significa que o modelo aprende uma distribuição, da qual é possível amostrar. O modelo não produz valores diretamente.
TimeSeriesTransformerForPrediction consiste em 2 blocos: um codificador, que recebe como entrada context_length de valores de série temporal (chamados de past_values), e um decodificador, que prevê prediction_length de valores de série temporal para o futuro (chamados de future_values). Durante o treinamento, é necessário fornecer pares de (past_values e future_values) ao modelo.
In addition to the raw (past_values and future_values), one typically provides additional features to the model. These can be the following:
- past_time_features: recursos temporais que o modelo adicionará a past_values. Eles funcionam como “codificações posicionais” para o codificador do Transformer. Exemplos incluem “dia do mês”, “mês do ano”, etc., como valores escalares (e, em seguida, empilhados como um vetor). Por exemplo, se um valor de série temporal específico foi obtido em 11 de agosto, é possível ter [11, 8] como vetor de recurso temporal (11 sendo “dia do mês” e 8 sendo “mês do ano”).
- future_time_features: recursos temporais que o modelo adicionará a future_values. Eles funcionam como “codificações posicionais” para o decodificador do Transformer. Exemplos incluem “dia do mês”, “mês do ano”, etc., como valores escalares (e, em seguida, empilhados como um vetor). Por exemplo, se um determinado valor de série temporal foi obtido em 11 de agosto, é possível ter [11, 8] como vetor de recurso temporal (11 sendo “dia do mês” e 8 sendo “mês do ano”).
- static_categorical_features: características categóricas que são estáticas ao longo do tempo (ou seja, possuem o mesmo valor para todos os past_values e future_values). Um exemplo aqui seria o ID da loja ou o ID da região que identifica uma determinada série temporal. Observe que essas características precisam ser conhecidas para TODOS os pontos de dados (incluindo aqueles no futuro).
- static_real_features: características de valor real que são estáticas ao longo do tempo (ou seja, têm o mesmo valor para todos os past_values e future_values). Um exemplo aqui é a representação de imagem do produto para o qual você tem os valores de série temporal (como o embedding ResNet de uma foto de “tênis”, se a sua série temporal for sobre as vendas de tênis). Observe que essas características precisam ser conhecidas para TODOS os pontos de dados (incluindo aqueles no futuro).
O modelo é treinado usando “teacher-forcing”, de forma semelhante ao treinamento de um Transformer para tradução automática. Isso significa que, durante o treinamento, desloca-se future_values uma posição para a direita como entrada do decoder, precedido pelo último valor de past_values. Em cada passo de tempo, o modelo precisa prever o próximo alvo. Portanto, a configuração do treinamento é semelhante à de um modelo GPT para linguagem, exceto que não há noção de decoder_start_token_id (usamos apenas o último valor do contexto como entrada inicial para o decoder).
No momento da inferência, fornecemos o valor final de past_values como entrada para o decodificador. Em seguida, podemos amostrar do modelo para fazer uma previsão no próximo passo de tempo, que é então fornecida ao decodificador para fazer a previsão seguinte (também chamada de geração autoregressiva).

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 Time Series Transformer: Probabilistic Time Series Forecasting with 🤗 Transformers

TimeSeriesTransformerConfig

classe transformers.TimeSeriesTransformerConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0id2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneis_encoder_decoder: bool = Trueprediction_length: int | None = Nonecontext_length: int | None = Nonedistribution_output: str = 'student_t'loss: str = 'nll'input_size: int = 1lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7)scaling: str | bool | None = 'mean'num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0num_time_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noneencoder_ffn_dim: int = 32decoder_ffn_dim: int = 32encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2activation_function: str = 'gelu'd_model: int = 64dropout: float | int = 0.1encoder_layerdrop: float | int = 0.1decoder_layerdrop: float | int = 0.1attention_dropout: float | int = 0.1activation_dropout: float | int = 0.1num_parallel_samples: int = 100init_std: float = 0.02use_cache: bool = True )

Parâmetros

is_encoder_decoder (bool, opcional, padrão True) — Indica se o modelo é usado como encoder/decoder 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. Esse valor é geralmente determinado pelo conjunto de dados e recomendamos configurá-lo adequadamente.
context_length (int, opcional, padrão prediction_length) — O comprimento do contexto para o codificador. Se for None, 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 lags da série temporal de entrada como covariáveis, frequentemente determinados pela frequência dos dados. O padrão é [1, 2, 3, 4, 5, 6, 7], mas recomendamos ajustá-lo de acordo com o conjunto de dados.
scaling (string ou bool, opcional, padrão "mean") — Se os alvos de entrada devem ser escalados usando o escaler “mean”, o escaler “std” ou nenhum escaler, caso seja None. Se for True, o escaler é definido como “mean”.
num_dynamic_real_features (int, opcional, padrão 0) — O número de características dinâmicas de valor real.
num_static_categorical_features (int, opcional, padrão 0) — O número de recursos categóricos estáticos.
num_static_real_features (int, opcional, padrão 0) — O número de características estáticas de valor real.
num_time_features (int, opcional, padrão 0) — O número de recursos temporais na série temporal de entrada.
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) — Dimensão dos embeddings e dos estados ocultos.
encoder_ffn_dim (int, opcional, padrão 32) — Dimensão da camada “intermediária” (frequentemente chamada de feed-forward) no encoder.
decoder_ffn_dim (int, opcional, padrão 32) — Dimensão da camada “intermediária” (frequentemente chamada de feed-forward) no decoder.
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. Se não for definido, usará o mesmo valor de num_layers.
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.
d_model (int, opcional, padrão 64) — 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.
encoder_layerdrop (Union[float, int], opcional, padrão 0.1) — A probabilidade de LayerDrop para o encoder. Consulte o [artigo do LayerDrop](veja 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 decoder. Consulte o [artigo do LayerDrop](veja 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) — Se o modelo deve ou não retornar as últimas chaves/valores de atenção (não usado por todos os modelos). Relevante apenas se config.is_decoder=True ou quando o modelo for um modelo generativo somente decodificador.

Esta é a classe de configuração para armazenar a configuração de um TimeSeriesTransformerModel. Ela é usada para instanciar um modelo Time Series Transformer 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 huggingface/time-series-transformer-tourism-monthly

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

>>> from transformers import TimeSeriesTransformerConfig, TimeSeriesTransformerModel

>>> # Initializing a Time Series Transformer configuration with 12 time steps for prediction
>>> configuration = TimeSeriesTransformerConfig(prediction_length=12)

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

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

TimeSeriesTransformerModel

classe transformers.TimeSeriesTransformerModel

< source >

( config: TimeSeriesTransformerConfig )

Parâmetros

config (TimeSeriesTransformerConfig) — 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() para carregar os pesos do modelo.

O modelo Time Series Transformer básico, que produz estados ocultos brutos sem nenhum head específico no topo.

Este modelo herda de 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 do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< source >

( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)

Parâmetros

past_values (torch.Tensor de forma (batch_size, sequence_length) ou (batch_size, sequence_length, input_size)) — Valores passados da série temporal, que servem como contexto para prever o futuro. O tamanho da sequência deste tensor deve ser maior que o context_length do modelo, pois o modelo usará o tamanho maior para construir recursos de defasagem, ou seja, valores adicionais do passado que são incluídos para servir como “contexto extra”.
O sequence_length aqui é igual a config.context_length + max(config.lags_sequence), o que, se nenhum lags_sequence for configurado, é igual a config.context_length + 7 (pois, por padrão, o maior índice de retorno em config.lags_sequence é 7). A propriedade _past_length retorna o comprimento real do passado.

O past_values é o que o codificador do Transformer recebe como entrada (com recursos adicionais opcionais, como static_categorical_features, static_real_features, past_time_features e lags).

Opcionalmente, os valores ausentes precisam ser substituídos por zeros e indicados por meio do past_observed_mask.

Para séries temporais multivariadas, a dimensão input_size > 1 é obrigatória e corresponde ao número de variáveis da série temporal por passo de tempo.
past_time_features (torch.Tensor de forma (batch_size, sequence_length, num_features)) — Recursos de tempo obrigatórios, que o modelo adicionará internamente a past_values. Esses recursos podem ser coisas como “mês do ano”, “dia do mês”, etc., codificados como vetores (por exemplo, como recursos de Fourier). Esses 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. Os recursos de idade têm valores pequenos para passos de tempo distantes no passado e aumentam monotonicamente quanto mais nos aproximamos do passo de tempo atual. Os recursos de feriados também são um bom exemplo de recursos de tempo.
Esses recursos funcionam como as “codificações posicionais” das entradas. Portanto, ao contrário de um modelo como BERT, em que as codificações de posição são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige o fornecimento de recursos temporais adicionais. O Time Series Transformer apenas aprende incorporações adicionais para static_categorical_features.

Covariáveis dinâmicas reais adicionais podem ser concatenadas a este tensor, com a ressalva de que esses recursos devem ser conhecidos no momento da previsão.

O num_features aqui é igual a config.num_time_features+config.num_dynamic_real_features`.
past_observed_mask (torch.BoolTensor de forma (batch_size, sequence_length) ou (batch_size, sequence_length, input_size), 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) — Recursos categóricos estáticos opcionais para os quais o modelo aprenderá um embedding, que será adicionado aos valores da série temporal.
Recursos categóricos estáticos 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 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 reais estáticos opcionais que o modelo adicionará aos valores da série temporal.
Recursos reais estáticos 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 real estático é a informação de promoção.
future_values (torch.Tensor de forma (batch_size, prediction_length) ou (batch_size, prediction_length, input_size), opcional) — Valores futuros da série temporal, que servem como rótulos para o modelo. O future_values é o que o Transformer precisa durante o treinamento para aprender a produzir, dado o past_values.
O comprimento da sequência aqui é igual a prediction_length.

Veja o notebook de demonstração e os trechos de código para mais detalhes.

Opcionalmente, durante o treinamento, quaisquer valores ausentes precisam ser substituídos por zeros e indicados por meio do future_observed_mask.

Para séries temporais multivariadas, a dimensão input_size > 1 é obrigatória e corresponde ao número de variáveis da série temporal por passo de tempo.
future_time_features (torch.Tensor de forma (batch_size, prediction_length, num_features)) — Recursos temporais obrigatórios para a janela de previsão, que o modelo adicionará internamente a future_values. Esses recursos 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. Os 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. Recursos de feriados também são um bom exemplo de recursos temporais.
Esses recursos funcionam como as “codificações posicionais” das entradas. Portanto, ao contrário de um modelo como BERT, em que as codificações de posição são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige o fornecimento de recursos temporais adicionais. O Time Series Transformer apenas aprende incorporações adicionais para static_categorical_features.

Covariáveis dinâmicas reais adicionais podem ser concatenadas a este tensor, com a ressalva de que esses recursos devem ser conhecidos no momento da previsão.

O num_features aqui é igual a config.num_time_features+config.num_dynamic_real_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 hidden-states na saída da última camada do encoder. Usado na cross-attention do decoder.
past_key_values (~cache_utils.Cache, opcional) — Estados ocultos 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 no past_key_values retornado pelo modelo em uma etapa anterior da decodificação, quando use_cache=True ou config.use_cache=True.
Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum past_key_values for passado, DynamicCache será inicializado por padrão.

O modelo sairá no mesmo formato de cache que é fornecido como entrada.

Se past_key_values forem usados, espera-se que o usuário insira apenas os input_ids não processados (aqueles que não têm seus estados de chave e valor passados fornecidos a 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 past_key_values são retornados e podem ser usados para acelerar a decodificação (veja past_key_values).

Retorna

Seq2SeqTSModelOutput ou tuple(torch.Tensor)

Um Seq2SeqTSModelOutput 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 (TimeSeriesTransformerConfig) e das entradas.

O método forward do TimeSeriesTransformerModel 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 decodificador 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) — Trata-se de uma instância de EncoderDecoderCache. Para mais detalhes, consulte nosso guia de cache kv.

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 (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um 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 (um 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 (um para cada camada) com 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 codificador 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 (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um 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 (um para cada camada) com 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 retornar à 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:

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerModel

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

>>> model = TimeSeriesTransformerModel.from_pretrained("huggingface/time-series-transformer-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"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state

TimeSeriesTransformerForPrediction

classe transformers.TimeSeriesTransformerForPrediction

< source >

( config: TimeSeriesTransformerConfig )

Parâmetros

config (TimeSeriesTransformerConfig) — 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() para carregar os pesos do modelo.

O modelo Time Series Transformer com uma cabeça de distribuição no topo para previsão de séries temporais.

forward

< source >

( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonefuture_observed_mask: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)

Parâmetros

past_values (torch.Tensor de forma (batch_size, sequence_length) ou (batch_size, sequence_length, input_size)) — Valores passados da série temporal, que servem como contexto para prever o futuro. O tamanho da sequência deste tensor deve ser maior que o context_length do modelo, pois o modelo usará o tamanho maior para construir recursos de defasagem, ou seja, valores adicionais do passado que são incluídos para servir como “contexto extra”.
O sequence_length aqui é igual a config.context_length + max(config.lags_sequence), o que, se nenhum lags_sequence for configurado, é igual a config.context_length + 7 (pois, por padrão, o maior índice de retorno em config.lags_sequence é 7). A propriedade _past_length retorna o comprimento real do passado.

O past_values é o que o codificador do Transformer recebe como entrada (com recursos adicionais opcionais, como static_categorical_features, static_real_features, past_time_features e lags).

Opcionalmente, os valores ausentes precisam ser substituídos por zeros e indicados por meio do past_observed_mask.

Para séries temporais multivariadas, a dimensão input_size > 1 é obrigatória e corresponde ao número de variáveis da série temporal por passo de tempo.
past_time_features (torch.Tensor de forma (batch_size, sequence_length, num_features)) — Recursos de tempo obrigatórios, que o modelo adicionará internamente a past_values. Esses recursos podem ser coisas como “mês do ano”, “dia do mês”, etc., codificados como vetores (por exemplo, como recursos de Fourier). Esses 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. Os recursos de idade têm valores pequenos para passos de tempo distantes no passado e aumentam monotonicamente quanto mais nos aproximamos do passo de tempo atual. Os recursos de feriados também são um bom exemplo de recursos de tempo.
Esses recursos funcionam como as “codificações posicionais” das entradas. Portanto, ao contrário de um modelo como BERT, em que as codificações de posição são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige o fornecimento de recursos temporais adicionais. O Time Series Transformer apenas aprende incorporações adicionais para static_categorical_features.

Covariáveis dinâmicas reais adicionais podem ser concatenadas a este tensor, com a ressalva de que esses recursos devem ser conhecidos no momento da previsão.

O num_features aqui é igual a config.num_time_features+config.num_dynamic_real_features`.
past_observed_mask (torch.BoolTensor de forma (batch_size, sequence_length) ou (batch_size, sequence_length, input_size), 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) — Recursos categóricos estáticos opcionais para os quais o modelo aprenderá um embedding, que será adicionado aos valores da série temporal.
Recursos categóricos estáticos 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 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 reais estáticos opcionais que o modelo adicionará aos valores da série temporal.
Recursos reais estáticos 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 real estático é a informação de promoção.
future_values (torch.Tensor de forma (batch_size, prediction_length) ou (batch_size, prediction_length, input_size), opcional) — Valores futuros da série temporal, que servem como rótulos para o modelo. O future_values é o que o Transformer precisa durante o treinamento para aprender a produzir, dado o past_values.
O comprimento da sequência aqui é igual a prediction_length.

Veja o notebook de demonstração e os trechos de código para mais detalhes.

Opcionalmente, durante o treinamento, quaisquer valores ausentes precisam ser substituídos por zeros e indicados por meio do future_observed_mask.

Para séries temporais multivariadas, a dimensão input_size > 1 é obrigatória e corresponde ao número de variáveis da série temporal por passo de tempo.
future_time_features (torch.Tensor de forma (batch_size, prediction_length, num_features)) — Recursos temporais obrigatórios para a janela de previsão, que o modelo adicionará internamente a future_values. Esses recursos 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. Os 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. Recursos de feriados também são um bom exemplo de recursos temporais.
Esses recursos funcionam como as “codificações posicionais” das entradas. Portanto, ao contrário de um modelo como BERT, em que as codificações de posição são aprendidas do zero internamente como parâmetros do modelo, o Time Series Transformer exige o fornecimento de recursos temporais adicionais. O Time Series Transformer apenas aprende incorporações adicionais para static_categorical_features.

Covariáveis dinâmicas reais adicionais podem ser concatenadas a este tensor, com a ressalva de que esses recursos devem ser conhecidos no momento da previsão.

O num_features aqui é igual a config.num_time_features+config.num_dynamic_real_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 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 hidden-states na saída da última camada do encoder. Usado na cross-attention do decoder.
past_key_values (~cache_utils.Cache, opcional) — Estados ocultos 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 no past_key_values retornado pelo modelo em uma etapa anterior da decodificação, quando use_cache=True ou config.use_cache=True.
Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum past_key_values for passado, DynamicCache será inicializado por padrão.

O modelo sairá no mesmo formato de cache que é fornecido como entrada.

Se past_key_values forem usados, espera-se que o usuário insira apenas os input_ids não processados (aqueles que não têm seus estados de chave e valor passados fornecidos a 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 past_key_values são retornados e podem ser usados para acelerar a decodificação (veja past_key_values).

Retorna

Seq2SeqTSModelOutput ou tuple(torch.Tensor)

O método forward do TimeSeriesTransformerForPrediction 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 decodificador 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) — Trata-se de uma instância de EncoderDecoderCache. Para mais detalhes, consulte nosso guia de cache kv.

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 (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um 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 (um 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 (um para cada camada) com 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 codificador 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 (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um 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 (um para cada camada) com 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 retornar à 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:

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerForPrediction

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

>>> model = TimeSeriesTransformerForPrediction.from_pretrained(
...     "huggingface/time-series-transformer-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"],
...     static_real_features=batch["static_real_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"],
...     static_real_features=batch["static_real_features"],
...     future_time_features=batch["future_time_features"],
... )

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

Update on GitHub