Timestral – 时间序列基础模型

简介 – Timestral 是一族用于多变量概率时间序列预测的预训练 transformer 模型。仓库仅包含推理代码，模型权重托管在 Hugging Face 上。

主要功能

• 支持最多 32,000 步历史上下文的多变量联合预测。
• 处理仅过去、已知未来和类别型协变量（数值或类似 one-hot）。
• 每个预测步返回 21 个分位数（非交叉），提供完整的预测分布。
• 四种模型尺寸（5M、28M、123M、209M），在精度与资源占用之间权衡；209M 版本在零样本模式下在三个公开基准（GIFT-Eval、TIME、fev-bench）中名列前茅。
• 支持 CPU 推理，如有 GPU 也可使用。

安装

pip install git+https://github.com/mistralai/timestral.git   # Python ≥3.10, torch ≥2.4

或使用 uv 克隆并同步精确锁定的依赖项。

典型用法

import numpy as np
from timestral import TimestralForecaster

forecaster = TimestralForecaster.from_pretrained(
    "mistralai/Timestral-209M", device="cpu"
)

# context: (batch, variates, time) – NaN marks missing values
context = np.random.randn(2, 1, 2000).cumsum(-1)
forecast = forecaster.forecast(context, prediction_length=96)

print(forecast.quantiles.shape)   # (2, 1, 96, 21)
print(forecast.median.shape)      # (2, 1, 96)

可选参数允许您传递：

• past_covariates（仅在历史窗口已知）
• known_covariates（可扩展到预测区间）
• categorical_*_covariates（数值类别代码，内部进行目标编码）

模型动物园 – 权重由 Mistral AI 组织托管在 Hugging Face 上：

模型	仓库	大小
Timestral‑5M	mistralai/Timestral-5M	21 MB
Timestral‑28M	mistralai/Timestral-28M	111 MB
Timestral‑123M	mistralai/Timestral-123M	490 MB
Timestral‑209M	mistralai/Timestral-209M	837 MB

TimestralForecaster.from_pretrained 会自动下载 config.json 和 model.safetensors。

架构概览 – 基于因果 patch 的 transformer，使用解耦区间预测（Decoupled Horizon Forecasting）训练。独立的预测 token 读取编码后的上下文，分位数头输出每个步的 21 个非交叉分位数。协变量行只读；已知未来的协变量可以查看预测区间，但不会读取目标 token。

许可证 – 代码采用 Apache 2.0 许可。模型权重在修改版 MIT 许可（见各 Hugging Face 仓库）下发布。使用权重必须遵守该许可。

支持 – 不接受拉取请求；如有问题，请在 GitHub 上打开 issue。