Aceder aos recursos do Azure a partir de um ponto de extremidade online com uma identidade gerida

  • Artigo

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

Saiba como aceder aos recursos do Azure a partir do seu script de pontuação com um ponto de extremidade online e uma identidade gerida atribuída pelo sistema ou uma identidade gerida atribuída pelo utilizador.

Os pontos de extremidade gerenciados e os pontos de extremidade do Kubernetes permitem que o Azure Machine Learning gerencie a carga de provisionar seu recurso de computação e implantar seu modelo de aprendizado de máquina. Normalmente, seu modelo precisa acessar recursos do Azure, como o Registro de Contêiner do Azure ou seu armazenamento de blob para inferência; Com uma identidade gerenciada, você pode acessar esses recursos sem precisar gerenciar credenciais em seu código. Saiba mais sobre identidades gerenciadas.

Este guia pressupõe que você não tenha uma identidade gerenciada, uma conta de armazenamento ou um ponto de extremidade online. Se já tiver estes componentes, avance para a secção Conceder permissão de acesso à identidade gerida.

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 e ML (v2) do Azure. Para obter mais informações, consulte Instalar, configurar e usar a CLI 2.0.

  • Um grupo de recursos do Azure, no qual você (ou a entidade de serviço usada) precisa ter acesso de Administrador de Acesso de Usuário e de Colaborador . Você tem esse grupo de recursos se configurou sua extensão de ML de acordo com o artigo anterior.

  • Uma área de trabalho do Azure Machine Learning. Você já tem um espaço de trabalho se configurou sua extensão de ML de acordo com o artigo anterior.

  • Um modelo de aprendizado de máquina treinado pronto para pontuação e implantação. Se você estiver acompanhando a amostra, um modelo será fornecido.

  • Se você ainda não definiu os padrões para a CLI do Azure, salve suas configurações padrão. Para evitar passar os valores da sua assinatura, espaço de trabalho e grupo de recursos várias vezes, execute este código:

    az account set --subscription <subscription ID>
az configure --defaults gitworkspace=<Azure Machine Learning workspace name> group=<resource group>

  • Para acompanhar o exemplo, clone o repositório de amostras e, em seguida, altere o diretório para cli.

    git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

Limitações

  • A identidade de um ponto de extremidade é imutável. Durante a criação do ponto de extremidade, você pode associá-lo a uma identidade atribuída pelo sistema (padrão) ou a uma identidade atribuída pelo usuário. Não é possível alterar a identidade depois que o ponto de extremidade é criado.
  • Se o armazenamento ARC e blob estiver configurado como privado, ou seja, atrás de uma rede virtual, o acesso a partir do ponto de extremidade do Kubernetes deverá ser feito pelo link privado, independentemente de seu espaço de trabalho ser público ou privado. Mais detalhes sobre a configuração de link privado, consulte Como proteger a vnet do espaço de trabalho.

Configurar variáveis para implantação

Configure os nomes das variáveis para o espaço de trabalho, o local do espaço de trabalho e o ponto de extremidade que você deseja criar para uso com sua implantação.

O código a seguir exporta esses valores como variáveis de ambiente em seu ponto de extremidade:

export WORKSPACE="<WORKSPACE_NAME>"
export LOCATION="<WORKSPACE_LOCATION>"
export ENDPOINT_NAME="<ENDPOINT_NAME>"

Em seguida, especifique o nome que você deseja dar à sua conta de armazenamento de blob, contêiner de blob e arquivo. Esses nomes de variáveis são definidos aqui e são referidos em az storage account create e az storage container create comandos na próxima seção.

O código a seguir exporta esses valores como variáveis de ambiente:

export STORAGE_ACCOUNT_NAME="<BLOB_STORAGE_TO_ACCESS>"
export STORAGE_CONTAINER_NAME="<CONTAINER_TO_ACCESS>"
export FILE_NAME="<FILE_TO_ACCESS>"

Depois que essas variáveis forem exportadas, crie um arquivo de texto localmente. Quando o ponto de extremidade é implantado, o script de pontuação acessa esse arquivo de texto usando a identidade gerenciada atribuída pelo sistema que é gerada na criação do ponto de extremidade.

Definir a configuração de implantação

Para implantar um ponto de extremidade online com a CLI, você precisa definir a configuração em um arquivo YAML. Para obter mais informações sobre o esquema YAML, consulte o documento de referência do YAML do ponto de extremidade online.

Os arquivos YAML nos exemplos a seguir são usados para criar pontos de extremidade online.

O exemplo de YAML a seguir está localizado em endpoints/online/managed/managed-identities/1-sai-create-endpoint. O ficheiro,

  • Define o nome pelo qual você deseja se referir ao ponto de extremidade, my-sai-endpoint.
  • Especifica o tipo de autorização a ser usada para acessar o ponto de extremidade, auth-mode: key.
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-sai-endpoint
auth_mode: key

Este exemplo de YAML, 2-sai-deployment.yml,

  • Especifica que o tipo de ponto de extremidade que você deseja criar é um online ponto de extremidade.
  • Indica que o ponto de extremidade tem uma implantação associada chamada blue.
  • Configura os detalhes da implantação, como qual modelo implantar e qual ambiente e script de pontuação usar.
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score_managedidentity.py
environment:
  conda_file: ../../model-1/environment/conda-managedidentity.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1
environment_variables:
  STORAGE_ACCOUNT_NAME: "storage_place_holder"
  STORAGE_CONTAINER_NAME: "container_place_holder"
  FILE_NAME: "file_place_holder"

Criar a identidade gerenciada

Para acessar os recursos do Azure, crie uma identidade gerenciada atribuída pelo sistema ou pelo usuário para seu ponto de extremidade online.

Quando você cria um ponto de extremidade online, uma identidade gerenciada atribuída ao sistema é gerada automaticamente para você, portanto, não há necessidade de criar uma identidade separada.

Criar conta de armazenamento e contêiner

Para este exemplo, crie uma conta de armazenamento de blob e um contêiner de blob e, em seguida, carregue o arquivo de texto criado anteriormente para o contêiner de blob. Você concede ao ponto de extremidade online e à identidade gerenciada acesso a essa conta de armazenamento e contêiner de blob.

Primeiro, crie uma conta de armazenamento.

az storage account create --name $STORAGE_ACCOUNT_NAME --location $LOCATION

Em seguida, crie o contêiner de blob na conta de armazenamento.

az storage container create --account-name $STORAGE_ACCOUNT_NAME --name $STORAGE_CONTAINER_NAME

Em seguida, carregue seu arquivo de texto para o contêiner de blob.

az storage blob upload --account-name $STORAGE_ACCOUNT_NAME --container-name $STORAGE_CONTAINER_NAME --name $FILE_NAME --file endpoints/online/managed/managed-identities/hello.txt

Criar um ponto de extremidade online

O código a seguir cria um ponto de extremidade online sem especificar uma implantação.

Aviso

A identidade de um ponto de extremidade é imutável. Durante a criação do ponto de extremidade, você pode associá-lo a uma identidade atribuída pelo sistema (padrão) ou a uma identidade atribuída pelo usuário. Não é possível alterar a identidade após a criação do ponto de extremidade.

Quando você cria um ponto de extremidade online, uma identidade gerenciada atribuída ao sistema é criada para o ponto de extremidade por padrão.

az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/managed-identities/1-sai-create-endpoint.yml

Verifique o status do ponto de extremidade com o seguinte.

az ml online-endpoint show --name $ENDPOINT_NAME

Se você encontrar algum problema, consulte Solução de problemas de implantação e pontuação de pontos de extremidade online.

Conceder permissão de acesso à identidade gerenciada

Importante

Os pontos de extremidade online exigem a permissão de pull do Registro de Contêiner do Azure, a permissão AcrPull para o registro de contêiner e a permissão do Leitor de Dados de Blob de Armazenamento para o armazenamento de dados padrão do espaço de trabalho.

Você pode permitir que a permissão de ponto de extremidade online acesse seu armazenamento por meio de sua identidade gerenciada atribuída pelo sistema ou dar permissão à identidade gerenciada atribuída pelo usuário para acessar a conta de armazenamento criada na seção anterior.

Recupere a identidade gerenciada atribuída ao sistema que foi criada para seu ponto de extremidade.

system_identity=`az ml online-endpoint show --name $ENDPOINT_NAME --query "identity.principal_id" -o tsv`

A partir daqui, você pode conceder permissão de identidade gerenciada atribuída ao sistema para acessar seu armazenamento.

az role assignment create --assignee-object-id $system_identity --assignee-principal-type ServicePrincipal --role "Storage Blob Data Reader" --scope $storage_id

Script de pontuação para acessar o recurso do Azure

Consulte o script a seguir para entender como usar seu token de identidade para acessar recursos do Azure, neste cenário, a conta de armazenamento criada nas seções anteriores.

import os
import logging
import json
import numpy
import joblib
import requests
from azure.identity import ManagedIdentityCredential
from azure.storage.blob import BlobClient


def access_blob_storage_sdk():
    credential = ManagedIdentityCredential(client_id=os.getenv("UAI_CLIENT_ID"))
    storage_account = os.getenv("STORAGE_ACCOUNT_NAME")
    storage_container = os.getenv("STORAGE_CONTAINER_NAME")
    file_name = os.getenv("FILE_NAME")

    blob_client = BlobClient(
        account_url=f"https://{storage_account}.blob.core.windows.net/",
        container_name=storage_container,
        blob_name=file_name,
        credential=credential,
    )
    blob_contents = blob_client.download_blob().content_as_text()
    logging.info(f"Blob contains: {blob_contents}")


def get_token_rest():
    """
    Retrieve an access token via REST.
    """

    access_token = None
    msi_endpoint = os.environ.get("MSI_ENDPOINT", None)
    msi_secret = os.environ.get("MSI_SECRET", None)

    # If UAI_CLIENT_ID is provided then assume that endpoint was created with user assigned identity,
    # # otherwise system assigned identity deployment.
    client_id = os.environ.get("UAI_CLIENT_ID", None)
    if client_id is not None:
        token_url = (
            msi_endpoint + f"?clientid={client_id}&resource=https://storage.azure.com/"
        )
    else:
        token_url = msi_endpoint + f"?resource=https://storage.azure.com/"

    logging.info("Trying to get identity token...")
    headers = {"secret": msi_secret, "Metadata": "true"}
    resp = requests.get(token_url, headers=headers)
    resp.raise_for_status()
    access_token = resp.json()["access_token"]
    logging.info("Retrieved token successfully.")
    return access_token


def access_blob_storage_rest():
    """
    Access a blob via REST.
    """

    logging.info("Trying to access blob storage...")
    storage_account = os.environ.get("STORAGE_ACCOUNT_NAME")
    storage_container = os.environ.get("STORAGE_CONTAINER_NAME")
    file_name = os.environ.get("FILE_NAME")
    logging.info(
        f"storage_account: {storage_account}, container: {storage_container}, filename: {file_name}"
    )
    token = get_token_rest()

    blob_url = f"https://{storage_account}.blob.core.windows.net/{storage_container}/{file_name}?api-version=2019-04-01"
    auth_headers = {
        "Authorization": f"Bearer {token}",
        "x-ms-blob-type": "BlockBlob",
        "x-ms-version": "2019-02-02",
    }
    resp = requests.get(blob_url, headers=auth_headers)
    resp.raise_for_status()
    logging.info(f"Blob contains: {resp.text}")


def init():
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # For multiple models, it points to the folder containing all deployed models (./azureml-models)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Model loaded")

    # Access Azure resource (Blob storage) using system assigned identity token
    access_blob_storage_rest()
    access_blob_storage_sdk()

    logging.info("Init complete")


# note you can pass in multiple rows for scoring
def run(raw_data):
    logging.info("Request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

Criar uma implantação com sua configuração

Crie uma implantação associada ao ponto de extremidade online. Saiba mais sobre a implantação em endpoints online.

Aviso

Essa implantação pode levar aproximadamente de 8 a 14 minutos, dependendo se o ambiente/imagem subjacente está sendo criado pela primeira vez. As implantações subsequentes usando o mesmo ambiente serão mais rápidas.

az ml online-deployment create --endpoint-name $ENDPOINT_NAME --all-traffic --name blue --file endpoints/online/managed/managed-identities/2-sai-deployment.yml --set environment_variables.STORAGE_ACCOUNT_NAME=$STORAGE_ACCOUNT_NAME environment_variables.STORAGE_CONTAINER_NAME=$STORAGE_CONTAINER_NAME environment_variables.FILE_NAME=$FILE_NAME

Nota

O valor do --name argumento pode substituir a name chave dentro do arquivo YAML.

Verifique o estado da implementação.

az ml online-deployment show --endpoint-name $ENDPOINT_NAME --name blue

Para refinar a consulta acima para retornar apenas dados específicos, consulte Consultar saída de comando da CLI do Azure.

Nota

O método init no script de pontuação lê o arquivo da sua conta de armazenamento usando o token de identidade gerenciado atribuído pelo sistema.

Para verificar a saída do método init, consulte o log de implantação com o código a seguir.

# Check deployment logs to confirm blob storage file contents read operation success.
az ml online-deployment get-logs --endpoint-name $ENDPOINT_NAME --name blue

Quando a implantação for concluída, o modelo, o ambiente e o ponto de extremidade serão registrados em seu espaço de trabalho do Azure Machine Learning.

Testar o parâmetro de avaliação

Depois que seu endpoint online for implantado, teste e confirme sua operação com uma solicitação. Os detalhes da inferência variam de modelo para modelo. Para este guia, os parâmetros de consulta JSON têm a seguinte aparência:

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

Para chamar seu ponto de extremidade, execute:

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

Excluir o ponto de extremidade e a conta de armazenamento

Se você não planeja continuar usando o endpoint e o armazenamento online implantados, exclua-os para reduzir custos. Quando você exclui o ponto de extremidade, todas as implantações associadas também são excluídas.

az ml online-endpoint delete --name $ENDPOINT_NAME --yes

az storage account delete --name $STORAGE_ACCOUNT_NAME --yes

Conteúdos relacionados