Share via

Acesse segredos da implantação on-line usando injeção de segredos (visualização)

  • Artigo

APLICA-SE A:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

Neste artigo, você aprenderá a usar a injeção secreta com um ponto de extremidade online e a implantação para acessar segredos de um armazenamento secreto.

Ficará a saber como:

  • Configurar sua identidade de usuário e suas permissões
  • Criar conexões de espaço de trabalho e/ou cofres de chaves para usar como armazenamentos secretos
  • Criar o ponto de extremidade e a implantação usando o recurso de injeção secreta

Importante

Esta funcionalidade está atualmente em pré-visualização pública. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas.

Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Pré-requisitos

  • Para usar o Azure Machine Learning, você deve ter uma assinatura do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar. Experimente hoje mesmo a versão gratuita ou paga do Azure Machine Learning .

  • Instale e configure a extensão CLI do Azure Machine Learning (v2) ou o SDK Python do Azure Machine Learning (v2).

  • Um grupo de Recursos do Azure, no qual você (ou a entidade de serviço que usa) precisa ter User Access Administrator e Contributor acessar. Você terá esse grupo de recursos se tiver configurado sua extensão do Azure Machine Learning conforme indicado anteriormente.

  • Uma área de trabalho do Azure Machine Learning. Você terá um espaço de trabalho se tiver configurado sua extensão do Azure Machine Learning conforme indicado anteriormente.

  • Qualquer modelo de aprendizado de máquina treinado pronto para pontuação e implantação.

Escolha uma loja secreta

Você pode optar por armazenar seus segredos (como chaves de API) usando:

  • Conexões de espaço de trabalho no espaço de trabalho: Se você usar esse tipo de armazenamento secreto, poderá conceder permissão posteriormente à identidade do ponto de extremidade (no momento da criação do ponto de extremidade) para ler segredos de conexões de espaço de trabalho automaticamente, desde que determinadas condições sejam atendidas. Para obter mais informações, consulte a guia identidade atribuída ao sistema na seção Criar um ponto de extremidade .
  • Cofres de chaves que não estão necessariamente sob o espaço de trabalho: se você usar esse tipo de armazenamento secreto, a identidade do ponto de extremidade não receberá permissão para ler segredos dos cofres de chaves automaticamente. Portanto, se você quiser usar um serviço de cofre de chave gerenciado, como o Cofre de Chaves do Microsoft Azure, como um armazenamento secreto, deverá atribuir uma função adequada posteriormente.

Usar a conexão do espaço de trabalho como um armazenamento secreto

Você pode criar conexões de espaço de trabalho para usar em sua implantação. Por exemplo, você pode criar uma conexão com o Serviço OpenAI do Microsoft Azure usando Conexões de Espaço de Trabalho - Criar API REST.

Como alternativa, você pode criar uma conexão personalizada usando o estúdio Azure Machine Learning (consulte Como criar uma conexão personalizada para fluxo de prompt) ou o Azure AI Studio (consulte Como criar uma conexão personalizada no AI Studio).

  1. Crie uma conexão do 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. Como alternativa, você pode criar uma conexão personalizada:

    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. Verifique se a identidade do usuário pode ler os segredos da conexão do espaço de trabalho, usando Conexões do Espaço de Trabalho - Listar Segredos API REST (visualização).

    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

Os trechos de código anteriores usam um token no cabeçalho ao fazer chamadas à Authorization API REST. Você pode obter o token executando az account get-access-token. Para obter mais informações sobre como obter um token, consulte Obter um token de acesso.

(Opcional) Usar o Azure Key Vault como um armazenamento secreto

Crie o cofre de chaves e defina um segredo para usar em sua implantação. Para obter mais informações sobre como criar o cofre de chaves, consulte Definir e recuperar um segredo do Cofre de Chaves do Azure usando a CLI do Azure. Além disso,

  1. Crie um Cofre da Chave do Azure:

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

  2. Crie um segredo:

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

    Este comando devolve a versão secreta que cria. Você pode verificar a id propriedade da resposta para obter a versão secreta. A resposta retornada se parece com https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Verifique se a identidade do usuário pode ler o segredo do cofre de chaves:

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

Importante

Se você usar o cofre de chaves como um armazenamento secreto para injeção de segredos, deverá configurar o modelo de permissão do cofre de chaves como RBAC (controle de acesso baseado em função) do Azure. Para obter mais informações, consulte Azure RBAC vs. política de acesso para o Cofre de Chaves.

Escolha uma identidade de usuário

Escolha a identidade do usuário que você usará para criar o ponto de extremidade online e a implantação online. Essa identidade de usuário pode ser uma conta de usuário, uma conta de entidade de serviço ou uma identidade gerenciada no Microsoft Entra ID. Para configurar a identidade do usuário, siga as etapas em Configurar a autenticação para recursos e fluxos de trabalho do Azure Machine Learning.

(Opcional) Atribuir uma função à identidade do usuário

  • Se sua identidade de usuário quiser que a identidade atribuída pelo sistema (SAI) do ponto de extremidade receba automaticamente permissão para ler segredos de conexões de espaço de trabalho, a identidade do usuário deverá ter a Azure Machine Learning Workspace Connection Secrets Reader função (ou superior) no escopo do espaço de trabalho.

    • Um administrador que tenha a permissão pode executar um comando da CLI para atribuir a Microsoft.Authorization/roleAssignments/write função à identidade do usuário:

      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

    A identidade atribuída pelo sistema (SAI) do ponto de extremidade não receberá automaticamente permissão para ler segredos dos cofres de chaves. Assim, a identidade do usuário não precisa ser atribuída uma função para o Cofre de Chaves.

  • Se você quiser usar uma identidade atribuída ao usuário (UAI) para o ponto de extremidade, não precisará atribuir a função à sua identidade de usuário. Em vez disso, se você pretende usar o recurso de injeção secreta, deve atribuir a função ao UAI do ponto de extremidade manualmente.

    • Um administrador que tenha a permissão pode executar os seguintes comandos para atribuir a Microsoft.Authorization/roleAssignments/write função à identidade do ponto de extremidade:

      Para conexões de espaço de trabalho:

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

      Para cofres de chaves:

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

  • Verifique se uma identidade (uma identidade de usuário ou identidade de ponto de extremidade) tem a função atribuída, indo para o recurso no portal do Azure. Por exemplo, no espaço de trabalho do Azure Machine Learning ou no Cofre da Chave:

    1. Selecione a guia Controle de acesso (IAM).
    2. Selecione o botão Verificar acesso e encontre a identidade.
    3. Verifique se a função correta aparece na guia Atribuições de função atuais.

Criar um ponto final

Se você estiver usando uma identidade atribuída pelo sistema (SAI) como identidade do ponto de extremidade, especifique se deseja impor o acesso a armazenamentos secretos padrão (ou seja, conexões de espaço de trabalho no espaço de trabalho) à identidade do ponto de extremidade.

  1. Criar um ficheiro 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. Crie o ponto de extremidade, usando o endpoint.yaml arquivo:

    az ml online-endpoint create -f endpoint.yaml

Se você não especificar a identity propriedade na definição de ponto de extremidade, o ponto de extremidade usará um SAI por padrão.

Se as seguintes condições forem atendidas, a identidade do ponto de extremidade receberá automaticamente a Azure Machine Learning Workspace Connection Secrets Reader função (ou superior) no escopo do espaço de trabalho:

  • A identidade do usuário que cria o ponto de extremidade tem a permissão para ler segredos de conexões de espaço de trabalho (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • O ponto de extremidade usa um SAI.
  • O ponto de extremidade é definido com um sinalizador para impor o acesso a armazenamentos secretos padrão (conexões de espaço de trabalho no espaço de trabalho atual) ao criar o ponto de extremidade.

A identidade do ponto de extremidade não receberá automaticamente uma função para ler segredos do Cofre de Chaves. Se você quiser usar o Cofre da Chave como um armazenamento secreto, precisará atribuir manualmente uma função adequada, como Key Vault Secrets User a identidade do ponto de extremidade no escopo do Cofre da Chave. Para obter mais informações sobre funções, consulte Funções internas do Azure para operações de plano de dados do Cofre de Chaves.

Criar uma implantação

  1. Crie um script de pontuação ou Dockerfile e os scripts relacionados para que a implantação possa consumir os segredos por meio de variáveis de ambiente.

    • Não há necessidade de chamar as APIs de recuperação secretas para as conexões de espaço de trabalho ou cofres de chaves. As variáveis de ambiente são preenchidas com os segredos quando o contêiner do usuário na implantação é iniciado.

    • O valor que é injetado em uma variável de ambiente pode ser um dos três tipos:

      • Toda a resposta da API List Secrets (visualização). Você precisará entender a estrutura de resposta da API, analisá-la e usá-la em seu contêiner de usuário.
      • Segredo individual ou metadados da conexão do espaço de trabalho. Você pode usá-lo sem entender a estrutura de resposta da API de conexão do espaço de trabalho.
      • Versão secreta individual do Cofre da Chave. Você pode usá-lo sem entender a estrutura de resposta da API do Cofre de Chaves.

  2. Inicie a criação da implantação, usando o script de pontuação (se você usar um modelo personalizado) ou um Dockerfile (se você adotar a abordagem BYOC para implantação). Especifique as variáveis de ambiente que o usuário espera dentro do contêiner do usuário.

    Se os valores mapeados para as variáveis de ambiente seguirem determinados padrões, a identidade do ponto de extremidade será usada para executar a recuperação e a injeção secretas.

    Padrão Comportamento
    ${{azureml://connections/<connection_name>}} Toda a resposta List Secrets API (visualização) é injetada na variável de ambiente.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} O valor da credencial é injetado na variável de ambiente.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} O valor dos metadados é injetado na variável de ambiente.
    ${{azureml://connections/<connection_name>/target}} O valor do alvo (quando aplicável) é injetado na variável ambiente.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} O valor da versão secreta é injetado na variável de ambiente.

    Por exemplo:

    1. Criar 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. Crie a implantação:

      az ml online-deployment create -f deployment.yaml

Se o sinalizador foi definido para o enforce_access_to_default_secret_stores ponto de extremidade, a permissão da identidade do usuário para ler segredos de conexões de espaço de trabalho será verificada tanto na criação do ponto de extremidade quanto no momento da criação da implantação. Se a identidade do usuário não tiver a permissão, a criação falhará.

No momento da criação da implantação, se qualquer variável de ambiente for mapeada para um valor que siga os padrões da tabela anterior, a recuperação e a injeção secretas serão realizadas com a identidade do ponto de extremidade (um SAI ou um UAI). Se a identidade do ponto de extremidade não tiver permissão para ler segredos de armazenamentos secretos designados (conexões de espaço de trabalho ou cofres de chaves), a criação da implantação falhará. Além disso, se a referência secreta especificada não existir nos repositórios secretos, a criação da implantação falhará.

Para obter mais informações sobre erros que podem ocorrer durante a implantação de pontos de extremidade online do Aprendizado de Máquina do Azure, consulte Erros de injeção secretos.

Consuma os segredos

Você pode consumir os segredos recuperando-os das variáveis de ambiente dentro do contêiner do usuário em execução em suas implantações.

Conteúdos relacionados