MLflow 3 迁移指南

本指南涵盖了从 MLflow 2.x 迁移到 MLflow 3.x 时发生的重大变更和 API 更新。

安装

通过运行以下命令来安装 MLflow 3：

bash

pip install "mlflow>=3.1"

资源：网站 | 文档 | 发布说明

MLflow 2.x 的主要变更

模型日志记录 API 变更

MLflow 2.x

python

with mlflow.start_run():
    mlflow.pyfunc.log_model(
        artifact_path="model",
        python_model=python_model,
    )

MLflow 3

python

# No longer requires starting a Run before logging models
mlflow.pyfunc.log_model(
    name="model",  # Use 'name' instead of 'artifact_path'
    python_model=python_model,
)

注意

在 MLflow 3 中，模型已成为一流实体。您可以直接调用 log_model，而无需使用 mlflow.start_run() 上下文管理器。使用 name 参数可启用对 LoggedModels 的搜索。

模型工件存储位置

MLflow 2.x

shell

experiments/
  └── <experiment_id>/
    └── <run_id>/
      └── artifacts/
        └── ... # model artifacts stored here

MLflow 3

shell

experiments/
  └── <experiment_id>/
    └── models/
      └── <model_id>/
        └── artifacts/
          └── ... # model artifacts stored here

警告

此更改会影响 mlflow.client.MlflowClient.list_artifacts() 的行为。模型工件不再作为运行工件存储。

UI 变更

工件选项卡

在 MLflow 3.x 中，运行页面的“工件”选项卡不再显示模型工件。现在，可以通过“已记录模型”页面访问模型工件，该页面提供了用于模型特定信息和工件的专用视图。

重大变更

已移除的功能

• MLflow Recipes：已完全移除（#15250）。迁移到标准的 MLflow 跟踪和模型注册表功能，或考虑使用 MLflow Projects。

• 模型 Flavor：以下 Flavor 不再受支持

  • fastai（#15255）- 使用 mlflow.pyfunc 和自定义包装器
  • mleap（#15259）- 使用 mlflow.onnx 或 mlflow.pyfunc
  • diviner - 使用 mlflow.pyfunc 和自定义包装器
  • gluon - 使用 mlflow.pytorch 或 mlflow.onnx

• AI Gateway：移除了 'routes' 和 'route_type' 配置键（#15331）。使用新的配置格式。

• 部署服务器：移除了部署服务器和 start-server CLI 命令（#15327）。使用 mlflow models serve 或容器化部署。

跟踪 API 变更

移除了 run_uuid 属性

将 run_uuid 替换为 run_id

python

# MLflow 2.x
run_info.run_uuid

# MLflow 3
run_info.run_id

移除了 Git 标签

以下运行标签已被移除（#15366）

• mlflow.gitBranchName
• mlflow.gitRepoURL

TensorFlow Autologging

从 TensorFlow Autologging 中移除了 every_n_iter 参数（#15412）。实现自定义日志记录回调以进行精细的日志记录频率控制。

模型 API 变更

移除的参数

以下参数已从模型日志记录/保存 API 中移除

• example_no_conversion（#15322）
• code_path（#15368）- 使用默认的代码目录结构
• PyTorch Flavor 的 requirements_file（#15369）- 使用 pip_requirements 或 extra_pip_requirements
• Transformers Flavor 的 inference_config（#15415）- 在日志记录前设置配置

ModelInfo 变更

ModelInfo 中移除了 signature_dict 属性（#15367）。请改用 signature 属性。

评估 API 变更

基线模型比较

移除了 baseline_model 参数（#15362）。使用 mlflow.validate_evaluation_results API 来比较模型。

python

# For classical ML models, use mlflow.models.evaluate
result_1 = mlflow.models.evaluate(
    model_1, data, targets="label", model_type="classifier"
)
result_2 = mlflow.models.evaluate(
    model_2, data, targets="label", model_type="classifier"
)

# Compare results
mlflow.validate_evaluation_results(result_1, result_2)

注意

对于 GenAI 评估，请使用 mlflow.genai.evaluate 和新的评估框架。有关从旧版 LLM 评估方法迁移的详细信息，请参阅GenAI 评估迁移指南。

MetricThreshold 变更

使用 greater_is_better 替代 higher_is_better

python

# MLflow 2.x
threshold = MetricThreshold(higher_is_better=True)

# MLflow 3
threshold = MetricThreshold(greater_is_better=True)

自定义指标

移除了 custom_metrics 参数（#15361）。使用评估 API 中更新的自定义指标方法。

Explainer 日志记录

mlflow.models.evaluate 不再默认记录 explainer 作为模型。要启用

python

mlflow.models.evaluate(
    ...,
    evaluator_config={
        "log_model_explainability": True,
        "log_explainer": True,
    },
)

环境变量

移除了 MLFLOW_GCS_DEFAULT_TIMEOUT（#15365）。使用标准的 GCS 客户端库方法配置超时。

迁移常见问题解答

MLflow 3.x 可以加载 MLflow 2.x 创建的资源吗？

是的，MLflow 3.x 可以加载 MLflow 2.x 创建的资源（运行、模型、跟踪等）。但是，反之则不成立。

警告

测试 MLflow 3.x 时，请使用单独的环境以避免与 MLflow 2.x 发生冲突。

load_model 抛出 ResourceNotFound 错误。是什么原因？

在 MLflow 3.x 中，模型工件存储在不同的位置。请使用 log_model 返回的模型 URI。

python

# ❌ Don't use mlflow.get_artifact_uri("model")
with mlflow.start_run() as run:
    mlflow.sklearn.log_model(my_model, name="model")
    mlflow.sklearn.load_model(mlflow.get_artifact_uri("model"))  # Fails!

# ✅ Use the model URI from log_model
with mlflow.start_run() as run:
    info = mlflow.sklearn.log_model(my_model, name="model")

    # Recommended: use model_uri from result
    mlflow.sklearn.load_model(info.model_uri)

    # Alternative: use model_id
    mlflow.sklearn.load_model(f"models:/{info.model_id}")

    # Deprecated: use run_id (will be removed in future)
    mlflow.sklearn.load_model(f"runs:/{run.info.run_id}/model")

如何修改模型要求？

使用 mlflow.models.update_model_requirements()

python

import mlflow


class DummyModel(mlflow.pyfunc.PythonModel):
    def predict(self, context, model_input: list[str]) -> list[str]:
        return model_input


model_info = mlflow.pyfunc.log_model(name="model", python_model=DummyModel())
mlflow.models.update_model_requirements(
    model_uri=model_info.model_uri,
    operation="add",
    requirement_list=["scikit-learn"],
)

如何停留在 MLflow 2.x？

将 MLflow 固定到最新的 2.x 版本。

bash

pip install 'mlflow<3'

兼容性

我们强烈建议同时升级客户端和服务器到 MLflow 3.x 以获得最佳体验。客户端和服务器版本之间的不匹配可能导致意外行为。

获取帮助

有关迁移特定代码的详细指导，请查阅

• MLflow 文档
• MLflow 社区论坛
• MLflow Slack
• 发布说明