基于 TabPFN 表格模型和因子模块的案例实践

Python: 3.11.15

TabPFN: 0.8.3 (torch: 2.8.0)

DolphinDB: 3.00.4.2

TabPFN 安装：

源码安装方式（方便查看 src 目录）：

git clone https://github.com/PriorLabs/TabPFN.git
cd TabPFN
pip install -e .

pip 安装方式：

pip install tabpfn

下面给出一个使用 TabPFNRegressor 进行回归任务的简单示例，使用官网给出的模型进行预测。 这里使用 make_regression 方法来生成回归问题的数据集样例：

from tabpfn import TabPFNRegressor 
from sklearn.datasets import make_regression 
from sklearn.model_selection import train_test_split 
from sklearn.metrics import mean_squared_error, r2_score 
X, y = make_regression( 
    n_samples=1000, 
    n_features=20, 
    noise=0.1, 
    random_state=42, ) 
X_train, X_test, y_train, y_test = train_test_split( 
    X, 
    y, 
    test_size=0.2, 
    random_state=42, ) 

API_TOKEN = ""
tabpfn_client.set_access_token(API_TOKEN)

model = TabPFNRegressor() 
model.fit(X_train, y_train) 
pred = model.predict(X_test) 
print("MSE:", mean_squared_error(y_test, pred)) 
print("R2:", r2_score(y_test, pred))

使用TabPFN 模型需要在官网上申请相应的 API Key 。本案例主要使用模型的 v3 版本进行训练，其 API Keys的申请链接为：https://ux.priorlabs.ai/accept-license?hf_repo_id=tabpfn_3

按照链接中的步骤，选择语言为 python ，安装 tabpfn_client 包后，生成 API Keys，界面如下图所示：

获取后，可在左侧菜单栏 API Keys 处随时查看已有的 API Key 。

在每个分钟级时间截面上，模型根据当前时刻的因子数据预测各股票未来 30 分钟收益率，随后按照预测收益率进行排序，用于后续 TopN 选股回测。训练时间选用 2026.01.01-2026.03.31，测试时间选用2026.04.01-2026.04.20。本案例使用 DolphinDB 现有因子模块中的 335 个因子，包括 MyTT 常见指标、WorldQuant 101 Alpha 因子指标库中的因子和国泰君安 191 Alpha 因子库中的因子。此处，可以通过调用 DolphinDB 因子模块来快速计算需要的因子：

use mytt
use wq101alpha
use gtja191Alpha

预测目标定义为：

return_30min = close(t + 30min) / close(t) - 1

其中，close(t) 表示当前时刻收盘价，close(t + 30min) 表示同一交易日内 30 分钟后的收盘价。为避免跨日收益率计算，样本仅保留 14:30 及之前的分钟数据。

从 DolphinDB 数据库中，获取需要的股票和因子数据。本案例中主要涉及三种数据来源：能够获取行业股票的行业分类表、分钟频的因子表和分钟 K 线表。

为避免出现未来信息干扰训练，数据集按照时间顺序划分训练集和测试集。本文实验设置如下：

表 3-1

由于预测时耗时过长，测试集按30分钟采样，即保留整点和整30分钟的数据，与预测目标的 30min 预测保持一致。

数据规模限制

TabPFN 在训练和预测时需要将训练样本作为上下文（context） 与 查询样本（query) 同时输入模型，并通过行维度和列维度的注意力机制提取信息。因此，当样本数量或特征数量较大时，模型的显存占用和计算复杂度都会明显增加。

本文原始因子数量为 335 个，如果直接使用全部因子进行训练，会显著增加模型输入维度和 GPU 显存压力，也可能引入较多冗余因子和噪声因子。因此，在建模前需要对因子进行筛选或降维，在保留有效信息的同时减少特征数量，从而提高训练效率和模型稳定性。

因子筛选

原始因子数量为 335 个。首先，基于训练集移除缺失率大于 0.3 的因子，从原始 335 个因子去除 49 个因子。检查剩下的因子中，没有只出现单一值的因子，全部保留。

在实际业务中，一般需要结果的可解释性，单因子 rankIC 的方式在可解释性方面效果较好，因此本文以此方法为例进行因子筛选。筛选条件采用 rankIC 值绝对值排名前80、icir 绝对值排名前80，并且 rankIC 正负方向一致比例大于 55%。计算单因子 rankIC 值时，为了节省计算时间，仅保留训练集整点和整 30 分钟数据进行计算。

rankIC 计算部分代码：（具体可见附件）

for ts, group in tqdm(grouped, desc="IC by timestamps", total=len(grouped)):
  if len(group) < 2:
      continue

  group_target = group["target"]

  for col in factor_cols:
      # 用 dropna 同时剔除因子和 target 的缺失值
      valid = group[[col, "target"]].dropna()

      if len(valid) < 2:
          continue

      if valid[col].nunique() <= 1 or valid["target"].nunique() <= 1:
          continue
      
      # 计算 Spearman 相关系数
      ic = valid[col].corr(valid["target"], method="spearman")
      ic_rows.append({"timestamp": ts, "factor": col, "ic": ic})

因子相关性分析：

从上述过程筛选得到的 80 个因子中相关系数绝对值大于 0.9 的因子对有 65 组，去除其中 rankIC 值较低的因子，使得每一对中只保留一个因子。进行处理后，保留至 45 个因子。后续的建模训练都基于这 45 个因子。

rankIC 值绝对值最大的 6 个因子：

数据预处理完整脚本见附件。

本文所使用的是 TabPFN V3 Regressor 结构，主要用于连续型目标变量的预测任务。

Base Model 预测时间：392s

Fine-tuning 每轮训练时间：64s

对于股票截面选股任务，仅使用均方误差 Mean Squared Error（MSE）等点预测误差无法充分衡量模型效果，因此本文重点计算 RankIC。具体地：在每个时间截面上，计算模型预测收益率与真实未来 30 分钟收益率之间的 Spearman 秩相关系数。具体数学定义与计算公式可见附录。

示例代码如下：

predictions = meta_test.copy()
predictions["y_pred"] = np.asarray(pred)

rankic_rows = []
for ts, group in predictions.groupby("timestamps", sort=True):
    valid_group = group[["target", "y_pred"]].dropna()
    sample_count = len(valid_group)

    if sample_count < 2:
        rankic = np.nan
    else:
        rankic = valid_group["y_pred"].corr(
            valid_group["target"],
            method="spearman",
        )

    rankic_rows.append(
        {
            "timestamp": ts,
            "sample_count": sample_count,
            "rankic": rankic,
        }
    )

rankic_df = pd.DataFrame(rankic_rows)
mean_rankic = rankic_df["rankic"].dropna().mean()
std_rankic = rankic_df["rankic"].dropna().std()
icir = mean_rankic / std_rankic if std_rankic > 0 else np.nan

其中，mean_rankic 表示所有时间截面 RankIC 的均值，反映模型整体截面排序能力；std_rankic 表示 RankIC 的波动程度；信息系数信息比率 Information Coefficient Information Ratio（ICIR）为 RankIC 均值与标准差之比，用于衡量排序能力的稳定性。

数据加载及训练完整脚本见附件。在代码中 mode 部分，可通过选择不同的模式 ( base / finetune ) 来选择进行基础模型或微调模型的预测。

学习率设置：

模型微调时使用 warmup 与 decay 结合的学习率调度策略。在前 warmup_steps 内，学习率从 0 线性上升至基础学习率。若 lr_warmup_only=True，warmup 结束后学习率保持不变；若 lr_warmup_only=False，warmup 结束后学习率按照 cosine decay 衰减至 0。默认设置为 lr_warmup_only=False，即前 10% steps 进行 linear warmup，之后进行 cosine decay。基础学习率默认值为 1e-5，实践中可进行调整。

TabPFN 文档https://docs.priorlabs.ai/capabilities/fine-tuning#tuning-guidelines 指出对于较大规模的数据集（例如训练样本量超过 10k 行），可以适当尝试更高的学习率，例如 3e-5 到 1e-4，以加快模型微调过程中的收敛速度。

此外，由于各个申万二级行业股票数量不同（分布于2-268支），训练时数据量不同，训练不同行业股票数据时所用的学习率也应进行调整，否则可能导致效果不佳。另外，因子也可根据行业做不同筛选。

训练轮数与早停策略：

模型最大训练轮数设置为 30 个 epochs。训练过程中使用验证集 MSE 作为早停判断指标，当验证集 MSE 连续 8 个 epochs 没有一定程度的提升时，提前停止训练，以降低过拟合风险。

损失函数：

模型训练默认使用 crps_loss 和 mse_loss。其中，mse_loss 衡量预测值与真实收益率之间的平方误差，强调点预测精度；crps_loss 衡量预测分布与真实值之间的差异，更关注概率预测质量和不确定性刻画。两者结合可以同时约束点预测误差和预测分布质量。对于回归任务，模型提供五种loss及权重，具体可见附录。

训练样本采样方式：

由于 TabPFN 每次输入模型的样本数量受到上下文长度和显存限制，微调过程中通常不会一次性将全部训练数据输入模型，而是从完整训练集中反复采样子集进行训练。可以调整N_FINETUNE_CTX_PLUS_QUERY_SAMPLES 控制每个训练 step 中 context 样本和 query 样本的总数量，避免数据量超过GPU显存。

预测集成参数：

n_estimators 用于控制 TabPFN 在预测阶段的集成次数。数值越大，模型会基于更多组不同的数据顺序、特征顺序或内部随机变换进行多次预测，并对结果进行集成平均，从而提升预测稳定性和鲁棒性。但较大的 n_estimators 会增加推理时间和显存/内存占用，因此需要在预测稳定性和计算成本之间进行权衡。本教程采用默认值2。

Base Model 预测结果

表 4-1

Fine-Tuned Model 预测结果

表 4-2

本结果仅为示例演示，实际应用需在更长时间段和更多行业上验证。

回归任务的 Loss 由五部分组成：ce_loss，crps_loss，crls_loss，mse_loss，mae_loss

模型前向传播后，会输出针对回归目标 y 的 bar distribution，即将连续的回归目标离散化到若干有序区间中，并预测 y 落入每个区间的概率。因此，TabPFN 的回归训练可以理解为把连续值预测转化为一种“有序分桶上的概率分布预测”问题，而不是直接预测单个标量值。

在默认设置下，TabPFN v3 的 regression checkpoint 使用预定义的非均匀分桶边界 borders，这些边界来自模型 checkpoint 中保存的参考分布，并用于对标准化后的y进行分桶。默认分桶数为 5,000，即模型对每个样本输出一个长度为 5,000 的 logits 向量：z_i=[z_i,1, z_i,2,…,z_i,5000]，

经过 softmax 后，logits 被转换为各个区间上的概率： $p_{i,k}=\frac{\exp \left(z_{i,k}\right)}{\sum _{j=1}^K\exp \left(z_{i,j}\right)}$ 。

若真实目标值 y_i 落入第 k_i 个区间，则训练时通过 bar distribution 的 negative log-likelihood，也就是 cross-entropy-like loss，鼓励模型提高该区间的预测概率密度。由于不同区间宽度可能不同，TabPFN 会用区间宽度 w_ki 对概率进行校正，因此单个样本的损失可以写为： ${\mathcal{L}}_{\mathrm{ce}}=-\log \left(\frac{p_{i,k_i}}{w_{k_i}}\right)$ 。

其中 w_ki 是第 k_i 个分桶区间的宽度。换言之，TabPFN 回归并不是直接对预测值和真实值计算 MSE，而是先学习 y 的预测分布，再通过真实 y 所在区间的概率密度来计算损失。

crps_loss 和 crls_loss 是基于预测分布的累积分布函数 CDF 计算的。

CDF： $P(y_i\le b_{k+1})=F_{i,k}=\sum _{j=1}^k{p}_{i,j}$

构造一个阶跃函数： $Y_{i,k}=\mathbf{1}(k\ge k_i)$ ，视为真实标签的累积分布 ${\mathcal{L}}_{\mathrm{crps}}=\frac{1}{N}\sum _{i=1}^N\sum _{k=1}^K{w}_k{(F_{i,k}-Y_{i,k})}^2$

L_crls 则是在 CDF 上计算类似二分类交叉熵的 logarithmic score：

${\mathcal{L}}_{\mathrm{crls}}=\frac{1}{N}\sum _{i=1}^N\sum _{k=1}^K{w}_k[-Y_{i,k}\log F_{i,k}-(1-Y_{i,k})\log (1-F_{i,k}\left)\right]$

对于 mse_loss 和 mae_loss ，则是先对桶分布求一个预测均值：令 $m_k=\frac{b_k+b_{k+1}}{2}$ ， ${ŷ}_i=\sum _{k=1}^K{p}_{i,k}{m}_k$ 则 ${\mathcal{L}}_{\mathrm{mse}}=\frac{1}{N}\sum _{i=1}^N{({ŷ}_i-y_i)}^2$ ， ${\mathcal{L}}_{\mathrm{mae}}=\frac{1}{N}\sum _{i=1}^N|{ŷ}_i-y_i|$ 。

总 loss 由五部分加权组成，默认仅用 crps_loss 和 mse_loss： ${\mathcal{L}}_{\mathrm{total}}={\lambda }_{\mathrm{ce}}{\mathcal{L}}_{\mathrm{ce}}+{\lambda }_{\mathrm{crps}}{\mathcal{L}}_{\mathrm{crps}}+{\lambda }_{\mathrm{crls}}{\mathcal{L}}_{\mathrm{crls}}+{\lambda }_{\mathrm{mse}}{\mathcal{L}}_{\mathrm{mse}}+{\lambda }_{\mathrm{mae}}{\mathcal{L}}_{\mathrm{mae}}$ 。