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

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. يبني هذا النموذج على بنية TimesFM الأصلية مع انتباه دوّار (rotary attention)، وتطبيع QK، وتوسيع الانتباه لكل بُعد، والتنبؤ المستمر بالكمّيات (quantile prediction).

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

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

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

يمكنك العثور على نقطة التفتيش في google/timesfm-2.5-200m-transformers.

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

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

< 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 = 16384horizon_length: int = 128num_hidden_layers: int = 20hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16rms_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)attention_dropout: float | int = 0.0initializer_range: float = 0.02num_key_value_heads: int = 16attention_bias: bool = Falseoutput_quantile_len: int = 1024decode_index: int = 5use_bias: bool = Falseactivation: str = 'swish'use_continuous_quantile_head: bool = Trueforce_flip_invariance: bool = Trueinfer_is_positive: bool = Truemax_position_embeddings: int = 16384rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )

المعاملات

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]) — الكمّيات (Quantiles) المراد التنبؤ بها.
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 جميع الرؤوس الأصلية داخل تلك المجموعة. لمزيد من التفاصيل، راجع هذا الورقة. إذا لم يتم تحديد القيمة، فستكون القيمة الافتراضية هي 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) — ما إذا كان سيتم استخدام رأس الكمية المستمر للتنبؤات الكمية غير الوسيط.
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 أطول.

هذه فئة الإعدادات المخزنة لإعدادات نموذج TimesFm2_5Model. تُستخدم لتوليد نموذج Timesfm2 5 وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن إنشاء إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ google/timesfm-2.5-200m-transformers

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

مثال:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

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

TimesFm2_5Model

فئة transformers.TimesFm2_5Model

< source >

( config: TimesFm2_5Config )

forward

< source >

( past_values: Tensorpast_values_padding: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5Output or tuple(torch.Tensor)

المعاملات

past_values (torch.Tensor من الشكل (batch_size, sequence_length)) — القيم السابقة لسلسلة الزمنية المستخدمة كمدخلات للنموذج.
past_values_padding (torch.LongTensor of shape (batch_size, sequence_length), اختياري) — قناع الحشو للمدخلات. 1 يشير إلى خطوات زمنية محشوّة (مقنّعة)، و0 يشير إلى قيم صالحة.

يعيد

TimesFm2_5Output أو tuple(torch.Tensor)

أُرجع كائن TimesFm2_5Output أو مجموعة مرتبة (tuple) من torch.Tensor (في حال تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة اعتماداً على الإعدادات (TimesFm2_5Config) والمدخلات.

تتجاوز طريقة TimesFm2_5Model الخاصة بالتقديم (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 of shape (batch_size,) or (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

< source >

( config: TimesFm2_5Config )

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

forward

< source >

( past_values: Sequencewindow_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonetruncate_negative: bool | None = Noneforce_flip_invariance: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5OutputForPrediction or tuple(torch.Tensor)

المعاملات

past_values (collections.abc.Sequence[torch.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) والمدخلات.

تتجاوز طريقة TimesFm2_5ModelForPrediction الخاصة بالتقديم (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 of shape (batch_size, horizon_length)) — توقعات حتمية بعد إزالة التطبيع.
full_predictions (torch.Tensor من الشكل (batch_size, horizon_length, quantiles)) — توقعات الكمّية (Quantile forecasts) بما في ذلك الوسيط بعد إزالة التطبيع.
loss (torch.Tensor of shape (1,), اختياري, يُعاد عند توفير future_values) — خسارة التدريب التي تجمع بين خسارة MSE وخسارة الفواصل (quantile) عند تقديم الأهداف.

Update on GitHub