部署使用部署模板的模型

本文介绍如何部署将部署模板固定到托管联机终结点的注册表模型。当模型有一个 default_deployment_template时，部署 YAML 只需引用模型 - 部署模板会提供环境、环境变量、评分端口和探测。还可以使用另一个部署模板替代默认值。模型的 allowed_deployment_templates 列表是作者精心整理的一组经过验证的覆盖项，供用户选择——它仅起指导作用，并非强制性限制。

注释

本文档中详细介绍的 YAML 语法基于最新版本的 ML CLI v2 扩展的 JSON 架构。此语法必定仅适用于最新版本的 ML CLI v2 扩展。可以在 https://azuremlschemasprod.azureedge.net/ 上查找早期扩展版本的架构。

先决条件

一份 Azure 订阅。如果没有试用版，请创建一个试用版。
一个 Azure 机器学习工作区。有关详细信息，请参阅管理 Azure 机器学习工作区。
对包含设置了 default_deployment_template 的模型的 Azure 机器学习注册表的读取权限。有关发布此类模型的信息，请参阅使用部署模板管理模型。
Azure CLI 和 ml 扩展均已安装并已登录。有关详细信息，请参阅安装和使用 CLI（v2）。
在工作区中创建终结点和部署的权限。此 AzureML 数据科学家 角色足以满足本文要求。

步骤 1：查找使用部署模板的模型

检查注册表中的模型，确认该模型有一个 default_deployment_template，并查看哪些其他部署模板位于其中 allowed_deployment_templates。

模型的defaultDeploymentTemplate和allowedDeploymentTemplates由注册表数据平面返回，你可以通过注册表的资源提供程序主机访问该数据平面。 Azure 资源管理器（management.chinacloudapi.cn）模型 GET 不包含这些字段。首先使用一次性发现调用查找数据平面主机，然后从中获取模型版本。

TOKEN=$(az account get-access-token --resource https://management.chinacloudapi.cn --query accessToken -o tsv)

RP_HOST=$(curl -s \
  "https://<your-region>.api.azureml.ms/registrymanagement/v1.0/registries/<your-registry>/discovery?api-version=v1.0" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.primaryRegionResourceProviderUri')

curl -X GET \
  "${RP_HOST%/}/mferp/managementfrontend/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/registries/<your-registry>/models/my-model/versions/1?api-version=2021-10-01-dataplanepreview" \
  -H "Authorization: Bearer $TOKEN"

在响应中查找 properties.defaultDeploymentTemplate.assetId 和 properties.allowedDeploymentTemplates[].assetId。

az ml model show \
  --name my-model --version 1 \
  --registry-name <your-registry>

在输出中查找 default_deployment_template.asset_id 和 allowed_deployment_templates[].asset_id。

from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

registry_client = MLClient(
    credential=DefaultAzureCredential(),
    registry_name="<your-registry>",
)

model = registry_client.models.get(name="my-model", version="1")
print(model.default_deployment_template)
print(model.allowed_deployment_templates)

步骤 2：创建联机终结点

使用联机终结点 - 创建或更新操作：

TOKEN=$(az account get-access-token --resource https://management.chinacloudapi.cn --query accessToken -o tsv)

curl -X PUT \
  "https://management.chinacloudapi.cn/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-workspace>/onlineEndpoints/my-endpoint?api-version=2023-04-01-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "<your-region>",
    "identity": { "type": "SystemAssigned" },
    "properties": {
      "authMode": "Key"
    }
  }'

az ml online-endpoint create --name my-endpoint \
  --workspace-name <your-workspace> \
  --resource-group <your-resource-group>

from azure.ai.ml import MLClient
from azure.ai.ml.entities import ManagedOnlineEndpoint
from azure.identity import DefaultAzureCredential

ws_client = MLClient(
    credential=DefaultAzureCredential(),
    subscription_id="<your-subscription-id>",
    resource_group_name="<your-resource-group>",
    workspace_name="<your-workspace>",
)

ws_client.online_endpoints.begin_create_or_update(
    ManagedOnlineEndpoint(name="my-endpoint")
).result()

步骤 3：使用模型的默认部署模板进行部署

当模型有一个 default_deployment_template时，部署模板会提供基础结构设置，例如 environment，请求设置和探测。部署有效负载仍必须包含底层 ARM 资源所需的 SKU/实例配置。

使用联机部署 - 创建或更新操作。将以下 JSON 另存为 deployment-default.json。 ARM 资源需要顶级 sku 块（name 和 capacity），并且 properties.endpointComputeType 必须是 Managed。 properties.model 引用指向注册表模型，其默认部署模板提供环境、请求设置和探测配置。

{
  "name": "blue",
  "endpointName": "my-endpoint",
  "tags": {},
  "location": "<your-region>",
  "properties": {
    "environmentVariables": {},
    "properties": {},
    "appInsightsEnabled": false,
    "endpointComputeType": "Managed",
    "instanceType": "Standard_DS3_v2",
    "model": "azureml://registries/<your-registry>/models/my-model/versions/1"
  },
  "sku": {
    "name": "Default",
    "capacity": 1
  }
}

TOKEN=$(az account get-access-token --resource https://management.chinacloudapi.cn --query accessToken -o tsv)

curl -X PUT \
  "https://management.chinacloudapi.cn/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-workspace>/onlineEndpoints/my-endpoint/deployments/blue?api-version=2023-04-01-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @deployment-default.json

将以下 YAML 另存为 deployment-default.yml：

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model: azureml://registries/<your-registry>/models/my-model/versions/1
instance_type: Standard_DS3_v2
instance_count: 1

az ml online-deployment create -f deployment-default.yml --all-traffic \
  --workspace-name <your-workspace> \
  --resource-group <your-resource-group>

from azure.ai.ml.entities import ManagedOnlineDeployment

deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name="my-endpoint",
    model="azureml://registries/<your-registry>/models/my-model/versions/1",
    instance_type="Standard_DS3_v2",
    instance_count=1,
)
ws_client.online_deployments.begin_create_or_update(deployment).result()

步骤 4：（可选）使用替代部署模板进行部署

若要使用与模型默认值不同的部署模板，请在部署上指定替代。模型 allowed_deployment_templates 列表是作者精选的一组经过验证的替代模板可供选择;它是指导，而不是强制限制，因此平台不会阻止不在列表中的替代。替代部署可以是同一终结点下的单独部署，因此步骤 3 中的部署会一直为流量提供服务，直到更新终结点的流量分配。

在 REST API 中，使用 properties.properties 键在嵌套的 azureml.deploymentTemplateOverride 包中设置覆盖项。将以下 JSON 保存为 deployment-override.json：

{
  "name": "green",
  "endpointName": "my-endpoint",
  "tags": {},
  "location": "<your-region>",
  "properties": {
    "environmentVariables": {},
    "properties": {
      "azureml.deploymentTemplateOverride": "azureml://registries/<your-registry>/deploymenttemplates/my-deployment-template2/versions/1"
    },
    "appInsightsEnabled": false,
    "endpointComputeType": "Managed",
    "instanceType": "Standard_DS3_v2",
    "model": "azureml://registries/<your-registry>/models/my-model/versions/1"
  },
  "sku": {
    "name": "Default",
    "capacity": 1
  }
}

TOKEN=$(az account get-access-token --resource https://management.chinacloudapi.cn --query accessToken -o tsv)

curl -X PUT \
  "https://management.chinacloudapi.cn/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-workspace>/onlineEndpoints/my-endpoint/deployments/green?api-version=2023-04-01-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @deployment-override.json

在 YAML 中，将 properties."azureml.deploymentTemplateOverride" 设置为覆盖项的注册表资产 URI。将以下 YAML 另存为 deployment-override.yml：

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: green
endpoint_name: my-endpoint
model: azureml://registries/<your-registry>/models/my-model/versions/1
instance_type: Standard_DS3_v2
instance_count: 1
properties:
  azureml.deploymentTemplateOverride: azureml://registries/<your-registry>/deploymenttemplates/my-deployment-template2/versions/1

az ml online-deployment create -f deployment-override.yml \
  --workspace-name <your-workspace> \
  --resource-group <your-resource-group>

deployment = ManagedOnlineDeployment(
    name="green",
    endpoint_name="my-endpoint",
    model="azureml://registries/<your-registry>/models/my-model/versions/1",
    instance_type="Standard_DS3_v2",
    instance_count=1,
    properties={
        "azureml.deploymentTemplateOverride": (
            "azureml://registries/<your-registry>/deploymenttemplates/my-deployment-template2/versions/1"
        ),
    },
)
ws_client.online_deployments.begin_create_or_update(deployment).result()

步骤 5：调用终结点

向部署发送评分请求。这些示例针对第 3 步中的 blue 部署。若要改为调用第 4 步中的覆盖部署，请将 blue 替换为 green。

对于来自使用部署模板管理模型的 TF Serving 部署模板，请求载荷采用标准的 TF Serving REST 格式。将以下内容另存为 request.json：

{ "instances": [1.0, 2.0, 5.0] }

获取评分 URI 和密钥，然后将 POST 请求有效负载发送到评分 URI。对于 TF 服务部署模板，评分路径为 /v1/models/half_plus_two:predict。有关详细信息，请参阅调用终结点以使用模型对数据进行评分。

SCORING_URI=$(az ml online-endpoint show --name my-endpoint --query scoring_uri -o tsv \
  --workspace-name <your-workspace> --resource-group <your-resource-group>)
KEY=$(az ml online-endpoint get-credentials --name my-endpoint --query primaryKey -o tsv \
  --workspace-name <your-workspace> --resource-group <your-resource-group>)

curl -X POST "$SCORING_URI" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

az ml online-endpoint invoke --name my-endpoint \
  --deployment-name blue \
  --workspace-name <your-workspace> \
  --resource-group <your-resource-group> \
  --request-file request.json

result = ws_client.online_endpoints.invoke(
    endpoint_name="my-endpoint",
    deployment_name="blue",
    request_file="request.json",
)
print(result)

响应是 TF 服务预测响应，例如： { "predictions": [2.5, 3.0, 4.5] }

步骤 6：更新或删除部署

若要更改流量分配、缩放部署或删除它，请使用标准托管联机终结点命令。部署模板不会更改这些操作。若要将实时流量切换到步骤 4 中的覆盖部署，请在流量更新中将 blue=100 替换为 green=100。

az ml online-endpoint update --name my-endpoint \
  --traffic "blue=100" \
  --workspace-name <your-workspace> \
  --resource-group <your-resource-group>

az ml online-deployment delete --name blue --endpoint-name my-endpoint \
  --workspace-name <your-workspace> \
  --resource-group <your-resource-group>

Troubleshooting

此部署模板不允许实例类型。 你在该部署中设置的 instance_type 不在部署模板的 allowed_instance_types 列表中。用于 az ml deployment-template show 列出允许的实例类型，然后将其设置为 instance_type 其中一种。
该环境不是注册表范围内的引用。 部署模板必须引用具有 azureml://registries/<registry-name>/environments/<name>/versions/<version> 语法的环境。先将工作区环境共享到注册表中，再引用它们。

Last updated on 2026-07-09