Uzyskiwanie dostępu do wpisów tajnych z wdrożenia online przy użyciu iniekcji wpisów tajnych (wersja zapoznawcza)

  • Artykuł

DOTYCZY: Rozszerzenie interfejsu wiersza polecenia platformy Azure w wersji 2 (current)Zestaw PYTHON SDK azure-ai-ml v2 (bieżąca)

W tym artykule dowiesz się, jak używać iniekcji wpisów tajnych z punktem końcowym online i wdrożeniem w celu uzyskania dostępu do wpisów tajnych z magazynu wpisów tajnych.

Dowiesz się, jak wykonywać następujące czynności:

  • Konfigurowanie tożsamości użytkownika i jej uprawnień
  • Tworzenie połączeń obszaru roboczego i/lub magazynów kluczy do użycia jako magazynów wpisów tajnych
  • Tworzenie punktu końcowego i wdrożenia przy użyciu funkcji wstrzykiwania wpisu tajnego

Ważne

Ta funkcja jest obecnie w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą być nieobsługiwane lub ograniczone.

Aby uzyskać więcej informacji, zobacz Uzupełniające warunki korzystania z wersji zapoznawczych platformy Microsoft Azure.

Wymagania wstępne

  • Aby korzystać z usługi Azure Machine Edukacja, musisz mieć subskrypcję platformy Azure. Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto. Wypróbuj bezpłatną lub płatną wersję usługi Azure Machine Edukacja dzisiaj.

  • Zainstaluj i skonfiguruj rozszerzenie interfejsu wiersza polecenia platformy Azure Edukacja (wersja 2) lub zestaw AZURE Machine Edukacja Python SDK (wersja 2).

  • Grupa zasobów platformy Azure, w której (lub używana jednostka usługi) musi mieć User Access Administrator dostęp i Contributor mieć do nich dostęp. Jeśli skonfigurowano rozszerzenie usługi Azure Machine Edukacja, musisz mieć taką grupę zasobów, jak określono wcześniej.

  • Obszar roboczy usługi Azure Machine Learning. Jeśli skonfigurowano rozszerzenie usługi Azure Machine Edukacja zgodnie z wcześniejszym opisem, będziesz mieć obszar roboczy.

  • Każdy wytrenowany model uczenia maszynowego jest gotowy do oceniania i wdrażania.

Wybieranie magazynu wpisów tajnych

Możesz wybrać przechowywanie wpisów tajnych (takich jak klucze interfejsu API) przy użyciu jednego z następujących elementów:

  • Połączenia obszaru roboczego w obszarze roboczym: jeśli używasz tego rodzaju magazynu wpisów tajnych, możesz później udzielić uprawnień tożsamości punktu końcowego (w czasie tworzenia punktu końcowego) do automatycznego odczytywania wpisów tajnych z połączeń obszaru roboczego, pod warunkiem spełnienia określonych warunków. Aby uzyskać więcej informacji, zobacz kartę Tożsamość przypisana przez system w sekcji Tworzenie punktu końcowego .
  • Magazyny kluczy, które nie muszą znajdować się w obszarze roboczym: jeśli używasz tego rodzaju magazynu wpisów tajnych, tożsamość punktu końcowego nie zostanie udzielona uprawnienia do automatycznego odczytywania wpisów tajnych z magazynów kluczy. W związku z tym, jeśli chcesz użyć usługi zarządzanego magazynu kluczy, takiej jak microsoft Azure Key Vault jako magazyn wpisów tajnych, musisz później przypisać odpowiednią rolę.

Używanie połączenia obszaru roboczego jako magazynu wpisów tajnych

Możesz utworzyć połączenia obszaru roboczego do użycia we wdrożeniu. Możesz na przykład utworzyć połączenie z usługą Microsoft Azure OpenAI Przy użyciu Połączenie ions obszaru roboczego — tworzenie interfejsu API REST.

Alternatywnie możesz utworzyć połączenie niestandardowe przy użyciu usługi Azure Machine Edukacja Studio (zobacz Jak utworzyć niestandardowe połączenie na potrzeby przepływu monitów) lub azure AI Studio (zobacz Jak utworzyć połączenie niestandardowe w programie AI Studio).

  1. Utwórz połączenie usługi Azure OpenAI:

    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. Alternatywnie możesz utworzyć połączenie niestandardowe:

    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. Sprawdź, czy tożsamość użytkownika może odczytywać wpisy tajne z połączenia obszaru roboczego, używając interfejsu API REST Połączenie ions obszaru roboczego — wyświetlanie listy wpisów tajnych (wersja zapoznawcza).

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

Uwaga

Poprzednie fragmenty kodu używają tokenu w nagłówku podczas wykonywania wywołań interfejsu Authorization API REST. Token można uzyskać, uruchamiając polecenie az account get-access-token. Aby uzyskać więcej informacji na temat uzyskiwania tokenu, zobacz Uzyskiwanie tokenu dostępu.

(Opcjonalnie) Używanie usługi Azure Key Vault jako magazynu wpisów tajnych

Utwórz magazyn kluczy i ustaw wpis tajny do użycia we wdrożeniu. Aby uzyskać więcej informacji na temat tworzenia magazynu kluczy, zobacz Set and retrieve a secret from Azure Key Vault using Azure CLI (Ustawianie i pobieranie wpisu tajnego z usługi Azure Key Vault przy użyciu interfejsu wiersza polecenia platformy Azure). Również

  1. Tworzenie usługi Azure Key Vault:

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

  2. Utwórz wpis tajny:

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

    To polecenie zwraca wersję wpisu tajnego, która zostanie utworzona. Możesz sprawdzić id właściwość odpowiedzi, aby uzyskać wersję wpisu tajnego. Zwrócona odpowiedź wygląda następująco: https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Sprawdź, czy tożsamość użytkownika może odczytać wpis tajny z magazynu kluczy:

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

Ważne

Jeśli używasz magazynu kluczy jako magazynu kluczy do wstrzykiwania wpisów tajnych, musisz skonfigurować model uprawnień magazynu kluczy jako kontrolę dostępu opartą na rolach (RBAC) platformy Azure. Aby uzyskać więcej informacji, zobacz Azure RBAC vs. access policy for Key Vault (Kontrola dostępu na podstawie ról platformy Azure i zasady dostępu dla usługi Key Vault).

Wybieranie tożsamości użytkownika

Wybierz tożsamość użytkownika, której użyjesz do utworzenia punktu końcowego online i wdrożenia online. Ta tożsamość użytkownika może być kontem użytkownika, kontem jednostki usługi lub tożsamością zarządzaną w usłudze Microsoft Entra ID. Aby skonfigurować tożsamość użytkownika, wykonaj kroki opisane w temacie Konfigurowanie uwierzytelniania dla zasobów i przepływów pracy usługi Azure Machine Edukacja.

(Opcjonalnie) Przypisywanie roli do tożsamości użytkownika

  • Jeśli tożsamość użytkownika chce, aby tożsamość przypisanej przez system punktu końcowego (SAI) została automatycznie udzielona uprawnienia do odczytu wpisów tajnych z połączeń obszaru roboczego, tożsamość użytkownika musi mieć Azure Machine Learning Workspace Connection Secrets Reader rolę (lub większą) w zakresie obszaru roboczego.

    • Administrator, który ma Microsoft.Authorization/roleAssignments/write uprawnienia, może uruchomić polecenie interfejsu wiersza polecenia, aby przypisać rolę do tożsamości użytkownika:

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

    Uwaga

    Tożsamość przypisana przez system punktu końcowego (SAI) nie zostanie automatycznie udzielona uprawnienia do odczytywania wpisów tajnych z magazynów kluczy. W związku z tym tożsamość użytkownika nie musi mieć przypisanej roli dla usługi Key Vault.

  • Jeśli chcesz użyć tożsamości przypisanej przez użytkownika dla punktu końcowego, nie musisz przypisywać roli do tożsamości użytkownika. Zamiast tego, jeśli zamierzasz użyć funkcji wstrzykiwania wpisów tajnych, musisz ręcznie przypisać rolę do interfejsu użytkownika punktu końcowego.

    • Administrator, który ma Microsoft.Authorization/roleAssignments/write uprawnienia, może uruchomić następujące polecenia, aby przypisać rolę do tożsamości punktu końcowego:

      W przypadku połączeń obszaru roboczego:

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

      W przypadku magazynów kluczy:

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

  • Sprawdź, czy tożsamość (tożsamość użytkownika lub tożsamość punktu końcowego) ma przypisaną rolę, przechodząc do zasobu w witrynie Azure Portal. Na przykład w obszarze roboczym usługi Azure Machine Edukacja lub w usłudze Key Vault:

    1. Wybierz kartę Kontrola dostępu (IAM).
    2. Wybierz przycisk Sprawdź dostęp i znajdź tożsamość.
    3. Sprawdź, czy właściwa rola jest wyświetlana na karcie Bieżące przypisania ról.

Tworzenie punktu końcowego

Jeśli używasz tożsamości przypisanej przez system (SAI) jako tożsamości punktu końcowego, określ, czy chcesz wymusić dostęp do domyślnych magazynów wpisów tajnych (a mianowicie połączeń obszaru roboczego w obszarze roboczym) z tożsamością punktu końcowego.

  1. Utwórz plik endpoint.yaml:

    $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. Utwórz punkt końcowy przy użyciu endpoint.yaml pliku :

    az ml online-endpoint create -f endpoint.yaml

Jeśli nie określisz identity właściwości w definicji punktu końcowego, punkt końcowy będzie domyślnie używać sai.

Jeśli zostaną spełnione następujące warunki, tożsamość punktu końcowego zostanie automatycznie udzielona Azure Machine Learning Workspace Connection Secrets Reader roli (lub wyższej) w zakresie obszaru roboczego:

  • Tożsamość użytkownika, która tworzy punkt końcowy, ma uprawnienia do odczytywania wpisów tajnych z połączeń obszaru roboczego (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • Punkt końcowy używa sai.
  • Punkt końcowy jest definiowany za pomocą flagi wymuszania dostępu do domyślnych magazynów wpisów tajnych (połączeń obszaru roboczego w bieżącym obszarze roboczym) podczas tworzenia punktu końcowego.

Tożsamość punktu końcowego nie zostanie automatycznie udzielona roli do odczytywania wpisów tajnych z usługi Key Vault. Jeśli chcesz użyć usługi Key Vault jako magazynu wpisów tajnych, musisz ręcznie przypisać odpowiednią rolę, taką jak Key Vault Secrets User do tożsamości punktu końcowego w zakresie usługi Key Vault. Aby uzyskać więcej informacji na temat ról, zobacz Role wbudowane platformy Azure dla operacji płaszczyzny danych usługi Key Vault.

Tworzenie wdrożenia

  1. Utwórz skrypt oceniania lub plik Dockerfile i powiązane skrypty, aby wdrożenie może korzystać z wpisów tajnych za pośrednictwem zmiennych środowiskowych.

    • Nie ma potrzeby wywoływania interfejsów API pobierania wpisów tajnych dla połączeń obszaru roboczego lub magazynów kluczy. Zmienne środowiskowe są wypełniane wpisami tajnymi podczas inicjowania kontenera użytkownika we wdrożeniu.

    • Wartość, która zostanie wstrzyknięta do zmiennej środowiskowej, może być jednym z trzech typów:

      • Cała odpowiedź interfejsu API wpisów tajnych listy (wersja zapoznawcza). Musisz poznać strukturę odpowiedzi interfejsu API, przeanalizować ją i użyć jej w kontenerze użytkownika.
      • Pojedynczy wpis tajny lub metadane z połączenia obszaru roboczego. Można go używać bez znajomości struktury odpowiedzi interfejsu API połączenia obszaru roboczego.
      • Pojedyncza wersja wpisu tajnego z usługi Key Vault. Można go używać bez znajomości struktury odpowiedzi interfejsu API usługi Key Vault.

  2. Zainicjuj tworzenie wdrożenia przy użyciu skryptu oceniania (jeśli używasz modelu niestandardowego) lub pliku Dockerfile (jeśli zastosujesz podejście BYOC do wdrożenia). Określ zmienne środowiskowe oczekiwane przez użytkownika w kontenerze użytkownika.

    Jeśli wartości mapowane na zmienne środowiskowe są zgodne z określonymi wzorcami, tożsamość punktu końcowego zostanie użyta do wykonania pobierania i iniekcji wpisu tajnego.

    Wzorzec Zachowanie
    ${{azureml://connections/<connection_name>}} Cała odpowiedź interfejsu API wpisów tajnych listy (wersja zapoznawcza) jest wprowadzana do zmiennej środowiskowej.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} Wartość poświadczeń jest wstrzykiwana do zmiennej środowiskowej.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} Wartość metadanych jest wstrzykiwana do zmiennej środowiskowej.
    ${{azureml://connections/<connection_name>/target}} Wartość elementu docelowego (jeśli ma zastosowanie) jest wstrzykiwana do zmiennej środowiskowej.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} Wartość wersji wpisu tajnego jest wstrzykiwana do zmiennej środowiskowej.

    Na przykład:

    1. Utwórz 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. Utwórz wdrożenie:

      az ml online-deployment create -f deployment.yaml

Jeśli flaga enforce_access_to_default_secret_stores została ustawiona dla punktu końcowego, uprawnienia tożsamości użytkownika do odczytu wpisów tajnych z połączeń obszaru roboczego będą sprawdzane zarówno podczas tworzenia punktu końcowego, jak i tworzenia wdrożenia. Jeśli tożsamość użytkownika nie ma uprawnień, tworzenie zakończy się niepowodzeniem.

W czasie tworzenia wdrożenia, jeśli jakakolwiek zmienna środowiskowa jest mapowana na wartość zgodną z wzorcami w poprzedniej tabeli, pobieranie wpisów tajnych i iniekcja będą wykonywane z tożsamością punktu końcowego (SAI lub UAI). Jeśli tożsamość punktu końcowego nie ma uprawnień do odczytu wpisów tajnych z wyznaczonych magazynów wpisów tajnych (połączeń obszaru roboczego lub magazynów kluczy), tworzenie wdrożenia zakończy się niepowodzeniem. Ponadto jeśli określone odwołanie do wpisu tajnego nie istnieje w magazynach wpisów tajnych, tworzenie wdrożenia zakończy się niepowodzeniem.

Aby uzyskać więcej informacji na temat błędów, które mogą wystąpić podczas wdrażania punktów końcowych usługi Azure Machine Edukacja online, zobacz Błędy iniekcji wpisów tajnych.

Korzystanie z wpisów tajnych

Wpisy tajne można używać, pobierając je ze zmiennych środowiskowych w kontenerze użytkownika uruchomionym we wdrożeniach.

Powiązana zawartość