Transformers documentation
Informer
Este modelo foi publicado no HF papers em 2020-12-14 e contribuído para o Hugging Face Transformers em 2023-03-08.
Informer
Visão geral
O modelo Informer foi proposto em Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting por Haoyi Zhou, Shanghang Zhang, Jieqi Peng, Shuai Zhang, Jianxin Li, Hui Xiong e Wancai Zhang.
Este método introduz um mecanismo de Atenção Probabilística para selecionar as consultas “ativas” em vez das consultas “preguiçosas” e fornece um Transformer esparsa, mitigando assim os requisitos quadráticos de computação e memória da atenção convencional.
O resumo do artigo é o seguinte:
Muitas aplicações do mundo real exigem a previsão de séries temporais de longa sequência, como o planejamento do consumo de eletricidade. A previsão de séries temporais de longa sequência (LSTF) exige uma alta capacidade de previsão do modelo, ou seja, a capacidade de capturar de forma eficiente o acoplamento de dependência de longo alcance entre a saída e a entrada. Estudos recentes demonstraram o potencial do Transformer para aumentar a capacidade de previsão. No entanto, existem vários problemas graves no Transformer que impedem sua aplicação direta à LSTF, incluindo a complexidade temporal quadrática, o alto uso de memória e a limitação inerente da arquitetura encoder-decoder. Para resolver esses problemas, projetamos um modelo eficiente baseado em Transformer para LSTF, chamado Informer, com três características distintas: (i) um mecanismo de autoatenção ProbSparse, que alcança O(L logL) em complexidade temporal e uso de memória, e apresenta desempenho comparável no alinhamento de dependências das sequências. (ii) a destilação de autoatenção destaca a atenção dominante ao reduzir pela metade a entrada da camada em cascata, e lida de forma eficiente com sequências de entrada extremamente longas. (iii) o decodificador de estilo generativo, embora conceitualmente simples, prevê as sequências de séries temporais longas em uma única operação de encaminhamento, em vez de uma abordagem passo a passo, o que melhora drasticamente a velocidade de inferência de previsões de sequência longa. Experimentos extensivos em quatro conjuntos de dados em larga escala demonstram que o Informer supera significativamente os métodos existentes e oferece uma nova solução para o problema de LSTF.
Este modelo foi contribuído por elisim e kashif. O código original pode ser encontrado aqui.
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: Multivariate Probabilistic Time Series Forecasting with Informer
InformerConfig
classe transformers.InformerConfig
< 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] | None = Nonescaling: str | bool | None = 'mean'num_dynamic_real_features: int = 0num_static_real_features: int = 0num_static_categorical_features: int = 0num_time_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_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'dropout: float | int = 0.05encoder_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 = Trueattention_type: str = 'prob'sampling_factor: int = 5distil: bool = True )
Parâmetros
- is_encoder_decoder (
bool, opcional, padrãoTrue) — 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ãoprediction_length) — O comprimento do contexto para o codificador. Se forNone, o comprimento do contexto será o mesmo que oprediction_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çalhodistribution_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 (
stringoubool, opcional, padrão"mean") — Se os alvos de entrada devem ser escalados usando o escaler “mean”, o escaler “std” ou nenhum escaler, caso sejaNone. Se forTrue, 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_real_features (
int, opcional, padrão 0) — O número de características estáticas de valor real. - num_static_categorical_features (
int, opcional, padrão 0) — O número de recursos categóricos estáticos. - 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 quenum_static_categorical_features. Não pode serNonesenum_static_categorical_featuresfor > 0. - embedding_dimension (
list[int], opcional) — A dimensão do embedding para cada uma das características categóricas estáticas. Deve ser uma lista de inteiros, com o mesmo comprimento quenum_static_categorical_features. Não pode serNonesenum_static_categorical_featuresfor > 0. - d_model (
int, opcional, padrão64) — Tamanho das camadas do codificador e da camada pooler. - encoder_ffn_dim (
int, opcional, padrão32) — Dimensão da camada “intermediária” (frequentemente chamada de feed-forward) no encoder. - decoder_ffn_dim (
int, opcional, padrão32) — Dimensão da camada “intermediária” (frequentemente chamada de feed-forward) no decoder. - encoder_attention_heads (
int, opcional, padrão2) — Número de cabeças de atenção para cada camada de atenção no codificador do Transformer. - decoder_attention_heads (
int, opcional, padrão2) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer. - encoder_layers (
int, opcional, padrão2) — Número de camadas ocultas no codificador do Transformer. Usará o mesmo valor denum_layersse não for definido. - decoder_layers (
int, opcional, padrão2) — Número de camadas ocultas no decodificador do Transformer. Se não for definido, usará o mesmo valor denum_layers. - activation_function (
str, opcional, padrãogelu) — 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ão0.05) — A proporção para todas as camadas de dropout. - encoder_layerdrop (
Union[float, int], opcional, padrão0.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ão0.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ão0.1) — A taxa de dropout para as probabilidades de atenção. - activation_dropout (
float, opcional, padrão 0.1) — A probabilidade de dropout usada entre as duas camadas das redes feed-forward. - 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ão0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos. - use_cache (
bool, opcional, padrãoTrue) — Se o modelo deve ou não retornar as últimas chaves/valores de atenção (não usado por todos os modelos). Relevante apenas seconfig.is_decoder=Trueou quando o modelo for um modelo generativo somente decodificador. - attention_type (
str, opcional, padrão “prob”) — Atenção utilizada no codificador. Pode ser definida como “prob” (ProbAttention do Informer) ou “full” (autoatenção canônica do transformer padrão). - sampling_factor (
int, opcional, padrão 5) — Fator de amostragem do ProbSparse (só tem efeito quandoattention_type=“prob”). É usado para controlar o comprimento de entrada da matriz de consulta reduzida (Q_reduce). - distil (
bool, opcional, padrãoTrue) — Se deve usar destilação no codificador.
Esta é a classe de configuração para armazenar a configuração de um InformerModel. Ela é usada para instanciar um modelo Informer 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/informer-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 InformerConfig, InformerModel
>>> # Initializing an Informer configuration with 12 time steps for prediction
>>> configuration = InformerConfig(prediction_length=12)
>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = InformerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configInformerModel
classe transformers.InformerModel
< source >( config: InformerConfig )
Parâmetros
- config (InformerConfig) — 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 Informer básico, que produz estados ocultos brutos sem nenhum cabeçalho 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.Tensorde 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 ocontext_lengthdo 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_lengthaqui é igual aconfig.context_length+max(config.lags_sequence), o que, se nenhumlags_sequencefor configurado, é igual aconfig.context_length+ 7 (pois, por padrão, o maior índice de retorno emconfig.lags_sequenceé 7). A propriedade_past_lengthretorna o comprimento real do passado.O
past_valuesé o que o codificador do Transformer recebe como entrada (com recursos adicionais opcionais, comostatic_categorical_features,static_real_features,past_time_featurese 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.Tensorde forma(batch_size, sequence_length, num_features)) — Recursos de tempo obrigatórios, que o modelo adicionará internamente apast_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_featuresaqui é igual aconfig.num_time_features+config.num_dynamic_real_features`. - past_observed_mask (
torch.BoolTensorde forma(batch_size, sequence_length)ou(batch_size, sequence_length, input_size), opcional) — Máscara booleana para indicar quaispast_valuesforam 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.LongTensorde 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.Tensorde 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.Tensorde 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. Ofuture_valuesé o que o Transformer precisa durante o treinamento para aprender a produzir, dado opast_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.Tensorde forma(batch_size, prediction_length, num_features)) — Recursos temporais obrigatórios para a janela de previsão, que o modelo adicionará internamente afuture_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. Os 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_featuresaqui é igual aconfig.num_time_features+config.num_dynamic_real_features. - decoder_attention_mask (
torch.LongTensorde 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 emlast_hidden_state,hidden_states(opcional) eattentions(opcional)last_hidden_statede 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 nopast_key_valuesretornado pelo modelo em uma etapa anterior da decodificação, quandouse_cache=Trueouconfig.use_cache=True.Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum
past_key_valuesfor passado, DynamicCache será inicializado por padrão.O modelo sairá no mesmo formato de cache que é fornecido como entrada.
Se
past_key_valuesforem usados, espera-se que o usuário insira apenas osinput_idsnã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 osinput_idscom a forma(batch_size, sequence_length). - use_cache (
bool, opcional) — Se definido comoTrue, os estados de chave-valorpast_key_valuessão retornados e podem ser usados para acelerar a decodificação (vejapast_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 (InformerConfig) e das entradas.
O método forward do InformerModel 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
Moduleem 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.Tensorde 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_valuesfor usado, apenas o último hidden-state das sequências, com forma(batch_size, 1, hidden_size), é retornado.past_key_values (
EncoderDecoderCache, opcional, retornado quandouse_cache=Trueé passado ou quandoconfig.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 quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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 quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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.Tensorde 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.Tensorde 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 InformerModel
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = InformerModel.from_pretrained("huggingface/informer-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_stateInformerForPrediction
classe transformers.InformerForPrediction
< source >( config: InformerConfig )
Parâmetros
- config (InformerConfig) — 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 Informer com uma cabeça de distribuição no topo para previsão de séries temporais.
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] = 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.Tensorde 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 ocontext_lengthdo modelo, pois o modelo usará o tamanho maior para construir recursos de defasagem (lags), ou seja, valores adicionais do passado que são incluídos para servir como “contexto extra”.O
sequence_lengthaqui é igual aconfig.context_length+max(config.lags_sequence), o que, se nenhumlags_sequencefor configurado, é igual aconfig.context_length+ 7 (pois, por padrão, o maior índice de retorno emconfig.lags_sequenceé 7). A propriedade_past_lengthretorna o comprimento real do passado.O
past_valuesé o que o codificador do Transformer recebe como entrada (com recursos adicionais opcionais, comostatic_categorical_features,static_real_features,past_time_featurese 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.Tensorde forma(batch_size, sequence_length, num_features)) — Recursos de tempo obrigatórios, que o modelo adicionará internamente apast_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_featuresaqui é igual aconfig.num_time_features+config.num_dynamic_real_features`. - past_observed_mask (
torch.BoolTensorde forma(batch_size, sequence_length)ou(batch_size, sequence_length, input_size), opcional) — Máscara booleana para indicar quaispast_valuesforam 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.LongTensorde 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.Tensorde 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.Tensorde 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. Ofuture_valuesé o que o Transformer precisa durante o treinamento para aprender a produzir, dado opast_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.Tensorde forma(batch_size, prediction_length, num_features)) — Recursos temporais obrigatórios para a janela de previsão, que o modelo adicionará internamente afuture_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. Os 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_featuresaqui é igual aconfig.num_time_features+config.num_dynamic_real_features. - future_observed_mask (
torch.BoolTensorde forma(batch_size, sequence_length)ou(batch_size, sequence_length, input_size), opcional) — Máscara booleana para indicar quaisfuture_valuesforam 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.LongTensorde 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 emlast_hidden_state,hidden_states(opcional) eattentions(opcional)last_hidden_statede 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 nopast_key_valuesretornado pelo modelo em uma etapa anterior da decodificação, quandouse_cache=Trueouconfig.use_cache=True.Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum
past_key_valuesfor passado, DynamicCache será inicializado por padrão.O modelo sairá no mesmo formato de cache que é fornecido como entrada.
Se
past_key_valuesforem usados, espera-se que o usuário insira apenas osinput_idsnã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 osinput_idscom a forma(batch_size, sequence_length). - use_cache (
bool, opcional) — Se definido comoTrue, os estados de chave-valorpast_key_valuessão retornados e podem ser usados para acelerar a decodificação (vejapast_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 (InformerConfig) e das entradas.
O método forward da InformerForPrediction 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
Moduleem 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.Tensorde 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_valuesfor usado, apenas o último hidden-state das sequências, com forma(batch_size, 1, hidden_size), é retornado.past_key_values (
EncoderDecoderCache, opcional, retornado quandouse_cache=Trueé passado ou quandoconfig.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 quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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 quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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.Tensorde 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.Tensorde 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 InformerForPrediction
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = InformerForPrediction.from_pretrained(
... "huggingface/informer-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)