Treelite: Universal model exchange format for decision tree forests

Warnings

• breaking Starting from Treelite 4.0, the tree compiler and prediction runtime functionality (e.g., `treelite.Model.compile`, `treelite.Model.export_lib`, and the `treelite_runtime` module) were migrated to a separate project called TL2cgen. Older code relying on these features will break.
  Fix: Install `tl2cgen` (e.g., `pip install tl2cgen`) and replace `treelite_runtime` imports with `tl2cgen`. Replace `treelite.Model.export_lib` with `tl2cgen.export_lib`, and `treelite_runtime.Predictor`/`DMatrix` with `tl2cgen.Predictor`/`DMatrix`.
• gotcha Treelite's primary role is model exchange and serialization; it does not train decision tree models. You must use other libraries like XGBoost, LightGBM, or scikit-learn to train models before importing them into Treelite.
  Fix: Ensure you have a pre-trained model object or file from a supported ML library before attempting to use Treelite for import and deployment.
• gotcha On macOS, Treelite requires the OpenMP runtime. On Windows, Visual C++ Redistributable might be necessary for the generated shared libraries to function correctly.
  Fix: For macOS, run `brew install libomp`. For Windows, ensure Visual C++ Redistributable is installed.

Install

• pip install treelite Core library for model exchange
• pip install tl2cgen Separate library for model compilation and runtime (recommended for deployment)

Imports

• treelite

  import treelite

• treelite.frontend

  import treelite.frontend

  Contains functions like `from_xgboost`, `load_lightgbm_model` for importing external models.
• tl2cgen

  import tl2cgen

  The dedicated module for model compilation and runtime prediction (post-Treelite 4.0).
• treelite_runtime
  wrong:

  import treelite_runtime

  correct:

  import tl2cgen

  The `treelite_runtime` module was deprecated and its functionality migrated to `tl2cgen` in Treelite 4.0+. Use `tl2cgen.Predictor` and `tl2cgen.DMatrix` instead.

Quickstart

This quickstart demonstrates how to import a pre-trained XGBoost model into Treelite, compile it into a shared library using `tl2cgen`, and then use the compiled library for predictions. Note that Treelite itself does not train models.

import os
import numpy as np
import xgboost # Required to train a model to be imported
import treelite
import tl2cgen # The separate compiler and runtime library

# 1. Train a dummy XGBoost model (in a real scenario, you'd load a pre-trained model)
X = np.random.rand(100, 10).astype('float32')
y = np.random.rand(100).astype('float32')
dtrain = xgboost.DMatrix(X, label=y)
param = {'max_depth': 2, 'eta': 1, 'objective': 'reg:squarederror'}
bst = xgboost.train(param, dtrain, num_boost_round=10)

# 2. Import the XGBoost model into Treelite
model = treelite.frontend.from_xgboost(bst)

# 3. Compile the Treelite model into a shared library using TL2cgen
# Choose appropriate extension: .so for Linux, .dll for Windows, .dylib for macOS
libpath = "./predictor.so"
tl2cgen.export_lib(model, toolchain="gcc", libpath=libpath, verbose=True)

# 4. Load the compiled model with TL2cgen for prediction
predictor = tl2cgen.Predictor(libpath=libpath, verbose=True)

# 5. Make predictions
dtest = tl2cgen.DMatrix(X)
predictions = predictor.predict(dtest)

print("Predictions (first 5):", predictions[:5])

# Clean up the generated library
os.remove(libpath)