驗證線上端點的用戶端

  • 發行項

適用於：Azure CLI ml 延伸模組 v2 (目前)Python SDK azure-ai-ml v2 (目前)

本文說明如何驗證用戶端，以在線上端點執行控制平面和資料平面作業。

控制平面作業會控制端點並加以變更。 控制平面作業包括線上端點和線上部署的建立、讀取、更新及刪除 (CRUD) 作業。

資料平面作業會使用資料與線上端點互動，而不會變更端點。 例如，資料平面作業可能包含將評分要求傳送至線上端點並取得回應。

必要條件

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

限制

具有 Microsoft Entra 權杖 (aad_token) 驗證模式的端點不支援使用 CLI az ml online-endpoint invoke、SDK ml_client.online_endpoints.invoke() 或 Azure Machine Learning 工作室的 [測試] 或 [取用] 索引標籤進行評分。 請改用泛型 Python SDK 或使用 REST API 傳遞控制平面權杖。 如需詳細資訊，請參閱使用金鑰或權杖為資料評分。

準備使用者身分識別

您需要使用者身分識別，才能在線上端點執行控制平面作業 (也就是 CRUD 作業) 和資料平面作業 (也就是傳送評分要求)。 您可以針對控制平面和資料平面作業使用相同的使用者身分識別或不同的使用者身分識別。 在本文中，您會針對控制平面和資料平面作業使用相同的使用者身分識別。

若要在 Microsoft Entra ID 下建立使用者身分識別，請參閱設定驗證。 您稍後需要身分識別識別碼。

對身分識別指派權限

在本節中，您會將權限指派給您用來與端點互動的使用者身分識別。 您可以從使用內建角色或建立自訂角色開始。 然後您會將角色指派給使用者身分識別。

使用內建角色

AzureML Data Scientist內建角色可用來管理及使用端點和部署，其使用萬用字元來包含下列控制平面 RBAC 動作：

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action

以及包含下列資料平面 RBAC 動作：

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action

Azure Machine Learning Workspace Connection Secrets Reader 內建角色可選擇性地用來從工作區連線存取祕密，且其包含下列控制平面 RBAC 動作：

  • Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action
  • Microsoft.MachineLearningServices/workspaces/metadata/secrets/read

如果您使用這些內建角色，則此步驟不需要採取任何動作。

(選擇性) 建立自訂角色

如果您使用內建角色或其他預先建立的自訂角色，則可以略過此步驟。

  1. 藉由建立角色的 JSON 定義，定義自訂角色的範圍和動作。 例如，下列角色定義可讓使用者在指定工作區下，對線上端點執行 CRUD。

    custom-role-for-control-plane.json：

    {
    "Name": "Custom role for control plane operations - online endpoint",
    "IsCustom": true,
    "Description": "Can CRUD against online endpoints.",
    "Actions": [
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action",
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action"
    ],
    "NotActions": [
    ],
    "AssignableScopes": [
        "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>"
    ]
}

    下列角色定義可讓使用者在指定工作區下，將評分要求傳送給線上端點。

    custom-role-for-scoring.json：

    {
    "Name": "Custom role for scoring - online endpoint",
    "IsCustom": true,
    "Description": "Can score against online endpoints.",
    "Actions": [
        "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*/action"
    ],
    "NotActions": [
    ],
    "AssignableScopes": [
        "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>"
    ]
}

  2. 使用 JSON 定義來建立自訂角色：

    az role definition create --role-definition custom-role-for-control-plane.json --subscription <subscriptionId>

az role definition create --role-definition custom-role-for-scoring.json --subscription <subscriptionId>

    注意

    若要建立自訂角色，您需要以下三個角色其中之一：

    • 擁有者
    • 使用者存取管理員
    • 具有 Microsoft.Authorization/roleDefinitions/write 權限 (可建立/更新/刪除自訂角色) 的自訂角色，以及 Microsoft.Authorization/roleDefinitions/read 權限 (可檢視自訂角色) 的自訂角色。

    如需建立自訂角色的詳細資訊，請參閱 Azure 自訂角色。

  3. 驗證角色定義：

    az role definition list --custom-role-only -o table

az role definition list -n "Custom role for control plane operations - online endpoint"
az role definition list -n "Custom role for scoring - online endpoint"

export role_definition_id1=`(az role definition list -n "Custom role for control plane operations - online endpoint" --query "[0].id" | tr -d '"')`

export role_definition_id2=`(az role definition list -n "Custom role for scoring - online endpoint" --query "[0].id" | tr -d '"')`

將角色指派給身分識別

  1. 如果您使用 AzureML Data Scientist 內建角色，請使用下列程式碼將角色指派給使用者身分識別。

    az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

  2. 如果您使用 Azure Machine Learning Workspace Connection Secrets Reader 內建角色，請選擇性地使用下列程式碼將角色指派給使用者身分識別。

    az role assignment create --assignee <identityId> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

  3. 如果您使用自訂角色，請使用下列程式碼將角色指派給使用者身分識別。

    az role assignment create --assignee <identityId> --role "Custom role for control plane operations - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

az role assignment create --assignee <identityId> --role "Custom role for scoring - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

    注意

    若要將自訂角色指派給使用者身分識別，您需要以下三個角色其中之一：

    • 擁有者
    • 使用者存取管理員
    • 允許 Microsoft.Authorization/roleAssignments/write 權限 (指派自訂角色) 和 Microsoft.Authorization/roleAssignments/read (檢視角色指派) 的自訂角色。

    如需不同 Azure 角色及其權限的詳細資訊，請參閱使用 Azure 角色和使用 Azure 入口網站指派 Azure 角色。

  4. 確認角色指派：

    az role assignment list --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

取得控制平面作業的 Microsoft Entra 權杖

如果您打算使用 REST API 執行控制平面作業，則執行此步驟，這會直接使用權杖。

如果您打算使用其他方式，例如 Azure Machine Learning CLI (v2)、Python SDK (v2) 或 Azure Machine Learning 工作室，則不需要手動取得 Microsoft Entra 權杖。 相反地，在登入期間，您的使用者身分識別已經通過驗證，而且會自動為您擷取和傳遞權杖。

您可以從 Azure 資源端點為控制平面擷取 Microsoft Entra 權杖：https://management.azure.com。

  1. 登入Azure。

    az login

  2. 如果您想要使用特定身分識別，請使用下列程式碼以身分識別登入：

    az login --identity --username <identityId>

  3. 使用此內容來取得權杖。

    export CONTROL_PLANE_TOKEN=`(az account get-access-token --resource https://management.azure.com --query accessToken | tr -d '"')`

(選擇性) 確認 Microsoft Entra 權杖的資源端點和用戶端識別碼

擷取 Microsoft Entra 權杖之後，您可以透過 jwt.ms 解碼權杖 (這會傳回 JSON 回應並提供下列資訊)，以驗證權杖是否適用於正確的 Azure 資源端點 management.azure.com 和正確的用戶端識別碼：

{
    "aud": "https://management.azure.com",
    "oid": "<your-object-id>"
}

建立端點

下列範例會建立具有系統指派的身分識別 (SAI) 作為端點身分識別的端點。 SAI 是端點受控識別的預設身分識別類型。 某些基本角色會自動指派給 SAI。 如需系統指派的身分識別角色指派的詳細資訊，請參閱端點身分識別的自動角色指派。

CLI 不需要您明確提供控制平面權杖。 相反地，CLI 會在登入期間對您進行驗證，而且會自動為您擷取並傳遞權杖。

  1. 建立端點定義 YAML 檔案。

    endpoint.yml：

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: aad_token

  2. 您可以針對金鑰驗證將 auth_mode 取代為 key，或針對 Azure Machine Learning 權杖驗證取代為 aml_token。在此範例中，您會針對 Microsoft Entra 權杖驗證使用 aad_token。

    az ml online-endpoint create -f endpoint.yml

  3. 檢查端點的狀態：

    az ml online-endpoint show -n my-endpoint

  4. 如果您想要在建立端點時覆寫 auth_mode (例如覆寫為 aad_token)，請執行下列程式碼：

    az ml online-endpoint create -n my-endpoint --auth_mode aad_token

  5. 如果您要更新現有的端點並指定 auth_mode (例如，指定為 aad_token)，請執行下列程式碼：

    az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token

建立部署

若要建立部署，請參閱使用線上端點部署 ML 模型或使用 REST 將模型部署為線上端點。 針對不同驗證模式建立部署的方式並無不同。

以下程式碼為示範如何建立部署的範例。 如需部署線上端點的詳細資訊，請參閱使用線上端點部署 ML 模型 (透過 CLI)

  1. 建立部署定義 YAML 檔案。

    blue-deployment.yml：

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-aad-auth-endp1
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

  2. 使用 YAML 檔案建立部署。 針對此範例，將所有流量設定為前往新部署。

    az ml online-deployment create -f blue-deployment.yml --all-traffic

取得端點的評分 URI

如果您打算使用 CLI 來叫用端點，則不需要明確地取得評分 URI，因為 CLI 會為您處理。 不過，您仍然可以使用 CLI 來取得評分 URI，以便將其與其他通道搭配使用，例如 REST API。

scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")

取得資料平面作業的金鑰或權杖

金鑰或權杖可用於資料平面作業，即使取得金鑰或權杖的程序是控制平面作業也一樣。 換句話說，您可以使用控制平面權杖來取得您稍後用來執行資料平面作業的金鑰或權杖。

取得金鑰或 Azure Machine Learning 權杖需要將正確的角色指派給提出要求的使用者身分識別，如控制平面作業的授權中所述。 使用者身分識別不需要任何額外的角色，即可取得 Microsoft Entra 權杖。

金鑰或 Azure Machine Learning 權杖

如果您打算使用 CLI 來叫用端點，而且端點已設定為使用金鑰或 Azure Machine Learning 權杖的驗證模式 (aml_token)，則不需要明確取得資料平面權杖，因為 CLI 會為您處理。 不過，您仍然可以使用 CLI 來取得資料平面權杖，以便將其與其他通道搭配使用，例如 REST API。

若要取得金鑰或 Azure Machine Learning 權杖 (aml_token)，請使用 az ml online-endpoint get-credentials 命令。 此命令會傳回包含金鑰或 Azure Machine Learning 權杖的 JSON 文件。

金鑰會在 primaryKey 和 secondaryKey 欄位中傳回。 下列範例示範如何使用 --query 參數只傳回主索引鍵：

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)

Azure Machine Learning 權杖會在 accessToken 欄位中傳回：

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)

此外，expiryTimeUtc 和 refreshAfterTimeUtc 欄位也包含權杖到期和重新整理時間。

Microsoft Entra 權杖

若要使用 CLI 取得 Microsoft Entra 權杖 (aad_token)，請使用 az account get-access-token 命令。 此命令會傳回包含 Microsoft Entra 權杖的 JSON 文件。

Microsoft Entra 權杖會在 accessToken 欄位中傳回：

export DATA_PLANE_TOKEN=`(az account get-access-token --resource https://ml.azure.com --query accessToken | tr -d '"')`

注意

  • CLI ml 延伸模組不支援取得 Microsoft Entra 權杖。 請改用 az account get-access-token，如先前的程式碼所述。
  • 資料平面作業的權杖會從 Azure 資源端點 ml.azure.com 擷取，而不是從 management.azure.com 擷取，不同於控制平面作業的權杖。

確認 Microsoft Entra 權杖的資源端點和用戶端識別碼

取得 Entra 權杖之後，您可以透過 jwt.ms 解碼權杖 (這會傳回 JSON 回應並提供下列資訊)，以驗證權杖是否適用於正確的 Azure 資源端點 ml.azure.com 和正確的用戶端識別碼：

{
    "aud": "https://ml.azure.com",
    "oid": "<your-object-id>"
}

使用金鑰或權杖為資料評分

金鑰或 Azure Machine Learning 權杖

您可以搭配金鑰或 Azure Machine Learning 權杖使用端點的 az ml online-endpoint invoke。 CLI 會自動處理金鑰或 Azure Machine Learning 權杖，因此您不需要明確傳遞金鑰。

az ml online-endpoint invoke -n my-endpoint -r request.json

Microsoft Entra 權杖

不支援針對具有 Microsoft Entra 權杖的端點使用 az ml online-endpoint invoke。 請改用 REST API，並使用端點的評分 URI 來叫用端點。

記錄和監視流量

若要在端點的診斷設定中啟用流量記錄，請遵循如何啟用/停用記錄中的步驟。

如果已啟用診斷設定，您可以檢查 AmlOnlineEndpointTrafficLogs 資料表以查看驗證模式和使用者身分識別。

相關內容