Warpgbm Mcp

WarpGBM ⚡

ニューラルネットワーク並みの速度を実現する勾配ブースティング。GPUネイティブ。分布を考慮。実運用に対応。

WarpGBM は、PyTorch とカスタム CUDA カーネルを使用し、シリコンから設計された高性能な GPU アクセラレーション対応 Gradient Boosted Decision Tree（GBDT）ライブラリです。妥協を許さないスピード重視のユーザーや研究者のために構築されています。

🎯 WarpGBM の特長

回帰と分類を統合
同じ超高速のインフラストラクチャで、連続値のターゲットにも多クラスラベルにも対応します。

不変学習（DES アルゴリズム）
変化する分布間で安定したシグナルをネイティブに学習できる、唯一のオープンソース GBDT です。Directional Era-Splitting を活用します。データは真空中に存在するわけではありません。

あらゆる処理を GPU で高速化
ビニング、ヒストグラム、分割、推論にカスタム CUDA カーネルを使用します。妥協はなく、CPU のボトルネックもありません。

Scikit-Learn 互換
そのまま置き換えられます。使い慣れた同じ API で、必要な 10 倍の速度を実現します。

---

🚀 クイックスタート

インストール

# Latest from GitHub (recommended)
pip install git+https://github.com/jefferythewind/warpgbm.git

# Stable from PyPI
pip install warpgbm

前提条件： CUDA をサポートする PyTorch（インストールガイド）

5 行で回帰

from warpgbm import WarpGBM
import numpy as np

model = WarpGBM(objective='regression', max_depth=5, n_estimators=100)
model.fit(X_train, y_train)
predictions = model.predict(X_test)

5 行で分類

from warpgbm import WarpGBM

model = WarpGBM(objective='multiclass', max_depth=5, n_estimators=50)
model.fit(X_train, y_train)  # y can be integers, strings, whatever
probabilities = model.predict_proba(X_test)
labels = model.predict(X_test)

---

🎮 機能

コアエンジン

• ⚡ ヒストグラムの構築、分割の探索、ビニング、予測に対応したGPU ネイティブの CUDA カーネル
• 🎯 複数の目的に対応：回帰、二値分類、多クラス分類
• 📊 ビニング済みデータの最適化 — データがすでに量子化されている場合、ビニングを省略できます
• 🔥 混合精度に対応 — float32 または int8 の入力
• 🎲 確率的な機能 — 正則化用の colsample_bytree

インテリジェンス

• 🧠 DES による不変学習 — 時間、レジーム、環境をまたいで汎化するシグナルを特定します
• 📈 スマートな初期化 — 分類ではクラス事前確率、回帰では平均値を使用します
• 🎯 ラベルの自動エンコーディング — 文字列、整数など、あらゆるラベルを処理します
• 🔍 特徴量の重要度 — ゲインベースの重要度と、時代ごとの独自の追跡機能

学習ユーティリティ

• ✅ 検証セットを使用した早期停止
• 📊 豊富なメトリクス：MSE、RMSLE、相関、対数損失、精度
• 🔍 損失曲線による進行状況の追跡
• 🎚️ 正則化 — 葉の L2 ペナルティ、最小分割ゲイン、最小子ノード重み
• 💾 ウォームスタートとチェックポイント — モデルの保存／読み込み、増分学習

---

⚔️ ベンチマーク

合成データ：1M 行 × 1K 特徴量（Google Colab L4 GPU）

   WarpGBM:   corr = 0.8882, train = 17.4s, infer = 3.2s  ⚡
   XGBoost:   corr = 0.8877, train = 33.2s, infer = 8.0s
  LightGBM:   corr = 0.8604, train = 29.8s, infer = 1.6s
  CatBoost:   corr = 0.8935, train = 392.1s, infer = 379.2s

XGBoost より 2 倍高速。CatBoost より 23 倍高速です。

→ ベンチマークを実行

多クラス分類：3.5K サンプル、3 クラス、50 ラウンド

Training:   2.13s
Inference:  0.37s
Accuracy:   75.3%

ニューラルネットワーク並みの速度で、実運用に対応した多クラス分類を実現します。

---

📖 例

回帰：ノート PC で LightGBM を上回る

import numpy as np
from sklearn.datasets import make_regression
from warpgbm import WarpGBM

# Generate data
X, y = make_regression(n_samples=100_000, n_features=500, random_state=42)
X, y = X.astype(np.float32), y.astype(np.float32)

# Train
model = WarpGBM(
    objective='regression',
    max_depth=5, 
    n_estimators=100, 
    learning_rate=0.01,
    num_bins=32
)
model.fit(X, y)

# Predict
preds = model.predict(X)
print(f"Correlation: {np.corrcoef(preds, y)[0,1]:.4f}")

分類：早期停止を使った多クラス分類

from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split
from warpgbm import WarpGBM

# 5-class problem
X, y = make_classification(
    n_samples=10_000, 
    n_features=50,
    n_classes=5, 
    n_informative=30
)

X_train, X_val, y_train, y_val = train_test_split(X, y, test_size=0.2)

model = WarpGBM(
    objective='multiclass',
    max_depth=6,
    n_estimators=200,
    learning_rate=0.1,
    num_bins=32
)

model.fit(
    X_train, y_train,
    X_eval=X_val, y_eval=y_val,
    eval_every_n_trees=10,
    early_stopping_rounds=5,
    eval_metric='logloss'
)

# Get probabilities or class predictions
probs = model.predict_proba(X_val)  # shape: (n_samples, n_classes)
labels = model.predict(X_val)        # class labels

不変学習：分布にロバストなシグナル

# Your data spans multiple time periods/regimes/environments
# Pass era_id to learn only signals that work across ALL eras

model = WarpGBM(
    objective='regression',
    max_depth=8,
    n_estimators=100
)

model.fit(
    X, y, 
    era_id=era_labels  # Array marking which era each sample belongs to
)

# Now your model ignores spurious correlations that don't generalize!

特徴量の重要度：モデルを理解する

from warpgbm import WarpGBM
from sklearn.datasets import load_iris

# Train a model
iris = load_iris()
X, y = iris.data, iris.target

model = WarpGBM(objective='multiclass', max_depth=5, n_estimators=100)
model.fit(X, y)

# Get feature importance (normalized)
importances = model.get_feature_importance()
for name, imp in zip(iris.feature_names, importances):
    print(f"{name}: {imp:.4f}")

# Output:
# sepal length (cm): 0.0002
# sepal width (cm): 0.0007
# petal length (cm): 0.1997
# petal width (cm): 0.7994

時代ごとの特徴量の重要度（WarpGBM 独自の機能！）

era_id を指定して学習すると、環境をまたいで安定している特徴量を確認できます。

# Train with eras
model.fit(X, y, era_id=era_labels)

# Get per-era importance: shape (n_eras, n_features)
per_era_imp = model.get_per_era_feature_importance()

# Identify invariant features (high importance across ALL eras)
invariant_features = per_era_imp.min(axis=0) > threshold

ウォームスタート：増分学習とチェックポイント

モデルを段階的に学習させ、チェックポイントを保存し、後から学習を再開できます。

from warpgbm import WarpGBM
import numpy as np

# Train 50 trees
model = WarpGBM(
    objective='regression',
    n_estimators=50,
    max_depth=5,
    learning_rate=0.1,
    warm_start=True  # Enable incremental training
)
model.fit(X, y)
predictions_50 = model.predict(X_test)

# Save checkpoint
model.save_model('checkpoint_50.pkl')

# Continue training for 50 more trees (total: 100)
model.n_estimators = 100
model.fit(X, y)  # Adds 50 trees on top of existing 50
predictions_100 = model.predict(X_test)

# Or load and continue training later
model_loaded = WarpGBM()
model_loaded.load_model('checkpoint_50.pkl')
model_loaded.warm_start = True
model_loaded.n_estimators = 100
model_loaded.fit(X, y)  # Resumes from 50 → 100 trees

ユースケース：

• ハイパーパラメーターの調整：50 本の木まで学習して評価し、100 本または 200 本が必要か判断します
• チェックポイント：長時間の学習中に進行状況を保存します
• 反復的な開発：最初から再学習せずに、木を追加します
• 実運用での更新：新しいデータが届いたら、モデルを増分学習で再学習します

ビニング済みデータ：最大速度（Numerai の例）

import pandas as pd
from numerapi import NumerAPI
from warpgbm import WarpGBM

# Download Numerai data (already quantized to integers)
napi = NumerAPI()
napi.download_dataset('v5.0/train.parquet', 'train.parquet')
train = pd.read_parquet('train.parquet')

features = [f for f in train.columns if 'feature' in f]
X = train[features].astype('int8').values
y = train['target'].values

# WarpGBM detects pre-binned data and skips binning
model = WarpGBM(max_depth=5, n_estimators=100, num_bins=20)
model.fit(X, y)  # Blazing fast!

結果：Numerai のデータで LightGBM より 13 倍高速（49 秒対 643 秒）

---

🧠 不変性学習：重要である理由

ほとんどの ML モデルは、トレーニングデータとテストデータが同じ分布から得られると仮定しています。現実を見てみましょう。実際はそうではありません。

• 株価は市場レジームによって変化します
• ユーザーの行動は時間とともに変化します
• 実験データはバッチ／施設／条件によって異なります

従来の GBDT： 目的変数と相関するシグナルなら、OOD で破綻する脆弱なパターンも含めて何でも学習します。

DES を用いた WarpGBM： 各分割がすべての環境（時代）にわたって汎化するかを明示的に検証します。頑健なシグナルだけを保持します。

アルゴリズム

候補となる分割ごとに、各時代で個別にゲインを計算します。次の条件を満たす分割のみを採用します。

1. すべての時代でゲインが正である
2. 分割の方向が時代をまたいで一貫している

これにより、一部の期間や環境でしか機能しない見せかけの相関への過学習を防ぎます。

視覚的なイメージ

左： 標準的なトレーニングではすべてのデータをまとめ、相関するシグナルなら何でも学習します。
右： 時代を考慮したトレーニングでは、すべての期間で機能するシグナルを求め、頑健な特徴量だけを学習します。

研究の基盤

• 不変リスク最小化： Arjovsky et al., 2019
• 変化させにくい説明： Parascandolo et al., 2020
• 決定木の時代分割： DeLise, 2023

---

📚 API リファレンス

コンストラクターのパラメーター

WarpGBM(
    objective='regression',        # 'regression', 'binary', or 'multiclass'
    num_bins=10,                   # Histogram bins for feature quantization
    max_depth=3,                   # Maximum tree depth
    learning_rate=0.1,             # Shrinkage rate (aka eta)
    n_estimators=100,              # Number of boosting rounds
    min_child_weight=20,           # Min sum of instance weights in child node
    min_split_gain=0.0,            # Min loss reduction to split
    L2_reg=1e-6,                   # L2 leaf regularization
    colsample_bytree=1.0,          # Feature subsample ratio per tree
    random_state=None,             # Random seed for reproducibility
    warm_start=False,              # If True, continue training from existing trees
    threads_per_block=64,          # CUDA block size (tune for your GPU)
    rows_per_thread=4,             # Rows processed per thread
    device='cuda'                  # 'cuda' or 'cpu' (GPU strongly recommended)
)

トレーニングメソッド

model.fit(
    X,                              # Features: np.array shape (n_samples, n_features)
    y,                              # Target: np.array shape (n_samples,)
    era_id=None,                    # Optional: era labels for invariant learning
    X_eval=None,                    # Optional: validation features
    y_eval=None,                    # Optional: validation targets  
    eval_every_n_trees=None,        # Eval frequency (in rounds)
    early_stopping_rounds=None,     # Stop if no improvement for N evals
    eval_metric='mse'               # 'mse', 'rmsle', 'corr', 'logloss', 'accuracy'
)

予測とユーティリティメソッド

# Regression: returns predicted values
predictions = model.predict(X)

# Classification: returns class labels (decoded)
labels = model.predict(X)

# Classification: returns class probabilities
probabilities = model.predict_proba(X)  # shape: (n_samples, n_classes)

# Feature importance: gain-based (like LightGBM/XGBoost)
importances = model.get_feature_importance(normalize=True)  # sums to 1.0
raw_gains = model.get_feature_importance(normalize=False)   # raw gain values

# Per-era importance (when era_id was used in training)
per_era_imp = model.get_per_era_feature_importance(normalize=True)  # shape: (n_eras, n_features)

# Save and load models
model.save_model('checkpoint.pkl')  # Saves all model state
model_loaded = WarpGBM()
model_loaded.load_model('checkpoint.pkl')  # Restores everything

属性

model.classes_                    # Unique class labels (classification only)
model.num_classes                 # Number of classes (classification only)
model.forest                      # Trained tree structures
model.training_loss               # Training loss history
model.eval_loss                   # Validation loss history (if eval set provided)
model.feature_importance_         # Feature importance (sum across eras)
model.per_era_feature_importance_ # Per-era feature importance (when era_id used)

---

🔧 インストールの詳細

Linux / macOS（推奨）

pip install git+https://github.com/jefferythewind/warpgbm.git

ローカルの PyTorch + CUDA 環境を使用して CUDA 拡張機能をコンパイルします。

Colab / CUDA バージョンが一致しない場合

pip install warpgbm --no-build-isolation

Windows

git clone https://github.com/jefferythewind/warpgbm.git
cd warpgbm
python setup.py bdist_wheel
pip install dist/warpgbm-*.whl

---

🎯 ユースケース

金融 ML： 市場レジームをまたいで機能するシグナルを学習
時系列： 分布シフトに対応した頑健な予測
科学研究： 実験バッチをまたいで汎化するモデル
高速推論： ミリ秒単位の SLA を持つ本番システム
Kaggle／コンペティション： GPU による高速化を活用したハイパーパラメーター調整
多クラス問題： 画像分類のフォールバック、テキスト分類、不正検知

---

🚧 ロードマップ

• マルチ GPU トレーニングのサポート
• GPU での SHAP 値計算
• 特徴量相互作用の制約
• 単調性制約
• カスタム損失関数
• 分散トレーニング
• デプロイ向け ONNX エクスポート

---

🙏 謝辞

PyTorch、scikit-learn、LightGBM、XGBoost、CUDA エコシステムの成果の上に構築されています。GBDT 研究コミュニティとすべてのコントリビューターに心から感謝します。

---

📝 バージョン履歴

v2.2.0（現行）

• 💾 増分トレーニング向けのウォームスタートをサポート（#14 をクローズ）
• 📦 チェックポイント保存用の save_model() および load_model() メソッド
• 🔄 warm_start=True を指定して、保存済みモデルからトレーニングを再開
• ✅ ウォームスタートと保存／読み込み機能を網羅する包括的なテストスイート
• 📚 ウォームスタートの例を含むドキュメントの更新

v2.1.1

• 🎲 再現性のある結果を得るための random_state パラメーター（#12 をクローズ）
• 🔧 特徴量サブサンプリング（colsample_bytree）のランダム性を制御
• ✅ 包括的な再現性テスト

v2.1.0

• 🔍 ゲインに基づく追跡と時代ごとの独自分析を備えた特徴量重要度
• 📊 get_feature_importance() および get_per_era_feature_importance() メソッド
• ✅ LightGBM との比較を含む包括的なテストスイート
• 📚 特徴量重要度の例を含むドキュメントの更新

v2.0.0

• ✨ softmax 目的関数による多クラス分類のサポート
• 🎯 二値分類モード
• 📊 新しい指標：対数損失、正解率
• 🏷️ ラベルの自動エンコード（文字列に対応）
• 🔮 確率を出力する predict_proba()
• ✅ 分類用の包括的なテストスイート
• 🔒 回帰との完全な後方互換性
• 🐛 未使用変数の問題を修正（#8）
• 🧹 未実装の L1_reg パラメーターを削除
• 📚 AGENT_GUIDE.md によるドキュメントの大幅な刷新

v1.0.0

• 🧠 Directional Era-Splitting（DES）による不変学習
• 🚀 VRAM の最適化
• 📈 Era 対応のヒストグラム計算

v0.1.26

• 🐛 予測時のメモリ関連のバグを修正
• 📊 相関評価指標を追加

v0.1.25

• 🎲 特徴量のサブサンプリング（colsample_bytree）

v0.1.23

• ⏹️ 早期停止をサポート
• ✅ 検証セットの評価

v0.1.21

• ⚡ CUDA 予測カーネル（ベクトル化された Python を置き換え）

---

📄 ライセンス

MIT ライセンス - LICENSE ファイルを参照してください

---

🤝 コントリビューション

プルリクエストを歓迎します！アーキテクチャの詳細と開発ガイドラインについては、AGENT_GUIDE.md を参照してください。

---

@jefferythewind が 🔥 を込めて開発

"より賢く学習し、より速く予測し、より高く汎化する。"