XGBoost Example

XGBoost Example

Файл: examples/xgboost/example.py. Самый полный и надёжный пример в репозитории — единственный, где корневой README и код полностью совпадают.

✅ Проверено на локальном Docker-стеке: и run_example(), и run_example_ray() отрабатывают до конца, финальная модель логируется в MLflow и реально попадает в S3 на MinIO (подтверждено напрямую через mc ls).

Данные: examples/xgboost/data/train_xgboost.csv и test_xgboost.csv (оба файла присутствуют в репозитории — пример готов к запуску "из коробки"). Конфигурация берётся из configs/settings.yaml через mlumina.core.MLuminaConfig.

Что делает скрипт

if __name__ == "__main__":
    run_example()       # локальный цикл: обучение + тюнинг без Ray
    run_example_ray()    # распределённый цикл: обучение + тюнинг через Ray

run_example() — локальный путь

1. get_config() — читает уже проинициализированный MLuminaConfig (инициализация происходит автоматически при импорте mlumina.core.config, см. страницу Getting Started в книге «Документация MLumina»).
2. xgboost_load_dataset(train_path=config.data.train_file, eval_path=config.data.eval_file, ray_data=False) — загружает xgb.DMatrix из CSV, путь к файлам берётся из configs/settings.yaml (data.train_file/data.eval_file).
3. XGBoostModel(mlflow_uri=config.cluster.mlflow_uri).train(dtrain, deval, **config.training.xgboost.model_dump()) — обучает модель с фиксированными параметрами из секции training.xgboost конфига (objective, tree_method, subsample, colsample_bytree, num_boost_round, error_func).
4. XGBoostTuningModel(...).run_optimization(dtrain, deval) — подбирает гиперпараметры локальным Optuna (диапазоны — из секции tune.xgboost конфига).
5. Переобучает модель на лучших параметрах (xgboost_tuning_model.train(...)) — отдельно от автоматического переобучения, которое run_optimization уже делает сама внутри себя при включённом MLflow.

run_example_ray() — распределённый путь

То же самое, но:

• ray.init(address=f"ray://{config.cluster.head_host}") — подключение к Ray-кластеру по адресу из конфига (cluster.head_host, например head:10001 внутри Docker-сети).
• xgboost_load_dataset(..., ray_data=True) (по умолчанию) — данные загружаются как RayDMatrix.
• XGBoostModel.train_ray(...) и XGBoostTuningModel.run_optimization_ray(...) — распределённое обучение/тюнинг через xgboost_ray и ray.tune.

Как запустить

Внутри контейнера с доступом к Ray-кластеру (например, docker compose exec head bash, либо через сервис scheduler):

python examples/xgboost/example.py

Перед запуском убедитесь, что configs/settings.yaml указывает на существующие файлы (data.train_file/data.eval_file — тип pydantic.FilePath, при отсутствии файла на диске конфигурация не проинициализируется вовсе, упадёт при импорте mlumina.core).

На что обратить внимание

• В run_example() xgboost_tuning_model.train(...) в конце вызывается на экземпляре, хотя XGBoostModel.train — @staticmethod (Python это допускает); работает корректно, просто нетипичный стиль вызова.
• При включённом mlflow_uri (он передаётся автоматически из config.cluster.mlflow_uri) run_optimization/run_optimization_ray теперь сами логируют финальную модель в MLflow — соответственно, ручное переобучение в конце run_example()/run_example_ray() частично дублирует эту работу (не ошибка, просто модель обучается дважды: один раз внутри тюнинга для лога в MLflow, второй раз — явно в самом скрипте).

Исправленный баг: XGBoostTuningModel.__init__() missing num_boost_round

Изначально оба вызова XGBoostTuningModel(...) (в run_example() и run_example_ray()) падали с

TypeError: XGBoostTuningModel.__init__() missing 1 required positional argument: 'num_boost_round'

Причина: конструктор передавал параметры через **config.tune.xgboost.model_dump(), а config.tune.xgboost (XGBoostTuneSettings) не содержит поля num_boost_round — оно есть только в config.training.xgboost (XGBoostTrainSettings). Исправлено — в оба вызова добавлен num_boost_round=config.training.xgboost.num_boost_round.

MLflow: версия клиента и сервера

Логирование модели в run_optimization/run_optimization_ray требует, чтобы версия пакета mlflow у клиента (в этом образе) и у mlflow-server совпадала — до фикса сервер был закреплён на mlflow==2.21.1 (mlflow/requirements.txt), а клиент ставился без пина и получал 3.16.1. MLflow 3.x использует новый API логирования моделей (/api/2.0/mlflow/logged-models), которого нет на сервере 2.x — mlflow.xgboost.log_model(...) падал с 404. Сервер обновлён до 3.16.1, версии синхронизированы.