Hugging Face's logo

Transformers documentation

Autoformer

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
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 2021-06-24 dan disumbangkan ke Hugging Face Transformers pada 2023-05-30.

Autoformer

Ikhtisar

Model Autoformer diusulkan dalam Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting oleh Haixu Wu, Jiehui Xu, Jianmin Wang, Mingsheng Long.

Model ini memperluas Transformer sebagai arsitektur dekomposisi mendalam, yang dapat secara progresif menguraikan komponen tren dan musiman selama proses peramalan.

Abstrak dari makalah tersebut adalah sebagai berikut:

Memperpanjang waktu prediksi merupakan kebutuhan kritis untuk aplikasi nyata, seperti peringatan dini cuaca ekstrem dan perencanaan konsumsi energi jangka panjang. Kertas ini mempelajari masalah prediksi jangka panjang pada deret waktu. Model berbasis Transformer sebelumnya mengadopsi berbagai mekanisme self-attention untuk menemukan dependensi jarak jauh. Namun, pola temporal yang rumit dari masa depan jangka panjang menghambat model dalam menemukan dependensi yang andal. Selain itu, Transformer harus mengadopsi versi sparse dari self-attention point-wise untuk efisiensi deret panjang, yang mengakibatkan bottleneck pemanfaatan informasi. Melampaui Transformer, kami merancang Autoformer sebagai arsitektur dekomposisi baru dengan mekanisme Auto-Correlation. Kami mematahkan konvensi pra-pemrosesan dekomposisi deret dan memperbaruinya menjadi blok internal dasar dari model dalam. Desain ini memberdayakan Autoformer dengan kapasitas dekomposisi progresif untuk deret waktu yang kompleks. Lebih lanjut, terinspirasi oleh teori proses stokastik, kami merancang mekanisme Auto-Correlation berdasarkan periodisitas deret, yang melakukan penemuan dependensi dan agregasi representasi pada level sub-deret. Auto-Correlation melampaui self-attention dalam hal efisiensi dan akurasi. Dalam prediksi jangka panjang, Autoformer menghasilkan akurasi state-of-the-art, dengan peningkatan relatif 38% pada enam benchmark, yang mencakup lima aplikasi praktis: energi, lalu lintas, ekonomi, cuaca, dan penyakit.

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

Sumber daya

Daftar sumber resmi Hugging Face dan komunitas (ditandai dengan 🌎) untuk membantu Anda memulai. Jika Anda tertarik untuk mengirimkan sumber agar disertakan di sini, silakan buka Pull Request dan kami akan meninjaunya! Sumber tersebut sebaiknya mendemonstrasikan sesuatu yang baru, bukan menduplikasi sumber yang sudah ada.

AutoformerConfig

kelas transformers.AutoformerConfig

< >

( 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 = 0id2label: 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 = Noneis_encoder_decoder: bool = Trueprediction_length: int | None = Nonecontext_length: int | None = Nonedistribution_output: str = 'student_t'loss: str = 'nll'input_size: int = 1lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7)scaling: bool | str = Truenum_time_features: int = 0num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32activation_function: str = 'gelu'dropout: float | int = 0.1encoder_layerdrop: float | int = 0.1decoder_layerdrop: float | int = 0.1attention_dropout: float | int = 0.1activation_dropout: float | int = 0.1num_parallel_samples: int = 100init_std: float = 0.02use_cache: bool = Truelabel_length: int = 10moving_average: int = 25autocorrelation_factor: int = 3 )

Parameter

  • is_encoder_decoder (bool, opsional, defaultnya True) — Apakah model digunakan sebagai encoder/decoder atau tidak.
  • prediction_length (int, opsional) — Panjang prediksi untuk decoder. Dengan kata lain, horizon prediksi dari model.
  • context_length (int, opsional, defaultnya prediction_length) — Panjang konteks untuk encoder. Jika tidak diset, panjang konteks akan sama dengan prediction_length.
  • distribution_output (string, opsional, default "student_t") — Head emisi distribusi untuk model. Bisa berupa “student_t”, “normal” atau “negative_binomial”.
  • loss (string, opsional, default "nll") — Fungsi loss untuk model yang sesuai dengan head distribution_output. Untuk distribusi parametrik, ini adalah negative log likelihood (nll) - yang saat ini satu-satunya yang didukung.
  • input_size (int, opsional, default 1) — Ukuran variabel target yang secara default adalah 1 untuk target univariat. Akan menjadi > 1 dalam kasus target multivariat.
  • lags_sequence (list[int], opsional, default [1, 2, 3, 4, 5, 6, 7]) — Lag dari deret waktu input sebagai kovariat, yang sering ditentukan oleh frekuensinya. Default adalah [1, 2, 3, 4, 5, 6, 7].
  • scaling (bool, opsional defaultnya True) — Apakah akan menskalakan target input.
  • num_time_features (int, opsional, default 0) — Jumlah fitur waktu dalam deret waktu input.
  • num_dynamic_real_features (int, opsional, default 0) — Jumlah fitur bernilai real dinamis.
  • num_static_categorical_features (int, opsional, default 0) — Jumlah fitur kategoris statis.
  • num_static_real_features (int, opsional, default 0) — Jumlah fitur bernilai real statis.
  • cardinality (list[int], opsional) — Kardinalitas (jumlah nilai yang berbeda) untuk masing-masing fitur kategoris statis. Harus berupa daftar bilangan bulat, dengan panjang yang sama dengan num_static_categorical_features. Tidak boleh None jika num_static_categorical_features > 0.
  • embedding_dimension (list[int], opsional) — Dimensi dari embedding dan hidden states.
  • d_model (int, opsional, default 64) — Ukuran lapisan encoder dan lapisan pooler.
  • encoder_attention_heads (int, opsional, default 2) — Jumlah kepala perhatian untuk setiap lapisan perhatian dalam encoder Transformer.
  • decoder_attention_heads (int, opsional, default 2) — Jumlah kepala perhatian untuk setiap lapisan perhatian dalam decoder Transformer.
  • encoder_layers (int, opsional, default 2) — Jumlah lapisan tersembunyi pada encoder Transformer. Akan menggunakan nilai yang sama dengan num_layers jika tidak diatur.
  • decoder_layers (int, opsional, default 2) — Jumlah lapisan tersembunyi dalam decoder Transformer. Akan menggunakan nilai yang sama dengan num_layers jika tidak diatur.
  • encoder_ffn_dim (int, opsional, defaultnya 32) — Dimensi dari lapisan “intermediate” (sering disebut feed-forward) di encoder.
  • decoder_ffn_dim (int, opsional, defaultnya 32) — Dimensi dari lapisan “intermediate” (sering disebut feed-forward) di decoder.
  • activation_function (str, opsional, defaultnya gelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
  • dropout (Union[float, int], opsional, default 0.1) — Rasio untuk semua lapisan dropout.
  • encoder_layerdrop (Union[float, int], opsional, default 0.1) — Probabilitas LayerDrop untuk encoder. Lihat [makalah LayerDrop](lihat https://huggingface.co/papers/1909.11556) untuk detail lebih lanjut.
  • decoder_layerdrop (Union[float, int], opsional, default 0.1) — Probabilitas LayerDrop untuk decoder. Lihat [makalah LayerDrop](lihat https://huggingface.co/papers/1909.11556) untuk detail lebih lanjut.
  • attention_dropout (Union[float, int], opsional, default 0.1) — Rasio dropout untuk probabilitas perhatian.
  • activation_dropout (Union[float, int], opsional, defaultnya 0.1) — Rasio dropout untuk aktivasi di dalam lapisan fully connected.
  • num_parallel_samples (int, opsional, default 100) — Jumlah sampel yang akan dihasilkan secara paralel untuk setiap langkah waktu inferensi.
  • init_std (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
  • use_cache (bool, opsional, defaultnya True) — Apakah model harus mengembalikan perhatian kunci/nilai terakhir (tidak digunakan oleh semua model). Hanya relevan jika config.is_decoder=True atau ketika model adalah model generatif yang hanya decoder.
  • label_length (int, opsional, default 10) — Panjang token awal dari decoder Autoformer, yang digunakan untuk prediksi multi-langkah langsung (yaitu generasi non-otoregresif).
  • moving_average (int, opsional, default 25) — Ukuran jendela dari moving average. Dalam praktiknya, ini adalah ukuran kernel dalam AvgPool1d dari Decomposition Layer.
  • autocorrelation_factor (int, opsional, default 3) — Faktor “Attention” (yaitu mekanisme AutoCorrelation) yang digunakan untuk menemukan k delay autokorelasi teratas. Disarankan dalam makalah untuk mengaturnya ke angka antara 1 dan 5.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari AutoformerModel. Kelas ini digunakan untuk membuat instans model Autoformer sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari huggingface/autoformer-tourism-monthly

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

Contoh:

>>> from transformers import AutoformerConfig, AutoformerModel

>>> # Initializing a default Autoformer configuration
>>> configuration = AutoformerConfig()

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = AutoformerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

AutoformerModel

kelas transformers.AutoformerModel

< >

( config: AutoformerConfig )

Parameter

  • config (AutoformerConfig) — 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 Autoformer 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_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → AutoformerModelOutput or tuple(torch.Tensor)

Parameter

  • past_values (torch.Tensor dengan bentuk (batch_size, sequence_length)) — Nilai masa lalu dari deret waktu, yang berfungsi sebagai konteks untuk memprediksi masa depan. Nilai-nilai ini dapat berisi lag, yaitu nilai tambahan dari masa lalu yang ditambahkan untuk berfungsi sebagai “konteks tambahan”. past_values adalah apa yang diterima encoder Transformer sebagai input (dengan fitur tambahan opsional, seperti static_categorical_features, static_real_features, past_time_features).

    Panjang urutan di sini sama dengan context_length + max(config.lags_sequence).

    Nilai yang hilang perlu diganti dengan nol.

  • past_time_features (torch.Tensor dengan bentuk (batch_size, sequence_length, num_features), opsional) — Fitur waktu opsional, yang secara internal akan ditambahkan oleh model ke past_values. Fitur-fitur ini bisa berupa hal-hal seperti “bulan dalam setahun”, “hari dalam sebulan”, dll. yang dikodekan sebagai vektor (misalnya sebagai Fourier features). Fitur-fitur ini juga bisa berupa fitur “usia” (age features), yang pada dasarnya membantu model mengetahui “pada titik mana dalam kehidupan” suatu time-series berada. Fitur usia memiliki nilai kecil untuk langkah waktu di masa lalu yang jauh dan meningkat secara monoton seiring kita mendekati langkah waktu saat ini.

    Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana positional encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur waktu tambahan.

    Autoformer hanya mempelajari embedding tambahan untuk static_categorical_features.

  • past_observed_mask (torch.BoolTensor dengan bentuk (batch_size, sequence_length), opsional) — Mask boolean untuk menunjukkan nilai past_values mana yang teramati dan mana yang hilang. Nilai mask dipilih dari [0, 1]:
    • 1 untuk nilai yang diamati,
    • 0 untuk nilai yang hilang (yaitu NaN yang diganti dengan nol).
  • static_categorical_features (torch.LongTensor dengan bentuk (batch_size, number of static categorical features), opsional) — Fitur kategoris statis opsional yang akan dipelajari modelnya sebagai embedding, yang kemudian akan ditambahkan ke nilai dari deret waktu tersebut.

    Fitur kategoris statis adalah fitur yang memiliki nilai yang sama untuk semua langkah waktu (statis terhadap waktu).

    Contoh tipikal dari fitur kategoris statis adalah ID deret waktu.

  • static_real_features (torch.Tensor dengan bentuk (batch_size, number of static real features), opsional) — Fitur real statis opsional yang akan ditambahkan model ke nilai dari deret waktu.

    Fitur real statis adalah fitur yang memiliki nilai yang sama untuk semua langkah waktu (statis terhadap waktu).

    Contoh tipikal dari fitur real statis adalah informasi promosi.

  • future_values (torch.Tensor dengan bentuk (batch_size, prediction_length)) — Nilai masa depan dari deret waktu, yang berfungsi sebagai label untuk model. future_values adalah apa yang perlu dipelajari oleh Transformer untuk dioutputkan, mengingat past_values.

    Lihat notebook demo dan potongan kode untuk detailnya.

    Nilai yang hilang perlu diganti dengan nol.

  • future_time_features (torch.Tensor dengan bentuk (batch_size, prediction_length, num_features), opsional) — Fitur waktu opsional, yang secara internal akan ditambahkan oleh model ke future_values. Fitur-fitur ini bisa berupa hal-hal seperti “bulan dalam setahun”, “hari dalam sebulan”, dll., yang dikodekan sebagai vektor (misalnya sebagai Fourier features). Fitur-fitur ini juga bisa berupa fitur “usia” (age features), yang pada dasarnya membantu model mengetahui “pada titik mana dalam kehidupan” suatu time-series berada. Fitur usia memiliki nilai kecil untuk langkah waktu di masa lalu yang jauh dan meningkat secara monoton seiring kita mendekati langkah waktu saat ini.

    Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana positional encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur tambahan.

    Autoformer hanya mempelajari embedding tambahan untuk static_categorical_features.

  • decoder_attention_mask (torch.LongTensor dengan bentuk (batch_size, target_sequence_length), opsional) — Mask untuk menghindari pelaksanaan attention pada indeks token tertentu. Secara default, mask kausal akan digunakan, untuk memastikan model hanya dapat melihat input sebelumnya guna memprediksi masa depan.
  • encoder_outputs (tuple(tuple(torch.Tensor), opsional) — Tuple terdiri dari last_hidden_state, hidden_states (opsional) dan attentions (opsional) last_hidden_state dengan bentuk (batch_size, sequence_length, hidden_size) (opsional) adalah rangkaian hidden-states pada keluaran lapisan terakhir encoder. Digunakan dalam cross-attention decoder.
  • past_key_values (~cache_utils.Cache, opsional) — Hidden-states yang sudah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari past_key_values yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika use_cache=True atau config.use_cache=True.

    Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada past_key_values yang diteruskan, DynamicCache akan diinisialisasi secara default.

    Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.

    Jika past_key_values digunakan, pengguna diharapkan hanya memasukkan input_ids yang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk (batch_size, unprocessed_length) alih-alih semua input_ids dengan bentuk (batch_size, sequence_length).

  • use_cache (bool, opsional) — Jika diset ke True, state kunci-nilai past_key_values akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat past_key_values).

Mengembalikan

AutoformerModelOutput atau tuple(torch.Tensor)

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

Metode forward dari AutoformerModel 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 dari decoder model.

    Jika past_key_values digunakan, hanya hidden-state terakhir dari sekuens dengan bentuk (batch_size, 1, hidden_size) yang dioutput.

  • trend (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size)) — Tensor tren untuk setiap deret waktu.

  • past_key_values (Cache, opsional, dikembalikan saat use_cache=True dilewatkan atau saat config.use_cache=True) — Ini adalah instance Cache. Untuk detail lebih lanjut, lihat panduan kv cache kami.

    Mengandung hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan (lihat input past_key_values) untuk mempercepat decoding berurutan.

  • decoder_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 dari decoder pada output setiap layer ditambah output embedding awal.

  • decoder_attentions (tuple[torch.Tensor], opsional, dikembalikan ketika output_attentions=True dilewatkan atau ketika config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap lapisan) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

    Bobot perhatian dari decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala self-attention.

  • cross_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 dari lapisan cross-attention decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala cross-attention.

  • encoder_last_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Urutan hidden-states pada keluaran lapisan terakhir dari encoder model.

  • encoder_hidden_states (tuple[torch.Tensor], opsional, dikembalikan ketika output_hidden_states=True dilewatkan atau ketika 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 dari encoder pada output setiap layer ditambah output embedding awal.

  • encoder_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 dari encoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala 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 masing-masing deret waktu, yang digunakan untuk memberikan input dengan magnitudo yang sama kepada model, kemudian digunakan untuk menskalakan kembali ke magnitudo asli. static_features: (torch.Tensor dengan bentuk (batch_size, feature size), opsional): Fitur statis dari masing-masing deret waktu dalam batch, yang disalin ke kovariat pada saat inferensi.

  • static_features (torch.Tensor dengan bentuk (batch_size, feature size), opsional) — Fitur statis dari masing-masing deret waktu dalam batch yang disalin ke kovariat pada saat inferensi.

Contoh:

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = AutoformerModel.from_pretrained("huggingface/autoformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state

AutoformerForPrediction

kelas transformers.AutoformerForPrediction

< >

( config: AutoformerConfig )

Parameter

  • config (AutoformerConfig) — 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 Autoformer dengan kepala distribusi di bagian atas untuk peramalan deret waktu.

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_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonefuture_observed_mask: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSPredictionOutput or tuple(torch.Tensor)

Parameter

  • past_values (torch.Tensor dengan bentuk (batch_size, sequence_length)) — Nilai masa lalu dari deret waktu, yang berfungsi sebagai konteks untuk memprediksi masa depan. Nilai-nilai ini dapat berisi lag, yaitu nilai tambahan dari masa lalu yang ditambahkan untuk berfungsi sebagai “konteks tambahan”. past_values adalah apa yang diterima encoder Transformer sebagai input (dengan fitur tambahan opsional, seperti static_categorical_features, static_real_features, past_time_features).

    Panjang urutan di sini sama dengan context_length + max(config.lags_sequence).

    Nilai yang hilang perlu diganti dengan nol.

  • past_time_features (torch.Tensor dengan bentuk (batch_size, sequence_length, num_features), opsional) — Fitur waktu opsional, yang secara internal akan ditambahkan oleh model ke past_values. Fitur-fitur ini bisa berupa hal-hal seperti “bulan dalam setahun”, “hari dalam sebulan”, dll. yang dikodekan sebagai vektor (misalnya sebagai Fourier features). Fitur-fitur ini juga bisa berupa fitur “usia” (age features), yang pada dasarnya membantu model mengetahui “pada titik mana dalam kehidupan” suatu time-series berada. Fitur usia memiliki nilai kecil untuk langkah waktu di masa lalu yang jauh dan meningkat secara monoton seiring kita mendekati langkah waktu saat ini.

    Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana positional encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur waktu tambahan.

    Autoformer hanya mempelajari embedding tambahan untuk static_categorical_features.

  • past_observed_mask (torch.BoolTensor dengan bentuk (batch_size, sequence_length), opsional) — Mask boolean untuk menunjukkan nilai past_values mana yang teramati dan mana yang hilang. Nilai mask dipilih dari [0, 1]:
    • 1 untuk nilai yang diamati,
    • 0 untuk nilai yang hilang (yaitu NaN yang diganti dengan nol).
  • static_categorical_features (torch.LongTensor dengan bentuk (batch_size, number of static categorical features), opsional) — Fitur kategoris statis opsional yang akan dipelajari modelnya sebagai embedding, yang kemudian akan ditambahkan ke nilai dari deret waktu tersebut.

    Fitur kategoris statis adalah fitur yang memiliki nilai yang sama untuk semua langkah waktu (statis terhadap waktu).

    Contoh tipikal dari fitur kategoris statis adalah ID deret waktu.

  • static_real_features (torch.Tensor dengan bentuk (batch_size, number of static real features), opsional) — Fitur real statis opsional yang akan ditambahkan model ke nilai dari deret waktu.

    Fitur real statis adalah fitur yang memiliki nilai yang sama untuk semua langkah waktu (statis terhadap waktu).

    Contoh tipikal dari fitur real statis adalah informasi promosi.

  • future_values (torch.Tensor dengan bentuk (batch_size, prediction_length)) — Nilai masa depan dari deret waktu, yang berfungsi sebagai label untuk model. future_values adalah apa yang perlu dipelajari oleh Transformer untuk dioutputkan, mengingat past_values.

    Lihat notebook demo dan potongan kode untuk detailnya.

    Nilai yang hilang perlu diganti dengan nol.

  • future_time_features (torch.Tensor dengan bentuk (batch_size, prediction_length, num_features), opsional) — Fitur waktu opsional, yang secara internal akan ditambahkan oleh model ke future_values. Fitur-fitur ini bisa berupa hal-hal seperti “bulan dalam setahun”, “hari dalam sebulan”, dll., yang dikodekan sebagai vektor (misalnya sebagai Fourier features). Fitur-fitur ini juga bisa berupa fitur “usia” (age features), yang pada dasarnya membantu model mengetahui “pada titik mana dalam kehidupan” suatu time-series berada. Fitur usia memiliki nilai kecil untuk langkah waktu di masa lalu yang jauh dan meningkat secara monoton seiring kita mendekati langkah waktu saat ini.

    Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana positional encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur tambahan.

    Autoformer hanya mempelajari embedding tambahan untuk static_categorical_features.

  • future_observed_mask (torch.BoolTensor dengan bentuk (batch_size, sequence_length) atau (batch_size, sequence_length, input_size), opsional) — Mask boolean untuk menunjukkan nilai future_values yang diamati dan nilai yang hilang. Nilai mask dipilih dalam [0, 1]: 1 untuk nilai yang diamati, 0 untuk nilai yang hilang (yaitu NaN yang diganti dengan nol). Mask ini digunakan untuk menyaring nilai yang hilang untuk perhitungan loss akhir. [0, 1]:
    • 1 untuk nilai yang diamati,
    • 0 untuk nilai yang hilang (yaitu NaN yang diganti dengan nol).

    Mask ini digunakan untuk menyaring nilai yang hilang untuk perhitungan loss akhir.

  • decoder_attention_mask (torch.LongTensor dengan bentuk (batch_size, target_sequence_length), opsional) — Mask untuk menghindari pelaksanaan attention pada indeks token tertentu. Secara default, mask kausal akan digunakan, untuk memastikan model hanya dapat melihat input sebelumnya guna memprediksi masa depan.
  • encoder_outputs (tuple(tuple(torch.Tensor), opsional) — Tuple terdiri dari last_hidden_state, hidden_states (opsional) dan attentions (opsional) last_hidden_state dengan bentuk (batch_size, sequence_length, hidden_size) (opsional) adalah rangkaian hidden-states pada keluaran lapisan terakhir encoder. Digunakan dalam cross-attention decoder.
  • past_key_values (~cache_utils.Cache, opsional) — Hidden-states yang sudah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari past_key_values yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika use_cache=True atau config.use_cache=True.

    Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada past_key_values yang diteruskan, DynamicCache akan diinisialisasi secara default.

    Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.

    Jika past_key_values digunakan, pengguna diharapkan hanya memasukkan input_ids yang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk (batch_size, unprocessed_length) alih-alih semua input_ids dengan bentuk (batch_size, sequence_length).

  • use_cache (bool, opsional) — Jika diset ke True, state kunci-nilai past_key_values akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat past_key_values).

Mengembalikan

Seq2SeqTSPredictionOutput atau tuple(torch.Tensor)

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

Metode forward dari AutoformerForPrediction 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.

  • loss (torch.Tensor dengan bentuk (1,), opsional, dikembalikan ketika future_values disediakan) — Loss distribusi.

  • params (torch.Tensor dengan bentuk (batch_size, num_samples, num_params)) — Parameter dari distribusi yang dipilih.

  • past_key_values (EncoderDecoderCache, opsional, dikembalikan ketika use_cache=True diteruskan atau ketika config.use_cache=True) — Ini adalah instance EncoderDecoderCache. Untuk detail lebih lanjut, lihat panduan kv cache kami.

    Mengandung hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan (lihat input past_key_values) untuk mempercepat decoding berurutan.

  • decoder_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 dari decoder pada output setiap layer ditambah output embedding awal.

  • decoder_attentions (tuple(torch.Tensor), opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap lapisan) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

    Bobot perhatian dari decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala self-attention.

  • cross_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 dari lapisan cross-attention decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala cross-attention.

  • encoder_last_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Urutan hidden-states pada keluaran lapisan terakhir dari encoder model.

  • encoder_hidden_states (tuple(torch.Tensor), opsional, dikembalikan ketika output_hidden_states=True dilewatkan atau ketika 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 dari encoder pada output setiap layer ditambah output embedding awal.

  • encoder_attentions (tuple(torch.Tensor), opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap lapisan) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

    Bobot perhatian dari encoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala 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.

  • static_features (torch.Tensor dengan bentuk (batch_size, feature size), opsional) — Fitur statis dari masing-masing deret waktu dalam batch yang disalin ke kovariat pada saat inferensi.

Contoh:

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = AutoformerForPrediction.from_pretrained("huggingface/autoformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_time_features=batch["future_time_features"],
... )

>>> mean_prediction = outputs.sequences.mean(dim=1)

AutoformerForPrediction juga dapat menggunakan static_real_features. Untuk melakukannya, atur num_static_real_features di AutoformerConfig berdasarkan jumlah fitur tersebut dalam dataset (dalam kasus dataset tourism_monthly itu

sama dengan 1), inisialisasi model dan panggil seperti yang ditunjukkan di bawah:

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerConfig, AutoformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> # check number of static real features
>>> num_static_real_features = batch["static_real_features"].shape[-1]

>>> # load configuration of pretrained model and override num_static_real_features
>>> configuration = AutoformerConfig.from_pretrained(
...     "huggingface/autoformer-tourism-monthly",
...     num_static_real_features=num_static_real_features,
... )
>>> # we also need to update feature_size as it is not recalculated
>>> configuration.feature_size += num_static_real_features

>>> model = AutoformerForPrediction(configuration)

>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )
Update on GitHub

←Decision Transformer Informer→