Hugging Face's logo

Transformers documentation

Informer

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo se publicó en HF papers el 2020-12-14 y se contribuyó a Hugging Face Transformers el 2023-03-08.

Informer

Resumen

El modelo Informer fue propuesto en Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting por Haoyi Zhou, Shanghang Zhang, Jieqi Peng, Shuai Zhang, Jianxin Li, Hui Xiong y Wancai Zhang.

Este método introduce un mecanismo de Atención Probabilística para seleccionar las consultas “activas” en lugar de las consultas “perezosas” y proporciona un Transformer disperso, lo que mitiga los requisitos de cómputo y memoria cuadráticos de la atención estándar.

El resumen del artículo es el siguiente:

Muchas aplicaciones del mundo real requieren la predicción de series temporales de secuencias largas, como la planificación del consumo de electricidad. La predicción de series temporales de secuencias largas (LSTF) exige una alta capacidad de predicción del modelo, es decir, la capacidad de capturar de manera eficiente el acoplamiento de dependencias de largo alcance entre la salida y la entrada. Estudios recientes han demostrado el potencial de Transformer para aumentar la capacidad de predicción. Sin embargo, existen varios problemas graves con Transformer que impiden su aplicación directa a LSTF, incluida la complejidad temporal cuadrática, el alto uso de memoria y la limitación inherente de la arquitectura encoder-decoder. Para abordar estos problemas, diseñamos un modelo eficiente basado en transformer para LSTF, llamado Informer, con tres características distintivas: (i) un mecanismo de autoatención ProbSparse, que logra O(L logL) en complejidad temporal y uso de memoria, y tiene un rendimiento comparable en la alineación de dependencias de las secuencias. (ii) la destilación de autoatención resalta la atención dominante al reducir a la mitad la entrada de la capa en cascada, y maneja de manera eficiente secuencias de entrada extremadamente largas. (iii) el decodificador de estilo generativo, aunque conceptualmente simple, predice las secuencias de series temporales largas en una sola operación de propagación hacia adelante en lugar de de manera paso a paso, lo que mejora drásticamente la velocidad de inferencia de las predicciones de secuencias largas. Experimentos extensos en cuatro conjuntos de datos a gran escala demuestran que Informer supera significativamente a los métodos existentes y proporciona una nueva solución al problema de LSTF.

Este modelo fue aportado por elisim y kashif. El código original se puede encontrar aquí.

Recursos

Una lista de recursos oficiales de Hugging Face y de la comunidad (indicados con 🌎) para ayudarte a empezar. Si te interesa enviar un recurso para que se incluya aquí, no dudes en abrir una Pull Request y lo revisaremos. El recurso debería demostrar algo nuevo en lugar de duplicar un recurso existente.

InformerConfig

clase transformers.InformerConfig

< >

( 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, valor predeterminado True) — Indica si el modelo se utiliza como codificador/decodificador o no.
  • prediction_length (int, opcional) — La longitud de predicción para el decodificador. En otras palabras, el horizonte de predicción del modelo. Este valor suele estar determinado por el conjunto de datos y recomendamos configurarlo de manera adecuada.
  • context_length (int, opcional, valor predeterminado prediction_length) — La longitud de contexto para el codificador. Si es None, la longitud de contexto será la misma que la de prediction_length.
  • distribution_output (string, opcional, valor predeterminado "student_t") — La cabeza de emisión de distribución del modelo. Puede ser “student_t”, “normal” o “negative_binomial”.
  • loss (string, opcional, valor predeterminado "nll") — La función de pérdida del modelo correspondiente a la cabecera distribution_output. Para distribuciones paramétricas, es la verosimilitud negativa (nll), que actualmente es la única admitida.
  • input_size (int, opcional, valor predeterminado 1) — El tamaño de la variable objetivo, que por defecto es 1 para objetivos univariados. Sería > 1 en el caso de objetivos multivariados.
  • lags_sequence (list[int], opcional, valor predeterminado [1, 2, 3, 4, 5, 6, 7]) — Los rezagos de la serie temporal de entrada como covariables, a menudo dictados por la frecuencia de los datos. El valor predeterminado es [1, 2, 3, 4, 5, 6, 7], pero recomendamos cambiarlo según corresponda en función del conjunto de datos.
  • scaling (string o bool, opcional por defecto "mean") — Si se deben escalar los objetivos de entrada mediante el escalador “mean”, el escalador “std” o sin escalador si es None. Si es True, el escalador se establece en “mean”.
  • num_dynamic_real_features (int, opcional, valor predeterminado 0) — El número de características dinámicas de valor real.
  • num_static_real_features (int, opcional, valor predeterminado 0) — El número de características estáticas de valor real.
  • num_static_categorical_features (int, opcional, valor predeterminado 0) — El número de características categóricas estáticas.
  • num_time_features (int, opcional, valor predeterminado 0) — El número de características temporales en la serie temporal de entrada.
  • cardinality (list[int], opcional) — La cardinalidad (número de valores distintos) para cada una de las características categóricas estáticas. Debe ser una lista de enteros, con la misma longitud que num_static_categorical_features. No puede ser None si num_static_categorical_features es > 0.
  • embedding_dimension (list[int], opcional) — La dimensión del embedding para cada una de las características categóricas estáticas. Debe ser una lista de enteros, con la misma longitud que num_static_categorical_features. No puede ser None si num_static_categorical_features es > 0.
  • d_model (int, opcional, valor predeterminado 64) — Tamaño de las capas del codificador y de la capa pooler.
  • encoder_ffn_dim (int, opcional, valor predeterminado 32) — Dimensionalidad de la capa “intermedia” (a menudo denominada feed-forward) en el codificador.
  • decoder_ffn_dim (int, opcional, valor predeterminado 32) — Dimensionalidad de la capa “intermedia” (a menudo denominada feed-forward) en el decodificador.
  • encoder_attention_heads (int, opcional, valor predeterminado 2) — Número de cabezas de atención para cada capa de atención en el codificador Transformer.
  • decoder_attention_heads (int, opcional, valor predeterminado 2) — Número de cabezas de atención para cada capa de atención en el decodificador del Transformer.
  • encoder_layers (int, opcional, valor predeterminado 2) — Número de capas ocultas en el codificador del Transformer. Usará el mismo valor que num_layers si no se establece.
  • decoder_layers (int, opcional, valor predeterminado 2) — Número de capas ocultas en el decodificador del Transformer. Si no se establece, se usará el mismo valor que num_layers.
  • activation_function (str, opcional, valor predeterminado gelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, "gelu", "relu", "silu", etc.
  • dropout (Union[float, int], opcional, valor predeterminado 0.05) — La proporción para todas las capas de dropout.
  • encoder_layerdrop (Union[float, int], opcional, valor predeterminado 0.1) — La probabilidad de LayerDrop para el codificador. Consulte el [artículo de LayerDrop](ver https://huggingface.co/papers/1909.11556) para más detalles.
  • decoder_layerdrop (Union[float, int], opcional, valor predeterminado 0.1) — La probabilidad de LayerDrop para el decodificador. Consulte el [artículo de LayerDrop](ver https://huggingface.co/papers/1909.11556) para más detalles.
  • attention_dropout (Union[float, int], opcional, valor predeterminado 0.1) — La proporción de dropout para las probabilidades de atención.
  • activation_dropout (float, opcional, valor predeterminado 0.1) — La probabilidad de dropout utilizada entre las dos capas de las redes feed-forward.
  • num_parallel_samples (int, opcional, valor predeterminado 100) — El número de muestras que se generan en paralelo para cada paso de tiempo de la inferencia.
  • init_std (float, opcional, valor predeterminado 0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
  • use_cache (bool, opcional, valor predeterminado True) — Indica si el modelo debe devolver las últimas claves/valores de atención (no utilizado por todos los modelos). Solo es relevante si config.is_decoder=True o cuando el modelo es un modelo generativo solo de decodificador.
  • attention_type (str, opcional, valor predeterminado “prob”) — Atención utilizada en el codificador. Se puede establecer en “prob” (ProbAttention de Informer) o “full” (autoatención canónica del transformer estándar).
  • sampling_factor (int, opcional, valor predeterminado 5) — Factor de muestreo de ProbSparse (solo tiene efecto cuando attention_type=“prob”). Se utiliza para controlar la longitud de entrada de la matriz de consulta reducida (Q_reduce).
  • distil (bool, opcional, valor predeterminado True) — Si se usa destilación en el codificador.

Esta es la clase de configuración para almacenar la configuración de un InformerModel. Se utiliza para instanciar un modelo Informer según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de huggingface/informer-tourism-monthly

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Ejemplo:

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

InformerModel

clase transformers.InformerModel

< >

( config: InformerConfig )

Parámetros

  • config (InformerConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.

El modelo Informer básico que emite estados ocultos sin ningún cabezal específico en la parte superior.

Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

forward

< >

( 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) o (batch_size, sequence_length, input_size)) — Valores pasados de la serie temporal, que sirven como contexto para predecir el futuro. El tamaño de la secuencia de esta tensor debe ser mayor que el context_length del modelo, ya que el modelo utilizará el tamaño mayor para construir características de rezago, es decir, valores adicionales del pasado que se añaden para servir como «contexto extra».

    La sequence_length aquí es igual a config.context_length + max(config.lags_sequence), lo que, si no se configura lags_sequence, es igual a config.context_length + 7 (ya que, por defecto, el mayor índice de retroceso en config.lags_sequence es 7). La propiedad _past_length devuelve la longitud real del pasado.

    past_values es lo que el codificador del Transformer recibe como entrada (con características adicionales opcionales, como static_categorical_features, static_real_features, past_time_features y rezagos).

    Opcionalmente, los valores faltantes deben reemplazarse con ceros e indicarse mediante past_observed_mask.

    Para series temporales multivariadas, la dimensión input_size > 1 es obligatoria y corresponde al número de variables de la serie temporal por paso de tiempo.

  • past_time_features (torch.Tensor de forma (batch_size, sequence_length, num_features)) — Características de tiempo requeridas, que el modelo añadirá internamente a past_values. Estas podrían ser cosas como «mes del año», «día del mes», etc., codificadas como vectores (por ejemplo, como características de Fourier). También podrían ser las llamadas características de «edad», que básicamente ayudan al modelo a saber «en qué punto de su vida» se encuentra una serie temporal. Las características de edad tienen valores pequeños para los pasos de tiempo del pasado lejano y aumentan de forma monótona a medida que nos acercamos al paso de tiempo actual. Las características de festivos también son un buen ejemplo de características de tiempo.

    Estas características funcionan como las “codificaciones posicionales” de las entradas. Por lo tanto, a diferencia de un modelo como BERT, donde las codificaciones de posición se aprenden desde cero internamente como parámetros del modelo, el Time Series Transformer requiere proporcionar características temporales adicionales. El Time Series Transformer solo aprende incrustaciones adicionales para static_categorical_features.

    Se pueden concatenar covariables dinámicas adicionales a este tensor, con la salvedad de que estas características deben ser conocidas en el momento de la predicción.

    El num_features aquí es igual a config.num_time_features+config.num_dynamic_real_features`.

  • past_observed_mask (torch.BoolTensor de forma (batch_size, sequence_length) o (batch_size, sequence_length, input_size), opcional) — Máscara booleana para indicar qué past_values fueron observados y cuáles faltaron. Valores de la máscara seleccionados en [0, 1]:
    • 1 para los valores que son observados,
    • 0 para los valores que están ausentes (es decir, NaNs que fueron reemplazados por ceros).
  • static_categorical_features (torch.LongTensor de forma (batch_size, number of static categorical features), opcional) — Características categóricas estáticas opcionales para las que el modelo aprenderá un embedding, que se añadirá a los valores de la serie temporal.

    Las características categóricas estáticas son aquellas que tienen el mismo valor para todos los pasos de tiempo (estáticas en el tiempo).

    Un ejemplo típico de una característica categórica estática es un ID de serie temporal.

  • static_real_features (torch.Tensor de forma (batch_size, number of static real features), opcional) — Características reales estáticas opcionales que el modelo añadirá a los valores de la serie temporal.

    Las características reales estáticas son características que tienen el mismo valor para todos los pasos de tiempo (estáticas en el tiempo).

    Un ejemplo típico de una característica real estática es la información de promociones.

  • future_values (torch.Tensor de forma (batch_size, prediction_length) o (batch_size, prediction_length, input_size), opcional) — Valores futuros de la serie temporal, que sirven como etiquetas para el modelo. Los future_values son lo que el Transformer necesita durante el entrenamiento para aprender a generar, dado el past_values.

    La longitud de la secuencia aquí es igual a prediction_length.

    Vea el cuaderno de demostración y los fragmentos de código para obtener más detalles.

    Opcionalmente, durante el entrenamiento, cualquier valor faltante debe reemplazarse con ceros e indicarse mediante future_observed_mask.

    Para series temporales multivariadas, la dimensión input_size > 1 es obligatoria y corresponde al número de variables de la serie temporal por paso de tiempo.

  • future_time_features (torch.Tensor de forma (batch_size, prediction_length, num_features)) — Características temporales requeridas para la ventana de predicción, que el modelo añadirá internamente a future_values. Estas pueden ser cosas como el «mes del año», el «día del mes», etc., codificadas como vectores (por ejemplo, como características de Fourier). También pueden ser las llamadas características de «edad», que básicamente ayudan al modelo a saber «en qué punto de su vida» se encuentra una serie temporal. Las características de edad tienen valores pequeños para los pasos de tiempo del pasado lejano y aumentan de forma monótona a medida que nos acercamos al paso de tiempo actual. Las características de festivos también son un buen ejemplo de características temporales.

    Estas características funcionan como las “codificaciones posicionales” de las entradas. Por lo tanto, a diferencia de un modelo como BERT, donde las codificaciones de posición se aprenden desde cero internamente como parámetros del modelo, el Time Series Transformer requiere proporcionar características temporales adicionales. El Time Series Transformer solo aprende incrustaciones adicionales para static_categorical_features.

    Se pueden concatenar covariables dinámicas adicionales a este tensor, con la salvedad de que estas características deben ser conocidas en el momento de la predicción.

    El num_features aquí es 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 realizar atención en ciertos índices de tokens. De forma predeterminada, se utilizará una máscara causal para asegurarse de que el modelo solo pueda mirar las entradas anteriores para predecir el futuro.
  • encoder_outputs (tuple(tuple(torch.Tensor), opcional) — La tupla consiste en last_hidden_state, hidden_states (opcional) y attentions (opcional) last_hidden_state de forma (batch_size, sequence_length, hidden_size) (opcional) es una secuencia de estados ocultos en la salida de la última capa del codificador. Se utiliza en la atención cruzada del decodificador.
  • past_key_values (~cache_utils.Cache, opcional) — Estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que se pueden usar para acelerar la decodificación secuencial. Esto generalmente consiste en la past_key_values devuelta por el modelo en una etapa anterior de la decodificación, cuando use_cache=True o config.use_cache=True.

    Solo se permite una instancia de Cache como entrada, consulte nuestra guía de caché kv. Si no se pasan past_key_values, DynamicCache se inicializará de forma predeterminada.

    El modelo generará el mismo formato de caché que se proporciona como entrada.

    Si se utilizan past_key_values, se espera que el usuario introduzca únicamente los input_ids no procesados (aquellos que no tienen sus estados de clave y valor pasados proporcionados a este modelo) con forma (batch_size, unprocessed_length) en lugar de todos los input_ids con forma (batch_size, sequence_length).

  • use_cache (bool, opcional) — Si se establece en True, se devuelven los estados de clave-valor de past_key_values y pueden usarse para acelerar la decodificación (ver past_key_values).

Devuelve

Seq2SeqTSModelOutput o tuple(torch.Tensor)

Un Seq2SeqTSModelOutput o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (InformerConfig) y las entradas.

El método forward de InformerModel reemplaza el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del decodificador del modelo.

    Si se utiliza past_key_values, solo se genera el último hidden-state de las secuencias con forma (batch_size, 1, hidden_size).

  • past_key_values (EncoderDecoderCache, opcional, se devuelve cuando se pasa use_cache=True o cuando config.use_cache=True) — Es una instancia de EncoderDecoderCache. Para más detalles, consulte nuestra guía de caché kv.

    Contiene estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que pueden utilizarse (véase la entrada past_key_values) para acelerar la decodificación secuencial.

  • decoder_hidden_states (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de los embeddings, si el modelo tiene una capa de embedding, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos del decodificador en la salida de cada capa más las salidas opcionales de la incrustación inicial.

  • decoder_attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

  • cross_attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención de la capa de atención cruzada del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de atención cruzada.

  • encoder_last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Secuencia de estados ocultos en la salida de la última capa del codificador del modelo.

  • encoder_hidden_states (tuple(torch.Tensor), opcional, devuelto cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos del codificador en la salida de cada capa más las salidas opcionales de la incrustación inicial.

  • encoder_attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención del codificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

  • loc (torch.Tensor de forma (batch_size,) o (batch_size, input_size), opcional) — Desplaza los valores de la ventana de contexto de cada serie temporal, lo que se utiliza para proporcionar al modelo entradas de la misma magnitud y luego se utiliza para desplazar de vuelta a la magnitud original.

  • scale (torch.Tensor de forma (batch_size,) o (batch_size, input_size), opcional) — Valores de escalado de la ventana de contexto de cada serie temporal, que se utilizan para proporcionar al modelo entradas de la misma magnitud y luego para reescalar de vuelta a la magnitud original.

  • static_features (torch.Tensor de forma (batch_size, feature size), opcional) — Características estáticas de cada serie temporal de un lote que se copian en las covariables durante la inferencia.

Ejemplos:

>>> 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_state

InformerForPrediction

clase transformers.InformerForPrediction

< >

( config: InformerConfig )

Parámetros

  • config (InformerConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.

El modelo Informer con una cabeza de distribución en la parte superior para el pronóstico de series temporales.

Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

forward

< >

( 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) o (batch_size, sequence_length, input_size)) — Valores pasados de la serie temporal, que sirven como contexto para predecir el futuro. El tamaño de la secuencia de esta tensor debe ser mayor que el context_length del modelo, ya que el modelo utilizará el tamaño mayor para construir características de rezago, es decir, valores adicionales del pasado que se añaden para servir como «contexto extra».

    La sequence_length aquí es igual a config.context_length + max(config.lags_sequence), lo que, si no se configura lags_sequence, es igual a config.context_length + 7 (ya que, por defecto, el mayor índice de retroceso en config.lags_sequence es 7). La propiedad _past_length devuelve la longitud real del pasado.

    past_values es lo que el codificador del Transformer recibe como entrada (con características adicionales opcionales, como static_categorical_features, static_real_features, past_time_features y rezagos).

    Opcionalmente, los valores faltantes deben reemplazarse con ceros e indicarse mediante past_observed_mask.

    Para series temporales multivariadas, la dimensión input_size > 1 es obligatoria y corresponde al número de variables de la serie temporal por paso de tiempo.

  • past_time_features (torch.Tensor de forma (batch_size, sequence_length, num_features)) — Características de tiempo requeridas, que el modelo añadirá internamente a past_values. Estas podrían ser cosas como «mes del año», «día del mes», etc., codificadas como vectores (por ejemplo, como características de Fourier). También podrían ser las llamadas características de «edad», que básicamente ayudan al modelo a saber «en qué punto de su vida» se encuentra una serie temporal. Las características de edad tienen valores pequeños para los pasos de tiempo del pasado lejano y aumentan de forma monótona a medida que nos acercamos al paso de tiempo actual. Las características de festivos también son un buen ejemplo de características de tiempo.

    Estas características funcionan como las “codificaciones posicionales” de las entradas. Por lo tanto, a diferencia de un modelo como BERT, donde las codificaciones de posición se aprenden desde cero internamente como parámetros del modelo, el Time Series Transformer requiere proporcionar características temporales adicionales. El Time Series Transformer solo aprende incrustaciones adicionales para static_categorical_features.

    Se pueden concatenar covariables dinámicas adicionales a este tensor, con la salvedad de que estas características deben ser conocidas en el momento de la predicción.

    El num_features aquí es igual a config.num_time_features+config.num_dynamic_real_features`.

  • past_observed_mask (torch.BoolTensor de forma (batch_size, sequence_length) o (batch_size, sequence_length, input_size), opcional) — Máscara booleana para indicar qué past_values fueron observados y cuáles faltaron. Valores de la máscara seleccionados en [0, 1]:
    • 1 para los valores que son observados,
    • 0 para los valores que están ausentes (es decir, NaNs que fueron reemplazados por ceros).
  • static_categorical_features (torch.LongTensor de forma (batch_size, number of static categorical features), opcional) — Características categóricas estáticas opcionales para las que el modelo aprenderá un embedding, que se añadirá a los valores de la serie temporal.

    Las características categóricas estáticas son aquellas que tienen el mismo valor para todos los pasos de tiempo (estáticas en el tiempo).

    Un ejemplo típico de una característica categórica estática es un ID de serie temporal.

  • static_real_features (torch.Tensor de forma (batch_size, number of static real features), opcional) — Características reales estáticas opcionales que el modelo añadirá a los valores de la serie temporal.

    Las características reales estáticas son características que tienen el mismo valor para todos los pasos de tiempo (estáticas en el tiempo).

    Un ejemplo típico de una característica real estática es la información de promociones.

  • future_values (torch.Tensor de forma (batch_size, prediction_length) o (batch_size, prediction_length, input_size), opcional) — Valores futuros de la serie temporal, que sirven como etiquetas para el modelo. Los future_values son lo que el Transformer necesita durante el entrenamiento para aprender a generar, dado el past_values.

    La longitud de la secuencia aquí es igual a prediction_length.

    Vea el cuaderno de demostración y los fragmentos de código para obtener más detalles.

    Opcionalmente, durante el entrenamiento, cualquier valor faltante debe reemplazarse con ceros e indicarse mediante future_observed_mask.

    Para series temporales multivariadas, la dimensión input_size > 1 es obligatoria y corresponde al número de variables de la serie temporal por paso de tiempo.

  • future_time_features (torch.Tensor de forma (batch_size, prediction_length, num_features)) — Características temporales requeridas para la ventana de predicción, que el modelo añadirá internamente a future_values. Estas pueden ser cosas como el «mes del año», el «día del mes», etc., codificadas como vectores (por ejemplo, como características de Fourier). También pueden ser las llamadas características de «edad», que básicamente ayudan al modelo a saber «en qué punto de su vida» se encuentra una serie temporal. Las características de edad tienen valores pequeños para los pasos de tiempo del pasado lejano y aumentan de forma monótona a medida que nos acercamos al paso de tiempo actual. Las características de festivos también son un buen ejemplo de características temporales.

    Estas características funcionan como las “codificaciones posicionales” de las entradas. Por lo tanto, a diferencia de un modelo como BERT, donde las codificaciones de posición se aprenden desde cero internamente como parámetros del modelo, el Time Series Transformer requiere proporcionar características temporales adicionales. El Time Series Transformer solo aprende incrustaciones adicionales para static_categorical_features.

    Se pueden concatenar covariables dinámicas adicionales a este tensor, con la salvedad de que estas características deben ser conocidas en el momento de la predicción.

    El num_features aquí es igual a config.num_time_features + config.num_dynamic_real_features.

  • future_observed_mask (torch.BoolTensor de forma (batch_size, sequence_length) o (batch_size, sequence_length, input_size), opcional) — Máscara booleana para indicar qué future_values fueron observados y cuáles faltaron. Valores de la máscara seleccionados en [0, 1]: 1 para valores observados, 0 para valores faltantes (es decir, NaNs que fueron reemplazados por ceros). Esta máscara se utiliza para filtrar los valores faltantes en el cálculo final de la pérdida. [0, 1]:
    • 1 para los valores que son observados,
    • 0 para los valores que están ausentes (es decir, NaNs que fueron reemplazados por ceros).

    Esta máscara se utiliza para filtrar los valores ausentes para el cálculo final de la pérdida.

  • decoder_attention_mask (torch.LongTensor de forma (batch_size, target_sequence_length), opcional) — Máscara para evitar realizar atención en ciertos índices de tokens. De forma predeterminada, se utilizará una máscara causal para asegurarse de que el modelo solo pueda mirar las entradas anteriores para predecir el futuro.
  • encoder_outputs (tuple(tuple(torch.Tensor), opcional) — La tupla consiste en last_hidden_state, hidden_states (opcional) y attentions (opcional) last_hidden_state de forma (batch_size, sequence_length, hidden_size) (opcional) es una secuencia de estados ocultos en la salida de la última capa del codificador. Se utiliza en la atención cruzada del decodificador.
  • past_key_values (~cache_utils.Cache, opcional) — Estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que se pueden usar para acelerar la decodificación secuencial. Esto generalmente consiste en la past_key_values devuelta por el modelo en una etapa anterior de la decodificación, cuando use_cache=True o config.use_cache=True.

    Solo se permite una instancia de Cache como entrada, consulte nuestra guía de caché kv. Si no se pasan past_key_values, DynamicCache se inicializará de forma predeterminada.

    El modelo generará el mismo formato de caché que se proporciona como entrada.

    Si se utilizan past_key_values, se espera que el usuario introduzca únicamente los input_ids no procesados (aquellos que no tienen sus estados de clave y valor pasados proporcionados a este modelo) con forma (batch_size, unprocessed_length) en lugar de todos los input_ids con forma (batch_size, sequence_length).

  • use_cache (bool, opcional) — Si se establece en True, se devuelven los estados de clave-valor de past_key_values y pueden usarse para acelerar la decodificación (ver past_key_values).

Devuelve

Seq2SeqTSModelOutput o tuple(torch.Tensor)

Un Seq2SeqTSModelOutput o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (InformerConfig) y las entradas.

El método forward de InformerForPrediction sobrescribe el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del decodificador del modelo.

    Si se utiliza past_key_values, solo se genera el último hidden-state de las secuencias con forma (batch_size, 1, hidden_size).

  • past_key_values (EncoderDecoderCache, opcional, se devuelve cuando se pasa use_cache=True o cuando config.use_cache=True) — Es una instancia de EncoderDecoderCache. Para más detalles, consulte nuestra guía de caché kv.

    Contiene estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que pueden utilizarse (véase la entrada past_key_values) para acelerar la decodificación secuencial.

  • decoder_hidden_states (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de los embeddings, si el modelo tiene una capa de embedding, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos del decodificador en la salida de cada capa más las salidas opcionales de la incrustación inicial.

  • decoder_attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

  • cross_attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención de la capa de atención cruzada del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de atención cruzada.

  • encoder_last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Secuencia de estados ocultos en la salida de la última capa del codificador del modelo.

  • encoder_hidden_states (tuple(torch.Tensor), opcional, devuelto cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos del codificador en la salida de cada capa más las salidas opcionales de la incrustación inicial.

  • encoder_attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención del codificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

  • loc (torch.Tensor de forma (batch_size,) o (batch_size, input_size), opcional) — Desplaza los valores de la ventana de contexto de cada serie temporal, lo que se utiliza para proporcionar al modelo entradas de la misma magnitud y luego se utiliza para desplazar de vuelta a la magnitud original.

  • scale (torch.Tensor de forma (batch_size,) o (batch_size, input_size), opcional) — Valores de escalado de la ventana de contexto de cada serie temporal, que se utilizan para proporcionar al modelo entradas de la misma magnitud y luego para reescalar de vuelta a la magnitud original.

  • static_features (torch.Tensor de forma (batch_size, feature size), opcional) — Características estáticas de cada serie temporal de un lote que se copian en las covariables durante la inferencia.

Ejemplos:

>>> 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)
Update on GitHub

←Autoformer PatchTSMixer→