Bu model 2023-10-14 tarihinde HF papers'ta yayımlandı ve 2026-02-27 tarihinde Hugging Face Transformers'a katkıda bulunuldu.

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 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 tarafından katkıda bulunmuştur. Orijinal kod burada bulunabilir.

Kontrol noktasını google/timesfm-2.5-200m-transformers adresinde bulabilirsiniz.

Kullanım örneği

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

sınıf transformers.TimesFm2_5Config

< 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 = 0is_encoder_decoder: bool = Falseid2label: 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 = Nonepatch_length: int = 32context_length: int = 16384horizon_length: int = 128num_hidden_layers: int = 20hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16rms_norm_eps: float = 1e-06quantiles: 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.0initializer_range: float = 0.02num_key_value_heads: int = 16attention_bias: bool = Falseoutput_quantile_len: int = 1024decode_index: int = 5use_bias: bool = Falseactivation: str = 'swish'use_continuous_quantile_head: bool = Trueforce_flip_invariance: bool = Trueinfer_is_positive: bool = Truemax_position_embeddings: int = 16384rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )

Parametreler

patch_length (int, isteğe bağlı, varsayılan 32) — Girdi dizisindeki bir yamanın 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 çözücüdeki 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 temsillerinin boyutu.
head_dim (int, isteğe bağlı, varsayılan 80) — Dikkat başı boyutu. None ise, varsayılan olarak hidden_size // num_attention_heads değerini alı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, isteğe bağlı, 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 çeyrekler.
attention_dropout (Union[float, int], isteğe bağlı, varsayılan 0.0) — Dikkat olasılıkları için dropout oranı.
initializer_range (float, isteğe bağlı, 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) — Bu, Grouped Query Attention uygulamasında kullanılacak 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 göz atın. Belirtilmezse, varsayılan olarak num_attention_heads kullanılır.
attention_bias (bool, isteğe bağlı, varsayılan False) — Öz-dikkat sırasında sorgu, anahtar, değer ve çıktı projeksiyon katmanlarında önyargı (bias) kullanılıp kullanılmayacağı.
output_quantile_len (int, isteğe bağlı, varsayılan 1024) — Quantile çıktı projeksiyon boyutunun uzunluğu.
decode_index (int, opsiyonel, varsayılan 5) — Nokta (medyan) tahminini çıkarmak için kantil boyutunda kullanılan indeks.
use_bias (bool, isteğe bağlı, varsayılan False) — MLP ve transformer doğrusal katmanlarında bias kullanılıp kullanılmayacağı.
activation (str, opsiyonel, varsayılan swish) — Çözücüdeki 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 dışı quantile tahminleri için sürekli quantile head'inin kullanılıp kullanılmayacağını belirtir.
force_flip_invariance (bool, isteğe bağlı, varsayılan True) — Tahmin sırasında flip-değişmezlik ortalama uygulamasının yapılıp yapılmayacağı.
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 en uzun 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 ve daha uzun max_position_embeddings ile RoPE kullanmak istiyorsanız ölçekleme için kullanılan isteğe bağlı parametreleri 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 örneklenmesinde, model mimarisini tanımlamak için kullanılır. Varsayılan değerlerle bir yapılandırma örneklendiğinde, google/timesfm-2.5-200m-transformers modelinin yapılandırmasına benzer bir yapılandırma elde edilir.

Yapılandırma nesneleri PreTrainedConfig sınıfından devralır ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için PreTrainedConfig belgesini okuyun.

Örnek:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

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

TimesFm2_5Model

sınıf transformers.TimesFm2_5Model

< source >

( config: TimesFm2_5Config )

forward

< source >

( past_values: Tensorpast_values_padding: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5Output or tuple(torch.Tensor)

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 dolgu (maskelenmiş) zaman adımlarını, 0 geçerli değerleri belirtir.

Dönüş değeri

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) ve girdilere bağlı olarak çeşitli öğelerden oluşur.

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ü önceki, ö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 (modelin bir gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için birer 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 (katman başına bir tane) içeren bir tuple, şekli (batch_size, num_heads, sequence_length, sequence_length).

Dikkat softmax'ı sonrası dikkat ağırlıkları, öz-dikkat başlıkları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 kullanılan her zaman serisinin bağlam penceresindeki değerleri kaydırır ve ardından değerleri orijinal büyüklüğe geri kaydırır.
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 penceresindeki değerlerin ölçeklenmesinde kullanılan ve ardından orijinal büyüklüğe geri ölçeklenmek için kullanılan değerler.
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

sınıf transformers.TimesFm2_5ModelForPrediction

< source >

( config: TimesFm2_5Config )

Quantile ve ortalama tahmini için TimesFm2_5 modeli.

forward

< source >

( past_values: collections.abc.Sequence[torch.Tensor]window_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonetruncate_negative: bool | None = Noneforce_flip_invariance: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5OutputForPrediction or tuple(torch.Tensor)

Parametreler

past_values (collections.abc.Sequence[torch.Tensor]) — Modelin girdisi olarak kullanılan zaman serisinin geçmiş değerleri. Her tensör bir boyutlu bir zaman serisidir.
window_size (int, isteğe bağlı) — Trend + artık ayrıştırmasının pencere boyutu. None ise ayrıştırma uygulanmaz.
future_values (torch.Tensor, isteğe bağlı) — Kayıp (loss) hesaplamak için kullanılan isteğe bağlı gelecek değerleri.
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ğerlerle sınırlandırılıp sınırlandırılmayacağını 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üş değeri

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ırma (TimesFm2_5Config) ve girdilere bağlı olarak çeşitli öğelerden oluşur.

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ü önceki, ö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 (modelin bir gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için birer 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 (katman başına bir tane) içeren bir tuple, şekli (batch_size, num_heads, sequence_length, sequence_length).

Dikkat softmax'ı sonrası dikkat ağırlıkları, öz-dikkat başlıkları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 verildiğinde MSE ve quantile kayıplarını birleştiren eğitim kaybı.

Update on GitHub