google-research/timesfm

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

TimesFM – 시계열 예측을 위한 기초 모델

무엇인가요 – TimesFM(Time Series Foundation Model)은 막대하고 다양한 시계열 데이터로 훈련된 디코더 전용 신경망입니다. Google Research는 모델 가중치와 Python 라이브러리를 공개하여, 새로운 데이터에 대해 제로샷 예측(단변량 또는 다변량)을 수행하거나, 자체 데이터로 모델을 미세 조정할 수 있도록 합니다.

왜 중요한가요 – 텍스트용 대규모 언어 모델과 마찬가지로, TimesFM은 다양한 분야(금융, 에너지, 소매 등)에서 즉시 작동하는 일반 목적 예측 모델을 목표로 합니다. 수작업 특징 공학이 필요 없으며, 리포지토리는 버전 3.0까지의 사전 학습된 체크포인트와 추론, 평가, LoRA 스타일 미세 조정을 위한 코드를 제공합니다.

주요 특징 (README 기준)

버전 3.0 – 네이티브 다변량 예측, 과거 전용 및 과거-미래 동적 공변량 지원, 세 가지 주요 시계열 기초 모델 벤치마크(fev-bench, TIME, GIFT-Eval)에서 최고 성능 기록.
모델 크기 – 주 체크포인트는 3.3억 파라미터. 가벼운 2억 파라미터 버전(2.5)도 제공.
긴 컨텍스트 – 최대 16,000 토큰(2.5) 및 전체 모델에서 15,360 토큰까지 지원, 긴 이력 고려 가능.
분위수 예측 – 선택적 3,000만 헤드로 최대 1,000단계 분위수 예측(기본 9분위) 제공.
백엔드 – 표준 PyTorch와 Apple silicon 전용 MLX 지원, 수치적 일치 결과 제공.
통합 포인트 – Google Cloud 제품(BigQuery ML, Vertex Model Garden) 및 일반 사용자를 위한 Google Sheets에서도 사용 가능.
미세 조정 – HuggingFace Transformers + PEFT(LoRA)를 사용한 예제 스크립트로 특정 시계열에 모델 적응 가능.
에이전트 지원 – AGENTS.md 파일에 자율 에이전트에서 TimesFM을 호출하는 방법 설명.

일반적인 사용 사례

분야	TimesFM의 활용 방법
비즈니스 예측 (판매, 수요, 재고)	새로운 제품 라인에 대한 제로샷 예측; 과거 판매 데이터로 미세 조정하여 정확도 향상
에너지 및 공공사업	날씨 공변량을 포함한 다변량 부하 및 가격 시계열 동시 예측
금융	거시경제 공변량을 조건으로 복수 자산 가격 시계열 예측
IoT/센서 데이터	장기간 예측을 통한 장비 건강 모니터링
빠른 프로토타이핑	코드 작성 없이 BigQuery ML 또는 Sheets를 통해 즉시 활용 가능

시작하기 (Python)

# 라이브러리 설치 (백엔드 선택)
pip install "timesfm[torch]"      # PyTorch (CPU/GPU)
# 또는
pip install "timesfm[mlx]"        # Apple silicon, PyTorch 필요 없음

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

cfg = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda"               # 또는 "cpu" / "mlx"
)
forecaster = TimesFM3Evaluator(cfg)

# 단변량 예제
ts = np.sin(np.linspace(0, 2*np.pi, 100)).astype(np.float32)
out = forecaster.predict_batch([ts], horizon=12, return_quantiles=True)[0]
print(out.forecast.shape)   # (12,)
print(out.quantiles.shape)  # (12, 9)

다변량 시계열의 경우, (num_variates, context_len) 배열과 선택적 공변량 배열을 README에 따라 전달하세요.

미세 조정 (LoRA) – 간략한 개요

# 리포지토리 복제 및 편집 가능 설치
git clone https://github.com/google-research/timesfm.git
cd timesfm
uv venv && source .venv/bin/activate
uv pip install -e .[torch]

# timesfm-forecasting/examples/finetuning/ 에서 예제
from transformers import AutoModelForCausalLM, Trainer, TrainingArguments
from peft import LoraConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("google/timesfm-3.0-pytorch")
peft_cfg = LoraConfig(r=8, lora_alpha=32, target_modules=["c_attn"])
model = get_peft_model(model, peft_cfg)
# …(context, target) 쌍의 Dataset 준비 후 Trainer 실행…

리포지토리에는 실행 가능한 finetuning 스크립트와 단위 테스트가 포함되어 있습니다.

라이선스

소스 코드 – Apache-2.0 (자유롭게 사용, 수정, 재배포 가능).
사전 학습된 가중치 – 버전 ≤2.5는 Apache-2.0. 버전 3.0 가중치는 별도의 비영리 라이선스(timesfm-non-commercial-license-v1.0)로 배포되며, 별도 계약 없이 영업 또는 생산 환경에 배포할 수 없습니다.

제한 및 주의사항

영업 사용 제한 – 최신 체크포인트(3.0)는 Google의 라이선스 없이 수익 창출 제품에 사용 불가.
하드웨어 요구사항 – 전체 크기 3.3억 파라미터 모델은 GPU에서 최적 작동. MLX 백엔드는 Apple silicon에 한정.
제로샷 성능 – 벤치마크에서 최고 성능을 기록하지만, 분야 특화 데이터는 여전히 미세 조정이 유리할 수 있음.
컨텍스트 자르기 – 모델의 global_context(15,360 토큰)를 초과하는 컨텍스트는 자동으로 자르며, 매우 긴 이력이 손실될 수 있음.
공식 제품 지원 없음 – 리포지토리는 "공식적으로 지원되지 않는 Google 제품"이라고 명시되어 있어, 버그 수정 및 업데이트는 오픈소스 커뮤니티에 의존.

더 많은 정보 찾기

논문: A decoder-only foundation model for time-series forecasting (ICML 2024) – https://arxiv.org/abs/2310.10688
모델 허브: Hugging Face 컬렉션 – https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6
블로그: README 내 링크에서 Google Research 블로그 포스트(고수준 동기 설명)
문서 및 예제: timesfm-forecasting/ 디렉터리에 튜토리얼, 에이전트 기술 문서, 단위 테스트 포함.

결론 – TimesFM은 연구 수준의 본격적인 시계열 예측용 기초 모델로, PyTorch 또는 MLX를 통한 즉시 사용 가능한 추론과 자체 데이터에 맞춘 모델 적응 경로를 제공합니다. 잘 문서화되어 있으며 벤치마크 검증을 거쳤으며 Google Cloud 서비스와 통합되어 있어, 다양한 분야에서 고품질 예측이 필요한 사용자에게 안정적인 선택입니다.