Skip to content

QUICKSTART.md

Latest commit

 

History

History
307 lines (226 loc) · 6.91 KB

QUICKSTART.md

File metadata and controls

307 lines (226 loc) · 6.91 KB
Raw

MLflow Complete Tutorial - Quick Start Guide

Overview

This tutorial demonstrates all four core components of MLflow in a modular, step-by-step approach.

Prerequisites

  • Python 3.8 or higher
  • pip package manager

Installation

  1. Navigate to the project directory:

    cd /home/hammad/mlflow_complete_tutorial

  2. Install dependencies:

    pip install -r requirements.txt

Running the Tutorial

Option 1: Run All Components (Recommended for First Time)

Execute all four components in sequence:

python run_all.py

This will run:

  • Component 1: MLflow Tracking
  • Component 2: MLflow Projects
  • Component 3: MLflow Models
  • Component 4: MLflow Model Registry

Option 2: Run Individual Components

Run each component separately to explore in detail:

# Component 1: Experiment Tracking
python 1_tracking.py

# Component 2: Reproducible Projects
python 2_projects.py

# Component 3: Model Packaging
python 3_models.py

# Component 4: Model Registry
python 4_model_registry.py

Option 3: Run via MLflow Projects

Use MLflow's project execution:

# Run all components
mlflow run . -e main

# Run specific component
mlflow run . -e tracking
mlflow run . -e projects
mlflow run . -e models
mlflow run . -e registry

# Run with custom parameters
mlflow run . -e projects -P n_estimators=200 -P max_depth=10

Viewing Results

Start MLflow UI

Open a separate terminal and run:

mlflow ui

Then open your browser and visit: http://localhost:5000

What You'll See in the UI

  1. Experiments Tab: View all experiments and runs

    • Compare different runs
    • Visualize metrics over time
    • Download artifacts

  2. Models Tab: Access the Model Registry

    • View registered models
    • See model versions
    • Check model stages (Staging, Production)

Tutorial Components

Component 1: MLflow Tracking

File: 1_tracking.py

Demonstrates:

  • Creating experiments
  • Logging parameters, metrics, and tags
  • Logging artifacts (plots, models, files)
  • Nested runs for hyperparameter tuning
  • Batch logging of metrics over epochs

Duration: ~2-3 minutes

Component 2: MLflow Projects

File: 2_projects.py

Demonstrates:

  • Project structure with MLproject file
  • Parameterized runs
  • Running projects programmatically
  • Reproducible execution environments

Duration: ~3-4 minutes

Component 3: MLflow Models

File: 3_models.py

Demonstrates:

  • Saving models in different flavors (sklearn, PyTorch)
  • Model signatures and input examples
  • Loading and using saved models
  • Custom PyFunc models with preprocessing
  • Model metadata and information

Duration: ~2-3 minutes

Component 4: MLflow Model Registry

File: 4_model_registry.py

Demonstrates:

  • Registering models
  • Model versioning (v1, v2, v3)
  • Stage transitions (None → Staging → Production → Archived)
  • Model descriptions and tags
  • Loading models from registry
  • Comparing model versions
  • Model aliasing

Duration: ~2-3 minutes

Project Structure

mlflow_complete_tutorial/
├── README.md                    # Main documentation
├── QUICKSTART.md               # This file
├── requirements.txt            # Python dependencies
├── .gitignore                  # Git ignore rules
├── MLproject                   # MLflow project config
├── python_env.yaml            # Python environment spec
├── utils.py                    # Utility functions
├── data/                       # Data directory
│   └── README.md
├── 1_tracking.py              # Component 1: Tracking
├── 2_projects.py              # Component 2: Projects
├── 3_models.py                # Component 3: Models
├── 4_model_registry.py        # Component 4: Registry
└── run_all.py                 # Master script

Expected Output

After running the tutorial, you'll have:

  1. MLflow Tracking Server Data (mlruns/ directory)

    • Multiple experiments
    • Dozens of runs with logged parameters and metrics
    • Artifacts including plots and models

  2. Registered Models (visible in MLflow UI)

    • A classification model with 3 versions
    • Models in different stages (Staging, Production, Archived)
    • Model descriptions and metadata

  3. Artifacts

    • Confusion matrices
    • Feature importance plots
    • Training history visualizations
    • Classification reports
    • Saved model files

Common Commands

# Install dependencies
pip install -r requirements.txt

# Run all tutorials
python run_all.py

# Run individual tutorial
python 1_tracking.py

# Start MLflow UI
mlflow ui

# Start MLflow UI on different port
mlflow ui --port 5001

# Run MLflow project
mlflow run . -e main

# Serve a model
mlflow models serve -m runs:/<RUN_ID>/model -p 5001

Troubleshooting

Issue: MLflow UI not accessible

# Check if MLflow is installed
pip show mlflow

# Try different port
mlflow ui --port 5001

Issue: Module not found

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Issue: Permission denied for mlruns/

# Check directory permissions
ls -la mlruns/

# Create directory if missing
mkdir -p mlruns

Issue: Torch installation fails

# Install CPU-only version
pip install torch --index-url https://download.pytorch.org/whl/cpu

Learning Path

  1. Start with Component 1 (Tracking)

    • Understand basic logging concepts
    • Learn about experiments and runs
    • See how to log artifacts

  2. Move to Component 2 (Projects)

    • Learn about project structure
    • Understand parameterization
    • See reproducible execution

  3. Explore Component 3 (Models)

    • Learn model packaging
    • Understand model signatures
    • Try loading and inference

  4. Master Component 4 (Registry)

    • Learn model versioning
    • Understand lifecycle stages
    • Practice model management

Next Steps

After completing this tutorial:

  1. Modify the code:

    • Change hyperparameters
    • Try different datasets
    • Add new metrics

  2. Integrate with your projects:

    • Add MLflow tracking to existing code
    • Create MLflow projects for your workflows
    • Register your own models

  3. Explore advanced features:

    • Remote tracking server setup
    • Cloud artifact storage (S3, Azure, GCS)
    • Model deployment to production
    • CI/CD integration

  4. Read the documentation:

Getting Help

License

This tutorial is provided for educational purposes.

Happy Learning! 🚀