Partilhar via

Criar trabalhos e dados de entrada para pontos de extremidade em lote

  • Artigo

Ao usar pontos de extremidade em lote no Aprendizado de Máquina do Azure, você pode executar operações em lote longas em grandes quantidades de dados de entrada. Os dados podem ser localizados em diferentes locais, como em diferentes regiões. Certos tipos de pontos de extremidade em lote também podem receber parâmetros literais como entradas.

Este artigo descreve como especificar entradas de parâmetros para pontos de extremidade em lote e criar trabalhos de implantação. O processo suporta trabalhar com dados de várias fontes, como ativos de dados, armazenamentos de dados, contas de armazenamento e arquivos locais.

Pré-requisitos

  • Um ponto de extremidade e implantação em lote. Para criar esses recursos, consulte Implantar modelos MLflow em implantações em lote no Azure Machine Learning.

  • Permissões para executar uma implantação de ponto de extremidade em lote. Você pode usar as funções de Cientista de Dados, Colaborador e Proprietário do AzureML para executar uma implantação. Para revisar permissões específicas necessárias para definições de função personalizadas, consulte Autorização em pontos de extremidade em lote.

  • Credenciais para invocar um ponto de extremidade. Para obter mais informações, consulte Estabelecer autenticação.

  • Acesso de leitura aos dados de entrada do cluster de computação onde o ponto de extremidade é implantado.

    Gorjeta

    Determinadas situações exigem o uso de um armazenamento de dados sem credenciais ou de uma conta externa do Armazenamento do Azure como entrada de dados. Nesses cenários, certifique-se de configurar clusters de computação para acesso a dados, pois a identidade gerenciada do cluster de computação é usada para montar a conta de armazenamento. Você ainda tem controle de acesso granular, porque a identidade do trabalho (invocador) é usada para ler os dados subjacentes.

Estabelecer autenticação

Para invocar um ponto de extremidade, você precisa de um token válido do Microsoft Entra. Quando você invoca um ponto de extremidade, o Aprendizado de Máquina do Azure cria um trabalho de implantação em lote sob a identidade associada ao token.

  • Se você usar a CLI do Azure Machine Learning (v2) ou o SDK do Azure Machine Learning para Python (v2) para invocar pontos de extremidade, não precisará obter o token do Microsoft Entra manualmente. Durante o login, o sistema autentica sua identidade de usuário. Ele também recupera e passa o token para você.
  • Se você usar a API REST para invocar pontos de extremidade, precisará obter o token manualmente.

Você pode usar suas próprias credenciais para a invocação, conforme descrito nos procedimentos a seguir.

Use a CLI do Azure para entrar com autenticação interativa ou de código de dispositivo:

az login

Para obter mais informações sobre vários tipos de credenciais, consulte Como executar trabalhos usando diferentes tipos de credenciais.

Criar empregos básicos

Para criar um trabalho a partir de um ponto de extremidade em lote, invoque o ponto de extremidade. A invocação pode ser feita usando a CLI do Azure Machine Learning, o SDK do Azure Machine Learning para Python ou uma chamada de API REST.

Os exemplos a seguir mostram noções básicas de invocação para um ponto de extremidade em lote que recebe uma única pasta de dados de entrada para processamento. Para obter exemplos que envolvem várias entradas e saídas, consulte Compreender entradas e saídas.

Use a invoke operação em pontos de extremidade de lote:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Invocar uma implantação específica

Os pontos de extremidade em lote podem hospedar várias implantações sob o mesmo ponto de extremidade. O ponto de extremidade padrão é usado, a menos que o usuário especifique o contrário. Você pode usar os procedimentos a seguir para alterar a implantação que você usa.

Use o argumento --deployment-name ou -d para especificar o nome da implantação:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --deployment-name $DEPLOYMENT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Configurar propriedades do trabalho

Você pode configurar algumas propriedades de trabalho no momento da invocação.

Nota

Atualmente, você pode configurar propriedades de trabalho somente em pontos de extremidade em lote com implantações de componentes de pipeline.

Configurar o nome do experimento

Use os procedimentos a seguir para configurar o nome do experimento.

Use o argumento --experiment-name para especificar o nome do experimento:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --experiment-name "my-batch-job-experiment" \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Compreender entradas e saídas

Os pontos de extremidade em lote fornecem uma API durável que os consumidores podem usar para criar trabalhos em lote. A mesma interface pode ser usada para especificar as entradas e saídas esperadas pela sua implantação. Use entradas para passar qualquer informação que seu ponto de extremidade precisa para executar o trabalho.

Diagrama que mostra como as entradas e saídas são usadas em pontos de extremidade em lote.

Os pontos de extremidade em lote suportam dois tipos de entradas:

  • Entradas de dados ou ponteiros para um local de armazenamento específico ou ativo do Azure Machine Learning
  • Entradas literais ou valores literais como números ou cadeias de caracteres que você deseja passar para o trabalho

O número e o tipo de entradas e saídas dependem do tipo de implantação em lote. As implantações de modelo sempre exigem uma entrada de dados e produzem uma saída de dados. Não há suporte para entradas literais em implantações de modelo. Em contraste, as implantações de componentes de pipeline fornecem uma construção mais geral para a construção de pontos de extremidade. Em uma implantação de componente de pipeline, você pode especificar qualquer número de entradas de dados, entradas literais e saídas.

A tabela a seguir resume as entradas e saídas para implantações em lote:

Tipo de implementação Número de entradas Tipos de entrada suportados Número de saídas Tipos de saída suportados
Implantação do modelo 1 Introdução de dados 1 Saídas de dados
Implantação de componentes de pipeline 0-N Entradas de dados e entradas literais 0-N Saídas de dados

Gorjeta

As entradas e saídas são sempre nomeadas. Cada nome serve como uma chave para identificar os dados e passar o valor durante a invocação. Como as implantações de modelo sempre exigem uma entrada e uma saída, os nomes são ignorados durante a invocação em implantações de modelo. Você pode atribuir o nome que melhor descreve seu caso de uso, como sales_estimation.

Explore entradas de dados

As entradas de dados referem-se a entradas que apontam para um local onde os dados são colocados. Como os pontos de extremidade em lote geralmente consomem grandes quantidades de dados, não é possível passar os dados de entrada como parte da solicitação de invocação. Em vez disso, você especifica o local onde o ponto de extremidade do lote deve ir para procurar os dados. Os dados de entrada são montados e transmitidos na instância de computação de destino para melhorar o desempenho.

Os pontos de extremidade em lote podem ler arquivos localizados nos seguintes tipos de armazenamento:

  • Ativos de dados do Azure Machine Learning, incluindo os tipos de pasta (uri_folder) e arquivo (uri_file).
  • Armazenamentos de dados do Azure Machine Learning, incluindo o Armazenamento de Blobs do Azure, o Azure Data Lake Storage Gen1 e o Azure Data Lake Storage Gen2.
  • Contas de Armazenamento do Azure, incluindo Blob Storage, Data Lake Storage Gen1 e Data Lake Storage Gen2.
  • Pastas e arquivos de dados locais, quando você usa a CLI do Azure Machine Learning ou o SDK do Azure Machine Learning para Python para invocar pontos de extremidade. Mas os dados locais são carregados no armazenamento de dados padrão do seu espaço de trabalho do Azure Machine Learning.

Importante

Aviso de descontinuação: os ativos de dados do tipo FileDataset (V1) foram preteridos e serão desativados no futuro. Os pontos de extremidade em lote existentes que dependem dessa funcionalidade continuarão a funcionar. Mas não há suporte para conjuntos de dados V1 em pontos de extremidade em lote que são criados com:

  • Versões da CLI do Azure Machine Learning v2 que estão geralmente disponíveis (2.4.0 e mais recentes).
  • Versões da API REST que estão disponíveis em geral (2022-05-01 e mais recentes).

Explore entradas literais

Entradas literais referem-se a entradas que podem ser representadas e resolvidas no momento da invocação, como cadeias de caracteres, números e valores booleanos. Normalmente, você usa entradas literais para passar parâmetros para seu ponto de extremidade como parte de uma implantação de componente de pipeline. Os pontos de extremidade em lote suportam os seguintes tipos literais:

  • string
  • boolean
  • float
  • integer

As entradas literais só são suportadas em implantações de componentes de pipeline. Para ver como especificar pontos de extremidade literais, consulte Criar trabalhos com entradas literais.

Explore saídas de dados

As saídas de dados referem-se ao local onde os resultados de um trabalho em lote são colocados. Cada saída tem um nome identificável e o Azure Machine Learning atribui automaticamente um caminho exclusivo a cada saída nomeada. Você pode especificar outro caminho, se necessário.

Importante

Os pontos de extremidade em lote suportam apenas saídas de gravação em armazenamentos de dados de Armazenamento de Blob. Se precisar gravar em uma conta de armazenamento com namespaces hierárquicos habilitados, como o Data Lake Storage Gen2, você poderá registrar o serviço de armazenamento como um armazenamento de dados de Armazenamento de Blob, pois os serviços são totalmente compatíveis. Dessa forma, você pode gravar saídas de pontos de extremidade em lote para o Data Lake Storage Gen2.

Criar trabalhos com entradas de dados

Os exemplos a seguir mostram como criar trabalhos ao usar entradas de dados de ativos de dados, armazenamentos de dados e contas de Armazenamento do Azure.

Usar dados de entrada de um ativo de dados

Os ativos de dados do Azure Machine Learning (anteriormente conhecidos como conjuntos de dados) são suportados como entradas para trabalhos. Siga estas etapas para executar um trabalho de ponto de extremidade em lote que usa dados de entrada armazenados em um ativo de dados registrado no Aprendizado de Máquina do Azure.

Aviso

Atualmente, não há suporte para ativos de dados do tipo tabela (MLTable).

  1. Crie o ativo de dados. Neste exemplo, ele consiste em uma pasta que contém vários arquivos CSV. Você usa pontos de extremidade em lote para processar os arquivos em paralelo. Você pode pular esta etapa se seus dados já estiverem registrados como um ativo de dados.

    1. Crie uma definição de ativo de dados em um arquivo YAML chamado heart-data.yml:

      $schema: https://azuremlschemas.azureedge.net/latest/data.schema.json
name: heart-data
description: An unlabeled data asset for heart classification.
type: uri_folder
path: data

    2. Crie o ativo de dados:

      az ml data create -f heart-data.yml

  2. Configure a entrada:

    DATA_ASSET_ID=$(az ml data show -n heart-data --label latest | jq -r .id)

    O ID do ativo de dados tem o formato /subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/data/<data-asset-name>/versions/<data-asset-version>.

  3. Execute o ponto de extremidade:

    Use o --set argumento para especificar a entrada. Primeiro, substitua qualquer hífenes no nome do ativo de dados por caracteres de sublinhado. As teclas podem conter apenas caracteres alfanuméricos e caracteres sublinhados.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_data.type="uri_folder" inputs.heart_data.path=$DATA_ASSET_ID

    Para um ponto de extremidade que serve a uma implantação de modelo, você pode usar o --input argumento para especificar a entrada de dados, porque uma implantação de modelo sempre requer apenas uma entrada de dados.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $DATA_ASSET_ID

    O argumento --set tende a produzir comandos longos quando você especifica várias entradas. Nesses casos, você pode listar suas entradas em um arquivo e, em seguida, consultar o arquivo quando invocar seu ponto de extremidade. Por exemplo, você pode criar um arquivo YAML chamado inputs.yml que contém as seguintes linhas:

    inputs:
  heart_data:
    type: uri_folder
    path: /subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/data/heart-data/versions/1

    Em seguida, você pode executar o seguinte comando, que usa o --file argumento para especificar as entradas:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

Usar dados de entrada de um armazenamento de dados

Seus trabalhos de implantação em lote podem fazer referência direta a dados que estão em armazenamentos de dados registrados do Azure Machine Learning. Neste exemplo, você primeiro carrega alguns dados em um armazenamento de dados em seu espaço de trabalho do Azure Machine Learning. Em seguida, você executa uma implantação em lote nesses dados.

Este exemplo usa o armazenamento de dados padrão, mas você pode usar um armazenamento de dados diferente. Em qualquer espaço de trabalho do Azure Machine Learning, o nome do armazenamento de dados de blob padrão é workspaceblobstore. Se você quiser usar um armazenamento de dados diferente nas etapas a seguir, substitua workspaceblobstore pelo nome do seu armazenamento de dados preferido.

  1. Carregue dados de exemplo para o armazenamento de dados. Os dados de exemplo estão disponíveis no repositório azureml-examples . Você pode encontrar os dados na pasta sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data desse repositório.

    1. No estúdio do Azure Machine Learning, abra a página de ativos de dados para seu armazenamento de dados de blob padrão e procure o nome de seu contêiner de blob.
    2. Use uma ferramenta como o Gerenciador de Armazenamento do Azure ou o AzCopy para carregar os dados de exemplo em uma pasta chamada heart-disease-uci-unlabeled nesse contêiner.

  2. Configure as informações de entrada:

    Coloque o caminho do INPUT_PATH arquivo na variável:

    DATA_PATH="heart-disease-uci-unlabeled"
INPUT_PATH="azureml://datastores/workspaceblobstore/paths/$DATA_PATH"

    Observe como a paths pasta faz parte do caminho de entrada. Esse formato indica que o valor a seguir é um caminho.

  3. Execute o ponto de extremidade:

    Use o --set argumento para especificar a entrada:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_data.type="uri_folder" inputs.heart_data.path=$INPUT_PATH

    Para um ponto de extremidade que serve a uma implantação de modelo, você pode usar o --input argumento para especificar a entrada de dados, porque uma implantação de modelo sempre requer apenas uma entrada de dados.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_PATH --input-type uri_folder

    O argumento --set tende a produzir comandos longos quando você especifica várias entradas. Nesses casos, você pode listar suas entradas em um arquivo e, em seguida, consultar o arquivo quando invocar seu ponto de extremidade. Por exemplo, você pode criar um arquivo YAML chamado inputs.yml que contém as seguintes linhas:

    inputs:
  heart_data:
    type: uri_folder
    path: azureml://datastores/workspaceblobstore/paths/<data-path>

    Se os dados estiverem em um arquivo, use o uri_file tipo para a entrada.

    Em seguida, você pode executar o seguinte comando, que usa o --file argumento para especificar as entradas:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

Usar dados de entrada de uma conta de Armazenamento do Azure

Os pontos de extremidade em lote do Azure Machine Learning podem ler dados de locais de nuvem em contas de Armazenamento do Azure, públicas e privadas. Use as etapas a seguir para executar um trabalho de ponto de extremidade em lote com dados em uma conta de armazenamento.

Para obter mais informações sobre configurações adicionais necessárias para ler dados de contas de armazenamento, consulte Configurar clusters de computação para acesso a dados.

  1. Configure a entrada:

    Defina a INPUT_DATA variável:

    INPUT_DATA="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data"

    Se os dados estiverem em um arquivo, use um formato semelhante ao seguinte para definir o caminho de entrada:

    INPUT_DATA="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data/heart.csv"

  2. Execute o ponto de extremidade:

    Use o --set argumento para especificar a entrada:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_data.type="uri_folder" inputs.heart_data.path=$INPUT_DATA

    Para um ponto de extremidade que serve a uma implantação de modelo, você pode usar o --input argumento para especificar a entrada de dados, porque uma implantação de modelo sempre requer apenas uma entrada de dados.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_DATA --input-type uri_folder

    O --set argumento tende a produzir comandos longos quando você especifica várias entradas. Nesses casos, você pode listar suas entradas em um arquivo e, em seguida, consultar o arquivo quando invocar seu ponto de extremidade. Por exemplo, você pode criar um arquivo YAML chamado inputs.yml que contém as seguintes linhas:

    inputs:
  heart_data:
    type: uri_folder
    path: https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

    Em seguida, você pode executar o seguinte comando, que usa o --file argumento para especificar as entradas:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

    Se os dados estiverem em um arquivo, use o uri_file tipo no arquivo inputs.yml para a entrada de dados.

Crie trabalhos com entradas literais

As implantações de componentes de pipeline podem ter entradas literais. Para obter um exemplo de uma implantação em lote que contém um pipeline básico, consulte Como implantar pipelines com pontos de extremidade em lote.

O exemplo a seguir mostra como especificar uma entrada chamada score_mode, do tipo string, com um valor de append:

Coloque suas entradas em um arquivo YAML, como um chamado inputs.yml:

inputs:
  score_mode:
    type: string
    default: append

Execute o seguinte comando, que usa o --file argumento para especificar as entradas.

az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

Você também pode usar o --set argumento para especificar o tipo e o valor padrão. Mas essa abordagem tende a produzir comandos longos quando você especifica várias entradas:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.score_mode.type="string" inputs.score_mode.default="append"

Criar trabalhos com saídas de dados

O exemplo a seguir mostra como alterar o local de uma saída chamada score. Para completar, o exemplo também configura uma entrada chamada heart_data.

Este exemplo usa o armazenamento de dados padrão, workspaceblobstore. Mas você pode usar qualquer outro armazenamento de dados em seu espaço de trabalho, desde que seja uma conta de Armazenamento de Blob. Se você quiser usar um armazenamento de dados diferente, substitua workspaceblobstore nas etapas a seguir pelo nome do seu armazenamento de dados preferido.

  1. Obtenha a ID do armazenamento de dados.

    DATA_STORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')

    O ID do armazenamento de dados tem o formato /subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/datastores/workspaceblobstore.

  2. Crie uma saída de dados:

    Defina os valores de entrada e saída em um arquivo chamado inputs-and-outputs.yml. Use o ID do armazenamento de dados no caminho de saída. Para completar, defina também a entrada de dados.

    inputs:
  heart_data:
    type: uri_folder
    path: https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data
outputs:
  score:
    type: uri_file
    path: <data-store-ID>/paths/batch-jobs/my-unique-path

    Nota

    Observe como a paths pasta faz parte do caminho de saída. Esse formato indica que o valor a seguir é um caminho.

  3. Execute a implantação:

    Use o --file argumento para especificar os valores de entrada e saída:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs-and-outputs.yml

Conteúdos relacionados