TabPFN

基于 Transformer 的表格数据 foundation model，支持几行代码完成分类/回归任务。亮点是在 Nature 发表，仅用合成数据预训练，小样本场景下表现突出，并附带 SHAP 解释、异常检测等扩展工具。注意权重采用非商业许可，企业版需另行联系。

README

TabPFN

快速开始

交互式 Notebook 教程

[!TIP]

立即体验我们的交互式 Colab notebook！这是亲手感受 TabPFN 的最佳方式，它将引导您完成安装、分类和回归示例。

⚡ 推荐 GPU：为获得最佳性能，请使用 GPU（即使是较旧的 ~8GB VRAM 型号也能良好运行；某些大型数据集需要 16GB）。在 CPU 上，仅适用于小型数据集（≲1000 样本）。没有 GPU？可以通过 TabPFN Client 使用我们免费的托管推理服务。

安装

官方安装（pip）

pip install tabpfn

或者从源代码安装

pip install "tabpfn @ git+https://github.com/PriorLabs/TabPFN.git"

或者本地开发安装：首先安装 uv（建议 0.10.0 或更高版本），我们用它进行开发，然后运行

git clone https://github.com/PriorLabs/TabPFN.git --depth 1
cd TabPFN
uv sync

基本用法

使用我们的默认 TabPFN-2.6 模型，该模型完全在合成数据上训练：

from tabpfn import TabPFNClassifier, TabPFNRegressor

clf = TabPFNClassifier()
clf.fit(X_train, y_train)  # 首次使用时会下载 checkpoint
predictions = clf.predict(X_test)

reg = TabPFNRegressor()
reg.fit(X_train, y_train)  # 首次使用时会下载 checkpoint
predictions = reg.predict(X_test)

使用其他模型版本（例如 TabPFN-2.5）：

from tabpfn import TabPFNClassifier, TabPFNRegressor
from tabpfn.constants import ModelVersion

classifier = TabPFNClassifier.create_default_for_version(ModelVersion.V2_5)
regressor = TabPFNRegressor.create_default_for_version(ModelVersion.V2_5)

完整示例请参见 tabpfn_for_binary_classification.py、tabpfn_for_multiclass_classification.py 和 tabpfn_for_regression.py 文件。

使用技巧

使用批预测模式：每次 predict 调用都会重新计算训练集。如果分别对 100 个样本调用 predict，速度几乎比单次调用慢 100 倍且更昂贵。如果测试集非常大，可以将其分成每批 1000 个样本。
避免数据预处理：在向模型输入数据时，不要应用数据缩放或 one-hot 编码。
使用 GPU：TabPFN 在 CPU 上执行较慢。确保有可用的 GPU 以获得更好性能。
注意数据集大小：TabPFN 在样本数少于 100,000 且特征数少于 2000 的数据集上效果最佳。对于更大的数据集，建议参考大型数据集指南。

TabPFN 生态

根据您的需求选择合适的 TabPFN 实现：

TabPFN Client 通过云端推理使用 TabPFN 的简单 API 客户端。
TabPFN Extensions 一个强大的配套仓库，包含高级工具、集成和功能——非常适合贡献：
- interpretability：通过 SHAP 解释、特征重要性和选择工具获得见解。
- unsupervised：异常检测和合成表格数据生成的工具。
- embeddings：提取并使用 TabPFN 内部学习的嵌入以进行下游任务或分析。
- many_class：处理超过 TabPFN 内置类别限制的多类分类问题。
- rf_pfn：将 TabPFN 与传统模型（如随机森林）结合，实现混合方法。
- hpo：针对 TabPFN 量身定制的自动超参数优化。
- post_hoc_ensembles：通过集成多个训练后的 TabPFN 模型来提升性能。
安装：
```
git clone https://github.com/priorlabs/tabpfn-extensions.git
pip install -e tabpfn-extensions
```
TabPFN（本仓库） 支持 PyTorch 和 CUDA 的快速本地推理核心实现。
TabPFN UX 无需编码的图形界面，可用于探索 TabPFN 功能——非常适合业务用户和原型设计。

TabPFN 工作流程速览

按照以下决策树构建您的模型，并从我们的生态系统中选择合适的扩展。它引导您解决有关数据、硬件和性能需求的关键问题，为您的特定用例找到最佳解决方案。

---
config:
  theme: 'default'
  themeVariables:
    edgeLabelBackground: 'white'
---
graph LR
    %% 1. 定义颜色方案和样式
    classDef default fill:#fff,stroke:#333,stroke-width:2px,color:#333;
    classDef start_node fill:#e8f5e9,stroke:#43a047,stroke-width:2px,color:#333;
    classDef process_node fill:#e0f2f1,stroke:#00796b,stroke-width:2px,color:#333;
    classDef decision_node fill:#fff8e1,stroke:#ffa000,stroke-width:2px,color:#333;

    style Infrastructure fill:#fff,stroke:#ccc,stroke-width:5px;
    style Unsupervised fill:#fff,stroke:#ccc,stroke-width:5px;
    style Data fill:#fff,stroke:#ccc,stroke-width:5px;
    style Performance fill:#fff,stroke:#ccc,stroke-width:5px;
    style Interpretability fill:#fff,stroke:#ccc,stroke-width:5px;

    %% 2. 定义图结构
    subgraph Infrastructure
        start((开始)) --> gpu_check["有 GPU 可用？"];
        gpu_check -- 是 --> local_version["使用 TabPFN<br/>(本地 PyTorch)"];
        gpu_check -- 否 --> api_client["使用 TabPFN-Client<br/>(云端 API)"];
        task_type["您的任务类型？"]
    end

    local_version --> task_type
    api_client --> task_type

    end_node((工作流程<br/>完成));

    subgraph Unsupervised
        unsupervised_type["选择<br/>无监督任务"];
        unsupervised_type --> imputation["缺失值填充"]
        unsupervised_type --> data_gen["数据生成"];
        unsupervised_type --> tabebm["数据增强"];
        unsupervised_type --> density["异常检测"];
        unsupervised_type --> embedding["获取嵌入"];
    end


    subgraph Data
        data_check["数据检查"];
        model_choice["样本数 > 5万 或<br/>类别数 > 10？"];
        data_check -- "表格包含文本数据？" --> api_backend_note["注意：API 客户端<br/>原生支持文本"];
        api_backend_note --> model_choice;
        data_check -- "时间序列数据？" --> ts_features["使用时间序列<br/>特征"];
        ts_features --> model_choice;
        data_check -- "纯表格数据" --> model_choice;
        model_choice -- "否" --> finetune_check;
        model_choice -- "是，5万-10万样本" --> ignore_limits["设置<br/>ignore_pretraining_limits=True"];
        model_choice -- "是，>10万样本" --> subsample["大型数据集指南<br/>"];
        model_choice -- "是，>10个类别" --> many_class["多类别<br/>方法"];
    end

    subgraph Performance
        finetune_check["需要微调？"];
        performance_check["需要更好性能？"];
        speed_check["预测时需要更快推理？"];
        kv_cache["启用 KV 缓存<br/>(fit_mode='fit_with_cache')<br/><small>更快的预测；+内存 ~O(N×F)</small>"];
        tuning_complete["调优完成"];

        finetune_check -- 是 --> finetuning["微调"];
        finetune_check -- 否 --> performance_check;

        finetuning --> performance_check;

        performance_check -- 否 --> tuning_complete;
        performance_check -- 是 --> hpo["HPO"];
        performance_check -- 是 --> post_hoc["后验<br/>集成"];
        performance_check -- 是 --> more_estimators["更多<br/>估计器"];
        performance_check -- 是 --> speed_check;

        speed_check -- 是 --> kv_cache;
        speed_check -- 否 --> tuning_complete;

        hpo --> tuning_complete;
        post_hoc --> tuning_complete;
        more_estimators --> tuning_complete;
        kv_cache --> tuning_complete;
    end

    subgraph Interpretability

        tuning_complete --> interpretability_check;

        interpretability_check["需要可解释性？"];

        interpretability_check --> feature_selection["特征选择"];
        interpretability_check --> partial_dependence["部分依赖图"];
        interpretability_check --> shapley["用 SHAP 解释"];
        interpretability_check --> shap_iq["用 SHAP IQ 解释"];
        interpretability_check -- 否 --> end_node;

        feature_selection --> end_node;
        partial_dependence --> end_node;
        shapley --> end_node;
        shap_iq --> end_node;

    end

    %% 3. 连接子图和路径
    task_type -- "分类或回归" --> data_check;
    task_type -- "无监督" --> unsupervised_type;

    subsample --> finetune_check;
    ignore_limits --> finetune_check;
    many_class --> finetune_check;

    %% 4. 应用样式
    class start,end_node start_node;
    class local_version,api_client,imputation,data_gen,tabebm,density,embedding,api_backend_note,ts_features,subsample,ignore_limits,many_class,finetuning,feature_selection,partial_dependence,shapley,shap_iq,hpo,post_hoc,more_estimators,kv_cache process_node;
    class gpu_check,task_type,unsupervised_type,data_check,model_choice,finetune_check,interpretability_check,performance_check,speed_check decision_node;
    class tuning_complete process_node;

    %% 5. 添加可点击链接（包括 KV 缓存示例）
    click local_version "https://github.com/PriorLabs/TabPFN" "TabPFN 后端选项"
    click api_client "https://github.com/PriorLabs/tabpfn-client" "TabPFN API 客户端"
    click api_backend_note "https://github.com/PriorLabs/tabpfn-client" "TabPFN API 后端"
    click unsupervised_type "https://github.com/PriorLabs/tabpfn-extensions" "TabPFN 扩展"
    click imputation "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/imputation.py" "TabPFN 缺失值填充示例"
    click data_gen "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/generate_data.py" "TabPFN 数据生成示例"
    click tabebm "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/tabebm/tabebm_augment_real_world_data.ipynb" "TabEBM 数据增强示例"
    click density "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/density_estimation_outlier_detection.py" "TabPFN 密度估计/异常检测示例"
    click embedding "https://github.com/PriorLabs/tabpfn-extensions/tree/main/examples/embedding" "TabPFN 嵌入示例"
    click ts_features "https://github.com/PriorLabs/tabpfn-time-series" "TabPFN 时间序列示例"
    click many_class "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/many_class/many_class_classifier_example.py" "多类别示例"
    click finetuning "https://github.com/PriorLabs/TabPFN/blob/main/examples/finetune_classifier.py" "微调示例"
    click feature_selection "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/feature_selection.py" "特征选择示例"
    click partial_dependence "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/pdp_example.py" "部分依赖图示例"
    click shapley "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/shap_example.py" "SHAP 值示例"
    click shap_iq "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/shapiq_example.py" "SHAP IQ 示例"
    click post_hoc "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/phe/phe_example.py" "后验集成示例"
    click hpo "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/hpo/tuned_tabpfn.py" "HPO 示例"
    click subsample "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/large_datasets/large_datasets_example.py" "大型数据集示例"
    click kv_cache "https://github.com/PriorLabs/TabPFN/blob/main/examples/kv_cache_fast_prediction.py" "KV 缓存快速预测示例"

许可

TabPFN-2.5 和 TabPFN-2.6 模型权重根据非商业许可提供。这些是默认使用的。

代码和 TabPFN-2 模型权重根据 Prior Labs 许可（Apache 2.0，附加署名要求）提供：此处。要使用 v2 模型权重，请按如下方式实例化模型：

from tabpfn.constants import ModelVersion

tabpfn_v2 = TabPFNRegressor.create_default_for_version(ModelVersion.V2)

企业版与生产环境

对于高吞吐量或大规模生产环境，我们提供企业版，具备以下能力：

快速推理模式：一种专有蒸馏引擎，将 TabPFN-2.6 转换为紧凑的 MLP 或树集成，为实时应用提供数量级更低的延迟。
大数据模式（扩展模式）：一种高级操作模式，解除行限制，支持高达 1000 万行的数据集——比默认的 TabPFN-2.5 和 TabPFN-2.6 模型提升了 1000 倍。
商业支持：包括用于生产用例的商业企业许可、专门的集成支持以及私有高速推理引擎的访问权限。

如需了解更多信息或申请商业许可，请通过 sales@priorlabs.ai 联系我们。

加入我们的社区

我们正在构建表格机器学习的未来，期待您的参与：

联系与学习：
- 加入我们的 Discord 社区
- 阅读我们的文档
- 查看 GitHub Issues
贡献：
- 报告 bug 或请求功能
- 提交 pull request（请确保先打开一个 issue 讨论功能/bug，如果不存在的话）
- 分享您的研究和用例
保持更新：Star 本仓库并加入 Discord 以获取最新更新

引用

您可以在此处阅读解释 TabPFNv2 的论文，在此处阅读 TabPFN-2.5 的模型报告。

@misc{grinsztajn2025tabpfn,
  title={TabPFN-2.5: Advancing the State of the Art in Tabular Foundation Models},
  author={Léo Grinsztajn and Klemens Flöge and Oscar Key and Felix Birkel and Philipp Jund and Brendan Roof and
          Benjamin Jäger and Dominik Safaric and Simone Alessi and Adrian Hayler and Mihir Manium and Rosen Yu and
          Felix Jablonski and Shi Bin Hoo and Anurag Garg and Jake Robertson and Magnus Bühler and Vladyslav Moroshan and
          Lennart Purucker and Clara Cornu and Lilly Charlotte Wehrhahn and Alessandro Bonetto and
          Bernhard Schölkopf and Sauraj Gambhir and Noah Hollmann and Frank Hutter},
  year={2025},
  eprint={2511.08667},
  archivePrefix={arXiv},
  url={https://arxiv.org/abs/2511.08667},
}

@article{hollmann2025tabpfn,
 title={Accurate predictions on small data with a tabular foundation model},
 author={Hollmann, Noah and M{\"u}ller, Samuel and Purucker, Lennart and
         Krishnakumar, Arjun and K{\"o}rfer, Max and Hoo, Shi Bin and
         Schirrmeister, Robin Tibor and Hutter, Frank},
 journal={Nature},
 year={2025},
 month={01},
 day={09},
 doi={10.1038/s41586-024-08328-6},
 publisher={Springer Nature},
 url={https://www.nature.com/articles/s41586-024-08328-6},
}

@inproceedings{hollmann2023tabpfn,
  title={TabPFN: A transformer that solves small tabular classification problems in a second},
  author={Hollmann, Noah and M{\"u}ller, Samuel and Eggensperger, Katharina and Hutter, Frank},
  booktitle={International Conference on Learning Representations 2023},
  year={2023}
}

❓ 常见问题

使用与兼容性

问：TabPFN 最适合多大的数据集？ 答：TabPFN-2.5 针对最多 50,000 行的数据集进行了优化。对于更大的数据集，考虑使用随机森林预处理或其他扩展。请参阅我们的 Colab notebook 了解策略。

问：为什么我不能在 Python 3.8 上使用 TabPFN？ 答：TabPFN 需要 Python 3.9+，因为它使用了较新的语言特性。兼容版本：3.9, 3.10, 3.11, 3.12, 3.13。

安装与设置

问：如何获得 TabPFN-2.5 / TabPFN-2.6 的访问权限？

首次使用时，TabPFN 会自动打开一个浏览器窗口，您可以在其中通过 PriorLabs 登录并接受许可条款。您的认证令牌会缓存到本地，因此您只需执行此操作一次。

对于无浏览器 / CI 环境，请访问 https://ux.priorlabs.ai，进入 License 标签页接受许可，然后使用从账户获取的令牌设置 TABPFN_TOKEN 环境变量。

如果基于浏览器的流程不可用，请联系我们 sales@priorlabs.ai。

问：如何在没有网络连接的情况下使用 TabPFN？

TabPFN 会在首次使用时自动下载模型权重。对于离线使用：

使用提供的下载脚本

如果您有 TabPFN 仓库，可以使用包含的脚本下载所有模型（包括集成变体）：

# 安装 TabPFN 后
python scripts/download_all_models.py

该脚本会下载主分类器和回归器模型，以及所有集成变体模型到系统的默认缓存目录。

手动下载

从 HuggingFace 手动下载模型文件：
- 分类器：tabpfn-v2.5-classifier-v2.5_default.ckpt（注意：分类器默认使用在真实数据上微调的模型）。
- 回归器：tabpfn-v2.5-regressor-v2.5_default.ckpt
将文件放在以下位置之一：
- 直接指定：TabPFNClassifier(model_path="/path/to/model.ckpt")
- 设置环境变量：export TABPFN_MODEL_CACHE_DIR="/path/to/dir"（参见下面的环境变量 FAQ）
- 默认操作系统缓存目录：
  - Windows：%APPDATA%\tabpfn\
  - macOS：~/Library/Caches/tabpfn/
  - Linux：~/.cache/tabpfn/

问：加载模型时出现 pickle 错误，怎么办？ 答：请尝试以下操作：

下载最新版本的 tabpfn：pip install tabpfn --upgrade
确保模型文件正确下载（如果需要，重新下载）

问：哪些环境变量可以用来配置 TabPFN？ 答：TabPFN 使用 Pydantic 设置进行配置，支持环境变量和 .env 文件：

认证：

TABPFN_TOKEN：直接提供 PriorLabs 认证令牌（适用于无头/CI 环境）。从 https://ux.priorlabs.ai 获取。
TABPFN_NO_BROWSER：设置为禁用自动浏览器登录（例如在打开浏览器不受欢迎的环境中）。

模型配置：

TABPFN_MODEL_CACHE_DIR：缓存下载的 TabPFN 模型的自定义目录（默认：平台特定的用户缓存目录）
TABPFN_ALLOW_CPU_LARGE_DATASET：允许在 CPU 上运行大型数据集（>1000 样本）。设置为 true 以覆盖 CPU 限制。注意：这将非常慢！

PyTorch 设置：

PYTORCH_CUDA_ALLOC_CONF：PyTorch CUDA 内存分配配置，用于优化 GPU 内存使用（默认：max_split_size_mb:512）。更多信息请参见 PyTorch CUDA 文档。

示例：

export TABPFN_MODEL_CACHE_DIR="/path/to/models"
export TABPFN_ALLOW_CPU_LARGE_DATASET=true
export PYTORCH_CUDA_ALLOC_CONF="max_split_size_mb:512"

或者简单地在您的 .env 文件中设置。

问：如何保存和加载训练好的 TabPFN 模型？ 答：使用 :func:save_fitted_tabpfn_model 持久化已拟合的估计器，稍后使用 :func:load_fitted_tabpfn_model（或相应的 load_from_fit_state 类方法）重新加载。

from tabpfn import TabPFNRegressor
from tabpfn.model_loading import (
    load_fitted_tabpfn_model,
    save_fitted_tabpfn_model,
)

# 在 GPU 上训练回归器
reg = TabPFNRegressor(device="cuda")
reg.fit(X_train, y_train)
save_fitted_tabpfn_model(reg, "my_reg.tabpfn_fit")

# 稍后或在没有 GPU 的机器上
reg_cpu = load_fitted_tabpfn_model("my_reg.tabpfn_fit", device="cpu")

如果只想存储基础模型权重（不带拟合的估计器），请使用 save_tabpfn_model(reg.model_, "my_tabpfn.ckpt")。这仅保存预训练权重的 checkpoint，以便稍后创建和拟合新的估计器。使用 load_model_criterion_config 重新加载 checkpoint。

性能与限制

问：TabPFN 能处理缺失值吗？ 答：可以！

问：如何提高 TabPFN 的性能？ 答：最佳实践：

使用 TabPFN Extensions 中的 AutoTabPFNClassifier 进行后验集成
特征工程：添加领域特定特征以提升模型性能

无效的做法：

调整特征缩放
将分类特征转换为数值（例如 one-hot 编码）

问：HuggingFace 上不同的 checkpoint 有什么区别？ 答：除了默认 checkpoint 之外，其他可用的 checkpoint 是实验性的，平均表现较差，建议始终从默认版本开始。它们可用于集成或超参数优化系统（并在 AutoTabPFNClassifier 中自动使用），也可以手动尝试。它们的名称后缀指示了我们认为它们擅长的领域。

每个 TabPFN-2.5 checkpoint 的更多细节

我们对在真实数据集上微调的 checkpoint 添加 🌍 表情符号。有关 43 个数据集的列表，请参见 TabPFN-2.5 论文。

tabpfn-v2.5-classifier-v2.5_default.ckpt 🌍：默认分类 checkpoint，在真实数据上微调。
tabpfn-v2.5-classifier-v2.5_default-2.ckpt：最佳合成分类 checkpoint。使用此模型可以获得没有真实数据微调的默认 TabPFN-2.5 分类模型。
tabpfn-v2.5-classifier-v2.5_large-features-L.ckpt：专为较大特征数（最多 500 个）和小样本（< 5K）设计。
tabpfn-v2.5-classifier-v2.5_large-features-XL.ckpt：专为较大特征数（最多 1000 个）设计（可能支持 max_features_per_estimator=1000）。
tabpfn-v2.5-classifier-v2.5_large-samples.ckpt：专为较大样本数（大于 30K）设计。
tabpfn-v2.5-classifier-v2.5_real.ckpt 🌍：另一个在真实数据上微调的分类 checkpoint。整体表现不错，但在大特征数（>100-200）上表现不佳。
tabpfn-v2.5-classifier-v2.5_real-large-features.ckpt 🌍：另一个在真实数据上微调的分类 checkpoint，在大样本（> 10K）上表现较差。
tabpfn-v2.5-classifier-v2.5_real-large-samples-and-features.ckpt 🌍：与 tabpfn-v2.5-classifier-v2.5_default.ckpt 相同。
tabpfn-v2.5-classifier-v2.5_variant.ckpt：表现不错，但在大特征数（> 100-200）上表现不佳。
tabpfn-v2.5-regressor-v2.5_default.ckpt：默认回归 checkpoint，仅在合成数据上训练。
tabpfn-v2.5-regressor-v2.5_low-skew.ckpt：专为低目标偏斜数据设计的变体（但平均表现较差）。
tabpfn-v2.5-regressor-v2.5_quantiles.ckpt：可能对分位数/分布估计有用的变体，不过默认版本仍应优先考虑。
tabpfn-v2.5-regressor-v2.5_real.ckpt 🌍：在真实数据上微调。在真实数据微调的 checkpoint 中表现最佳。对于回归，我们建议默认使用仅合成数据的 checkpoint，但此 checkpoint 在某些数据集上要好得多。
tabpfn-v2.5-regressor-v2.5_real-variant.ckpt 🌍：另一个在真实数据上微调的回归变体。
tabpfn-v2.5-regressor-v2.5_small-samples.ckpt：在小样本（< 3K）上略优的变体。
tabpfn-v2.5-regressor-v2.5_variant.ckpt：另一个变体，没有明确的专长，但在少数数据集上可能表现更好。

开发

安装 uv
设置环境：

git clone https://github.com/PriorLabs/TabPFN.git
cd TabPFN
uv sync
source venv/bin/activate  # Windows: venv\Scripts\activate
pre-commit install

提交前：

pre-commit run --all-files

运行测试：

pytest tests/

匿名遥测

本项目会收集完全匿名的使用遥测数据，并可以选择退出所有遥测或选择加入扩展遥测。

这些数据仅用于帮助我们为相关产品和计算环境提供稳定性，并指导未来的改进。

不收集任何个人数据
绝不发送任何代码、模型输入或输出
数据严格匿名，无法关联到个人

有关遥测的详细信息，请参见我们的遥测参考和隐私政策。

要退出，请设置以下环境变量：

export TABPFN_DISABLE_TELEMETRY=1

开源项目PriorLabs2026-05-05原文

打开互动版

TabPFN

README

TabPFN

快速开始

交互式 Notebook 教程

安装

基本用法

使用技巧

TabPFN 生态

TabPFN 工作流程速览

许可

企业版与生产环境

加入我们的社区

引用

❓ 常见问题

使用与兼容性

安装与设置

性能与限制

开发

匿名遥测

相关内容

warp

sim

superpowers

skills

skills