MLflow 3 如何通过 Python 列出 Run 中未注册的模型？

2026-11-06数据阿明

结论

在 MLflow 3 中，mlflow.pytorch.log_model(..., name=...) 记录的是 Logged Model。模型 artifact 不再作为普通 Run artifact 存储，因此通过 client.list_artifacts(run_id) 查不到它们是正常的。要查询这些模型，可以使用 MlflowClient.search_logged_models()，再根据 source_run_id 筛选。加载模型时，可以用它的 model_id 构造 models:/<model_id> URI。MLflow 3 的迁移说明也提到，模型 artifact 已不再存储为 Run artifacts。MLflow 3 迁移指南

列出指定 Run 中的模型

下面的示例按 experiment 查询模型并处理分页，之后在 Python 中根据 source_run_id 筛选。这样不需要假设 source_run_id 支持服务端过滤：

import mlflow
from mlflow.tracking import MlflowClient

mlflow.set_tracking_uri("http://localhost:5000")
client = MlflowClient()

experiment_id = "1"
run_id = "c1fc86256ed64b6ea1c71ea4122f07be"

models = []
page_token = None

while True:
    page = client.search_logged_models(
        experiment_ids=[experiment_id],
        max_results=1000,
        page_token=page_token,
    )
    models.extend(
        model for model in page
        if model.source_run_id == run_id
    )

    page_token = page.token
    if not page_token:
        break

for model in models:
    print(
        f"name={model.name}, "
        f"run_id={model.source_run_id}, "
        f"model_id={model.model_id}"
    )

search_logged_models() 返回的 Logged Model 对象包含 name、source_run_id 和 model_id 等字段。MLflow Python API：search_logged_models

加载选中的 PyTorch 模型

筛选结果中的 model_id 可以直接用于 MLflow 3 的模型 URI：

selected_model = next(
    model for model in models
    if model.name == "checkpoint_epoch_2"
)

model_a = mlflow.pytorch.load_model(
    f"models:/{selected_model.model_id}"
)

MLflow 3 文档将 models:/<model_id> 列为模型 URI，也建议使用 log_model() 返回的 model_uri 或 model_id 加载 Logged Model。MLflow 3 模型 URI 说明

如果同一个 Run 中记录了多个同名模型，还需要结合 step、模型指标或其他已记录的属性来确定目标，仅凭 name 可能无法区分。上面的代码会先获取所选 experiment 中的模型，再根据 source_run_id 在本地筛选。请确认 tracking server 与 Python 客户端使用兼容的 MLflow 3 版本。