PriorLabs/tabpfn-time-series

📦 TabPFN-TS란 무엇인가요?

TabPFN-TS는 합성 테이블 데이터로 학습된 대규모 신경망인 TabPFN 기초 모델을 재사용하여 제로샷 시계열 예측을 수행할 수 있게 해주는 Python 라이브러리입니다. 이 라이브러리는 단변량 계열을 테이블로 변환하고, 엔지니어링된 달력 스타일의 특성들을 추가한 뒤 TabPFN을 회귀 모델로 실행합니다. 모델이 이미 사전 학습되어 있으므로 별도의 학습 없이 점 예측과 확률 예측을 얻을 수 있습니다.

---

🛠️ 핵심 구성 요소

구성 요소	역할
TabPFNTSPipeline	데이터 변환, 특성 생성, TabPFN 호출(로컬 또는 클라우드 클라이언트 경유), 예측 결과 반환 등 전체 워크플로우를 처리하는 고수준 클래스.
특성 엔지니어링	달력, 사인/코사인 및 기타 시간적 특성을 자동으로 생성하는 기본 세트 (TABPFN_TS_DEFAULT_FEATURES).
TabPFN 모델	기반이 되는 테이블 기초 모델. 기본적으로 패키지는 Hugging Face에서 TabPFN-3.5(또는 미세 조정된 TabPFN-TS-3 체크포인트)를 가져옵니다.
tabpfn-client	선택적 클라우드 추론 백엔드; GPU 없이 예측을 실행할 수 있게 합니다.

---

🚀 사용 방법 (빠른 예제)

from tabpfn_time_series import TabPFNTSPipeline

# `context_df`에는 과거 타겟 열(및 알려진 미래 공변량)이 포함됩니다
pipeline = TabPFNTSPipeline()          # 기본값은 클라우드 클라이언트, GPU 불필요
forecast = pipeline.predict_df(context_df, prediction_length=24)

• predict_df는 시간 인덱스와 타겟 열이 있는 pandas DataFrame을 기대합니다. 알려진 미래 공변량(예: 휴일)이 있는 경우 future_df 인수에 전달하십시오.
• 반환된 객체에는 점 예측이 포함되며, 요청 시 확률 분위수도 포함됩니다.

단계별 가이드는 README에 링크된 노트북을 참조하십시오:

• quickstart.ipynb – 샘플 데이터셋에서 예측 얻기.
• how-it-works.ipynb – 테이블 변환 및 특성 파이프라인에 대한 심층 분석.

---

🎯 강점은 무엇인가요?

강점	중요성
제로샷 – 학습 데이터나 미세 조정 불필요	빠른 프로토타이핑이나 짧은 이력 데이터만 있을 때 이상적입니다.
빠른 추론 – 로컬 (CPU) 또는 클라우드 클라이언트	일반 하드웨어에서도 작동하며, 클라우드 클라이언트를 통해 GPU가 필요 없습니다.
확률적 출력	위험을 고려한 의사결정에 유용한 예측 구간을 제공합니다.
알려진 미래 공변량	달력 효과, 휴일 플래그 또는 예측 시점에 사용 가능한 외부 예측을 입력할 수 있습니다.

---

⚠️ 제한 사항

제한 사항	세부 정보
단변량 중심	다변량 타겟은 독립적인 예측으로 분할되며, 계열 간 상호작용은 무시됩니다.
과거 동적 공변량 없음	과거 관측치가 필요한 특성(예: 과거 날씨)은 제외됩니다.
정적 공변량 무시	store_id와 같은 항목 수준 속성은 사용되지 않습니다.
TabPFN 체크포인트 의존	예측 품질은 테이블 모델이 변환된 계열에 대해 얼마나 잘 일반화되는지에 따라 달라집니다.

과거의 동적 또는 정적 정보에 크게 의존하는 문제라면 전용 다변량 시계열 모델이 더 나은 성능을 보일 수 있습니다.

---

📦 설치 및 요구 사항

pip install tabpfn-time-series

• 기본 클라우드 모드에는 tabpfn>=9.0.0 및 tabpfn-client>=0.5.3이 필요합니다.
• 로컬 모드에서는 첫 실행 시 ux.priorlabs.ai에서 라이선스에 동의한 후 TabPFN-3.5 체크포인트를 다운로드합니다.

---

📚 추가 읽기 및 인용

• 논문 – Zero-Shot Time Series Forecasting with TabPFN (arXiv:2501.02945).
• TabPFN-3 보고서 – GIFT-EVAL 벤치마크에서 SOTA 결과를 달성한 미세 조정 체크포인트에 대한 세부 정보.
• 학술 작업에서 이 라이브러리를 사용할 때는 두 가지 모두를 인용하십시오.

---

🔍 원격 측정 및 개인정보 보호

이 라이브러리는 익명화된 사용 통계(패키지 버전, Python 버전, 호출 횟수, 입력 차원)만 전송합니다. 데이터, 코드 또는 모델 출력은 전송되지 않습니다. TABPFN_DISABLE_TELEMETRY=1을 설정하여 거부할 수 있습니다.

---

TL;DR – TabPFN-TS는 TabPFN 테이블 기초 모델을 빠른 점 예측 및 확률적 단변량 시계열 예측에 재사용하는 경량의 학습 불필요 라이브러리이며, GPU 없는 사용을 위한 클라우드 추론 옵션을 제공합니다.