PriorLabs/tabpfn-time-series

Zero-shot Time Series Forecasting with TabPFN (work accepted at NeurIPS 2024 TRL and TSALM workshops)

📦 什么是 TabPFN-TS？

TabPFN-TS 是一个 Python 库，让您能够通过重复使用 TabPFN 基础模型（一个在合成表格数据上训练的大型神经网络）来进行零样本时间序列预测。该库将单变量序列转换为表格，添加一些工程化的日历风格特征，然后将 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 使用。