timestral README

项目的 README,来自 github.com/mistralai/timestral。合并为一个 markdown 文件:README.md。

Timestral

Timestral

Blog post · Hugging Face collection · License

Timestral is a family of time series foundation models for multivariate probabilistic forecasting, with support for past-only and known-future covariates. This repository provides standalone inference for Timestral models. It needs only PyTorch, NumPy, safetensors and huggingface_hub, and runs on CPU or GPU.

License: the code in this repository is licensed under Apache 2.0. The Timestral model weights are released separately on the Hugging Face Hub under a Modified MIT license. See License.

Highlights

At launch, Timestral-209M ranked first among pretrained and zero-shot models on the three main public forecasting benchmarks:

All four sizes (5M, 28M, 123M, 209M) sit on the Pareto front of accuracy versus model size. Full results are in the blog post and the model cards on Hugging Face.

Install

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

Or from a clone with uv, using the versions pinned in uv.lock:

git clone https://github.com/mistralai/timestral.git && cd timestral
uv sync --frozen
source .venv/bin/activate

Models

The weights are on the Hugging Face Hub, in the Mistral AI organization:

model Hub repo weights (fp32)
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

from_pretrained downloads config.json and model.safetensors once to the Hub cache.

Forecast

import numpy as np
from timestral import TimestralForecaster

forecaster = TimestralForecaster.from_pretrained("mistralai/Timestral-209M")  # device="cuda" for a GPU

context = np.random.randn(2, 1, 2000).cumsum(-1)        # (series, variates, time); NaN = missing
forecast = forecaster.forecast(context, prediction_length=96)

forecast.quantiles.shape   # (2, 1, 96, 21): series, variates, horizon, quantile levels
forecast.quantile_levels   # (0.01, 0.05, 0.1, ..., 0.9, 0.95, 0.99)
forecast.median            # (2, 1, 96)
forecast.quantile(0.9)     # (2, 1, 96)

Loading options

from_pretrained takes a Hub repo id or a local directory with config.json and model.safetensors.

Covariates

forecast = forecaster.forecast(
    context,                          # (B, V, T)
    prediction_length=96,
    past_covariates=past,             # (B, C_past, T): known over the context only
    known_covariates=known,           # (B, C_known, T + 96): known over context and horizon
)

Covariates are conditioning rows: they are not forecast, and covariate rows never read the targets. Known-future covariate rows whose values are all 0 or 1 are treated as indicators. NaN marks a missing covariate value.

Categorical covariates

forecast = forecaster.forecast(
    context,
    prediction_length=96,
    categorical_past_covariates=codes_past,     # (B, C, T) numeric category codes, NaN = missing
    categorical_known_covariates=codes_known,   # (B, C, T + 96)
)

Pass categories as numeric codes (for example pandas.factorize), with NaN for missing values and for any padding. For a univariate target each categorical row is target-encoded per series: category c becomes (mean + sum_c) / (1 + count_c) over the forward-filled context, missing values form their own category, and a category absent from the context maps to the series mean. Multivariate targets receive the raw codes. Encoded rows are appended after the numeric covariates. timestral.covariate_encoding.target_encode exposes the encoding.

Architecture

Timestral is a causal patch-based transformer trained with Decoupled Horizon Forecasting (DHF), where forecasts are generated from separate prediction tokens that read the causally encoded context. Each variate is a target, a past-only covariate or a known-future covariate: covariates pass information to targets but never read them, and only known-future covariates see the forecast horizon. A quantile head outputs 21 non-crossing quantiles per time step, and each forecast patch is denormalized with the statistics of the context and the block's earlier predicted medians.

Benchmarks

Timestral is evaluated zero-shot on three benchmarks, with the forecaster defaults and the full history up to 32768 steps as context:

benchmark inputs beyond the target
GIFT-Eval (97 configs) past_feat_dynamic_real as past covariates
fev-bench (100 tasks) past and known covariates; categorical columns target-encoded
TIME (98 tasks) none (TIME has no covariates)

Contributing

We do not accept pull requests. Bug reports and questions are welcome as GitHub issues.

timestral is maintained by the team at Mistral AI. We answer issues on a best-effort basis and fix security vulnerabilities and major bugs. See CONTRIBUTING.md for how to report an issue.

License

The code in this repository (the timestral package and tests) is licensed under the Apache License 2.0. See the LICENSE file.

The Timestral model weights are not covered by the Apache License 2.0. They are distributed separately on the Hugging Face Hub under a Modified MIT license, available in each model repository (Timestral-5M, Timestral-28M, Timestral-123M, Timestral-209M). When using the model weights, you must not use them in a manner that infringes, misappropriates, or otherwise violates any third party's rights, including intellectual property rights.

timestral (mistralai/timestral)

正在搜索数据库…

这是什么?Timestral 是 Mistral AI 推出的一系列时间序列基础模型,用于多变量概率预测,支持仅使用过去的协变量和已知未来的协变量。本仓库提供用于运行这些模型的独立推理代码。
这是完整的训练框架,还是只是一个推理库?它是一个独立的推理库:你从 Hugging Face Hub 加载预训练权重,然后对你的数据调用 forecast(),而不是自己训练模型。
我该如何用 Timestral 做预测?安装该包(例如在使用 uv 克隆仓库后,按固定的 uv.lock 安装),然后使用 Hub 仓库 ID(如 mistralai/Timestral-209M)通过 Timestral.from_pretrained() 加载模型,并将你的时间序列数组传入 forecast()。
使用它需要安装哪些依赖?只需 PyTorch、NumPy、safetensors 和 huggingface_hub;首次加载时,模型权重会自动从 Hugging Face Hub 下载。
这个工具面向哪些人?适合搭建预测流程、需要预训练的零样本时间序列模型而非从零训练的人,例如数据科学家和机器学习工程师。
代码和模型权重是否使用同一许可证?不是。本仓库中的推理代码采用 Apache 2.0 许可证,而模型权重在 Hugging Face 上单独发布,采用 Modified MIT 许可证,并附加了禁止侵犯第三方权利的额外限制。
Timestral 的预测效果与其他模型相比如何?发布时,Timestral-209M 在 GIFT-Eval、TIME 和 fev-bench 基准测试中,在预训练及零样本模型里排名第一;四种规格都位于精度与模型大小的帕累托前沿上。
有哪些可用的模型规格?Hugging Face 上发布了四种规格:Timestral-5M、28M、123M 和 209M,fp32 权重大小从 21 MB 到 837 MB 不等。
什么是解耦时域预测?这是 Timestral 背后的训练方法:一个因果的、基于分块(patch)的 Transformer,通过独立的预测令牌生成预测,这些令牌读取经过因果编码的上下文,而不是逐步自回归解码。
除了目标序列,我还能使用其他协变量吗?可以,你可以传入仅使用过去的协变量、已知未来的协变量以及分类协变量;协变量会影响预测结果,但自身从不被预测,分类协变量会按序列进行目标编码。
作者
mistralai
大小
0.3 MB
星标
1.2K
更新
提交Oct 15
时长
1个月
提交 · 90 天