Transformers documentation
TimesFM
Bu model, 2023-10-14 tarihinde HF papers'ta yayımlanmış ve 2025-04-16 tarihinde Hugging Face Transformers'a katkıda bulunmuştur.
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 makalesinde önerilen, önceden eğitilmiş bir zaman serisi temel modelidir. Bu model, yalnızca decoder kullanan bir mimariye sahiptir; girdi olarak zaman serisi verisinin üst üste binmeyen yamalarını (patch) alı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 tarafından katkıda bulunmuştur. Orijinal kod burada bulunabilir.
Modeli kullanmak için:
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
sınıf transformers.TimesFmConfig
< 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 = 512horizon_length: int = 128freq_size: int = 3num_hidden_layers: int = 50hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16tolerance: float = 1e-06rms_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)pad_val: float = 1123581321.0attention_dropout: float | int = 0.0use_positional_embedding: bool = Falseinitializer_range: float = 0.02min_timescale: int = 1max_timescale: int = 10000 )
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 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ılan50) — Transformer decoder'ındaki gizli katman sayısı. - hidden_size (
int, isteğe bağlı, varsayılan1280) — Gizli temsillerin boyutu. - intermediate_size (
int, isteğe bağlı, varsayılan1280) — MLP temsillerinin boyutu. - head_dim (
int, isteğe bağlı, varsayılan80) — 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ılan16) — Transformer decoder'ındaki her dikkat katmanı için dikkat başı sayısı. - tolerance (
float, isteğe bağlı, varsayılan 1e-06) — Kantil kaybı için tolerans. - rms_norm_eps (
float, isteğe bağlı, varsayılan1e-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. - pad_val (
float, isteğe bağlı, varsayılan 1123581321.0) — Tahminleri doldurmak için kullanılan değer. - attention_dropout (
float, isteğe bağlı, varsayılan 0.0) — Dikkat skorları için dropout olasılığı. - use_positional_embedding (
bool, isteğe bağlı, varsayılanFalse) — Konumsal gömme eklenip eklenmeyeceğini belirtir. - initializer_range (
float, isteğe bağlı, varsayılan0.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 örneklendiğinde, google/timesfm-2.0-500m-pytorch 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.
TimesFmModel
sınıf transformers.TimesFmModel
< source >( config: TimesFmConfig )
Parametreler
- config (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() yöntemine bakın.
Üzerinde herhangi bir özel head olmadan ham hidden-states üreten çıplak Timesfm Model.
Bu model 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 boyutlandırma, başları budama vb.) için üst sınıf belgelendirmesine bakın.
Bu model aynı zamanda bir PyTorch 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
< source >( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput 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)) — Zaman serisinin dolgu göstergesi. - freq (
torch.LongTensor, şekli(batch_size,)) — Zaman serisi verileri için frekans indeksleri.
Dönüş değeri
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) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
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ü ö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=Truegeçirildiğinde veyaconfig.output_hidden_states=Trueolduğ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=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğ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, )) — Zaman serisi girdilerinin ortalaması.scale (
torch.Tensor, şekli(batch_size,)) — Zaman serisi girdilerinin ölçeği.
TimesFmModelForPrediction
Quantile ve ortalama tahmini için TimesFM modeli.
forward
< source >( past_values: collections.abc.Sequence[torch.Tensor]freq: collections.abc.Sequence[typing.Union[torch.Tensor, int]] | None = Nonewindow_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonereturn_forecast_on_context: bool = Falsetruncate_negative: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutputForPrediction 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. - freq (
torch.LongTensor, şekli(batch_size,)) — Zaman serisi verileri için frekans indeksleri. - window_size (
int, isteğe bağlı) — Trend + artık ayrıştırmasının pencere boyutu. None ise ayrıştırma yapılmaz. - future_values (
torch.Tensor, opsiyonel) — Kayıp hesabında kullanılacak isteğe bağlı gelecek 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ı) — Mevcut olduğunda, yani ilk giriş yamasından sonra, bağlam üzerinde tahmini döndürmek için True. - truncate_negative (
bool, isteğe bağlı) — Bağlamlardan herhangi birinde negatif olmayan değerler varsa yalnızca negatif olmayan değerlere kısaltır, aksi halde hiçbir işlem yapmaz.
Dönüş değeri
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ırma (TimesFmConfig) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
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ü ö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=Truegeçirildiğinde veyaconfig.output_hidden_states=Trueolduğ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=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğ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, sequence_length)) — Zaman serisinin ortalama tahminleri.full_predictions (
torch.Tensor, şekli(batch_size, sequence_length)) — Ortalamayı ve kantilleri içeren zaman serisinin tüm tahminleri.loss (
torch.Tensor, şekli(1,), opsiyonel,future_valuessağlandığında döndürülür) — TimesFM modelinin kaybı.
Örnek:
>>> 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