# محوّل السلاسل الزمنية

## نظرة عامة

نموذج Time Series Transformer هو نموذج Transformer قياسي من نوع المُشفِّر-المُفكِّك (encoder-decoder) للتنبؤ بالمتسلسلات الزمنية. وقد ساهم في تطوير هذا النموذج [kashif](https://huggingface.co/kashif).

## نصائح للاستخدام

- على غرار النماذج الأخرى في المكتبة، يُعدّ [TimeSeriesTransformerModel](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerModel) نموذج Transformer خامًا دون أي رأس (head) فوقه، بينما [TimeSeriesTransformerForPrediction](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerForPrediction)
يضيف رأس توزيع فوق النموذج السابق، ويمكن استخدامه للتنبؤ بالسلاسل الزمنية. لاحظ أن هذا نموذج تنبؤ احتمالي، وليس نموذج تنبؤ بنقطة. وهذا يعني أن النموذج يتعلم توزيعًا يمكن أخذ عينات منه. لا يُخرج النموذج قيمًا مباشرة.
- يتكون [TimeSeriesTransformerForPrediction](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerForPrediction) من بلوكين: مُشفِّر يستقبل مدخلات من قيم السلاسل الزمنية بطول `context_length` (تُسمى `past_values`)،
ومفكّك (decoder) يتنبأ بـ `prediction_length` من قيم السلاسل الزمنية في المستقبل (تُسمى `future_values`). أثناء التدريب، يجب تقديم أزواج من (`past_values` و`future_values`) إلى النموذج.
- بالإضافة إلى القيم الخام (`past_values` و`future_values`)، يُقدَّم النموذج عادةً بميزات إضافية. ويمكن أن تكون هذه الميزات كالتالي:
  - `past_time_features`: ميزات زمنية سيقوم النموذج بإضافتها إلى `past_values`. تعمل هذه الميزات كـ "ترميز موضعي" لمشفّر Transformer. من الأمثلة عليها "يوم من الشهر"، "شهر من السنة"، وما إلى ذلك، بقيم قياسية (ثم تُرصّ معًا كمتجه). على سبيل المثال، إذا تم الحصول على قيمة معينة من السلسلة الزمنية في 11 أغسطس، فيمكن أن يكون متجه الميزة الزمنية [11, 8] (حيث يمثل 11 "يوم من الشهر"، ويمثل 8 "شهر من السنة").
  - `future_time_features`: خصائص زمنية سيقوم النموذج بإضافتها إلى `future_values`. تعمل هذه الخصائص كـ "ترميز موضعي" لفك تشفير Transformer. أمثلة عليها هي "يوم من الشهر"، "شهر من السنة"، وما إلى ذلك، بقيم قياسية (ثم تُرصّ معًا كمتجه). على سبيل المثال، إذا تم الحصول على قيمة سلسلة زمنية معينة في 11 أغسطس، فيمكن أن يكون متجه الخاصية الزمنية [11, 8] (حيث يمثل 11 "يوم من الشهر"، ويمثل 8 "شهر من السنة").
  - `static_categorical_features`: متغيرات فئوية ثابتة عبر الزمن (أي، لها القيمة نفسها لجميع `past_values` و`future_values`). مثال على ذلك معرّف المتجر أو معرّف المنطقة الذي يميّز سلسلة زمنية معينة. لاحظ أن هذه المتغيرات يجب أن تكون معروفة لجميع نقاط البيانات (بما في ذلك تلك الموجودة في المستقبل).
  - `static_real_features`: ميزات ذات قيم حقيقية ثابتة عبر الزمن (أي، لها القيمة نفسها لجميع `past_values` و`future_values`). مثال على ذلك هو تمثيل الصورة للمنتج الذي لديك قيم السلاسل الزمنية له (مثل تضمين [ResNet](resnet) لصورة "حذاء"، إذا كانت سلسلتك الزمنية تتعلق بمبيعات الأحذية). لاحظ أن هذه الميزات يجب أن تكون معروفة لجميع نقاط البيانات (بما في ذلك تلك الموجودة في المستقبل).
- يتم تدريب النموذج باستخدام "إجبار المعلم"، على غرار طريقة تدريب Transformer للترجمة الآلية. وهذا يعني أنه، أثناء التدريب، يتم إزاحة
`future_values` بمقدار موضع واحد إلى اليمين كمدخل إلى المُفكِّك، مع إضافة القيمة الأخيرة من `past_values` في البداية. في كل خطوة زمنية، يحتاج النموذج إلى التنبؤ بالهدف التالي. لذا فإن إعداد التدريب مشابه لنموذج GPT للغة، باستثناء عدم وجود مفهوم `decoder_start_token_id` (حيث نستخدم ببساطة القيمة الأخيرة من السياق كمدخل أولي للمُفكِّك).
- عند الاستدلال، نمدّ القيمة النهائية لـ `past_values` كمدخل إلى المُفكِّك. ثم يمكننا أخذ عينة من النموذج لإجراء تنبؤ في الخطوة الزمنية التالية،
يُمرَّر بعد ذلك إلى المُفكِّك (decoder) من أجل إجراء التنبؤ التالي (المعروف أيضًا بالتوليد الذاتي التتابعي).

## الموارد

قائمة بموارد رسمية من Hugging Face وموارد مجتمعية (مشار إليها بـ 🌎) لمساعدتك على البدء. إذا كنت مهتمًا بإرسال مورد ليُدرج هنا، فلا تتردد في فتح Pull Request وسنقوم بمراجعته! ويُفضّل أن يُظهر المورد شيئًا جديدًا بدلًا من تكرار مورد موجود مسبقًا.

- اطّلع على منشور مدونة Time Series Transformer في مدونة HuggingFace: [التنبؤ الاحتمالي بالسلاسل الزمنية باستخدام 🤗 Transformers](https://huggingface.co/blog/time-series-transformers)

## TimeSeriesTransformerConfig[[transformers.TimeSeriesTransformerConfig]]

#### transformers.TimeSeriesTransformerConfig[[transformers.TimeSeriesTransformerConfig]]

```python
transformers.TimeSeriesTransformerConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, prediction_length: int | None = None, context_length: int | None = None, distribution_output: str = 'student_t', loss: str = 'nll', input_size: int = 1, lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7), scaling: str | bool | None = 'mean', num_dynamic_real_features: int = 0, num_static_categorical_features: int = 0, num_static_real_features: int = 0, num_time_features: int = 0, cardinality: list[int] | None = None, embedding_dimension: list[int] | None = None, encoder_ffn_dim: int = 32, decoder_ffn_dim: int = 32, encoder_attention_heads: int = 2, decoder_attention_heads: int = 2, encoder_layers: int = 2, decoder_layers: int = 2, activation_function: str = 'gelu', d_model: int = 64, dropout: float | int = 0.1, encoder_layerdrop: float | int = 0.1, decoder_layerdrop: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.1, num_parallel_samples: int = 100, init_std: float = 0.02, use_cache: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/configuration_time_series_transformer.py#L24)

**المعاملات:**

is_encoder_decoder (`bool`، *اختياري*، الافتراضي هو `True`) : ما إذا كان النموذج يُستخدم كمُشفِّر/مُفكِّك أم لا.

prediction_length (`int`, *اختياري*) : طول التنبؤ للمفكّك. بعبارة أخرى، أفق التنبؤ للنموذج. عادةً ما يُحدَّد هذا القيمة بواسطة مجموعة البيانات، وننصح بإعدادها بشكل مناسب.

context_length (`int`، *اختياري*، القيمة الافتراضية هي `prediction_length`) : طول السياق للمشفّر. إذا كانت `None`، فسيكون طول السياق هو نفسه `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]`) : التأخيرات (lags) لسلسلة البيانات الزمنية المدخلة كمتغيرات مصاحبة، وغالبًا ما تُحدَّد بناءً على تكرار البيانات. القيمة الافتراضية هي `[1, 2, 3, 4, 5, 6, 7]`، لكننا نوصي بتغييرها بما يتناسب مع مجموعة البيانات.

scaling (`string` أو `bool`، *اختياري* القيمة الافتراضية `"mean"`) : ما إذا كان سيتم توسيع الأهداف المدخلة عبر مُوسِّع "mean" أو مُوسِّع "std" أو بدون مُوسِّع إذا كانت `None`. إذا كانت `True`، يتم تعيين المُوسِّع إلى "mean".

num_dynamic_real_features (`int`, *اختياري*, القيمة الافتراضية 0) : عدد الميزات الديناميكية ذات القيم الحقيقية.

num_static_categorical_features (`int`, *اختياري*, القيمة الافتراضية 0) : عدد الميزات التصنيفية الثابتة.

num_static_real_features (`int`, *اختياري*, القيمة الافتراضية 0) : عدد الميزات الثابتة ذات القيم الحقيقية.

num_time_features (`int`, *اختياري*, القيمة الافتراضية 0) : عدد ميزات الوقت في السلسلة الزمنية المدخلة.

cardinality (`list[int]`, *اختياري*) : الكاردينالية (عدد القيم المختلفة) لكل من الميزات التصنيفية الثابتة. يجب أن تكون قائمة من الأعداد الصحيحة، ذات نفس طول `num_static_categorical_features`. لا يمكن أن تكون `None` إذا كان `num_static_categorical_features` > 0.

embedding_dimension (`list[int]`, *اختياري*) : أبعاد التضمينات والحالات المخفية.

encoder_ffn_dim (`int`, *اختياري*, الافتراضي هو `32`) : أبعاد طبقة "الوسيطة" (المعروفة غالبًا باسم طبقة التقدّم الأمامي) في المُشفِّر.

decoder_ffn_dim (`int`، *اختياري*، الافتراضي هو `32`) : أبعاد طبقة "الوسيطة" (المعروفة غالبًا باسم طبقة التقدّم الأمامي) في المُفكِّك.

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` إذا لم يتم تعيينه.

activation_function (`str`، *اختياري*، القيمة الافتراضية `gelu`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، `"gelu"`، `"relu"`، `"silu"`، وما إلى ذلك.

d_model (`int`, *اختياري*, الافتراضي هو `64`) : حجم طبقات المُرمِّز وطبقة المُجمِّع.

dropout (`Union[float, int]`، *اختياري*، القيمة الافتراضية هي `0.1`) : النسبة لجميع طبقات dropout.

encoder_layerdrop (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.1`) : احتمال LayerDrop للمُشفِّر. راجع [ورقة LayerDrop](see https://huggingface.co/papers/1909.11556) لمزيد من التفاصيل.

decoder_layerdrop (`Union[float, int]`، *اختياري*، الافتراضي هو `0.1`) : احتمال LayerDrop للمفكّك. راجع [ورقة LayerDrop](see 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` أو عندما يكون النموذج نموذجًا توليديًا يعتمد على المُفكِّك فقط.

هذه فئة الإعدادات المخزنة لإعدادات نموذج TimeSeriesTransformerModel. تُستخدم لاستحداث نموذج Time Series Transformer وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [huggingface/time-series-transformer-tourism-monthly](https://huggingface.co/huggingface/time-series-transformer-tourism-monthly)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

مثال:

```python
>>> 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.config
```

## TimeSeriesTransformerModel[[transformers.TimeSeriesTransformerModel]]

#### transformers.TimeSeriesTransformerModel[[transformers.TimeSeriesTransformerModel]]

```python
transformers.TimeSeriesTransformerModel(config: TimeSeriesTransformerConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L782)

**المعاملات:**

config ([TimeSeriesTransformerConfig](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج Time Series Transformer الأساسي الذي يُخرج حالات مخفية خام دون أي رأس محدد في الأعلى.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.TimeSeriesTransformerModel.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L920)

**المعاملات:**

past_values (`torch.Tensor` من الشكل `(batch_size, sequence_length)` أو `(batch_size, sequence_length, input_size)`) : القيم السابقة لسلسلة الزمن، والتي تعمل كسياق للتنبؤ بالمستقبل. يجب أن يكون حجم التسلسل لهذا الموتر أكبر من `context_length` للنموذج، لأن النموذج سيستخدم الحجم الأكبر لبناء ميزات التأخير، أي قيم إضافية من الماضي تُضاف لتعمل كـ "سياق إضافي". `sequence_length` هنا يساوي `config.context_length` + `max(config.lags_sequence)`، والذي إذا لم يتم تكوين `lags_sequence`، يساوي `config.context_length` + 7 (لأن أكبر فهرس للنظر إلى الوراء في `config.lags_sequence` هو 7 افتراضيًا). الخاصية `_past_length` تعيد الطول الفعلي للماضي. `past_values` هو ما يحصل عليه مشفّر Transformer كمدخلات (مع ميزات إضافية اختيارية، مثل `static_categorical_features`، `static_real_features`، `past_time_features` والتأخيرات). بشكل اختياري، يجب استبدال القيم المفقودة بالصفر وإشارتها عبر `past_observed_mask`. لسلاسل الزمن متعددة المتغيرات، يُطلب بُعد `input_size` > 1، وهو يتوافق مع عدد المتغيرات في سلسلة الزمن لكل خطوة زمنية.

past_time_features (`torch.Tensor` من الشكل `(batch_size, sequence_length, num_features)`) : ميزات الوقت المطلوبة، والتي سيضيفها النموذج داخليًا إلى `past_values`. يمكن أن تكون هذه الميزات أشياء مثل "شهر السنة"، و"اليوم من الشهر"، وما إلى ذلك، مشفّرة كمتجهات (على سبيل المثال كميزات فورييه). كما يمكن أن تكون ما يُسمى بـ"ميزات العمر"، والتي تساعد النموذج في الأساس على معرفة "النقطة التي وصل إليها" السلاسل الزمنية في مسارها الزمني. تتميز ميزات العمر بقيم صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية. ميزات العطلات مثال جيد آخر على ميزات الوقت. تعمل هذه الميزات كـ"ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلم ترميزات الموضع من الصفر داخليًا كمعلمات للنموذج، يتطلب Time Series Transformer توفير ميزات وقت إضافية. يتعلم Time Series Transformer ترسيبات إضافية فقط لـ`static_categorical_features`. يمكن دمج متغيرات ديناميكية حقيقية إضافية مع هذا المصفوفة، مع ملاحظة أن هذه الميزات يجب أن تكون معروفة في وقت التنبؤ. `num_features` هنا يساوي `config.`num_time_features` + `config.num_dynamic_real_features`.

past_observed_mask (`torch.BoolTensor` من الشكل `(batch_size, sequence_length)` أو `(batch_size, sequence_length, input_size)`، *اختياري*) : قناع منطقي لتحديد أي قيم `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)` أو `(batch_size, prediction_length, input_size)`، *اختياري*) : القيم المستقبلية لسلسلة الزمن، والتي تعمل كوسوم للنموذج. القيمة `future_values` هي ما يحتاجه النموذج التحويلي (Transformer) أثناء التدريب ليتعلم الإخراج، بناءً على `past_values`. طول التسلسل هنا يساوي `prediction_length`. راجع دفتر الملاحظات التوضيحي ومقاطع الأكواد للتفاصيل. بشكل اختياري، أثناء التدريب يجب استبدال أي قيم مفقودة بالأصفار وإشارتها عبر `future_observed_mask`. بالنسبة لسلاسل الزمن متعددة المتغيرات، يُشترط وجود بُعد `input_size` > 1، وهو يتوافق مع عدد المتغيرات في سلسلة الزمن لكل خطوة زمنية.

future_time_features (`torch.Tensor` من الشكل `(batch_size, prediction_length, num_features)`) : الميزات الزمنية المطلوبة لنافذة التنبؤ، والتي ستضيفها النموذج داخليًا إلى `future_values`. يمكن أن تكون هذه الميزات أشياء مثل "شهر السنة" أو "اليوم من الشهر" وما إلى ذلك، مشفّرة كمتجهات (على سبيل المثال كميزات فورييه). كما يمكن أن تكون ما يُسمى بـ "ميزات العمر"، والتي تساعد النموذج في الأساس على معرفة "المرحلة من العمر" التي تتواجد فيها السلسلة الزمنية. تتميز ميزات العمر بقيم صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية. ميزات العطلات مثال جيد آخر على الميزات الزمنية. تعمل هذه الميزات كـ "ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلم ترميزات الموضع من الصفر داخليًا كمعلمات للنموذج، يتطلب Time Series Transformer توفير ميزات زمنية إضافية. يتعلم Time Series Transformer ترسيبات إضافية فقط لـ `static_categorical_features`. يمكن دمج متغيرات ديناميكية حقيقية إضافية مع هذا المصفوفة، مع ملاحظة أن هذه الميزات يجب أن تكون معروفة في وقت التنبؤ. `num_features` هنا يساوي `config.`num_time_features` + `config.num_dynamic_real_features`.

decoder_attention_mask (`torch.LongTensor` بأبعاد `(batch_size, target_sequence_length)`، *اختياري*) : قناع لتجنّب تنفيذ الانتباه على فهارس رموز معينة. افتراضيًا، يُستخدم قناع سببي لضمان أن النموذج لا ينظر إلّا إلى المدخلات السابقة من أجل التنبؤ بالمستقبل.

encoder_outputs (`tuple(tuple(torch.Tensor)`, *اختياري*) : يتكوّن Tuple من `last_hidden_state` و`hidden_states` (*اختياري*) و`attentions` (*اختياري*). `last_hidden_state` ذو الشكل `(batch_size, sequence_length, hidden_size)` (*اختياري*) هو تسلسل من الحالات المخفية عند مخرجات الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع في المُفكِّك.

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/main/ar/internal/generation_utils#transformers.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`).

**يعيد:** [Seq2SeqTSModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) أو `tuple(torch.Tensor)`

[Seq2SeqTSModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) أو مجموعة مرتبة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([TimeSeriesTransformerConfig](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig)) والمدخلات.

تُعيد طريقة [TimeSeriesTransformerModel](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerModel) الخاصة بالتقديم (forward) تعريف الطريقة الخاصة `__call__`.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن `Module` بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

- **last_hidden_state** (`torch.Tensor` بشكل `(batch_size, sequence_length, hidden_size)`) -- سلسلة من حالات الإخفاء عند مخرج الطبقة الأخيرة من فاحش النموذج.

  إذا تم استخدام `past_key_values`، فإن الحالة المخفية الأخيرة فقط من التسلسلات ذات الشكل `(batch_size, 1, hidden_size)` هي التي تُخرج.
- **past_key_values** (`EncoderDecoderCache`، *اختياري*، يُعاد عند تمرير `use_cache=True` أو عند `config.use_cache=True`) -- هو كائن من نوع [EncoderDecoderCache](/docs/transformers/main/ar/internal/generation_utils#transformers.EncoderDecoderCache). لمزيد من التفاصيل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache).

  تحتوي على حالات مخفية محسوبة مسبقًا (مفاتيح وقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها (انظر مدخل `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) عند مخرج كل طبقة، بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **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.Tensor` بأبعاد `(batch_size,)` أو `(batch_size, input_size)`، *اختياري*) -- إزاحة قيم نافذة السياق لكل سلسلة زمنية، والتي تُستخدم لإمداد النموذج بمدخلات ذات نفس المقدار، ثم تُستخدم للإزاحة مرة أخرى إلى المقدار الأصلي.
- **scale** (`torch.Tensor` بأبعاد `(batch_size,)` أو `(batch_size, input_size)`، *اختياري*) -- قيم التوسيع الخاصة بنافذة السياق لكل سلسلة زمنية، وتُستخدم لإعطاء النموذج مدخلات بنفس المقدار، ثم تُستخدم لإعادة القياس إلى المقدار الأصلي.
- **static_features** (`torch.Tensor` بأبعاد `(batch_size, feature size)`، *اختياري*) -- الميزات الثابتة لكل سلسلة زمنية في الدفعة، والتي تُنسخ إلى المتغيرات المصاحبة عند الاستدلال.

أمثلة:

```python
>>> 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_state
```

## TimeSeriesTransformerForPrediction[[transformers.TimeSeriesTransformerForPrediction]]

#### transformers.TimeSeriesTransformerForPrediction[[transformers.TimeSeriesTransformerForPrediction]]

```python
transformers.TimeSeriesTransformerForPrediction(config: TimeSeriesTransformerConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L1114)

**المعاملات:**

config ([TimeSeriesTransformerConfig](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج Time Series Transformer مع رأس توزيع في الأعلى للتنبؤ بالسلاسل الزمنية.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.TimeSeriesTransformerForPrediction.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, future_observed_mask: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L1148)

**المعاملات:**

past_values (`torch.Tensor` من الشكل `(batch_size, sequence_length)` أو `(batch_size, sequence_length, input_size)`) : القيم السابقة لسلسلة الزمن، والتي تعمل كسياق للتنبؤ بالمستقبل. يجب أن يكون حجم التسلسل لهذا الموتر أكبر من `context_length` للنموذج، لأن النموذج سيستخدم الحجم الأكبر لبناء ميزات التأخير، أي قيم إضافية من الماضي تُضاف لتعمل كـ "سياق إضافي". `sequence_length` هنا يساوي `config.context_length` + `max(config.lags_sequence)`، والذي إذا لم يتم تكوين `lags_sequence`، يساوي `config.context_length` + 7 (لأن أكبر فهرس للنظر إلى الوراء في `config.lags_sequence` هو 7 افتراضيًا). الخاصية `_past_length` تعيد الطول الفعلي للماضي. `past_values` هو ما يحصل عليه مشفّر Transformer كمدخلات (مع ميزات إضافية اختيارية، مثل `static_categorical_features`، `static_real_features`، `past_time_features` والتأخيرات). بشكل اختياري، يجب استبدال القيم المفقودة بالصفر وإشارتها عبر `past_observed_mask`. لسلاسل الزمن متعددة المتغيرات، يُطلب بُعد `input_size` > 1، وهو يتوافق مع عدد المتغيرات في سلسلة الزمن لكل خطوة زمنية.

past_time_features (`torch.Tensor` من الشكل `(batch_size, sequence_length, num_features)`) : ميزات الوقت المطلوبة، والتي سيضيفها النموذج داخليًا إلى `past_values`. يمكن أن تكون هذه الميزات أشياء مثل "شهر السنة"، و"اليوم من الشهر"، وما إلى ذلك، مشفّرة كمتجهات (على سبيل المثال كميزات فورييه). كما يمكن أن تكون ما يُسمى بـ"ميزات العمر"، والتي تساعد النموذج في الأساس على معرفة "النقطة التي وصل إليها" السلاسل الزمنية في مسارها الزمني. تتميز ميزات العمر بقيم صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية. ميزات العطلات مثال جيد آخر على ميزات الوقت. تعمل هذه الميزات كـ"ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلم ترميزات الموضع من الصفر داخليًا كمعلمات للنموذج، يتطلب Time Series Transformer توفير ميزات وقت إضافية. يتعلم Time Series Transformer ترسيبات إضافية فقط لـ`static_categorical_features`. يمكن دمج متغيرات ديناميكية حقيقية إضافية مع هذا المصفوفة، مع ملاحظة أن هذه الميزات يجب أن تكون معروفة في وقت التنبؤ. `num_features` هنا يساوي `config.`num_time_features` + `config.num_dynamic_real_features`.

past_observed_mask (`torch.BoolTensor` من الشكل `(batch_size, sequence_length)` أو `(batch_size, sequence_length, input_size)`، *اختياري*) : قناع منطقي لتحديد أي قيم `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)` أو `(batch_size, prediction_length, input_size)`، *اختياري*) : القيم المستقبلية لسلسلة الزمن، والتي تعمل كوسوم للنموذج. القيمة `future_values` هي ما يحتاجه النموذج التحويلي (Transformer) أثناء التدريب ليتعلم الإخراج، بناءً على `past_values`. طول التسلسل هنا يساوي `prediction_length`. راجع دفتر الملاحظات التوضيحي ومقاطع الأكواد للتفاصيل. بشكل اختياري، أثناء التدريب يجب استبدال أي قيم مفقودة بالأصفار وإشارتها عبر `future_observed_mask`. بالنسبة لسلاسل الزمن متعددة المتغيرات، يُشترط وجود بُعد `input_size` > 1، وهو يتوافق مع عدد المتغيرات في سلسلة الزمن لكل خطوة زمنية.

future_time_features (`torch.Tensor` من الشكل `(batch_size, prediction_length, num_features)`) : الميزات الزمنية المطلوبة لنافذة التنبؤ، والتي ستضيفها النموذج داخليًا إلى `future_values`. يمكن أن تكون هذه الميزات أشياء مثل "شهر السنة" أو "اليوم من الشهر" وما إلى ذلك، مشفّرة كمتجهات (على سبيل المثال كميزات فورييه). كما يمكن أن تكون ما يُسمى بـ "ميزات العمر"، والتي تساعد النموذج في الأساس على معرفة "المرحلة من العمر" التي تتواجد فيها السلسلة الزمنية. تتميز ميزات العمر بقيم صغيرة للخطوات الزمنية البعيدة في الماضي، وتزداد بشكل متزايد كلما اقتربنا من الخطوة الزمنية الحالية. ميزات العطلات مثال جيد آخر على الميزات الزمنية. تعمل هذه الميزات كـ "ترميز الموضع" للمدخلات. لذا، على عكس نموذج مثل BERT، حيث يتم تعلم ترميزات الموضع من الصفر داخليًا كمعلمات للنموذج، يتطلب Time Series Transformer توفير ميزات زمنية إضافية. يتعلم Time Series Transformer ترسيبات إضافية فقط لـ `static_categorical_features`. يمكن دمج متغيرات ديناميكية حقيقية إضافية مع هذا المصفوفة، مع ملاحظة أن هذه الميزات يجب أن تكون معروفة في وقت التنبؤ. `num_features` هنا يساوي `config.`num_time_features` + `config.num_dynamic_real_features`.

future_observed_mask (`torch.BoolTensor` من الشكل `(batch_size, sequence_length)` أو `(batch_size, sequence_length, input_size)`، *اختياري*) : قناع منطقي يُبيّن أيّ قيم `future_values` كانت مُلاحَظة وأيّها كانت مفقودة. قيم القناع المختارة من `[0, 1]`: - 1 للقيم **المُلاحَظة**، - 0 للقيم **المفقودة** (أي قيم NaN التي استُبدلت بالأصفار). يُستخدم هذا القناع لاستبعاد القيم المفقودة في حساب الدالة النهائية.

decoder_attention_mask (`torch.LongTensor` بأبعاد `(batch_size, target_sequence_length)`، *اختياري*) : قناع لتجنّب تنفيذ الانتباه على فهارس رموز معينة. افتراضيًا، يُستخدم قناع سببي لضمان أن النموذج لا ينظر إلّا إلى المدخلات السابقة من أجل التنبؤ بالمستقبل.

encoder_outputs (`tuple(tuple(torch.Tensor)`, *اختياري*) : يتكوّن Tuple من `last_hidden_state` و`hidden_states` (*اختياري*) و`attentions` (*اختياري*). `last_hidden_state` ذو الشكل `(batch_size, sequence_length, hidden_size)` (*اختياري*) هو تسلسل من الحالات المخفية عند مخرجات الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع في المُفكِّك.

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/main/ar/internal/generation_utils#transformers.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`).

**يعيد:** [Seq2SeqTSModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) أو `tuple(torch.Tensor)`

[Seq2SeqTSModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) أو مجموعة مرتبة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([TimeSeriesTransformerConfig](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig)) والمدخلات.

تتجاوز طريقة [TimeSeriesTransformerForPrediction](/docs/transformers/main/ar/model_doc/time_series_transformer#transformers.TimeSeriesTransformerForPrediction) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن `Module` بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

- **last_hidden_state** (`torch.Tensor` بشكل `(batch_size, sequence_length, hidden_size)`) -- سلسلة من حالات الإخفاء عند مخرج الطبقة الأخيرة من فاحش النموذج.

  إذا تم استخدام `past_key_values`، فإن الحالة المخفية الأخيرة فقط من التسلسلات ذات الشكل `(batch_size, 1, hidden_size)` هي التي تُخرج.
- **past_key_values** (`EncoderDecoderCache`، *اختياري*، يُعاد عند تمرير `use_cache=True` أو عند `config.use_cache=True`) -- هو كائن من نوع [EncoderDecoderCache](/docs/transformers/main/ar/internal/generation_utils#transformers.EncoderDecoderCache). لمزيد من التفاصيل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache).

  تحتوي على حالات مخفية محسوبة مسبقًا (مفاتيح وقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها (انظر مدخل `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) عند مخرج كل طبقة، بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **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.Tensor` بأبعاد `(batch_size,)` أو `(batch_size, input_size)`، *اختياري*) -- إزاحة قيم نافذة السياق لكل سلسلة زمنية، والتي تُستخدم لإمداد النموذج بمدخلات ذات نفس المقدار، ثم تُستخدم للإزاحة مرة أخرى إلى المقدار الأصلي.
- **scale** (`torch.Tensor` بأبعاد `(batch_size,)` أو `(batch_size, input_size)`، *اختياري*) -- قيم التوسيع الخاصة بنافذة السياق لكل سلسلة زمنية، وتُستخدم لإعطاء النموذج مدخلات بنفس المقدار، ثم تُستخدم لإعادة القياس إلى المقدار الأصلي.
- **static_features** (`torch.Tensor` بأبعاد `(batch_size, feature size)`، *اختياري*) -- الميزات الثابتة لكل سلسلة زمنية في الدفعة، والتي تُنسخ إلى المتغيرات المصاحبة عند الاستدلال.

أمثلة:

```python
>>> 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)
```