建立模型套件 (預覽)

發行項
03/20/2024

模型套件是 Azure Machine Learning 中的一項功能，能讓您收集所有必要的相依性，以將機器學習模型部署到服務平台。在部署模型之前先建立封裝，可提供穩健可靠的部署，以及更有效率的 MLOps 工作流程。套件可以跨工作區移動，甚至可以移動到 Azure Machine Learning 以外的地方。

重要

此功能目前處於公開預覽。此預覽版本沒有服務等級協定，不建議用於處理生產工作負載。可能不支援特定功能，或可能已經限制功能。

如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

在本文中，您將了解如何封裝模型以進行部署。

必要條件

遵循本文中的步驟之前，請確定您已滿足下列必要條件：

Azure 訂用帳戶。如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。試用免費或付費版本的 Azure Machine Learning。
Azure Machine Learning 工作區。如果您沒有工作區，請依照如何管理工作區一文的步驟建立。
Azure 角色型存取控制 (Azure RBAC) 可用來授與 Azure Machine Learning 作業的存取權。若要執行本文中的步驟，您的使用者帳戶必須獲指派 Azure Machine Learning 工作區的擁有者或參與者角色，或自訂角色。如需詳細資訊，請參閱管理對 Azure Machine Learning 工作區的存取。

關於此範例

在此範例中，您將了解如何在 Azure Machine Learning 中封裝模型。

複製存放庫

本文中的範例是以 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 Machine Learning 工作區連線。

Azure CLI
Python

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

工作區是 Azure Machine Learning 的最上層資源，其提供一個集中位置來處理您在使用 Azure Machine Learning 時建立的所有成品。本節將帶您與要執行部署工作的工作區連線。

匯入必要的程式庫：

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 Machine Learning 中的計算執行個體中執行，請依指示建立 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 Machine Learning 以外的位置部署模型套件。
您想要在 MLOps 工作流程中使用模型套件。

您可以透過指定下列設定來建立模型套件：

封裝模型：每個模型封裝只能包含單一模型。 Azure Machine Learning 不支援將多個模型封裝在同一個模型封裝。
基礎環境：環境用於指示基礎映像，以及模型所需的 Python 封裝相依性。若使用 MLflow 模型，Azure Machine Learning 會自動產生基礎環境。若使用自訂模型，您必須自行指定。
服務技術：用來執行模型的推斷堆疊。

註冊模型

模型套件要求在您的工作區或 Azure Machine Learning 登錄中註冊模型。在這個範例中，您的存放庫已有模型的本機複本，所以你只要在工作區的登錄中發佈模型即可。如果您已註冊嘗試部署的模型，可以跳過這個步驟。

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 Machine Learning SDK，在 Azure Machine Learning 中建立模型套件。自訂套件規格支援下列屬性：

Azure CLI
Python

屬性	類型	描述	必要
`target_environment`	`str`	要建立之套件的名稱。封裝作業的結果是 Azure Machine Learning 中的環境。	Yes
`base_environment_source`	`object`	要用來建立套件的基底映像，其中已指定模型的相依性。	是，除非模型是 MLflow。
`base_environment_source.type`	`str`	基底映像的類型。只使用另一個環境，因為基底映像 (`type: environment_asset`) 受到支援。
`base_environment_source.resource_id`	`str`	要使用之基礎環境的資源識別碼。使用 `azureml:<name>:<version>` 格式或完整資源識別碼。
`inferencing_server`	`object`	要使用的推斷伺服器。	Yes
`inferencing_server.type`	`azureml_online` `custom`	針對 Azure Machine Learning 推斷伺服器使用 `azureml_online`，針對 TensorFlow serving 或 Torch Serve 等自訂線上伺服器則使用 `custom`。	Yes
`inferencing_server.code_configuration`	`object`	具有推斷常式的程式碼設定。其應該包含至少一個具有 `init` 和 `run` 方法的 Python 檔案。	是，除非模型是 MLflow。
`model_configuration`	`object`	模型設定。使用此屬性來控制所產生映像中的模型封裝方式。	No
`model_configuration.mode`	`download` `copy`	指出模型會如何置於套件中。可能的值為 `download` (預設) 和 `copy`。當您想要在部署期間從模型登錄下載模型時，請使用 `download`。此選項能建立較小的 Docker 映像，因為其上方並未包括模型。當您想要將映像與 Azure Machine Learning 中斷連線時，請使用 `copy`。系統將不會在封裝期間將模型複製到 Docker 映像內。已啟用私人連結的工作區不支援 `copy`。	No

屬性	類型	描述	必要
`target_environment`	`str`	要建立之套件的名稱。封裝作業的結果是 Azure Machine Learning 中的環境。	Yes
`base_environment_source`	`BaseEnvironment`	要用來建立套件的基底映像，其中已指定模型的相依性。	是，除非模型類型是 MLflow。
`base_environment_source.type`	`BaseEnvironmentType`	基底映像的類型。僅使用另一個環境 (`EnvironmentAsset`)，因為基底映像受到支援。
`base_environment_source.resource_id`	`str`	要使用之基礎環境的資源識別碼。使用 `azureml:<name>:<version>` 格式或完整格式資源識別碼。
`inferencing_server`	`AzureMLOnlineInferencingServer` `CustomOnlineInferenceServer`	要使用的推斷伺服器。針對 Azure Machine Learning 推斷伺服器使用 `AzureMLOnlineInferencingServer`，針對 TensorFlow serving、Torch Serve 等自訂線上伺服器則使用 `CustomOnlineInferenceServer`。若設定為 `AzureMLInferencingServer`，且模型類型不是 Mlflow，應指定程式碼設定區段，其中至少包含一個具有 `init` 和 `run` 方法的 Python 檔案。若設定為 `CustomOnlineInferenceServer`，應指定線上伺服器設定區段。	Yes
`model_configuration`	`ModelConfiguration`	模型設定。使用此屬性來控制所產生映像中的模型封裝方式。	No
`model_configuration.mode`	`ModelInputMode`	指定模型會如何置於套件中。可能的值為 `ModelInputMode.DOWNLOAD` (預設) 和 `ModelInputMode.COPY`。當您想要在部署期間從模型登錄下載模型時，請使用 `ModelInputMode.DOWNLOAD`。此選項能建立較小的 Docker 映像，因為其上方並未包括模型。當您想要將映像與 Azure Machine Learning 中斷連線時，請使用 `ModelInputMode.COPY`。系統將不會在封裝期間將模型複製到 Docker 映像內。已啟用私人連結的工作區不支援 `ModelInputMode.COPY`。	No

建立套件規格，如下所示：

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="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")
    ),
)

啟動模型封裝作業：

Azure CLI
Python

az ml model package -n $MODEL_NAME -v $MODEL_VERSION --file package-moe.yml

model_package = ml_client.models.package(model_name, model.version, pakage_config)

封裝作業的結果是環境。

封裝在私人 Python 摘要中具有相依性的模型

模型套件可以解析在私人摘要中提供的 Python 相依性。若要使用這項功能，您必須從工作區建立與摘要的連線，並指定 PAT 令牌組態。下列 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

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=model_package_name,
    target_environment_version=model_package_version,
    inferencing_server=AzureMLOnlineInferencingServer(),
)

啟動作業以建立模型套件：

Azure CLI
Python

az ml model package --name $MODEL_NAME \
                    --version $MODEL_VERSION \
                    --registry-name azureml \
                    --file package.yml

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

該套件現已在目標工作區中建立，且已準備好進行部署。

封裝模型以在 Azure Machine Learning 以外的位置部署

若有必要，可以在 Azure Machine Learning 以外的位置部署模型套件。若要保證可攜性，您只需要確保套件中的模型設定已將模式設定為 copy，以將模型本身複製到產生的 Docker 映像內，而不是從 Azure Machine Learning 中的模型登錄加以參考。

下列程式碼會示範如何設定模型套件中的 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="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"),
)

後續步驟

封裝並將模型部署至線上端點 (部分機器翻譯)。
封裝並將模型部署至 App Service (部分機器翻譯)。