Transformers documentation
TimesFM
Model ini dipublikasikan di HF papers pada 2023-10-14 dan disumbangkan ke Hugging Face Transformers pada 2025-04-16.
TimesFM
Ikhtisar
TimesFM (Time Series Foundation Model) adalah model fondasi deret waktu yang telah dilatih sebelumnya, yang diusulkan dalam A decoder-only foundation model for time-series forecasting oleh Abhimanyu Das, Weihao Kong, Rajat Sen, dan Yichen Zhou. Ini adalah model decoder-only yang menggunakan patch data deret waktu yang tidak tumpang tindih sebagai input dan menghasilkan prediksi panjang patch output secara autoregresif.
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 bergaya patched-decoder pada korpus deret waktu yang besar, dan dapat bekerja dengan baik di berbagai panjang riwayat peramalan, panjang prediksi, dan granularitas temporal.
Model ini disumbangkan oleh kashif. Kode aslinya dapat ditemukan di sini.
Untuk menggunakan model:
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
kelas 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 )
Parameter
- patch_length (
int, opsional, default 32) — Panjang satu patch dalam urutan input. - context_length (
int, opsional, default 512) — Panjang konteks input. - horizon_length (
int, opsional, default 128) — Panjang horizon prediksi. - freq_size (
int, opsional, default 3) — Jumlah embedding frekuensi. - num_hidden_layers (
int, opsional, default50) — Jumlah lapisan tersembunyi dalam decoder Transformer. - hidden_size (
int, opsional, default1280) — Dimensi dari representasi tersembunyi. - intermediate_size (
int, opsional, default1280) — Dimensi representasi MLP. - head_dim (
int, opsional, default80) — Dimensi head attention. Jika None, nilainya akan default ke hidden_size // num_attention_heads - num_attention_heads (
int, opsional, default16) — Jumlah attention head untuk setiap lapisan attention di decoder Transformer. - tolerance (
float, opsional, default 1e-06) — Toleransi untuk quantile loss. - rms_norm_eps (
float, opsional, defaultnya1e-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. - pad_val (
float, opsional, default 1123581321.0) — Nilai yang digunakan untuk mengisi (padding) prediksi. - attention_dropout (
float, opsional, default 0.0) — Probabilitas dropout untuk skor attention. - use_positional_embedding (
bool, opsional, defaultFalse) — Apakah akan menambahkan positional embeddings. - initializer_range (
float, opsional, defaultnya0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot. - min_timescale (
int, opsional, default 1) — Awal dari indeks posisi geometris. Menentukan periodisitas sinyal yang ditambahkan. - max_timescale (
int, opsional, default 10000) — Ukuran akhir dari indeks posisi geometris. Menentukan frekuensi sinyal yang ditambahkan.
Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari TimesFmModel. Kelas ini digunakan untuk menginstansiasi model Timesfm berdasarkan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Menginstansiasi konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari google/timesfm-2.0-500m-pytorch
Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.
TimesFmModel
kelas transformers.TimesFmModel
< source >( config: TimesFmConfig )
Parameter
- config (TimesFmConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.
Model Timesfm polos yang menghasilkan hidden-states mentah tanpa head spesifik di atasnya.
Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)
Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.
forward
< source >( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)
Parameter
- past_values (
torch.Tensordengan bentuk(batch_size, sequence_length)) — Nilai masa lalu dari deret waktu yang berfungsi sebagai input ke model. - past_values_padding (
torch.LongTensordengan bentuk(batch_size, sequence_length)) — Indikator padding untuk deret waktu. - freq (
torch.LongTensordengan bentuk(batch_size,)) — Indeks frekuensi untuk data deret waktu.
Mengembalikan
TimesFmOutput atau tuple(torch.Tensor)
TimesFmOutput atau tuple dari
torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (TimesFmConfig) dan input.
Metode forward dari TimesFmModel menimpa metode khusus __call__.
Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance
Modulesetelahnya 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.Tensordengan bentuk(batch_size, sequence_length, hidden_size)) — Urutan hidden-states pada keluaran lapisan terakhir model.hidden_states (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_hidden_states=Truedilewatkan atau saatconfig.output_hidden_states=True) — Tuple daritorch.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 saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.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.Tensordengan bentuk(batch_size, )) — Rata-rata dari input deret waktu.scale (
torch.Tensordengan bentuk(batch_size,)) — Skala dari input deret waktu.
TimesFmModelForPrediction
Model TimesFM untuk prediksi kuantil dan rata-rata.
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)
Parameter
- past_values (
torch.Tensordengan bentuk(batch_size, sequence_length)) — Nilai masa lalu dari deret waktu yang berfungsi sebagai input ke model. - freq (
torch.LongTensordengan bentuk(batch_size,)) — Indeks frekuensi untuk data deret waktu. - window_size (
int, opsional) — Ukuran jendela untuk dekomposisi tren + residual. Jika None, dekomposisi tidak dilakukan. - future_values (
torch.Tensor, opsional) — Nilai deret waktu masa depan opsional yang akan digunakan untuk perhitungan loss. - forecast_context_len (
int, opsional) — Panjang konteks maksimum opsional. - return_forecast_on_context (
bool, opsional) — True untuk mengembalikan forecast pada context jika tersedia, yaitu setelah input patch pertama. - truncate_negative (
bool, opsional) — Memotong hanya ke nilai non-negatif jika ada konteks yang memiliki nilai non-negatif, jika tidak, tidak melakukan apa pun.
Mengembalikan
TimesFmOutputForPrediction atau tuple(torch.Tensor)
TimesFmOutputForPrediction atau tuple dari
torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (TimesFmConfig) dan input.
Metode forward dari TimesFmModelForPrediction menimpa metode khusus __call__.
Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance
Modulesetelahnya 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.Tensordengan bentuk(batch_size, sequence_length, hidden_size)) — Urutan hidden-states pada keluaran lapisan terakhir model.hidden_states (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_hidden_states=Truedilewatkan atau saatconfig.output_hidden_states=True) — Tuple daritorch.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 saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.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.Tensordengan bentuk(batch_size, sequence_length)) — Prediksi rata-rata dari deret waktu.full_predictions (
torch.Tensordengan bentuk(batch_size, sequence_length)) — Prediksi lengkap dari deret waktu, termasuk mean dan kuantil.loss (
torch.Tensordengan bentuk(1,), opsional, dikembalikan saatfuture_valuesdisediakan) — Nilai loss dari model TimesFM.
Contoh:
>>> 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