cuda_ml_nvforest_load_model: Load a tree ensemble with nvForest

In cuda.ml: R Interface for the RAPIDS cuML Suite of Libraries

Load a tree ensemble with nvForest

Description

Loads an XGBoost, LightGBM, or Treelite model with the current nvForest API. The model's classification or regression task is read from Treelite metadata rather than supplied separately.

Usage

cuda_ml_nvforest_load_model(
  model_file,
  model_type = NULL,
  class_levels = NULL,
  device = c("gpu", "cpu"),
  device_id = NULL,
  layout = c("depth_first", "breadth_first", "layered"),
  precision = c("native", "single", "double"),
  default_chunk_size = NULL,
  align_bytes = NULL
)

Arguments

model_file	Path to a model file.
model_type	File format, or NULL to infer it from a recognized filename suffix. See Model formats.
class_levels	Optional class labels in model-output order. When omitted, classifiers use "0", "1", and so on.
device	Inference device: "gpu" or "cpu". The default is "gpu".
device_id	GPU device identifier, or NULL for the current device.
layout	Tree layout.
precision	Native, single, or double precision.
default_chunk_size	Default prediction chunk size, or NULL to use nvForest's heuristic.
align_bytes	Memory alignment, or NULL for the device default.

Value

An nvForest model for use with predict().

Model formats

The supported model_type values are:

• "xgboost_ubj" for XGBoost UBJSON;

• "xgboost_json" for XGBoost JSON;

• "xgboost_legacy" for the legacy XGBoost binary format;

• "lightgbm" for LightGBM text models; and

• "treelite_checkpoint" for Treelite checkpoints.

When model_type = NULL, the format is inferred only from the case-insensitive filename suffix: ‘.ubj’, ‘.json’, ‘.model’, and ‘.txt’ map to "xgboost_ubj", "xgboost_json", "xgboost_legacy", and "lightgbm", respectively. Treelite checkpoints have no inferred suffix and require model_type = "treelite_checkpoint". Inference does not inspect file contents; use an explicit type when the suffix does not identify the format.

Runtime requirements

GPU inference requires the complete, roughly 1.6 GiB runtime installed by cuda_ml_install() and a supported NVIDIA GPU and driver. For CPU-only deployment, install the separate, roughly 3 MiB backend with cuda_ml_install(device = "cpu"). It does not install cuML or the complete managed CUDA and RAPIDS runtime, and it requires neither an NVIDIA GPU nor an NVIDIA driver. An existing complete backend installation can also execute nvForest models on CPU; the separate backend avoids that runtime in CPU-only environments.

Persistence

Persist nvForest models with cuda_ml_serialize() and restore them with cuda_ml_unserialize(). Current states do not record CPU or GPU placement. Select the deployment device when restoring, for example cuda_ml_unserialize(state, device = "cpu"); GPU is the default. Tree layout, chunk size, memory alignment, and GPU device identifier are likewise restore-time settings. Prediction precision is retained unless explicitly overridden. cuda.ml validates the saved state and selected backend before restoration.

To create a standard Treelite checkpoint together with the metadata needed for a complete cuda.ml round-trip, use cuda_ml_nvforest_export() and restore the pair with cuda_ml_nvforest_import().

See Also

cuda_ml_nvforest_info(), cuda_ml_nvforest_leaf_ids(), cuda_ml_nvforest_predict_per_tree(), and vignette("nvforest")

cuda.ml documentation built on Aug. 21, 2026, 9:14 a.m.