Transformers documentation
Zaman Serisi Transformer
Bu model 2022-09-30 tarihinde Hugging Face Transformers'a katkıda bulunulmuştur.
Zaman Serisi Transformer
Genel Bakış
Time Series Transformer modeli, zaman serisi tahmini için standart bir kodlayıcı-çözücü Transformer'dır. Bu model kashif tarafından katkıda bulunmuştur.
Kullanım ipuçları
- Kütüphanedeki diğer modellere benzer şekilde, TimeSeriesTransformerModel üzerinde herhangi bir başlık (head) bulunmayan ham Transformer'dır ve TimeSeriesTransformerForPrediction, zaman serisi tahmini için kullanılabilecek bir dağılım başlığını bu modelin üzerine ekler. Bunun, nokta tahmini (point forecasting) değil, olasılıksal tahmin (probabilistic forecasting) modeli olduğunu unutmayın. Bu, modelin örneklem alınabilecek bir dağılımı öğrendiği anlamına gelir. Model doğrudan değerler üretmez.
- TimeSeriesTransformerForPrediction, 2 bloktan oluşur:
context_lengthuzunluğundaki zaman serisi değerlerini (bunapast_valuesdenir) girdi olarak alan bir kodlayıcı ve gelecektekiprediction_lengthuzunluğundaki zaman serisi değerlerini (bunafuture_valuesdenir) tahmin eden bir çözücü. Eğitim sırasında modele (past_valuesvefuture_values) çiftleri sağlanmalıdır. - Ham (
past_valuesvefuture_values), modela ek olarak genellikle ek özellikler sağlanır. Bunlar şunlar olabilir:past_time_features:past_valuesdeğerlerine modelin ekleyeceği zamansal özellikler. Bunlar, Transformer kodlayıcısı için “konumsal kodlamalar” işlevi görür. Örnekler, skaler değerler olarak “ayın günü”, “yılın ayı” vb. şeklindedir (ve ardından bir vektör olarak birleştirilirler). Örneğin, belirli bir zaman serisi değeri 11 Ağustos’ta elde edilmişse, zaman özelliği vektörü olarak [11, 8] kullanılabilir (11 “ayın günü”, 8 “yılın ayı” olarak).future_time_features: modelinfuture_valuesiçine ekleyeceği zamansal özellikler. Bunlar, Transformer decoder'ı için “pozisyonel kodlamalar” işlevi görür. Örnekler, skaler değerler olarak “ayın günü”, “yılın ayı” vb. şeklindedir (ardından bir vektör olarak birleştirilirler). Örn. belirli bir zaman serisi değeri 11 Ağustos'ta elde edildiyse, zaman özelliği vektörü olarak [11, 8] kullanılabilir (11 “ayın günü”, 8 “yılın ayı” olarak).static_categorical_features: zaman içinde sabit kalan kategorik özellikler (yani, tümpast_valuesvefuture_valuesiçin aynı değere sahip olanlar). Buradaki bir örnek, belirli bir zaman serisini tanımlayan mağaza kimliği veya bölge kimliğidir. Bu özelliklerin TÜM veri noktaları (gelecektekiler dahil) için bilinmesi gerektiğini unutmayın.static_real_features: zaman içinde sabit kalan (yani tümpast_valuesvefuture_valuesiçin aynı değere sahip olan) gerçek değerli özellikler. Buradaki bir örnek, zaman serisi değerlerine sahip olduğunuz ürünün görsel temsili olabilir (örneğin, zaman seriniz ayakkabı satışlarıyla ilgiliyse, bir “ayakkabı” fotoğrafının ResNet gömümü). Bu özelliklerin TÜM veri noktaları (gelecektekiler dahil) için bilinmesi gerektiğini unutmayın.
- Model, makine çevirisinde bir Transformer'ın eğitildiği gibi “teacher-forcing” yöntemiyle eğitilir. Bu, eğitim sırasında
future_values'in bir konum sağa kaydırılarak decoder'a girdi olarak verildiği ve bunun başınapast_values'in son değerinin eklendiği anlamına gelir. Her zaman adımında model, bir sonraki hedefi tahmin etmelidir. Dolayısıyla eğitim kurulumu, dil için bir GPT modeline benzer; ancakdecoder_start_token_idkavramı yoktur (decoder'ın başlangıç girdisi olarak bağlamın son değerini kullanırız). - Çıkarım sırasında,
past_values'in son değerini decoder'a girdi olarak veririz. Ardından, modelden örnekleyerek bir sonraki zaman adımında bir tahmin yapabiliriz; bu tahmin, bir sonraki tahmini (aynı zamanda otoregresif üretim olarak da adlandırılır) yapmak üzere decoder'a beslenir.
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 Time Series Transformer blog yazısına göz atın: 🤗 Transformers ile Olasılıksal Zaman Serisi Tahmini
TimeSeriesTransformerConfig
sınıf transformers.TimeSeriesTransformerConfig
< 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: str | bool | None = 'mean'num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0num_time_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noneencoder_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'd_model: int = 64dropout: 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 = True )
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. Bu değer genellikle veri seti tarafından belirlenir ve uygun şekilde ayarlanmasını öneririz. - context_length (
int, isteğe bağlı, varsayılanprediction_length) — Kodlayıcı için bağlam uzunluğu.Noneise, 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 kullanılan gecikmeleri, genellikle verinin frekansı tarafından belirlenir. Varsayılan değer[1, 2, 3, 4, 5, 6, 7]olmakla birlikte, veri setine göre uygun şekilde değiştirmenizi öneririz. - scaling (
stringveyabool, isteğe bağlı, varsayılan"mean") — Girdi hedeflerinin “mean” ölçekleyici, “std” ölçekleyici veyaNoneise ölçekleyici olmadan ölçeklendirilip ölçeklendirilmeyeceğini belirtir.Trueise ölçekleyici “mean” olarak ayarlanır. - 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ı. - num_time_features (
int, isteğe bağlı, varsayılan 0) — Girdi zaman serisindeki zaman özelliklerinin 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. - 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. - 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. - 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. - d_model (
int, isteğe bağlı, varsayılan64) — Kodlayıcı katmanlarının ve pooler katmanının boyutu. - 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.
Bu, bir TimeSeriesTransformerModel yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Time Series Transformer modelinin örneklenmesi ve model mimarisinin tanımlanması için kullanılır. Varsayılan değerlerle bir yapılandırma örneklendiğinde, huggingface/time-series-transformer-tourism-monthly ile benzer bir yapılandırma elde edilir.
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 TimeSeriesTransformerConfig, TimeSeriesTransformerModel
>>> # Initializing a Time Series Transformer configuration with 12 time steps for prediction
>>> configuration = TimeSeriesTransformerConfig(prediction_length=12)
>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = TimeSeriesTransformerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configTimeSeriesTransformerModel
sınıf transformers.TimeSeriesTransformerModel
< source >( config: TimeSeriesTransformerConfig )
Parametreler
- config (TimeSeriesTransformerConfig) — 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 head olmadan ham hidden-state çıktısı üreten çıplak Time Series Transformer 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'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)
Parametreler
- past_values (
torch.Tensorof shape(batch_size, sequence_length)or(batch_size, sequence_length, input_size)) — Past values of the time series, that serve as context in order to predict the future. The sequence size of this tensor must be larger than thecontext_lengthof the model, since the model will use the larger size to construct lag features, i.e. additional values from the past which are added in order to serve as “extra context”.Buradaki
sequence_length,config.context_length+max(config.lags_sequence)'ye eşittir;lags_sequenceyapılandırılmamışsa bu değerconfig.context_length+ 7'ye eşittir (varsayılan olarakconfig.lags_sequenceiçindeki en büyük geriye bakma indeksi 7'dir)._past_lengthözelliği, geçmişin gerçek uzunluğunu döndürür.past_values, Transformer kodlayıcısının girdisi olarak aldığı değerdir (isteğe bağlı ek özellikler, örneğinstatic_categorical_features,static_real_features,past_time_featuresve gecikmeler ile birlikte).İsteğe bağlı olarak, eksik değerler sıfırlarla değiştirilmeli ve
past_observed_maskile belirtilmelidir.Çok değişkenli zaman serileri için
input_size> 1 boyutu zorunludur ve zaman serisindeki her zaman adımı başına değişken sayısına karşılık gelir. - past_time_features (
torch.Tensorşeklinde(batch_size, sequence_length, num_features)) — Modelin içsel olarakpast_values. eekleyeceği zorunlu zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, zaman serisinin “hayatı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. Tatil özellikleri de zaman özellikleri için iyi bir örnektir.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 modellerin aksine, Time Series Transformer ek zaman özelliklerinin sağlanmasını gerektirir. Time Series Transformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir.Bu tensöre ek dinamik gerçek kovaryatlar birleştirilebilir; ancak bu özelliklerin tahmin anında bilinmesi gerektiği unutulmamalıdır.
Buradaki
num_features,config.num_time_features+config.num_dynamic_real_features` değerine eşittir. - past_observed_mask (
torch.BoolTensorşeklinde(batch_size, sequence_length)veya(batch_size, sequence_length, input_size), isteğe bağlı) — Hangipast_valuesdeğerlerin gözlemlendiğini, hangilerinin eksik olduğunu belirtmek için Boolean mask. Mask değerleri[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)veya(batch_size, prediction_length, input_size), isteğe bağlı) — Zaman serisinin gelecekteki değerleri, model için etiket görevi görür.future_valuesdeğeri, Transformer'ın eğitim sırasında, verilen 'e göre öğrenip çıkarması gereken şeydir. Buradaki dizi uzunluğu prediction_length değerine eşittir. Ayrıntılar için demo defterine ve kod parçacıklarına bakın. İsteğe bağlı olarak, eğitim sırasında eksik değerlerin sıfırlarla değiştirilmesi ve future_observed_mask ile belirtilmesi gerekir. Çok değişkenli zaman serileri için input_size > 1 boyutu zorunludur ve zaman serisindeki her zaman adımı başına değişken sayısına karşılık gelir.past_values.Buradaki dizi uzunluğu
prediction_lengthdeğerine eşittir.Detaylar için demo defterine ve kod parçacıklarına bakın.
İsteğe bağlı olarak, eğitim sırasında eksik değerlerin sıfırlarla değiştirilmesi ve
future_observed_maskile belirtilmesi gerekir.Çok değişkenli zaman serileri için
input_size> 1 boyutu zorunludur ve zaman serisindeki her zaman adımı başına değişken sayısına karşılık gelir. - future_time_features (
torch.Tensorşeklinde(batch_size, prediction_length, num_features)) — modelin içsel olarakfuture_values. değere ekleyeceği, tahmin penceresi için gerekli zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, zaman serisinin “hayatı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. Tatil özellikleri de zaman özelliklerinin iyi bir örneğidir.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 modellerin aksine, Time Series Transformer ek zaman özelliklerinin sağlanmasını gerektirir. Time Series Transformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir.Bu tensöre ek dinamik gerçek kovaryatlar birleştirilebilir; ancak bu özelliklerin tahmin anında bilinmesi gerektiği unutulmamalıdır.
Buradaki
num_features,config.num_time_features+config.num_dynamic_real_features` değerine eşittir. - 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
Seq2SeqTSModelOutput veya tuple(torch.Tensor)
A Seq2SeqTSModelOutput veya bir torch.Tensor demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (TimeSeriesTransformerConfig) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
TimeSeriesTransformerModel 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.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 decoder'ın gizli durumları ve isteğe bağlı başlangıç gömme çıktıları.
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 kodlayıcının gizli durumları ve isteğe bağlı başlangıç gömme çıktıları.
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 TimeSeriesTransformerModel
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = TimeSeriesTransformerModel.from_pretrained("huggingface/time-series-transformer-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_stateTimeSeriesTransformerForPrediction
sınıf transformers.TimeSeriesTransformerForPrediction
< source >( config: TimeSeriesTransformerConfig )
Parametreler
- config (TimeSeriesTransformerConfig) — 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 Time Series Transformer 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'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)
Parametreler
- past_values (
torch.Tensorof shape(batch_size, sequence_length)or(batch_size, sequence_length, input_size)) — Past values of the time series, that serve as context in order to predict the future. The sequence size of this tensor must be larger than thecontext_lengthof the model, since the model will use the larger size to construct lag features, i.e. additional values from the past which are added in order to serve as “extra context”.Buradaki
sequence_length,config.context_length+max(config.lags_sequence)'ye eşittir;lags_sequenceyapılandırılmamışsa bu değerconfig.context_length+ 7'ye eşittir (varsayılan olarakconfig.lags_sequenceiçindeki en büyük geriye bakma indeksi 7'dir)._past_lengthözelliği, geçmişin gerçek uzunluğunu döndürür.past_values, Transformer kodlayıcısının girdisi olarak aldığı değerdir (isteğe bağlı ek özellikler, örneğinstatic_categorical_features,static_real_features,past_time_featuresve gecikmeler ile birlikte).İsteğe bağlı olarak, eksik değerler sıfırlarla değiştirilmeli ve
past_observed_maskile belirtilmelidir.Çok değişkenli zaman serileri için
input_size> 1 boyutu zorunludur ve zaman serisindeki her zaman adımı başına değişken sayısına karşılık gelir. - past_time_features (
torch.Tensorşeklinde(batch_size, sequence_length, num_features)) — Modelin içsel olarakpast_values. eekleyeceği zorunlu zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, zaman serisinin “hayatı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. Tatil özellikleri de zaman özellikleri için iyi bir örnektir.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 modellerin aksine, Time Series Transformer ek zaman özelliklerinin sağlanmasını gerektirir. Time Series Transformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir.Bu tensöre ek dinamik gerçek kovaryatlar birleştirilebilir; ancak bu özelliklerin tahmin anında bilinmesi gerektiği unutulmamalıdır.
Buradaki
num_features,config.num_time_features+config.num_dynamic_real_features` değerine eşittir. - past_observed_mask (
torch.BoolTensorşeklinde(batch_size, sequence_length)veya(batch_size, sequence_length, input_size), isteğe bağlı) — Hangipast_valuesdeğerlerin gözlemlendiğini, hangilerinin eksik olduğunu belirtmek için Boolean mask. Mask değerleri[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)veya(batch_size, prediction_length, input_size), isteğe bağlı) — Zaman serisinin gelecekteki değerleri, model için etiket görevi görür.future_valuesdeğeri, Transformer'ın eğitim sırasında, verilen 'e göre öğrenip çıkarması gereken şeydir. Buradaki dizi uzunluğu prediction_length değerine eşittir. Ayrıntılar için demo defterine ve kod parçacıklarına bakın. İsteğe bağlı olarak, eğitim sırasında eksik değerlerin sıfırlarla değiştirilmesi ve future_observed_mask ile belirtilmesi gerekir. Çok değişkenli zaman serileri için input_size > 1 boyutu zorunludur ve zaman serisindeki her zaman adımı başına değişken sayısına karşılık gelir.past_values.Buradaki dizi uzunluğu
prediction_lengthdeğerine eşittir.Detaylar için demo defterine ve kod parçacıklarına bakın.
İsteğe bağlı olarak, eğitim sırasında eksik değerlerin sıfırlarla değiştirilmesi ve
future_observed_maskile belirtilmesi gerekir.Çok değişkenli zaman serileri için
input_size> 1 boyutu zorunludur ve zaman serisindeki her zaman adımı başına değişken sayısına karşılık gelir. - future_time_features (
torch.Tensorşeklinde(batch_size, prediction_length, num_features)) — modelin içsel olarakfuture_values. değere ekleyeceği, tahmin penceresi için gerekli zaman özellikleri. Bunlar, örneğin Fourier özellikleri olarak kodlanmış “yılın ayı”, “ayın günü” gibi şeyler olabilir. Bunlar, zaman serisinin “hayatı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. Tatil özellikleri de zaman özelliklerinin iyi bir örneğidir.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 modellerin aksine, Time Series Transformer ek zaman özelliklerinin sağlanmasını gerektirir. Time Series Transformer yalnızca
static_categorical_featuresiçin ek gömme (embedding) öğrenir.Bu tensöre ek dinamik gerçek kovaryatlar birleştirilebilir; ancak bu özelliklerin tahmin anında bilinmesi gerektiği unutulmamalıdır.
Buradaki
num_features,config.num_time_features+config.num_dynamic_real_features` değerine eşittir. - 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
Seq2SeqTSModelOutput veya tuple(torch.Tensor)
A Seq2SeqTSModelOutput veya bir torch.Tensor demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (TimeSeriesTransformerConfig) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
TimeSeriesTransformerForPrediction 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.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 decoder'ın gizli durumları ve isteğe bağlı başlangıç gömme çıktıları.
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 kodlayıcının gizli durumları ve isteğe bağlı başlangıç gömme çıktıları.
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 TimeSeriesTransformerForPrediction
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = TimeSeriesTransformerForPrediction.from_pretrained(
... "huggingface/time-series-transformer-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)