RTDL（表格深度学习研究）

RTDL（Research on Tabular Deep Learning）是一系列关于表格数据深度学习的论文和软件包集合。

:bell: 如需关注新项目的公告，请订阅此 GitHub 仓库的发布通知：“Watch -> Custom -> Releases”。

[!NOTE] 下面的项目列表是最新的，但 rtdl Python 包已弃用。 如果您曾使用过 rtdl 包，请阅读详细说明。

1. 首先需要澄清的是，本仓库并未弃用， 只有 rtdl 包已被弃用：它已被其他包所取代。
2. 如果您是从 PyPI 安装的最新版本 rtdl==0.0.13（而非从 GitHub！） 使用命令 pip install rtdl 进行安装，那么相同的模型 （MLP、ResNet、FT-Transformer）可以在 rtdl_revisiting_models 包中找到， 虽然 API 略有不同。
3. :exclamation: 如果您使用的是主分支中的未完成代码，强烈建议您切换到新的包。 特别是， 用于连续特征的嵌入实现尚不完善， 存在许多未解决的问题（而 rtdl_num_embeddings 包则更加高效且正确）。

论文

(2024) TabM：通过参数高效的集成方法推进表格深度学习
论文   代码   使用指南

(2024) TabReD：分析表格深度学习基准中的陷阱并填补空白
论文   代码

(2023) TabR：表格深度学习与最近邻方法的结合
论文   代码

(2022) TabDDPM：使用扩散模型建模表格数据
论文   代码

(2022) 重新审视表格深度学习的预训练目标
论文   代码

(2022) 关于表格深度学习中数值特征的嵌入方法
论文   代码   软件包（rtdl_num_embeddings）

(2021) 重新审视用于表格数据的深度学习模型
论文   代码   软件包（rtdl_revisiting_models）

(2019) 用于表格数据深度学习的神经无意识决策集成
论文   代码

RTDL 快速上手指南

RTDL (Research on Tabular Deep Learning) 是一个专注于表格数据深度学习的开源项目集合，汇集了多篇顶会论文及其对应的代码实现。注意：原有的 rtdl Python 包已弃用，请根据需求安装以下新的独立包。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.8 或更高版本
• 前置依赖：
  • PyTorch (推荐最新稳定版)
  • NumPy
  • Pandas
  • Scikit-learn

确保已安装基础深度学习环境：

pip install torch numpy pandas scikit-learn

安装步骤

由于原 rtdl 包已废弃，请根据你的研究或应用需求选择安装对应的子项目包。推荐使用国内镜像源加速安装。

1. 安装经典模型复现包 (MLP, ResNet, FT-Transformer)

对应论文：Revisiting Deep Learning Models for Tabular Data (2021)

pip install rtdl-revisiting-models -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装数值特征嵌入包 (Numerical Embeddings)

对应论文：On Embeddings for Numerical Features in Tabular Deep Learning (2022) 此包修复了旧版中连续特征嵌入的实现问题，效率更高。

pip install rtdl-num-embeddings -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装其他前沿模型

如需使用 TabM, TabR, TabDDPM 等较新模型，建议直接克隆对应仓库使用（因部分尚未发布为独立 PyPI 包）：

TabM (2024):

git clone https://github.com/yandex-research/tabm.git
cd tabm
pip install -e .

TabR (2023):

git clone https://github.com/yandex-research/tabular-dl-tabr.git
cd tabular-dl-tabr
pip install -e .

基本使用

以下以 rtdl-revisiting-models 包中的 FT-Transformer 为例，展示最基础的构建与使用前向传播流程。

代码示例

import torch
import torch.nn as nn
from rtdl_revisiting_models import FTTransformer

# 1. 定义超参数
num_classes = 2  # 分类任务类别数
d_in = 10        # 输入特征维度
d_out = 64       # 隐藏层维度
n_layers = 3     # Transformer 层数

# 2. 初始化模型
# 注意：具体参数名称可能随版本微调，请参考各包文档
model = FTTransformer(
    n_numerical_features=d_in,
    d_model=d_out,
    n_layers=n_layers,
    head_config={'n_layers': 2, 'd_out': num_classes}
)

# 3. 准备模拟数据 (Batch Size: 4, Features: 10)
X_num = torch.randn(4, d_in) 

# 4. 前向传播
logits = model(X_num)

print(f"输出形状：{logits.shape}") 
# 预期输出：torch.Size([4, 2])

使用说明

• 数据预处理：该系列模型通常假设数值特征已经过标准化处理。
• 类别特征：若包含类别特征，需先进行索引编码（Index Encoding），并传入相应的 n_categorical_features 和 cat_idx 参数（视具体模型实现而定）。
• 训练循环：模型返回的是 logits，分类任务请配合 CrossEntropyLoss 使用，回归任务请配合 MSELoss 使用。