Transformers documentation
Autoformer
Este modelo se publicó en HF papers el 24-06-2021 y se contribuyó a Hugging Face Transformers el 30-05-2023.
Autoformer
Resumen
El modelo Autoformer fue propuesto en Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting por Haixu Wu, Jiehui Xu, Jianmin Wang, Mingsheng Long.
Este modelo amplía el Transformer como una arquitectura de descomposición profunda, que puede descomponer progresivamente las componentes de tendencia y estacionalidad durante el proceso de predicción.
El resumen del artículo es el siguiente:
Extender el horizonte de predicción es una necesidad crítica para aplicaciones reales, como la alerta temprana de fenómenos meteorológicos extremos y la planificación a largo plazo del consumo de energía. Este artículo estudia el problema de la predicción a largo plazo de series temporales. Los modelos basados en Transformers anteriores adoptan diversos mecanismos de autoatención para descubrir dependencias de largo alcance. Sin embargo, los patrones temporales intrincados del futuro a largo plazo impiden que el modelo encuentre dependencias fiables. Además, los Transformers deben adoptar versiones dispersas de la autoatención punto a punto para la eficiencia en series largas, lo que resulta en un cuello de botella en la utilización de la información. Yendo más allá de los Transformers, diseñamos Autoformer como una nueva arquitectura de descomposición con un mecanismo de Auto-Correlation. Rompemos con la convención de preprocesamiento de la descomposición de series y la renovamos como un bloque interno básico de los modelos profundos. Este diseño dota a Autoformer de capacidades de descomposición progresiva para series temporales complejas. Además, inspirados en la teoría de procesos estocásticos, diseñamos el mecanismo de Auto-Correlation basado en la periodicidad de la serie, que realiza el descubrimiento de dependencias y la agregación de representaciones a nivel de subseries. Auto-Correlation supera a la autoatención tanto en eficiencia como en precisión. En la predicción a largo plazo, Autoformer logra una precisión líder en el sector, con una mejora relativa del 38 % en seis benchmarks, que cubren cinco aplicaciones prácticas: energía, tráfico, economía, clima y enfermedad.
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.
- Echa un vistazo al artículo de blog sobre Autoformer en el blog de HuggingFace: Sí, los Transformers son efectivos para la predicción de series de tiempo (+ Autoformer)
AutoformerConfig
clase transformers.AutoformerConfig
< 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: bool | str = Truenum_time_features: int = 0num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32activation_function: str = 'gelu'dropout: 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 = Truelabel_length: int = 10moving_average: int = 25autocorrelation_factor: int = 3 )
Parámetros
- is_encoder_decoder (
bool, opcional, valor predeterminadoTrue) — 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. - context_length (
int, opcional, valor predeterminadoprediction_length) — La longitud de contexto para el codificador. Si no se establece, la longitud de contexto será la misma que la deprediction_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 cabeceradistribution_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. El valor predeterminado es[1, 2, 3, 4, 5, 6, 7]. - scaling (
bool, opcional por defectoTrue) — Si se deben escalar los objetivos de entrada. - num_time_features (
int, opcional, valor predeterminado 0) — El número de características temporales en la serie temporal de entrada. - num_dynamic_real_features (
int, opcional, valor predeterminado 0) — El número de características dinámicas de valor real. - num_static_categorical_features (
int, opcional, valor predeterminado 0) — El número de características categóricas estáticas. - num_static_real_features (
int, opcional, valor predeterminado 0) — El número de características estáticas de valor real. - 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 quenum_static_categorical_features. No puede serNonesinum_static_categorical_featureses > 0. - embedding_dimension (
list[int], opcional) — Dimensionalidad de los embeddings y los estados ocultos. - d_model (
int, opcional, valor predeterminado64) — Tamaño de las capas del codificador y de la capa pooler. - encoder_attention_heads (
int, opcional, valor predeterminado2) — Número de cabezas de atención para cada capa de atención en el codificador Transformer. - decoder_attention_heads (
int, opcional, valor predeterminado2) — Número de cabezas de atención para cada capa de atención en el decodificador del Transformer. - encoder_layers (
int, opcional, valor predeterminado2) — Número de capas ocultas en el codificador del Transformer. Usará el mismo valor quenum_layerssi no se establece. - decoder_layers (
int, opcional, valor predeterminado2) — Número de capas ocultas en el decodificador del Transformer. Si no se establece, se usará el mismo valor quenum_layers. - encoder_ffn_dim (
int, opcional, valor predeterminado32) — Dimensionalidad de la capa “intermedia” (a menudo denominada feed-forward) en el codificador. - decoder_ffn_dim (
int, opcional, valor predeterminado32) — Dimensionalidad de la capa “intermedia” (a menudo denominada feed-forward) en el decodificador. - activation_function (
str, opcional, valor predeterminadogelu) — 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 predeterminado0.1) — La proporción para todas las capas de dropout. - encoder_layerdrop (
Union[float, int], opcional, valor predeterminado0.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 predeterminado0.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 predeterminado0.1) — La proporción de dropout para las probabilidades de atención. - activation_dropout (
Union[float, int], opcional, valor predeterminado0.1) — La proporción de dropout para las activaciones dentro de la capa totalmente conectada. - 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 predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos. - use_cache (
bool, opcional, valor predeterminadoTrue) — Indica si el modelo debe devolver las últimas claves/valores de atención (no utilizado por todos los modelos). Solo es relevante siconfig.is_decoder=Trueo cuando el modelo es un modelo generativo solo de decodificador. - label_length (
int, opcional, valor predeterminado 10) — Longitud del token de inicio del decodificador de Autoformer, que se utiliza para la predicción directa de varios pasos (es decir, generación no autorregresiva). - moving_average (
int, opcional, valor predeterminado 25) — El tamaño de la ventana de la media móvil. En la práctica, es el tamaño del kernel en AvgPool1d de la capa de Descomposición. - autocorrelation_factor (
int, opcional, valor predeterminado 3) — Factor de “atención” (es decir, mecanismo de AutoCorrelation) que se utiliza para encontrar los k retardos de autocorrelación más altos. En el artículo se recomienda establecerlo en un número entre 1 y 5.
Esta es la clase de configuración para almacenar la configuración de un AutoformerModel. Se utiliza para instanciar un modelo Autoformer 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/autoformer-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 AutoformerConfig, AutoformerModel
>>> # Initializing a default Autoformer configuration
>>> configuration = AutoformerConfig()
>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = AutoformerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configAutoformerModel
clase transformers.AutoformerModel
< source >( config: AutoformerConfig )
Parámetros
- config (AutoformerConfig) — 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 Autoformer 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
< 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'> ) → AutoformerModelOutput or tuple(torch.Tensor)
Parámetros
- past_values (
torch.Tensorde forma(batch_size, sequence_length)) — Valores pasados de la serie temporal que sirven como contexto para predecir el futuro. Estos valores pueden contener rezagos, es decir, valores adicionales del pasado que se añaden para servir como «contexto extra». Elpast_valueses lo que el codificador del Transformer recibe como entrada (con características adicionales opcionales, comostatic_categorical_features,static_real_features,past_time_features).La longitud de la secuencia aquí es igual a
context_length+max(config.lags_sequence).Los valores faltantes deben reemplazarse con ceros.
- past_time_features (
torch.Tensorde forma(batch_size, sequence_length, num_features), opcional) — Características de tiempo opcionales, que el modelo añadirá internamente apast_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.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 de tiempo adicionales.
El Autoformer solo aprende embeddings adicionales para
static_categorical_features. - past_observed_mask (
torch.BoolTensorde forma(batch_size, sequence_length), opcional) — Máscara booleana para indicar quépast_valuesse observaron 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.LongTensorde 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.Tensorde 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.Tensorde forma(batch_size, prediction_length)) — Valores futuros de la serie temporal, que sirven como etiquetas para el modelo. Elfuture_valueses lo que el Transformer necesita aprender a generar, dado elpast_values.Vea el cuaderno de demostración y los fragmentos de código para obtener más detalles.
Los valores faltantes deben reemplazarse con ceros.
- future_time_features (
torch.Tensorde forma(batch_size, prediction_length, num_features), opcional) — Características temporales opcionales, que el modelo añadirá internamente afuture_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.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 adicionales.
El Autoformer solo aprende embeddings adicionales para
static_categorical_features. - decoder_attention_mask (
torch.LongTensorde 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 enlast_hidden_state,hidden_states(opcional) yattentions(opcional)last_hidden_statede 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 lapast_key_valuesdevuelta por el modelo en una etapa anterior de la decodificación, cuandouse_cache=Trueoconfig.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 losinput_idsno 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 losinput_idscon forma(batch_size, sequence_length). - use_cache (
bool, opcional) — Si se establece enTrue, se devuelven los estados de clave-valor depast_key_valuesy pueden usarse para acelerar la decodificación (verpast_key_values).
Devuelve
AutoformerModelOutput o tuple(torch.Tensor)
Un AutoformerModelOutput 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 (AutoformerConfig) y las entradas.
El método forward de AutoformerModel 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
Moduledespué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.Tensorde 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).trend (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Tensor de tendencia para cada serie temporal.past_key_values (
Cache, opcional, se devuelve cuando se pasause_cache=Trueo cuandoconfig.use_cache=True) — Es una instancia de Cache. Para más detalles, consulta 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 pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.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 de la incrustación inicial.
decoder_attentions (
tuple[torch.Tensor], opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.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 pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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, se devuelve cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.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 de la incrustación inicial.
encoder_attentions (
tuple[torch.Tensor], opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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.Tensorde 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.Tensorde forma(batch_size, feature size), opcional): Características estáticas de cada serie temporal en un lote, que se copian en las covariables en el momento de la inferencia.static_features (
torch.Tensorde 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 AutoformerModel
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = AutoformerModel.from_pretrained("huggingface/autoformer-tourism-monthly")
>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
... past_values=batch["past_values"],
... past_time_features=batch["past_time_features"],
... past_observed_mask=batch["past_observed_mask"],
... static_categorical_features=batch["static_categorical_features"],
... future_values=batch["future_values"],
... future_time_features=batch["future_time_features"],
... )
>>> last_hidden_state = outputs.last_hidden_stateAutoformerForPrediction
clase transformers.AutoformerForPrediction
< source >( config: AutoformerConfig )
Parámetros
- config (AutoformerConfig) — 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 Autoformer 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
< 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'> ) → Seq2SeqTSPredictionOutput or tuple(torch.Tensor)
Parámetros
- past_values (
torch.Tensorde forma(batch_size, sequence_length)) — Valores pasados de la serie temporal que sirven como contexto para predecir el futuro. Estos valores pueden contener rezagos, es decir, valores adicionales del pasado que se añaden para servir como «contexto extra». Elpast_valueses lo que el codificador del Transformer recibe como entrada (con características adicionales opcionales, comostatic_categorical_features,static_real_features,past_time_features).La longitud de la secuencia aquí es igual a
context_length+max(config.lags_sequence).Los valores faltantes deben reemplazarse con ceros.
- past_time_features (
torch.Tensorde forma(batch_size, sequence_length, num_features), opcional) — Características de tiempo opcionales, que el modelo añadirá internamente apast_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.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 de tiempo adicionales.
El Autoformer solo aprende embeddings adicionales para
static_categorical_features. - past_observed_mask (
torch.BoolTensorde forma(batch_size, sequence_length), opcional) — Máscara booleana para indicar quépast_valuesse observaron 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.LongTensorde 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.Tensorde 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.Tensorde forma(batch_size, prediction_length)) — Valores futuros de la serie temporal, que sirven como etiquetas para el modelo. Elfuture_valueses lo que el Transformer necesita aprender a generar, dado elpast_values.Vea el cuaderno de demostración y los fragmentos de código para obtener más detalles.
Los valores faltantes deben reemplazarse con ceros.
- future_time_features (
torch.Tensorde forma(batch_size, prediction_length, num_features), opcional) — Características temporales opcionales, que el modelo añadirá internamente afuture_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.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 adicionales.
El Autoformer solo aprende embeddings adicionales para
static_categorical_features. - future_observed_mask (
torch.BoolTensorde forma(batch_size, sequence_length)o(batch_size, sequence_length, input_size), opcional) — Máscara booleana para indicar quéfuture_valuesfueron 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.LongTensorde 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 enlast_hidden_state,hidden_states(opcional) yattentions(opcional)last_hidden_statede 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 lapast_key_valuesdevuelta por el modelo en una etapa anterior de la decodificación, cuandouse_cache=Trueoconfig.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 losinput_idsno 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 losinput_idscon forma(batch_size, sequence_length). - use_cache (
bool, opcional) — Si se establece enTrue, se devuelven los estados de clave-valor depast_key_valuesy pueden usarse para acelerar la decodificación (verpast_key_values).
Devuelve
Seq2SeqTSPredictionOutput o tuple(torch.Tensor)
Un Seq2SeqTSPredictionOutput 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 (AutoformerConfig) y las entradas.
El método forward de AutoformerForPrediction 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
Moduledespué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.
loss (
torch.Tensorde forma(1,), opcional, se devuelve cuando se proporciona unfuture_values) — Pérdida distribucional.params (
torch.Tensorde forma(batch_size, num_samples, num_params)) — Parámetros de la distribución elegida.past_key_values (
EncoderDecoderCache, opcional, se devuelve cuando se pasause_cache=Trueo cuandoconfig.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 pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.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 de la incrustación inicial.
decoder_attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.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 pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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 pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.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 de la incrustación inicial.
encoder_attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.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.Tensorde 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.Tensorde 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.Tensorde 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 AutoformerForPrediction
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = AutoformerForPrediction.from_pretrained("huggingface/autoformer-tourism-monthly")
>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
... past_values=batch["past_values"],
... past_time_features=batch["past_time_features"],
... past_observed_mask=batch["past_observed_mask"],
... static_categorical_features=batch["static_categorical_features"],
... future_values=batch["future_values"],
... future_time_features=batch["future_time_features"],
... )
>>> loss = outputs.loss
>>> loss.backward()
>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
... past_values=batch["past_values"],
... past_time_features=batch["past_time_features"],
... past_observed_mask=batch["past_observed_mask"],
... static_categorical_features=batch["static_categorical_features"],
... future_time_features=batch["future_time_features"],
... )
>>> mean_prediction = outputs.sequences.mean(dim=1)AutoformerForPrediction también puede usar static_real_features. Para hacerlo, establezca num_static_real_features en AutoformerConfig en función del número de dichas características en el conjunto de datos (en el caso del conjunto de datos tourism_monthly,
es igual a 1), inicialice el modelo y llame como se muestra a continuación:
>>> from huggingface_hub import hf_hub_download >>> import torch >>> from transformers import AutoformerConfig, AutoformerForPrediction >>> file = hf_hub_download( ... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset" ... ) >>> batch = torch.load(file) >>> # check number of static real features >>> num_static_real_features = batch["static_real_features"].shape[-1] >>> # load configuration of pretrained model and override num_static_real_features >>> configuration = AutoformerConfig.from_pretrained( ... "huggingface/autoformer-tourism-monthly", ... num_static_real_features=num_static_real_features, ... ) >>> # we also need to update feature_size as it is not recalculated >>> configuration.feature_size += num_static_real_features >>> model = AutoformerForPrediction(configuration) >>> outputs = model( ... past_values=batch["past_values"], ... past_time_features=batch["past_time_features"], ... past_observed_mask=batch["past_observed_mask"], ... static_categorical_features=batch["static_categorical_features"], ... static_real_features=batch["static_real_features"], ... future_values=batch["future_values"], ... future_time_features=batch["future_time_features"], ... )