Condividi tramite

Accedere ai segreti dalla distribuzione online usando l'inserimento di segreti (anteprima)

  • Articolo

SI APPLICA A:estensione ml dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)

Questo articolo illustra come usare l'inserimento di segreti con un endpoint online e la distribuzione per accedere ai segreti da un archivio segreto.

Si apprenderà come:

  • Configurare l'identità utente e le relative autorizzazioni
  • Creare connessioni all'area di lavoro e/o insiemi di credenziali delle chiavi da usare come archivi segreti
  • Creare l'endpoint e la distribuzione usando la funzionalità di inserimento dei segreti

Importante

Questa funzionalità è attualmente in anteprima pubblica. Questa versione di anteprima viene fornita senza contratto di servizio, pertanto se ne sconsiglia l’uso per i carichi di lavoro in ambienti di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate.

Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Prerequisiti

  • Per usare Azure Machine Learning, è necessario avere una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare. Provare la versione gratuita o a pagamento di Azure Machine Learning.

  • Installare e configurare l'estensione dell'interfaccia della riga di comando di Azure Machine Learning (v2) o Azure Machine Learning Python SDK (v2).

  • Un gruppo di risorse di Azure, in cui l’utente (o l'entità servizio usata) deve avere l'accesso User Access Administrator e Contributor. Se è stata configurata l'estensione di Azure Machine Learning come indicato in precedenza, si avrà un gruppo di risorse di questo tipo.

  • Un'area di lavoro di Azure Machine Learning. Se è stata configurata l'estensione di Azure Machine Learning come indicato in precedenza, si avrà un'area di lavoro.

  • Qualsiasi modello di Machine Learning con training pronto per l'assegnazione di punteggi e la distribuzione.

Scegliere un archivio segreto

È possibile scegliere di archiviare i segreti (ad esempio le chiavi API) usando:

  • Connessioni all'area di lavoro nell'area di lavoro: se si usa questo tipo di archivio segreto, è possibile concedere in un secondo momento l'autorizzazione all'identità dell'endpoint (in fase di creazione dell'endpoint) per leggere automaticamente i segreti dalle connessioni all'area di lavoro, purché vengano soddisfatte determinate condizioni. Per altre informazioni, vedere la scheda Identità assegnata dal sistema nella sezione Creare un endpoint.
  • Insiemi di credenziali delle chiavi non necessariamente nell'area di lavoro: se si usa questo tipo di archivio segreto, all'identità dell'endpoint non verrà concessa automaticamente l'autorizzazione per leggere i segreti dagli insiemi di credenziali delle chiavi. Pertanto, se si vuole usare un servizio di insieme di credenziali delle chiavi gestito, ad esempio Microsoft Azure Key Vault come archivio segreto, è necessario assegnare un ruolo appropriato in un secondo momento.

Usare la connessione all'area di lavoro come archivio segreto

È possibile creare connessioni all'area di lavoro da usare nella distribuzione. Ad esempio, è possibile creare una connessione al servizio OpenAI di Microsoft Azure usando Connessioni all'area di lavoro - Creare l'API REST.

In alternativa, è possibile creare una connessione personalizzata usando Azure Machine Learning Studio (vedere Come creare una connessione personalizzata per il flusso di richiesta) o Azure AI Studio (vedere Come creare una connessione personalizzata in AI Studio).

  1. Creare una connessione OpenAI di Azure:

    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. In alternativa, è possibile creare una connessione personalizzata:

    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. Verificare che l'identità utente possa leggere i segreti dalla connessione all'area di lavoro usando Connessioni all'area di lavoro - Elencare l'API REST segreti (anteprima).

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

Nota

I frammenti di codice precedenti usano un token nell'intestazione Authorization durante l'esecuzione di chiamate API REST. È possibile ottenere il token eseguendo az account get-access-token. Per altre informazioni sul recupero di un token, vedere Ottenere un token di accesso.

(Facoltativo) Usare Azure Key Vault come archivio segreto

Creare l'insieme di credenziali delle chiavi e impostare un segreto da usare nella distribuzione. Per altre informazioni sulla creazione dell'insieme di credenziali delle chiavi, vedere Impostare e recuperare un segreto da Azure Key Vault usando l'interfaccia della riga di comando di Azure. Inoltre,

  1. Creare un insieme di credenziali delle chiavi di Azure:

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

  2. Creare un segreto:

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

    Questo comando restituisce la versione del segreto creata. È possibile controllare la proprietà id della risposta per ottenere la versione del segreto. La risposta restituita è simile a https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Verificare che l'identità utente possa leggere il segreto dall'insieme di credenziali delle chiavi:

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

Importante

Se si usa l'insieme di credenziali delle chiavi come archivio segreto per l'inserimento di segreti, è necessario configurare il modello di autorizzazione dell'insieme di credenziali delle chiavi come controllo degli accessi in base al ruolo di Azure. Per altre informazioni, vedere Controllo degli accessi in base al ruolo di Azure e criteri di accesso per Key Vault.

Scegliere un'identità utente

Scegliere l'identità utente che verrà usata per creare l'endpoint online e la distribuzione online. Questa identità utente può essere un account utente, un account entità servizio o un'identità gestita in Microsoft Entra ID. Per configurare l'identità utente, seguire la procedura descritta in Configurare l'autenticazione per le risorse e i flussi di lavoro di Azure Machine Learning.

(Facoltativo) Assegnare un ruolo all'identità utente

  • Se l'identità utente vuole che all'identità assegnata dal sistema dell'endpoint venga concessa automaticamente l'autorizzazione per leggere i segreti dalle connessioni all'area di lavoro, l'identità utente deve avere il ruolo Azure Machine Learning Workspace Connection Secrets Reader (o versione successiva) nell'ambito dell'area di lavoro.

    • Un amministratore che dispone dell'autorizzazione Microsoft.Authorization/roleAssignments/write può eseguire un comando dell'interfaccia della riga di comando per assegnare il ruolo all'identità utente:

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

    Nota

    All'identità assegnata dal sistema dell'endpoint non verrà concessa automaticamente l'autorizzazione per la lettura dei segreti dagli insiemi di credenziali delle chiavi. L'identità utente non deve quindi essere assegnata a un ruolo per l'insieme di credenziali delle chiavi.

  • Se si vuole usare un'identità assegnata dall'utente per l'endpoint, non è necessario assegnare il ruolo all'identità utente. Se invece si intende usare la funzionalità di inserimento dei segreti, è necessario assegnare manualmente il ruolo all'interfaccia utente dell'endpoint.

    • Un amministratore che dispone dell'autorizzazione Microsoft.Authorization/roleAssignments/write può eseguire i comandi seguenti per assegnare il ruolo all'identità dell'endpoint:

      Per le connessioni all'area di lavoro:

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

      Per gli insiemi di credenziali delle chiavi:

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

  • Verificare che a un'identità (identità utente o identità dell'endpoint) sia assegnato il ruolo, passando alla risorsa nel portale di Azure. Ad esempio, nell'area di lavoro di Azure Machine Learning o nell'insieme di credenziali delle chiavi:

    1. Selezionare la scheda Controllo di accesso (IAM).
    2. Selezionare il pulsante Controllare l'accesso e trovare l'identità.
    3. Verificare che il ruolo corretto sia visualizzato nella scheda Assegnazioni di ruolo correnti.

Creare un endpoint

Se si usa un'identità assegnata dal sistema (SAI) come identità dell'endpoint, specificare se si vuole applicare l'accesso agli archivi dei segreti predefiniti (ovvero le connessioni dell'area di lavoro nell'area di lavoro) all'identità dell'endpoint.

  1. Creare un file 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. Creare l'endpoint usando il file endpoint.yaml:

    az ml online-endpoint create -f endpoint.yaml

Se non si specifica la proprietà identity nella definizione dell'endpoint, per impostazione predefinita l'endpoint userà un SAI.

Se vengono soddisfatte le condizioni seguenti, all'identità dell'endpoint verrà automaticamente concesso il ruolo di Azure Machine Learning Workspace Connection Secrets Reader (o superiore) nell'ambito dell'area di lavoro:

  • L'identità utente che crea l'endpoint ha l'autorizzazione per leggere i segreti dalle connessioni dell'area di lavoro (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • L'endpoint usa un SAI.
  • L'endpoint viene definito con un flag per applicare l'accesso agli archivi dei segreti predefiniti (connessioni dell'area di lavoro nell'area di lavoro corrente) durante la creazione dell'endpoint.

All'identità dell'endpoint non verrà concesso automaticamente un ruolo per leggere i segreti dall'insieme di credenziali delle chiavi. Se si vuole usare l'insieme di credenziali delle chiavi come archivio segreto, è necessario assegnare manualmente un ruolo appropriato, ad esempio Key Vault Secrets User all'identità dell'endpoint nell'ambito dell'insieme di credenziali delle chiavi. Per altre informazioni sui ruoli, vedere Ruoli predefiniti di Azure per le operazioni del piano dati di Key Vault.

Creare una distribuzione

  1. Creare uno script di assegnazione dei punteggi o Dockerfile e gli script correlati in modo che la distribuzione possa utilizzare i segreti tramite variabili di ambiente.

    • Non è necessario chiamare le API di recupero dei segreti per le connessioni dell'area di lavoro o gli insiemi di credenziali delle chiavi. Le variabili di ambiente vengono popolate con i segreti quando viene avviato il contenitore utente nella distribuzione.

    • Il valore inserito in una variabile di ambiente può essere uno dei tre tipi seguenti:

      • L'intera risposta dell’API List Secrets (anteprima). Sarà necessario comprendere la struttura di risposta dell'API, analizzarla e usarla nel contenitore utente.
      • Singolo segreto o metadati dalla connessione dell'area di lavoro. È possibile usarla senza comprendere la struttura di risposta dell'API di connessione dell'area di lavoro.
      • Singola versione del segreto dell'insieme di credenziali delle chiavi. È possibile usarla senza comprendere la struttura di risposta dell'API di Key Vault.

  2. Avviare la creazione della distribuzione usando lo script di assegnazione dei punteggi (se si usa un modello personalizzato) o un Dockerfile (se si usa l'approccio BYOC alla distribuzione). Specificare le variabili di ambiente previste dall'utente all'interno del contenitore utente.

    Se i valori mappati alle variabili di ambiente seguono determinati modelli, l'identità dell'endpoint verrà usata per eseguire il recupero e l'inserimento dei segreti.

    Modello Comportamento
    ${{azureml://connections/<connection_name>}} L'intera risposta dell’API List Secrets (anteprima) viene inserita nella variabile di ambiente.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} Il valore della credenziale viene inserito nella variabile di ambiente.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} Il valore dei metadati viene inserito nella variabile di ambiente.
    ${{azureml://connections/<connection_name>/target}} Il valore della destinazione (se applicabile) viene inserito nella variabile di ambiente.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} Il valore della versione del segreto viene inserito nella variabile di ambiente.

    Ad esempio:

    1. Creare 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. Creare la distribuzione:

      az ml online-deployment create -f deployment.yaml

Se il flag enforce_access_to_default_secret_stores è stato impostato per l'endpoint, l'autorizzazione dell'identità utente per leggere i segreti dalle connessioni all'area di lavoro verrà verificata sia al momento della creazione dell'endpoint che della creazione della distribuzione. Se l'identità utente non dispone dell'autorizzazione, la creazione avrà esito negativo.

In fase di creazione della distribuzione, se viene eseguito il mapping di una variabile di ambiente a un valore che segue i modelli nella tabella precedente, il recupero e l'inserimento dei segreti verranno eseguiti con l'identità dell'endpoint (un SAI o un UAI). Se l'identità dell'endpoint non dispone dell'autorizzazione per leggere i segreti dagli archivi dei segreti designati (connessioni all'area di lavoro o insiemi di credenziali delle chiavi), la creazione della distribuzione avrà esito negativo. Inoltre, se il riferimento al segreto specificato non esiste negli archivi dei segreti, la creazione della distribuzione avrà esito negativo.

Per altre informazioni sugli errori che possono verificarsi durante la distribuzione degli endpoint online di Azure Machine Learning, vedere Errori di inserimento dei segreti.

Utilizzare i segreti

È possibile utilizzare i segreti recuperandoli dalle variabili di ambiente all'interno del contenitore utente in esecuzione nelle distribuzioni.

Contenuto correlato