# TimesFM 2.5

## نظرة عامة

TimesFM 2.5 (Time Series Foundation Model) هو نموذج أساسي مسبق التدريب لسلاسل الزمنية، اقترحه Abhimanyu Das وWeihao Kong وRajat Sen وYichen Zhou في [A decoder-only foundation model for time-series forecasting](https://huggingface.co/papers/2310.10688). يبني هذا النموذج على بنية TimesFM الأصلية مع انتباه دوّار (rotary attention)، وتطبيع QK، وتوسيع الانتباه لكل بُعد، والتنبؤ المستمر بالكمّيات (quantile prediction).

المستخلص من الورقة البحثية هو كالتالي:

*بفضل التطورات الأخيرة في نماذج اللغة الكبيرة لمعالجة اللغة الطبيعية (NLP)، صممنا نموذجًا أساسيًا (foundation model) للسلاسل الزمنية للتنبؤ، حيث تقترب أدائه الصفرية (zero-shot) الجاهزة للاستخدام على مجموعة متنوعة من مجموعات البيانات العامة من دقة أحدث نماذج التنبؤ المُشرفة (supervised) لكل مجموعة بيانات على حدة. يعتمد نموذجنا على تدريب مسبق لنموذج انتباه (attention) بنمط المُفكِّك (decoder) مع تقطيع المدخلات (input patching)، باستخدام قاعدة بيانات ضخمة للسلاسل الزمنية تشمل مجموعات بيانات حقيقية واصطناعية. تشير التجارب على مجموعة متنوعة من مجموعات بيانات التنبؤ غير المرئية سابقًا إلى أن النموذج قادر على تقديم تنبؤات صفرية دقيقة عبر مجالات مختلفة، وأُفق زمني للتنبؤ، ودقة زمنية متباينة.*

تمت مساهمة هذا النموذج من قِبل [kashif](https://huggingface.co/kashif). يمكن العثور على الكود الأصلي [هنا](https://github.com/google-research/timesfm).

يمكنك العثور على نقطة التفتيش في [`google/timesfm-2.5-200m-transformers`](https://huggingface.co/google/timesfm-2.5-200m-transformers).

## مثال على الاستخدام

```python
import numpy as np
import torch

from transformers import TimesFm2_5ModelForPrediction

model = TimesFm2_5ModelForPrediction.from_pretrained(
    "google/timesfm-2.5-200m-transformers",
    device_map="auto",
)

forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
forecast_input_tensor = [torch.tensor(ts, dtype=torch.float32, device=model.device) for ts in forecast_input]

with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, return_dict=True)
    point_forecast = outputs.mean_predictions
    quantile_forecast = outputs.full_predictions
```

## TimesFm2_5Config[[transformers.TimesFm2_5Config]]

#### transformers.TimesFm2_5Config[[transformers.TimesFm2_5Config]]

```python
transformers.TimesFm2_5Config(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, is_encoder_decoder: bool = False, 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, patch_length: int = 32, context_length: int = 16384, horizon_length: int = 128, num_hidden_layers: int = 20, hidden_size: int = 1280, intermediate_size: int = 1280, head_dim: int = 80, num_attention_heads: int = 16, rms_norm_eps: float = 1e-06, quantiles: list[float] | tuple[float, ...] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9), attention_dropout: float | int = 0.0, initializer_range: float = 0.02, num_key_value_heads: int = 16, attention_bias: bool = False, output_quantile_len: int = 1024, decode_index: int = 5, use_bias: bool = False, activation: str = 'swish', use_continuous_quantile_head: bool = True, force_flip_invariance: bool = True, infer_is_positive: bool = True, max_position_embeddings: int = 16384, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None)
```

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

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

patch_length (`int`، *اختياري*، القيمة الافتراضية 32) : طول الباتش الواحد في تسلسل الإدخال.

context_length (`int`، *اختياري*، القيمة الافتراضية 16384) : طول سياق الإدخال.

horizon_length (`int`، *اختياري*، القيمة الافتراضية 128) : طول أفق التنبؤ.

num_hidden_layers (`int`، *اختياري*، القيمة الافتراضية `20`) : عدد الطبقات المخفية في مُفكِّك Transformer.

hidden_size (`int`، *اختياري*، القيمة الافتراضية `1280`) : بُعد التمثيلات المخفية.

intermediate_size (`int`، *اختياري*، القيمة الافتراضية `1280`) : بُعد تمثيلات MLP.

head_dim (`int`، *اختياري*، القيمة الافتراضية `80`) : بُعد رأس الانتباه. إذا كانت القيمة None، فستكون القيمة الافتراضية هي hidden_size // num_attention_heads

num_attention_heads (`int`، *اختياري*، القيمة الافتراضية `16`) : عدد رؤوس الانتباه في كل طبقة انتباه داخل مُفكِّك Transformer.

rms_norm_eps (`float`، *اختياري*، القيمة الافتراضية `1e-06`) : قيمة الإيبسلون المستخدمة في طبقات تطبيع rms.

quantiles (`list[float]`، *اختياري*، القيمة الافتراضية `[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]`) : الكتل التي سيتم التنبؤ بها.

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

initializer_range (`float`، *اختياري*، القيمة الافتراضية `0.02`) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.

num_key_value_heads (`int`، *اختياري*، القيمة الافتراضية `16`) : هذا هو عدد رؤوس key_value التي يجب استخدامها لتنفيذ Grouped Query Attention. إذا كان `num_key_value_heads=num_attention_heads`، فسيستخدم النموذج Multi Head Attention (MHA)، وإذا كان `num_key_value_heads=1` فسيستخدم النموذج Multi Query Attention (MQA)، وإلا فسيتم استخدام GQA. عند تحويل نقطة تحقق متعددة الرؤوس إلى نقطة تحقق GQA، يجب بناء كل مجموعة من رؤوس key و value عن طريق meanpooling جميع الرؤوس الأصلية داخل تلك المجموعة. لمزيد من التفاصيل، راجع [هذا الورق](https://huggingface.co/papers/2305.13245). إذا لم يتم تحديد القيمة، فستكون القيمة الافتراضية هي `num_attention_heads`.

attention_bias (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم استخدام انحياز في طبقات الإسقاط للاستعلام والمفتاح والقيمة والمخرجات أثناء الانتباه الذاتي.

output_quantile_len (`int`، *اختياري*، القيمة الافتراضية 1024) : طول بُعد الإسقاط الخاص بمخرجات الكوانتايل.

decode_index (`int`، *اختياري*، القيمة الافتراضية 5) : فهرس في بُعد الكمية (quantile) المستخدم لاستخراج التنبؤ بالنقطة (الوسيط).

use_bias (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان سيتم استخدام الانحياز في طبقات MLP والطبقات الخطية في المحوّل.

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

use_continuous_quantile_head (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم استخدام رأس الكمية المستمر (continuous quantile head) للتنبؤات غير الوسيطية.

force_flip_invariance (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تطبيق متوسط عدم التماثل عند الانقلاب أثناء التنبؤ.

infer_is_positive (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تقييد التوقعات بقيم غير سالبة عندما تكون القيمة الدنيا للمدخلات غير سالبة.

max_position_embeddings (`int`، *اختياري*، القيمة الافتراضية `16384`) : الحد الأقصى لطول التسلسل الذي قد يُستخدم به هذا النموذج.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`، *اختياري*) : قاموس يحتوي على معاملات التهيئة الخاصة بتضمينات RoPE. يجب أن يحتوي القاموس على قيمة لـ `rope_theta`، وبشكل اختياري معاملات تُستخدم للتوسيع في حال رغبتَ في استخدام RoPE مع `max_position_embeddings` أطول.

هذه فئة الإعدادات (configuration class) لتخزين إعدادات نموذج TimesFm2_5Model. تُستخدم لاستحداث نموذج Timesfm2 5 وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ [google/timesfm-2.5-200m-transformers](https://huggingface.co/google/timesfm-2.5-200m-transformers)

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

مثال:

```python
>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

>>> configuration = TimesFm2_5Config()
>>> model = TimesFm2_5ModelForPrediction(configuration)
>>> configuration = model.config
```

## TimesFm2_5Model[[transformers.TimesFm2_5Model]]

#### transformers.TimesFm2_5Model[[transformers.TimesFm2_5Model]]

```python
transformers.TimesFm2_5Model(config: TimesFm2_5Config)
```

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

#### forward[[transformers.TimesFm2_5Model.forward]]

```python
forward(past_values: Tensor, past_values_padding: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

past_values (`torch.Tensor` من الشكل `(batch_size, sequence_length)`) : القيم السابقة لسلسلة الزمنية المستخدمة كمدخلات للنموذج.

past_values_padding (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : قناع الحشو للمدخل. `1` يشير إلى خطوات زمنية محشوة (مقنّعة)، و`0` يشير إلى قيم صالحة.

**يعيد:** `TimesFm2_5Output` أو `tuple(torch.Tensor)`

A `TimesFm2_5Output` or a tuple of `torch.Tensor` (if `return_dict=False` is passed or when `config.return_dict=False`) comprising various elements depending on the configuration ([TimesFm2_5Config](/docs/transformers/main/ar/model_doc/timesfm2_5#transformers.TimesFm2_5Config)) and inputs.

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

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

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`) -- تسلسل من حالات الإخفاء (hidden-states) عند مخرج الطبقة الأخيرة من النموذج.
- **hidden_states** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) بأبعاد `(batch_size, sequence_length, hidden_size)`.

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

## TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

#### transformers.TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

```python
transformers.TimesFm2_5ModelForPrediction(config: TimesFm2_5Config)
```

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

نموذج TimesFm2_5 للتنبؤ بالكمّية والمتوسط.

#### forward[[transformers.TimesFm2_5ModelForPrediction.forward]]

```python
forward(past_values: Sequence, window_size: int | None = None, future_values: typing.Optional[torch.Tensor] = None, forecast_context_len: int | None = None, truncate_negative: bool | None = None, force_flip_invariance: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

past_values (`collections.abc.Sequence[torch.Tensor]`) : القيم السابقة لسلسلة الزمنية التي تعمل كمدخل للنموذج. كل متجه (Tensor) هو سلسلة زمنية أحادية البعد.

window_size (`int`, *اختياري*) : حجم نافذة تحليل الاتجاه والمكوّن المتبقي. إذا كانت `None`، فلن يُطبَّق التحليل.

future_values (`torch.Tensor`، *اختياري*) : قيم مستقبلية اختيارية تُستخدم لحساب الخسارة.

forecast_context_len (`int`, *اختياري*) : تجاوز اختياري لطول السياق يُستخدم أثناء التنبؤ.

truncate_negative (`bool`، *اختياري*) : ما إذا كان سيتم تقييد المخرجات بقيم غير سالبة. إذا كانت `None`، فإن القيمة الافتراضية هي `config.infer_is_positive`.

force_flip_invariance (`bool`, *اختياري*) : ما إذا كان سيتم تطبيق تركيب عدم التماثل عند القلب. إذا كان `None`، فإن القيمة الافتراضية هي `config.force_flip_invariance`.

**يعيد:** `TimesFm2_5OutputForPrediction` أو `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`) -- تسلسل من حالات الإخفاء (hidden-states) عند مخرج الطبقة الأخيرة من النموذج.
- **hidden_states** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) بأبعاد `(batch_size, sequence_length, hidden_size)`.

  حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **attentions** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_attentions=True` أو عند تعيين `config.output_attentions=True`) -- مجموعة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **mean_predictions** (`torch.Tensor` من الشكل `(batch_size, horizon_length)`) -- تنبؤات حتمية بعد إزالة التطبيع.
- **full_predictions** (`torch.Tensor` من الشكل `(batch_size, horizon_length, quantiles)`) -- توقعات الكمّية بما في ذلك الوسيط بعد إزالة التطبيع.
- **loss** (`torch.Tensor` of shape `(1,)`, *اختياري*, يُعاد عند تقديم `future_values`) -- خسارة التدريب التي تجمع بين خسارة MSE وخسارة quantile عند توفير الأهداف.