Sooboost
纯 Rust 实现的梯度提升决策树(GBDT)。目标很直接:让 Rust 项目用表格数据时,不必为了一个 GBDT 拖进 Python 或 C++ 工具链。
状态:crates.io 0.2.0 已发布。 核心算法(分箱 / 直方图 / 建树 / 提升 / 类别特征 / 序列化)已完整可用并通过 CI 门禁; M6 硬化已收口:早停 / 交叉验证 / 特征重要度 / softmax 多分类全部落地, 真实数据集精度下限已固化为 CI 性能门禁。注意:模型格式为 v4,0.1.x 导出的模型文件需重新训练。 生产使用请自行评估。
快速开始
[]
= "0.2.0"
use GradientBoosting;
use ;
// 1. 读数据(arrow RecordBatch 零拷贝视图;也支持 from_record_batch)
let train = from_csv_path?;
// 2. 训练(builder 式配置,一行目标)
let model = regressor
.n_estimators
.learning_rate
.max_depth
.seed
.fit?;
// 3. 预测 / 在线单行推断 / 存读
let preds = model.predict?;
let one = model.predict_row?;
model.save?;
let reloaded = load?;
二分类把 regressor() 换成 classifier() 即可,predict 输出正类概率,
raw_scores 输出 logit(供自定义阈值 / 校准)。
早停 / 交叉验证 / 特征重要度(M6 已落地)
// 早停:连续 50 轮验证损失无改善即停,并回滚到最优轮
let model = regressor
.n_estimators
.early_stopping // 验证集 Dataset + patience
.fit?;
model.best_iteration; // 实际使用的轮数
model.eval_history; // 每轮验证损失(学习曲线)
// K 折交叉验证(连续分块,完全确定;指标按目标自动选 R² / AUC / accuracy)
let cv = regressor
.n_estimators
.cross_validate?;
cv.mean; cv.std; cv.fold_scores;
// 特征重要度(gain / cover / frequency,归一化;随模型持久化,load 后可用)
let imp = model.feature_importances;
多分类(softmax,M6 已落地)
// 每轮每类一棵树;y 必须为整数标签 ∈ [0, n_classes)
let model = multiclass_classifier
.n_estimators
.learning_rate
.fit?;
let classes = model.predict_classes?; // argmax 类别
let proba = model.predict_proba?; // [row][class],softmax 行和为 1
let logits = model.raw_logits?; // softmax 前的 logits(自定义校准用)
model.feature_importances; // 跨全部类别聚合
// 序列化与目标自动探测与标量模型完全一致:save / load / from_bytes
model.save?;
let loaded = load?; // 自动探测出多分类目标
多分类暂不支持类别特征与早停(显式报错,不静默降级);交叉验证指标自动用 accuracy。
CLI 同样支持:--eval <valid.csv> --early-stopping <rounds>。
完整可运行示例:
精度对标
当前基线是 scikit-learn HistGradientBoostingRegressor/Classifier
(benchmark/*/correctness_metrics.json,纳入 CI 门禁)。sooboost 一列来自
sooboost-cli,超参与基线一致(100 轮 / lr 0.1 / max_depth 6):
| 数据集 | 指标 | sooboost | sklearn HGB | 差 |
|---|---|---|---|---|
| california_housing(16.5k×8) | R² | 0.8287 | 0.8355 | −0.007 |
| synthetic_regression | R² | 0.9567 | 0.9615 | −0.005 |
| synthetic_regression_nonlinear | R² | 0.3745 | 0.3666 | +0.008 |
| synthetic_binary | AUC | 0.9478 | 0.9491 | −0.001 |
参考:example 用 200 轮 / lr 0.1 在 california_housing 上跑到 R² 0.8404, 训练 1.08s(16,512 行 × 8 特征),测试集 4,128 行。
诚实的边界:上表只对标了 sklearn HGB(纳入 CI 门禁的基线)。 对标 XGBoost / LightGBM / CatBoost 的实测见下一节。
对比 XGBoost / LightGBM / CatBoost(真实数据集)
统一预算(200 轮 / lr 0.1 / seed 42,深度或叶子取各库默认等价容量),
三个真实数据集(非合成),复现:python benchmark/compare_giants.py:
| 数据集 | 指标 | sooboost | XGBoost 3.4 | LightGBM 4.7 | CatBoost 1.2 | sklearn HGB |
|---|---|---|---|---|---|---|
| california_housing(16.5k×8) | R² | 0.8403 | 0.8410 | 0.8466 | 0.8243 | 0.8427 |
| diabetes(353×10) | R² | 0.3877 | 0.3594 | 0.3494 | 0.4521 | 0.3408 |
| breast_cancer(455×30) | AUC | 0.9950 | 0.9937 | 0.9891 | 0.9970 | 0.9904 |
结论(如实说,不过度宣称):sooboost 在三个真实集上全部进入前二—— 回归与分类质量与三巨头同一梯队(差距 <1%),小数据集上甚至超过 XGBoost / LightGBM; CatBoost 在小数据集上领先,归因于其有序提升等算法差异,不是工程问题。 训练速度:快于 sklearn HGB 与 CatBoost,慢于 LightGBM / XGBoost(后者有多年的 SIMD / leaf-wise 优化沉淀,这是 M6 性能门禁要追的方向)。
为什么再造一个
| 取舍 | 选择 | 代价 |
|---|---|---|
| 实现语言 | 纯 Rust,#![forbid(unsafe_code)] |
放弃了部分 SIMD / 零拷贝的极致优化空间 |
| 数据入口 | arrow RecordBatch 零拷贝视图 |
与 arrow 生态绑定 |
| 可复现性 | 无隐藏随机源,seed 显式传递;同输入同 seed 逐位一致 | 需要显式管理 seed |
| 全局状态 | 无。运行时状态经 TrainingContext 显式传递 |
API 略啰嗦(门面已收口) |
| 平台 | MVP 只支持 x86_64 Linux / Windows | 其他平台未验证 |
| 依赖 | 克制;不引入按月强迫升级的重依赖 | 暂无 GPU 支持 |
设计取自对 XGBoost / LightGBM / CatBoost 失败模式的调研(见 doc/research/),
7 条红线与 10 条架构决策记录在 doc/baseline/architecture.md。
仓库结构
sooboost-core/ 核心库(数据层 → 树内核 → 训练层 → 部署面)
sooboost-cli/ 命令行基准工具
sooboost-experiments/ 研究方向原型(条件分布树 / Flow Matching;非生产 API)
benchmark/ 基准数据集与金标准指标(含 CI 门禁脚本)
fuzz/ cargo-fuzz 靶机
doc/ 文档体系(入口 doc/README.md)
分层依赖单向向下,文档按 baseline(契约)/ ledgers(台账)/ records(流水)/
plans(方案)/ research(调研)/ archive(冻结)分类。
开发
# 基准门禁(需 numpy/pandas/scikit-learn)
路线图
权威记录在 doc/ledgers/roadmap.md:
- M4 地基修复(已完成):源码全量入 git、集成测试转绿、CI 门禁复验全绿
- M5 可用库 v0.1(已完成):公共 API 门面 ✅、端到端示例 ✅、对标三巨头 ✅、发布 crates.io 0.1.0
- M6 硬化与差异化(已完成):早停 ✅、交叉验证 ✅、特征重要度 ✅(gain/cover/frequency)、softmax 多分类 ✅(模型格式 v4)、真实基准固化进 CI 性能门禁 ✅;多分类校准与早停留远期
- 远期 / 支线(显式搁置):WASM / C ABI / codegen、PostgreSQL 插件、生产热替换、crates.io 0.2.0 发版
许可证
Apache-2.0