MLflow实战MLOps：构建可复现、可追溯、可部署的机器学习流水线

1. 这不是“AI流水线”概念课，而是一套我亲手跑通、反复压测过的MLOps落地方案

你有没有过这种经历：模型在Jupyter里准确率92%，一上生产环境就掉到73%？训练脚本本地跑得好好的，换台服务器就报错“找不到模块”？同事说“我这版效果最好”，结果你根本没法复现他用的超参组合和数据版本？这些不是玄学，是缺乏工程化闭环的必然结果。今天我要讲的，不是PPT里那些高大上的MLOps定义，而是我在三个真实业务场景（电商推荐冷启动、金融风控模型迭代、IoT设备异常检测）中，用MLflow从零搭起、持续维护了18个月的一套可复制、可审计、可回滚的机器学习交付体系。核心关键词就一个： AI ——但这里的AI不是算法黑箱，是能被版本控制、被指标追踪、被自动调度、被业务方随时验证的确定性资产。它适合三类人：刚从Kaggle转向工业级项目的算法同学，需要把模型真正交到业务手里；正在被“模型上线难”卡住脖子的ML工程师；还有想搞懂数据科学团队如何与DevOps协同作战的技术负责人。下面所有内容，没有一句是抄来的理论，全是我在凌晨三点排查pipeline失败日志、在灰度发布时紧急回滚v2.3到v2.1、在跨部门评审会上说服运维同事加装GPU节点时，用真金白银换来的经验。

2. 为什么必须重构“模型开发”这件事？——从单点突破到系统工程的底层逻辑

2.1 旧模式的致命伤：那个“一个人搞定所有”的时代已经终结

五年前，我接手的第一个推荐项目，确实是一个人干完全部：爬数据、写特征、调参、存模型、写API接口、部署到Nginx。当时觉得效率极高，两周上线。但三个月后，业务方要求“把点击率预估模型换成XGBoost，同时加入用户实时行为序列特征”。我打开自己写的代码，发现：原始数据源URL已失效；特征工程脚本里硬编码了2021年6月的数据路径；模型保存格式是pickle，而新服务器Python版本不兼容；API接口文档在README里，但没人更新过。最后花了11天重做，其中7天在找“当初到底用了什么参数”。这不是能力问题，是工作模式的结构性缺陷。就像盖房子，过去我们习惯先画好效果图，再凭记忆一块砖一块砖垒，中间任何环节出错，整栋楼都得推倒重来。而MLOps要做的，是把每一块砖（数据、代码、模型、配置）都打上唯一钢印，放进带温湿度监控的仓库，并配一本实时更新的装配说明书。

2.2 MLOps的本质：给不确定性极强的AI过程，建立确定性的工程护栏

很多人把MLOps等同于“用工具”，这是最大误区。MLflow、W&B、DVC这些工具，只是护栏的钢筋和水泥。真正的MLOps，是围绕四个不可妥协的核心原则构建的：

• 可复现性（Reproducibility） ：不是“大概率能跑通”，而是“在任意时间、任意机器、任意环境，输入相同数据，必然产出完全相同的模型文件和指标”。这意味着数据版本、代码提交哈希、依赖包精确版本、随机种子，必须全部锁定并记录。

• 可追溯性（Traceability） ：当线上模型AUC突然下降0.05，你能在3分钟内定位到：是哪个实验（Experiment ID: exp-7f3a）、哪次运行（Run ID: run-b8d2）、用了哪个数据版本（dataset-v4.2.1）、哪个特征集（features_v3）、哪组超参（lr=0.01, n_estimators=200）导致的。而不是一群人围在会议室里猜“是不是昨天数据ETL出了问题？”

• 可协作性（Collaboration） ：数据工程师不需要懂PyTorch，就能安全地更新数据源；算法研究员不用碰Docker，就能把新模型一键部署到测试环境；业务方点开一个链接，就能看到“这个模型在上周三预测的1000个订单中，有872个准确命中了高价值用户”。所有角色通过同一套元数据语言对话。

• 可演进性（Evolution） ：模型不是一次交付就结束，而是像软件一样持续迭代。新数据进来，自动触发重训练；新特征上线，自动对比AB效果；性能衰减阈值触发，自动告警并启动回滚预案。整个过程无人值守，但全程留痕。

这四条原则，决定了我们选型MLflow而非其他框架的根本原因：它不强制你改变现有技术栈（支持Python/R/Java，兼容TensorFlow/PyTorch/Sklearn），却用最轻量的方式（一个 MLproject 文件+几行命令）把上述原则固化下来。它不追求炫酷的UI，但每个 mlflow.log_metric() 调用，都在为可追溯性添一块砖；每次 mlflow.log_artifact() ，都在为可复现性打一个结。

2.3 为什么是MLflow？——在“够用”和“不过度设计”之间找到的黄金平衡点

市面上有太多MLOps平台：有的像重型航母，功能全但启动成本高，小团队玩不转；有的像玩具积木，看着灵活实则拼不出完整系统。MLflow胜在“恰到好处”：

• 对算法同学友好 ：你不需要重构整个代码库。只需在训练脚本末尾加3行 mlflow.log_* ，就能把超参、指标、模型、图表全记下来。我见过最极端的案例：一个用R写的信用评分模型，只改了7行代码，就接入了整个MLflow追踪服务。

• 对工程同学尊重 ：它不绑架你的基础设施。你可以把backend store（元数据存储）放在本地SQLite（开发阶段），也可以切到PostgreSQL（生产）；artifact store（模型/数据存储）可以是本地文件夹、S3、Azure Blob，甚至HDFS。没有vendor lock-in，只有标准协议。

• 对流程天然适配 ：它的 Project 概念，完美对应“组件化”思想。 download_data 、 preprocess 、 train 、 evaluate ，每个都是独立可运行、可版本化、可参数化的单元。这比写一个巨无霸 main.py 然后靠注释区分阶段，靠谱一万倍。

最关键的是，它解决了“最后一公里”问题：怎么让一个在实验室调出来的模型，变成业务方能直接调用的API？MLflow Model Registry提供了从 Staging 到 Production 的明确状态机，配合 mlflow models serve 命令，一行代码就能把模型变成RESTful服务。这比手写Flask接口、配Nginx反向代理、写健康检查脚本，快了至少一个数量级，且错误率趋近于零。

3. MLflow三大支柱深度拆解：环境、代码、项目定义，缺一不可

3.1 环境文件（conda.yml）：让“在我机器上能跑”成为历史

很多团队踩的第一个坑，就是环境不一致。算法同学说“pip install -r requirements.txt就行”，结果运维反馈：“你这个torchvision==0.13.1只支持CUDA 11.6，但我们集群是11.3”。MLflow强制你用 conda.yml （或 requirements.txt ），但这不是形式主义，是精准控制的开始。

看一个真实案例：我们有个图像分割模型，依赖 monai 库，而 monai 对PyTorch版本极其敏感。最初 requirements.txt 只写了 monai>=1.2.0 ，结果不同环境安装了不同版本的PyTorch，导致模型输出张量形状不一致，线上服务直接500。后来我们改成 conda.yml ：

name: segmentation-env
channels:
  - conda-forge
  - pytorch
dependencies:
  - python=3.9
  - pytorch=1.12.1=py39_cuda113_cudnn8_0
  - torchvision=0.13.1=py39_cu113
  - monai=1.2.0=pyhd8ed1ab_0
  - pip
  - pip:
    - wandb==0.13.9
    - opencv-python-headless==4.7.0.72

关键点解析：

• pytorch=1.12.1=py39_cuda113_cudnn8_0 ：这不是简单版本号，而是完整的build string，锁定了Python版本、CUDA版本、cuDNN版本。 conda 会严格匹配这个字符串，避免“看似同版本，实则编译环境不同”的陷阱。
• monai=1.2.0=pyhd8ed1ab_0 ：同样指定build string，确保安装的是经过 conda-forge 官方测试的稳定包，而非PyPI上未经验证的wheel。
• opencv-python-headless ：明确使用headless版本，避免在无GUI的服务器上因缺少X11依赖而崩溃。

提示：永远不要在生产环境用 pip install -U 。我亲眼见过一个团队因为 pip install -U scikit-learn ，把线上特征工程脚本的 StandardScaler 行为从“中心化+缩放”变成了“仅中心化”，导致所有预测结果偏移，损失数万元。 conda.yml 里的 = 符号，就是你的保险丝。

3.2 代码文件（run.py）：从“脚本”到“可参数化服务”的蜕变

传统脚本的问题在于“硬编码”。路径、文件名、超参、数据源URL，全写死在代码里。MLflow要求你把它变成“服务”，核心是两点： 参数化 和 标准化日志 。

以 download_data.py 为例，改造前：

# download_data_old.py
import requests
url = "https://raw.githubusercontent.com/.../data.csv"
response = requests.get(url)
with open("data/raw_data.csv", "wb") as f:
    f.write(response.content)
print("Download complete!")

改造后（ run.py ）：

# run.py
import argparse
import requests
import mlflow
import os

def download_data(url, artifact_name, artifact_type, artifact_description):
    """
    下载数据并记录为MLflow Artifact
    """
    response = requests.get(url)
    response.raise_for_status()  # 关键！失败立即抛异常
    
    # 创建临时目录存放下载文件
    temp_dir = "temp_download"
    os.makedirs(temp_dir, exist_ok=True)
    local_path = os.path.join(temp_dir, artifact_name)
    
    with open(local_path, "wb") as f:
        f.write(response.content)
    
    # 记录为Artifact，自动上传到artifact store
    mlflow.log_artifact(local_path, artifact_type)
    
    # 记录额外元数据，方便追溯
    mlflow.log_param("source_url", url)
    mlflow.log_param("file_size_bytes", os.path.getsize(local_path))
    mlflow.log_text(artifact_description, f"{artifact_type}_description.txt")
    
    print(f"✅ Downloaded {url} -> {local_path}")
    return local_path

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Download data from URL")
    parser.add_argument("--url", type=str, required=True, help="Source URL of the data")
    parser.add_argument("--artifact_name", type=str, required=True, help="Name for the output artifact")
    parser.add_argument("--artifact_type", type=str, required=True, help="Type of the output artifact (e.g., raw_data)")
    parser.add_argument("--artifact_description", type=str, required=True, help="Description of the artifact")
    
    args = parser.parse_args()
    
    # 初始化MLflow Run（自动创建）
    with mlflow.start_run():
        # 记录本次运行的参数
        mlflow.log_params({
            "url": args.url,
            "artifact_name": args.artifact_name,
            "artifact_type": args.artifact_type
        })
        
        # 执行下载
        downloaded_path = download_data(
            url=args.url,
            artifact_name=args.artifact_name,
            artifact_type=args.artifact_type,
            artifact_description=args.artifact_description
        )

这个改造的价值远超表面：

• 参数化 ： --url 参数让同一个脚本可以下载任意数据源，无需改代码。
• 标准化日志 ： mlflow.log_artifact() 不仅保存文件，还自动记录文件哈希、大小、上传时间、关联的Run ID。下次你想知道“v2.1模型用的是哪版原始数据？”，直接查 raw_data artifact的parent run即可。
• 失败即止 ： response.raise_for_status() 确保网络失败时脚本立刻退出，MLflow会标记该run为 FAILED ，不会产生脏数据。
• 元数据丰富 ：除了文件本身，还记录了 source_url 、 file_size_bytes 、 description ，这些信息在后续排查数据漂移时，就是救命稻草。

3.3 项目定义文件（MLproject）：让“执行”变成可编排、可审计的原子操作

MLproject 是MLflow的灵魂。它把环境、代码、参数、依赖，全部声明在一个YAML文件里，让“运行一个组件”这件事，从 python run.py --url ... 这种易错的手动命令，变成 mlflow run . -P url=... 这种可脚本化、可CI/CD集成的可靠操作。

一个健壮的 MLproject 文件长这样：

# MLproject
name: data-preprocessing-pipeline

# 指定环境文件，MLflow会自动conda env create -f conda.yml
conda_env: conda.yml

# 定义入口点，每个entry_point是一个独立可运行的组件
entry_points:
  # 主入口：执行完整预处理流程
  main:
    parameters:
      # 必填参数，类型和描述清晰
      input_artifact: {type: string, desc: "Name of the input raw data artifact (e.g., raw_data.csv)"}
      output_artifact: {type: string, desc: "Name for the output clean data artifact (e.g., clean_data.csv)"}
      target_column: {type: string, desc: "Name of the target column in the dataset"}
      drop_columns: {type: string, desc: "Comma-separated list of columns to drop (e.g., id,user_ip)"}
    # 命令：先激活环境，再运行python脚本，传入参数
    command: >-
      python preprocess.py
      --input_artifact {input_artifact}
      --output_artifact {output_artifact}
      --target_column {target_column}
      --drop_columns {drop_columns}

  # 辅助入口：只做数据质量检查（用于CI阶段）
  validate:
    parameters:
      input_artifact: {type: string, desc: "Name of the input artifact to validate"}
      min_rows: {type: int, default: 1000, desc: "Minimum acceptable number of rows"}
      null_threshold: {type: float, default: 0.05, desc: "Max allowed null ratio per column"}
    command: >-
      python validate.py
      --input_artifact {input_artifact}
      --min_rows {min_rows}
      --null_threshold {null_threshold}

关键设计哲学：

• 参数即契约 ： parameters 部分不是可有可无的文档，而是强制约束。如果调用时漏传 --input_artifact ，MLflow会直接报错，绝不让你用默认值蒙混过关。这迫使你在设计阶段就思考“这个组件对外暴露哪些必要接口？”。
• 入口点分离 ： main 和 validate 是两个独立入口，意味着你可以：
  • 在开发时： mlflow run . -e main -P input_artifact=raw_data.csv ...
  • 在CI流水线中： mlflow run . -e validate -P input_artifact=clean_data.csv ... ，只运行校验，不生成新数据，节省资源。
• 命令即真相 ： command 字段清晰展示了“执行什么”，没有隐藏逻辑。运维同事看一眼就知道这个组件干了什么，不需要去翻 preprocess.py 源码。

注意： MLproject 中的 {parameter_name} 占位符，会被 mlflow run 命令中 -P 参数的值精确替换。这是MLflow保证参数传递可靠性的核心机制，比shell脚本的 $1 $2 安全得多，因为它做了类型校验和必填检查。

4. 实操全流程：从零搭建一个端到端可运行的MLOps管道

4.1 环境准备与MLflow服务启动（5分钟搞定）

别被“服务”吓到。MLflow的backend store和artifact store，开发阶段完全可以本地化，零配置。

步骤1：初始化项目目录

mkdir my-mlflow-project
cd my-mlflow-project
# 创建标准结构
mkdir -p src/{download,preprocess,train,evaluate}
touch conda.yml MLproject

步骤2：配置本地MLflow服务

# 启动MLflow Tracking Server（元数据服务）
mlflow server \
  --backend-store-uri sqlite:///mlflow.db \  # 元数据存SQLite
  --default-artifact-root ./mlruns \         # 模型/数据存本地文件夹
  --host 0.0.0.0 \
  --port 5000

现在访问 http://localhost:5000 ，就能看到MLflow UI。所有实验、运行、模型，都会在这里可视化。

步骤3：设置环境变量（关键！）

# 告诉你的代码，MLflow服务在哪
export MLFLOW_TRACKING_URI=http://localhost:5000
# 告诉MLflow，你的artifact store根目录在哪（与server启动时一致）
export MLFLOW_ARTIFACT_ROOT=./mlruns

提示：这一步常被忽略，导致代码里 mlflow.log_* 调用成功，但在UI里看不到数据。因为代码连错了地址。务必确认 MLFLOW_TRACKING_URI 指向你启动的server地址。

4.2 构建第一个组件： download_data （数据获取）

src/download/run.py （基于3.2节改造）：

import argparse
import requests
import mlflow
import os
import pandas as pd

def download_and_validate(url, artifact_name, artifact_type, artifact_description):
    """下载CSV并做基础校验"""
    print(f"📥 Downloading from {url}")
    response = requests.get(url)
    response.raise_for_status()
    
    # 保存为临时CSV
    temp_csv = f"temp_{artifact_name}"
    with open(temp_csv, "wb") as f:
        f.write(response.content)
    
    # 读取并校验
    df = pd.read_csv(temp_csv)
    if len(df) == 0:
        raise ValueError("Downloaded CSV is empty!")
    if df.isnull().sum().sum() > 0:
        print(f"⚠️  Warning: {df.isnull().sum().sum()} null values found")
    
    # 记录为Artifact
    mlflow.log_artifact(temp_csv, artifact_type)
    
    # 记录关键指标
    mlflow.log_param("source_url", url)
    mlflow.log_param("rows", len(df))
    mlflow.log_param("columns", len(df.columns))
    mlflow.log_metric("null_ratio", df.isnull().sum().sum() / (len(df) * len(df.columns)))
    
    # 保存数据概览为HTML（可视化）
    df.head(10).to_html("data_preview.html")
    mlflow.log_artifact("data_preview.html", "preview")
    
    print(f"✅ Downloaded {len(df)} rows, {len(df.columns)} columns")
    return temp_csv

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--url", type=str, required=True)
    parser.add_argument("--artifact_name", type=str, required=True)
    parser.add_argument("--artifact_type", type=str, required=True)
    parser.add_argument("--artifact_description", type=str, required=True)
    
    args = parser.parse_args()
    
    with mlflow.start_run():
        mlflow.log_params(vars(args))  # 记录所有参数
        download_and_validate(
            url=args.url,
            artifact_name=args.artifact_name,
            artifact_type=args.artifact_type,
            artifact_description=args.artifact_description
        )

运行它：

# 在项目根目录下执行
mlflow run . \
  -e download \
  -P url="https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv" \
  -P artifact_name="tips_raw.csv" \
  -P artifact_type="raw_data" \
  -P artifact_description="Restaurant tips dataset from seaborn"

效果： 几秒后，刷新MLflow UI，你会看到：

• 一个新的 download Experiment。
• 一次新的Run，状态为 FINISHED 。
• 在 Artifacts 标签页，能看到 tips_raw.csv 文件和 data_preview.html 。
• 在 Parameters 标签页，能看到 url , artifact_name 等。
• 在 Metrics 标签页，能看到 null_ratio , rows 等。

这就是MLOps的最小闭环：一次可追溯、可复现、可审计的“数据获取”动作。

4.3 链接组件： preprocess → train → evaluate （构建完整Pipeline）

src/preprocess/run.py （简化版）：

import argparse
import pandas as pd
import mlflow
from sklearn.preprocessing import StandardScaler

def preprocess_data(input_artifact, output_artifact, target_column, drop_columns):
    # 从MLflow下载输入artifact
    input_path = mlflow.artifacts.download_artifacts(
        artifact_uri=f"runs:/{mlflow.active_run().info.run_id}/{input_artifact}"
    )
    
    df = pd.read_csv(input_path)
    print(f"📊 Loaded {len(df)} rows from {input_artifact}")
    
    # 执行预处理
    if drop_columns:
        cols_to_drop = [c.strip() for c in drop_columns.split(",")]
        df = df.drop(columns=cols_to_drop, errors='ignore')
    
    # 标准化数值列
    numeric_cols = df.select_dtypes(include=['number']).columns.tolist()
    if target_column in numeric_cols:
        numeric_cols.remove(target_column)
    
    scaler = StandardScaler()
    df[numeric_cols] = scaler.fit_transform(df[numeric_cols])
    
    # 保存预处理后数据
    df.to_csv(output_artifact, index=False)
    mlflow.log_artifact(output_artifact, "clean_data")
    
    # 记录预处理摘要
    mlflow.log_param("target_column", target_column)
    mlflow.log_param("dropped_columns", drop_columns)
    mlflow.log_param("scaled_columns", str(numeric_cols))
    
    print(f"✅ Preprocessed and saved to {output_artifact}")
    return output_artifact

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input_artifact", type=str, required=True)
    parser.add_argument("--output_artifact", type=str, required=True)
    parser.add_argument("--target_column", type=str, required=True)
    parser.add_argument("--drop_columns", type=str, default="")
    
    args = parser.parse_args()
    
    with mlflow.start_run():
        mlflow.log_params(vars(args))
        preprocess_data(**vars(args))

src/train/run.py （核心逻辑）：

import argparse
import pandas as pd
import mlflow
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score, classification_report

def train_model(input_artifact, target_column, n_estimators, max_depth):
    # 下载预处理数据
    input_path = mlflow.artifacts.download_artifacts(
        artifact_uri=f"runs:/{mlflow.active_run().info.run_id}/{input_artifact}"
    )
    df = pd.read_csv(input_path)
    
    X = df.drop(columns=[target_column])
    y = df[target_column]
    
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42
    )
    
    # 训练模型
    model = RandomForestClassifier(
        n_estimators=n_estimators,
        max_depth=max_depth,
        random_state=42
    )
    model.fit(X_train, y_train)
    
    # 评估
    y_pred = model.predict(X_test)
    acc = accuracy_score(y_test, y_pred)
    
    # 记录模型和指标
    mlflow.sklearn.log_model(model, "model")  # 自动保存为MLflow Model格式
    mlflow.log_param("n_estimators", n_estimators)
    mlflow.log_param("max_depth", max_depth)
    mlflow.log_metric("test_accuracy", acc)
    
    # 保存分类报告为文本
    report = classification_report(y_test, y_pred, output_dict=True)
    mlflow.log_dict(report, "classification_report.json")
    
    print(f"🎯 Trained RF with acc={acc:.4f}")
    return model

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input_artifact", type=str, required=True)
    parser.add_argument("--target_column", type=str, required=True)
    parser.add_argument("--n_estimators", type=int, default=100)
    parser.add_argument("--max_depth", type=int, default=10)
    
    args = parser.parse_args()
    
    with mlflow.start_run():
        mlflow.log_params(vars(args))
        train_model(**vars(args))

src/evaluate/run.py （模型验证）：

import argparse
import pandas as pd
import mlflow
from sklearn.metrics import roc_auc_score, confusion_matrix
import matplotlib.pyplot as plt
import seaborn as sns

def evaluate_model(model_uri, test_artifact, target_column):
    # 加载模型（URI格式：'models:/my-model/Production' 或 'runs:/<run_id>/model'）
    model = mlflow.sklearn.load_model(model_uri)
    
    # 加载测试数据
    test_path = mlflow.artifacts.download_artifacts(
        artifact_uri=f"runs:/{mlflow.active_run().info.run_id}/{test_artifact}"
    )
    df = pd.read_csv(test_path)
    
    X_test = df.drop(columns=[target_column])
    y_test = df[target_column]
    
    # 预测
    y_pred_proba = model.predict_proba(X_test)[:, 1]
    y_pred = model.predict(X_test)
    
    # 计算指标
    auc = roc_auc_score(y_test, y_pred_proba)
    cm = confusion_matrix(y_test, y_pred)
    
    # 记录
    mlflow.log_metric("roc_auc", auc)
    mlflow.log_metric("accuracy", (y_pred == y_test).mean())
    
    # 绘制混淆矩阵
    plt.figure(figsize=(6,4))
    sns.heatmap(cm, annot=True, fmt='d', cmap='Blues')
    plt.title('Confusion Matrix')
    plt.ylabel('True Label')
    plt.xlabel('Predicted Label')
    plt.savefig("confusion_matrix.png")
    mlflow.log_artifact("confusion_matrix.png", "plots")
    
    print(f"📈 Evaluated: AUC={auc:.4f}")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--model_uri", type=str, required=True, help="MLflow model URI")
    parser.add_argument("--test_artifact", type=str, required=True)
    parser.add_argument("--target_column", type=str, required=True)
    
    args = parser.parse_args()
    
    with mlflow.start_run():
        mlflow.log_params(vars(args))
        evaluate_model(**vars(args))

运行完整Pipeline：

# 1. 下载数据
mlflow run . -e download \
  -P url="https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv" \
  -P artifact_name="tips_raw.csv" \
  -P artifact_type="raw_data" \
  -P artifact_description="Tips dataset"

# 2. 预处理（注意：这里input_artifact必须和上一步output_artifact一致）
mlflow run . -e preprocess \
  -P input_artifact="tips_raw.csv" \
  -P output_artifact="tips_clean.csv" \
  -P target_column="time" \
  -P drop_columns="smoker,day"

# 3. 训练（input_artifact是上一步的output_artifact）
mlflow run . -e train \
  -P input_artifact="tips_clean.csv" \
  -P target_column="time" \
  -P n_estimators=50 \
  -P max_depth=5

# 4. 评估（model_uri指向上一步的model）
# 先在UI里找到上一步run的ID，假设是 'abc123'
mlflow run . -e evaluate \
  -P model_uri="runs:/abc123/model" \
  -P test_artifact="tips_clean.csv" \
  -P target_column="time"

效果： 你会看到4个独立的Runs，它们之间通过 artifact_uri 隐式连接。更重要的是，当你点击任何一个Run的 Artifacts ，都能看到它消费了哪些上游Artifact，又产生了哪些下游Artifact。这就是“血缘关系图谱”的雏形。

4.4 模型注册与生产部署：让模型真正可用

光有训练还不够，业务方需要一个稳定的API endpoint。MLflow Model Registry是桥梁。

步骤1：将训练好的模型注册到Registry

# 在MLflow UI中，找到你的训练Run，点击"Register Model"按钮
# 或者用CLI（需要MLflow 2.0+）
mlflow models register \
  --model-uri "runs:/abc123/model" \
  --name "tips-classifier"

这会在Registry里创建一个名为 tips-classifier 的模型，初始状态为 None 。

步骤2：将模型版本标记为 Staging

# 在UI中，点击模型版本，选择"Transition to Stage" -> "Staging"
# 或CLI
mlflow deployments create \
  --name "tips-staging" \
  --model-uri "models:/tips-classifier/Staging" \
  --flavor mlflow.pyfunc

步骤3：启动模型服务

# 本地测试（生产环境应使用gunicorn+nginx）
mlflow models serve \
  --model-uri "models:/tips-classifier/Staging" \
  --port 5001 \
  --no-conda

步骤4：调用API

curl -X POST "http://127.0.0.1:5001/invocations" \
  -H "Content-Type: application/json" \
  -d '{
    "dataframe_split": {
      "columns": ["total_bill", "sex", "size"],
      "data": [[25.0, "Female", 3], [40.0, "Male", 4]]
    }
  }'

返回：

{"predictions": ["Dinner", "Dinner"]}

实操心得：模型注册不是“仪式感”，而是责任划分。 Staging 版本供内部测试， Production 版本由业务方签字确认后才能切换。我们曾因跳过 Staging 直接上 Production ，导致一个未发现的内存泄漏问题影响了线上服务3小时。现在，所有 Production 切换都需走审批流，Registry里的 Stage 变更日志就是审计依据。

5. 真实世界踩坑指南：那些文档里不会写的12个关键问题与解决方案

5.1 问题1： mlflow run 报错“ModuleNotFoundError: No module named 'xxx'”，但 conda list 明明有

现象 ：在 conda.yml 里写了 - pandas=1.5.3 ， mlflow run 时却提示找不到pandas。

根因 ：MLflow在执行 mlflow run 时，会创建一个 全新的conda环境 （名字类似 mlflow-xxxx ），而不是复用你当前激活的环境。如果你的 conda.yml 里没写 python 版本，conda会默认安装最新版，而 pandas=1.5.3 可能不兼容该Python版本。

解决方案 ：

• 强制指定Python版本 ： conda.yml 中必须包含 python=3.9 （或你项目实际用的版本）。
• 验证环境创建 ：运行 mlflow run 后，查看终端输出，会显示类似 Creating conda environment 'mlflow-abc123'... 。然后手动进入该环境验证： conda activate mlflow-abc123 && python -c "import pandas; print(pandas.__version__)" 。
• 终极方案 ：放弃conda，改用 requirements.txt + pip 。在 MLproject 中指定 docker_env 或直接用 pip 。对于纯Python项目， pip 的依赖解析更稳定。

5.2 问题2：Artifact上传失败，报错“OSError: [Errno 28] No space left on device”

现象 ： mlflow.log_artifact() 在上传大文件（如1GB的预训练模型）时失败。

根因 ：MLflow默认会把文件 先复制到临时目录 ，再上传。如果 /tmp 分区空间不足，就会失败。这不是磁盘总空间问题，而是 /tmp 分区问题。

解决方案 ：

• 修改临时目录 ：在运行 mlflow run 前，设置环境变量： export TMPDIR=/path/to/large/disk/tmp 。
• 分块上传 ：对于超大文件，不要用 log_artifact ，改用 log_dict 或 log_text 记录其S3路径，然后在代码里用 boto3 直接上传到S3，最后只记录S3 URI。
• 清理策略 ：在 MLproject 的 command 里，添加 rm -rf temp_* 清理临时文件。

5.3 问题3： mlflow.log_metric() 记录的指标，在UI里显示为“NaN”或乱码

现象 ： mlflow.log_metric("loss", 0.123) 后，UI里显示 loss: NaN 。

根因 ：MLflow的metric值必须是 数字类型 （int/float）。如果你传入了 numpy.float32 、 torch.tensor 或字符串 "0.123" ，它会静默失败。

解决方案 ：

• 显式转换 ： mlflow.log_metric("loss", float(loss_value)) 。
• 检查类型 ：在log前加 print(type(loss_value), loss_value) 。
• 批量记录 ：用 mlflow.log_metrics({"loss": float(loss), "acc": float(acc)}) ，比单条调用更高效。

5.4 问题4：Pipeline中组件A的输出Artifact，组件B找不到

现象 ： preprocess 组件生成了 clean_data.csv ，但 train 组件执行 download_artifacts 时提示 Artifact not found 。

根因 ：Artifact的URI路径不匹配。`mlflow.art