نُشر هذا النموذج في أوراق HF في 14 أكتوبر 2023، وأُضيف إلى مكتبة Hugging Face Transformers في 16 أبريل 2025.

TimesFM

نظرة عامة

TimesFM (Time Series Foundation Model) هو نموذج أساسي مسبق التدريب لسلاسل الزمنية، اقترحه كلٌّ من Abhimanyu Das وWeihao Kong وRajat Sen وYichen Zhou في ورقة A decoder-only foundation model for time-series forecasting. وهو نموذج يعتمد على المُفكِّك فقط، حيث يستقبل كتلًا غير متداخلة من بيانات سلسلة الزمنية كمدخلات، ثم يُولِّد تنبؤًا بطول كتلة محددة بطريقة ذاتية التراجع.

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

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

تمت مساهمة هذا النموذج من قِبل kashif. يمكن العثور على الكود الأصلي هنا.

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

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

< 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 = 0is_encoder_decoder: bool = Falseid2label: 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 = Nonepatch_length: int = 32context_length: int = 512horizon_length: int = 128freq_size: int = 3num_hidden_layers: int = 50hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16tolerance: float = 1e-06rms_norm_eps: float = 1e-06quantiles: 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.0attention_dropout: float | int = 0.0use_positional_embedding: bool = Falseinitializer_range: float = 0.02min_timescale: int = 1max_timescale: int = 10000 )

المعاملات

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]) — الكمّيات (Quantiles) المراد التنبؤ بها.
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) — نهاية المؤشر الموضعي الهندسي. يحدد تردد الإشارة المضافة.

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

ترث كائنات التهيئة من PreTrainedConfig ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ PreTrainedConfig لمزيد من المعلومات.

TimesFmModel

فئة transformers.TimesFmModel

< source >

( config: TimesFmConfig )

المعاملات

config (TimesFmConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعداد إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.

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

يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

forward

< source >

( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)

المعاملات

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 أو مجموعة مرتبة من torch.Tensor (في حال تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة تعتمد على الإعدادات (TimesFmConfig) والمدخلات.

تتجاوز طريقة TimesFmModel الخاصة بالتقديم (forward) الطريقة الخاصة __call__.

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

last_hidden_state (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)) — تسلسل حالات مخفية عند مخرج الطبقة الأخيرة من النموذج.
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

< source >

( config: TimesFmConfig )

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

forward

< source >

( past_values: Sequencefreq: collections.abc.Sequence[typing.Union[torch.Tensor, int]] | None = Nonewindow_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonereturn_forecast_on_context: bool = Falsetruncate_negative: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutputForPrediction or tuple(torch.Tensor)

المعاملات

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) والمدخلات.

تُعيد طريقة TimesFmModelForPrediction الخاصة بالتقديم (forward) تعريف الطريقة الخاصة __call__.

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

last_hidden_state (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)) — تسلسل حالات مخفية عند مخرج الطبقة الأخيرة من النموذج.
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.

مثال:

>>> 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

Update on GitHub