Transformers documentation
Informer
Model ini dipublikasikan di HF papers pada 2020-12-14 dan disumbangkan ke Hugging Face Transformers pada 2023-03-08.
Informer
Ikhtisar
Model Informer diusulkan dalam Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting oleh Haoyi Zhou, Shanghang Zhang, Jieqi Peng, Shuai Zhang, Jianxin Li, Hui Xiong, dan Wancai Zhang.
Metode ini memperkenalkan mekanisme Probabilistic Attention untuk memilih query yang “aktif” alih-alih query yang “malas”, dan menyediakan Transformer yang jarang (sparse), sehingga mengurangi kebutuhan komputasi dan memori kuadratik dari perhatian (attention) standar.
Abstrak dari makalah tersebut adalah sebagai berikut:
Banyak aplikasi dunia nyata memerlukan prediksi deret waktu berurutan panjang, seperti perencanaan konsumsi listrik. Peramalan deret waktu berurutan panjang (LSTF) menuntut kapasitas prediksi model yang tinggi, yaitu kemampuan untuk menangkap secara efisien kaitan dependensi jarak jauh yang presisi antara keluaran dan masukan. Studi-studi terbaru telah menunjukkan potensi Transformer untuk meningkatkan kapasitas prediksi. Namun, terdapat beberapa masalah serius pada Transformer yang menghalangi penerapannya secara langsung ke LSTF, termasuk kompleksitas waktu kuadratik, penggunaan memori yang tinggi, dan keterbatasan inheren arsitektur encoder-decoder. Untuk mengatasi masalah-masalah ini, kami merancang model berbasis transformer yang efisien untuk LSTF, bernama Informer, dengan tiga karakteristik khas: (i) mekanisme self-attention ProbSparse, yang mencapai O(L logL) dalam kompleksitas waktu dan penggunaan memori, serta memiliki kinerja yang sebanding dalam penyelarasan dependensi urutan. (ii) distilasi self-attention menyoroti perhatian yang dominan dengan mengurangi setengah masukan lapisan kaskade, dan menangani secara efisien urutan masukan yang sangat panjang. (iii) decoder bergaya generatif, yang secara konseptual sederhana, memprediksi urutan deret waktu panjang dalam satu operasi maju alih-alih cara langkah demi langkah, yang secara drastis meningkatkan kecepatan inferensi prediksi berurutan panjang. Eksperimen ekstensif pada empat dataset berskala besar menunjukkan bahwa Informer secara signifikan melampaui metode yang ada dan menyediakan solusi baru untuk masalah LSTF.
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.
- Lihat posting blog Informer di blog HuggingFace: Peramalan Deret Waktu Probabilistik Multivariat dengan Informer
InformerConfig
kelas transformers.InformerConfig
< 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 = 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] | None = Nonescaling: str | bool | None = 'mean'num_dynamic_real_features: int = 0num_static_real_features: int = 0num_static_categorical_features: int = 0num_time_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2activation_function: str = 'gelu'dropout: float | int = 0.05encoder_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 = Trueattention_type: str = 'prob'sampling_factor: int = 5distil: bool = True )
Parameter
- is_encoder_decoder (
bool, opsional, defaultnyaTrue) — Apakah model digunakan sebagai encoder/decoder atau tidak. - prediction_length (
int, opsional) — Panjang prediksi untuk decoder. Dengan kata lain, horizon prediksi model. Nilai ini biasanya ditentukan oleh dataset dan kami merekomendasikan untuk menyetelnya dengan tepat. - context_length (
int, opsional, defaultnyaprediction_length) — Panjang konteks untuk encoder. JikaNone, panjang konteks akan sama denganprediction_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 headdistribution_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 kali ditentukan oleh frekuensi data. Default adalah[1, 2, 3, 4, 5, 6, 7]tetapi kami merekomendasikan untuk mengubahnya sesuai dengan dataset. - scaling (
stringataubool, opsional defaultnya"mean") — Apakah akan menskalakan target input melalui scaler “mean”, scaler “std”, atau tanpa scaler jikaNone. JikaTrue, scaler diatur ke “mean”. - num_dynamic_real_features (
int, opsional, default 0) — Jumlah fitur bernilai real dinamis. - num_static_real_features (
int, opsional, default 0) — Jumlah fitur bernilai real statis. - num_static_categorical_features (
int, opsional, default 0) — Jumlah fitur kategoris statis. - num_time_features (
int, opsional, default 0) — Jumlah fitur waktu dalam deret waktu input. - cardinality (
list[int], opsional) — Kardinalitas (jumlah nilai yang berbeda) untuk masing-masing fitur kategoris statis. Harus berupa daftar bilangan bulat, dengan panjang yang sama dengannum_static_categorical_features. Tidak bolehNonejikanum_static_categorical_features> 0. - embedding_dimension (
list[int], opsional) — Dimensi embedding untuk masing-masing fitur kategoris statis. Harus berupa daftar bilangan bulat, dengan panjang yang sama dengannum_static_categorical_features. Tidak bolehNonejikanum_static_categorical_features> 0. - d_model (
int, opsional, default64) — Ukuran lapisan encoder dan lapisan pooler. - encoder_ffn_dim (
int, opsional, defaultnya32) — Dimensi dari lapisan “intermediate” (sering disebut feed-forward) di encoder. - decoder_ffn_dim (
int, opsional, defaultnya32) — Dimensi dari lapisan “intermediate” (sering disebut feed-forward) di decoder. - encoder_attention_heads (
int, opsional, default2) — Jumlah kepala perhatian untuk setiap lapisan perhatian dalam encoder Transformer. - decoder_attention_heads (
int, opsional, default2) — Jumlah kepala perhatian untuk setiap lapisan perhatian dalam decoder Transformer. - encoder_layers (
int, opsional, default2) — Jumlah lapisan tersembunyi pada encoder Transformer. Akan menggunakan nilai yang sama dengannum_layersjika tidak diatur. - decoder_layers (
int, opsional, default2) — Jumlah lapisan tersembunyi dalam decoder Transformer. Akan menggunakan nilai yang sama dengannum_layersjika tidak diatur. - activation_function (
str, opsional, defaultnyagelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya,"gelu","relu","silu", dan sebagainya. - dropout (
Union[float, int], opsional, default0.05) — Rasio untuk semua lapisan dropout. - encoder_layerdrop (
Union[float, int], opsional, default0.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, default0.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, default0.1) — Rasio dropout untuk probabilitas perhatian. - activation_dropout (
float, opsional, default 0.1) — Probabilitas dropout yang digunakan di antara dua lapisan dari jaringan feed-forward. - num_parallel_samples (
int, opsional, default 100) — Jumlah sampel yang akan dihasilkan secara paralel untuk setiap langkah waktu inferensi. - init_std (
float, opsional, defaultnya0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot. - use_cache (
bool, opsional, defaultnyaTrue) — Apakah model harus mengembalikan perhatian kunci/nilai terakhir (tidak digunakan oleh semua model). Hanya relevan jikaconfig.is_decoder=Trueatau ketika model adalah model generatif yang hanya decoder. - attention_type (
str, opsional, default “prob”) — Atensi yang digunakan di encoder. Nilai ini dapat diatur ke “prob” (ProbAttention dari Informer) atau “full” (self-attention kanonik dari transformer vanilla). - sampling_factor (
int, opsional, default 5) — Faktor sampling ProbSparse (hanya berpengaruh ketikaattention_type=“prob”). Digunakan untuk mengontrol panjang input matriks query yang direduksi (Q_reduce). - distil (
bool, opsional, defaultTrue) — Apakah akan menggunakan distilasi di encoder.
Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari InformerModel. Kelas ini digunakan untuk membuat instance model Informer sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instance konfigurasi dengan nilai default akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari huggingface/informer-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 InformerConfig, InformerModel
>>> # Initializing an Informer configuration with 12 time steps for prediction
>>> configuration = InformerConfig(prediction_length=12)
>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = InformerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configInformerModel
kelas transformers.InformerModel
< source >( config: InformerConfig )
Parameter
- config (InformerConfig) — 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 Informer 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_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'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)
Parameter
- past_values (
torch.Tensordengan bentuk(batch_size, sequence_length)atau(batch_size, sequence_length, input_size)) — Nilai masa lalu dari deret waktu, yang berfungsi sebagai konteks untuk memprediksi masa depan. Ukuran sekuens dari tensor ini harus lebih besar daricontext_lengthdari model, karena model akan menggunakan ukuran yang lebih besar untuk membuat fitur lag, yaitu nilai tambahan dari masa lalu yang ditambahkan untuk berfungsi sebagai “konteks tambahan”.sequence_lengthdi sini sama denganconfig.context_length+max(config.lags_sequence), yang jika tidak adalags_sequenceyang dikonfigurasi, sama denganconfig.context_length+ 7 (karena secara default, indeks look-back terbesar dalamconfig.lags_sequenceadalah 7). Properti_past_lengthmengembalikan panjang aktual dari masa lalu.past_valuesadalah apa yang diterima oleh encoder Transformer sebagai input (dengan fitur tambahan opsional, sepertistatic_categorical_features,static_real_features,past_time_featuresdan lag).Secara opsional, nilai yang hilang perlu diganti dengan nol dan ditunjukkan melalui
past_observed_mask.Untuk deret waktu multivariat, dimensi
input_size> 1 diperlukan dan sesuai dengan jumlah variat dalam deret waktu per langkah waktu. - past_time_features (
torch.Tensordengan bentuk(batch_size, sequence_length, num_features)) — Fitur waktu yang wajib, yang akan ditambahkan secara internal oleh model kepast_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” sebuah 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 hari libur juga merupakan contoh yang baik dari fitur waktu.Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana position encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur waktu tambahan. Time Series Transformer hanya mempelajari embeddings tambahan untuk
static_categorical_features.Covariate dinamis real tambahan dapat digabungkan ke tensor ini, dengan catatan bahwa fitur-fitur ini harus diketahui pada saat prediksi.
num_featuresdi sini sama denganconfig.num_time_features+config.num_dynamic_real_features`. - past_observed_mask (
torch.BoolTensordengan bentuk(batch_size, sequence_length)atau(batch_size, sequence_length, input_size), opsional) — Mask boolean untuk menunjukkan nilaipast_valuesmana yang diamati dan mana yang hilang. Nilai mask dipilih dalam[0, 1]:- 1 untuk nilai yang diamati,
- 0 untuk nilai yang hilang (yaitu NaN yang diganti dengan nol).
- static_categorical_features (
torch.LongTensordengan 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.Tensordengan 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.Tensordengan bentuk(batch_size, prediction_length)atau(batch_size, prediction_length, input_size), opsional) — Nilai masa depan dari deret waktu, yang berfungsi sebagai label untuk model.future_valuesadalah apa yang dibutuhkan Transformer selama pelatihan untuk dipelajari sebagai output, mengingatpast_values.Panjang urutan di sini sama dengan
prediction_length.Lihat notebook demo dan potongan kode untuk detailnya.
Secara opsional, selama pelatihan, nilai yang hilang perlu diganti dengan nol dan ditunjukkan melalui
future_observed_mask.Untuk deret waktu multivariat, dimensi
input_size> 1 diperlukan dan sesuai dengan jumlah variat dalam deret waktu per langkah waktu. - future_time_features (
torch.Tensordengan bentuk(batch_size, prediction_length, num_features)) — Fitur waktu yang diperlukan untuk jendela prediksi, yang secara internal akan ditambahkan oleh model kefuture_values. Fitur-fitur ini bisa berupa hal-hal seperti "bulan dalam setahun", "hari dalam sebulan", dan sebagainya, 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" sebuah 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 hari libur juga merupakan contoh yang baik dari fitur waktu.Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana position encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur waktu tambahan. Time Series Transformer hanya mempelajari embeddings tambahan untuk
static_categorical_features.Covariate dinamis real tambahan dapat digabungkan ke tensor ini, dengan catatan bahwa fitur-fitur ini harus diketahui pada saat prediksi.
num_featuresdi sini sama denganconfig.num_time_features+config.num_dynamic_real_features. - decoder_attention_mask (
torch.LongTensordengan 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 darilast_hidden_state,hidden_states(opsional) danattentions(opsional)last_hidden_statedengan 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 daripast_key_valuesyang dikembalikan oleh model pada tahap decoding sebelumnya, ketikause_cache=Trueatauconfig.use_cache=True.Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada
past_key_valuesyang diteruskan, DynamicCache akan diinisialisasi secara default.Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.
Jika
past_key_valuesdigunakan, pengguna diharapkan hanya memasukkaninput_idsyang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk(batch_size, unprocessed_length)alih-alih semuainput_idsdengan bentuk(batch_size, sequence_length). - use_cache (
bool, opsional) — Jika diset keTrue, state kunci-nilaipast_key_valuesakan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihatpast_key_values).
Mengembalikan
Seq2SeqTSModelOutput atau tuple(torch.Tensor)
A Seq2SeqTSModelOutput atau tuple dari
torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (InformerConfig) dan input.
Metode forward dari InformerModel 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 dari decoder model.Jika
past_key_valuesdigunakan, hanya hidden-state terakhir dari sekuens dengan bentuk(batch_size, 1, hidden_size)yang dioutput.past_key_values (
EncoderDecoderCache, opsional, dikembalikan ketikause_cache=Truediteruskan atau ketikaconfig.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 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 dari decoder pada output setiap layer ditambah output embedding awal yang opsional.
decoder_attentions (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.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 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 dari lapisan cross-attention decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala cross-attention.
encoder_last_hidden_state (
torch.Tensordengan 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 ketikaoutput_hidden_states=Truedilewatkan atau ketikaconfig.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 dari encoder pada output setiap layer ditambah output embedding awal yang opsional.
encoder_attentions (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.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.Tensordengan 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.Tensordengan 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.Tensordengan 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 InformerModel
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = InformerModel.from_pretrained("huggingface/informer-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"],
... static_real_features=batch["static_real_features"],
... future_values=batch["future_values"],
... future_time_features=batch["future_time_features"],
... )
>>> last_hidden_state = outputs.last_hidden_stateInformerForPrediction
kelas transformers.InformerForPrediction
< source >( config: InformerConfig )
Parameter
- config (InformerConfig) — 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 Informer 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
< source >( 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'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)
Parameter
- past_values (
torch.Tensordengan bentuk(batch_size, sequence_length)atau(batch_size, sequence_length, input_size)) — Nilai masa lalu dari deret waktu, yang berfungsi sebagai konteks untuk memprediksi masa depan. Ukuran sekuens dari tensor ini harus lebih besar daricontext_lengthdari model, karena model akan menggunakan ukuran yang lebih besar untuk membuat fitur lag, yaitu nilai tambahan dari masa lalu yang ditambahkan untuk berfungsi sebagai “konteks tambahan”.sequence_lengthdi sini sama denganconfig.context_length+max(config.lags_sequence), yang jika tidak adalags_sequenceyang dikonfigurasi, sama denganconfig.context_length+ 7 (karena secara default, indeks look-back terbesar dalamconfig.lags_sequenceadalah 7). Properti_past_lengthmengembalikan panjang aktual dari masa lalu.past_valuesadalah apa yang diterima oleh encoder Transformer sebagai input (dengan fitur tambahan opsional, sepertistatic_categorical_features,static_real_features,past_time_featuresdan lag).Secara opsional, nilai yang hilang perlu diganti dengan nol dan ditunjukkan melalui
past_observed_mask.Untuk deret waktu multivariat, dimensi
input_size> 1 diperlukan dan sesuai dengan jumlah variat dalam deret waktu per langkah waktu. - past_time_features (
torch.Tensordengan bentuk(batch_size, sequence_length, num_features)) — Fitur waktu yang wajib, yang akan ditambahkan secara internal oleh model kepast_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” sebuah 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 hari libur juga merupakan contoh yang baik dari fitur waktu.Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana position encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur waktu tambahan. Time Series Transformer hanya mempelajari embeddings tambahan untuk
static_categorical_features.Covariate dinamis real tambahan dapat digabungkan ke tensor ini, dengan catatan bahwa fitur-fitur ini harus diketahui pada saat prediksi.
num_featuresdi sini sama denganconfig.num_time_features+config.num_dynamic_real_features`. - past_observed_mask (
torch.BoolTensordengan bentuk(batch_size, sequence_length)atau(batch_size, sequence_length, input_size), opsional) — Mask boolean untuk menunjukkan nilaipast_valuesmana yang diamati dan mana yang hilang. Nilai mask dipilih dalam[0, 1]:- 1 untuk nilai yang diamati,
- 0 untuk nilai yang hilang (yaitu NaN yang diganti dengan nol).
- static_categorical_features (
torch.LongTensordengan 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.Tensordengan 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.Tensordengan bentuk(batch_size, prediction_length)atau(batch_size, prediction_length, input_size), opsional) — Nilai masa depan dari deret waktu, yang berfungsi sebagai label untuk model.future_valuesadalah apa yang dibutuhkan Transformer selama pelatihan untuk dipelajari sebagai output, mengingatpast_values.Panjang urutan di sini sama dengan
prediction_length.Lihat notebook demo dan potongan kode untuk detailnya.
Secara opsional, selama pelatihan, nilai yang hilang perlu diganti dengan nol dan ditunjukkan melalui
future_observed_mask.Untuk deret waktu multivariat, dimensi
input_size> 1 diperlukan dan sesuai dengan jumlah variat dalam deret waktu per langkah waktu. - future_time_features (
torch.Tensordengan bentuk(batch_size, prediction_length, num_features)) — Fitur waktu yang diperlukan untuk jendela prediksi, yang secara internal akan ditambahkan oleh model kefuture_values. Fitur-fitur ini bisa berupa hal-hal seperti "bulan dalam setahun", "hari dalam sebulan", dan sebagainya, 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" sebuah 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 hari libur juga merupakan contoh yang baik dari fitur waktu.Fitur-fitur ini berfungsi sebagai “positional encodings” dari input. Jadi, berbeda dengan model seperti BERT, di mana position encodings dipelajari dari awal secara internal sebagai parameter model, Time Series Transformer memerlukan penyediaan fitur waktu tambahan. Time Series Transformer hanya mempelajari embeddings tambahan untuk
static_categorical_features.Covariate dinamis real tambahan dapat digabungkan ke tensor ini, dengan catatan bahwa fitur-fitur ini harus diketahui pada saat prediksi.
num_featuresdi sini sama denganconfig.num_time_features+config.num_dynamic_real_features. - future_observed_mask (
torch.BoolTensordengan bentuk(batch_size, sequence_length)atau(batch_size, sequence_length, input_size), opsional) — Mask boolean untuk menunjukkan nilaifuture_valuesyang 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.LongTensordengan 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 darilast_hidden_state,hidden_states(opsional) danattentions(opsional)last_hidden_statedengan 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 daripast_key_valuesyang dikembalikan oleh model pada tahap decoding sebelumnya, ketikause_cache=Trueatauconfig.use_cache=True.Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada
past_key_valuesyang diteruskan, DynamicCache akan diinisialisasi secara default.Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.
Jika
past_key_valuesdigunakan, pengguna diharapkan hanya memasukkaninput_idsyang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk(batch_size, unprocessed_length)alih-alih semuainput_idsdengan bentuk(batch_size, sequence_length). - use_cache (
bool, opsional) — Jika diset keTrue, state kunci-nilaipast_key_valuesakan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihatpast_key_values).
Mengembalikan
Seq2SeqTSModelOutput atau tuple(torch.Tensor)
A Seq2SeqTSModelOutput atau tuple dari
torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (InformerConfig) dan input.
Metode forward dari InformerForPrediction 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 dari decoder model.Jika
past_key_valuesdigunakan, hanya hidden-state terakhir dari sekuens dengan bentuk(batch_size, 1, hidden_size)yang dioutput.past_key_values (
EncoderDecoderCache, opsional, dikembalikan ketikause_cache=Truediteruskan atau ketikaconfig.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 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 dari decoder pada output setiap layer ditambah output embedding awal yang opsional.
decoder_attentions (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.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 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 dari lapisan cross-attention decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala cross-attention.
encoder_last_hidden_state (
torch.Tensordengan 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 ketikaoutput_hidden_states=Truedilewatkan atau ketikaconfig.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 dari encoder pada output setiap layer ditambah output embedding awal yang opsional.
encoder_attentions (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.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.Tensordengan 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.Tensordengan 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.Tensordengan 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 InformerForPrediction
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = InformerForPrediction.from_pretrained(
... "huggingface/informer-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"],
... static_real_features=batch["static_real_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"],
... static_real_features=batch["static_real_features"],
... future_time_features=batch["future_time_features"],
... )
>>> mean_prediction = outputs.sequences.mean(dim=1)