记录工件（模型、图表、文件）

全面理解和重现机器学习 (machine learning)实验运行，需要跟踪超参数 (parameter) (hyperparameter)和性能指标之外的更多内容。完整的实验跟踪需要访问运行过程中产生的所有输出。这些输出在 MLflow 中称作工件，可包含各类文件，例如训练好的模型本身、性能的可视化内容、评估报告，甚至是处理过的数据子集。

MLflow 提供简单的方法，将这些输出与你记录的参数和指标一同保存，直接关联到产生它们的具体运行。这确保了评估或重现结果所需的所有组成部分都存储在一起。

什么是工件？

可以将工件看作是你的机器学习 (machine learning)代码产生的、你希望为给定运行保存的任何文件输出。常见例子包括：

• 训练好的模型文件： 序列化的模型对象（例如，经过 pickle 序列化的 scikit-learn 模型、TensorFlow SavedModel、PyTorch .pt 文件）。
• 数据文件： 用于训练或评估的数据子集、特征重要性文件、配置文件。
• 图表和可视化内容： 图像，如混淆矩阵、ROC 曲线、学习曲线（例如，PNG、JPG、SVG 文件）。
• 报告： 总结评估结果或模型分析的文本或 HTML 文件。

记录这些工件重要的原因有几点：

• 可重现性： 保存精确的模型文件，方便他人（或未来的自己）直接加载和使用。
• 分析： 可视化内容和报告能提供比仅凭指标更全面的了解。
• 调试： 中间数据或日志有助于诊断特定运行中的问题。
• 部署： 记录的模型工件通常可以直接用于部署管道。

记录单个文件

记录工件最基本的方式是使用 mlflow.log_artifact() 函数。此函数接受一个本地文件路径，并将其副本保存到该运行的工件存储库中。

假设你已经用 Matplotlib 生成了一个图表，并将其保存到名为 confusion_matrix.png 的文件中。你可以这样记录它：

import mlflow
import matplotlib.pyplot as plt
# 假设已定义 'model'、'X_test'、'y_test'
# 并且你有一个函数 plot_confusion_matrix

# 生成并保存图表
fig, ax = plt.subplots()
# plot_confusion_matrix(model, X_test, y_test, ax=ax) # 你的绘图逻辑
ax.set_title("Confusion Matrix")
plt.savefig("confusion_matrix.png")
plt.close(fig) # 关闭图表以释放内存

# 启动 MLflow 运行（或使用现有运行）
with mlflow.start_run():
    # 照常记录参数和指标...
    mlflow.log_param("solver", "liblinear")
    mlflow.log_metric("accuracy", 0.85)

    # 将图表文件作为工件记录
    mlflow.log_artifact("confusion_matrix.png")

    print(f"运行 ID: {mlflow.active_run().info.run_id}")
    print("工件 'confusion_matrix.png' 已记录。")

此代码运行后，confusion_matrix.png 文件将被复制到该运行的工件位置（通常在本地 mlruns 目录中，或在配置的远程存储中）。你可以指定可选的 artifact_path 参数 (parameter)，以便在工件存储中的子目录中组织工件。例如，mlflow.log_artifact("confusion_matrix.png", artifact_path="plots") 会将文件放入该运行工件视图中的 plots 文件夹内。

记录目录

有时你需要记录多个文件，可能它们包含在一个目录中。例如，你可能有一个包含多个图表或配置文件的目录。与其单独记录每个文件，不如使用 mlflow.log_artifacts()（注意复数 's'）。

import mlflow
import os

# 创建一个包含一些虚拟文件的目录
os.makedirs("run_outputs", exist_ok=True)
with open("run_outputs/config.yaml", "w") as f:
    f.write("learning_rate: 0.01\n")
with open("run_outputs/feature_importances.txt", "w") as f:
    f.write("feature1: 0.8\nfeature2: 0.2\n")

# 启动 MLflow 运行
with mlflow.start_run():
    mlflow.log_param("feature_set", "v2")
    mlflow.log_metric("auc", 0.78)

    # 记录整个目录
    mlflow.log_artifacts("run_outputs", artifact_path="outputs")

    print(f"运行 ID: {mlflow.active_run().info.run_id}")
    print("目录 'run_outputs' 已记录到 'outputs'。")

# 如果需要，清理本地虚拟文件/目录
# import shutil
# shutil.rmtree("run_outputs")

此命令将本地 run_outputs 目录的整个内容记录到该运行工件存储中的 outputs 子目录。

记录机器学习 (machine learning)模型

尽管你可以使用 mlflow.log_artifact() 记录模型文件，但 MLflow 提供了专门用于记录模型的函数，这些函数提供了重要的优势。这些函数通过特定框架的“风格”（例如 mlflow.sklearn、mlflow.pytorch、mlflow.tensorflow 等）提供，它们不仅保存模型文件，还包含额外元数据：

• 序列化格式： 记录模型保存的方式（例如，pickle、ONNX、SavedModel）。
• 依赖项： 在 conda.yaml 或 requirements.txt 文件中记录所需的库版本（如 scikit-learn、pandas）。
• 输入/输出Schema（可选）： 你可以定义预期的输入数据结构和模型的输出格式，这有助于验证和部署。
• MLmodel 文件： 一个重要的元数据文件，描述模型、其风格以及如何加载和使用它。

使用这些函数使模型更独立，更容易在以后使用 MLflow 的模型服务或注册工具进行重用或部署。

这里是使用 mlflow.sklearn.log_model() 的例子：

import mlflow
import mlflow.sklearn
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.datasets import make_classification
from sklearn.metrics import accuracy_score

# 生成样本数据
X, y = make_classification(n_samples=1000, n_features=10, random_state=42)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# 训练一个简单模型
model = LogisticRegression()
model.fit(X_train, y_train)
y_pred = model.predict(X_test)
accuracy = accuracy_score(y_test, y_pred)

# 启动 MLflow 运行
with mlflow.start_run() as run:
    # 记录参数和指标
    mlflow.log_param("model_type", "LogisticRegression")
    mlflow.log_metric("accuracy", accuracy)

    # 记录 scikit-learn 模型
    # 'sk_model' 是工件存储中的目录名
    # 'registered_model_name' 是可选的，用于注册模型
    mlflow.sklearn.log_model(
        sk_model=model,
        artifact_path="sk_model",
        # input_example=X_train[:5], # 可选：记录输入 schema 示例
        # signature=mlflow.models.infer_signature(X_train, model.predict(X_train)) # 可选：记录输入/输出签名
    )

    print(f"运行 ID: {run.info.run_id}")
    print("模型已记录到工件路径 'sk_model'。")
    print(f"准确度: {accuracy:.4f}")

以这种方式记录模型时，MLflow 会在工件存储中创建一个目录（例如 sk_model），其中包含序列化模型文件（本例中为 model.pkl）、一个 conda.yaml 文件、一个 requirements.txt 文件以及 MLmodel 元数据文件。相比仅仅保存原始的 .pkl 文件，这种打包方式使得模型管理和重新部署变得显著更方便。

查看工件

工件记录后，你可以通过 MLflow UI 轻松访问它们。导航到特定运行的页面，你会找到一个“工件”部分。此部分提供一个文件浏览器界面，你可以在其中浏览目录并查看或下载记录的文件。作为工件记录的图像通常直接在 UI 中渲染，便于快速查看图表，比如前面提到的混淆矩阵示例。使用 log_model 函数记录的模型将显示 MLmodel 文件和关联的依赖文件。

这里是一个记录的图表可能被可视化的简单例子（UI 如何渲染图像）：

ROC 曲线工件的可视化示例，可能在 MLflow UI 中显示或从数据生成。

记录工件是有效实验追踪的基本组成部分。它确保你工作的重要输出（模型、图表、配置和报告）得以保存，并直接关联到产生它们的具体代码版本、参数 (parameter)和指标，大大提升你分析、重现和在此基础上进一步发展成果的能力。