# TimesFM 2.5

## Genel Bakış

TimesFM 2.5 (Time Series Foundation Model), Abhimanyu Das, Weihao Kong, Rajat Sen ve Yichen Zhou tarafından [A decoder-only foundation model for time-series forecasting](https://huggingface.co/papers/2310.10688) makalesinde önerilen, önceden eğitilmiş bir zaman serisi temel modelidir. Model, orijinal TimesFM mimarisine dayanmakta olup dönerli dikkat (rotary attention), QK normalizasyonu, boyut başına dikkat ölçekleme ve sürekli kantil tahmini özelliklerini içermektedir.

Makalenin özeti aşağıdaki gibidir:

*Doğal Dil İşleme (NLP) alanında büyük dil modellerindeki son gelişmelerden ilham alarak, çeşitli açık veri setlerinde kutudan çıktığı gibi (out-of-the-box) sıfır atış (zero-shot) performansı, her bir veri seti için en son (state-of-the-art) denetimli tahmin modellerinin doğruluğuna yaklaşan bir zaman serisi temel modeli tasarladık. Modelimiz, hem gerçek dünya hem de sentetik veri setlerinden oluşan büyük bir zaman serisi korpusu kullanılarak, girdi yamalaması (input patching) ile bir decoder tarzı dikkat (attention) modelinin ön eğitimi (pretraining) üzerine kuruludur. Daha önce görülmemiş çeşitli tahmin veri setleri üzerinde yapılan deneyler, modelin farklı alanlarda, tahmin ufuklarında ve zaman granülerliklerinde doğru sıfır atış tahminleri üretebileceğini göstermektedir.*

Bu model [kashif](https://huggingface.co/kashif) tarafından katkıda bulunmuştur. Orijinal kod [burada](https://github.com/google-research/timesfm) bulunabilir.

Kontrol noktasını [`google/timesfm-2.5-200m-transformers`](https://huggingface.co/google/timesfm-2.5-200m-transformers) adresinde bulabilirsiniz.

## Kullanım örneği

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

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

**Parametreler:**

patch_length (`int`, *isteğe bağlı*, varsayılan 32) : Girdi dizisinde bir yamanın (patch) uzunluğu.

context_length (`int`, *isteğe bağlı*, varsayılan 16384) : Girdi bağlamının uzunluğu.

horizon_length (`int`, *isteğe bağlı*, varsayılan 128) : Tahmin ufku uzunluğu.

num_hidden_layers (`int`, *isteğe bağlı*, varsayılan `20`) : Transformer decoder'ındaki gizli katman sayısı.

hidden_size (`int`, *isteğe bağlı*, varsayılan `1280`) : Gizli temsillerin boyutu.

intermediate_size (`int`, *isteğe bağlı*, varsayılan `1280`) : MLP temsil boyutu.

head_dim (`int`, *isteğe bağlı*, varsayılan `80`) : Dikkat başı boyutu. None ise, hidden_size // num_attention_heads değerine ayarlanır.

num_attention_heads (`int`, *isteğe bağlı*, varsayılan `16`) : Transformer decoder'ındaki her dikkat katmanı için dikkat başı sayısı.

rms_norm_eps (`float`, *opsiyonel*, varsayılan `1e-06`) : rms normalizasyon katmanları tarafından kullanılan epsilon.

quantiles (`list[float]`, *isteğe bağlı*, varsayılan `[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]`) : Tahmin edilecek kantiller.

attention_dropout (`Union[float, int]`, *isteğe bağlı*, varsayılan `0.0`) : Dikkat olasılıkları için dropout oranı.

initializer_range (`float`, *opsiyonel*, varsayılan `0.02`) : Tüm ağırlık matrislerini başlatmak için kullanılan truncated_normal_initializer'ın standart sapması.

num_key_value_heads (`int`, *isteğe bağlı*, varsayılan `16`) : Grouped Query Attention'ı uygulamak için kullanılması gereken key_value başlarının sayısıdır. `num_key_value_heads=num_attention_heads` ise model Multi Head Attention (MHA) kullanır, `num_key_value_heads=1` ise model Multi Query Attention (MQA) kullanır, aksi halde GQA kullanılır. Çok başlı bir checkpoint'i GQA checkpoint'ine dönüştürürken, her grup key ve value başı, o gruptaki tüm orijinal başların ortalama havuzlanması (meanpooling) ile oluşturulmalıdır. Daha fazla ayrıntı için [bu makaleye](https://huggingface.co/papers/2305.13245) göz atın. Belirtilmezse, varsayılan olarak `num_attention_heads` kullanılır.

attention_bias (`bool`, *isteğe bağlı*, varsayılan `False`) : Kendi kendine dikkat (self-attention) sırasında sorgu, anahtar, değer ve çıktı projeksiyon katmanlarında sapma (bias) kullanılıp kullanılmayacağı.

output_quantile_len (`int`, *isteğe bağlı*, varsayılan 1024) : Kuantil çıktı projeksiyon boyutunun uzunluğu.

decode_index (`int`, *opsiyonel*, varsayılan 5) : Nokta (medyan) tahminini çıkarmak için kullanılan kantil boyutundaki indeks.

use_bias (`bool`, *isteğe bağlı*, varsayılan `False`) : MLP ve transformer doğrusal katmanlarında sapma (bias) kullanılıp kullanılmayacağı.

activation (`str`, *isteğe bağlı*, varsayılan `swish`) : Dekoderdeki doğrusal olmayan aktivasyon fonksiyonu (fonksiyon veya dize). Örneğin, `"gelu"`, `"relu"`, `"silu"` vb.

use_continuous_quantile_head (`bool`, *isteğe bağlı*, varsayılan `True`) : Medyan olmayan kantil tahminleri için sürekli kantil başlığının kullanılıp kullanılmayacağı.

force_flip_invariance (`bool`, *isteğe bağlı*, varsayılan `True`) : Tahmin sırasında flip-değişmez ortalama uygulanıp uygulanmayacağı.

infer_is_positive (`bool`, *isteğe bağlı*, varsayılan `True`) : Girdi minimumu negatif değilse, tahminlerin negatif olmayan değerlere sabitlenip sabitlenmeyeceğini belirtir.

max_position_embeddings (`int`, *isteğe bağlı*, varsayılan `16384`) : Bu modelin kullanılabileceği maksimum dizi uzunluğu.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *isteğe bağlı*) : RoPE gömme yapılandırma parametrelerini içeren sözlük. Sözlük, `rope_theta` için bir değer içermeli ve daha uzun `max_position_embeddings` ile RoPE kullanmak istiyorsanız ölçekleme için kullanılan parametreleri isteğe bağlı olarak içermelidir.

Bu, bir TimesFm2_5Model yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Timesfm2 5 modelinin örneklenmesi ve model mimarisinin tanımlanması için kullanılır. Varsayılanlarla bir yapılandırma örneği oluşturmak, [google/timesfm-2.5-200m-transformers](https://huggingface.co/google/timesfm-2.5-200m-transformers) ile benzer bir yapılandırmaya yol açar.

Yapılandırma nesneleri [PreTrainedConfig](/docs/transformers/v5.23.0/tr/main_classes/configuration#transformers.PreTrainedConfig) sınıfından türetilir ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için [PreTrainedConfig](/docs/transformers/v5.23.0/tr/main_classes/configuration#transformers.PreTrainedConfig) belgesini okuyun.

Örnek:

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

[Kaynak](https://github.com/huggingface/transformers/blob/v5.23.0/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'>)
```

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

**Parametreler:**

past_values (`torch.Tensor`, şekli `(batch_size, sequence_length)`) : Modelin girdisi olarak kullanılan zaman serisinin geçmiş değerleri.

past_values_padding (`torch.LongTensor`, şekli `(batch_size, sequence_length)`, *isteğe bağlı*) : Girdi için dolgu maskesi. `1` dolgulu (maskelenmiş) zaman adımlarını, `0` geçerli değerleri belirtir.

**Dönüş:** `TimesFm2_5Output` veya `tuple(torch.Tensor)`

`TimesFm2_5Output` veya bir `torch.Tensor` demeti (eğer `return_dict=False` geçirildiyse veya `config.return_dict=False` ise), yapılandırmaya ([TimesFm2_5Config](/docs/transformers/v5.23.0/tr/model_doc/timesfm2_5#transformers.TimesFm2_5Config)) ve girdilere bağlı olarak çeşitli öğelerden oluşur.

[TimesFm2_5Model](/docs/transformers/v5.23.0/tr/model_doc/timesfm2_5#transformers.TimesFm2_5Model) forward metodu, `__call__` özel metodunu geçersiz kılar.

İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine `Module` örneğini çağırmak gerekir; çünkü ilki ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.

- **last_hidden_state** (`torch.Tensor`, şekli `(batch_size, sequence_length, hidden_size)`) -- Modelin son katmanının çıktısındaki gizli durumlar dizisi.
- **hidden_states** (`tuple(torch.Tensor)`, *isteğe bağlı*, `output_hidden_states=True` geçirildiğinde veya `config.output_hidden_states=True` olduğunda döndürülür) -- `torch.Tensor` (gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için bir tane) içeren, `(batch_size, sequence_length, hidden_size)` biçiminde bir demet.

  Her katmanın çıktısında modelin gizli durumları ve isteğe bağlı başlangıç gömme çıktıları.
- **attentions** (`tuple(torch.Tensor)`, *isteğe bağlı*, `output_attentions=True` geçirildiğinde veya `config.output_attentions=True` olduğunda döndürülür) -- `torch.Tensor` (her katman için bir tane) içeren bir tuple, şekli `(batch_size, num_heads, sequence_length, sequence_length)`.

  Dikkat softmax'ı sonrası dikkat ağırlıkları, öz-dikkat kafalarında ağırlıklı ortalamanın hesaplanmasında kullanılır.
- **loc** (`torch.Tensor`, şekli `(batch_size,)` veya `(batch_size, input_size)`, *isteğe bağlı*) -- Modelin aynı büyüklükte girdiler almasını sağlamak için her zaman serisinin bağlam penceresindeki değerleri kaydıran ve ardından orijinal büyüklüğe geri kaydırmak için kullanılan değer.
- **scale** (`torch.Tensor`, şekli `(batch_size,)` veya `(batch_size, input_size)`, *isteğe bağlı*) -- Modelin aynı büyüklükte girdiler almasını sağlamak için her zaman serisinin bağlam penceresinin ölçeklendirme değerleri; ardından orijinal büyüklüğe geri ölçeklendirmede kullanılır.
- **context_mu** (`torch.Tensor`, şekli `(batch_size, num_patches)`) -- Normalizasyon sırasında her giriş yaması için hesaplanan kayan ortalamalar.
- **context_sigma** (`torch.Tensor`, şekli `(batch_size, num_patches)`) -- Normalizasyon sırasında her giriş yaması için hesaplanan hareketli standart sapmalar.

## TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

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

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

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

Quantile ve ortalama tahmini için TimesFm2_5 modeli.

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

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

**Parametreler:**

past_values (`collections.abc.Sequence[torch.Tensor]`) : Model girdisi olarak kullanılan zaman serisinin geçmiş değerleri. Her tensör bir boyutlu bir zaman serisidir.

window_size (`int`, *opsiyonel*) : Trend + artık ayrıştırmasının pencere boyutu. `None` ise ayrıştırma uygulanmaz.

future_values (`torch.Tensor`, *isteğe bağlı*) : Kaybı hesaplamak için kullanılan isteğe bağlı gelecek değerler.

forecast_context_len (`int`, *isteğe bağlı*) : Tahmin sırasında kullanılan isteğe bağlı bağlam uzunluğu geçersiz kılma değeri.

truncate_negative (`bool`, *isteğe bağlı*) : Çıktıların negatif olmayan değerlere sabitlenip sabitlenmeyeceğini belirtir. `None` ise, varsayılan olarak `config.infer_is_positive` kullanılır.

force_flip_invariance (`bool`, *isteğe bağlı*) : Flip-invariance kombinasyonunun uygulanıp uygulanmayacağını belirtir. `None` ise, varsayılan olarak `config.force_flip_invariance` kullanılır.

**Dönüş:** `TimesFm2_5OutputForPrediction` veya `tuple(torch.Tensor)`

`TimesFm2_5OutputForPrediction` veya bir `torch.Tensor` demeti (eğer `return_dict=False` geçirildiyse veya `config.return_dict=False` ise), yapılandırmaya ([TimesFm2_5Config](/docs/transformers/v5.23.0/tr/model_doc/timesfm2_5#transformers.TimesFm2_5Config)) ve girdilere bağlı olarak çeşitli öğelerden oluşur.

[TimesFm2_5ModelForPrediction](/docs/transformers/v5.23.0/tr/model_doc/timesfm2_5#transformers.TimesFm2_5ModelForPrediction) forward metodu, `__call__` özel metodunu geçersiz kılar.

İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine `Module` örneğini çağırmak gerekir; çünkü ilki ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.

- **last_hidden_state** (`torch.Tensor`, şekli `(batch_size, sequence_length, hidden_size)`) -- Modelin son katmanının çıktısındaki gizli durumlar dizisi.
- **hidden_states** (`tuple(torch.Tensor)`, *isteğe bağlı*, `output_hidden_states=True` geçirildiğinde veya `config.output_hidden_states=True` olduğunda döndürülür) -- `torch.Tensor` (gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için bir tane) içeren, `(batch_size, sequence_length, hidden_size)` biçiminde bir demet.

  Her katmanın çıktısında modelin gizli durumları ve isteğe bağlı başlangıç gömme çıktıları.
- **attentions** (`tuple(torch.Tensor)`, *isteğe bağlı*, `output_attentions=True` geçirildiğinde veya `config.output_attentions=True` olduğunda döndürülür) -- `torch.Tensor` (her katman için bir tane) içeren bir tuple, şekli `(batch_size, num_heads, sequence_length, sequence_length)`.

  Dikkat softmax'ı sonrası dikkat ağırlıkları, öz-dikkat kafalarında ağırlıklı ortalamanın hesaplanmasında kullanılır.
- **mean_predictions** (`torch.Tensor`, şekli `(batch_size, horizon_length)`) -- Normalizasyon kaldırıldıktan sonraki deterministik tahminler.
- **full_predictions** (`torch.Tensor`, şekli `(batch_size, horizon_length, quantiles)`) -- Normalizasyon kaldırıldıktan sonra medyanı da içeren kantil tahminleri.
- **loss** (`torch.Tensor`, şekli `(1,)`, *opsiyonel*, `future_values` sağlandığında döndürülür) -- Hedefler sağlandığında MSE ve quantile kayıplarını birleştiren eğitim kaybı.

