MLflow 2026: 追踪 10,000+ 实验的开源 ML 全生命周期平台 — 部署指南

# 完整的 MLflow 架构一览:
# 1. Tracking Server (REST API + UI)
#    ├── Backend Store: PostgreSQL / MySQL / SQLite
#    └── Artifact Store: S3 / GCS / Azure / Local
#
# 2. Tracking Client (Python/R/Java/REST)
#    ├── log_param(), log_metric(), log_artifact()
#    └── set_tags(), register_model()
#
# 3. Model Registry
#    ├── Model Versions (v1, v2, v3...)
#    └── Stage Transitions (None → Staging → Production)
#
# 4. Model Serving
#    └── REST endpoint: /invocations

# 安装 MLflow
pip install mlflow==2.22.0

# 使用本地文件存储启动追踪服务器
mkdir -p ~/mlflow-tracking
mlflow server \
  --backend-store-uri sqlite:///~/mlflow-tracking/mlflow.db \
  --default-artifact-root ~/mlflow-tracking/artifacts \
  --host 0.0.0.0 \
  --port 5000

# 在另一个终端中，运行你的第一个追踪实验
python -c "
import mlflow

mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('quick-start')

with mlflow.start_run():
    mlflow.log_param('learning_rate', 0.01)
    mlflow.log_param('epochs', 10)
    mlflow.log_metric('accuracy', 0.94)
    mlflow.log_metric('f1_score', 0.93)
    print(f'Run ID: {mlflow.active_run().info.run_id}')
"

# 安装数据库和云支持
pip install mlflow[extras]==2.22.0 psycopg2-binary boto3

# 使用 PostgreSQL 和 S3 启动追踪服务器
export MLFLOW_S3_ENDPOINT_URL=https://s3.amazonaws.com
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

mlflow server \
  --backend-store-uri postgresql://mlflow:password@postgres:5432/mlflowdb \
  --default-artifact-root s3://your-bucket/mlflow-artifacts \
  --host 0.0.0.0 \
  --port 5000

# docker-compose.yml — 完整的 MLflow 堆栈
version: '3.8'
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: mlflow
      POSTGRES_PASSWORD: mlflow_password
      POSTGRES_DB: mlflowdb
    volumes:
      - pgdata:/var/lib/postgresql/data

  mlflow:
    image: python:3.11-slim
    command: >
      bash -c "pip install mlflow==2.22.0 psycopg2-binary boto3 &&
               mlflow server
               --backend-store-uri postgresql://mlflow:mlflow_password@postgres:5432/mlflowdb
               --default-artifact-root s3://my-bucket/mlflow
               --host 0.0.0.0 --port 5000"
    ports:
      - "5000:5000"
    depends_on:
      - postgres

volumes:
  pgdata:

# 启动完整堆栈
docker-compose up -d

# 验证追踪服务器正在运行
curl http://localhost:5000/api/2.0/mlflow/experiments/list

# 创建 droplet 并安装 MLflow
ssh root@your-droplet-ip << 'EOF'
apt update && apt install -y python3-pip
pip install mlflow[extras]==2.22.0 psycopg2-binary

# 为 MLflow 创建 systemd 服务
cat > /etc/systemd/system/mlflow.service << 'SERVICEDEF'
[Unit]
Description=MLflow Tracking Server
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/mlflow server --backend-store-uri sqlite:///var/lib/mlflow/mlflow.db --default-artifact-root /var/lib/mlflow/artifacts --host 0.0.0.0 --port 5000
Restart=always

[Install]
WantedBy=multi-user.target
SERVICEDEF

systemctl enable mlflow && systemctl start mlflow
EOF

# tracking_example.py — 使用 MLflow 记录实验
import mlflow
import mlflow.sklearn
from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score, f1_score
import warnings
warnings.filterwarnings('ignore')

# 设置追踪服务器和实验
mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('wine-classification')

def run_experiment(n_estimators, max_depth, min_samples_split):
    with mlflow.start_run():
        # 记录参数
        mlflow.log_param('n_estimators', n_estimators)
        mlflow.log_param('max_depth', max_depth)
        mlflow.log_param('min_samples_split', min_samples_split)
        mlflow.log_param('model_type', 'RandomForest')

        # 加载数据并训练
        X, y = load_wine(return_X_y=True)
        X_train, X_test, y_train, y_test = train_test_split(
            X, y, test_size=0.2, random_state=42
        )

        clf = RandomForestClassifier(
            n_estimators=n_estimators,
            max_depth=max_depth,
            min_samples_split=min_samples_split,
            random_state=42
        )
        clf.fit(X_train, y_train)

        # 评估
        predictions = clf.predict(X_test)
        accuracy = accuracy_score(y_test, predictions)
        f1 = f1_score(y_test, predictions, average='weighted')

        # 记录指标
        mlflow.log_metric('accuracy', accuracy)
        mlflow.log_metric('f1_score', f1)

        # 记录模型
        mlflow.sklearn.log_model(
            clf,
            artifact_path='model',
            registered_model_name='wine-classifier'
        )

        print(f'Run completed: accuracy={accuracy:.4f}, f1={f1:.4f}')

# 运行多个实验
if __name__ == '__main__':
    configs = [
        (50, 5, 0.01),
        (100, 10, 0.02),
        (200, 15, 0.05),
        (300, 20, 0.10),
        (500, None, 0.02),
    ]
    for n_est, depth, min_split in configs:
        run_experiment(n_est, depth, min_split)

# 运行实验搜索
python tracking_example.py

# autolog_example.py — scikit-learn 的自动日志记录
import mlflow
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split

mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('autolog-demo')

# 启用 autologging — 捕获参数、指标、模型、制品
mlflow.sklearn.autolog()

X, y = load_wine(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

with mlflow.start_run():
    clf = RandomForestClassifier(n_estimators=100, random_state=42)
    clf.fit(X_train, y_train)
    # 无需手动记录 — autolog 自动捕获所有内容

# pytorch_tracking.py — 使用 MLflow 追踪 PyTorch 训练
import mlflow
import torch
import torch.nn as nn
from torch.utils.data import DataLoader
from torchvision import datasets, transforms

mlflow.set_tracking_uri('http://localhost:5000')
mlflow.set_experiment('pytorch-cifar10')

# 启用 PyTorch autologging
mlflow.pytorch.autolog()

def train_model(epochs, lr, batch_size):
    with mlflow.start_run():
        mlflow.log_param('epochs', epochs)
        mlflow.log_param('learning_rate', lr)
        mlflow.log_param('batch_size', batch_size)

        device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
        mlflow.log_param('device', str(device))

        # 数据加载
        transform = transforms.Compose([
            transforms.ToTensor(),
            transforms.Normalize((0.5,), (0.5,))
        ])
        train_ds = datasets.CIFAR10('./data', train=True, download=True, transform=transform)
        train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True)

        # 简单 CNN 模型
        model = nn.Sequential(
            nn.Conv2d(3, 32, 3, padding=1), nn.ReLU(), nn.MaxPool2d(2),
            nn.Conv2d(32, 64, 3, padding=1), nn.ReLU(), nn.MaxPool2d(2),
            nn.Flatten(), nn.Linear(64 * 8 * 8, 128), nn.ReLU(),
            nn.Linear(128, 10)
        ).to(device)

        optimizer = torch.optim.Adam(model.parameters(), lr=lr)
        criterion = nn.CrossEntropyLoss()

        # 训练循环
        model.train()
        for epoch in range(epochs):
            total_loss = 0
            for batch_idx, (data, target) in enumerate(train_loader):
                data, target = data.to(device), target.to(device)
                optimizer.zero_grad()
                output = model(data)
                loss = criterion(output, target)
                loss.backward()
                optimizer.step()
                total_loss += loss.item()

            avg_loss = total_loss / len(train_loader)
            mlflow.log_metric('train_loss', avg_loss, step=epoch)
            print(f'Epoch {epoch}: loss={avg_loss:.4f}')

        # 记录最终模型
        mlflow.pytorch.log_model(model, 'model')

if __name__ == '__main__':
    train_model(epochs=5, lr=0.001, batch_size=64)

# registry_example.py — 管理模型版本和阶段
import mlflow
from mlflow.tracking import MlflowClient

client = MlflowClient(tracking_uri='http://localhost:5000')
model_name = 'wine-classifier'

# 注册新的模型版本
result = mlflow.register_model(
    model_uri='runs:/<RUN_ID>/model',
    name=model_name
)
print(f'Registered version: {result.version}')

# 将版本转换为 Staging
client.transition_model_version_stage(
    name=model_name,
    version=result.version,
    stage='Staging'
)

# 添加版本描述
client.update_model_version(
    name=model_name,
    version=result.version,
    description='Wine classifier with 94.4% accuracy, RandomForest 200 estimators'
)

# 设置版本标签
client.set_model_version_tag(
    name=model_name,
    version=result.version,
    key='reviewed_by',
    value='ml-lead@company.com'
)

# 列出模型的所有版本
mlflow models list-versions -m wine-classifier

# 预期输出:
#   Version  Stage       Description
#   1        Production  Initial production model
#   2        Staging     Wine classifier with 94.4% accuracy...
#   3        None        Experimental architecture

# 加载特定模型版本进行推理
import mlflow.pyfunc

model = mlflow.pyfunc.load_model(
    model_uri='models:/wine-classifier/Production'
)

# 或通过版本号加载
model_v2 = mlflow.pyfunc.load_model(
    model_uri='models:/wine-classifier/2'
)

# 使用 MLflow 内置服务器在本地提供服务
mlflow models serve \
  -m models:/wine-classifier/Production \
  -p 5001 \
  --env-manager local

# 测试端点
curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      [14.23, 1.71, 2.43, 15.6, 127.0, 2.80, 3.06, 0.28, 2.29, 5.64, 1.04, 3.92, 1065.0],
      [12.37, 1.07, 2.10, 18.5, 88.0, 3.52, 3.75, 0.24, 1.95, 4.50, 1.04, 2.77, 660.0]
    ]
  }'

# 响应: {"predictions": [0, 1]}

# 为模型构建 Docker 镜像
mlflow models build-docker \
  -m models:/wine-classifier/Production \
  -n wine-classifier-serving:v1.0 \
  --enable-mlserver

# 运行服务容器
docker run -p 5001:8080 wine-classifier-serving:v1.0

# 测试
curl -X POST http://localhost:5001/invocations \
  -H "Content-Type: application/json" \
  -d '{"inputs": [[14.23, 1.71, 2.43, 15.6, 127.0, 2.80, 3.06, 0.28, 2.29, 5.64, 1.04, 3.92, 1065.0]]}'

# deploy_sagemaker.py — 部署到 AWS SageMaker
import mlflow.sagemaker

mlflow.sagemaker.deploy(
    app_name='wine-classifier-prod',
    model_uri='models:/wine-classifier/Production',
    execution_role_arn='arn:aws:iam::123456789:role/SageMakerRole',
    instance_type='ml.m5.large',
    region_name='us-east-1'
)

# deploy_azure.py — 部署到 Azure ML
from azureml.core import Workspace
import mlflow.azureml

ws = Workspace.from_config()
mlflow.azureml.deploy(
    model_uri='models:/wine-classifier/Production',
    workspace=ws,
    deployment_config={
        'computeType': 'aci',
        'containerResourceRequirements': {'cpu': 1, 'memoryInGB': 2}
    },
    service_name='wine-classifier-aci'
)

# auth_server.py — 带基本认证的 MLflow 服务器
from flask import Flask, request, Response
import mlflow.server
import os

app = Flask(__name__)

VALID_CREDENTIALS = {
    'data-scientist': 'secure_password_123',
    'ml-engineer': 'engineer_pass_456'
}

def check_auth():
    auth = request.authorization
    if not auth or not auth.password:
        return False
    return VALID_CREDENTIALS.get(auth.username) == auth.password

@app.before_request
def require_auth():
    if not check_auth():
        return Response('Authentication required', 401,
                       {'WWW-Authenticate': 'Basic realm="MLflow"'})

# 在认证代理后挂载 MLflow
# 或使用带基本认证的 nginx 反向代理

# nginx.conf — 带基本认证的反向代理
server {
    listen 80;
    server_name mlflow.yourcompany.com;

    location / {
        auth_basic "MLflow Tracking Server";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# cleanup.py — 删除旧运行以管理存储
from mlflow.tracking import MlflowClient
from datetime import datetime, timedelta

client = MlflowClient('http://localhost:5000')

# 查找并删除超过 90 天的运行
cutoff = datetime.now() - timedelta(days=90)
experiments = client.search_experiments()

for exp in experiments:
    runs = client.search_runs(
        experiment_ids=[exp.experiment_id],
        filter_string=f"attributes.start_time < {int(cutoff.timestamp() * 1000)}"
    )
    for run in runs:
        if run.info.status == 'FINISHED':
            client.delete_run(run.info.run_id)
            print(f'Deleted run {run.info.run_id} from {exp.name}')

print(f'Cleanup completed. Deleted {len(runs)} old runs.')

# 通过 cron 每周运行清理
crontab -e
# 添加: 0 2 * * 0 /usr/bin/python3 /opt/mlflow/cleanup.py >> /var/log/mlflow-cleanup.log 2>&1

# .github/workflows/ml-pipeline.yml
name: ML Training Pipeline
on:
  push:
    branches: [main]

jobs:
  train:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install mlflow==2.22.0 scikit-learn pandas

      - name: Train and register model
        env:
          MLFLOW_TRACKING_URI: ${{ secrets.MLFLOW_TRACKING_URI }}
        run: |
          python train.py --register-model --stage Staging

      - name: Notify team
        run: |
          echo "Model trained and registered. Review at $MLFLOW_TRACKING_URI"