PriorLabs/TabPFN
GitHub: PriorLabs/TabPFN
TabPFN 是一个基于 Transformer 的表格数据基础模型，通过预训练方式实现对小规模结构化数据的快速分类与回归，无需传统训练流程。
Stars: 6911 | Forks: 679
# TabPFN
[](https://badge.fury.io/py/tabpfn)
[](https://pepy.tech/project/tabpfn)
[](https://discord.gg/BHnX2Ptf4j)
[](https://priorlabs.ai/docs)
[](https://colab.research.google.com/github/PriorLabs/TabPFN/blob/main/examples/notebooks/TabPFN_Demo_Local.ipynb)
[](https://pypi.org/project/tabpfn/)
## 快速入门
### 交互式 Notebook 教程
### 安装
官方安装 (pip)
```
pip install tabpfn
```
或者从源码安装
```
pip install "tabpfn @ git+https://github.com/PriorLabs/TabPFN.git"
```
或者本地开发安装：首先[安装 uv](https://docs.astral.sh/uv/getting-started/installation)（建议使用 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) # downloads checkpoint on first use
predictions = clf.predict(X_test)
reg = TabPFNRegressor()
reg.fit(X_train, y_train) # downloads checkpoint on first use
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](https://github.com/PriorLabs/TabPFN/tree/main/examples/tabpfn_for_binary_classification.py)、[tabpfn_for_multiclass_classification.py](https://github.com/PriorLabs/TabPFN/tree/main/examples/tabpfn_for_multiclass_classification.py) 和 [tabpfn_for_regression.py](https://github.com/PriorLabs/TabPFN/tree/main/examples/tabpfn_for_regression.py) 文件。
### 使用技巧
- **使用批量预测模式**：每次 `predict` 调用都会重新计算训练集。单独对 100 个样本调用 `predict` 几乎比单次调用慢 100 倍，且成本更高。如果测试集非常大，请将其拆分为每个包含 1000 个样本的块。
- **避免数据预处理**：在将数据输入模型时，不要应用数据缩放或独热编码。
- **使用 GPU**：TabPFN 在 CPU 上执行速度较慢。请确保有可用的 GPU 以获得更好的性能。
- **注意数据集大小**：TabPFN 在样本数少于 100,000 且特征数少于 2000 的数据集上效果最佳。对于更大的数据集，我们建议查看[大型数据集指南](https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/large_datasets/large_datasets_example.py)。
## TabPFN 生态系统
根据您的需求选择合适的 TabPFN 实现：
- **[TabPFN Client](https://github.com/priorlabs/tabpfn-client)**
简单的 API 客户端，用于通过云端推理使用 TabPFN。
- **[TabPFN Extensions](https://github.com/priorlabs/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 (此仓库)](https://github.com/priorlabs/tabpfn)**
支持使用 PyTorch 和 CUDA 进行快速本地推理的核心实现。
- **[TabPFN UX](https://ux.priorlabs.ai)**
无代码图形界面，用于探索 TabPFN 功能——非常适合业务用户和原型设计。
## TabPFN 工作流一览
遵循此决策树来构建您的模型，并从我们的生态系统选择正确的扩展。它将引导您解答有关数据、硬件和性能需求的关键问题，指导您找到适合特定用例的最佳解决方案。
```
---
config:
theme: 'default'
themeVariables:
edgeLabelBackground: 'white'
---
graph LR
%% 1. DEFINE COLOR SCHEME & STYLES
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. DEFINE GRAPH STRUCTURE
subgraph Infrastructure
start((Start)) --> gpu_check["GPU available?"];
gpu_check -- Yes --> local_version["Use TabPFN
(local PyTorch)"]; gpu_check -- No --> api_client["Use TabPFN-Client
(cloud API)"]; task_type["What is
your task?"] end local_version --> task_type api_client --> task_type end_node((Workflow
Complete)); subgraph Unsupervised unsupervised_type["Select
Unsupervised Task"]; unsupervised_type --> imputation["Imputation"] unsupervised_type --> data_gen["Data
Generation"]; unsupervised_type --> tabebm["Data
Augmentation"]; unsupervised_type --> density["Outlier
Detection"]; unsupervised_type --> embedding["Get
Embeddings"]; end subgraph Data data_check["Data Checks"]; model_choice["Samples > 50k or
Classes > 10?"]; data_check -- "Table Contains Text Data?" --> api_backend_note["Note: API client has
native text support"]; api_backend_note --> model_choice; data_check -- "Time-Series Data?" --> ts_features["Use Time-Series
Features"]; ts_features --> model_choice; data_check -- "Purely Tabular" --> model_choice; model_choice -- "No" --> finetune_check; model_choice -- "Yes, 50k-100k samples" --> ignore_limits["Set
ignore_pretraining_limits=True"]; model_choice -- "Yes, >100k samples" --> subsample["Large Datasets Guide
"]; model_choice -- "Yes, >10 classes" --> many_class["Many-Class
Method"]; end subgraph Performance finetune_check["Need
Finetuning?"]; performance_check["Need Even Better Performance?"]; speed_check["Need faster inference
at prediction time?"]; kv_cache["Enable KV Cache
(fit_mode='fit_with_cache')
Faster predict; +Memory ~O(N×F)"]; tuning_complete["Tuning Complete"]; finetune_check -- Yes --> finetuning["Finetuning"]; finetune_check -- No --> performance_check; finetuning --> performance_check; performance_check -- No --> tuning_complete; performance_check -- Yes --> hpo["HPO"]; performance_check -- Yes --> post_hoc["Post-Hoc
Ensembling"]; performance_check -- Yes --> more_estimators["More
Estimators"]; performance_check -- Yes --> speed_check; speed_check -- Yes --> kv_cache; speed_check -- No --> 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["Need
Interpretability?"]; interpretability_check --> feature_selection["Feature Selection"]; interpretability_check --> partial_dependence["Partial Dependence Plots"]; interpretability_check --> shapley["Explain with
SHAP"]; interpretability_check --> shap_iq["Explain with
SHAP IQ"]; interpretability_check -- No --> end_node; feature_selection --> end_node; partial_dependence --> end_node; shapley --> end_node; shap_iq --> end_node; end %% 3. LINK SUBGRAPHS AND PATHS task_type -- "Classification or Regression" --> data_check; task_type -- "Unsupervised" --> unsupervised_type; subsample --> finetune_check; ignore_limits --> finetune_check; many_class --> finetune_check; %% 4. APPLY STYLES 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. ADD CLICKABLE LINKS (INCLUDING KV CACHE EXAMPLE) click local_version "https://github.com/PriorLabs/TabPFN" "TabPFN Backend Options" click api_client "https://github.com/PriorLabs/tabpfn-client" "TabPFN API Client" click api_backend_note "https://github.com/PriorLabs/tabpfn-client" "TabPFN API Backend" click unsupervised_type "https://github.com/PriorLabs/tabpfn-extensions" "TabPFN Extensions" click imputation "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/imputation.py" "TabPFN Imputation Example" click data_gen "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/generate_data.py" "TabPFN Data Generation Example" click tabebm "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/tabebm/tabebm_augment_real_world_data.ipynb" "TabEBM Data Augmentation Example" click density "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/density_estimation_outlier_detection.py" "TabPFN Density Estimation/Outlier Detection Example" click embedding "https://github.com/PriorLabs/tabpfn-extensions/tree/main/examples/embedding" "TabPFN Embedding Example" click ts_features "https://github.com/PriorLabs/tabpfn-time-series" "TabPFN Time-Series Example" click many_class "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/many_class/many_class_classifier_example.py" "Many Class Example" click finetuning "https://github.com/PriorLabs/TabPFN/blob/main/examples/finetune_classifier.py" "Finetuning Example" click feature_selection "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/feature_selection.py" "Feature Selection Example" click partial_dependence "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/pdp_example.py" "Partial Dependence Plots Example" click shapley "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/shap_example.py" "Shapley Values Example" click shap_iq "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/shapiq_example.py" "SHAP IQ Example" click post_hoc "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/phe/phe_example.py" "Post-Hoc Ensemble Example" click hpo "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/hpo/tuned_tabpfn.py" "HPO Example" click subsample "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/large_datasets/large_datasets_example.py" "Large Datasets Example" click kv_cache "https://github.com/PriorLabs/TabPFN/blob/main/examples/kv_cache_fast_prediction.py" "KV Cache Fast Prediction Example" ``` ## 许可证 TabPFN-2.5 和 TabPFN-2.6 模型权重根据[非商业许可证](https://huggingface.co/Prior-Labs/tabpfn_2_6/blob/main/LICENSE)授权。这些是默认使用的。 代码和 TabPFN-2 模型权重根据 Prior Labs 许可证（Apache 2.0 及额外的署名要求）授权：[此处](LICENSE)。要使用 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](mailto:sales@priorlabs.ai) 联系我们。** ## 引用 您可以阅读[此处](https://doi.org/10.1038/s41586-024-08328-6)的论文了解 TabPFNv2，并在[此处](https://arxiv.org/abs/2511.08667)阅读 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](https://colab.research.google.com/drive/154SoIzNW1LHBWyrxNwmBqtFAr1uZRZ6a#scrollTo=OwaXfEIWlhC8) 了解相关策略。 **问：为什么我不能在 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](https://ux.priorlabs.ai) 登录并接受许可条款。您的身份验证令牌会在本地缓存，因此您只需执行一次此操作。 **对于没有浏览器的无头 / CI 环境**，请访问 [https://ux.priorlabs.ai](https://ux.priorlabs.ai)，转到 **License（许可证）**选项卡接受许可，然后使用从您的帐户获取的令牌设置 `TABPFN_TOKEN` 环境变量。 如果您无法使用基于浏览器的方式，请通过 [`sales@priorlabs.ai`](mailto:sales@priorlabs.ai) 联系我们。 **问：如何在没有互联网连接的情况下使用 TabPFN？** TabPFN 会在首次使用时自动下载模型权重。对于离线使用： **使用提供的下载脚本** 如果您拥有 TabPFN 代码库，则可以使用包含的脚本下载所有模型（包括集成变体）： ``` # 在安装 TabPFN 之后 python scripts/download_all_models.py ``` 此脚本会将主分类器和回归器模型以及所有集成变体模型下载到您系统的默认缓存目录中。 **手动下载** 1. 从 HuggingFace 手动下载模型文件： - 分类器：[tabpfn-v2.5-classifier-v2.5_default.ckpt](https://huggingface.co/Prior-Labs/tabpfn_2_5/blob/main/tabpfn-v2.5-classifier-v2.5_default.ckpt)（注意：默认分类器使用的是在真实数据上微调的模型）。 - 回归器：[tabpfn-v2.5-regressor-v2.5_default.ckpt](https://huggingface.co/Prior-Labs/tabpfn_2_5/blob/main/tabpfn-v2.5-regressor-v2.5_default.ckpt) 2. 将文件放置在以下任一位置： - 直接指定：`TabPFNClassifier(model_path="/path/to/model.ckpt")` - 设置环境变量：`export TABPFN_MODEL_CACHE_DIR="/path/to/dir"`（参见下文的环境变量常见问题） - 默认的操作系统缓存目录： - 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](https://ux.priorlabs.ai) 获取。 - `TABPFN_NO_BROWSER`：设置为禁用基于浏览器的自动登录（例如，在不适合打开浏览器的环境中）。 **模型配置：** - `TABPFN_MODEL_CACHE_DIR`：用于缓存下载的 TabPFN 模型的自定义目录（默认：特定于平台的用户缓存目录） - `TABPFN_ALLOW_CPU_LARGE_DATASET`：允许在 CPU 上使用大型数据集（>1000 个样本）运行 TabPFN。设置为 `true` 以覆盖 CPU 限制。注意：这会非常慢！ **PyTorch 设置：** - `PYTORCH_CUDA_ALLOC_CONF`：PyTorch CUDA 内存分配配置，用于优化 GPU 内存使用（默认值：`max_split_size_mb:512`）。有关更多信息，请参阅 [PyTorch CUDA 文档](https://docs.pytorch.org/docs/stable/notes/cuda.html#optimizing-memory-usage-with-pytorch-cuda-alloc-conf)。 示例： ``` 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 上训练 regressor reg = TabPFNRegressor(device="cuda") reg.fit(X_train, y_train) save_fitted_tabpfn_model(reg, "my_reg.tabpfn_fit") # 稍后或在仅 CPU 的机器上 reg_cpu = load_fitted_tabpfn_model("my_reg.tabpfn_fit", device="cpu") ``` 如果只想存储基础模型权重（不包含已拟合的估计器），请使用 ``save_tabpfn_model(reg.model_, "my_tabpfn.ckpt")``。这仅保存预训练权重的检查点， 以便您以后可以创建并拟合一个新的估计器。使用 ``load_model_criterion_config`` 重新加载检查点。 ### **性能与限制** **问：TabPFN 可以处理缺失值吗？** 答：**可以！** **问：我怎样才能提高 TabPFN 的性能？** 答：最佳实践： - 使用 [TabPFN Extensions](https://github.com/priorlabs/tabpfn-extensions) 中的 **AutoTabPFNClassifier** 进行事后集成 - 特征工程：添加特定领域的特征以提高模型性能 无效操作： - 调整特征缩放 - 将分类特征转换为数值（例如，独热编码） **问：[Hugging-Face](https://huggingface.co/Prior-Labs/tabpfn_2_5/tree/main) 上有哪些不同的检查点？** 答：除了默认检查点外，其他可用的检查点都是实验性的，平均效果较差，我们建议始终从默认检查点开始。它们可以作为集成或超参数优化系统的一部分（并在 `AutoTabPFNClassifier` 中自动使用），或者手动尝试。它们的名称后缀代表了我们认为它们擅长的方面。
## 开发
1. 安装 [uv](https://docs.astral.sh/uv/)
2. 设置环境：
```
git clone https://github.com/PriorLabs/TabPFN.git
cd TabPFN
uv sync
source venv/bin/activate # On Windows: venv\Scripts\activate
pre-commit install
```
3. 提交前：
```
pre-commit run --all-files
```
4. 运行测试：
```
pytest tests/
```
## 匿名遥测
本项目收集完全匿名的使用遥测数据，您可以选择退出任何遥测或选择加入扩展遥测。
这些数据仅用于帮助我们为相关产品和计算环境提供稳定性并指导未来的改进。
- **不收集个人数据**
- **绝不发送任何代码、模型输入或输出**
- **数据严格匿名，无法关联到个人**
有关遥测的详细信息，请参阅我们的[遥测参考](https://github.com/PriorLabs/TabPFN/blob/main/TELEMETRY.md)和我们的[隐私政策](https://priorlabs.ai/privacy-policy/)。
**要选择退出**，请设置以下环境变量：
```
export TABPFN_DISABLE_TELEMETRY=1
```
由 [Prior Labs](https://priorlabs.ai) 用 ❤️ 构建 - 版权所有 (c) 2026 Prior Labs GmbH
## 快速入门
### 交互式 Notebook 教程
### 安装
官方安装 (pip)
```
pip install tabpfn
```
或者从源码安装
```
pip install "tabpfn @ git+https://github.com/PriorLabs/TabPFN.git"
```
或者本地开发安装：首先[安装 uv](https://docs.astral.sh/uv/getting-started/installation)（建议使用 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) # downloads checkpoint on first use
predictions = clf.predict(X_test)
reg = TabPFNRegressor()
reg.fit(X_train, y_train) # downloads checkpoint on first use
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](https://github.com/PriorLabs/TabPFN/tree/main/examples/tabpfn_for_binary_classification.py)、[tabpfn_for_multiclass_classification.py](https://github.com/PriorLabs/TabPFN/tree/main/examples/tabpfn_for_multiclass_classification.py) 和 [tabpfn_for_regression.py](https://github.com/PriorLabs/TabPFN/tree/main/examples/tabpfn_for_regression.py) 文件。
### 使用技巧
- **使用批量预测模式**：每次 `predict` 调用都会重新计算训练集。单独对 100 个样本调用 `predict` 几乎比单次调用慢 100 倍，且成本更高。如果测试集非常大，请将其拆分为每个包含 1000 个样本的块。
- **避免数据预处理**：在将数据输入模型时，不要应用数据缩放或独热编码。
- **使用 GPU**：TabPFN 在 CPU 上执行速度较慢。请确保有可用的 GPU 以获得更好的性能。
- **注意数据集大小**：TabPFN 在样本数少于 100,000 且特征数少于 2000 的数据集上效果最佳。对于更大的数据集，我们建议查看[大型数据集指南](https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/large_datasets/large_datasets_example.py)。
## TabPFN 生态系统
根据您的需求选择合适的 TabPFN 实现：
- **[TabPFN Client](https://github.com/priorlabs/tabpfn-client)**
简单的 API 客户端，用于通过云端推理使用 TabPFN。
- **[TabPFN Extensions](https://github.com/priorlabs/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 (此仓库)](https://github.com/priorlabs/tabpfn)**
支持使用 PyTorch 和 CUDA 进行快速本地推理的核心实现。
- **[TabPFN UX](https://ux.priorlabs.ai)**
无代码图形界面，用于探索 TabPFN 功能——非常适合业务用户和原型设计。
## TabPFN 工作流一览
遵循此决策树来构建您的模型，并从我们的生态系统选择正确的扩展。它将引导您解答有关数据、硬件和性能需求的关键问题，指导您找到适合特定用例的最佳解决方案。
```
---
config:
theme: 'default'
themeVariables:
edgeLabelBackground: 'white'
---
graph LR
%% 1. DEFINE COLOR SCHEME & STYLES
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. DEFINE GRAPH STRUCTURE
subgraph Infrastructure
start((Start)) --> gpu_check["GPU available?"];
gpu_check -- Yes --> local_version["Use TabPFN(local PyTorch)"]; gpu_check -- No --> api_client["Use TabPFN-Client
(cloud API)"]; task_type["What is
your task?"] end local_version --> task_type api_client --> task_type end_node((Workflow
Complete)); subgraph Unsupervised unsupervised_type["Select
Unsupervised Task"]; unsupervised_type --> imputation["Imputation"] unsupervised_type --> data_gen["Data
Generation"]; unsupervised_type --> tabebm["Data
Augmentation"]; unsupervised_type --> density["Outlier
Detection"]; unsupervised_type --> embedding["Get
Embeddings"]; end subgraph Data data_check["Data Checks"]; model_choice["Samples > 50k or
Classes > 10?"]; data_check -- "Table Contains Text Data?" --> api_backend_note["Note: API client has
native text support"]; api_backend_note --> model_choice; data_check -- "Time-Series Data?" --> ts_features["Use Time-Series
Features"]; ts_features --> model_choice; data_check -- "Purely Tabular" --> model_choice; model_choice -- "No" --> finetune_check; model_choice -- "Yes, 50k-100k samples" --> ignore_limits["Set
ignore_pretraining_limits=True"]; model_choice -- "Yes, >100k samples" --> subsample["Large Datasets Guide
"]; model_choice -- "Yes, >10 classes" --> many_class["Many-Class
Method"]; end subgraph Performance finetune_check["Need
Finetuning?"]; performance_check["Need Even Better Performance?"]; speed_check["Need faster inference
at prediction time?"]; kv_cache["Enable KV Cache
(fit_mode='fit_with_cache')
Faster predict; +Memory ~O(N×F)"]; tuning_complete["Tuning Complete"]; finetune_check -- Yes --> finetuning["Finetuning"]; finetune_check -- No --> performance_check; finetuning --> performance_check; performance_check -- No --> tuning_complete; performance_check -- Yes --> hpo["HPO"]; performance_check -- Yes --> post_hoc["Post-Hoc
Ensembling"]; performance_check -- Yes --> more_estimators["More
Estimators"]; performance_check -- Yes --> speed_check; speed_check -- Yes --> kv_cache; speed_check -- No --> 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["Need
Interpretability?"]; interpretability_check --> feature_selection["Feature Selection"]; interpretability_check --> partial_dependence["Partial Dependence Plots"]; interpretability_check --> shapley["Explain with
SHAP"]; interpretability_check --> shap_iq["Explain with
SHAP IQ"]; interpretability_check -- No --> end_node; feature_selection --> end_node; partial_dependence --> end_node; shapley --> end_node; shap_iq --> end_node; end %% 3. LINK SUBGRAPHS AND PATHS task_type -- "Classification or Regression" --> data_check; task_type -- "Unsupervised" --> unsupervised_type; subsample --> finetune_check; ignore_limits --> finetune_check; many_class --> finetune_check; %% 4. APPLY STYLES 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. ADD CLICKABLE LINKS (INCLUDING KV CACHE EXAMPLE) click local_version "https://github.com/PriorLabs/TabPFN" "TabPFN Backend Options" click api_client "https://github.com/PriorLabs/tabpfn-client" "TabPFN API Client" click api_backend_note "https://github.com/PriorLabs/tabpfn-client" "TabPFN API Backend" click unsupervised_type "https://github.com/PriorLabs/tabpfn-extensions" "TabPFN Extensions" click imputation "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/imputation.py" "TabPFN Imputation Example" click data_gen "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/generate_data.py" "TabPFN Data Generation Example" click tabebm "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/tabebm/tabebm_augment_real_world_data.ipynb" "TabEBM Data Augmentation Example" click density "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/unsupervised/density_estimation_outlier_detection.py" "TabPFN Density Estimation/Outlier Detection Example" click embedding "https://github.com/PriorLabs/tabpfn-extensions/tree/main/examples/embedding" "TabPFN Embedding Example" click ts_features "https://github.com/PriorLabs/tabpfn-time-series" "TabPFN Time-Series Example" click many_class "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/many_class/many_class_classifier_example.py" "Many Class Example" click finetuning "https://github.com/PriorLabs/TabPFN/blob/main/examples/finetune_classifier.py" "Finetuning Example" click feature_selection "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/feature_selection.py" "Feature Selection Example" click partial_dependence "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/pdp_example.py" "Partial Dependence Plots Example" click shapley "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/shap_example.py" "Shapley Values Example" click shap_iq "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/interpretability/shapiq_example.py" "SHAP IQ Example" click post_hoc "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/phe/phe_example.py" "Post-Hoc Ensemble Example" click hpo "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/hpo/tuned_tabpfn.py" "HPO Example" click subsample "https://github.com/PriorLabs/tabpfn-extensions/blob/main/examples/large_datasets/large_datasets_example.py" "Large Datasets Example" click kv_cache "https://github.com/PriorLabs/TabPFN/blob/main/examples/kv_cache_fast_prediction.py" "KV Cache Fast Prediction Example" ``` ## 许可证 TabPFN-2.5 和 TabPFN-2.6 模型权重根据[非商业许可证](https://huggingface.co/Prior-Labs/tabpfn_2_6/blob/main/LICENSE)授权。这些是默认使用的。 代码和 TabPFN-2 模型权重根据 Prior Labs 许可证（Apache 2.0 及额外的署名要求）授权：[此处](LICENSE)。要使用 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](mailto:sales@priorlabs.ai) 联系我们。** ## 引用 您可以阅读[此处](https://doi.org/10.1038/s41586-024-08328-6)的论文了解 TabPFNv2，并在[此处](https://arxiv.org/abs/2511.08667)阅读 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](https://colab.research.google.com/drive/154SoIzNW1LHBWyrxNwmBqtFAr1uZRZ6a#scrollTo=OwaXfEIWlhC8) 了解相关策略。 **问：为什么我不能在 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](https://ux.priorlabs.ai) 登录并接受许可条款。您的身份验证令牌会在本地缓存，因此您只需执行一次此操作。 **对于没有浏览器的无头 / CI 环境**，请访问 [https://ux.priorlabs.ai](https://ux.priorlabs.ai)，转到 **License（许可证）**选项卡接受许可，然后使用从您的帐户获取的令牌设置 `TABPFN_TOKEN` 环境变量。 如果您无法使用基于浏览器的方式，请通过 [`sales@priorlabs.ai`](mailto:sales@priorlabs.ai) 联系我们。 **问：如何在没有互联网连接的情况下使用 TabPFN？** TabPFN 会在首次使用时自动下载模型权重。对于离线使用： **使用提供的下载脚本** 如果您拥有 TabPFN 代码库，则可以使用包含的脚本下载所有模型（包括集成变体）： ``` # 在安装 TabPFN 之后 python scripts/download_all_models.py ``` 此脚本会将主分类器和回归器模型以及所有集成变体模型下载到您系统的默认缓存目录中。 **手动下载** 1. 从 HuggingFace 手动下载模型文件： - 分类器：[tabpfn-v2.5-classifier-v2.5_default.ckpt](https://huggingface.co/Prior-Labs/tabpfn_2_5/blob/main/tabpfn-v2.5-classifier-v2.5_default.ckpt)（注意：默认分类器使用的是在真实数据上微调的模型）。 - 回归器：[tabpfn-v2.5-regressor-v2.5_default.ckpt](https://huggingface.co/Prior-Labs/tabpfn_2_5/blob/main/tabpfn-v2.5-regressor-v2.5_default.ckpt) 2. 将文件放置在以下任一位置： - 直接指定：`TabPFNClassifier(model_path="/path/to/model.ckpt")` - 设置环境变量：`export TABPFN_MODEL_CACHE_DIR="/path/to/dir"`（参见下文的环境变量常见问题） - 默认的操作系统缓存目录： - 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](https://ux.priorlabs.ai) 获取。 - `TABPFN_NO_BROWSER`：设置为禁用基于浏览器的自动登录（例如，在不适合打开浏览器的环境中）。 **模型配置：** - `TABPFN_MODEL_CACHE_DIR`：用于缓存下载的 TabPFN 模型的自定义目录（默认：特定于平台的用户缓存目录） - `TABPFN_ALLOW_CPU_LARGE_DATASET`：允许在 CPU 上使用大型数据集（>1000 个样本）运行 TabPFN。设置为 `true` 以覆盖 CPU 限制。注意：这会非常慢！ **PyTorch 设置：** - `PYTORCH_CUDA_ALLOC_CONF`：PyTorch CUDA 内存分配配置，用于优化 GPU 内存使用（默认值：`max_split_size_mb:512`）。有关更多信息，请参阅 [PyTorch CUDA 文档](https://docs.pytorch.org/docs/stable/notes/cuda.html#optimizing-memory-usage-with-pytorch-cuda-alloc-conf)。 示例： ``` 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 上训练 regressor reg = TabPFNRegressor(device="cuda") reg.fit(X_train, y_train) save_fitted_tabpfn_model(reg, "my_reg.tabpfn_fit") # 稍后或在仅 CPU 的机器上 reg_cpu = load_fitted_tabpfn_model("my_reg.tabpfn_fit", device="cpu") ``` 如果只想存储基础模型权重（不包含已拟合的估计器），请使用 ``save_tabpfn_model(reg.model_, "my_tabpfn.ckpt")``。这仅保存预训练权重的检查点， 以便您以后可以创建并拟合一个新的估计器。使用 ``load_model_criterion_config`` 重新加载检查点。 ### **性能与限制** **问：TabPFN 可以处理缺失值吗？** 答：**可以！** **问：我怎样才能提高 TabPFN 的性能？** 答：最佳实践： - 使用 [TabPFN Extensions](https://github.com/priorlabs/tabpfn-extensions) 中的 **AutoTabPFNClassifier** 进行事后集成 - 特征工程：添加特定领域的特征以提高模型性能 无效操作： - 调整特征缩放 - 将分类特征转换为数值（例如，独热编码） **问：[Hugging-Face](https://huggingface.co/Prior-Labs/tabpfn_2_5/tree/main) 上有哪些不同的检查点？** 答：除了默认检查点外，其他可用的检查点都是实验性的，平均效果较差，我们建议始终从默认检查点开始。它们可以作为集成或超参数优化系统的一部分（并在 `AutoTabPFNClassifier` 中自动使用），或者手动尝试。它们的名称后缀代表了我们认为它们擅长的方面。
每个 TabPFN-2.5 检查点的更多详细信息
我们为在真实数据集上微调的检查点添加了 🌍 表情符号。有关 43 个数据集的列表，请参阅 [TabPFN-2.5 论文](https://arxiv.org/abs/2511.08667)。 - `tabpfn-v2.5-classifier-v2.5_default.ckpt` 🌍：默认分类检查点，在真实数据上进行了微调。 - `tabpfn-v2.5-classifier-v2.5_default-2.ckpt`：最佳分类合成数据检查点。使用它可获得未经真实数据微调的默认 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` 🌍：其他在真实数据上微调的分类检查点。总体效果相当不错，但在大型特征（>100-200）上表现不佳。 - `tabpfn-v2.5-classifier-v2.5_real-large-features.ckpt` 🌍：其他在真实上微调的分类检查点，在大样本（> 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`：默认回归检查点，仅在合成数据上训练。 - `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` 🌍：在真实数据上微调。在真实数据微调的检查点中最佳的检查点。对于回归，我们建议将仅使用合成数据的检查点作为默认选择，但此检查点在某些数据集上效果明显更好。 - `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`：其他变体，没有明显的专长，但在少数数据集上可能表现更好。标签：AI, Apex, Prior Labs, PyPI, Python, Scikit-learn, TabPFN, TabPFNClassifier, TabPFNRegressor, uv, Vectored Exception Handling, 人工智能, 先验学习, 凭据扫描, 分类模型, 合成数据训练, 回归模型, 基础模型, 大模型, 快速推理, 数据科学, 无后门, 机器学习, 深度学习, 用户模式Hook绕过, 算法, 自动化代码审查, 表格数据, 表格数据基础模型, 资源验证, 逆向工具