# TimesFM 2.5

## Visão geral

TimesFM 2.5 (Time Series Foundation Model) é um modelo de fundação pré-treinado para séries temporais proposto em [A decoder-only foundation model for time-series forecasting](https://huggingface.co/papers/2310.10688) por Abhimanyu Das, Weihao Kong, Rajat Sen e Yichen Zhou. Ele se baseia na arquitetura original do TimesFM, com atenção rotativa, normalização QK, escalonamento de atenção por dimensão e previsão contínua de quantis.

O resumo do artigo é o seguinte:

*Inspirados pelos avanços recentes em modelos de linguagem de grande escala para Processamento de Linguagem Natural (NLP), projetamos um modelo de fundação para séries temporais voltado à previsão, cujo desempenho zero-shot pronto para uso em uma variedade de conjuntos de dados públicos se aproxima da precisão dos modelos de previsão supervisionados de estado da arte para cada conjunto de dados individual. Nosso modelo é baseado no pré-treinamento de um modelo de atenção em estilo decodificador com patching de entrada, utilizando um grande corpus de séries temporais que inclui conjuntos de dados tanto do mundo real quanto sintéticos. Experimentos em um conjunto diversificado de conjuntos de dados de previsão anteriormente não vistos sugerem que o modelo pode gerar previsões zero-shot precisas em diferentes domínios, horizontes de previsão e granularidades temporais.*

Este modelo foi contribuído por [kashif](https://huggingface.co/kashif). O código original pode ser encontrado [aqui](https://github.com/google-research/timesfm).

Você pode encontrar o checkpoint em [`google/timesfm-2.5-200m-transformers`](https://huggingface.co/google/timesfm-2.5-200m-transformers).

## Exemplo 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)
```

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

**Parâmetros:**

patch_length (`int`, *opcional*, padrão 32) : O comprimento de um patch na sequência de entrada.

context_length (`int`, *opcional*, padrão 16384) : O comprimento do contexto de entrada.

horizon_length (`int`, *opcional*, padrão 128) : O comprimento do horizonte de previsão.

num_hidden_layers (`int`, *opcional*, padrão `20`) : Número de camadas ocultas no decodificador do Transformer.

hidden_size (`int`, *opcional*, padrão `1280`) : Dimensão das representações ocultas.

intermediate_size (`int`, *opcional*, padrão `1280`) : Dimensão das representações do MLP.

head_dim (`int`, *opcional*, padrão `80`) : A dimensão da cabeça de atenção. Se for None, o padrão será hidden_size // num_attention_heads

num_attention_heads (`int`, *opcional*, padrão `16`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

rms_norm_eps (`float`, *opcional*, padrão `1e-06`) : O epsilon usado pelas camadas de normalização rms.

quantiles (`list[float]`, *opcional*, padrão `[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]`) : Os quantis a prever.

attention_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

num_key_value_heads (`int`, *opcional*, padrão `16`) : Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se `num_key_value_heads=num_attention_heads`, o modelo usará Multi Head Attention (MHA); se `num_key_value_heads=1`, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada cabeça de chave e valor do grupo deve ser construída pela média (meanpooling) de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte [este artigo](https://huggingface.co/papers/2305.13245). Se não for especificado, o valor padrão será `num_attention_heads`.

attention_bias (`bool`, *opcional*, padrão `False`) : Se deve usar um viés nas camadas de projeção de query, key, value e output durante a autoatenção.

output_quantile_len (`int`, *opcional*, padrão 1024) : Comprimento da dimensão de projeção da saída do quantil.

decode_index (`int`, *opcional*, padrão 5) : Índice na dimensão de quantil usado para extrair a previsão de ponto (mediana).

use_bias (`bool`, *opcional*, padrão `False`) : Se deve usar viés nas camadas lineares do MLP e do transformer.

activation (`str`, *opcional*, padrão `swish`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

use_continuous_quantile_head (`bool`, *opcional*, padrão `True`) : Se deve usar a cabeça de quantil contínuo para previsões de quantis não mediana.

force_flip_invariance (`bool`, *opcional*, padrão `True`) : Se deve aplicar a média de invariância por inversão durante a previsão.

infer_is_positive (`bool`, *opcional*, padrão `True`) : Se deve limitar as previsões a valores não negativos quando o mínimo da entrada for não negativo.

max_position_embeddings (`int`, *opcional*, padrão `16384`) : O comprimento máximo de sequência com o qual este modelo pode ser usado.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *opcional*) : Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para `rope_theta` e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com `max_position_embeddings` maiores.

Esta é a classe de configuração para armazenar a configuração de um TimesFm2_5Model. Ela é usada para instanciar um modelo Timesfm2 5 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [google/timesfm-2.5-200m-transformers](https://huggingface.co/google/timesfm-2.5-200m-transformers)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

```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)
```

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

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

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

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

**Parâmetros:**

past_values (`torch.Tensor` de forma `(batch_size, sequence_length)`) : Valores passados da série temporal usados como entrada para o modelo.

past_values_padding (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara de preenchimento para a entrada. `1` indica passos de tempo preenchidos (mascarados), `0` indica valores válidos.

**Retorna:** `TimesFm2_5Output` ou `tuple(torch.Tensor)`

Um `TimesFm2_5Output` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([TimesFm2_5Config](/docs/transformers/main/pt/model_doc/timesfm2_5#transformers.TimesFm2_5Config)) e das entradas.

O método forward do [TimesFm2_5Model](/docs/transformers/main/pt/model_doc/timesfm2_5#transformers.TimesFm2_5Model) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **loc** (`torch.Tensor` de forma `(batch_size,)` ou `(batch_size, input_size)`, *opcional*) -- Desloca os valores da janela de contexto de cada série temporal, o que é usado para fornecer ao modelo entradas da mesma magnitude e, em seguida, para desfazer o deslocamento e voltar à magnitude original.
- **scale** (`torch.Tensor` de forma `(batch_size,)` ou `(batch_size, input_size)`, *opcional*) -- Valores de escala da janela de contexto de cada série temporal, usados para fornecer ao modelo entradas da mesma magnitude e, em seguida, para reescalar de volta à magnitude original.
- **context_mu** (`torch.Tensor` de forma `(batch_size, num_patches)`) -- Médias móveis calculadas por patch de entrada durante a normalização.
- **context_sigma** (`torch.Tensor` de forma `(batch_size, num_patches)`) -- Desvios padrão em execução calculados por patch de entrada durante a normalização.

## TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

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

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

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

Modelo TimesFm2_5 para previsão de quantis e média.

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

```python
forward(past_values: Sequence, 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'>)
```

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

**Parâmetros:**

past_values (`collections.abc.Sequence[torch.Tensor]`) : Valores passados da série temporal que servem como entrada para o modelo. Cada tensor é uma série temporal unidimensional.

window_size (`int`, *opcional*) : Tamanho da janela da decomposição em tendência + resíduo. Se `None`, a decomposição não é aplicada.

future_values (`torch.Tensor`, *opcional*) : Valores futuros opcionais usados para calcular a perda.

forecast_context_len (`int`, *opcional*) : Substituição opcional do comprimento do contexto usada durante a previsão.

truncate_negative (`bool`, *opcional*) : Se deve limitar as saídas a valores não negativos. Se `None`, o padrão é `config.infer_is_positive`.

force_flip_invariance (`bool`, *opcional*) : Se deve aplicar a combinação de invariância por inversão. Se `None`, o padrão é `config.force_flip_invariance`.

**Retorna:** `TimesFm2_5OutputForPrediction` ou `tuple(torch.Tensor)`

Um `TimesFm2_5OutputForPrediction` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([TimesFm2_5Config](/docs/transformers/main/pt/model_doc/timesfm2_5#transformers.TimesFm2_5Config)) e das entradas.

O método forward do [TimesFm2_5ModelForPrediction](/docs/transformers/main/pt/model_doc/timesfm2_5#transformers.TimesFm2_5ModelForPrediction) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **mean_predictions** (`torch.Tensor` de forma `(batch_size, horizon_length)`) -- Previsões determinísticas após a desnornalização.
- **full_predictions** (`torch.Tensor` de forma `(batch_size, horizon_length, quantiles)`) -- Previsões de quantis incluindo a mediana após a desnornalização.
- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `future_values` é fornecido) -- Perda de treinamento que combina perdas de MSE e quantil quando os alvos são fornecidos.