Delen via

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.

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 az login 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. Voor het ophalen van het Microsoft Entra-token zijn geen extra rollen vereist voor de gebruikersidentiteit.

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

Gebruik de opdracht az ml online-endpoint get-credentials om de sleutels of het token op te halen voor gegevensvlakbewerkingen . Met deze opdracht wordt een JSON-uitvoer geretourneerd die de sleutels, het token en/of aanvullende informatie bevat.

Tip

Als u een specifieke informatie wilt extraheren uit de JSON-uitvoer, wordt de --query parameter van de CLI-opdracht gebruikt als voorbeeld. U kunt hiervoor echter elk geschikt hulpmiddel gebruiken.

Wanneer auth_mode van het eindpunt key

  • Sleutels worden geretourneerd in de primaryKey en secondaryKey velden.
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)
export DATA_PLANE_TOKEN2=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query secondaryKey)

Wanneer auth_mode van het eindpunt aml_token

  • Token wordt geretourneerd in het accessToken veld.
  • De verlooptijd van het token wordt geretourneerd in het expiryTimeUtc veld.
  • De vernieuwingstijd van het token wordt geretourneerd in het refreshAfterTimeUtc veld.
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
export REFRESH_AFTER_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query refreshAfterTimeUtc)

Wanneer auth_mode van het eindpunt aad_token

  • Token wordt geretourneerd in het accessToken veld.
  • De verlooptijd van het token wordt geretourneerd in het expiryTimeUtc veld.
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)

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

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

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

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