Model ini dipublikasikan di HF papers pada 2023-10-14 dan disumbangkan ke Hugging Face Transformers pada 2026-02-27.

TimesFM 2.5

Ikhtisar

TimesFM 2.5 (Time Series Foundation Model) adalah model fondasi deret waktu pra-terlatih yang diusulkan dalam A decoder-only foundation model for time-series forecasting oleh Abhimanyu Das, Weihao Kong, Rajat Sen, dan Yichen Zhou. Model ini dibangun di atas arsitektur TimesFM asli dengan rotary attention, QK normalization, per-dimension attention scaling, dan continuous quantile prediction.

Abstrak dari makalah tersebut adalah sebagai berikut:

Dengan motivasi dari kemajuan terbaru dalam model bahasa besar untuk Pemrosesan Bahasa Alami (NLP), kami merancang model fondasi deret waktu untuk peramalan, di mana kinerja zero-shot-nya yang siap pakai pada berbagai dataset publik mendekati akurasi model peramalan supervised state-of-the-art untuk masing-masing dataset individu. Model kami didasarkan pada pra-pelatihan model perhatian gaya decoder dengan input patching, menggunakan korpus deret waktu besar yang mencakup dataset dunia nyata dan sintetis. Eksperimen pada beragam dataset peramalan yang belum pernah dilihat sebelumnya menunjukkan bahwa model ini dapat menghasilkan ramalan zero-shot yang akurat di berbagai domain, horizon peramalan, dan granularitas temporal.

Model ini disumbangkan oleh kashif. Kode aslinya dapat ditemukan di sini.

Anda dapat menemukan checkpoint di google/timesfm-2.5-200m-transformers.

Contoh penggunaan

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

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

Parameter

patch_length (int, opsional, default 32) — Panjang satu patch dalam urutan input.
context_length (int, opsional, default 16384) — Panjang konteks input.
horizon_length (int, opsional, default 128) — Panjang horizon prediksi.
num_hidden_layers (int, opsional, default 20) — Jumlah lapisan tersembunyi dalam decoder Transformer.
hidden_size (int, opsional, default 1280) — Dimensi dari representasi tersembunyi.
intermediate_size (int, opsional, default 1280) — Dimensi representasi MLP.
head_dim (int, opsional, default 80) — Dimensi head attention. Jika None, nilainya akan default ke hidden_size // num_attention_heads
num_attention_heads (int, opsional, default 16) — Jumlah attention head untuk setiap lapisan attention di decoder Transformer.
rms_norm_eps (float, opsional, defaultnya 1e-06) — Epsilon yang digunakan oleh lapisan normalisasi rms.
quantiles (list[float], opsional, default [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) — Kuantil yang akan diprediksi.
attention_dropout (Union[float, int], opsional, default 0.0) — Rasio dropout untuk probabilitas perhatian.
initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
num_key_value_heads (int, opsional, default 16) — Ini adalah jumlah key_value heads yang harus digunakan untuk mengimplementasikan Grouped Query Attention. Jika num_key_value_heads=num_attention_heads, model akan menggunakan Multi Head Attention (MHA), jika num_key_value_heads=1 model akan menggunakan Multi Query Attention (MQA), selain itu GQA yang digunakan. Saat mengkonversi checkpoint multi-head menjadi checkpoint GQA, setiap group key dan value head harus dibangun dengan meanpooling semua head asli di dalam grup tersebut. Untuk detail lebih lanjut, lihat paper ini. Jika tidak ditentukan, akan default ke num_attention_heads.
attention_bias (bool, opsional, default False) — Apakah akan menggunakan bias pada lapisan proyeksi query, key, value, dan output selama self-attention.
output_quantile_len (int, opsional, default 1024) — Panjang dimensi proyeksi output kuantil.
decode_index (int, opsional, default 5) — Indeks ke dimensi kuantil yang digunakan untuk mengekstrak ramalan titik (median).
use_bias (bool, opsional, default False) — Apakah akan menggunakan bias pada lapisan linear MLP dan transformer.
activation (str, opsional, default swish) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
use_continuous_quantile_head (bool, opsional, default True) — Apakah akan menggunakan continuous quantile head untuk prediksi quantile non-median.
force_flip_invariance (bool, opsional, default True) — Apakah akan menerapkan rata-rata invariance-flip selama peramalan.
infer_is_positive (bool, opsional, default True) — Apakah akan membatasi (clamp) perkiraan ke nilai non-negatif ketika nilai minimum input bersifat non-negatif.
max_position_embeddings (int, opsional, default 16384) — Panjang maksimum urutan yang mungkin digunakan dengan model ini.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opsional) — Kamus yang berisi parameter konfigurasi untuk embedding RoPE. Kamus tersebut harus berisi nilai untuk rope_theta dan secara opsional parameter yang digunakan untuk penskalaan jika Anda ingin menggunakan RoPE dengan max_position_embeddings yang lebih panjang.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari TimesFm2_5Model. Kelas ini digunakan untuk menginstansiasi model Timesfm2 5 sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Menginstansiasi konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari google/timesfm-2.5-200m-transformers

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

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

TimesFm2_5Model

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

Parameter

past_values (torch.Tensor dengan bentuk (batch_size, sequence_length)) — Nilai masa lalu dari deret waktu yang digunakan sebagai input ke model.
past_values_padding (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Mask padding untuk input. 1 menunjukkan langkah waktu yang di-pad (disediakan), 0 menunjukkan nilai yang valid.

Mengembalikan

TimesFm2_5Output atau tuple(torch.Tensor)

TimesFm2_5Output atau tuple dari torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (TimesFm2_5Config) dan input.

Metode forward dari TimesFm2_5Model menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

last_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size)) — Urutan hidden-states pada keluaran lapisan terakhir model.
hidden_states (tuple(torch.Tensor), opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.Tensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, sequence_length, hidden_size).

Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
attentions (tuple(torch.Tensor), opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).
loc (torch.Tensor dengan bentuk (batch_size,) atau (batch_size, input_size), opsional) — Menggeser nilai dari context window setiap time series, yang digunakan untuk memberikan input dengan magnitudo yang sama kepada model, kemudian digunakan untuk menggeser kembali ke magnitudo aslinya.
scale (torch.Tensor dengan bentuk (batch_size,) atau (batch_size, input_size), opsional) — Nilai penskalaan untuk jendela konteks dari setiap deret waktu, yang digunakan untuk memberikan input dengan magnitudo yang sama kepada model, kemudian digunakan untuk melakukan penskalaan kembali ke magnitudo aslinya.
context_mu (torch.Tensor dengan bentuk (batch_size, num_patches)) — Rata-rata berjalan yang dihitung per patch input selama normalisasi.
context_sigma (torch.Tensor dengan bentuk (batch_size, num_patches)) — Deviasi standar berjalan yang dihitung per patch input selama normalisasi.

TimesFm2_5ModelForPrediction

kelas transformers.TimesFm2_5ModelForPrediction

< source >

( config: TimesFm2_5Config )

Model TimesFm2_5 untuk prediksi kuantil dan rata-rata.

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)

Parameter

past_values (collections.abc.Sequence[torch.Tensor]) — Nilai-nilai masa lalu dari deret waktu yang berfungsi sebagai input ke model. Setiap tensor adalah deret waktu 1D.
window_size (int, opsional) — Ukuran jendela untuk dekomposisi tren + residual. Jika None, dekomposisi tidak diterapkan.
future_values (torch.Tensor, opsional) — Nilai masa depan opsional yang digunakan untuk menghitung loss.
forecast_context_len (int, opsional) — Override panjang konteks opsional yang digunakan selama peramalan.
truncate_negative (bool, opsional) — Apakah akan membatasi keluaran ke nilai non-negatif. Jika None, defaultnya adalah config.infer_is_positive.
force_flip_invariance (bool, opsional) — Apakah akan menerapkan kombinasi flip-invariance. Jika None, defaultnya adalah config.force_flip_invariance.

Mengembalikan

TimesFm2_5OutputForPrediction atau tuple(torch.Tensor)

TimesFm2_5OutputForPrediction atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (TimesFm2_5Config) dan input.

Metode forward dari TimesFm2_5ModelForPrediction menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

last_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size)) — Urutan hidden-states pada keluaran lapisan terakhir model.
hidden_states (tuple(torch.Tensor), opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.Tensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, sequence_length, hidden_size).

Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
attentions (tuple(torch.Tensor), opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).
mean_predictions (torch.Tensor dengan bentuk (batch_size, horizon_length)) — Peramalan deterministik setelah denormalisasi.
full_predictions (torch.Tensor dengan bentuk (batch_size, horizon_length, quantiles)) — Peramalan kuantil termasuk median setelah denormalisasi.
loss (torch.Tensor dengan bentuk (1,), opsional, dikembalikan saat future_values disediakan) — Loss pelatihan yang menggabungkan MSE dan quantile losses ketika target disediakan.

Update on GitHub