Mô hình này được công bố trên HF papers vào ngày 2023-10-14 và được đóng góp cho Hugging Face Transformers vào ngày 2026-02-27.

TimesFM 2.5

Tổng quan

TimesFM 2.5 (Time Series Foundation Model) là một mô hình nền tảng cho chuỗi thời gian được huấn luyện trước, được đề xuất trong A decoder-only foundation model for time-series forecasting bởi Abhimanyu Das, Weihao Kong, Rajat Sen và Yichen Zhou. Nó được xây dựng dựa trên kiến trúc TimesFM ban đầu với rotary attention, QK normalization, per-dimension attention scaling và continuous quantile prediction.

Tóm tắt từ bài báo như sau:

Được thúc đẩy bởi những tiến bộ gần đây của các mô hình ngôn ngữ lớn trong Xử lý Ngôn ngữ Tự nhiên (NLP), chúng tôi thiết kế một mô hình nền tảng cho chuỗi thời gian phục vụ dự báo, với hiệu suất zero-shot ngay lập tức trên nhiều bộ dữ liệu công khai tiệm cận độ chính xác của các mô hình dự báo có giám sát tiên tiến nhất cho từng bộ dữ liệu riêng lẻ. Mô hình của chúng tôi dựa trên việc tiền huấn luyện một mô hình chú ý kiểu decoder với kỹ thuật patch đầu vào, sử dụng một kho ngữ liệu chuỗi thời gian lớn bao gồm cả các bộ dữ liệu thực tế và tổng hợp. Các thí nghiệm trên một tập hợp đa dạng các bộ dữ liệu dự báo chưa từng thấy trước đó cho thấy mô hình có thể tạo ra các dự báo zero-shot chính xác trên các lĩnh vực khác nhau, các chân trời dự báo và các mức độ hạt thời gian khác nhau.

Mô hình này được đóng góp bởi kashif. Mã gốc có thể được tìm thấy tại đây.

Bạn có thể tìm thấy checkpoint tại google/timesfm-2.5-200m-transformers.

Ví dụ sử dụng

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

lớp 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 )

Tham số

patch_length (int, tùy chọn, mặc định là 32) — Chiều dài của một patch trong chuỗi đầu vào.
context_length (int, tùy chọn, mặc định là 16384) — Độ dài của ngữ cảnh đầu vào.
horizon_length (int, tùy chọn, mặc định là 128) — Chiều dài của chân trời dự đoán.
num_hidden_layers (int, tùy chọn, mặc định là 20) — Số lượng lớp ẩn trong bộ giải mã Transformer.
hidden_size (int, tùy chọn, mặc định là 1280) — Kích thước của các biểu diễn ẩn.
intermediate_size (int, tùy chọn, mặc định là 1280) — Kích thước của các biểu diễn MLP.
head_dim (int, tùy chọn, mặc định là 80) — Kích thước chiều của đầu chú ý. Nếu là None, giá trị mặc định sẽ là hidden_size // num_attention_heads
num_attention_heads (int, tùy chọn, mặc định là 16) — Số lượng đầu attention cho mỗi lớp attention trong bộ giải mã Transformer.
rms_norm_eps (float, tùy chọn, mặc định là 1e-06) — Giá trị epsilon được sử dụng bởi các lớp chuẩn hóa rms.
quantiles (list[float], tùy chọn, mặc định là [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) — Các quantile cần dự đoán.
attention_dropout (Union[float, int], tùy chọn, mặc định là 0.0) — Tỷ lệ dropout cho các xác suất chú ý.
initializer_range (float, tùy chọn, mặc định là 0.02) — Độ lệch chuẩn của truncated_normal_initializer để khởi tạo tất cả các ma trận trọng số.
num_key_value_heads (int, tùy chọn, mặc định là 16) — Đây là số lượng key_value heads cần được sử dụng để triển khai Grouped Query Attention. Nếu num_key_value_heads=num_attention_heads, mô hình sẽ sử dụng Multi Head Attention (MHA), nếu num_key_value_heads=1 mô hình sẽ sử dụng Multi Query Attention (MQA), ngược lại sẽ sử dụng GQA. Khi chuyển đổi checkpoint multi-head sang checkpoint GQA, mỗi nhóm key và value head nên được xây dựng bằng cách meanpooling tất cả các head gốc trong nhóm đó. Để biết thêm chi tiết, hãy xem bài báo này. Nếu không được chỉ định, giá trị mặc định sẽ là num_attention_heads.
attention_bias (bool, tùy chọn, mặc định là False) — Có sử dụng bias trong các lớp chiếu query, key, value và output trong quá trình tự chú ý hay không.
output_quantile_len (int, tuỳ chọn, mặc định là 1024) — Chiều dài của chiều dự đoán đầu ra quantile.
decode_index (int, tuỳ chọn, mặc định là 5) — Chỉ số vào chiều quantile được dùng để trích xuất dự báo điểm (trung vị).
use_bias (bool, tùy chọn, mặc định là False) — Có sử dụng bias trong các lớp tuyến tính của MLP và transformer hay không.
activation (str, tùy chọn, mặc định là swish) — Hàm kích hoạt phi tuyến (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ, "gelu", "relu", "silu", v.v.
use_continuous_quantile_head (bool, tùy chọn, mặc định là True) — Có sử dụng đầu quantile liên tục cho các dự đoán quantile không phải trung vị hay không.
force_flip_invariance (bool, tùy chọn, mặc định là True) — Có áp dụng trung bình hóa bất biến lật trong quá trình dự báo hay không.
infer_is_positive (bool, tùy chọn, mặc định là True) — Có kẹp các dự báo về các giá trị không âm khi giá trị nhỏ nhất của đầu vào là không âm hay không.
max_position_embeddings (int, tùy chọn, mặc định là 16384) — Chiều dài chuỗi tối đa mà mô hình này có thể được sử dụng.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], tùy chọn) — Từ điển chứa các tham số cấu hình cho các embedding RoPE. Từ điển phải chứa một giá trị cho rope_theta và tùy chọn các tham số được sử dụng để mở rộng trong trường hợp bạn muốn sử dụng RoPE với max_position_embeddings dài hơn.

Đây là lớp cấu hình để lưu trữ cấu hình của một TimesFm2_5Model. Nó được sử dụng để khởi tạo một mô hình Timesfm2 5 theo các đối số được chỉ định, xác định kiến trúc của mô hình. Việc khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của google/timesfm-2.5-200m-transformers

Các đối tượng cấu hình kế thừa từ PreTrainedConfig và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ PreTrainedConfig để biết thêm thông tin.

Ví dụ:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

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

TimesFm2_5Model

lớp 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)

Tham số

past_values (torch.Tensor có hình dạng (batch_size, sequence_length)) — Các giá trị quá khứ của chuỗi thời gian được sử dụng làm đầu vào cho mô hình.
past_values_padding (torch.LongTensor có hình dạng (batch_size, sequence_length), tùy chọn) — Mặt nạ đệm cho đầu vào. 1 chỉ các bước thời gian đã được đệm (bị che), 0 chỉ các giá trị hợp lệ.

Trả về

TimesFm2_5Output hoặc tuple(torch.Tensor)

Một TimesFm2_5Output hoặc một tuple của torch.Tensor (nếu return_dict=False được truyền hoặc khi config.return_dict=False) bao gồm các thành phần khác nhau tùy thuộc vào cấu hình (TimesFm2_5Config) và đầu vào.

Phương thức forward của TimesFm2_5Model ghi đè lên phương thức đặc biệt __call__.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, người dùng nên gọi instance của Module sau đó thay vì gọi hàm này, vì instance Module sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ lặng lẽ bỏ qua chúng.

last_hidden_state (torch.Tensor có hình dạng (batch_size, sequence_length, hidden_size)) — Chuỗi các hidden-state tại đầu ra của lớp cuối cùng của mô hình.
hidden_states (tuple(torch.Tensor), tuỳ chọn, được trả về khi output_hidden_states=True được truyền vào hoặc khi config.output_hidden_states=True) — Bộ tuple của torch.Tensor (một cho đầu ra của embeddings, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng (batch_size, sequence_length, hidden_size).

Trạng thái ẩn của mô hình tại đầu ra của mỗi lớp cùng với các đầu ra embedding ban đầu tùy chọn.
attentions (tuple(torch.Tensor), tuỳ chọn, được trả về khi output_attentions=True được truyền vào hoặc khi config.output_attentions=True) — Tuple của torch.Tensor (một cho mỗi lớp) có hình dạng (batch_size, num_heads, sequence_length, sequence_length).

Trọng số chú ý sau softmax của attention, được sử dụng để tính trung bình có trọng số trong các đầu self-attention.
loc (torch.Tensor có shape (batch_size,) hoặc (batch_size, input_size), optional) — Các giá trị dịch chuyển của context window cho mỗi chuỗi thời gian, được dùng để cung cấp cho mô hình các đầu vào có cùng độ lớn, sau đó dùng để dịch chuyển ngược lại về độ lớn ban đầu.
scale (torch.Tensor có shape (batch_size,) hoặc (batch_size, input_size), optional) — Các giá trị scale của context window cho từng chuỗi thời gian, được dùng để đưa đầu vào của mô hình về cùng một bậc độ lớn, sau đó dùng để rescale ngược lại về độ lớn gốc.
context_mu (torch.Tensor có hình dạng (batch_size, num_patches)) — Các giá trị trung bình chạy được tính cho từng patch đầu vào trong quá trình chuẩn hóa.
context_sigma (torch.Tensor có hình dạng (batch_size, num_patches)) — Độ lệch chuẩn chạy được tính cho từng patch đầu vào trong quá trình chuẩn hóa.

TimesFm2_5ModelForPrediction

lớp transformers.TimesFm2_5ModelForPrediction

< source >

( config: TimesFm2_5Config )

Mô hình TimesFm2_5 cho dự báo phân vị và trung bình.

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)

Tham số

past_values (collections.abc.Sequence[torch.Tensor]) — Các giá trị quá khứ của chuỗi thời gian đóng vai trò là đầu vào cho mô hình. Mỗi tensor là một chuỗi thời gian 1 chiều.
window_size (int, tùy chọn) — Kích thước cửa sổ của phân rã xu hướng + phần dư. Nếu None, không áp dụng phân rã.
future_values (torch.Tensor, tùy chọn) — Các giá trị tương lai tùy chọn được sử dụng để tính toán loss.
forecast_context_len (int, tùy chọn) — Độ dài ngữ cảnh tùy chọn được sử dụng trong quá trình dự báo.
truncate_negative (bool, tùy chọn) — Có nên kẹp các giá trị đầu ra về các giá trị không âm hay không. Nếu là None, mặc định là config.infer_is_positive.
force_flip_invariance (bool, tùy chọn) — Có áp dụng tổ hợp bất biến lật hay không. Nếu là None, mặc định là config.force_flip_invariance.

Trả về

TimesFm2_5OutputForPrediction hoặc tuple(torch.Tensor)

Một TimesFm2_5OutputForPrediction hoặc một tuple của torch.Tensor (nếu return_dict=False được truyền hoặc khi config.return_dict=False) bao gồm các thành phần khác nhau tùy thuộc vào cấu hình (TimesFm2_5Config) và đầu vào.

Phương thức forward của TimesFm2_5ModelForPrediction ghi đè lên phương thức đặc biệt __call__.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, người dùng nên gọi instance của Module sau đó thay vì gọi hàm này, vì instance Module sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ lặng lẽ bỏ qua chúng.

last_hidden_state (torch.Tensor có hình dạng (batch_size, sequence_length, hidden_size)) — Chuỗi các hidden-state tại đầu ra của lớp cuối cùng của mô hình.
hidden_states (tuple(torch.Tensor), tuỳ chọn, được trả về khi output_hidden_states=True được truyền vào hoặc khi config.output_hidden_states=True) — Bộ tuple của torch.Tensor (một cho đầu ra của embeddings, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng (batch_size, sequence_length, hidden_size).

Trạng thái ẩn của mô hình tại đầu ra của mỗi lớp cùng với các đầu ra embedding ban đầu tùy chọn.
attentions (tuple(torch.Tensor), tuỳ chọn, được trả về khi output_attentions=True được truyền vào hoặc khi config.output_attentions=True) — Tuple của torch.Tensor (một cho mỗi lớp) có hình dạng (batch_size, num_heads, sequence_length, sequence_length).

Trọng số chú ý sau softmax của attention, được sử dụng để tính trung bình có trọng số trong các đầu self-attention.
mean_predictions (torch.Tensor có hình dạng (batch_size, horizon_length)) — Dự báo xác định sau khi khử chuẩn hóa.
full_predictions (torch.Tensor có hình dạng (batch_size, horizon_length, quantiles)) — Dự báo phân vị bao gồm trung vị sau khi khử chuẩn hóa.
loss (torch.Tensor có shape (1,), optional, được trả về khi future_values được cung cấp) — Loss huấn luyện kết hợp MSE và quantile losses khi các target được cung cấp.

Update on GitHub