Ray Train: LightGBMTrainer¶
A LightGBMTrainer runs a gradient-boosted tree training loop on a Ray Dataset shard.
When to use it. Tabular models with LightGBM that need more data or more workers than one process handles.
The picture below is the graph drawn in Eugo's visual Ray builder, and the cell under Generated code is the Ray code the builder produced from it. The code is plain Ray: it runs without the builder.
Back to the gallery · Tested with Ray 2.55.1

The graph in Eugo's visual Ray builder.
The trainer type (LightGBM here) is a setting of the Trainer node, so the canvas looks the same for Torch, LightGBM and XGBoost.
Setup¶
Start a local Ray instance. The options keep the notebook quiet: no dashboard, and worker logs stay out of the notebook. Ray is capped at four CPUs so the example behaves the same on any machine. The generated code below only calls ray.init() when Ray is not running yet, so it reuses this instance.
import ray
ray.init(include_dashboard=False, log_to_driver=False, logging_level="ERROR", num_cpus=4)
RayContext(dashboard_url='', python_version='3.12.3', ray_version='2.55.1', ray_commit='237c2455ebb1ea15a32dd9e1fdeb2d617badc37f')
User functions¶
The nodes in the graph call these ordinary Python functions and classes. In the builder you write them in a normal notebook cell, and the generated code refers to them by name.
import os
import tempfile
import lightgbm
import ray
def train_loop():
# Runs on every training worker. Learns label = id > 3 from the id column.
df = ray.train.get_dataset_shard("train").materialize().to_pandas()
train_set = lightgbm.Dataset(df[["id"]], label=(df["id"] > 3).astype(int))
booster = lightgbm.train(
{"objective": "binary", "min_data_in_leaf": 1, "verbose": -1},
train_set,
num_boost_round=5,
)
with tempfile.TemporaryDirectory() as tmp:
booster.save_model(os.path.join(tmp, "model.txt"))
ray.train.report(
{"rows": len(df), "trees": booster.num_trees()},
checkpoint=ray.train.Checkpoint.from_directory(tmp),
)
Generated code¶
This is the cell the visual builder generated from the graph above.
# Generated with Eugo's visual Ray builder
import ray
from ray.train import ScalingConfig
from ray.train.lightgbm import LightGBMTrainer
if not ray.is_initialized():
ray.init()
ds = ray.data.range(8)
_trainer_n2 = LightGBMTrainer(train_loop, scaling_config=ScalingConfig(num_workers=1, use_gpu=False), datasets={"train": ds})
result = _trainer_n2.fit()
Check the result¶
The cell below checks that the generated code did what the graph describes.
import os
assert result.error is None, result.error
assert result.metrics["rows"] == 8 and result.metrics["trees"] == 5, result.metrics
print("metrics:", result.metrics)
print("checkpoint saved:", os.path.basename(result.checkpoint.path))
metrics: {'rows': 8, 'trees': 5}
checkpoint saved: checkpoint_2026-11-07_20-30-24.999392
How the graph maps to the code¶
Each step names a node in the picture by its label, the lines of the generated cell it produced, and what those lines do. Node ids such as n1 are not drawn on the canvas. Where the builder names a variable after a node, the id is its suffix (for example _trainer_n2).
Setup (lines 1, 3–5 and 7–8)
# Generated with Eugo's visual Ray builder
...
import ray
from ray.train import ScalingConfig
from ray.train.lightgbm import LightGBMTrainer
...
if not ray.is_initialized():
ray.init()
The first line marks the cell as generated. The builder then adds an import for every Ray API the graph uses and a guarded ray.init(), so re-running the cell reuses the running cluster.
Source (node n1, line 10)
ds = ray.data.range(8)
An eight-row dataset fed in as the "train" split.
Trainer (node n2, lines 12–13)
_trainer_n2 = LightGBMTrainer(train_loop, scaling_config=ScalingConfig(num_workers=1, use_gpu=False), datasets={"train": ds})
result = _trainer_n2.fit()
LightGBMTrainer(train_loop, scaling_config=ScalingConfig(num_workers=1, use_gpu=False), datasets=...) runs the loop on the worker group and returns a Result.
Clean up¶
Shut down Ray, so the next notebook starts fresh.
ray.shutdown()