# TimesFM 2.5

## Resumen

TimesFM 2.5 (Time Series Foundation Model) es un modelo de base preentrenado para series de tiempo propuesto en [A decoder-only foundation model for time-series forecasting](https://huggingface.co/papers/2310.10688) por Abhimanyu Das, Weihao Kong, Rajat Sen y Yichen Zhou. Se basa en la arquitectura original de TimesFM con atención rotativa, normalización QK, escalado de atención por dimensión y predicción de cuantiles continua.

El resumen del artículo es el siguiente:

*Inspirados por los avances recientes en modelos de lenguaje de gran escala para el Procesamiento del Lenguaje Natural (NLP), diseñamos un modelo de base para series temporales de predicción cuyo rendimiento zero-shot, listo para usar, en una variedad de conjuntos de datos públicos se acerca a la precisión de los modelos de predicción supervisados de última generación para cada conjunto de datos individual. Nuestro modelo se basa en el preentrenamiento de un modelo de atención de estilo decodificador con parcheo de entrada, utilizando un gran corpus de series temporales que comprende tanto conjuntos de datos del mundo real como sintéticos. Los experimentos en un conjunto diverso de conjuntos de datos de predicción previamente no vistos sugieren que el modelo puede generar predicciones zero-shot precisas en diferentes dominios, horizontes de predicción y granularidades temporales.*

Este modelo fue aportado por [kashif](https://huggingface.co/kashif). El código original se puede encontrar [aquí](https://github.com/google-research/timesfm).

Puedes encontrar el punto de control en [`google/timesfm-2.5-200m-transformers`](https://huggingface.co/google/timesfm-2.5-200m-transformers).

## Ejemplo de uso

```python
import numpy as np
import torch

from transformers import TimesFm2_5ModelForPrediction

model = TimesFm2_5ModelForPrediction.from_pretrained(
    "google/timesfm-2.5-200m-transformers",
    device_map="auto",
)

forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
forecast_input_tensor = [torch.tensor(ts, dtype=torch.float32, device=model.device) for ts in forecast_input]

with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, return_dict=True)
    point_forecast = outputs.mean_predictions
    quantile_forecast = outputs.full_predictions
```

## TimesFm2_5Config[[transformers.TimesFm2_5Config]]

#### transformers.TimesFm2_5Config[[transformers.TimesFm2_5Config]]

```python
transformers.TimesFm2_5Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, patch_length: int = 32, context_length: int = 16384, horizon_length: int = 128, num_hidden_layers: int = 20, hidden_size: int = 1280, intermediate_size: int = 1280, head_dim: int = 80, num_attention_heads: int = 16, rms_norm_eps: float = 1e-06, quantiles: list[float] | tuple[float, ...] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9), attention_dropout: float | int = 0.0, initializer_range: float = 0.02, num_key_value_heads: int = 16, attention_bias: bool = False, output_quantile_len: int = 1024, decode_index: int = 5, use_bias: bool = False, activation: str = 'swish', use_continuous_quantile_head: bool = True, force_flip_invariance: bool = True, infer_is_positive: bool = True, max_position_embeddings: int = 16384, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm2_5/configuration_timesfm2_5.py#L30)

**Parámetros:**

patch_length (`int`, *opcional*, valor predeterminado 32) : La longitud de un parche en la secuencia de entrada.

context_length (`int`, *opcional*, valor predeterminado 16384) : La longitud del contexto de entrada.

horizon_length (`int`, *opcional*, valor predeterminado 128) : La longitud del horizonte de predicción.

num_hidden_layers (`int`, *opcional*, valor predeterminado `20`) : Número de capas ocultas en el decodificador del Transformer.

hidden_size (`int`, *opcional*, valor predeterminado `1280`) : Dimensión de las representaciones ocultas.

intermediate_size (`int`, *opcional*, valor predeterminado `1280`) : Dimensión de las representaciones de MLP.

head_dim (`int`, *opcional*, valor predeterminado `80`) : La dimensión de la cabeza de atención. Si es None, se establecerá en hidden_size // num_attention_heads

num_attention_heads (`int`, *opcional*, valor predeterminado `16`) : Número de cabezas de atención para cada capa de atención en el decodificador del Transformer.

rms_norm_eps (`float`, *opcional*, valor predeterminado `1e-06`) : El epsilon utilizado por las capas de normalización rms.

quantiles (`list[float]`, *opcional*, valor predeterminado `[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]`) : Los cuantiles a predecir.

attention_dropout (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : La proporción de dropout para las probabilidades de atención.

initializer_range (`float`, *opcional*, valor predeterminado `0.02`) : La desviación estándar de truncated_normal_initializer para inicializar todas las matrices de pesos.

num_key_value_heads (`int`, *opcional*, valor predeterminado `16`) : Este es el número de cabezas de key_value que se deben utilizar para implementar Grouped Query Attention. Si `num_key_value_heads=num_attention_heads`, el modelo utilizará Multi Head Attention (MHA); si `num_key_value_heads=1`, el modelo utilizará Multi Query Attention (MQA); en caso contrario, se utilizará GQA. Al convertir un checkpoint multi-head a un checkpoint GQA, cada cabeza de key y value del grupo debe construirse mediante el promedio (meanpooling) de todas las cabezas originales dentro de ese grupo. Para más detalles, consulte [este artículo](https://huggingface.co/papers/2305.13245). Si no se especifica, el valor predeterminado será `num_attention_heads`.

attention_bias (`bool`, *opcional*, valor predeterminado `False`) : Indica si se debe usar un sesgo en las capas de proyección de consulta, clave, valor y salida durante la autoatención.

output_quantile_len (`int`, *opcional*, valor predeterminado 1024) : Longitud de la dimensión de proyección de la salida del cuantil.

decode_index (`int`, *opcional*, valor predeterminado 5) : Índice en la dimensión de cuantiles utilizado para extraer la predicción puntual (mediana).

use_bias (`bool`, *opcional*, valor predeterminado `False`) : Si se debe usar sesgo en las capas lineales de MLP y transformer.

activation (`str`, *opcional*, valor predeterminado `swish`) : La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

use_continuous_quantile_head (`bool`, *opcional*, valor predeterminado `True`) : Si se debe usar la cabeza de cuantiles continuos para predicciones de cuantiles no mediana.

force_flip_invariance (`bool`, *opcional*, valor predeterminado `True`) : Si se aplica el promedio de invariancia por inversión durante la predicción.

infer_is_positive (`bool`, *opcional*, valor predeterminado `True`) : Si se deben limitar las predicciones a valores no negativos cuando el mínimo de la entrada es no negativo.

max_position_embeddings (`int`, *opcional*, valor predeterminado `16384`) : La longitud máxima de secuencia con la que se podría utilizar este modelo.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *opcional*) : Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor para `rope_theta` y, opcionalmente, parámetros utilizados para el escalado en caso de que desee usar RoPE con `max_position_embeddings` más largas.

Esta es la clase de configuración para almacenar la configuración de un TimesFm2_5Model. Se utiliza para instanciar un modelo Timesfm2 5 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 [google/timesfm-2.5-200m-transformers](https://huggingface.co/google/timesfm-2.5-200m-transformers)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

Ejemplo:

```python
>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

>>> configuration = TimesFm2_5Config()
>>> model = TimesFm2_5ModelForPrediction(configuration)
>>> configuration = model.config
```

## TimesFm2_5Model[[transformers.TimesFm2_5Model]]

#### transformers.TimesFm2_5Model[[transformers.TimesFm2_5Model]]

```python
transformers.TimesFm2_5Model(config: TimesFm2_5Config)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L457)

#### forward[[transformers.TimesFm2_5Model.forward]]

```python
forward(past_values: Tensor, past_values_padding: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L553)

**Parámetros:**

past_values (`torch.Tensor` de forma `(batch_size, sequence_length)`) : Valores pasados de la serie temporal utilizados como entrada del modelo.

past_values_padding (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara de relleno para la entrada. `1` indica pasos de tiempo rellenados (enmascarados), `0` indica valores válidos.

**Devuelve:** `TimesFm2_5Output` o `tuple(torch.Tensor)`

Un `TimesFm2_5Output` 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 ([TimesFm2_5Config](/docs/transformers/main/es/model_doc/timesfm2_5#transformers.TimesFm2_5Config)) y las entradas.

El método forward de [TimesFm2_5Model](/docs/transformers/main/es/model_doc/timesfm2_5#transformers.TimesFm2_5Model) 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 preprocesamiento y posprocesamiento, 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 modelo.
- **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 modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
- **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 tras el 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.
- **context_mu** (`torch.Tensor` de forma `(batch_size, num_patches)`) -- Medias móviles calculadas por parche de entrada durante la normalización.
- **context_sigma** (`torch.Tensor` de forma `(batch_size, num_patches)`) -- Desviaciones estándar móviles calculadas por parche de entrada durante la normalización.

## TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

#### transformers.TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

```python
transformers.TimesFm2_5ModelForPrediction(config: TimesFm2_5Config)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L639)

Modelo TimesFm2_5 para predicción de cuantiles y media.

#### forward[[transformers.TimesFm2_5ModelForPrediction.forward]]

```python
forward(past_values: collections.abc.Sequence[torch.Tensor], window_size: int | None = None, future_values: typing.Optional[torch.Tensor] = None, forecast_context_len: int | None = None, truncate_negative: bool | None = None, force_flip_invariance: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L727)

**Parámetros:**

past_values (`collections.abc.Sequence[torch.Tensor]`) : Valores pasados de la serie temporal que sirven como entrada al modelo. Cada tensor es una serie temporal unidimensional.

window_size (`int`, *opcional*) : Tamaño de la ventana de la descomposición en tendencia + residual. Si es `None`, no se aplica la descomposición.

future_values (`torch.Tensor`, *opcional*) : Valores futuros opcionales utilizados para calcular la pérdida.

forecast_context_len (`int`, *opcional*) : Longitud de contexto opcional que se usa durante la predicción.

truncate_negative (`bool`, *opcional*) : Si se deben limitar las salidas a valores no negativos. Si es `None`, el valor predeterminado es `config.infer_is_positive`.

force_flip_invariance (`bool`, *opcional*) : Si se aplica la combinación de invaria a la inversión. Si es `None`, el valor predeterminado es `config.force_flip_invariance`.

**Devuelve:** `TimesFm2_5OutputForPrediction` o `tuple(torch.Tensor)`

Un `TimesFm2_5OutputForPrediction` 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 ([TimesFm2_5Config](/docs/transformers/main/es/model_doc/timesfm2_5#transformers.TimesFm2_5Config)) y las entradas.

El método forward de [TimesFm2_5ModelForPrediction](/docs/transformers/main/es/model_doc/timesfm2_5#transformers.TimesFm2_5ModelForPrediction) 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 preprocesamiento y posprocesamiento, 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 modelo.
- **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 modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
- **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 tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
- **mean_predictions** (`torch.Tensor` de forma `(batch_size, horizon_length)`) -- Predicciones deterministas tras la desnormalización.
- **full_predictions** (`torch.Tensor` de forma `(batch_size, horizon_length, quantiles)`) -- Predicciones de cuantiles que incluyen la mediana tras la desnormalización.
- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, se devuelve cuando se proporciona `future_values`) -- Pérdida de entrenamiento que combina las pérdidas MSE y de cuantiles cuando se proporcionan objetivos.