TabPFN 实践指南：三步从表格数据到分类与回归预测-平芜编程栈

TabPFN 实践指南：三步从表格数据到分类与回归预测

【免费下载链接】TabPFN⚡ TabPFN: Foundation Model for Tabular Data ⚡项目地址: https://gitcode.com/GitHub_Trending/ta/TabPFN

TabPFN 是一个面向表格数据的基础模型，能在你手头的小样本数据上直接完成二分类、多分类和回归预测，适合欺诈检测、客户流失、科研实验等来不及做特征工程和调参的场景。它提供 sklearn 风格的 fit/predict 接口，内置预处理、集成与调优逻辑，安装后几分钟内就能在本地得到第一版预测结果。

它解决什么问题：小样本表格上的零训练预测

传统做法里，拿到一张表格后通常要经历缺失值处理、缩放、编码、选模型、调参、交叉验证一整条流水线，且每个项目都要重来一遍。TabPFN 把这条流水线压缩为一次 fit 调用：模型通过上下文学习的方式，把训练集当作"提示"直接前向推理出预测，fit 阶段不做梯度训练，因此在小数据集上也能快速出结果。

分类任务：二分类与多分类

分类器 TabPFNClassifier 是主入口。调用 fit 后，模型会缓存训练集的表示；predict 返回类别，predict_proba 返回各类别概率。多分类同样支持，且内置阈值校准与 softmax 温度调优机制，可用留出数据自动选择更合适的决策阈值。仓库示例目录 examples/tabpfn_for_binary_classification.py 和 examples/tabpfn_for_multiclass_classification.py 覆盖了两种任务的完整流程。

回归任务：输出均值、分位数与完整分布

回归器 TabPFNRegressor 不只输出一个点预测。predict 支持 mean、median、mode 等输出类型，也可以指定分位数列表。更进一步的用法是传入 output_type="full" 拿到逐样本的预测分布，再用 src/tabpfn/visualisation/ 中的 plot_regression_distribution 把"模型认为这个样本的目标值大概落在哪一段"画出来。示例见 examples/plot_regression_distribution.py。

缺失值与脏数据：直接喂入即可

官方 FAQ 明确确认 TabPFN 可以处理缺失值。数据清洗（clean）、模态检测（区分数值、类别、文本、日期列）、标签编码都在内部自动完成，相关实现位于 src/tabpfn/preprocessing/ 目录。官方也明确提醒：用户侧不需要自己做缩放或 one-hot 编码，反而做这些预处理对模型没有帮助。

快速上手：最小安装与调用路径

安装与许可认证

TabPFN 要求 Python 3.10 以上，依赖 PyTorch 2.5 以上。安装只有一条命令：

pip install tabpfn

首次 fit 时会自动下载模型权重并打开浏览器完成许可认证，令牌会缓存在本地，只需做一次。在无浏览器的 CI 或服务器环境，需要先在官方页面接受许可，再通过环境变量 TABPFN_TOKEN 提供令牌；也可用 TABPFN_NO_BROWSER 关闭自动弹窗。

写出第一个预测器

默认使用 TabPFN-3 模型，三行代码即可跑通分类：

from tabpfn import TabPFNClassifier clf = TabPFNClassifier() clf.fit(X_train, y_train) # 首次调用自动下载权重 predictions = clf.predict(X_test)

需要复现旧版本结果时，可用 create_default_for_version 指定版本（如 V2、V2_5、V2_6），这在 tests/ 的参考预测值测试中也被大量使用，说明不同版本的输出差异是受控且可校验的。

离线与缓存配置

离线部署可以用仓库自带的脚本一次性拉取全部模型：

python scripts/download_all_models.py

权重默认缓存在系统用户缓存目录（Linux 为 ~/.cache/tabpfn/），也可用环境变量 TABPFN_MODEL_CACHE_DIR 指定位置，便于内网机器共享同一份权重。

核心能力拆解：内置预处理、多种推理模式与可训练接口

内置集成与特征工程

fit 阶段会构建一个内部集成（ensemble）：对特征做随机子采样、轮转/打乱、分布重塑（分位数变换、SquashingScaler 等）、SVD 特征追加、指纹特征，再按多个成员前向推理后聚合。特征重要性排序还会借助 LightGBM 做自动选择。这些步骤的配置集中在 src/tabpfn/preprocessing/ensemble.py，用户无需逐项设置；n_estimators 默认为 auto，会按特征覆盖度自动伸缩。

推理模式：按内存与速度取舍

构造器的 fit_mode 提供四种模式：low_memory、fit_preprocessors、fit_with_cache、batched。区别在于是否缓存训练集表示（KV cache）以及测试集是否分块。测试集很大时，官方建议单次批量 predict 而不是逐条调用——因为每次 predict 都会重算训练集表示，逐条调用 100 条样本可能慢近 100 倍；测试集超过 1000 行时建议按 1000 行一块切分。缓存精度还可配置为 int8 或 fp8 以省显存。

微调、Prompt Tuning 与保存加载

权重冻结的基础上还有两条"训练"路径：一是 examples/prompt_tuning_classifier.py 展示的 prompt tuning，通过 differentiable_input=True 让一组可微的"提示样本"参与梯度更新；二是 src/tabpfn/finetuning/ 中的 FinetunedTabPFNClassifier / FinetunedTabPFNRegressor，支持完整微调训练，含早停、学习率调度与多卡分片，配套示例在 examples/finetune_classifier.py 和 examples/finetune_regressor.py。已有拟合结果可用 save_fitted_tabpfn_model 持久化、load_fitted_tabpfn_model 在其他进程恢复。

前置条件与局限：适合谁、不适合谁

硬件与数据规模

GPU 是官方推荐配置（约 8GB 显存即可，大测试集约 16GB）；纯 CPU 环境下 TabPFN-3 默认最多 5000 个训练样本，旧版本 1000 个，可用 TABPFN_ALLOW_CPU_LARGE_DATASET 突破但速度很慢。数据集规模方面，TabPFN-3 的推荐上限为 100 万行 × 200 特征、10 万行 × 2000 特征或 1000 行 × 2 万特征，行数与特征数之间是此消彼长的关系；超出后建议降采样或设置 ignore_pretraining_limits=True。

与树模型做法的差异

对比维度	TabPFN	传统树模型（如 XGBoost）
拟合方式	上下文学习，无梯度训练	在数据集上迭代训练
预处理	内置，用户无需缩放/编码	通常需自行完成
推理硬件	推荐 GPU	CPU 即可
模型权重许可	v2.5/2.6/3 为非商业许可	开源许可