创建模型包（预览版）

项目
08/26/2024

模型包是 Azure 机器学习中的一项功能，可用于收集将机器学习模型部署到服务平台所需的所有依赖项。在部署模型之前创建包可提供稳健可靠的部署以及更高效的 MLOps 工作流。包可以跨工作区移动，甚至可以移动到 Azure 机器学习之外。

重要

此功能目前处于公开预览状态。此预览版在提供时没有附带服务级别协议，我们不建议将其用于生产工作负荷。某些功能可能不受支持或者受限。

有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

本文将介绍如何打包用于部署的模型。

先决条件

在按照本文中的步骤操作之前，请确保满足以下先决条件：

Azure 订阅。如果没有 Azure 订阅，可在开始前创建一个试用帐户。试用 Azure 机器学习。
Azure 机器学习工作区。如果没有，请使用如何管理工作区一文中的步骤创建一个。
Azure 基于角色的访问控制 (Azure RBAC) 用于授予对 Azure 机器学习中的操作的访问权限。若要执行本文中的步骤，必须为用户帐户分配 Azure 机器学习工作区的所有者或参与者角色，或者分配一个自定义角色。有关详细信息，请参阅管理对 Azure 机器学习工作区的访问。
要打包的模型。此示例使用工作区中注册的 MLflow 模型。

关于此示例

在此示例中，你将了解如何在 Azure 机器学习中打包模型。

克隆存储库

本文中的示例基于 azureml-examples 存储库中包含的代码示例。要在无需复制/粘贴 YAML 和其他文件的情况下在本地运行命令，请先克隆存储库，然后将目录更改为以下文件夹：

Azure CLI
Python

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

!git clone https://github.com/Azure/azureml-examples --depth 1
!cd azureml-examples/sdk/python

本部分使用文件夹 endpoints/online/deploy-packages/custom-model 中的示例。

连接到工作区

连接到将在其中完成工作的 Azure 机器学习工作区。

Azure CLI
Python

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

工作区是 Azure 机器学习的顶级资源，为使用 Azure 机器学习时创建的所有项目提供了一个集中的处理位置。在本部分，你将连接到在其中执行部署任务的工作区。

导入所需的库：

from azure.identity import DefaultAzureCredential
from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
    AzureMLOnlineInferencingServer,
    ModelPackage,
    CodeConfiguration,
    BaseEnvironment,
    ModelConfiguration,
)
from azure.ai.ml.entities import (
    ManagedOnlineEndpoint,
    ManagedOnlineDeployment,
    Environment,
    Model,
)

如果要在 Azure 机器学习的计算实例中运行，请创建一个 MLClient，如下所示：

ml_client = MLClient.from_config(DefaultAzureCredential())

否则，请配置工作区详细信息并获取工作区句柄：

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)

打包模型

可以显式创建模型包，以允许控制打包操作的完成方式。在以下情况下使用此工作流：

你想要自定义模型包的创建方式。
你想要在 Azure 机器学习外部部署模型包。
你想要在 MLOps 工作流中使用模型包。

可以通过指定以下内容来创建模型包：

要打包的模型：每个模型包只能包含一个模型。 Azure 机器学习不支持在同一模型包下打包多个模型。
基础环境：环境用于指示基础映像以及模型所需的 Python 包依赖项。对于 MLflow 模型，Azure 机器学习会自动生成基础环境。对于自定义模型，需要指定它。
服务技术：用于运行模型的推理堆栈。

注册模型

模型包要求在工作区或 Azure 机器学习注册表中注册模型。在本例中，你已在存储库中拥有模型的本地副本，因此只需要将模型发布到工作区中的注册表。如果打算部署的模型已注册，则可以跳过此部分。

Azure CLI
Python

MODEL_NAME='sklearn-regression'
MODEL_PATH='model'
az ml model create --name $MODEL_NAME --path $MODEL_PATH --type custom_model

model_name = "sklearn-regression"
model_path = "model"

model = ml_client.models.create_or_update(Model(name=model_name, path=model_path))

创建基础环境

基础环境用于指示基础映像以及模型 Python 包依赖项。我们的模型需要使用以下包，如 conda 文件中所示：

conda.yaml

name: model-env
channels:
  - conda-forge
dependencies:
  - python=3.9
  - numpy=1.23.5
  - pip=23.0.1
  - scikit-learn=1.2.2
  - scipy=1.10.1
  - xgboost==1.3.3

注意

基础环境与用于将模型部署到联机和批量终结点的环境有何不同？ 将模型部署到终结点时，你的环境需要包含模型的依赖项以及托管联机终结点正常工作所需的 Python 包。这会将手动过程引入部署，其中，必须将模型的要求与服务平台的要求相结合。另一方面，使用模型包可以消除这种摩擦，因为推理服务器所需的包将在打包时自动注入到模型包中。

按如下所示创建环境：

Azure CLI
Python

创建环境定义：

sklearn-regression-env.yml

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: sklearn-regression-env
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04
conda_file: conda.yaml
description: An environment for models built with XGBoost and Scikit-learn.

然后创建环境：

az ml environment create -f environment/sklearn-regression-env.yml

base_environment = ml_client.environments.create_or_update(
    Environment(
        name=f"{model_name}-env",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04",
        conda_file="environment/conda.yml",
    )
)

创建包规格

可以使用 Azure CLI 或适用于 Python 的 Azure 机器学习 SDK 在 Azure 机器学习中创建模型包。自定义包规范支持以下属性：

Azure CLI
Python

属性	类型	描述	必须
`target_environment`	`str`	要创建的包的名称。包操作的结果是 Azure 机器学习中的环境。	是
`base_environment_source`	`object`	用于创建指定模型依赖项的包的基础映像。	是的，除非模型为 MLflow。
`base_environment_source.type`	`str`	基础映像的类型。仅支持使用其他环境作为基础映像 (`type: environment_asset`)。
`base_environment_source.resource_id`	`str`	要使用的基础环境的资源 ID。使用格式 `azureml:<name>:<version>` 或长资源 ID。
`inferencing_server`	`object`	要使用的推理服务器。	是
`inferencing_server.type`	`azureml_online` `custom`	对 Azure 机器学习推理服务器使用 `azureml_online`，或对自定义联机服务器（例如 TensorFlow 服务或 Torch Serve）使用 `custom`。	是
`inferencing_server.code_configuration`	`object`	使用推理例程的代码配置。它应包含至少一个具有 `init` 和 `run` 方法的 Python 文件。	是的，除非模型为 MLflow。
`model_configuration`	`object`	模型配置。使用此属性可以控制模型在结果映像中的打包方式。	否
`model_configuration.mode`	`download` `copy`	指示如何将模型放置在包中。可能的值为 `download`（默认）或 `copy`。若要在部署时从模型注册表下载模型，请使用 `download`。此选项会创建更小的 docker 映像，因为模型不包含在其中。若要断开映像与 Azure 机器学习的连接，请使用 `copy`。模型将在打包时复制到 docker 映像内部。启用了专用链接的工作区不支持 `copy`。	否

属性	类型	描述	必须
`target_environment`	`str`	要创建的包的名称。包操作的结果是 Azure 机器学习中的环境。	是
`base_environment_source`	`BaseEnvironment`	用于创建指定模型依赖项的包的基础映像。	是的，除非模型类型为 MLflow。
`base_environment_source.type`	`BaseEnvironmentType`	基础映像的类型。仅支持使用其他环境 (`EnvironmentAsset`) 作为基础映像。
`base_environment_source.resource_id`	`str`	要使用的基础环境的资源 ID。使用格式 `azureml:<name>:<version>` 或长格式资源 ID。
`inferencing_server`	`AzureMLOnlineInferencingServer` `CustomOnlineInferenceServer`	要使用的推理服务器。对 Azure 机器学习推理服务器使用 `AzureMLOnlineInferencingServer`，或对自定义联机服务器（例如 TensorFlow 服务或 Torch Serve 等）使用 `CustomOnlineInferenceServer`。如果设置为 `AzureMLInferencingServer` 并且模型类型不是 Mlflow，则应指定代码配置部分，其中包含至少一个具有 `init` 和 `run` 方法的 Python 文件。如果设置为 `CustomOnlineInferenceServer`，则应指定联机服务器配置部分。	是
`model_configuration`	`ModelConfiguration`	模型配置。使用此属性可以控制模型在结果映像中的打包方式。	否
`model_configuration.mode`	`ModelInputMode`	指明如何将模型放置在包中。可能的值为 `ModelInputMode.DOWNLOAD`（默认）或 `ModelInputMode.COPY`。若要在部署时从模型注册表下载模型，请使用 `ModelInputMode.DOWNLOAD`。此选项会创建更小的 docker 映像，因为模型不包含在其中。若要断开映像与 Azure 机器学习的连接，请使用 `ModelInputMode.COPY`。模型将在打包时复制到 docker 映像内部。启用了专用链接的工作区不支持 `ModelInputMode.COPY`。	否

按如下所示创建包规格：

Azure CLI
Python

package-moe.yml

 $schema: http://azureml/sdk-2-0/ModelVersionPackage.json
 base_environment_source:
	type: environment_asset
    resource_id: azureml:sklearn-regression-env:1
 target_environment: sklearn-regression-online-pkg
 inferencing_server: 
	type: azureml_online
	code_configuration:
  	  code: src
      scoring_script: score.py

若要创建模型包，请按如下所示创建包规格：

 pakage_config = ModelPackage(
	target_environment_name="sklearn-regression-online-pkg",
	base_environment_source=BaseEnvironment(
    	type="asset",
    	resource_id=f"azureml:{base_environment.name}:{base_environment.version}",
	),
	inferencing_server=AzureMLOnlineInferencingServer(
    	code_configuration=CodeConfiguration(code="src", scoring_script="score.py")
	),
 )

    
1. Start the model package operation:

    # [Azure CLI](#tab/cli)
    
    ```azurecli
	az ml model package -n $MODEL_NAME -v $MODEL_VERSION --file package-moe.yml
	```
    
    # [Python](#tab/sdk)
    
    ```python
	model_package = ml_client.models.package(model_name, model.version, pakage_config)
	```
    
1. The result of the package operation is an environment.


## Package a model that has dependencies in private Python feeds

Model packages can resolve Python dependencies that are available in private feeds. To use this capability, you need to create a connection from your workspace to the feed and specify the PAT token configuration. The following Python code shows how you can configure the workspace where you're running the package operation.

```python
from azure.ai.ml.entities import WorkspaceConnection
from azure.ai.ml.entities import PatTokenConfiguration

# fetching secrets from env var to secure access, these secrets can be set outside or source code
git_pat = os.environ["GIT_PAT"]

credentials = PatTokenConfiguration(pat=git_pat)

ws_connection = WorkspaceConnection(
    name="<workspace_connection_name>",
    target="<git_url>",
    type="git",
    credentials=credentials,
)

ml_client.connections.create_or_update(ws_connection)

创建连接后，按照打包模型部分中的说明生成模型包。在以下示例中，程序包的基础环境使用 Python 依赖项 bar 的专用源，如以下 conda 文件中所指定：

conda.yml

name: foo
channels:
  - defaults
dependencies:
  - python
  - pip
  - pip:
    - --extra-index-url <python_feed_url>
    - bar

如果使用的是 MLflow 模型，模型依赖性会在模型本身内部指示，因此不需要基础环境。相反，请在记录模型时指定专用源依赖项，如使用自定义签名、环境或示例记录模型中所述。

打包注册表中托管的模型

模型包提供了在部署之前收集依赖项的便捷方法。但是，当模型托管在注册表中时，部署目标通常是另一个工作区。在此设置中创建包时，请使用 target_environment 属性指定要创建模型包的完整位置，而不仅仅是其名称。

以下代码从注册表创建 t5-base 模型的包：

连接到模型所在的注册表以及需要在其中创建模型包的工作区：

Azure CLI
Python

az login
 Connect-AzAccount -Environment AzureChinaCloud

 registry_client = MLClient(
	credential=DefaultAzureCredential(),
	subscription_id=ml_client.subscription_id,
	resource_group_name=ml_client.resource_group_name,
	workspace_reference=ml_client.workspace_name,
	registry_name=registry_name,
 )

获取对要打包的模型的引用。在本例中，我们将从 azureml 注册表中打包模型 t5-base。

Azure CLI
Python

 MODEL_NAME="t5-base"
 MODEL_VERSION=$(az ml model show --name $MODEL_NAME --label latest --registry-name azureml | jq .version -r)

 model_name = "t5-base"
 model = registry_client.models.get(name=model_name, label="latest")

创建包规格。由于要打包的模型是 MLflow，因此基础环境和评分脚本是可选的。

Azure CLI
Python

package.yml

 $schema: http://azureml/sdk-2-0/ModelVersionPackage.json
 target_environment: pkg-t5-base-online
 inferencing_server: 
	type: azureml_online

 import time

 model_package_name = f"pkg-{model.name}-{model.version}"
 model_package_version = str(int(time.time()))

 package_config = ModelPackage(
	target_environment_name=model_package_name,
	target_environment_version=model_package_version,
	inferencing_server=AzureMLOnlineInferencingServer(),
 )

启动创建模型包的操作：

Azure CLI
Python

 #<get_model>
 MODEL_NAME="t5-base"
 MODEL_VERSION=$(az ml model show --name $MODEL_NAME --label latest --registry-name azureml | jq .version -r)
 #</get_model>

 #<build_package>
 az ml model package --name $MODEL_NAME \
                     --version $MODEL_VERSION \
                     --registry-name azureml \
                     --file package.yml
 #</build_package>

 model_package = registry_client.models.package(
	model.name, model.version, package_config
 )

现在，该包已在目标工作区中创建并准备好部署。

用于在 Azure 机器学习外部部署的包模型

如果需要，可以将模型包部署在 Azure 机器学习之外。为了保证可移植性，只需确保包中的模型配置将模式设置为 copy，以便将模型本身复制到生成的 docker 映像中，而不是从模型注册表中引用 Azure 机器学习。

以下代码演示如何在模型包中配置 copy：

Azure CLI
Python

package-external.yml

$schema: http://azureml/sdk-2-0/ModelVersionPackage.json
base_environment_source:
    type: environment_asset
    resource_id: azureml:sklearn-regression-env:1
target_environment: sklearn-regression-docker-pkg
inferencing_server: 
    type: azureml_online
    code_configuration:
      code: src
      scoring_script: score.py
model_configuration:
  mode: copy

pakage_config = ModelPackage(
    target_environment_name="sklearn-regression-online-pkg",
    base_environment_source=BaseEnvironment(
        type="asset",
        resource_id=f"azureml:{base_environment.name}:{base_environment.version}",
    ),
    inferencing_server=AzureMLOnlineInferencingServer(
        code_configuration=CodeConfiguration(code="src", scoring_script="score.py")
    ),
    model_configuration=ModelConfiguration(mode="copy"),
)

通过