这篇说说如何在 Notebook 中通过 MLflow API 记录这三类信息，并在实验详情页查看记录结果。
一、前提条件
在开始记录前，请确保：
·已创建目标实验（参见 创建实验），并获取实验 ID 或实验名称。
·当前账号在该实验上拥有编辑或管理权限。
·已在 Notebook 中安装 MLflow 客户端（DataBuddy 默认环境已预置 MLflow，无需额外安装）。
MLflow 协议中可记录的三类信息为：参数（Parameter）、指标（Metric）、工件（Artifact）。各类型的含义与典型示例请参见 什么是模型实验 > 关键概念。
二、记录方式选择
DataBuddy 支持两种记录方式，可按场景灵活选择：
| 方式 | 适用场景 |
| 自动记录 | 使用 sklearn / xgboost / lightgbm / pytorch / tensorflow 等主流框架，无需手写 log_*，框架训练时自动捕获参数、指标与模型 |
| 手动记录 | 自定义训练流程；需要记录非框架默认捕获的指标，完全控制记录时机与内容 |
三、自动记录
在 mlflow.start_run() 之前调用 mlflow.autolog()，框架训练时会自动捕获参数、指标、模型与训练数据集：
import mlflowfrom sklearn.datasets import load_diabetesfrom sklearn.ensemble import RandomForestRegressorfrom sklearn.model_selection import train_test_splitmlflow.set_experiment(experiment_id="3")mlflow.autolog() # 自动记录with mlflow.start_run(): db = load_diabetes() X_train, X_test, y_train, y_test = train_test_split(db.data, db.target) rf = RandomForestRegressor(n_estimators=100, max_depth=6) rf.fit(X_train, y_train) # 参数（n_estimators、max_depth）、训练指标、模型工件均自动记录
注意：说明：
注意：Autologging 是注册模型的推荐方式之一：自动记录的模型默认携带签名（Signature），可直接用于 Catalog 注册。模型签名是注册模型的强制前置条件。
四、1.手动记录参数
在 with mlflow.start_run() 上下文中调用 mlflow.log_param：
import mlflowwith mlflow.start_run(run_name="manual_run"): # 单个参数 mlflow.log_param("learning_rate", 0.01) mlflow.log_param("batch_size", 64) mlflow.log_param("optimizer", "Adam") # 批量记录 mlflow.log_params({ "n_estimators": 100, "max_depth": 6, "max_features": 3, })
取值约束 ：
·key 为字符串，最大长度由 MLflow 协议规定。
·value 类型可以是字符串、整数或浮点数。
·同一 Run 内同名参数 只能记录一次 ，重复记录会报错。
五、2.手动记录指标
在 with mlflow.start_run() 上下文中调用 mlflow.log_metric，可指定 step 用于绘制曲线：
import mlflowwith mlflow.start_run(run_name="manual_run"): # 单个指标 mlflow.log_metric("accuracy", 0.92) mlflow.log_metric("auc", 0.88) # 训练过程中按 epoch 记录损失 for epoch in range(100): loss = train_one_epoch(…) mlflow.log_metric("loss", loss, step=epoch) # 批量记录 mlflow.log_metrics({ "precision": 0.91, "recall": 0.89, "f1": 0.90, })
注意：说明：
六、3.手动记录工件（Artifact）
工件包括序列化的模型、日志、配置、图片等任意文件。记录方式分为两类：
1. 记录通用工件文件
import mlflowwith mlflow.start_run(): # 记录单个文件 mlflow.log_artifact("output/eval_report.html") # 记录到子目录 mlflow.log_artifact("config/params.yaml", artifact_path="configs") # 记录整个目录 mlflow.log_artifacts("output/figures", artifact_path="figures")
2. 记录模型工件
不同 ML 框架使用对应的 log_model 方法。常用示例：
# scikit-learnmlflow.sklearn.log_model( sk_model=model, name="sklearn-model", input_example=X_train, # 提供输入样例，自动生成签名)# PyTorchmlflow.pytorch.log_model(model, "model")# 自定义 Python 模型mlflow.pyfunc.log_model(artifact_path="model", python_model=my_model)
注意：注册到 Catalog 的模型必须携带签名（Signature）。建议在 log_model 时传入 input_example= 让 MLflow 自动推断签名；或在调用前显式构造 mlflow.models.signature.ModelSignature。无签名的模型在后续注册时将被拒绝。
3. 在记录时直接注册模型
通过 registered_model_name= 参数可在 log_model 时同步注册到 Catalog（同一模型名首次注册为 V1，再次注册版本号自动 +1）：
mlflow.sklearn.log_model( sk_model=model, name="sklearn-model", input_example=X_train, registered_model_name="my_catalog.my_schema.churn_model",)
模型注册的详细规则参见 模型版本管理。
七、完整示例
下面是一个端到端的示例，演示在一次训练中同时记录参数、指标、模型并完成注册：
import mlflowimport mlflow.sklearnfrom sklearn.datasets import make_regressionfrom sklearn.ensemble import RandomForestRegressorfrom sklearn.metrics import mean_squared_errorfrom sklearn.model_selection import train_test_splitmlflow.set_experiment("regression_demo")with mlflow.start_run() as run: X, y = make_regression(n_features=4, n_informative=2, random_state=0, shuffle=False) X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42) params = {"max_depth": 2, "random_state": 42} model = RandomForestRegressor(**params) model.fit(X_train, y_train) # 记录参数 mlflow.log_params(params) # 记录指标 y_pred = model.predict(X_test) mlflow.log_metrics({"mse": mean_squared_error(y_test, y_pred)}) # 记录并注册模型（同步注册到 Catalog） mlflow.sklearn.log_model( sk_model=model, name="sklearn-model", input_example=X_train, registered_model_name="catalog_name.schema_name.model_name", )
八、父子 Run 与超参搜索
在父 Run 上下文中嵌套子 Run，常用于超参数搜索场景：
import mlflowwith mlflow.start_run(run_name="Parent Run") as parent: mlflow.log_param("model_type", "RandomForest") for n in [50, 100, 200]: with mlflow.start_run(run_name=f"n_estimators={n}", nested=True): mlflow.log_param("n_estimators", n) # … 训练并记录 metric …
实验详情中的运行任务列表会以嵌套方式展示父 Run 与其下的子 Run，便于分层查看。
九、1. 如何查看实验详情
记录完成后，进入实验详情查看：
1.1 进入数据科学 > 模型实验 ，点击目标实验名称进入详情。
1.2 默认在 运行任务 中以列表展示所有 Run。
1.3 点击运行任务名称进入 Run 详情，包含 4 个 Tab 如下：
| Tab | 内容 |
| 概览信息 | 关于此运行任务的基本信息。支持点击跳转数据集、模型、代码文件界面。支持编辑标签，搜索参数配置、指标 |
| 模型指标 | 展示通过 log_metric 记录的指标的可视化图表（柱状图、折线图等） |
| 系统指标 | CPU 使用率、内存、网络、磁盘等系统级监控图表 |
| 模型文件 | 当前 Run 的所有工件文件，支持浏览、复制、下载 |
十、2. 添加自定义标签
在 概览信息 页面，你可以为该运行任务添加自定义键值对标签，用于分类与检索。
操作方式：在添加标签 区域输入键值对，每输入一组后点击保存按钮，系统会自动新增一行；点击行末删除按钮可移除该行。
十一、3. 验证结果
记录完成后，你可以通过以下方式确认记录结果：
·概览信息 中可看到所有记录的参数、指标、自定义标签。
·模型指标 与 系统指标 中可看到对应的图表。
·模型文件 中可看到记录的工件文件树状结构。
·如果同步注册了模型，可在 模型管理 列表中找到对应的注册模型。
十二、调用 mlflow.log_param 时报错 Parameter already logged 怎么办？
同一 Run 内同名参数只能记录一次。请检查代码是否在循环中重复记录同一参数；如果确实需要按时间步记录变化的值，请改用 mlflow.log_metric(key, value, step=…)。
十三、指标曲线为什么只显示一个点？
mlflow.log_metric(key, value) 不传 step 时默认按记录顺序累加。如果只调用了一次，曲线只有一个点。在训练循环中按 epoch 调用 log_metric(key, value, step=epoch) 即可绘制完整曲线。
十四、模型注册时提示模型没有签名怎么办？
注册模型要求模型必须携带签名。请：
1. 在 log_model 调用时传入 input_example= 让 MLflow 自动推断签名；或
2. 显式构造 mlflow.models.signature.ModelSignature 并通过 signature= 参数传入；或
3. 启用 mlflow.autolog() 由框架自动记录带签名的模型。
若模型没有签名，则模型不会被记录，模型文件 区不会显示已记录的模型文件。
十五、手动启动的 Run 一直停留在运行中状态怎么办？
如果代码异常退出且未正确关闭 Run，可能导致 Run 状态滞留。建议始终使用 with mlflow.start_run() as run: 上下文管理器，异常退出时也会自动调用 mlflow.end_run() 关闭 Run。
十六、相关文档
·什么是模型实验
·创建实验
·对比实验结果
·Notebook