本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# MLflow 与您的环境集成


以下页面介绍如何在您的开发环境中开始使用 MLflow SDK 和 AWS MLflow 插件。这可能包括 Studio IDEs 或 Studio Classic 中的本地或 Jupyter 笔记本环境。

Amazon SageMaker AI 使用 MLflow 插件自定义 MLflow Python 客户端的行为并集成 AWS 工具。该 AWS MLflow 插件对 MLflow 使用[AWS 签名版本 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) 进行的 API 调用进行身份验证。该 AWS MLflow 插件允许您使用 MLflow跟踪服务器 ARN 连接到您的跟踪服务器。有关插件的更多信息，请参阅[AWS MLflow 插件](https://pypi.org/project/sagemaker-mlflow/)和[MLflow 插件](https://mlflow.org/docs/latest/plugins.html)。

**重要**  
您的开发环境中的用户 IAM 权限必须有权访问任何相关 MLflow 的 API 操作，才能成功运行提供的示例。有关更多信息，请参阅 [为设置 IAM 权限 MLflow](mlflow-create-tracking-server-iam.md)。

有关使用 MLflow 软件开发工具包的更多信息，请参阅 MLflow文档中的 [Python API](https://mlflow.org/docs/2.13.2/python_api/index.html)。

## 安装 MLflow 和 AWS MLflow 插件


在您的开发环境中，同时安装两者 MLflow 以及 AWS MLflow 插件。

```
pip install sagemaker-mlflow
```

为确保您的 MLflow 客户端和跟踪服务器之间的兼容性，请根据您的跟踪服务器版本使用相应的 MLflow 版本：
+ 对于跟踪服务器 2.13.x，请使用 `mlflow==2.13.2`
+ 对于跟踪服务器 2.16.x，请使用 `mlflow==2.16.2`
+ 对于跟踪服务器 3.0.x，请使用 `mlflow==3.0.0`

要查看哪些版本可用于 SageMaker AI，请参阅[跟踪服务器版本](mlflow.md#mlflow-create-tracking-server-versions)。 MLflow 

## Connect 连接到您的 MLflow 跟踪服务器


使用 `[mlflow.set\$1tracking\$1uri](https://mlflow.org/docs/2.13.2/python_api/mlflow.html#mlflow.set_tracking_uri)` 从开发环境使用 ARN 连接到跟踪服务器：

```
import mlflow

arn = "YOUR-TRACKING-SERVER-ARN"

mlflow.set_tracking_uri(arn)
```

# 在训练期间记录指标、参数和 MLflow 模型
日志指标

连接到 MLflow 跟踪服务器后，您可以使用 MLflow SDK 记录指标、参数和 MLflow 模型。

## 记录训练指标


在 MLflow 训练`mlflow.log_metric`中使用来跟踪指标。有关使用记录指标的更多信息 MLflow，请参阅`[mlflow.log\$1metric](https://mlflow.org/docs/2.13.2/python_api/mlflow.html#mlflow.log_metric)`。

```
with mlflow.start_run():
    mlflow.log_metric("foo", 1)
    
print(mlflow.search_runs())
```

该脚本应创建一个实验运行，并打印出类似下面的输出结果：

```
run_id experiment_id status artifact_uri ... tags.mlflow.source.name tags.mlflow.user tags.mlflow.source.type tags.mlflow.runName
0 607eb5c558c148dea176d8929bd44869 0 FINISHED s3://dddd/0/607eb5c558c148dea176d8929bd44869/a... ... file.py user-id LOCAL experiment-code-name
```

在 MLflow 用户界面中，此示例应类似于以下内容：

![\[显示在顶层 “实MLflow 验” 菜单中的实验。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/mlflow/mlflow-ui-experiments.png)


选择**运行名称**，查看更多运行详情。

![\[在 MLflow 界面中的实验运行页面上显示的实验参数。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/mlflow/mlflow-ui-foo.png)


## 对数参数和模型


**注意**  
以下示例要求环境具有 `s3:PutObject` 权限。此权限应与 MLflow 软件开发工具包用户登录账户或联合 AWS 账户时所扮演的 IAM 角色相关联。更多信息，请参阅[用户和角色策略示例](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-policies-s3.html)。

以下示例将带您完成基本的模型训练工作流程， SKLearn并向您展示如何在 MLflow 实验运行中跟踪该模型。此示例记录了参数、指标和模型构件。

```
import mlflow

from mlflow.models import infer_signature

import pandas as pd
from sklearn import datasets
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score, precision_score, recall_score, f1_score

# This is the ARN of the MLflow Tracking Server you created
mlflow.set_tracking_uri(your-tracking-server-arn)
mlflow.set_experiment("some-experiment")

# Load the Iris dataset
X, y = datasets.load_iris(return_X_y=True)

# Split the data into training and test sets
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# Define the model hyperparameters
params = {"solver": "lbfgs", "max_iter": 1000, "multi_class": "auto", "random_state": 8888}

# Train the model
lr = LogisticRegression(**params)
lr.fit(X_train, y_train)

# Predict on the test set
y_pred = lr.predict(X_test)

# Calculate accuracy as a target loss metric
accuracy = accuracy_score(y_test, y_pred)

# Start an MLflow run and log parameters, metrics, and model artifacts
with mlflow.start_run():
    # Log the hyperparameters
    mlflow.log_params(params)

    # Log the loss metric
    mlflow.log_metric("accuracy", accuracy)

    # Set a tag that we can use to remind ourselves what this run was for
    mlflow.set_tag("Training Info", "Basic LR model for iris data")

    # Infer the model signature
    signature = infer_signature(X_train, lr.predict(X_train))

    # Log the model
    model_info = mlflow.sklearn.log_model(
        sk_model=lr,
        name="iris_model", # Changed from artifact_path to name for MLflow 3.0
        signature=signature,
        input_example=X_train,
        registered_model_name="tracking-quickstart",
    )
```

在 MLflow 界面中，在左侧导航窗格中选择实验名称以浏览所有关联的运行。选择**运行名称**，查看每个运行的更多信息。在此示例中，该运行的实验运行页面应类似于以下内容。

![\[在 MLflow 界面中跟踪实验运行的参数。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/mlflow/mlflow-ui-parameters.png)


本例记录逻辑回归模型。在 MLflow 用户界面中，您还应该看到记录的模型工件。

![\[跟踪 MLflow 用户界面中运行的实验的模型工件。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/mlflow/mlflow-ui-model-artifacts.png)


# 在模型注册表中自动注册 SageMaker AI SageMaker 模型
注册模型

您可以使用 Python SDK 或直接通过 MLflow 用户界面记录 MLflow SageMaker 模型并将其自动注册到 “模型注册表”。

**注意**  
请勿在模型名称中使用空格。虽然 MLflow 支持带空格的模型名称，但 SageMaker AI Model Package 不支持。如果在模型名称中使用空格，自动注册过程将失败。

## 使用 SageMaker Python 软件开发工具包注册模型


在 MLflow 客户端`create_registered_model`中使用，在 SageMaker AI 中自动创建与您选择的现有 MLflow 模型相对应的模型包组。

```
import mlflow 
from mlflow import MlflowClient

mlflow.set_tracking_uri(arn)

client = MlflowClient()

mlflow_model_name = 'AutoRegisteredModel'
client.create_registered_model(mlflow_model_name, tags={"key1": "value1"})
```

`mlflow.register_model()`用于在模型训练期间自动向 SageMaker 模型注册表注册模型。注册 MLflow 模型时，会在 SageMaker AI 中创建相应的模型包组和模型包版本。

```
import mlflow.sklearn
from mlflow.models import infer_signature
from sklearn.datasets import make_regression
from sklearn.ensemble import RandomForestRegressor

mlflow.set_tracking_uri(arn)
params = {"n_estimators": 3, "random_state": 42}
X, y = make_regression(n_features=4, n_informative=2, random_state=0, shuffle=False)

# Log MLflow entities
with mlflow.start_run() as run:
    rfr = RandomForestRegressor(**params).fit(X, y)
    signature = infer_signature(X, rfr.predict(X))
    mlflow.log_params(params)
    mlflow.sklearn.log_model(rfr, artifact_path="sklearn-model", signature=signature)

model_uri = f"runs:/{run.info.run_id}/sklearn-model"
mv = mlflow.register_model(model_uri, "RandomForestRegressionModel")

print(f"Name: {mv.name}")
print(f"Version: {mv.version}")
```

## 使用 MLflow 用户界面注册模型


您也可以直接在 MLflow 用户界面中向 SageMaker 模型注册表注册模型。在 MLflow 用户界面的**模型**菜单中，选择**创建模型**。以这种方式新创建的所有模型都将添加到 SageMaker 模型注册表中。

![\[在 MLflow UI 中创建模型注册表。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/mlflow/mlflow-ui-register-model.png)


在实验跟踪期间记录模型后，在 MLflow 用户界面中导航到运行页面。选择 Ar **t** ifacts 窗格，然后选择右上角的注册**模型**，在模型注册表 MLflow和模型注册表中注册 SageMaker 模型版本。

![\[在 MLflow UI 中创建模型注册表。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/mlflow/mlflow-ui-register-model-2.png)


## 查看 Studio 中已注册的模型


在 SageMaker Studio 登录页面中，选择左侧导航窗格中的**模**特以查看您注册的模特。有关 Studio 入门的更多信息，请参阅[启动 Amazon SageMaker Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-launch.html)。

![\[MLflow 在 Studio 用户界面的 “ SageMaker 模型注册表” 中注册的模型。\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/images/mlflow/mlflow-studio-model-registry.png)


# 使用部署 MLflow 模型 `ModelBuilder`
部署模型

您可以使用 Amazon A SageMaker I MLflow 模型生成器将模型部署到 A SageMaker I 终端节点。有关 Amazon A SageMaker I 模型生成器的更多信息，请参阅[使用在 Amazon A SageMaker I 中创建模型 ModelBuilder](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-modelbuilder-creation.html)。

`ModelBuilder` 是一个 Python 类，它接收框架模型或用户指定的推理规范，并将其转换为可部署的模型。有关该`ModelBuilder`课程的更多详细信息，请参阅[ModelBuilder](https://sagemaker.readthedocs.io/en/stable/api/inference/model_builder.html#sagemaker.serve.builder.model_builder.ModelBuilder)。

要使用部署 MLflow 模型`ModelBuilder`，请在`model_metadata["MLFLOW_MODEL_PATH"]`属性中提供 MLflow工件的路径。请继续阅读有关有效模型路径输入格式的更多信息：

**注意**  
如果您以 MLflow 运行 ID 或模型注册路径的形式提供 MLflow 模型构件路径，则还必须通过该`model_metadata["MLFLOW_TRACKING_ARN"]`属性指定您的跟踪服务器 ARN。
+ [需要 `model_metadata` 中 ARN 的模型路径](#mlflow-track-experiments-model-deployment-with-arn)
+ [在 `model_metadata` 中不需要 ARN 的模型路径](#mlflow-track-experiments-model-deployment-without-arn)

## 需要 `model_metadata` 中 ARN 的模型路径


以下模型路径要求在 `model_metadata` 中指定 ARN 以进行部署：
+ MLflow [运行 ID](https://mlflow.org/docs/latest/python_api/mlflow.entities.html?highlight=mlflow%20info#mlflow.entities.RunInfo.run_id)：`runs:/aloy-run-id/run-relative/path/to/model`
+ MLflow [模型注册表路径](https://mlflow.org/docs/latest/model-registry.html#find-registered-models)：`models:/model-name/model-version`

## 在 `model_metadata` 中不需要 ARN 的模型路径


以下模型路径无需在 `model_metadata` 中指定 ARN 以进行部署：
+ 本地模型路径：`/Users/me/path/to/local/model`
+ Amazon S3 模型路径：`s3://amzn-s3-demo-bucket/path/to/model`
+ 模型软件包 ARN：`arn:aws:sagemaker:region:account-id:mlflow-tracking-server/tracking-server-name`

有关 MLflow 模型部署如何与 Amazon A SageMaker I 配合使用的更多信息，请参阅 MLflow 文档中的[将 MLflow模型部署到 SageMaker Amazon AI](https://mlflow.org/docs/latest/deployment/deploy-model-to-sagemaker.html)。

如果使用 Amazon S3 路径，可以通过以下命令找到注册模型的路径：

```
registered_model = client.get_registered_model(name='AutoRegisteredModel')
source_path = registered_model.latest_versions[0].source
```

以下示例概述了如何使用`ModelBuilder`和 MLflow 模型注册表路径部署 MLflow 模型。由于此示例以模型注册表路径的形式提供了 MLflow 模型构件路径，因此对的调用还`ModelBuilder`必须通过属性指定跟踪服务器 ARN。`model_metadata["MLFLOW_TRACKING_ARN"]`

**重要**  
必须使用 Pyth SageMaker on 软件开发工具包 [2.224.0](https://pypi.org/project/sagemaker/2.224.0/) 或更高版本才能使用。`ModelBuilder`

**注意**  
请参考以下代码示例。有关向您展示如何部署注册 MLflow 模型的 end-to-end示例，请参阅[使用 Jupyter Notebook 示例的 MLflow 教程](mlflow-tutorials.md)。

```
from sagemaker.serve import ModelBuilder
from sagemaker.serve.mode.function_pointers import Mode
from sagemaker.serve import SchemaBuilder

my_schema = SchemaBuilder(
    sample_input=sample_input, 
    sample_output=sample_output
)

model_builder = ModelBuilder(
    mode=Mode.SAGEMAKER_ENDPOINT,
    schema_builder=my_schema,
    role_arn="Your-service-role-ARN",
    model_metadata={
        # both model path and tracking server ARN are required if you use an mlflow run ID or mlflow model registry path as input
        "MLFLOW_MODEL_PATH": "models:/sklearn-model/1"
        "MLFLOW_TRACKING_ARN": "arn:aws:sagemaker:region:account-id:mlflow-tracking-server/tracking-server-name"
    }
)
model = model_builder.build()
predictor = model.deploy( initial_instance_count=1, instance_type="ml.c6i.xlarge" )
```

要维护使用部署的 MLflow 模型的[血统跟踪](https://docs.aws.amazon.com/sagemaker/latest/dg/lineage-tracking.html)`ModelBuilder`，您必须拥有以下 IAM 权限：
+ `sagemaker:CreateArtifact`
+ `sagemaker:ListArtifacts`
+ `sagemaker:AddAssociation`
+ `sagemaker:DescribeMLflowTrackingServer`

**重要**  
任务流水线追踪为可选项。如果没有与任务流水线追踪相关的权限，则部署成功。如果未配置权限，则在调用 `model.deploy()` 时会出现任务流水线追踪权限错误。不过，端点部署仍会成功，您可以直接与模型端点进行交互。如果配置了上述权限，就会自动创建和存储任务流水线追踪信息。

有关更多信息和 end-to-end示例，请参阅[使用 Jupyter Notebook 示例的 MLflow 教程](mlflow-tutorials.md)。