# TimesFM

## Genel Bakış

TimesFM (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. Bu model, yalnızca decoder (çözücü) mimarisine sahiptir; girdi olarak zaman serisi verisinin örtüşmeyen yamalarını (patch) kullanır ve otoregresif bir şekilde belirli bir çıktı yaması uzunluğunda tahmin üretir.

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ışlı (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, büyük bir zaman serisi korpusu üzerinde yamalı-dekoder (patched-decoder) tarzı bir dikkat (attention) modelinin ön eğitimi (pretraining) üzerine kuruludur ve farklı tahmin geçmişi uzunlukları, tahmin uzunlukları ve zaman granülerlikleri arasında iyi çalışabilir.*

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

Modeli kullanmak için:

```python
import numpy as np
import torch

from transformers import TimesFmModelForPrediction

model = TimesFmModelForPrediction.from_pretrained(
    "google/timesfm-2.0-500m-pytorch",
    attn_implementation="sdpa",
    device_map="auto"
)

 # Create dummy inputs
forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]

# Convert inputs to sequence of tensors
forecast_input_tensor = [
    torch.tensor(ts).to(model.device)
    for ts in forecast_input
]
frequency_input_tensor = torch.tensor(frequency_input, dtype=torch.long).to(model.device)

# Get predictions from the pre-trained model
with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, freq=frequency_input_tensor, return_dict=True)
    point_forecast_conv = outputs.mean_predictions.float().cpu().numpy()
    quantile_forecast_conv = outputs.full_predictions.float().cpu().numpy()
```

## TimesFmConfig[[transformers.TimesFmConfig]]

#### transformers.TimesFmConfig[[transformers.TimesFmConfig]]

```python
transformers.TimesFmConfig(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 = 512, horizon_length: int = 128, freq_size: int = 3, num_hidden_layers: int = 50, hidden_size: int = 1280, intermediate_size: int = 1280, head_dim: int = 80, num_attention_heads: int = 16, tolerance: float = 1e-06, 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), pad_val: float = 1123581321.0, attention_dropout: float | int = 0.0, use_positional_embedding: bool = False, initializer_range: float = 0.02, min_timescale: int = 1, max_timescale: int = 10000)
```

[Kaynak](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm/configuration_timesfm.py#L24)

**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 512) : Girdi bağlamının uzunluğu.

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

freq_size (`int`, *isteğe bağlı*, varsayılan 3) : Frekans gömme sayısı.

num_hidden_layers (`int`, *isteğe bağlı*, varsayılan `50`) : 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ı.

tolerance (`float`, *isteğe bağlı*, varsayılan 1e-06) : Kuantil kaybı için tolerans.

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.

pad_val (`float`, *isteğe bağlı*, varsayılan 1123581321.0) : Tahminleri doldurmak için kullanılan değer.

attention_dropout (`float`, *opsiyonel*, varsayılan 0.0) : Dikkat skorları için dropout olasılığı.

use_positional_embedding (`bool`, *isteğe bağlı*, varsayılan `False`) : Konumsal gömme eklenip eklenmeyeceğini belirtir.

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

min_timescale (`int`, *isteğe bağlı*, varsayılan 1) : Geometrik konumsal dizinin başlangıcı. Eklenen sinyalin periyodikliğini belirler.

max_timescale (`int`, *isteğe bağlı*, varsayılan 10000) : Geometrik konumsal dizinin sonu. Eklenen sinyalin frekansını belirler.

Bu, bir TimesFmModel yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Timesfm modelini örneklemek ve model mimarisini tanımlamak için kullanılır. Varsayılan değerlerle bir yapılandırma örneği oluşturmak, [google/timesfm-2.0-500m-pytorch](https://huggingface.co/google/timesfm-2.0-500m-pytorch) modelinin yapılandırmasına benzer bir yapılandırma elde etmenizi sağlar.

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.

## TimesFmModel[[transformers.TimesFmModel]]

#### transformers.TimesFmModel[[transformers.TimesFmModel]]

```python
transformers.TimesFmModel(config: TimesFmConfig)
```

[Kaynak](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm/modeling_timesfm.py#L332)

**Parametreler:**

config ([TimesFmConfig](/docs/transformers/v5.23.0/tr/model_doc/timesfm#transformers.TimesFmConfig)) : Modelin tüm parametrelerini içeren model yapılandırma sınıfı. Bir yapılandırma dosyasıyla başlatmak, modelle ilişkili ağırlıkları yüklemez, yalnızca yapılandırmayı yükler. Model ağırlıklarını yüklemek için [from_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.PreTrainedModel.from_pretrained) yöntemine göz atın.

Üzerinde herhangi bir özel head olmadan ham hidden-states üreten çıplak Timesfm Model.

Bu model [PreTrainedModel](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.PreTrainedModel) sınıfından devralır. Kütüphanenin tüm modelleri için uyguladığı genel yöntemler (indirme veya kaydetme, giriş gömme boyutlarını yeniden ayarlama, başları budama vb.) için üst sınıf belgelendirmesine bakın.

Bu model aynı zamanda bir PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) alt sınıfıdır. Bunu standart bir PyTorch Module olarak kullanın ve genel kullanım ve davranışla ilgili tüm konular için PyTorch dokümantasyonuna başvurun.

#### forward[[transformers.TimesFmModel.forward]]

```python
forward(past_values: Tensor, past_values_padding: LongTensor, freq: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Kaynak](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm/modeling_timesfm.py#L365)

**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)`) : Zaman serisinin dolgu göstergesi.

freq (`torch.LongTensor`, şekli `(batch_size,)`) : Zaman serisi verisi için frekans indeksleri.

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

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

[TimesFmModel](/docs/transformers/v5.23.0/tr/model_doc/timesfm#transformers.TimesFmModel) 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, )`) -- Zaman serisi girdilerinin ortalaması.
- **scale** (`torch.Tensor`, şekli `(batch_size,)`) -- Zaman serisi girdilerinin ölçeği.

## TimesFmModelForPrediction[[transformers.TimesFmModelForPrediction]]

#### transformers.TimesFmModelForPrediction[[transformers.TimesFmModelForPrediction]]

```python
transformers.TimesFmModelForPrediction(config: TimesFmConfig)
```

[Kaynak](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm/modeling_timesfm.py#L566)

Quantile ve ortalama tahmini için TimesFM modeli.

#### forward[[transformers.TimesFmModelForPrediction.forward]]

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

[Kaynak](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm/modeling_timesfm.py#L648)

**Parametreler:**

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

freq (`torch.LongTensor`, şekli `(batch_size,)`) : Zaman serisi verisi için frekans indeksleri.

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

future_values (`torch.Tensor`, *isteğe bağlı*) : Kayıp hesabı için kullanılacak isteğe bağlı gelecekteki zaman serisi değerleri.

forecast_context_len (`int`, *isteğe bağlı*) : İsteğe bağlı maksimum bağlam uzunluğu.

return_forecast_on_context (`bool`, *isteğe bağlı*) : Mevcutsa, yani ilk giriş yamasından sonra, bağlamda tahmini döndürmek için True.

truncate_negative (`bool`, *isteğe bağlı*) : Bağlamlardan herhangi birinin negatif olmayan değerleri varsa yalnızca negatif olmayan değerlere kısaltır, aksi takdirde hiçbir işlem yapmaz.

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

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

[TimesFmModelForPrediction](/docs/transformers/v5.23.0/tr/model_doc/timesfm#transformers.TimesFmModelForPrediction) 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, sequence_length)`) -- Zaman serisinin ortalama tahminleri.
- **full_predictions** (`torch.Tensor`, şekli `(batch_size, sequence_length)`) -- Ortalama ve kantilleri içeren zaman serisinin tam tahminleri.
- **loss** (`torch.Tensor`, şekli `(1,)`, *opsiyonel*, `future_values` sağlandığında döndürülür) -- TimesFM modelinin kaybı.

Örnek:

```python
>>> from transformers import TimesFmModelForPrediction

>>> model = TimesFmModelForPrediction.from_pretrained("google/timesfm-2.0-500m-pytorch")

>>> forecast_input = [torch.linspace(0, 20, 100).sin(), torch.linspace(0, 20, 200).sin(), torch.linspace(0, 20, 400).sin()]
>>> frequency_input = torch.tensor([0, 1, 2], dtype=torch.long)

>>> # Generate
>>> with torch.no_grad():
>>>     outputs = model(past_values=forecast_input, freq=frequency_input, return_dict=True)
>>>     point_forecast_conv = outputs.mean_predictions
>>>     quantile_forecast_conv = outputs.full_predictions
```

