Sdílet prostřednictvím

Přístup k tajným kódům z online nasazení pomocí injektáže tajných kódů (Preview)

  • Článek

PLATÍ PRO:Rozšíření Azure CLI ml v2 (aktuální)Python SDK azure-ai-ml v2 (aktuální)

V tomto článku se naučíte používat injektáž tajných kódů s online koncovým bodem a nasazením pro přístup k tajným kódům z úložiště tajných kódů.

Naučíte se:

  • Nastavení identity uživatele a jeho oprávnění
  • Vytvoření připojení pracovního prostoru nebo trezorů klíčů, které se mají použít jako úložiště tajných klíčů
  • Vytvoření koncového bodu a nasazení pomocí funkce injektáže tajných kódů

Důležité

Tato funkce je v současné době ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti.

Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Požadavky

  • Pokud chcete používat Azure Machine Learning, musíte mít předplatné Azure. Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet. Vyzkoušejte si bezplatnou nebo placenou verzi služby Azure Machine Learning ještě dnes.

  • Nainstalujte a nakonfigurujte rozšíření Azure Machine Learning CLI (v2) nebo sadu Azure Machine Learning Python SDK (v2).

  • Skupina prostředků Azure, ve které potřebujete mít User Access Administrator (nebo instanční objekt, který používáte), a Contributor přístup. Takovou skupinu prostředků budete mít, pokud jste nakonfigurovali rozšíření Azure Machine Learning, jak je uvedeno dříve.

  • Pracovní prostor služby Azure Machine Learning. Pokud jste nakonfigurovali rozšíření Azure Machine Learning, jak jste uvedli dříve, budete mít pracovní prostor.

  • Jakýkoli vytrénovaný model strojového učení připravený k bodování a nasazení

Volba úložiště tajných kódů

Tajné kódy (například klíče rozhraní API) můžete ukládat pomocí následujících:

  • Připojení pracovního prostoru v rámci pracovního prostoru: Pokud používáte tento druh úložiště tajných kódů, můžete později udělit oprávnění identitě koncového bodu (v době vytvoření koncového bodu) ke čtení tajných kódů z připojení pracovního prostoru automaticky za předpokladu, že jsou splněny určité podmínky. Další informace najdete na kartě identit přiřazené systémem v části Vytvoření koncového bodu .
  • Trezory klíčů, které nejsou nutně součástí pracovního prostoru: Pokud používáte tento druh úložiště tajných kódů, identita koncového bodu nebude udělena oprávnění k automatickému čtení tajných kódů z trezorů klíčů. Proto pokud chcete použít službu spravovaného trezoru klíčů, jako je Microsoft Azure Key Vault jako úložiště tajných kódů, musíte později přiřadit správnou roli.

Použití připojení pracovního prostoru jako úložiště tajných kódů

Můžete vytvořit připojení pracovního prostoru, která se budou používat v nasazení. Můžete například vytvořit připojení ke službě Microsoft Azure OpenAI pomocí připojení pracovních prostorů – Vytvoření rozhraní REST API.

Případně můžete vytvořit vlastní připojení pomocí studio Azure Machine Learning (viz Postup vytvoření vlastního připojení pro tok výzvy) nebo Azure AI Foundry (viz Postup vytvoření vlastního připojení na portálu Azure AI Foundry).

  1. Vytvořte připojení 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. Alternativně můžete vytvořit vlastní připojení:

    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. Ověřte, že identita uživatele může číst tajné kódy z připojení pracovního prostoru pomocí připojení pracovních prostorů – Výpis tajných kódů REST API (Preview).

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

Poznámka:

Předchozí fragmenty kódu používají token v Authorization hlavičce při volání rozhraní REST API. Token můžete získat spuštěním az account get-access-tokenpříkazu . Další informace o získání tokenu najdete v tématu Získání přístupového tokenu.

(Volitelné) Použití služby Azure Key Vault jako úložiště tajných kódů

Vytvořte trezor klíčů a nastavte tajný klíč pro použití v nasazení. Další informace o vytvoření trezoru klíčů najdete v tématu Nastavení a načtení tajného klíče ze služby Azure Key Vault pomocí Azure CLI. Navíc,

  1. Vytvoření služby Azure Key Vault:

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

  2. Vytvoření tajného kódu:

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

    Tento příkaz vrátí verzi tajného kódu, která vytvoří. Můžete zkontrolovat id vlastnost odpovědi a získat verzi tajného kódu. Vrácená odpověď vypadá takto https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Ověřte, že identita uživatele může číst tajný klíč z trezoru klíčů:

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

Důležité

Pokud trezor klíčů používáte jako úložiště tajných kódů pro injektáž tajných kódů, musíte nakonfigurovat model oprávnění trezoru klíčů jako řízení přístupu na základě role v Azure (RBAC). Další informace najdete v tématu Azure RBAC vs. zásady přístupu ke službě Key Vault.

Volba identity uživatele

Zvolte identitu uživatele, kterou použijete k vytvoření online koncového bodu a online nasazení. Tato identita uživatele může být uživatelským účtem, instančním účtem nebo spravovanou identitou v Microsoft Entra ID. Pokud chcete nastavit identitu uživatele, postupujte podle kroků v tématu Nastavení ověřování pro prostředky a pracovní postupy služby Azure Machine Learning.

(Volitelné) Přiřazení role identitě uživatele

  • Pokud vaše identita uživatele chce, aby identita přiřazená systémem koncového bodu (SAI) automaticky udělila oprávnění ke čtení tajných kódů z připojení pracovního prostoru, musí Azure Machine Learning Workspace Connection Secrets Reader mít identita uživatele roli (nebo vyšší) v oboru pracovního prostoru.

    • Správce s Microsoft.Authorization/roleAssignments/write oprávněním může spustit příkaz rozhraní příkazového řádku pro přiřazení role identitě uživatele:

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

    Poznámka:

    Identita přiřazená systémem koncového bodu (SAI) nebude automaticky udělena oprávnění ke čtení tajných kódů z trezorů klíčů. Identita uživatele proto nemusí být přiřazena roli pro službu Key Vault.

  • Pokud chcete pro koncový bod použít identitu přiřazenou uživatelem, nemusíte roli přiřazovat identitě uživatele. Místo toho, pokud máte v úmyslu použít funkci injektáže tajných kódů, musíte roli přiřadit uživatelskému rozhraní koncového bodu ručně.

    • Správce, který má Microsoft.Authorization/roleAssignments/write oprávnění, může spustit následující příkazy pro přiřazení role k identitě koncového bodu:

      Připojení pracovního prostoru:

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

      Trezory klíčů:

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

  • Ověřte, že identita (identita uživatele nebo identita koncového bodu) má přiřazenou roli, a to tak, že přejdete k prostředku na webu Azure Portal. Například v pracovním prostoru Azure Machine Learning nebo ve službě Key Vault:

    1. Vyberte kartu Řízení přístupu (IAM).
    2. Vyberte tlačítko Zkontrolovat přístup a vyhledejte identitu.
    3. Ověřte, že se na kartě Aktuální přiřazení rolí zobrazuje správná role.

Vytvoření koncového bodu

Pokud jako identitu koncového bodu používáte identitu přiřazenou systémem (SAI), určete, jestli chcete vynutit přístup k výchozím úložištím tajných kódů (konkrétně připojení pracovního prostoru v rámci pracovního prostoru) k identitě koncového bodu.

  1. Vytvořte soubor 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. Vytvořte koncový bod pomocí endpoint.yaml souboru:

    az ml online-endpoint create -f endpoint.yaml

Pokud v definici koncového bodu nezadáte identity vlastnost, použije koncový bod ve výchozím nastavení sai.

Pokud jsou splněny následující podmínky, identita koncového bodu se automaticky udělí Azure Machine Learning Workspace Connection Secrets Reader roli (nebo vyšší) v oboru pracovního prostoru:

  • Identita uživatele, která vytvoří koncový bod, má oprávnění ke čtení tajných kódů z připojení pracovního prostoru (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • Koncový bod používá sai.
  • Koncový bod je definován příznakem pro vynucení přístupu k výchozím úložištům tajných kódů (připojení pracovního prostoru v aktuálním pracovním prostoru) při vytváření koncového bodu.

Identitě koncového bodu se automaticky nepřidělí role pro čtení tajných kódů ze služby Key Vault. Pokud chcete službu Key Vault použít jako úložiště tajných kódů, musíte ručně přiřadit správnou roli, jako Key Vault Secrets User je identita koncového bodu v oboru služby Key Vault. Další informace o rolích najdete v tématu Předdefinované role Azure pro operace roviny dat služby Key Vault.

Vytvoření nasazení

  1. Vytvořte bodovací skript nebo soubor Dockerfile a související skripty, aby nasazení bylo možné využívat tajné kódy prostřednictvím proměnných prostředí.

    • Není nutné volat rozhraní API pro načítání tajných kódů pro připojení pracovního prostoru nebo trezory klíčů. Proměnné prostředí se naplní tajnými kódy, když se spustí kontejner uživatele v nasazení.

    • Hodnota, která se vloží do proměnné prostředí, může být jedním ze tří typů:

      • Celá odpověď rozhraní API pro výpis tajných kódů (Preview) Budete muset porozumět struktuře odpovědí rozhraní API, analyzovat ji a používat ji v kontejneru uživatele.
      • Individuální tajný klíč nebo metadata z připojení pracovního prostoru. Můžete ho použít, aniž byste porozuměli struktuře odpovědí rozhraní API připojení pracovního prostoru.
      • Individuální verze tajného kódu ze služby Key Vault. Můžete ho použít, aniž byste porozuměli struktuře odpovědí rozhraní API služby Key Vault.

  2. Spusťte vytvoření nasazení pomocí hodnoticího skriptu (pokud používáte vlastní model) nebo souboru Dockerfile (pokud použijete přístup BYOC k nasazení). Zadejte proměnné prostředí, které uživatel očekává v rámci kontejneru uživatele.

    Pokud hodnoty mapované na proměnné prostředí dodržují určité vzory, použije se identita koncového bodu k provádění načítání a injektáže tajných kódů.

    Vzor Chování
    ${{azureml://connections/<connection_name>}} Celá odpověď rozhraní API pro tajné kódy seznamu (Preview) se vloží do proměnné prostředí.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} Hodnota přihlašovacích údajů se vloží do proměnné prostředí.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} Hodnota metadat se vloží do proměnné prostředí.
    ${{azureml://connections/<connection_name>/target}} Hodnota cíle (pokud je k dispozici) se vloží do proměnné prostředí.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} Hodnota verze tajného kódu se vloží do proměnné prostředí.

    Příklad:

    1. Vytvořit 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. Vytvořte nasazení:

      az ml online-deployment create -f deployment.yaml

enforce_access_to_default_secret_stores Pokud byl příznak nastavený pro koncový bod, oprávnění identity uživatele ke čtení tajných kódů z připojení pracovního prostoru se zkontroluje jak při vytváření koncového bodu, tak při vytváření nasazení. Pokud identita uživatele nemá oprávnění, vytvoření se nezdaří.

Pokud se při vytváření nasazení namapuje nějaká proměnná prostředí na hodnotu, která následuje za vzory v předchozí tabulce, provede se načtení tajných kódů a injektáž s identitou koncového bodu (buď SAI, nebo UAI). Pokud identita koncového bodu nemá oprávnění ke čtení tajných kódů z určených úložišť tajných kódů (připojení pracovního prostoru nebo trezorů klíčů), vytvoření nasazení selže. Pokud zadaný odkaz na tajný kód v úložištích tajných kódů neexistuje, vytvoření nasazení selže.

Další informace o chybách, ke kterým může dojít při nasazování online koncových bodů služby Azure Machine Learning, najdete v tématu Chyby injektáže tajných kódů.

Využívání tajných kódů

Tajné kódy můžete využívat načtením z proměnných prostředí v kontejneru uživatele spuštěného ve vašich nasazeních.

Související obsah