:boom: 新闻

• 2025年11月10日：LimiX-2M正式发布！相较于LimiX-16M，这一更小的版本在显存占用上显著降低，推理速度更快。同时，检索机制也得到了增强，进一步提升了模型性能，并减少了推理时间和内存消耗。
• 2025年8月29日：LimiX V1.0发布。

⚡ 最新结果与SOTA模型对比

➤ 概述

我们推出了LimiX，这是我们LDM系列的第一款产品。LimiX旨在进一步提升通用性：通过一套统一的训练与推理流程，即可完成分类、回归、缺失值填补、特征选择、样本选择以及因果推断等任务，推动从定制化流水线向统一的基础型表格数据学习范式的转变。

LimiX采用专为结构化数据建模和任务泛化优化的Transformer架构。该模型首先将来自先验知识库的特征X和目标Y嵌入为标记表示。在核心模块中，注意力机制同时作用于样本和特征维度，以识别关键样本和特征中的重要模式。随后，这些高维表示会被传递到回归和分类头，从而使模型能够支持多种预测任务。

有关详细信息，请参阅以下技术报告：LimiX:释放结构化数据建模能力，助力通用智能 或 LimiX_Technical_Report.pdf。

➤ 卓越性能

LimiX模型在多项任务中均取得了SOTA水平的表现。

➩ 分类

➩ 回归

➩ 缺失值填补

➤ 教程

➩ 安装

方案一（推荐）：使用Dockerfile

下载 Dockerfile

docker build --network=host -t limix/infe:v1 --build-arg FROM_IMAGES=nvidia/cuda:12.2.0-base-ubuntu22.04 -f Dockerfile .

方案二：手动构建

下载预编译的flash_attn文件

wget -O flash_attn-2.8.0.post2+cu12torch2.7cxx11abiTRUE-cp312-cp312-linux_x86_64.whl https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.0.post2/flash_attn-2.8.0.post2+cu12torch2.7cxx11abiTRUE-cp312-cp312-linux_x86_64.whl

安装Python依赖

pip install python==3.12.7 torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1
pip install flash_attn-2.8.0.post2+cu12torch2.7cxx11abiTRUE-cp312-cp312-linux_x86_64.whl
pip install scikit-learn  einops  huggingface-hub matplotlib networkx numpy pandas  scipy tqdm typing_extensions xgboost kditransform hyperopt

下载源代码

git clone https://github.com/limix-ldm/LimiX.git
cd LimiX

➤ 推理

LimiX支持分类、回归和缺失值填补等任务

➩ 模型下载

模型大小	下载链接	支持的任务
LimiX-16M	LimiX-16M.ckpt	✅ 分类 ✅回归 ✅缺失值填补
LimiX-2M	LimiX-2M.ckpt	✅ 分类 ✅回归

➩ 接口说明

模型创建

class LimiXPredictor:
    def __init__(self,
                 device:torch.device,
                 model_path:str,
                 mix_precision:bool=True,
                 inference_config: list|str,
                 categorical_features_indices:List[int]|None=None,
                 outlier_remove_std: float=12,
                 softmax_temperature:float=0.9,
                 task_type: Literal['Classification', 'Regression']='Classification',
                 mask_prediction:bool=False,
                 inference_with_DDP: bool = False,
                 seed:int=0)

参数	数据类型	描述
device	torch.device	加载模型的硬件设备
model_path	str	需要加载的模型路径
mix_precision	bool	是否启用混合精度推理
inference_config	list/str	用于推理的配置文件
categorical_features_indices	list	表格数据中分类列的索引
outlier_remove_std	float	用于去除异常值的阈值，定义为标准差的倍数
softmax_temperature	float	用于控制Softmax操作行为的温度
task_type	str	任务类型，可为“分类”或“回归”
mask_prediction	bool	是否启用缺失值填补
inference_with_DDP	bool	是否在推理过程中启用DDP
seed	int	用于控制随机状态的种子

预测

def predict(self, x_train:np.ndarray, y_train:np.ndarray, x_test:np.ndarray) -> np.ndarray:

参数	数据类型	描述
x_train	np.ndarray	训练集的输入特征
y_train	np.ndarray	训练集的目标变量
x_test	np.ndarray	测试集的输入特征

推理配置文件说明

配置文件名	说明	区别
cls_default_retrieval.json	默认的分类任务推理配置文件，带检索	分类性能更优
cls_default_noretrieval.json	默认的分类任务推理配置文件，不带检索	速度更快，内存需求更低
reg_default_retrieval.json	默认的回归任务推理配置文件，带检索	回归性能更优
reg_default_noretrieval.json	默认的回归任务推理配置文件，不带检索	速度更快，内存需求更低
reg_default_noretrieval_MVI.json	默认的缺失值插补任务推理配置文件

➩ 基于样本检索的集成推理

有关基于样本检索的集成推理的详细技术介绍，请参阅技术报告。

考虑到推理速度和内存需求，基于样本检索的集成推理目前仅支持硬件规格高于NVIDIA RTX 4090 GPU的设备。

分类任务

python inference_classifier.py --save_name your_save_name --inference_config_path path_to_retrieval_config --data_dir path_to_data

回归任务

python inference_regression.py --save_name your_save_name --inference_config_path path_to_retrieval_config --data_dir path_to_data

自定义推理任务的数据预处理

首先生成推理配置文件

generate_inference_config()

分类任务

单GPU或CPU

python  inference_classifier.py --save_name your_save_name --inference_config_path path_to_retrieval_config --data_dir path_to_data

多GPU分布式推理

torchrun --nproc_per_node=8  inference_classifier.py --save_name your_save_name --inference_config_path path_to_retrieval_config --data_dir path_to_data --inference_with_DDP

回归任务

单GPU或CPU

python  inference_regression.py --save_name your_save_name --inference_config_path path_to_retrieval_config --data_dir path_to_data

多GPU分布式推理

torchrun --nproc_per_node=8  inference_regression.py --save_name your_save_name --inference_config_path path_to_retrieval_config --data_dir path_to_data --inference_with_DDP

检索优化项目

该项目实现了一个优化的检索系统。为了达到最佳性能，我们使用Optuna对检索参数进行超参数调优。

安装

请确保已安装所需依赖：

pip install optuna

使用

对于使用预先优化参数的标准推理，请参考以下代码：

searchInference = RetrievalSearchHyperparameters(
           dict(device_id=0,model_path=model_path), X_train, y_train, X_test, y_test,
)
config, result = searchInference.search(n_trials=10, metric="AUC",
              inference_config='config/cls_default_retrieval.json',task_type="cls")

这将启动一个Optuna研究，为您特定的数据集和用例寻找最佳的检索参数组合。

➩ 分类

from sklearn.datasets import load_breast_cancer
from sklearn.metrics import accuracy_score, roc_auc_score
from sklearn.model_selection import train_test_split
from huggingface_hub import hf_hub_download
import numpy as np
import os, sys

os.environ["RANK"] = "0"
os.environ["WORLD_SIZE"] = "1"
os.environ["MASTER_ADDR"] = "127.0.0.1"
os.environ["MASTER_PORT"] = "29500"

ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if ROOT_DIR not in sys.path:
    sys.path.insert(0, ROOT_DIR)
from inference.predictor import LimiXPredictor

X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.5, random_state=42)

model_file = hf_hub_download(repo_id="stableai-org/LimiX-16M", filename="LimiX-16M.ckpt", local_dir="./cache")

clf = LimiXPredictor(device=torch.device('cuda'), model_path=model_file, inference_config='config/cls_default_retrieval.json')
prediction = clf.predict(X_train, y_train, X_test)

print("roc_auc_score:", roc_auc_score(y_test, prediction[:, 1]))
print("accuracy_score:", accuracy_score(y_test, np.argmax(prediction, axis=1)))

更多示例请参阅inference_classifier.py

➩ 回归

from functools import partial

from sklearn.datasets import fetch_california_housing
from sklearn.model_selection import train_test_split
from sklearn.metrics import r2_score
from huggingface_hub import hf_hub_download
try:
    from sklearn.metrics import root_mean_squared_error as mean_squared_error
except:
    from sklearn.metrics import mean_squared_error
    mean_squared_error = partial(mean_squared_error, squared=False)
import os, sys

os.environ["RANK"] = "0"
os.environ["WORLD_SIZE"] = "1"
os.environ["MASTER_ADDR"] = "127.0.0.1"
os.environ["MASTER_PORT"] = "29500"

ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if ROOT_DIR not in sys.path:
    sys.path.insert(0, ROOT_DIR)
from inference.predictor import LimiXPredictor

house_data = fetch_california_housing()
X, y = house_data.data, house_data.target
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.33, random_state=42)

y_mean = y_train.mean()
y_std = y_train.std()
y_train_normalized = (y_train - y_mean) / y_std
y_test_normalized = (y_test - y_mean) / y_std

model_path = hf_hub_download(repo_id="stableai-org/LimiX-16M", filename="LimiX-16M.ckpt", local_dir="./cache")

model = LimiXPredictor(device=torch.device('cuda'), model_path=model_path, inference_config='config/reg_default_retrieval.json')
y_pred = model.predict(X_train, y_train_normalized, X_test)    

# 计算RMSE和R²
y_pred = y_pred.to('cpu').numpy()
rmse = mean_squared_error(y_test_normalized, y_pred)
r2 = r2_score(y_test_normalized, y_pred)

print(f'RMSE: {rmse}')
print(f'R2: {r2}')

更多示例请参阅inference_regression.py

➩ 缺失值插补

演示文件请参见examples/demo_missing_value_imputation.py

➤ 链接

• LimiX：释放通用智能的结构化数据建模能力：LimiX：释放通用智能的结构化数据建模能力
• LimiX 技术报告：LimiX_Technical_Report.pdf
• 使用 LimiX 的详细说明：访问 LimiX 官方文档
• 平衡综合挑战性全领域分类基准：bcco_cls
• 平衡综合挑战性全领域回归基准：bcco_reg

➤ 许可证

本仓库中的代码以 Apache-2.0 许可证开源，而 LimiX 模型权重的使用则受模型许可证约束。LimiX 权重完全可用于学术研究，并在获得适当授权后也可用于商业用途。

➤ 引用

@article{zhang2025limix,
  title={Limix: Unleashing structured-data modeling capability for generalist intelligence},
  author={Zhang, Xingxuan and Ren, Gang and Yu, Han and Yuan, Hao and Wang, Hui and Li, Jiansheng and Wu, Jiayun and Mo, Lang and Mao, Li and Hao, Mingchao and others},
  journal={arXiv preprint arXiv:2509.03505},
  year={2025}
}

LimiX 快速上手指南

LimiX 是一款基于 Transformer 架构的通用表格数据基础模型，支持分类、回归、缺失值填补等多种任务。本指南将帮助您快速完成环境配置并运行首个预测示例。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 22.04)
• GPU: NVIDIA GPU (推荐 RTX 4090 或更高以启用检索增强推理；普通推理支持较低显存设备)
• CUDA: 12.2+
• Python: 3.12.7

前置依赖

• Docker (可选，推荐用于隔离环境)
• Git
• NVIDIA Container Toolkit (若使用 Docker)

2. 安装步骤

您可以选择使用 Docker（推荐）或手动安装。

方案一：使用 Docker（推荐）

下载 Dockerfile 并构建镜像：

wget https://raw.githubusercontent.com/limix-ldm/LimiX/main/Dockerfile
docker build --network=host -t limix/infe:v1 --build-arg FROM_IMAGES=nvidia/cuda:12.2.0-base-ubuntu22.04 -f Dockerfile .

启动容器：

docker run --gpus all -it --rm limix/infe:v1 bash

方案二：手动安装

1. 下载预编译的 flash_attn 包：

wget -O flash_attn-2.8.0.post2+cu12torch2.7cxx11abiTRUE-cp312-cp312-linux_x86_64.whl https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.0.post2/flash_attn-2.8.0.post2+cu12torch2.7cxx11abiTRUE-cp312-cp312-linux_x86_64.whl

2. 安装 Python 依赖：

pip install python==3.12.7 torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1
pip install flash_attn-2.8.0.post2+cu12torch2.7cxx11abiTRUE-cp312-cp312-linux_x86_64.whl
pip install scikit-learn einops huggingface-hub matplotlib networkx numpy pandas scipy tqdm typing_extensions xgboost kditransform hyperopt

提示：国内用户建议使用清华或阿里镜像源加速安装，例如在 pip 命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple。

3. 克隆源代码：

git clone https://github.com/limix-ldm/LimiX.git
cd LimiX

3. 基本使用

以下示例演示如何使用 LimiX-16M 模型进行简单的二分类任务（乳腺癌数据集）。

步骤 1: 准备代码

创建文件 quick_start.py，填入以下代码：

from sklearn.datasets import load_breast_cancer
from sklearn.metrics import accuracy_score, roc_auc_score
from sklearn.model_selection import train_test_split
from huggingface_hub import hf_hub_download
import numpy as np
import os, sys
import torch

# 设置分布式环境变量（单机单卡模式）
os.environ["RANK"] = "0"
os.environ["WORLD_SIZE"] = "1"
os.environ["MASTER_ADDR"] = "127.0.0.1"
os.environ["MASTER_PORT"] = "29500"

# 添加项目路径
ROOT_DIR = os.path.abspath(os.path.dirname(__file__))
if ROOT_DIR not in sys.path:
    sys.path.insert(0, ROOT_DIR)

from inference.predictor import LimiXPredictor

# 1. 加载数据
X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.5, random_state=42)

# 2. 下载模型 (自动缓存到本地)
# 可选模型：LimiX-16M (全能型) 或 LimiX-2M (轻量型，仅支持分类/回归)
model_file = hf_hub_download(repo_id="stableai-org/LimiX-16M", filename="LimiX-16M.ckpt", local_dir="./cache")

# 3. 初始化预测器
# task_type: 'Classification' 或 'Regression'
# inference_config: 选择带检索 (性能更好) 或不带检索 (速度更快) 的配置
clf = LimiXPredictor(
    device=torch.device('cuda'), 
    model_path=model_file, 
    inference_config='config/cls_default_retrieval.json',
    task_type='Classification'
)

# 4. 执行预测
# 输入：训练集特征、训练集标签、测试集特征
prediction = clf.predict(X_train, y_train, X_test)

# 5. 评估结果
print("ROC AUC Score:", roc_auc_score(y_test, prediction[:, 1]))
print("Accuracy Score:", accuracy_score(y_test, np.argmax(prediction, axis=1)))

步骤 2: 运行脚本

python quick_start.py

常用配置说明

任务类型	推荐配置文件 (inference_config)	说明
分类 (Classification)	config/cls_default_retrieval.json	默认开启检索，精度最高
分类 (快速)	config/cls_default_noretrieval.json	关闭检索，速度更快，显存占用更低
回归 (Regression)	config/reg_default_retrieval.json	默认开启检索，精度最高
缺失值填补	config/reg_default_noretrieval_MVI.json	专门用于缺失值填补任务

注意：若显存不足（如低于 24GB），建议在初始化 LimiXPredictor 时选用 *_noretrieval.json 配置文件，或直接使用参数量更小的 LimiX-2M 模型。