Transformers documentation
Autoformer
نُشر هذا النموذج في أوراق HF في 24 يونيو 2021، وأُضيف إلى مكتبة Hugging Face Transformers في 30 مايو 2023.
Autoformer
نظرة عامة
قُدِّم نموذج Autoformer في Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting بواسطة Haixu Wu وJiehui Xu وJianmin Wang وMingsheng Long.
تُوسّع هذه النموذج بنية Transformer كبنية تحليلية عميقة، مما يتيح تحليل المكونات الاتجاهية والموسمية تدريجياً أثناء عملية التنبؤ.
المستخلص من الورقة البحثية هو كالتالي:
تمديد فترة التنبؤ هو مطلب حاسم للتطبيقات الواقعية، مثل الإنذار المبكر للأحوال الجوية القاسية والتخطيط طويل الأمد لاستهلاك الطاقة. تدرس هذه الورقة مشكلة التنبؤ طويل الأمد لسلاسل البيانات الزمنية. تعتمد نماذج Transformer السابقة على آليات انتباه ذاتي متنوعة لاكتشاف الاعتماديات طويلة المدى. ومع ذلك، تمنع الأنماط الزمنية المعقدة للمستقبل البعيد النموذج من إيجاد اعتماديات موثوقة. كما أن نماذج Transformer مضطرة لاعتماد إصدارات متناثرة من الانتباه الذاتي النقطي من أجل كفاءة السلاسل الطويلة، مما يؤدي إلى عنق زجاجة في استغلال المعلومات. متجاوزين نماذج Transformer، صممنا Autoformer كبنية تفكيك جديدة تتضمن آلية ارتباط ذاتي (Auto-Correlation). كسرنا العرف السائد في المعالجة المسبقة المتمثلة في تفكيك السلاسل، وأعدنا ابتكارها كتداخل داخلي أساسي في النماذج العميقة. يمنح هذا التصميم Autoformer قدرات تفكيك تدريجي لسلاسل البيانات الزمنية المعقدة. وعلاوة على ذلك، مستوحين من نظرية العمليات العشوائية، صممنا آلية Auto-Correlation بناءً على دورية السلاسل، حيث تقوم باكتشاف الاعتماديات وتجميع التمثيلات على مستوى السلاسل الفرعية. تتفوق آلية Auto-Correlation على الانتباه الذاتي من حيث الكفاءة والدقة على حد سواء. في التنبؤ طويل الأمد، يحقق Autoformer دقة متقدمة، مع تحسن نسبي بنسبة 38% على ستة معايير مرجعية، تغطي خمسة تطبيقات عملية: الطاقة، والمرور، والاقتصاد، والطقس، والأمراض.
تمت مساهمة هذا النموذج من قِبل elisim وkashif. يمكن العثور على الكود الأصلي هنا.
الموارد
قائمة بموارد رسمية من Hugging Face وموارد مجتمعية (مشار إليها بـ 🌎) لمساعدتك على البدء. إذا كنت مهتمًا بتقديم مورد ليُدرج هنا، فلا تتردد في فتح طلب سحب (Pull Request) وسنقوم بمراجعته! يُفضّل أن يُظهر المورد شيئًا جديدًا بدلاً من تكرار مورد موجود مسبقًا.
- اطّلع على مدونة Autoformer في مدونة HuggingFace: نعم، نماذج Transformers فعّالة للتنبؤ بالسلاسل الزمنية (+ Autoformer)
AutoformerConfig
فئة 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 )
المعاملات
- is_encoder_decoder (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان النموذج يُستخدم كمُشفِّر/مُفكِّك أم لا. - prediction_length (
int, اختياري) — طول التنبؤ للمفكّك. بعبارة أخرى، هو أفق التنبؤ للنموذج. - context_length (
int، اختياري، القيمة الافتراضية هيprediction_length) — طول السياق للمشفّر. إذا لم يتم تعيينه، فسيكون طول السياق مساويًا لـprediction_length. - distribution_output (
string، اختياري، القيمة الافتراضية"student_t") — رأس الإصدار التوزيعي للنموذج. يمكن أن يكون"student_t"أو "normal" أو "negative_binomial". - loss (
string، اختياري، القيمة الافتراضية"nll") — دالة الخسارة للنموذج المقابلة لرأسdistribution_output. بالنسبة للتوزيعات البارامترية، تكون دالة الخسارة هي الاحتمالية السالبة (nll) - وهي حاليًا الخيار المدعوم الوحيد. - input_size (
int، اختياري، القيمة الافتراضية 1) — حجم المتغير المستهدف، والذي يكون افتراضيًا 1 في حالة الأهداف أحادية المتغير. يكون > 1 في حالة الأهداف متعددة المتغيرات. - lags_sequence (
list[int]، اختياري، القيمة الافتراضية[1, 2, 3, 4, 5, 6, 7]) — تأخيرات سلسلة الزمنية المدخلة كمتغيرات مصاحبة، وغالباً ما تُحدَّد بناءً على التكرار. القيمة الافتراضية هي[1, 2, 3, 4, 5, 6, 7]. - scaling (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم توسيع الأهداف المدخلة. - num_time_features (
int، اختياري، القيمة الافتراضية 0) — عدد ميزات الوقت في سلسلة الزمنية المدخلة. - num_dynamic_real_features (
int، اختياري، القيمة الافتراضية 0) — عدد الميزات الديناميكية ذات القيم الحقيقية. - num_static_categorical_features (
int، اختياري، القيمة الافتراضية 0) — عدد الميزات التصنيفية الثابتة. - num_static_real_features (
int، اختياري، القيمة الافتراضية 0) — عدد الميزات الثابتة ذات القيم الحقيقية. - cardinality (
list[int], اختياري) — عدد القيم المختلفة (cardinality) لكل من الميزات التصنيفية الثابتة. يجب أن يكون قائمة من الأعداد الصحيحة، ذات نفس طولnum_static_categorical_features. لا يمكن أن يكونNoneإذا كانnum_static_categorical_features> 0. - embedding_dimension (
list[int]، اختياري) — أبعاد التضمينات والحالات المخفية. - d_model (
int، اختياري، القيمة الافتراضية64) — حجم طبقات المُشفِّر وطبقة المُجمِّع. - encoder_attention_heads (
int, اختياري، القيمة الافتراضية2) — عدد رؤوس الانتباه لكل طبقة انتباه في مُشفِّر Transformer. - decoder_attention_heads (
int، اختياري، القيمة الافتراضية2) — عدد رؤوس الانتباه لكل طبقة انتباه في مُفكِّك Transformer. - encoder_layers (
int, اختياري، القيمة الافتراضية2) — عدد الطبقات المخفية في مُشفِّر Transformer. سيستخدم القيمة نفسها لـnum_layersإذا لم يتم ضبطه. - decoder_layers (
int, اختياري، القيمة الافتراضية2) — عدد الطبقات المخفية في مُفكِّك Transformer. سيُستخدم نفس قيمةnum_layersإذا لم يتم تعيينه. - encoder_ffn_dim (
int, اختياري، القيمة الافتراضية32) — أبعاد طبقة "الوسط" (التي تُسمّى غالباً بطبقة التغذية الأمامية) في المُشفِّر. - decoder_ffn_dim (
int، اختياري، القيمة الافتراضية32) — أبعاد طبقة "الوسط" (التي تُسمّى غالبًا بالطبقة الأمامية) في المُفكِّك. - activation_function (
str، اختياري، القيمة الافتراضيةgelu) — دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال،"gelu"،"relu"،"silu"، وغيرها. - dropout (
Union[float, int]، اختياري، القيمة الافتراضية0.1) — النسبة لجميع طبقات dropout. - encoder_layerdrop (
Union[float, int]، اختياري، القيمة الافتراضية0.1) — احتمال LayerDrop للمُشفِّر. راجع [ورقة LayerDrop](انظر https://huggingface.co/papers/1909.11556) لمزيد من التفاصيل. - decoder_layerdrop (
Union[float, int]، اختياري، القيمة الافتراضية0.1) — احتمال LayerDrop الخاص بفك الترميز. راجع [ورقة LayerDrop](انظر https://huggingface.co/papers/1909.11556) لمزيد من التفاصيل. - attention_dropout (
Union[float, int]، اختياري، القيمة الافتراضية0.1) — نسبة الإسقاط (dropout) لاحتمالات الانتباه. - activation_dropout (
Union[float, int]، اختياري، القيمة الافتراضية0.1) — نسبة dropout للتفعيلات داخل الطبقة المتصلة بالكامل. - num_parallel_samples (
int، اختياري، القيمة الافتراضية 100) — عدد العينات التي سيتم توليدها بالتوازي لكل خطوة زمنية من خطوات الاستدلال. - init_std (
float، اختياري، القيمة الافتراضية0.02) — انحراف معياري لمُهيّئ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان. - use_cache (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب على النموذج إرجاع قيم المفاتيح/القيم الأخيرة للانتباه (لا تستخدمها جميع النماذج). لا ينطبق إلا إذا كانconfig.is_decoder=Trueأو إذا كان النموذج نموذجًا توليديًا يعتمد على المُفكِّك فقط. - label_length (
int, اختياري، القيمة الافتراضية 10) — طول رمز البداية لمفكّك Autoformer، والذي يُستخدم للتنبؤ متعدد الخطوات المباشر (أي التوليد غير الذاتي). - moving_average (
int، اختياري، القيمة الافتراضية 25) — حجم نافذة المتوسط المتحرك. عملياً، هو حجم النواة في AvgPool1d لطبقة التفكيك (Decomposition Layer). - autocorrelation_factor (
int، اختياري، القيمة الافتراضية 3) — عامل "الانتباه" (أي آلية AutoCorrelation) الذي يُستخدم لإيجاد تأخيرات الارتباط الذاتي الأعلى k. يُوصى في الورقة البحثية بإعداده إلى رقم بين 1 و5.
هذه فئة الإعدادات المخزنة لإعدادات نموذج AutoformerModel. تُستخدم لاستحداث نموذج Autoformer وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ huggingface/autoformer-tourism-monthly
ترث كائنات التهيئة من PreTrainedConfig ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ PreTrainedConfig لمزيد من المعلومات.
مثال:
>>> 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
فئة transformers.AutoformerModel
< source >( config: AutoformerConfig )
المعاملات
- config (AutoformerConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعدادات إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.
نموذج Autoformer الأساسي الذي يُخرج حالات مخفية خام دون أي رأس محدد في الأعلى.
يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).
هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.
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)
المعاملات
- past_values (
torch.Tensorبشكل(batch_size, sequence_length)) — القيم السابقة لسلسلة الزمنية، والتي تعمل كسياق للتنبؤ بالمستقبل. قد تحتوي هذه القيم على تأخيرات، أي قيم إضافية من الماضي تُضاف لتعمل كـ "سياق إضافي". يتم إدخالpast_valuesكمُدخل إلى مُشفِّر Transformer (مع ميزات إضافية اختيارية، مثلstatic_categorical_features,static_real_features,past_time_features).طول التسلسل هنا يساوي
context_length+max(config.lags_sequence).يجب استبدال القيم المفقودة بالأصفار.
- past_time_features (
torch.Tensorبشكل(batch_size, sequence_length, num_features), اختياري) — ميزات زمنية اختيارية، ستضيفها النموذج داخليًا إلىpast_values. قد تكون هذه ميزات مثل «شهر السنة» و«اليوم من الشهر» وما إلى ذلك، مُرمَّزة كمتجهات (على سبيل المثال، كميزات فورييه). كما قد تكون ما يُسمى بـ«ميزات العمر»، التي تساعد النموذج في الأساس على معرفة «المرحلة» التي تمر بها السلسلة الزمنية. تأخذ ميزات العمر قيمًا صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية.تعمل هذه الميزات بمثابة "ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلّم ترميزات الموضع من الصفر داخليًا كمعاملات للنموذج، يتطلب Time Series Transformer توفير ميزات زمنية إضافية.
يتعلم Autoformer تضمينات إضافية فقط لـ
static_categorical_features. - past_observed_mask (
torch.BoolTensorبشكل(batch_size, sequence_length), اختياري) — قناع منطقي لتحديد أيpast_valuesتم رصدها وأيها مفقود. قيم القناع المختارة من[0, 1]:- 1 للقيم التي تم ملاحظتها،
- 0 للقيم التي تكون مفقودة (أي قيم NaN التي تم استبدالها بالأصفار).
- static_categorical_features (
torch.LongTensorبشكل(batch_size, number of static categorical features), اختياري) — ميزات تصنيفية ثابتة اختيارية يتعلم النموذج تضمينًا لها، ثم يضيفه إلى قيم السلاسل الزمنية.الميزات التصنيفية الثابتة هي ميزات تملك القيمة نفسها لجميع خطوات الزمن (ثابتة عبر الزمن).
مثال نموذجي على خاصية فئوية ثابتة هو معرّف السلسلة الزمنية.
- static_real_features (
torch.Tensorبشكل(batch_size, number of static real features), اختياري) — مواصفات حقيقية ثابتة اختيارية ستضيفها النموذج إلى قيم السلاسل الزمنية. المواصفات الحقيقية الثابتة هي مواصفات لها نفس القيمة لجميع الخطوات الزمنية (ثابتة عبر الزمن). مثال نموذجي على الميزة الحقيقية الثابتة هو معلومات الترويج.الميزات الحقيقية الثابتة هي ميزات تملك القيمة نفسها لجميع خطوات الزمن (ثابتة عبر الزمن).
مثال نموذجي على ميزة حقيقية ثابتة هو معلومات العروض الترويجية.
- future_values (
torch.Tensorبشكل(batch_size, prediction_length)) — القيم المستقبلية لسلسلة الزمنية، والتي تعمل كوسوم للنموذج. القيمةfuture_valuesهي ما يحتاج إلى تعلّمه النموذج لتخريجه، بناءً علىpast_values.راجع دفتر الملاحظات التوضيحي ومقتطفات الأكواد للاطلاع على التفاصيل.
يجب استبدال القيم المفقودة بالأصفار.
- future_time_features (
torch.Tensorبشكل(batch_size, prediction_length, num_features), اختياري) — ميزات زمنية اختيارية، ستضيفها النموذج داخليًا إلىfuture_values. قد تكون هذه ميزات مثل «شهر السنة» و«اليوم من الشهر» وما إلى ذلك، مُرمّزة كمتجهات (على سبيل المثال، كميزات فورييه). كما قد تكون ما يُسمى بـ«ميزات العمر»، التي تساعد النموذج في الأساس على معرفة «المرحلة الزمنية» التي تتواجد فيها السلسلة الزمنية. تتميز ميزات العمر بقيم صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية.تُشكّل هذه الميزات ما يُعرف بـ "ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلّم ترميزات الموضع من الصفر داخليًا بوصفها معاملات للنموذج، فإن Time Series Transformer يتطلب توفير ميزات إضافية.
يتعلم Autoformer تضمينات إضافية فقط لـ
static_categorical_features. - decoder_attention_mask (
torch.LongTensorof shape(batch_size, target_sequence_length), اختياري) — قناع لتجنّب تنفيذ الانتباه على فهارس رموز معينة. افتراضيًا، يُستخدم قناع سببي (causal mask) للتأكد من أن النموذج لا يستطيع النظر إلا إلى المدخلات السابقة من أجل التنبؤ بالمستقبل. - encoder_outputs (
tuple(tuple(torch.Tensor), اختياري) — يتألف العنصر المرتب منlast_hidden_stateوhidden_states(اختياري) وattentions(اختياري)last_hidden_stateذو الشكل(batch_size, sequence_length, hidden_size)(اختياري) هو تسلسل من حالات المخفية عند مخرج الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع (cross-attention) في المُفكِّك. - past_key_values (
~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً منpast_key_valuesالذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندماuse_cache=Trueأوconfig.use_cache=True.يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير
past_key_values، فسيتم تهيئة DynamicCache افتراضياً.سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.
عند استخدام
past_key_values، يُتوقَّع من المستخدم إدخالinput_idsغير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد(batch_size, unprocessed_length)بدلاً من جميعinput_idsبأبعاد(batch_size, sequence_length). - use_cache (
bool، اختياري) — إذا تم تعيينه إلىTrue، تُعاد حالات المفاتيح والقيمpast_key_valuesويمكن استخدامها لتسريع فك الترميز (انظرpast_key_values).
يعيد
AutoformerModelOutput أو tuple(torch.Tensor)
AutoformerModelOutput أو مجموعة مرتبة من
torch.Tensor (إذا تم تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة
تعتمد على الإعداد (AutoformerConfig) والمدخلات.
تتجاوز طريقة AutoformerModel الخاصة بالتقديم (forward) الطريقة الخاصة __call__.
على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن
Moduleبدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.
last_hidden_state (
torch.Tensorمن الشكل(batch_size, sequence_length, hidden_size)) — تسلسل من حالات الإخفاء عند مخرج الطبقة الأخيرة من فاحم النموذج.إذا تم استخدام
past_key_values، فإن الحالة المخفية الأخيرة فقط من التسلسلات ذات الشكل(batch_size, 1, hidden_size)هي التي تُخرج.trend (
torch.Tensorمن الشكل(batch_size, sequence_length, hidden_size)) — متجه الاتجاه لكل سلسلة زمنية.past_key_values (
Cache، اختياري، يُعاد عند تمريرuse_cache=Trueأو عند تعيينconfig.use_cache=True) — إنه كائن من نوع Cache. لمزيد من التفاصيل، راجع دليل ذاكرة kv.تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها (انظر مدخل
past_key_values) لتسريع فك الترميز التسلسلي.decoder_hidden_states (
tuple[torch.Tensor]، اختياري، يُعاد عند تمريرoutput_hidden_states=Trueأو عند تعيينconfig.output_hidden_states=True) — مجموعة منtorch.Tensor(واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) بأبعاد(batch_size, sequence_length, hidden_size).حالات المخفية (Hidden states) لمفكّك الترميز (decoder) عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي (initial embedding).
decoder_attentions (
tuple[torch.Tensor]، اختياري، يُعاد عند تمريرoutput_attentions=Trueأو عند تعيينconfig.output_attentions=True) — مجموعة منtorch.Tensor(واحدة لكل طبقة) بأبعاد(batch_size, num_heads, sequence_length, sequence_length).أوزان الانتباه في المُفكِّك، بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
cross_attentions (
tuple[torch.Tensor]، اختياري، يُعاد عند تمريرoutput_attentions=Trueأو عند تعيينconfig.output_attentions=True) — مجموعة منtorch.Tensor(واحدة لكل طبقة) بأبعاد(batch_size, num_heads, sequence_length, sequence_length).أوزان الانتباه لطبقة الانتباه المتقاطع في المُفكِّك، بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه المتقاطع.
encoder_last_hidden_state (
torch.Tensorمن الشكل(batch_size, sequence_length, hidden_size)، اختياري) — تسلسل حالات مخفية عند مخرج الطبقة الأخيرة من مُشفِّر النموذج.encoder_hidden_states (
tuple[torch.Tensor]، اختياري، يُعاد عند تمريرoutput_hidden_states=Trueأو عند تعيينconfig.output_hidden_states=True) — مجموعة منtorch.Tensor(واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) بأبعاد(batch_size, sequence_length, hidden_size).حالات المخفية للمشفّر عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي.
encoder_attentions (
tuple[torch.Tensor]، اختياري، يُعاد عند تمريرoutput_attentions=Trueأو عند تعيينconfig.output_attentions=True) — مجموعة منtorch.Tensor(واحدة لكل طبقة) بأبعاد(batch_size, num_heads, sequence_length, sequence_length).أوزان الانتباه في المُشفِّر، بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
loc (
torch.Tensorof shape(batch_size,)or(batch_size, input_size), اختياري) — قيم إزاحة نافذة السياق لكل سلسلة زمنية، تُستخدم لمنح النموذج مدخلات بنفس المقدار، ثم تُستخدم بعد ذلك للإزاحة مرة أخرى إلى المقدار الأصلي.scale (
torch.Tensorمن الشكل(batch_size,)أو(batch_size, input_size)، اختياري) — قيم التوسيع لنافذة السياق لكل سلسلة زمنية، وتُستخدم لمنح النموذج مدخلات بنفس الحجم، ثم تُستخدم لإعادة التوسيع إلى الحجم الأصلي. static_features: (torch.Tensorمن الشكل(batch_size, feature size)، اختياري): الميزات الثابتة لكل سلسلة زمنية في الدفعة، والتي تُنسخ إلى المتغيرات المشتركة عند الاستدلال.static_features (
torch.Tensorof shape(batch_size, feature size), اختياري) — الميزات الثابتة لكل سلسلة زمنية في الدفعة، والتي تُنسخ إلى المتغيرات المشتركة عند الاستدلال.
أمثلة:
>>> 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
فئة transformers.AutoformerForPrediction
< source >( config: AutoformerConfig )
المعاملات
- config (AutoformerConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعدادات إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.
نموذج Autoformer مع رأس توزيع في الأعلى للتنبؤ بالسلاسل الزمنية.
يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).
هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.
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)
المعاملات
- past_values (
torch.Tensorبشكل(batch_size, sequence_length)) — القيم السابقة لسلسلة الزمنية، والتي تعمل كسياق للتنبؤ بالمستقبل. قد تحتوي هذه القيم على تأخيرات، أي قيم إضافية من الماضي تُضاف لتعمل كـ "سياق إضافي". يتم إدخالpast_valuesكمُدخل إلى مُشفِّر Transformer (مع ميزات إضافية اختيارية، مثلstatic_categorical_features,static_real_features,past_time_features).طول التسلسل هنا يساوي
context_length+max(config.lags_sequence).يجب استبدال القيم المفقودة بالأصفار.
- past_time_features (
torch.Tensorبشكل(batch_size, sequence_length, num_features), اختياري) — ميزات زمنية اختيارية، ستضيفها النموذج داخليًا إلىpast_values. قد تكون هذه ميزات مثل «شهر السنة» و«اليوم من الشهر» وما إلى ذلك، مُرمَّزة كمتجهات (على سبيل المثال، كميزات فورييه). كما قد تكون ما يُسمى بـ«ميزات العمر»، التي تساعد النموذج في الأساس على معرفة «المرحلة» التي تمر بها السلسلة الزمنية. تأخذ ميزات العمر قيمًا صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية.تعمل هذه الميزات بمثابة "ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلّم ترميزات الموضع من الصفر داخليًا كمعاملات للنموذج، يتطلب Time Series Transformer توفير ميزات زمنية إضافية.
يتعلم Autoformer تضمينات إضافية فقط لـ
static_categorical_features. - past_observed_mask (
torch.BoolTensorبشكل(batch_size, sequence_length), اختياري) — قناع منطقي لتحديد أيpast_valuesتم رصدها وأيها مفقود. قيم القناع المختارة من[0, 1]:- 1 للقيم التي تم ملاحظتها،
- 0 للقيم التي تكون مفقودة (أي قيم NaN التي تم استبدالها بالأصفار).
- static_categorical_features (
torch.LongTensorبشكل(batch_size, number of static categorical features), اختياري) — ميزات تصنيفية ثابتة اختيارية يتعلم النموذج تضمينًا لها، ثم يضيفه إلى قيم السلاسل الزمنية.الميزات التصنيفية الثابتة هي ميزات تملك القيمة نفسها لجميع خطوات الزمن (ثابتة عبر الزمن).
مثال نموذجي على خاصية فئوية ثابتة هو معرّف السلسلة الزمنية.
- static_real_features (
torch.Tensorبشكل(batch_size, number of static real features), اختياري) — مواصفات حقيقية ثابتة اختيارية ستضيفها النموذج إلى قيم السلاسل الزمنية. المواصفات الحقيقية الثابتة هي مواصفات لها نفس القيمة لجميع الخطوات الزمنية (ثابتة عبر الزمن). مثال نموذجي على الميزة الحقيقية الثابتة هو معلومات الترويج.الميزات الحقيقية الثابتة هي ميزات تملك القيمة نفسها لجميع خطوات الزمن (ثابتة عبر الزمن).
مثال نموذجي على ميزة حقيقية ثابتة هو معلومات العروض الترويجية.
- future_values (
torch.Tensorبشكل(batch_size, prediction_length)) — القيم المستقبلية لسلسلة الزمنية، والتي تعمل كوسوم للنموذج. القيمةfuture_valuesهي ما يحتاج إلى تعلّمه النموذج لتخريجه، بناءً علىpast_values.راجع دفتر الملاحظات التوضيحي ومقتطفات الأكواد للاطلاع على التفاصيل.
يجب استبدال القيم المفقودة بالأصفار.
- future_time_features (
torch.Tensorبشكل(batch_size, prediction_length, num_features), اختياري) — ميزات زمنية اختيارية، ستضيفها النموذج داخليًا إلىfuture_values. قد تكون هذه ميزات مثل «شهر السنة» و«اليوم من الشهر» وما إلى ذلك، مُرمّزة كمتجهات (على سبيل المثال، كميزات فورييه). كما قد تكون ما يُسمى بـ«ميزات العمر»، التي تساعد النموذج في الأساس على معرفة «المرحلة الزمنية» التي تتواجد فيها السلسلة الزمنية. تتميز ميزات العمر بقيم صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية.تُشكّل هذه الميزات ما يُعرف بـ "ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلّم ترميزات الموضع من الصفر داخليًا بوصفها معاملات للنموذج، فإن Time Series Transformer يتطلب توفير ميزات إضافية.
يتعلم Autoformer تضمينات إضافية فقط لـ
static_categorical_features. - future_observed_mask (
torch.BoolTensorبشكل(batch_size, sequence_length)أو(batch_size, sequence_length, input_size), اختياري) — قناع منطقي لتحديد أيfuture_valuesتمت ملاحظتها وأيها مفقودة. قيم القناع المختارة من ضمن [0, 1]: القيمة 1 للقيم الملاحظة، والقيمة 0 للقيم المفقودة (أي قيم NaN التي تم استبدالها بالصفر). يُستخدم هذا القناع لاستبعاد القيم المفقودة في حساب الخسارة النهائي.[0, 1]:- 1 للقيم التي تم ملاحظتها،
- 0 للقيم التي تكون مفقودة (أي قيم NaN التي تم استبدالها بالأصفار).
تُستخدم هذه القناع (Mask) لاستبعاد القيم المفقودة في حساب الخسارة النهائية.
- decoder_attention_mask (
torch.LongTensorof shape(batch_size, target_sequence_length), اختياري) — قناع لتجنّب تنفيذ الانتباه على فهارس رموز معينة. افتراضيًا، يُستخدم قناع سببي (causal mask) للتأكد من أن النموذج لا يستطيع النظر إلا إلى المدخلات السابقة من أجل التنبؤ بالمستقبل. - encoder_outputs (
tuple(tuple(torch.Tensor), اختياري) — يتألف العنصر المرتب منlast_hidden_stateوhidden_states(اختياري) وattentions(اختياري)last_hidden_stateذو الشكل(batch_size, sequence_length, hidden_size)(اختياري) هو تسلسل من حالات المخفية عند مخرج الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع (cross-attention) في المُفكِّك. - past_key_values (
~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً منpast_key_valuesالذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندماuse_cache=Trueأوconfig.use_cache=True.يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير
past_key_values، فسيتم تهيئة DynamicCache افتراضياً.سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.
عند استخدام
past_key_values، يُتوقَّع من المستخدم إدخالinput_idsغير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد(batch_size, unprocessed_length)بدلاً من جميعinput_idsبأبعاد(batch_size, sequence_length). - use_cache (
bool، اختياري) — إذا تم تعيينه إلىTrue، تُعاد حالات المفاتيح والقيمpast_key_valuesويمكن استخدامها لتسريع فك الترميز (انظرpast_key_values).
يعيد
Seq2SeqTSPredictionOutput أو tuple(torch.Tensor)
Seq2SeqTSPredictionOutput أو مجموعة مرتبة من
torch.Tensor (إذا تم تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة
تعتمد على الإعداد (AutoformerConfig) والمدخلات.
تتجاوز طريقة AutoformerForPrediction الخاصة بالتقديم (forward) الطريقة الخاصة __call__.
على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن
Moduleبدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.
loss (
torch.Tensorof shape(1,), اختياري, يُعاد عند توفيرfuture_values) — خسارة التوزيع.params (
torch.Tensorمن الشكل(batch_size, num_samples, num_params)) — معاملات التوزيع المختار.past_key_values (
EncoderDecoderCache، اختياري، يُعاد عند تمريرuse_cache=Trueأو عند تعيينconfig.use_cache=True) — إنه كائن من نوع EncoderDecoderCache. لمزيد من التفاصيل، راجع دليل ذاكرة kv.تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها (انظر مدخل
past_key_values) لتسريع فك الترميز التسلسلي.decoder_hidden_states (
tuple(torch.Tensor)، اختياري، يُعاد عند تمريرoutput_hidden_states=Trueأو عند تعيينconfig.output_hidden_states=True) — مجموعة منtorch.Tensor(واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) بأبعاد(batch_size, sequence_length, hidden_size).حالات المخفية (Hidden states) لمفكّك الترميز (decoder) عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي (initial embedding).
decoder_attentions (
tuple(torch.Tensor)، اختياري، يُعاد عند تمريرoutput_attentions=Trueأو عند تعيينconfig.output_attentions=True) — مجموعة منtorch.Tensor(واحدة لكل طبقة) بأبعاد(batch_size, num_heads, sequence_length, sequence_length).أوزان الانتباه في المُفكِّك، بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
cross_attentions (
tuple(torch.Tensor)، اختياري، يُعاد عند تمريرoutput_attentions=Trueأو عند تعيينconfig.output_attentions=True) — مجموعة منtorch.Tensor(واحدة لكل طبقة) بأبعاد(batch_size, num_heads, sequence_length, sequence_length).أوزان الانتباه لطبقة الانتباه المتقاطع في المُفكِّك، بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه المتقاطع.
encoder_last_hidden_state (
torch.Tensorمن الشكل(batch_size, sequence_length, hidden_size)، اختياري) — تسلسل حالات مخفية عند مخرج الطبقة الأخيرة من مُشفِّر النموذج.encoder_hidden_states (
tuple(torch.Tensor)، اختياري، يُعاد عند تمريرoutput_hidden_states=Trueأو عند تعيينconfig.output_hidden_states=True) — مجموعة منtorch.Tensor(واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) من الشكل(batch_size, sequence_length, hidden_size).حالات المخفية للمشفّر عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي.
encoder_attentions (
tuple(torch.Tensor)، اختياري، يُعاد عند تمريرoutput_attentions=Trueأو عند تعيينconfig.output_attentions=True) — مجموعة منtorch.Tensor(واحدة لكل طبقة) بأبعاد(batch_size, num_heads, sequence_length, sequence_length).أوزان الانتباه في المُشفِّر، بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
loc (
torch.Tensorof shape(batch_size,)or(batch_size, input_size), اختياري) — قيم إزاحة نافذة السياق لكل سلسلة زمنية، تُستخدم لمنح النموذج مدخلات بنفس المقدار، ثم تُستخدم بعد ذلك للإزاحة مرة أخرى إلى المقدار الأصلي.scale (
torch.Tensorمن الشكل(batch_size,)أو(batch_size, input_size)، اختياري) — قيم التوسيع الخاصة بنافذة السياق لكل سلسلة زمنية، والتي تُستخدم لإعطاء النموذج مدخلات بنفس الحجم، ثم تُستخدم لإعادة التوسيع إلى الحجم الأصلي.static_features (
torch.Tensorof shape(batch_size, feature size), اختياري) — الميزات الثابتة لكل سلسلة زمنية في الدفعة، والتي تُنسخ إلى المتغيرات المشتركة عند الاستدلال.
أمثلة:
>>> 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. للقيام بذلك، اضبط num_static_real_features في AutoformerConfig بناءً على عدد هذه الميزات في مجموعة البيانات (في حالة مجموعة بيانات tourism_monthly يكون
يساوي 1)، قم بتهيئة النموذج واستدعاء … كما هو موضح أدناه:
>>> 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"], ... )