# TimesFM

## نظرة عامة

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model proposed in [A decoder-only foundation model for time-series forecasting](https://huggingface.co/papers/2310.10688) by Abhimanyu Das, Weihao Kong, Rajat Sen, and  Yichen Zhou. It is a decoder only model that uses non-overlapping patches of time-series data as input and outputs some output patch length prediction in an autoregressive fashion.

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

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

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

لاستخدام النموذج:

```python
import numpy as np
import torch

from transformers import TimesFmModelForPrediction

model = TimesFmModelForPrediction.from_pretrained(
    "google/timesfm-2.0-500m-pytorch",
    attn_implementation="sdpa",
    device_map="auto"
)

 # Create dummy inputs
forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]

# Convert inputs to sequence of tensors
forecast_input_tensor = [
    torch.tensor(ts).to(model.device)
    for ts in forecast_input
]
frequency_input_tensor = torch.tensor(frequency_input, dtype=torch.long).to(model.device)

# Get predictions from the pre-trained model
with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, freq=frequency_input_tensor, return_dict=True)
    point_forecast_conv = outputs.mean_predictions.float().cpu().numpy()
    quantile_forecast_conv = outputs.full_predictions.float().cpu().numpy()
```

## TimesFmConfig[[transformers.TimesFmConfig]]

#### transformers.TimesFmConfig[[transformers.TimesFmConfig]]

```python
transformers.TimesFmConfig(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 = 512, horizon_length: int = 128, freq_size: int = 3, num_hidden_layers: int = 50, hidden_size: int = 1280, intermediate_size: int = 1280, head_dim: int = 80, num_attention_heads: int = 16, tolerance: float = 1e-06, 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), pad_val: float = 1123581321.0, attention_dropout: float | int = 0.0, use_positional_embedding: bool = False, initializer_range: float = 0.02, min_timescale: int = 1, max_timescale: int = 10000)
```

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

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

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

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

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

freq_size (`int`، *اختياري*، القيمة الافتراضية 3) : عدد تضمينات التردد.

num_hidden_layers (`int`، *اختياري*، القيمة الافتراضية `50`) : عدد الطبقات المخفية في مُفكِّك 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.

tolerance (`float`، *اختياري*، القيمة الافتراضية 1e-06) : التسامح لخسارة الكمّية.

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]`) : الكتل التي سيتم التنبؤ بها.

pad_val (`float`، *اختياري*، القيمة الافتراضية 1123581321.0) : القيمة المستخدمة لتعبئة التوقعات.

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

use_positional_embedding (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب إضافة تضمينات موضعية.

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

min_timescale (`int`، *اختياري*، القيمة الافتراضية 1) : بداية الفهرس الموضعي الهندسي. يحدد دورية الإشارة المضافة.

max_timescale (`int`، *اختياري*، القيمة الافتراضية 10000) : نهاية المؤشر الموضعي الهندسي. يحدد تردد الإشارة المضافة.

هذه فئة الإعدادات المخزنة لإعدادات نموذج TimesFmModel. تُستخدم لاستحداث نموذج Timesfm وفقًا للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [google/timesfm-2.0-500m-pytorch](https://huggingface.co/google/timesfm-2.0-500m-pytorch)

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

## TimesFmModel[[transformers.TimesFmModel]]

#### transformers.TimesFmModel[[transformers.TimesFmModel]]

```python
transformers.TimesFmModel(config: TimesFmConfig)
```

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

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

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

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

يرث هذا النموذج من [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.TimesFmModel.forward]]

```python
forward(past_values: Tensor, past_values_padding: LongTensor, freq: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

past_values_padding (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`) : مؤشر التعبئة لسلسلة البيانات الزمنية.

freq (`torch.LongTensor` من الشكل `(batch_size,)`) : فهارس التردد لبيانات السلاسل الزمنية.

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

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

تتجاوز طريقة [TimesFmModel](/docs/transformers/main/ar/model_doc/timesfm#transformers.TimesFmModel) الخاصة بالتقديم (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, )`) -- متوسط مدخلات السلاسل الزمنية.
- **scale** (`torch.Tensor` من الشكل `(batch_size,)`) -- مقياس مدخلات السلاسل الزمنية.

## TimesFmModelForPrediction[[transformers.TimesFmModelForPrediction]]

#### transformers.TimesFmModelForPrediction[[transformers.TimesFmModelForPrediction]]

```python
transformers.TimesFmModelForPrediction(config: TimesFmConfig)
```

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

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

#### forward[[transformers.TimesFmModelForPrediction.forward]]

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

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

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

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

freq (`torch.LongTensor` من الشكل `(batch_size,)`) : فهارس التردد لبيانات السلاسل الزمنية.

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

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

forecast_context_len (`int`، *اختياري*) : الحد الأقصى اختياري لطول السياق.

return_forecast_on_context (`bool`، *اختياري*) : True للإرجاع التنبؤ على السياق عند توفره، أي بعد أول رقعة إدخال.

truncate_negative (`bool`، *اختياري*) : إذا كانت أي من السياقات تحتوي على قيم غير سالبة، يتم اقتطاع القيم إلى القيم غير السالبة فقط، وإلا لا يتم تنفيذ أي إجراء.

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

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

تُعيد طريقة [TimesFmModelForPrediction](/docs/transformers/main/ar/model_doc/timesfm#transformers.TimesFmModelForPrediction) الخاصة بالتقديم (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, sequence_length)`) -- متوسطات التنبؤات لسلسلة الزمن.
- **full_predictions** (`torch.Tensor` من الشكل `(batch_size, sequence_length)`) -- التوقعات الكاملة لسلسلة الزمنية بما في ذلك المتوسط والنسب المئوية.
- **loss** (`torch.Tensor` من الشكل `(1,)`، *اختياري*، يُعاد عند تقديم `future_values`) -- خسارة نموذج TimesFM.

مثال:

```python
>>> from transformers import TimesFmModelForPrediction

>>> model = TimesFmModelForPrediction.from_pretrained("google/timesfm-2.0-500m-pytorch")

>>> forecast_input = [torch.linspace(0, 20, 100).sin(), torch.linspace(0, 20, 200).sin(), torch.linspace(0, 20, 400).sin()]
>>> frequency_input = torch.tensor([0, 1, 2], dtype=torch.long)

>>> # Generate
>>> with torch.no_grad():
>>>     outputs = model(past_values=forecast_input, freq=frequency_input, return_dict=True)
>>>     point_forecast_conv = outputs.mean_predictions
>>>     quantile_forecast_conv = outputs.full_predictions
```