🧪 MLflow Practice — практический проект

Проект для изучения MLflow на практике: от логирования экспериментов до Model Registry, Model Serving и воспроизводимых запусков. Поддерживает GPU (RTX 3090) и CPU.

📖 CODE_WALKTHROUGH.md — подробный разбор каждого файла.

---

📁 Структура

mlflow-practice/
├── MLproject              # Формат MLflow Projects (воспроизводимость)
├── python_env.yaml        # Окружение для MLproject
├── requirements.txt        # зависимости
├── setup_server.sh        # установка на GPU-сервере
├── start_ui.sh             # запуск MLflow Tracking Server
├── CODE_WALKTHROUGH.md    # экскурс по коду
├── scripts/
│   └── setup_git.sh       # настройка Git (HTTPS + токен)
└── src/
    ├── train_simple.py     # Урок 1: sklearn + Tracking (ручное)
    ├── train_gpu.py        # Урок 2: PyTorch CNN на GPU
    ├── register_model.py   # Урок 3: Model Registry
    ├── load_and_predict.py # Урок 4: загрузка + предсказание
    ├── compare_runs.py     # Урок 5: сравнение через API
    ├── autolog_demo.py     # Урок 6: autolog (автоматическое)
    ├── hyperparam_sweep.py # Урок 7: перебор гиперпараметров
    ├── serve_model.py      # Урок 8: REST API сервер
    └── grid_search_cv.py   # Урок 9: GridSearchCV + autolog

---

🚀 Быстрый старт

1. Установка

# На GPU-сервере:
bash setup_server.sh
source .venv/bin/activate

# PyTorch под CUDA:
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install flask  # для serve_model.py

2. Запуск MLflow UI (Tracking Server)

./start_ui.sh
# → http://10.0.0.7:5555

Сервер использует SQLite-бэкенд (mlflow.db). Скрипты логируют на него по HTTP (http://localhost:5555), поэтому сервер должен быть запущен и работать в отдельном терминале всё время, пока вы запускаете уроки. Иначе скрипты упадут с ConnectionError к localhost:5555. Адрес можно переопределить: export MLFLOW_TRACKING_URI=http://<host>:5555.

3. Уроки по порядку

# Урок 1 — scikit-learn (CPU, ~5 сек)
python src/train_simple.py --n-estimators 100 --max-depth 8
python src/train_simple.py --n-estimators 200 --max-depth 12
python src/train_simple.py --n-estimators 50  --max-depth 5

# Урок 2 — PyTorch CNN на 3090 (~1-2 мин)
python src/train_gpu.py --epochs 10 --batch-size 256 --lr 0.001

# Урок 3 — Регистрация лучшей модели
python src/register_model.py --experiment digits_classification

# Урок 4 — Загрузка и предсказание
python src/load_and_predict.py

# Урок 5 — Сравнение запусков
python src/compare_runs.py --experiment digits_classification --top 10

# Урок 6 — Autolog (автоматическое логирование)
python src/autolog_demo.py

# Урок 7 — Hyperparameter sweep (20 комбинаций)
python src/hyperparam_sweep.py --max-combos 20

# Урок 8 — Model serving (REST API)
python src/serve_model.py --port 5001
# → curl http://localhost:5001/predict_random

# Урок 9 — GridSearchCV + autolog (parent/child runs)
python src/grid_search_cv.py

4. MLflow Projects (воспроизводимый запуск)

mlflow run нужен установленный MLFLOW_TRACKING_URI и активированный venv (иначе: file-store maintenance mode и python: command not found).

source .venv/bin/activate
export MLFLOW_TRACKING_URI=http://localhost:5555   # сервер MLflow должен работать

# --env-manager local — использовать текущий venv (не создавать новый из python_env.yaml)
mlflow run . --env-manager local --experiment-name digits_classification \
    -P n_estimators=200 -P max_depth=12
mlflow run . --env-manager local -e gpu --experiment-name mnist_cnn_gpu \
    -P epochs=10 -P batch_size=256 -P lr=0.001
mlflow run . --env-manager local -e sweep --experiment-name sweep_digits \
    -P max_combos=30

--experiment-name теперь опционален (скрипты не конфликтуют с run'ом от mlflow run), но полезен, чтобы запуск попал в нужный эксперимент, а не в Default.

---

📚 Что изучает каждый урок

Урок	Концепция MLflow	На чём
1	Tracking: params, metrics, artifacts, tags	RandomForest (digits)
2	Tracking + GPU: логирование по эпохам, learning curves	PyTorch CNN (MNIST) на 3090
3	Model Registry: версии, стадии Staging→Production	лучшая модель из Урока 1
4	Model Loading: models:/name/stage	предсказание
5	API: search_runs, order_by	сортировка по accuracy
6	Autolog: одна строка вместо ручного логирования	GradientBoosting (wine)
7	Hyperparameter sweep: itertools + random search	20+ комбинаций RandomForest
8	GridSearchCV + autolog: parent/child runs	18 комбинаций × 5 фолдов
9	Model serving: Flask REST API	REST эндпоинты для модели

---

🖥️ RTX 3090

Параметр	Значение
VRAM	24 GB GDDR6X
Рекомендуемый batch-size	256–512 для MNIST
CUDA	12.1
MNIST 10 epochs	~1-2 минуты

Код GPU-aware — автоматически выбирает CUDA если доступна.

---

💡 Эксперименты для самостоятельной работы

1. Подбор гиперпараметров — запустите sweep с --max-combos 50
2. Сравнение моделей — обучите RandomForest vs GradientBoosting vs SVM
3. Autolog vs ручное — запустите один датасет с autolog и без, сравните
4. Model Registry — обучите несколько версий, переведите лучшую в Production
5. Serving — поднимите REST API, отправьте запрос через curl
6. MLproject — запустите через mlflow run . на другой машине