Timestral – 시계열 파운데이션 모델

정의 – Timestral은 다변량 확률적 시계열 예측을 위한 사전 학습된 트랜스포머 모델 제품군입니다. 저장소에는 추론 코드만 포함되어 있으며, 모델 가중치는 Hugging Face에 있습니다.

주요 기능

• 최대 32,000 스텝의 과거 컨텍스트로 여러 변수를 동시에 예측합니다.
• 과거 전용, 알려진 미래, 범주형 공변량(숫자 또는 원-핫 유사)을 처리합니다.
• 수평선 스텝마다 21개의 분위수(비교차)를 반환하여 완전한 예측 분포를 제공합니다.
• 4가지 모델 크기(5M, 28M, 123M, 209M)로 정확도와 리소스 사용량 간의 균형을 맞춥니다. 209M 버전은 제로샷 모드에서 세 가지 공개 벤치마크(GIFT-Eval, TIME, fev-bench)에서 1위를 차지했습니다.
• 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 (숫자 범주 코드, 내부적으로 타겟 인코딩)

모델 zoo – 가중치는 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를 자동으로 다운로드합니다.

아키텍처 개요 – Decoupled Horizon Forecasting으로 훈련된 인과 패치 기반 트랜스포머. 별도의 예측 토큰이 인코딩된 컨텍스트를 읽고, 분위수 헤드가 스텝마다 21개의 비교차 분위수를 출력합니다. 공변량 행은 읽기 전용입니다. 알려진 미래 공변량은 수평선을 볼 수 있지만 타겟 토큰을 읽지는 않습니다.

라이선스 – 코드는 Apache 2.0입니다. 모델 가중치는 수정된 MIT 라이선스(각 Hugging Face 저장소 참조)로 제공됩니다. 가중치 사용은 해당 라이선스를 준수해야 합니다.

지원 – 풀 리퀘스트는 받지 않습니다. 버그나 질문은 GitHub에 이슈를 열어주세요.