tabicl

环境要求

• Python 环境（可通过 pip 安装第三方包）
• 首次使用需联网，从 Hugging Face 自动下载预训练 checkpoint
• 处理较大数据集建议使用 GPU（H100 上 5 万样本/100 特征约 10 秒内完成）
• Intel Mac 用户若 pip 安装 PyTorch 失败，需先用 conda 安装 PyTorch

安装与启动步骤

1. 1安装 tabicl

   一条命令即可完成安装，TabICL 兼容 scikit-learn，安装后可直接导入使用。

   pip install tabicl

   复制

2. 2按需安装可选依赖

   预测、可解释性、微调、预训练等功能对应不同 extras，也可用 all 一次性装齐。

   pip install tabicl[forecast]
   pip install tabicl[shap]
   pip install tabicl[finetune]
   pip install tabicl[pretrain]

   复制

3. 3Intel Mac 装 PyTorch

   仅在 Intel Mac 上 pip 安装 PyTorch 失败时需要，先用 conda 装好 PyTorch 再装 tabicl。

   conda install pytorch -c pytorch

   复制

4. 4零样本分类与回归

   fit 阶段首次会下载 checkpoint，之后开销很低；真正的上下文学习发生在 predict 时。

   from tabicl import TabICLClassifier, TabICLRegressor
   
   clf = TabICLClassifier()
   clf.fit(X_train, y_train)  # downloads checkpoint on first use, otherwise cheap
   clf.predict(X_test)  # in-context learning happens here
   
   reg = TabICLRegressor()
   reg.fit(X_train, y_train)
   reg.predict(X_test)

   复制

5. 5开启 KV 缓存加速

   缓存训练数据的 KV 投影并在多次 predict 间复用，速度更快但会额外占用内存，需权衡。

   clf = TabICLClassifier(kv_cache=True)
   clf.fit(X_train, y_train)  # caches key-value projections for training data
   clf.predict(X_test)  # fast: only processes test data by reusing the cached context

   复制

6. 6保存与加载模型

   可将已 fit 的分类器/回归器落盘再加载；关闭 save_training_data 有助于数据隐私。

   clf.save(
       "classifier.pkl",
       save_model_weights=False,  # if False, reload from checkpoint on load
       save_training_data=True,   # if True, include training data; if False, discard it (requires KV cache)
       save_kv_cache=True,        # if True and KV cache exists, save it
   )
   clf = TabICLClassifier.load("classifier.pkl")

   复制

7. 7微调单数据集(可选)

   需先装 finetune 依赖，提供验证集和输出目录；多 GPU 微调在 torchrun 下自动识别。

   from tabicl import FinetunedTabICLClassifier
   
   clf = FinetunedTabICLClassifier(
       epochs=50,
       learning_rate=1e-5,
       eval_metric="roc_auc",
       patience=10,
       random_state=0,
       verbose=True,
   )
   clf.fit(X_train, y_train, X_val=X_val, y_val=y_val, output_dir="./ckpts")
   y_pred = clf.predict(X_test)

   复制

关键配置

如何确认成功

跑通 fit 与 predict 即成功；首次运行会自动下载 checkpoint，设 verbose=True 可看到推理详细信息。

常见问题

注意事项

• TabICLRegressor 与分类器参数相同，但不含 class_shuffle_method、softmax_temperature、average_logits、support_many_classes。
• 微调写出的 checkpoint 遵循预训练 checkpoint 格式，可直接用 TabICLClassifier(model_path="ckpts/best.ckpt") 加载回零样本估计器。
• 多 GPU 微调在 torchrun 下自动检测：torchrun --nproc-per-node=2 finetune_script.py。
• 微调分类任务的教程可参考仓库中的 tutorials/finetune_classifier.py。