google-research/timesfm

TimesFM

TimesFM(Time Series Foundation Model)은 Google Research에서 시계열 예측을 위해 개발한 사전 학습된 시계열 기반 모델입니다.

• 논문: A decoder-only foundation model for time-series forecasting, ICML 2024.
• 모든 체크포인트: TimesFM Hugging Face Collection.
• Google Research 블로그.
• Google 1P 제품에서의 TimesFM:
• BigQuery ML: 확장성과 안정성을 위한 엔터프라이즈 수준 SQL 쿼리.
• Google Sheets: 일상적인 스프레드시트용.
• Vertex Model Garden: 에이전트 호출을 위한 도커화된 엔드포인트.

이 오픈 버전은 공식적으로 지원되는 Google 제품이 아닙니다.

최신 모델 버전: TimesFM 2.5

보관된 모델 버전:

• 1.0 및 2.0: 관련 코드는 하위 디렉토리 v1에 보관되어 있습니다. pip install timesfm==1.3.0을 실행하여 이전 버전의 패키지를 설치하면 해당 모델을 로드할 수 있습니다.

업데이트 - 2026년 6월 5일

PyPI를 timesfm=2.0.0으로 업데이트했습니다. 설치를 참조하세요.

업데이트 - 2026년 4월 9일

HuggingFace Transformers + PEFT(LoRA)를 사용한 파인튜닝 예제가 추가되었습니다. timesfm-forecasting/examples/finetuning/을 참조하세요. 또한 단위 테스트(tests/)가 추가되었고 여러 커뮤니티 수정 사항이 통합되었습니다.

@kashif와 @darkpowerxo에게 감사드립니다.

업데이트 - 2026년 3월 19일

@borealBytes가 AGENTS 지원을 추가해 주셨습니다! TimesFM SKILL.md가 공개되었습니다.

업데이트 - 2025년 10월 29일

TimesFM 2.5에 XReg를 통한 공변량 지원이 다시 추가되었습니다.

업데이트 - 2025년 9월 15일

TimesFM 2.5가 출시되었습니다!

TimesFM 2.0과 비교하여 새로운 2.5 모델은:

• 500M에서 200M 파라미터로 감소했습니다.
• 2048에서 최대 16k 컨텍스트 길이를 지원합니다.
• 선택적 30M 분위수 헤드를 통해 최대 1k 예측 지평까지 연속 분위수 예측을 지원합니다.
• frequency 표시자를 제거했습니다.
• 몇 가지 새로운 예측 플래그가 있습니다.

2025년 9월 출시 이후 다음과 같은 개선이 완료되었습니다:

1. ✅ 더 빠른 추론을 위한 Flax 버전의 모델.
2. ✅ XReg를 통한 공변량 지원 (2025년 10월 업데이트 참조).
3. ✅ 문서, 예제 및 에이전트 스킬 (timesfm-forecasting/ 참조).
4. ✅ HuggingFace Transformers + PEFT를 통한 LoRA 파인튜닝 예제 (timesfm-forecasting/examples/finetuning/ 참조).
5. ✅ 핵심 레이어, 설정 및 유틸리티에 대한 단위 테스트 (tests/ 참조).

설치

PyPI에서

# torch로 패키지 설치
pip install timesfm[torch]
# 또는 Flax로 설치
pip install timesfm[flax]
# XReg가 필요한 경우
pip install timesfm[xreg]

로컬 설치

1. 저장소를 클론합니다:

    git clone https://github.com/google-research/timesfm.git
    cd timesfm

1. 가상 환경을 만들고 uv를 사용하여 의존성을 설치합니다:

    # 가상 환경 생성
    uv venv

    # 환경 활성화
    source.venv/bin/activate

    # torch로 패키지를 편집 가능 모드로 설치
    uv pip install -e.[torch]
    # 또는 flax로 설치
    uv pip install -e.[flax]
    # XReg가 필요한 경우
    uv pip install -e.[xreg]

1. [선택 사항] OS와 가속기(CPU, GPU, TPU 또는 Apple Silicon)에 따라 선호하는 torch / jax 백엔드를 설치합니다:

• PyTorch 설치.
• Jax 설치 (Flax용).

코드 예제

import torch
import numpy as np
import timesfm

torch.set_float32_matmul_precision("high")

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")

model.compile(
    timesfm.ForecastConfig(
        max_context=1024,
        max_horizon=256,
        normalize_inputs=True,
        use_continuous_quantile_head=True,
        force_flip_invariance=True,
        infer_is_positive=True,
        fix_quantile_crossing=True,
    )
)
point_forecast, quantile_forecast = model.forecast(
    horizon=12,
    inputs=[
        np.linspace(0, 1, 100),
        np.sin(np.linspace(0, 20, 67)),
    ],  # 두 개의 더미 입력
)
point_forecast.shape  # (2, 12)
quantile_forecast.shape  # (2, 12, 10): 평균, 10번째부터 90번째 분위수까지.