Transformers documentation

TimesFM

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

< >

( 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, default 50) — 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.
  • tolerance (float, opsional, default 1e-06) — Toleransi untuk quantile loss.
  • 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.
  • 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, default False) — Apakah akan menambahkan positional embeddings.
  • initializer_range (float, opsional, defaultnya 0.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

< >

( 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

< >

( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)

Parameter

  • past_values (torch.Tensor dengan bentuk (batch_size, sequence_length)) — Nilai masa lalu dari deret waktu yang berfungsi sebagai input ke model.
  • past_values_padding (torch.LongTensor dengan bentuk (batch_size, sequence_length)) — Indikator padding untuk deret waktu.
  • freq (torch.LongTensor dengan 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 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, )) — Rata-rata dari input deret waktu.

  • scale (torch.Tensor dengan bentuk (batch_size,)) — Skala dari input deret waktu.

TimesFmModelForPrediction

kelas transformers.TimesFmModelForPrediction

< >

( config: TimesFmConfig )

Model TimesFM untuk prediksi kuantil dan rata-rata.

forward

< >

( 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.Tensor dengan bentuk (batch_size, sequence_length)) — Nilai masa lalu dari deret waktu yang berfungsi sebagai input ke model.
  • freq (torch.LongTensor dengan 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 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, sequence_length)) — Prediksi rata-rata dari deret waktu.

  • full_predictions (torch.Tensor dengan bentuk (batch_size, sequence_length)) — Prediksi lengkap dari deret waktu, termasuk mean dan kuantil.

  • loss (torch.Tensor dengan bentuk (1,), opsional, dikembalikan saat future_values disediakan) — 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
Update on GitHub