Transformers documentation
Autoformer
Bu model 2021-06-24 tarihinde HF papers'ta yayımlandı ve 2023-05-30 tarihinde Hugging Face Transformers'a katkıda bulunuldu.
Autoformer
Genel Bakış
Autoformer modeli, Haixu Wu, Jiehui Xu, Jianmin Wang ve Mingsheng Long tarafından Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting makalesinde önerilmiştir.
Bu model, Transformer'ı, tahmin süreci sırasında trend ve mevsimsel bileşenleri kademeli olarak ayrıştırabilen derin bir ayrıştırma mimarisi olarak genişletir.
Makalenin özeti aşağıdaki gibidir:
Tahmin süresinin uzatılması, aşırı hava erken uyarısı ve uzun vadeli enerji tüketimi planlaması gibi gerçek dünya uygulamaları için kritik bir gerekliliktir. Bu makale, zaman serilerinin uzun vadeli tahmin sorununu ele alır. Önceki Transformer tabanlı modeller, uzun menzilli bağımlılıkları keşfetmek için çeşitli öz-dikkat (self-attention) mekanizmaları benimsemiştir. Ancak, uzun vadeli geleceğin karmaşık zaman örüntüleri, modelin güvenilir bağımlılıkları bulmasını engeller. Ayrıca, Transformer'lar uzun seriler için verimlilik sağlamak üzere nokta bazlı öz-dikkatlerin seyreltilmiş (sparse) versiyonlarını benimsemek zorunda kalır; bu durum bilgi kullanımında bir darboğaza yol açar. Transformer'ların ötesine geçerek, Auto-Correlation mekanizmasına sahip yeni bir ayrıştırma (decomposition) mimarisi olan Autoformer'ı tasarladık. Serilerin ayrıştırılmasına yönelik ön işleme geleneğinden koptuk ve bunu derin modellerin temel iç bloğu olarak yeniledik. Bu tasarım, Autoformer'a karmaşık zaman serileri için kademeli ayrıştırma yetenekleri kazandırır. Ayrıca, stokastik süreç teorisinden ilham alarak, Auto-Correlation mekanizmasını serilerin periyodikliğine dayalı olarak tasarladık; bu mekanizma bağımlılık keşfini ve temsil birleştirmeyi alt seri (sub-series) düzeyinde gerçekleştirir. Auto-Correlation, hem verimlilik hem de doğruluk açısından öz-dikkatten üstündür. Uzun vadeli tahminlerde Autoformer, enerji, trafik, ekonomi, hava ve hastalık olmak üzere beş pratik uygulamayı kapsayan altı benchmark üzerinde %38'lik bir göreli iyileşmeyle en iyi (state-of-the-art) doğruluğu elde eder.
Bu model elisim ve kashif tarafından katkıda bulunmuştur. Orijinal kod burada bulunabilir.
Kaynaklar
Başlamanıza yardımcı olmak için resmi Hugging Face ve topluluk (🌎 ile belirtilen) kaynaklarının listesi. Burada yer alacak bir kaynak göndermekle ilgileniyorsanız, bir Pull Request açmaktan çekinmeyin; inceleyeceğiz! Kaynağın, mevcut bir kaynağı tekrarlamak yerine ideal olarak yeni bir şey göstermesi beklenir.
- HuggingFace blog'daki Autoformer blog yazısına göz atın: Evet, Transformers Zaman Serisi Tahmini için Etkilidir (+ Autoformer)
AutoformerConfig
sınıf transformers.AutoformerConfig
< 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] | 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 )
Parametreler
- is_encoder_decoder (
bool, isteğe bağlı, varsayılanTrue) — Modelin bir kodlayıcı/çözücü olarak kullanılıp kullanılmadığı. - prediction_length (
int, isteğe bağlı) — Çözücü için tahmin uzunluğu. Başka bir deyişle, modelin tahmin ufku. - context_length (
int, isteğe bağlı, varsayılanprediction_length) — Kodlayıcı için bağlam uzunluğu. Ayarlanmazsa, bağlam uzunluğuprediction_lengthile aynı olacaktır. - distribution_output (
string, isteğe bağlı, varsayılan"student_t") — Modelin dağılım çıkış başlığı. “student_t”, “normal” veya “negative_binomial” olabilir. - loss (
string, isteğe bağlı, varsayılan"nll") —distribution_outputbaşlığına karşılık gelen modelin kayıp fonksiyonu. Parametrik dağılımlar için negatif log olma olasılığıdır (nll) - şu anda desteklenen tek kayıp fonksiyonu budur. - input_size (
int, isteğe bağlı, varsayılan 1) — Varsayılan olarak tek değişkenli hedefler için 1 olan hedef değişkenin boyutu. Çok değişkenli hedefler durumunda > 1 olur. - lags_sequence (
list[int], isteğe bağlı, varsayılan[1, 2, 3, 4, 5, 6, 7]) — Girdi zaman serisinin kovaryatlar olarak gecikmeleri, genellikle frekans tarafından belirlenir. Varsayılan değer[1, 2, 3, 4, 5, 6, 7]'dir. - scaling (
bool, isteğe bağlı, varsayılanTrue) — Girdi hedeflerinin ölçeklendirilip ölçeklendirilmeyeceğini belirtir. - num_time_features (
int, isteğe bağlı, varsayılan 0) — Girdi zaman serisindeki zaman özelliklerinin sayısı. - num_dynamic_real_features (
int, isteğe bağlı, varsayılan 0) — Dinamik gerçek değerli özelliklerin sayısı. - num_static_categorical_features (
int, isteğe bağlı, varsayılan 0) — Statik kategorik özelliklerin sayısı. - num_static_real_features (
int, isteğe bağlı, varsayılan 0) — Statik gerçek değerli özelliklerin sayısı. - cardinality (
list[int], isteğe bağlı) — Statik kategorik özelliklerin her biri için kardinalite (farklı değer sayısı).num_static_categorical_featuresile aynı uzunlukta, tamsayılardan oluşan bir liste olmalıdır.num_static_categorical_features> 0 iseNoneolamaz. - embedding_dimension (
list[int], isteğe bağlı) — Gömme ve gizli durumların boyutluluğu. - d_model (
int, isteğe bağlı, varsayılan64) — Kodlayıcı katmanlarının ve pooler katmanının boyutu. - encoder_attention_heads (
int, isteğe bağlı, varsayılan2) — Transformer kodlayıcısındaki her dikkat katmanı için dikkat başı sayısı. - decoder_attention_heads (
int, isteğe bağlı, varsayılan2) — Transformer decoder'ındaki her dikkat katmanı için dikkat başı sayısı. - encoder_layers (
int, isteğe bağlı, varsayılan2) — Transformer kodlayıcısındaki gizli katman sayısı. Ayarlanmazsanum_layersile aynı değeri kullanır. - decoder_layers (
int, isteğe bağlı, varsayılan2) — Transformer decoder'ındaki gizli katman sayısı. Ayarlanmazsanum_layersile aynı değeri kullanır. - encoder_ffn_dim (
int, isteğe bağlı, varsayılan32) — Encoder'daki “ara” (genellikle feed-forward olarak adlandırılan) katmanın boyutluğu. - decoder_ffn_dim (
int, isteğe bağlı, varsayılan32) — Decoder'daki “ara” (genellikle feed-forward olarak adlandırılan) katmanın boyutluluğu. - activation_function (
str, isteğe bağlı, varsayılangelu) — Çözücüdeki doğrusal olmayan aktivasyon fonksiyonu (fonksiyon veya dize). Örneğin,"gelu","relu","silu"vb. - dropout (
Union[float, int], isteğe bağlı, varsayılan0.1) — Tüm dropout katmanları için oran. - encoder_layerdrop (
Union[float, int], isteğe bağlı, varsayılan0.1) — Encoder için LayerDrop olasılığı. Daha fazla ayrıntı için [LayerDrop makalesine](bkz. https://huggingface.co/papers/1909.11556) bakın. - decoder_layerdrop (
Union[float, int], isteğe bağlı, varsayılan0.1) — Çözücü için LayerDrop olasılığı. Daha fazla ayrıntı için [LayerDrop makalesine](bkz. https://huggingface.co/papers/1909.11556) bakın. - attention_dropout (
Union[float, int], isteğe bağlı, varsayılan0.1) — Dikkat olasılıkları için dropout oranı. - activation_dropout (
Union[float, int], isteğe bağlı, varsayılan0.1) — Tamamen bağlı katmandaki aktivasyonlar için dropout oranı. - num_parallel_samples (
int, isteğe bağlı, varsayılan 100) — Çıkarımın her zaman adımı için paralel olarak üretilecek örnek sayısı. - init_std (
float, isteğe bağlı, varsayılan0.02) — Tüm ağırlık matrislerini başlatmak için kullanılan truncated_normal_initializer'ın standart sapması. - use_cache (
bool, isteğe bağlı, varsayılanTrue) — Modelin son anahtar/değer dikkatlerini (tüm modellerde kullanılmaz) döndürüp döndürmeyeceği. Yalnızcaconfig.is_decoder=Trueolduğunda veya model yalnızca çözücü tabanlı üretken bir model olduğunda geçerlidir. - label_length (
int, isteğe bağlı, varsayılan 10) — Autoformer decoder'ının başlangıç token uzunluğu, doğrudan çok adımlı tahmin (yani otoregresif olmayan üretim) için kullanılır. - moving_average (
int, isteğe bağlı, varsayılan 25) — Hareketli ortalamanın pencere boyutu. Uygulamada, Decomposition Katmanı'ndaki AvgPool1d'nin çekirdek boyutudur. - autocorrelation_factor (
int, isteğe bağlı, varsayılan 3) — “Attention” (yani AutoCorrelation mekanizması) faktörü, üstel k otokorelasyon gecikmelerini bulmak için kullanılır. Makalede, bu değerin 1 ile 5 arasında bir sayı olarak ayarlanması önerilmektedir.
Bu, bir AutoformerModel yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Autoformer modelinin örneklenmesi ve model mimarisinin tanımlanması için kullanılır. Varsayılan değerlerle bir yapılandırma örneği oluşturmak, huggingface/autoformer-tourism-monthly yapılandırmasına benzer bir yapılandırma elde edilmesini sağlar.
Yapılandırma nesneleri PreTrainedConfig sınıfından devralır ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için PreTrainedConfig belgesini okuyun.
Örnek:
>>> 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.configAutoformerModel
sınıf transformers.AutoformerModel
< source >( config: AutoformerConfig )
Parametreler
- config (AutoformerConfig) — Modelin tüm parametrelerini içeren model yapılandırma sınıfı. Bir yapılandırma dosyasıyla başlatmak, modelle ilişkili ağırlıkları yüklemez, yalnızca yapılandırmayı yükler. Model ağırlıklarını yüklemek için from_pretrained() yöntemine bakın.
Üzerinde herhangi bir özel başlık olmadan ham gizli durumları (hidden-states) üreten çıplak Autoformer Model.
Bu model PreTrainedModel sınıfından devralır. Kütüphanenin tüm modelleri için uyguladığı genel yöntemler (indirme veya kaydetme, giriş gömme boyutlarını yeniden boyutlandırma, başları budama vb.) için üst sınıf belgelendirmesine bakın.
Bu model aynı zamanda bir PyTorch torch.nn.Module alt sınıfıdır. Bunu standart bir PyTorch Module olarak kullanın ve genel kullanım ve davranışla ilgili tüm konular için PyTorch dokümantasyonuna başvurun.
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'> ) → AutoformerModelOutput or tuple(torch.Tensor)
Parametreler
- past_values (
torch.Tensorşeklinde(batch_size, sequence_length)) — Zaman serisinin geçmiş değerleri, geleceği tahmin etmek için bağlam olarak hizmet eder. Bu değerler, gecikmeleri (lags) içerebilir; yani “ek bağlam” olarak hizmet etmek amacıyla eklenen geçmişten ek değerler.past_valuesTransformer kodlayıcısının girdi olarak aldığı şeydir (isteğe bağlı ek özellikler, örneğinstatic_categorical_features,static_real_features,past_time_features).Buradaki dizi uzunluğu
context_length+max(config.lags_sequence)'e eşittir.Eksik değerler sıfırlarla değiştirilmelidir.
- past_time_features (
torch.Tensorşeklinde(batch_size, sequence_length, num_features), isteğe bağlı) — Modelin içsel olarakpast_values. eekleyeceği isteğe bağlı zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, zaman serisinin “yaşamının hangi noktasında” olduğunu modelin bilmesine yardımcı olan, temelde “yaş” özellikleri de olabilir. Yaş özellikleri, uzak geçmiş zaman adımları için küçük değerlere sahiptir ve mevcut zaman adımına yaklaştıkça monoton olarak artar.Bu özellikler, girdilerin “konumsal kodlamaları” olarak görev yapar. Dolayısıyla, konumsal kodlamaların model parametreleri olarak sıfırdan öğrenildiği BERT gibi bir modelin aksine, Time Series Transformer ek zaman özelliklerinin sağlanmasını gerektirir.
Autoformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir. - past_observed_mask (
torch.BoolTensorşeklinde(batch_size, sequence_length), isteğe bağlı) — Hangipast_valuesdeğerlerin gözlemlendiğini, hangilerinin eksik olduğunu belirtmek için Boolean mask. Mask değerleri şu aralıktan seçilir: gözlemlenen değerler için 1, eksik değerler için 0 (yani sıfırlarla değiştirilen NaN'lar).[0, 1]:- gözlemlenen değerler için 1
- eksik (yani sıfırlarla değiştirilen NaN'lar) olan değerler için 0.
- static_categorical_features (
torch.LongTensorşeklinde(batch_size, number of static categorical features), isteğe bağlı) — Modelin gömme (embedding) öğreneceği ve zaman serisi değerlerine ekleyeceği isteğe bağlı statik kategorik özellikler. Statik kategorik özellikler, tüm zaman adımları için aynı değere sahip olan (zamana göre statik) özelliklerdir. Statik kategorik bir özelliğin tipik bir örneği, bir zaman serisi kimliğidir.Statik kategorik özellikler, tüm zaman adımları için aynı değere sahip olan (zaman içinde statik) özelliklerdir.
Statik kategorik bir özelliğin tipik bir örneği, zaman serisi kimliğidir.
- static_real_features (
torch.Tensorşeklinde(batch_size, number of static real features), isteğe bağlı) — Modelin zaman serisi değerlerine ekleyeceği isteğe bağlı statik gerçek özellikler. Statik gerçek özellikler, tüm zaman adımları için aynı değere sahip olan (zamana göre statik) özelliklerdir. Statik gerçek bir özelliğin tipik bir örneği, promosyon bilgisidir.Statik gerçek özellikler, tüm zaman adımları için aynı değere sahip olan (zamana göre statik) özelliklerdir.
Statik gerçek bir özelliğin tipik bir örneği, promosyon bilgileridir.
- future_values (
torch.Tensorşeklinde(batch_size, prediction_length)) — Zaman serisinin, model için etiket olarak kullanılan gelecek değerleri.future_valuesverildiğinde, Transformer'ın öğrenip çıkarması gereken şeydir. Ayrıntılar için demo defterine ve kod parçacıklarına bakın. Eksik değerler sıfırlarla değiştirilmelidir.past_values.Detaylar için demo defterine ve kod parçacıklarına bakın.
Eksik değerler sıfırlarla değiştirilmelidir.
- future_time_features (
torch.Tensorşeklinde(batch_size, prediction_length, num_features), isteğe bağlı) — Modelin içsel olarakfuture_values. şuna ekleyeceği isteğe bağlı zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, bir zaman serisinin “yaşamının hangi noktasında” olduğunu modelin bilmesine yardımcı olan, temelde “yaş” özellikleri de olabilir. Yaş özellikleri, uzak geçmiş zaman adımları için küçük değerlere sahiptir ve mevcut zaman adımına yaklaştıkça monoton olarak artar.Bu özellikler, girdilerin “konumsal kodlamaları” olarak görev yapar. Dolayısıyla, konumsal kodlamaların model parametreleri olarak sıfırdan öğrenildiği BERT gibi bir modelin aksine, Time Series Transformer ek özelliklerin sağlanmasını gerektirir.
Autoformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir. - decoder_attention_mask (
torch.LongTensor, şekli(batch_size, target_sequence_length), isteğe bağlı) — Belirli token indekslerinde dikkat işleminin uygulanmasını önlemek için kullanılan maske. Varsayılan olarak, modelin geleceği tahmin ederken yalnızca önceki girdilere bakmasını sağlamak için nedensel bir maske kullanılır. - encoder_outputs (
tuple(tuple(torch.Tensor), opsiyonel) — Demet,last_hidden_state,hidden_states(opsiyonel) veattentions(opsiyonel) öğelerinden oluşur.last_hidden_state,(batch_size, sequence_length, hidden_size)biçiminde (opsiyonel), kodlayıcının son katmanının çıktısındaki gizli durumlar dizisidir. Çözücüdeki çapraz dikkat (cross-attention) mekanizmasında kullanılır. - past_key_values (
~cache_utils.Cache, isteğe bağlı) — Sıralı çözümlemeyi hızlandırmak için kullanılabilen önceden hesaplanmış gizli durumlar (self-attention ve cross-attention bloklarındaki anahtar ve değerler). Bu genelliklepast_key_valuesdeğerinin, çözümlemenin önceki bir aşamasında model tarafından döndürülenuse_cache=Trueveyaconfig.use_cache=True.Girdi olarak yalnızca Cache örneği kabul edilir, kv cache kılavuzumuza bakın.
past_key_valuesgeçirilmezse, varsayılan olarak DynamicCache başlatılır.Model, girdi olarak verilen aynı önbellek biçimini çıktı olarak üretecektir.
past_key_valueskullanılıyorsa, kullanıcının tüminput_ids(şekli(batch_size, sequence_length)) yerine, bu modele geçmiş anahtar değer durumları verilmemiş olan, işlenmemişinput_ids(şekli(batch_size, unprocessed_length)) girmesi beklenir. - use_cache (
bool, isteğe bağlı) —Trueolarak ayarlanırsa,past_key_valuesanahtar değer durumları döndürülür ve çözümlemeyi hızlandırmak için kullanılabilir (bkz.past_key_values).
Dönüş değeri
AutoformerModelOutput veya tuple(torch.Tensor)
AutoformerModelOutput veya bir torch.Tensor demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (AutoformerConfig) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
AutoformerModel forward metodu, __call__ özel metodunu geçersiz kılar.
İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine
Moduleörneğini çağırmak gerekir; çünkü önceki, ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.
last_hidden_state (
torch.Tensor, şekli(batch_size, sequence_length, hidden_size)) — Modelin decoder'ının son katmanının çıktısındaki gizli durumlar dizisi.past_key_valueskullanılırsa, yalnızca(batch_size, 1, hidden_size)biçimindeki dizilerin son gizli durumu (hidden-state) çıktı olarak verilir.trend (
torch.Tensor, şekli(batch_size, sequence_length, hidden_size)) — Her zaman serisi için trend tensörü.past_key_values (
Cache, isteğe bağlı,use_cache=Truegeçirildiğinde veyaconfig.use_cache=Trueolduğunda döndürülür) — Bir Cache örneğidir. Daha fazla ayrıntı için kv cache kılavuzumuza bakın.Sıralı çözümlemeyi hızlandırmak için (bkz.
past_key_valuesgirdisi) kullanılabilen, önceden hesaplanmış gizli durumları (self-attention bloklarındaki ve cross-attention bloklarındaki anahtar ve değerler) içerir.decoder_hidden_states (
tuple[torch.Tensor], isteğe bağlı,output_hidden_states=Truegeçirildiğinde veyaconfig.output_hidden_states=Trueolduğunda döndürülür) —torch.Tensor(modelin bir gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için birer tane) içeren bir tuple, şekli(batch_size, sequence_length, hidden_size).Her katmanın çıktısında ve başlangıç gömme çıktılarında dekodlayıcının gizli durumları.
decoder_attentions (
tuple[torch.Tensor], isteğe bağlı,output_attentions=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğunda döndürülür) —torch.Tensor(katman başına bir tane) içeren bir tuple, şekli(batch_size, num_heads, sequence_length, sequence_length).Dikkat ağırlıkları, dikkat softmax'ından sonra, öz-dikkat kafalarında ağırlıklı ortalamanın hesaplanmasında kullanılan dekoderin
cross_attentions (
tuple[torch.Tensor], isteğe bağlı,output_attentions=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğunda döndürülür) —torch.Tensor(katman başına bir tane) içeren bir tuple, şekli(batch_size, num_heads, sequence_length, sequence_length).Dekoderin çapraz dikkat katmanının dikkat ağırlıkları, dikkat softmax'ından sonra, çapraz dikkat başlıklarında ağırlıklı ortalamanın hesaplanmasında kullanılır.
encoder_last_hidden_state (
torch.Tensor, şekli(batch_size, sequence_length, hidden_size), isteğe bağlı) — Modelin kodlayıcısının son katmanının çıktısındaki gizli durumlar dizisi.encoder_hidden_states (
tuple[torch.Tensor], isteğe bağlı,output_hidden_states=Truegeçirildiğinde veyaconfig.output_hidden_states=Trueolduğunda döndürülür) —torch.Tensor(modelin bir gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için birer tane) içeren,(batch_size, sequence_length, hidden_size)biçiminde bir demet.Her katmanın çıktısında ve başlangıç gömme çıktılarında kodlayıcının gizli durumları.
encoder_attentions (
tuple[torch.Tensor], isteğe bağlı,output_attentions=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğunda döndürülür) —torch.Tensor(katman başına bir tane) içeren bir tuple, şekli(batch_size, num_heads, sequence_length, sequence_length).Dikkat yumuşatma (attention softmax) sonrasında, öz-dikkat (self-attention) kafalarında ağırlıklı ortalamanın hesaplanmasında kullanılan kodlayıcının dikkat ağırlıkları.
loc (
torch.Tensor, şekli(batch_size,)veya(batch_size, input_size), isteğe bağlı) — Modelin aynı büyüklükte girdiler almasını sağlamak için kullanılan her zaman serisinin bağlam penceresindeki değerleri kaydırır ve ardından değerleri orijinal büyüklüğe geri kaydırır.scale (
torch.Tensor, şekli(batch_size,)veya(batch_size, input_size), isteğe bağlı) — Her zaman serisinin bağlam penceresindeki ölçekleme değerleri; modelin aynı büyüklükte girdiler almasını sağlamak için kullanılır ve ardından orijinal büyüklüğe geri ölçeklenmek için kullanılır. static_features: (torch.Tensor, şekli(batch_size, feature size), isteğe bağlı): Bir batch içindeki her zaman serisinin, çıkarım sırasında kovaryatlara kopyalanan statik özellikleri.static_features (
torch.Tensor, şekli(batch_size, feature size), isteğe bağlı) — Bir batch içindeki her zaman serisinin, çıkarım sırasında kovaryatlara kopyalanan statik özellikleri.
Örnekler:
>>> 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_stateAutoformerForPrediction
sınıf transformers.AutoformerForPrediction
< source >( config: AutoformerConfig )
Parametreler
- config (AutoformerConfig) — Modelin tüm parametrelerini içeren model yapılandırma sınıfı. Bir yapılandırma dosyasıyla başlatmak, modelle ilişkili ağırlıkları yüklemez, yalnızca yapılandırmayı yükler. Model ağırlıklarını yüklemek için from_pretrained() yöntemine bakın.
Zaman serisi tahmini için üstünde bir dağılım başlığı bulunan Autoformer Modeli.
Bu model PreTrainedModel sınıfından devralır. Kütüphanenin tüm modelleri için uyguladığı genel yöntemler (indirme veya kaydetme, giriş gömme boyutlarını yeniden boyutlandırma, başları budama vb.) için üst sınıf belgelendirmesine bakın.
Bu model aynı zamanda bir PyTorch torch.nn.Module alt sınıfıdır. Bunu standart bir PyTorch Module olarak kullanın ve genel kullanım ve davranışla ilgili tüm konular için PyTorch dokümantasyonuna başvurun.
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'> ) → Seq2SeqTSPredictionOutput or tuple(torch.Tensor)
Parametreler
- past_values (
torch.Tensorşeklinde(batch_size, sequence_length)) — Zaman serisinin geçmiş değerleri, geleceği tahmin etmek için bağlam olarak hizmet eder. Bu değerler, gecikmeleri (lags) içerebilir; yani “ek bağlam” olarak hizmet etmek amacıyla eklenen geçmişten ek değerler.past_valuesTransformer kodlayıcısının girdi olarak aldığı şeydir (isteğe bağlı ek özellikler, örneğinstatic_categorical_features,static_real_features,past_time_features).Buradaki dizi uzunluğu
context_length+max(config.lags_sequence)'e eşittir.Eksik değerler sıfırlarla değiştirilmelidir.
- past_time_features (
torch.Tensorşeklinde(batch_size, sequence_length, num_features), isteğe bağlı) — Modelin içsel olarakpast_values. eekleyeceği isteğe bağlı zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, zaman serisinin “yaşamının hangi noktasında” olduğunu modelin bilmesine yardımcı olan, temelde “yaş” özellikleri de olabilir. Yaş özellikleri, uzak geçmiş zaman adımları için küçük değerlere sahiptir ve mevcut zaman adımına yaklaştıkça monoton olarak artar.Bu özellikler, girdilerin “konumsal kodlamaları” olarak görev yapar. Dolayısıyla, konumsal kodlamaların model parametreleri olarak sıfırdan öğrenildiği BERT gibi bir modelin aksine, Time Series Transformer ek zaman özelliklerinin sağlanmasını gerektirir.
Autoformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir. - past_observed_mask (
torch.BoolTensorşeklinde(batch_size, sequence_length), isteğe bağlı) — Hangipast_valuesdeğerlerin gözlemlendiğini, hangilerinin eksik olduğunu belirtmek için Boolean mask. Mask değerleri şu aralıktan seçilir: gözlemlenen değerler için 1, eksik değerler için 0 (yani sıfırlarla değiştirilen NaN'lar).[0, 1]:- gözlemlenen değerler için 1
- eksik (yani sıfırlarla değiştirilen NaN'lar) olan değerler için 0.
- static_categorical_features (
torch.LongTensorşeklinde(batch_size, number of static categorical features), isteğe bağlı) — Modelin gömme (embedding) öğreneceği ve zaman serisi değerlerine ekleyeceği isteğe bağlı statik kategorik özellikler. Statik kategorik özellikler, tüm zaman adımları için aynı değere sahip olan (zamana göre statik) özelliklerdir. Statik kategorik bir özelliğin tipik bir örneği, bir zaman serisi kimliğidir.Statik kategorik özellikler, tüm zaman adımları için aynı değere sahip olan (zaman içinde statik) özelliklerdir.
Statik kategorik bir özelliğin tipik bir örneği, zaman serisi kimliğidir.
- static_real_features (
torch.Tensorşeklinde(batch_size, number of static real features), isteğe bağlı) — Modelin zaman serisi değerlerine ekleyeceği isteğe bağlı statik gerçek özellikler. Statik gerçek özellikler, tüm zaman adımları için aynı değere sahip olan (zamana göre statik) özelliklerdir. Statik gerçek bir özelliğin tipik bir örneği, promosyon bilgisidir.Statik gerçek özellikler, tüm zaman adımları için aynı değere sahip olan (zamana göre statik) özelliklerdir.
Statik gerçek bir özelliğin tipik bir örneği, promosyon bilgileridir.
- future_values (
torch.Tensorşeklinde(batch_size, prediction_length)) — Zaman serisinin, model için etiket olarak kullanılan gelecek değerleri.future_valuesverildiğinde, Transformer'ın öğrenip çıkarması gereken şeydir. Ayrıntılar için demo defterine ve kod parçacıklarına bakın. Eksik değerler sıfırlarla değiştirilmelidir.past_values.Detaylar için demo defterine ve kod parçacıklarına bakın.
Eksik değerler sıfırlarla değiştirilmelidir.
- future_time_features (
torch.Tensorşeklinde(batch_size, prediction_length, num_features), isteğe bağlı) — Modelin içsel olarakfuture_values. şuna ekleyeceği isteğe bağlı zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, bir zaman serisinin “yaşamının hangi noktasında” olduğunu modelin bilmesine yardımcı olan, temelde “yaş” özellikleri de olabilir. Yaş özellikleri, uzak geçmiş zaman adımları için küçük değerlere sahiptir ve mevcut zaman adımına yaklaştıkça monoton olarak artar.Bu özellikler, girdilerin “konumsal kodlamaları” olarak görev yapar. Dolayısıyla, konumsal kodlamaların model parametreleri olarak sıfırdan öğrenildiği BERT gibi bir modelin aksine, Time Series Transformer ek özelliklerin sağlanmasını gerektirir.
Autoformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir. - future_observed_mask (
torch.BoolTensorşeklinde(batch_size, sequence_length)veya(batch_size, sequence_length, input_size), isteğe bağlı) — hangifuture_valuesdeğerlerin gözlemlendiğini, hangilerinin eksik olduğunu belirtmek için kullanılan Boole maskesi. Maskede seçilen değerler aralığındadır: gözlemlenen değerler için 1, eksik değerler için 0 (yani sıfırlarla değiştirilen NaN'lar). Bu maske, son kayıp hesabı için eksik değerleri elemek üzere kullanılır.[0, 1]:- gözlemlenen değerler için 1
- eksik (yani sıfırlarla değiştirilen NaN'lar) olan değerler için 0.
Bu maske, son kayıp hesabı için eksik değerleri elemek için kullanılır.
- decoder_attention_mask (
torch.LongTensor, şekli(batch_size, target_sequence_length), isteğe bağlı) — Belirli token indekslerinde dikkat işleminin uygulanmasını önlemek için kullanılan maske. Varsayılan olarak, modelin geleceği tahmin ederken yalnızca önceki girdilere bakmasını sağlamak için nedensel bir maske kullanılır. - encoder_outputs (
tuple(tuple(torch.Tensor), opsiyonel) — Demet,last_hidden_state,hidden_states(opsiyonel) veattentions(opsiyonel) öğelerinden oluşur.last_hidden_state,(batch_size, sequence_length, hidden_size)biçiminde (opsiyonel), kodlayıcının son katmanının çıktısındaki gizli durumlar dizisidir. Çözücüdeki çapraz dikkat (cross-attention) mekanizmasında kullanılır. - past_key_values (
~cache_utils.Cache, isteğe bağlı) — Sıralı çözümlemeyi hızlandırmak için kullanılabilen önceden hesaplanmış gizli durumlar (self-attention ve cross-attention bloklarındaki anahtar ve değerler). Bu genelliklepast_key_valuesdeğerinin, çözümlemenin önceki bir aşamasında model tarafından döndürülenuse_cache=Trueveyaconfig.use_cache=True.Girdi olarak yalnızca Cache örneği kabul edilir, kv cache kılavuzumuza bakın.
past_key_valuesgeçirilmezse, varsayılan olarak DynamicCache başlatılır.Model, girdi olarak verilen aynı önbellek biçimini çıktı olarak üretecektir.
past_key_valueskullanılıyorsa, kullanıcının tüminput_ids(şekli(batch_size, sequence_length)) yerine, bu modele geçmiş anahtar değer durumları verilmemiş olan, işlenmemişinput_ids(şekli(batch_size, unprocessed_length)) girmesi beklenir. - use_cache (
bool, isteğe bağlı) —Trueolarak ayarlanırsa,past_key_valuesanahtar değer durumları döndürülür ve çözümlemeyi hızlandırmak için kullanılabilir (bkz.past_key_values).
Dönüş değeri
Seq2SeqTSPredictionOutput veya tuple(torch.Tensor)
Bir Seq2SeqTSPredictionOutput veya bir torch.Tensor demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (AutoformerConfig) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
AutoformerForPrediction forward metodu, __call__ özel metodunu geçersiz kılar.
İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine
Moduleörneğini çağırmak gerekir; çünkü önceki, ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.
loss (
torch.Tensor, şekli(1,), isteğe bağlı,future_valuessağlandığında döndürülür) — Dağılımsal kayıp.params (
torch.Tensor, şekli(batch_size, num_samples, num_params)) — Seçilen dağılımın parametreleri.past_key_values (
EncoderDecoderCache, isteğe bağlı,use_cache=Truegeçirildiğinde veyaconfig.use_cache=Trueolduğunda döndürülür) — Bir EncoderDecoderCache örneğidir. Daha fazla ayrıntı için kv önbellek kılavuzumuza bakın.Sıralı çözümlemeyi hızlandırmak için (bkz.
past_key_valuesgirdisi) kullanılabilen, önceden hesaplanmış gizli durumları (self-attention bloklarındaki ve cross-attention bloklarındaki anahtar ve değerler) içerir.decoder_hidden_states (
tuple(torch.Tensor), isteğe bağlı,output_hidden_states=Truegeçirildiğinde veyaconfig.output_hidden_states=Trueolduğunda döndürülür) —torch.Tensor(modelin bir gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için birer tane) içeren,(batch_size, sequence_length, hidden_size)biçiminde bir demet.Her katmanın çıktısında ve başlangıç gömme çıktılarında dekodlayıcının gizli durumları.
decoder_attentions (
tuple(torch.Tensor), isteğe bağlı,output_attentions=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğunda döndürülür) —torch.Tensor(katman başına bir tane) içeren bir tuple, şekli(batch_size, num_heads, sequence_length, sequence_length).Dikkat ağırlıkları, dikkat softmax'ından sonra, öz-dikkat kafalarında ağırlıklı ortalamanın hesaplanmasında kullanılan dekoderin
cross_attentions (
tuple(torch.Tensor), isteğe bağlı,output_attentions=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğunda döndürülür) —(batch_size, num_heads, sequence_length, sequence_length)biçiminde, her katman için bir adet içerentorch.Tensordemeti.Dekoderin çapraz dikkat katmanının dikkat ağırlıkları, dikkat softmax'ından sonra, çapraz dikkat başlıklarında ağırlıklı ortalamanın hesaplanmasında kullanılır.
encoder_last_hidden_state (
torch.Tensor, şekli(batch_size, sequence_length, hidden_size), isteğe bağlı) — Modelin kodlayıcısının son katmanının çıktısındaki gizli durumlar dizisi.encoder_hidden_states (
tuple(torch.Tensor), isteğe bağlı,output_hidden_states=Truegeçirildiğinde veyaconfig.output_hidden_states=Trueolduğunda döndürülür) —torch.Tensor(modelin bir gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için birer tane) içeren,(batch_size, sequence_length, hidden_size)biçiminde bir demet.Her katmanın çıktısında ve başlangıç gömme çıktılarında kodlayıcının gizli durumları.
encoder_attentions (
tuple(torch.Tensor), isteğe bağlı,output_attentions=Truegeçirildiğinde veyaconfig.output_attentions=Trueolduğunda döndürülür) —torch.Tensor(katman başına bir tane) içeren bir tuple, şekli(batch_size, num_heads, sequence_length, sequence_length).Dikkat yumuşatma (attention softmax) sonrasında, öz-dikkat (self-attention) kafalarında ağırlıklı ortalamanın hesaplanmasında kullanılan kodlayıcının dikkat ağırlıkları.
loc (
torch.Tensor, şekli(batch_size,)veya(batch_size, input_size), isteğe bağlı) — Modelin aynı büyüklükte girdiler almasını sağlamak için kullanılan her zaman serisinin bağlam penceresindeki değerleri kaydırır ve ardından değerleri orijinal büyüklüğe geri kaydırır.scale (
torch.Tensor, şekli(batch_size,)veya(batch_size, input_size), isteğe bağlı) — Modelin aynı büyüklükte girdiler almasını sağlamak için her zaman serisinin bağlam penceresindeki değerlerin ölçeklenmesinde kullanılan ve ardından orijinal büyüklüğe geri ölçeklenmek için kullanılan değerler.static_features (
torch.Tensor, şekli(batch_size, feature size), isteğe bağlı) — Bir batch içindeki her zaman serisinin, çıkarım sırasında kovaryatlara kopyalanan statik özellikleri.
Örnekler:
>>> 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, static_real_features'ı da kullanabilir. Bunu yapmak için, AutoformerConfig içindeki num_static_real_features değerini, veri setindeki bu tür özelliklerin sayısına göre ayarlayın (tourism_monthly veri seti durumunda
1'e eşitse), modeli başlatın ve aşağıda gösterildiği gibi çağırın:
>>> 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"], ... )