Dela via

Få åtkomst till hemligheter från onlinedistribution med hjälp av hemlig inmatning (förhandsversion)

  • Artikel

GÄLLER FÖR:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (aktuell)

I den här artikeln lär du dig att använda hemlig injektion med en onlineslutpunkt och distribution för att få åtkomst till hemligheter från ett hemligt arkiv.

Du lär dig att:

  • Konfigurera användaridentiteten och dess behörigheter
  • Skapa arbetsyteanslutningar och/eller nyckelvalv som ska användas som hemliga arkiv
  • Skapa slutpunkten och distributionen med hjälp av funktionen för hemlig inmatning

Viktigt!

Den här funktionen är för närvarande i allmänt tillgänglig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade.

Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Förutsättningar

  • Om du vill använda Azure Machine Learning måste du ha en Azure-prenumeration. Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar. Prova den kostnadsfria eller betalda versionen av Azure Machine Learning idag.

  • Installera och konfigurera Azure Machine Learning CLI-tillägget (v2) eller Azure Machine Learning Python SDK (v2).

  • En Azure-resursgrupp där du (eller tjänstens huvudnamn du använder) måste ha User Access Administrator och Contributor komma åt. Du kommer att ha en sådan resursgrupp om du har konfigurerat ditt Azure Machine Learning-tillägg enligt vad som angavs tidigare.

  • En Azure Machine Learning-arbetsyta. Du har en arbetsyta om du har konfigurerat ditt Azure Machine Learning-tillägg enligt vad som angavs tidigare.

  • Alla tränade maskininlärningsmodeller som är redo för bedömning och distribution.

Välj ett hemligt arkiv

Du kan välja att lagra dina hemligheter (till exempel API-nycklar) med antingen:

  • Arbetsyteanslutningar under arbetsytan: Om du använder den här typen av hemligt arkiv kan du senare bevilja behörighet till slutpunktsidentiteten (när slutpunkten skapas) för att läsa hemligheter från arbetsyteanslutningar automatiskt, förutsatt att vissa villkor uppfylls. Mer information finns på fliken systemtilldelad identitet i avsnittet Skapa en slutpunkt .
  • Nyckelvalv som inte nödvändigtvis finns under arbetsytan: Om du använder den här typen av hemligt arkiv beviljas inte slutpunktsidentiteten behörighet att läsa hemligheter från nyckelvalven automatiskt. Om du därför vill använda en hanterad key vault-tjänst, till exempel Microsoft Azure Key Vault som ett hemligt arkiv, måste du tilldela en lämplig roll senare.

Använda arbetsyteanslutning som ett hemligt arkiv

Du kan skapa arbetsyteanslutningar som ska användas i distributionen. Du kan till exempel skapa en anslutning till Microsoft Azure OpenAI-tjänsten med hjälp av Arbetsyteanslutningar – Skapa REST API.

Du kan också skapa en anpassad anslutning med hjälp av Azure Machine Learning-studio (se Skapa en anpassad anslutning för promptflöde) eller Azure AI Studio (se Skapa en anpassad anslutning i AI Studio).

  1. Skapa en Azure OpenAI-anslutning:

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "ApiKey",
        "category": "AzureOpenAI",
        "credentials": {
            "key": "<key>",
            "endpoint": "https://<name>.openai.azure.com/",
        },
        "expiryTime": null,
        "target": "https://<name>.openai.azure.com/",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "ApiType": "Azure"
        }
    }
}

  2. Du kan också skapa en anpassad anslutning:

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "CustomKeys",
        "category": "CustomKeys",
        "credentials": {
            "keys": {
                "OPENAI_API_KEY": "<key>",
                "SPEECH_API_KEY": "<key>"
            }
        },
        "expiryTime": null,
        "target": "_",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "OPENAI_API_BASE": "<oai endpoint>",
            "OPENAI_API_VERSION": "<oai version>",
            "OPENAI_API_TYPE": "azure",
            "SPEECH_REGION": "eastus",
        }
    }
}

  3. Kontrollera att användaridentiteten kan läsa hemligheterna från arbetsyteanslutningen med hjälp av Workspace Connections – List Secrets REST API (förhandsversion).

    POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview
Authorization: Bearer {{token}}

Kommentar

De tidigare kodfragmenten Authorization använder en token i huvudet när du gör REST API-anrop. Du kan hämta token genom att köra az account get-access-token. Mer information om hur du hämtar en token finns i Hämta en åtkomsttoken.

(Valfritt) Använda Azure Key Vault som ett hemligt arkiv

Skapa nyckelvalvet och ange en hemlighet som ska användas i distributionen. Mer information om hur du skapar nyckelvalvet finns i Ange och hämta en hemlighet från Azure Key Vault med Azure CLI. Dessutom,

  1. Skapa ett Azure Key Vault:

    az keyvault create --name mykeyvault --resource-group myrg --location eastus

  2. Skapa en hemlighet:

    az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>

    Det här kommandot returnerar den hemliga version som skapas. Du kan kontrollera egenskapen för id svaret för att hämta den hemliga versionen. Det returnerade svaret ser ut som https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Kontrollera att användaridentiteten kan läsa hemligheten från nyckelvalvet:

    az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>

Viktigt!

Om du använder nyckelvalvet som ett hemligt arkiv för hemlig inmatning måste du konfigurera nyckelvalvets behörighetsmodell som rollbaserad åtkomstkontroll i Azure (RBAC). Mer information finns i Azure RBAC jämfört med åtkomstprincip för Key Vault.

Välj en användaridentitet

Välj den användaridentitet som du ska använda för att skapa onlineslutpunkten och onlinedistributionen. Den här användaridentiteten kan vara ett användarkonto, ett konto för tjänstens huvudnamn eller en hanterad identitet i Microsoft Entra-ID. Om du vill konfigurera användaridentiteten följer du stegen i Konfigurera autentisering för Azure Machine Learning-resurser och arbetsflöden.

(Valfritt) Tilldela en roll till användaridentiteten

  • Om din användaridentitet vill att slutpunktens systemtilldelade identitet (SAI) automatiskt ska beviljas behörighet att läsa hemligheter från arbetsyteanslutningar måste användaridentiteten Azure Machine Learning Workspace Connection Secrets Reader ha rollen (eller högre) i arbetsytans omfång.

    • En administratör som har behörigheten Microsoft.Authorization/roleAssignments/write kan köra ett CLI-kommando för att tilldela rollen till användaridentiteten:

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

    Kommentar

    Slutpunktens systemtilldelade identitet (SAI) beviljas inte automatiskt behörighet att läsa hemligheter från nyckelvalv. Användaridentiteten behöver därför inte tilldelas någon roll för Key Vault.

  • Om du vill använda en användartilldelad identitet (UAI) för slutpunkten behöver du inte tilldela rollen till din användaridentitet. Om du tänker använda funktionen för hemlig inmatning måste du i stället tilldela rollen till slutpunktens UAI manuellt.

    • En administratör som har behörigheten Microsoft.Authorization/roleAssignments/write kan köra följande kommandon för att tilldela rollen till slutpunktsidentiteten:

      För anslutningar till arbetsytor:

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

      För nyckelvalv:

      az role assignment create --assignee <EndpointIdentityID> --role "Key Vault Secrets User" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<vaultName>

  • Kontrollera att en identitet (antingen en användaridentitet eller slutpunktsidentitet) har tilldelats rollen genom att gå till resursen i Azure Portal. Till exempel i Azure Machine Learning-arbetsytan eller Key Vault:

    1. Välj fliken Åtkomstkontroll (IAM).
    2. Välj knappen Kontrollera åtkomst och hitta identiteten.
    3. Kontrollera att rätt roll visas under fliken Aktuella rolltilldelningar .

Skapa en slutpunkt

Om du använder en systemtilldelad identitet (SAI) som slutpunktsidentitet anger du om du vill framtvinga åtkomst till standardhemlighetslager (dvs. arbetsyteanslutningar under arbetsytan) till slutpunktsidentiteten.

  1. Skapa en endpoint.yaml-fil:

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
properties:
    enforce_access_to_default_secret_stores: enabled  # default: disabled

  2. Skapa slutpunkten med hjälp av endpoint.yaml filen:

    az ml online-endpoint create -f endpoint.yaml

Om du inte anger identity egenskapen i slutpunktsdefinitionen använder slutpunkten ett SAI som standard.

Om följande villkor uppfylls beviljas slutpunktsidentiteten Azure Machine Learning Workspace Connection Secrets Reader automatiskt rollen (eller högre) i arbetsytans omfång:

  • Användaridentiteten som skapar slutpunkten har behörighet att läsa hemligheter från arbetsyteanslutningar (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • Slutpunkten använder ett SAI.
  • Slutpunkten definieras med en flagga för att framtvinga åtkomst till standardhemlighetslager (arbetsyteanslutningar under den aktuella arbetsytan) när slutpunkten skapas.

Slutpunktsidentiteten beviljas inte automatiskt en roll för att läsa hemligheter från Key Vault. Om du vill använda Key Vault som ett hemligt arkiv måste du manuellt tilldela en lämplig roll, till exempel Key Vault Secrets User till slutpunktsidentiteten i nyckelvalvets omfång. Mer information om roller finns i Inbyggda Roller i Azure för key vault-dataplansåtgärder.

Skapa en distribution

  1. Skapa ett bedömningsskript eller Dockerfile och relaterade skript så att distributionen kan använda hemligheterna via miljövariabler.

    • Du behöver inte anropa API:erna för hemlig hämtning för arbetsyteanslutningar eller nyckelvalv. Miljövariablerna fylls i med hemligheterna när användarcontainern i distributionen initieras.

    • Värdet som matas in i en miljövariabel kan vara en av de tre typerna:

      • Hela svaret för listhemlighets-API:et (förhandsversion). Du måste förstå API-svarsstrukturen, parsa den och använda den i din användarcontainer.
      • Enskild hemlighet eller metadata från arbetsyteanslutningen. Du kan använda den utan att förstå api-svarsstrukturen för arbetsytans anslutning.
      • Enskild hemlig version från Key Vault. Du kan använda den utan att förstå nyckelvalvs-API:ets svarsstruktur.

  2. Starta skapandet av distributionen med hjälp av antingen bedömningsskriptet (om du använder en anpassad modell) eller en Dockerfile (om du använder BYOC-metoden för distribution). Ange miljövariabler som användaren förväntar sig i användarcontainern.

    Om de värden som mappas till miljövariablerna följer vissa mönster används slutpunktsidentiteten för att utföra hemlig hämtning och inmatning.

    Mönster Funktionssätt
    ${{azureml://connections/<connection_name>}} Svaret för hela listhemlighets-API:et (förhandsversion) matas in i miljövariabeln.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} Värdet för autentiseringsuppgifterna matas in i miljövariabeln.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} Värdet för metadata matas in i miljövariabeln.
    ${{azureml://connections/<connection_name>/target}} Värdet för målet (om tillämpligt) matas in i miljövariabeln.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} Värdet för den hemliga versionen matas in i miljövariabeln.

    Till exempel:

    1. Skapa deployment.yaml:

      $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
#…
environment_variables:
    AOAI_CONNECTION: ${{azureml://connections/aoai_connection}}
    LANGCHAIN_CONNECTION: ${{azureml://connections/multi_connection_langchain}}

    OPENAI_KEY: ${{azureml://connections/multi_connection_langchain/credentials/OPENAI_API_KEY}}
    OPENAI_VERSION: ${{azureml://connections/multi_connection_langchain/metadata/OPENAI_API_VERSION}}

    USER_SECRET_KV1_KEY: ${{keyvault:https://mykeyvault.vault.azure.net/secrets/secret1/secretversion1}}

    2. Skapa distributionen:

      az ml online-deployment create -f deployment.yaml

enforce_access_to_default_secret_stores Om flaggan har angetts för slutpunkten kontrolleras användaridentitetens behörighet att läsa hemligheter från arbetsyteanslutningar både när slutpunkten skapas och när distributionen skapas. Om användaridentiteten inte har behörigheten misslyckas skapandet.

Om en miljövariabel mappas till ett värde som följer mönstren i den föregående tabellen vid distributionen utförs hemlig hämtning och inmatning med slutpunktsidentiteten (antingen en SAI eller en UAI). Om slutpunktsidentiteten inte har behörighet att läsa hemligheter från avsedda hemliga arkiv (antingen arbetsyteanslutningar eller nyckelvalv) misslyckas distributionen. Om den angivna hemliga referensen inte finns i de hemliga arkiven misslyckas distributionen.

Mer information om fel som kan inträffa under distributionen av Azure Machine Learning-onlineslutpunkter finns i Hemliga inmatningsfel.

Använda hemligheterna

Du kan använda hemligheterna genom att hämta dem från miljövariablerna i användarcontainern som körs i dina distributioner.

Relaterat innehåll