Clients verifiëren voor online-eindpunten

  • Artikel

VAN TOEPASSING OP:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

In dit artikel wordt beschreven hoe u clients verifieert voor het uitvoeren van besturingsvlak- en gegevensvlakbewerkingen op online-eindpunten.

Een besturingsvlak bepaalt een eindpunt en wijzigt het. Besturingsvlakbewerkingen zijn onder andere CRUD-bewerkingen (create, read, update, delete) op online-eindpunten en onlineimplementaties.

Een gegevensvlakbewerking maakt gebruik van gegevens om te communiceren met een online-eindpunt zonder het eindpunt te wijzigen. Een gegevensvlakbewerking kan bijvoorbeeld bestaan uit het verzenden van een scoreaanvraag naar een online-eindpunt en het ophalen van een antwoord.

Vereisten

Voordat u de stappen in dit artikel volgt, moet u ervoor zorgen dat u over de volgende vereisten beschikt:

  • Een Azure Machine Learning-werkruimte. Als u er nog geen hebt, gebruikt u de stappen in de quickstart: artikel Werkruimtebronnen maken om er een te maken.

  • De Azure CLI en de ml extensie of de Azure Machine Learning Python SDK v2:

    • Zie De CLI (v2) installeren, instellen en gebruiken om de Azure CLI en extensie te installeren.

      Belangrijk

      In de CLI-voorbeelden in dit artikel wordt ervan uitgegaan dat u de Bash-shell (of compatibele) shell gebruikt. Bijvoorbeeld vanuit een Linux-systeem of Windows-subsysteem voor Linux.

    • Gebruik de volgende opdracht om de Python SDK v2 te installeren:

      pip install azure-ai-ml azure-identity

      Gebruik de volgende opdracht om een bestaande installatie van de SDK bij te werken naar de nieuwste versie:

      pip install --upgrade azure-ai-ml azure-identity

      Zie De Python SDK v2 voor Azure Machine Learning installeren voor meer informatie.

Beperkingen

Eindpunten met microsoft Entra-token (aad_token)-verificatiemodus bieden geen ondersteuning voor scoren met behulp van de CLIaz ml online-endpoint invoke, SDK ml_client.online_endpoints.invoke()of de tabbladen Testen of Gebruiken van de Azure Machine Learning-studio. Gebruik in plaats daarvan een algemene Python SDK of gebruik REST API om het token voor het besturingsvlak door te geven. Zie Scoregegevens met behulp van de sleutel of het token voor meer informatie.

Een gebruikersidentiteit voorbereiden

U hebt een gebruikersidentiteit nodig voor het uitvoeren van besturingsvlakbewerkingen (dat wil gezegd CRUD-bewerkingen) en gegevensvlakbewerkingen (dat wil gezegd scoreaanvragen verzenden) op het online-eindpunt. U kunt dezelfde gebruikersidentiteit of verschillende gebruikersidentiteiten gebruiken voor de besturingsvlak- en gegevensvlakbewerkingen. In dit artikel gebruikt u dezelfde gebruikersidentiteit voor bewerkingen op het besturingsvlak en het gegevensvlak.

Zie Verificatie instellen als u een gebruikersidentiteit wilt maken onder Microsoft Entra-id. U hebt de id later nodig.

Machtigingen toewijzen aan de identiteit

In deze sectie wijst u machtigingen toe aan de gebruikersidentiteit die u gebruikt voor interactie met het eindpunt. U begint met het gebruik van een ingebouwde rol of door een aangepaste rol te maken. Daarna wijst u de rol toe aan uw gebruikersidentiteit.

Een ingebouwde rol gebruiken

De AzureML Data Scientistingebouwde rol kan worden gebruikt voor het beheren en gebruiken van eindpunten en implementaties en maakt gebruik van jokertekens om de volgende RBAC-acties voor het besturingsvlak op te nemen:

  • 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

en om de volgende RBAC-actie voor het gegevensvlak op te nemen:

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

De ingebouwde rol kan eventueel Azure Machine Learning Workspace Connection Secrets Reader worden gebruikt voor toegang tot geheimen vanuit werkruimteverbindingen en bevat de volgende RBAC-acties voor het besturingsvlak :

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

Als u deze ingebouwde rollen gebruikt, is er geen actie nodig bij deze stap.

(Optioneel) Een aangepaste rol maken

U kunt deze stap overslaan als u ingebouwde rollen of andere vooraf gemaakte aangepaste rollen gebruikt.

  1. Definieer het bereik en de acties voor aangepaste rollen door JSON-definities van de rollen te maken. Met de volgende roldefinitie kan de gebruiker bijvoorbeeld een online-eindpunt onder een opgegeven werkruimte CRUD gebruiken.

    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>"
    ]
}

    Met de volgende roldefinitie kan de gebruiker scoreaanvragen verzenden naar een online-eindpunt, onder een opgegeven werkruimte.

    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. Gebruik de JSON-definities om aangepaste rollen te maken:

    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>

    Notitie

    Als u aangepaste rollen wilt maken, hebt u een van de volgende drie rollen nodig:

    • eigenaar
    • beheerder van gebruikerstoegang
    • een aangepaste rol met Microsoft.Authorization/roleDefinitions/write machtiging (aangepaste rollen maken/bijwerken/verwijderen) en Microsoft.Authorization/roleDefinitions/read machtiging (om aangepaste rollen weer te geven).

    Zie Aangepaste Azure-rollen voor meer informatie over het maken van aangepaste rollen.

  3. Controleer de roldefinitie:

    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 '"')`

De rol toewijzen aan de identiteit

  1. Als u de AzureML Data Scientist ingebouwde rol gebruikt, gebruikt u de volgende code om de rol toe te wijzen aan uw gebruikersidentiteit.

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

  2. Als u de Azure Machine Learning Workspace Connection Secrets Reader ingebouwde rol gebruikt, gebruikt u desgewenst de volgende code om de rol toe te wijzen aan uw gebruikersidentiteit.

    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. Als u een aangepaste rol gebruikt, gebruikt u de volgende code om de rol toe te wijzen aan uw gebruikersidentiteit.

    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>

    Notitie

    Als u aangepaste rollen wilt toewijzen aan de gebruikersidentiteit, hebt u een van de volgende drie rollen nodig:

    • eigenaar
    • beheerder van gebruikerstoegang
    • een aangepaste rol die machtigingen toestaat Microsoft.Authorization/roleAssignments/write (aangepaste rollen toewijzen) en Microsoft.Authorization/roleAssignments/read (om roltoewijzingen weer te geven).

    Zie Azure-rollen en het toewijzen van Azure-rollen met behulp van Azure Portal voor meer informatie over de verschillende Azure-rollen en hun machtigingen.

  4. Bevestig de roltoewijzing:

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

Het Microsoft Entra-token ophalen voor besturingsvlakbewerkingen

Voer deze stap uit als u van plan bent om besturingsvlakbewerkingen uit te voeren met REST API, die rechtstreeks gebruikmaken van het token.

Als u van plan bent om andere manieren te gebruiken, zoals Azure Machine Learning CLI (v2), Python SDK (v2) of de Azure Machine Learning-studio, hoeft u het Microsoft Entra-token niet handmatig op te halen. In plaats daarvan wordt uw gebruikersidentiteit tijdens het aanmelden al geverifieerd en wordt het token automatisch voor u opgehaald en doorgegeven.

U kunt het Microsoft Entra-token ophalen voor besturingsvlakbewerkingen van het Azure-resource-eindpunt: https://management.azure.com.

  1. Meld u aan bij Azure.

    az login

  2. Als u een specifieke identiteit wilt gebruiken, gebruikt u de volgende code om u aan te melden met de identiteit:

    az login --identity --username <identityId>

  3. Gebruik deze context om het token op te halen.

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

(Optioneel) Het resource-eindpunt en de client-id voor het Microsoft Entra-token verifiëren

Nadat u het Microsoft Entra-token hebt opgehaald, kunt u controleren of het token voor het juiste Azure-resource-eindpunt management.azure.com en de juiste client-id is door het token te decoderen via jwt.ms, waarmee een json-antwoord wordt geretourneerd met de volgende informatie:

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

Een eindpunt maken

In het volgende voorbeeld wordt het eindpunt gemaakt met een door het systeem toegewezen identiteit (SAI) als eindpuntidentiteit. De SAI is het standaardidentiteitstype van de beheerde identiteit voor eindpunten. Sommige basisrollen worden automatisch toegewezen voor de SAI. Zie Automatische roltoewijzing voor eindpuntidentiteit voor meer informatie over roltoewijzing voor een door het systeem toegewezen identiteit.

De CLI vereist niet dat u het token voor het besturingsvlak expliciet opgeeft. In plaats daarvan verifieert de CLI u tijdens het aanmelden en wordt het token automatisch voor u opgehaald en doorgegeven.

  1. Maak een YAML-bestand met eindpuntdefinities.

    endpoint.yml:

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

  2. U kunt vervangen door auth_modekey sleutelverificatie of aml_token voor verificatie van Azure Machine Learning-token. In dit voorbeeld gebruikt aad_token u voor verificatie van Microsoft Entra-token.

    az ml online-endpoint create -f endpoint.yml

  3. Controleer de status van het eindpunt:

    az ml online-endpoint show -n my-endpoint

  4. Als u wilt overschrijven auth_mode (bijvoorbeeld naar aad_token) bij het maken van een eindpunt, voert u de volgende code uit:

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

  5. Als u het bestaande eindpunt wilt bijwerken en wilt opgeven auth_mode (bijvoorbeeld naar aad_token), voert u de volgende code uit:

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

Een implementatie maken

Zie Een ML-model implementeren met een online-eindpunt of REST gebruiken om een model als een online-eindpunt te implementeren om een implementatie te maken. Er is geen verschil in hoe u implementaties maakt voor verschillende verificatiemodi.

De volgende code is een voorbeeld van het maken van een implementatie. Zie Een ML-model implementeren met een online-eindpunt (via CLI) voor meer informatie over het implementeren van online-eindpunten

  1. Maak een YAML-bestand voor de implementatiedefinitie.

    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. Maak de implementatie met behulp van het YAML-bestand. In dit voorbeeld stelt u al het verkeer in op de nieuwe implementatie.

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

De score-URI voor het eindpunt ophalen

Als u van plan bent om de CLI te gebruiken om het eindpunt aan te roepen, hoeft u de score-URI niet expliciet op te halen, omdat de CLI dit voor u afhandelt. U kunt echter nog steeds de CLI gebruiken om de score-URI op te halen, zodat u deze kunt gebruiken met andere kanalen, zoals REST API.

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

De sleutel of het token ophalen voor bewerkingen van het gegevensvlak

Een sleutel of token kan worden gebruikt voor bewerkingen van het gegevensvlak, ook al is het ophalen van de sleutel of het token een besturingsvlakbewerking. Met andere woorden, u gebruikt een token voor het besturingsvlak om de sleutel of het token op te halen die u later gebruikt om uw gegevensvlakbewerkingen uit te voeren.

Als u de sleutel of het Azure Machine Learning-token ophaalt, moet de juiste rol worden toegewezen aan de gebruikersidentiteit die deze aanvraagt, zoals wordt beschreven in autorisatie voor besturingsvlakbewerkingen. De gebruikersidentiteit heeft geen extra rollen nodig om het Microsoft Entra-token op te halen.

Sleutel- of Azure Machine Learning-token

Als u van plan bent om de CLI te gebruiken om het eindpunt aan te roepen en als het eindpunt is ingesteld voor het gebruik van een verificatiemodus van de sleutel of het Azure Machine Learning-token (aml_token), hoeft u het gegevensvlaktoken niet expliciet op te halen, omdat de CLI dit voor u afhandelt. U kunt echter nog steeds de CLI gebruiken om het gegevensvlaktoken op te halen, zodat u het kunt gebruiken met andere kanalen, zoals REST API.

Gebruik de opdracht az ml online-endpoint get-credentials om de sleutel of het Azure Machine Learning-token (aml_token) op te halen. Met deze opdracht wordt een JSON-document geretourneerd dat de sleutel of het Azure Machine Learning-token bevat.

Sleutels worden geretourneerd in de primaryKey en secondaryKey velden. In het volgende voorbeeld ziet u hoe u de --query parameter gebruikt om alleen de primaire sleutel te retourneren:

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-tokens worden geretourneerd in het accessToken veld:

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

expiryTimeUtc De en refreshAfterTimeUtc velden bevatten ook de verloop- en vernieuwingstijden van het token.

Microsoft Entra-token

Gebruik de opdracht az account get-access-token om het Microsoft Entra-token (aad_token) op te halen met cli. Met deze opdracht wordt een JSON-document geretourneerd dat het Microsoft Entra-token bevat.

Microsoft Entra-token wordt geretourneerd in het accessToken veld:

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

Notitie

  • De CLI-extensie ml biedt geen ondersteuning voor het ophalen van het Microsoft Entra-token. Gebruik az account get-access-token in plaats daarvan, zoals beschreven in de vorige code.
  • Het token voor gegevensvlakbewerkingen wordt opgehaald uit het Azure-resource-eindpunt ml.azure.com in plaats van management.azure.com, in tegenstelling tot het token voor besturingsvlakbewerkingen.

Controleer het resource-eindpunt en de client-id voor het Microsoft Entra-token

Nadat u het Entra-token hebt opgehaald, kunt u controleren of het token voor het juiste Azure-resource-eindpunt ml.azure.com en de juiste client-id is door het token te decoderen via jwt.ms, waarmee een json-antwoord wordt geretourneerd met de volgende informatie:

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

Gegevens beoordelen met behulp van de sleutel of het token

Sleutel- of Azure Machine Learning-token

U kunt voor eindpunten met een sleutel of Een Azure Machine Learning-token gebruiken az ml online-endpoint invoke . De CLI verwerkt de sleutel of het Azure Machine Learning-token automatisch, zodat u deze niet expliciet hoeft door te geven.

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

Microsoft Entra-token

Het gebruik az ml online-endpoint invoke voor eindpunten met een Microsoft Entra-token wordt niet ondersteund. Gebruik in plaats daarvan REST API en gebruik de score-URI van het eindpunt om het eindpunt aan te roepen.

Logboekregistratie en bewaking van verkeer

Als u logboekregistratie van verkeer wilt inschakelen in de diagnostische instellingen voor het eindpunt, volgt u de stappen in Logboeken in- of uitschakelen.

Als de diagnostische instelling is ingeschakeld, kunt u de AmlOnlineEndpointTrafficLogs tabel controleren om de verificatiemodus en gebruikersidentiteit te zien.

Gerelateerde inhoud