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

  • Artigo

Os pontos de extremidade em lote podem ser usados para executar uma pontuação de lote em grandes quantidades de dados. Esses dados podem ser colocados em diferentes lugares. Alguns tipos de pontos de extremidade em lote também podem receber parâmetros literais como entradas. Neste tutorial, abordaremos como você pode especificar essas entradas e os diferentes tipos ou locais com suporte.

Antes de invocar um ponto de extremidade

Para invocar com êxito um ponto de extremidade em lote e criar trabalhos, verifique se você tem o seguinte:

  • Você tem permissões para executar uma implantação de ponto de extremidade em lote. As funções de Cientista de Dados, Colaborador e Proprietário do AzureML podem ser usadas para executar uma implantação. Para definições de funções personalizadas, leia Autorização em pontos de extremidade em lote para saber quais são as permissões específicas necessárias.

  • Você tem um token válido do Microsoft Entra ID que representa uma entidade de segurança para invocar o ponto de extremidade. Essa entidade de segurança pode ser uma entidade de usuário ou uma entidade de serviço. De qualquer forma, quando um ponto de extremidade é invocado, um trabalho de implantação em lote é criado na identidade associada ao token. Para fins de teste, você pode usar suas credenciais para a invocação, conforme mencionado abaixo.

    Use a CLI do Azure para fazer login usando autenticação interativa ou do código de dispositivo:

    az login

    Para saber mais sobre como autenticar com vários tipos de credenciais, leia Autorização em pontos de extremidade em lotes.

  • O cluster de cálculo em que o ponto de extremidade está implantado tem acesso para ler os dados inseridos.

    Dica

    Se você estiver usando um armazenamento de dados sem credencial ou uma Conta de Armazenamento do Azure externa como entrada de dados, configure clusters de cálculo para acesso a dados. A identidade gerenciada do cluster de cálculo é usada para montar a conta de armazenamento. A identidade do trabalho (invocador) ainda é usada para ler os dados subjacentes, permitindo que você obtenha um controle de acesso mais refinado.

Criar noções básicas de trabalhos

Para criar um trabalho a partir de um ponto de extremidade em lote, você precisa invocá-lo. A invocação pode ser feita usando a CLI do Azure, o SDK do Azure Machine Learning para Python ou uma chamada à API REST. Os exemplos a seguir mostram os conceitos básicos da invocação para um ponto de extremidade em lote que recebe uma única pasta de dados de entrada para processamento. Consulte Compreensão de entradas e saídas para obter exemplos com entradas e saídas diferentes.

Use a operação invoke em pontos de extremidade em 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 do lote podem hospedar várias implantações no mesmo ponto de extremidade. O ponto de extremidade padrão será usado, salvo especificações em contrário por parte do usuário. Você pode alterar a implantação usada da seguinte maneira:

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 das propriedades no trabalho criado no momento da invocação.

Observação

A configuração de propriedades de trabalho só está disponível em pontos de extremidade em lotes com implantações de componente pipeline por momento.

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

Processando 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 as saídas que sua implantação espera. Use entradas para passar qualquer informação que seu ponto de extremidade precise para executar o trabalho.

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

Os pontos de extremidade do lote dão suporte a dois tipos de entradas:

  • Entradas de dados, que são ponteiros para um local de armazenamento específico ou ativo do Azure Machine Learning.
  • Entradas literais, que são 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 requerem uma entrada de dados e produzem uma saída de dados. Não há suporte para entradas de literais. No entanto, as implantações de componentes do pipeline fornecem um constructo mais geral para criar pontos de extremidade e permitem que você especifique qualquer número de entradas (de dados e de literais) e saídas.

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

Tipo de implantação Número da entrada Tipos de entrada com suporte Número da saída Tipos de saída com suporte
Implantação de modelo 1 Entradas de dados 1 Saídas de dados
Implantação do componente de pipeline [0..N] Entradas de dados e entradas literais [0..N] Saídas de dados

Dica

Entradas e saídas são sempre nomeadas. Esses nomes atuam como chaves para identificá-las e repassar o valor real durante a invocação. Para as implantações de modelo, como sempre requerem uma entrada e uma saída, o nome é ignorado durante a invocação. Você pode atribuir o nome o que melhor descreva seu caso de uso, como, por exemplo "estimativas_de_vendas".

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, você não pode passar os dados de entrada como parte da solicitação de invocação. Em vez disso, você especifica o local aonde o ponto de extremidade do lote deve ir para procurar os dados. Os dados de entrada são montados e transmitidos na computação de destino para melhorar o desempenho.

Os pontos de extremidade do Lote dão suporte à leitura de arquivos localizados nas seguintes opções de armazenamento:

  • Ativos de dados do Azure Machine Learning, incluindo 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 o Azure Data Lake Storage Gen1, o Azure Data Lake Storage Gen2 e o Armazenamento de Blobs do Azure.
  • Pastas/arquivos de dados locais (CLI do Azure Machine Learning ou SDK do Azure Machine Learning para Python). No entanto, essa operação faz com que os dados locais sejam carregados no armazenamento de dados padrão do Azure Machine Learning no workspace no qual você está trabalhando.

Importante

Aviso de substituição: conjuntos de dados do tipo FileDataset (V1) estão preteridos e serão desativados no futuro. Os pontos de extremidade em lote existentes que dependem dessa funcionalidade continuarão funcionando, mas os criados com a CLI v2 (2.4.0 e mais recente) GA ou com a REST API (2022-05-01 e mais recente) GA não serão compatíveis com o conjunto de dados da V1.

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 boolianos. Normalmente, você usa entradas literais para passar parâmetros para o ponto de extremidade como parte de uma implantação de componente de pipeline. Os pontos de extremidade do lote dão suporte aos seguintes tipos literais:

  • string
  • boolean
  • float
  • integer

As entradas de literais só têm suporte nas implantações de componentes do pipeline. Confira Criar trabalhos com entradas de literais para saber como especificá-las.

Saídas de dados

As saídas de dados referem-se ao local em que os resultados de um trabalho em lote devem ser colocados. As saídas são identificadas pelo nome e o Azure Machine Learning atribui automaticamente um caminho exclusivo para cada saída nomeada. No entanto, você pode especificar outro caminho, se necessário.

Importante

Os pontos de extremidade em lote só dão suporte à gravação de saídas nos armazenamentos de dados do Armazenamento de Blobs do Azure. Se você precisar gravar em uma conta de armazenamento com namespaces hierárquicos habilitados (também conhecidos como Azure Datalake Gen2 ou ADLS Gen2), observe que esse serviço de armazenamento pode ser registrado como um armazenamento de dados do Armazenamento de Blobs do Azure, uma vez que os serviços são totalmente compatíveis. Dessa forma, você pode gravar saídas de pontos de extremidade em lote no ADLS Gen2.

Criar trabalhos com entradas de dados

Os exemplos a seguir mostram como criar trabalhos obtendo entradas de dados de ativos de dados, armazenamentos de dados e Contas de Armazenamento do Azure.

Inserir dados de um ativo de dados

Os ativos de dados do Azure Machine Learning (anteriormente conhecidos como conjuntos de dados) têm suporte como entradas para trabalhos. Siga estas etapas para executar um trabalho de ponto de extremidade em lote usando os dados armazenados em um ativo de dados registrado no Azure Machine Learning:

Aviso

No momento, os ativos de dados do tipo Tabela (MLTable) não são compatíveis no momento.

  1. Em primeiro lugar, crie o ativo de dados. Esse ativo de dados consiste de uma pasta com diversos arquivos CSV que você processará em paralelo, usando pontos de extremidade em lote. Você pode ignorar essa etapa se seus dados já estiverem registrados como um ativo de dados.

    Crie uma definição de ativo de dados em YAML:

    heart-dataset-unlabeled.yml

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

    Em seguida, crie o ativo de dados:

    az ml data create -f heart-dataset-unlabeled.yml

  2. Crie a entrada ou a solicitação:

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

    Observação

    A ID de ativos de dados seria semelhante a /subscriptions/<subscription>/resourcegroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/data/<data-asset>/versions/<version>. Você também pode usar azureml:/<datasset_name>@latest como uma maneira de especificar a entrada.

  3. Execute o ponto de extremidade:

    Use o argumento --set para especificar a entrada:

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

    No caso de um ponto de extremidade usado para uma implantação de modelo, você pode usar o argumento --input para especificar a entrada de dados, já que uma implantação de modelo sempre requer apenas uma entrada de dados.

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

    O argumento --set tende a produzir comandos longos quando várias entradas são especificadas. Nesses casos, coloque suas entradas em um arquivo YAML e use --file para especificar as entradas necessárias para a invocação do seu ponto de extremidade.

    inputs.yml

    inputs:
  heart_dataset: azureml:/<datasset_name>@latest

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

Inserir dados de armazenamentos de dados

Os dados de armazenamentos de dados registrados do Azure Machine Learning podem ser referenciados diretamente por trabalhos de implantações em lote. Nesse exemplo, você primeiro carrega alguns dados no armazenamento de dados padrão do workspace do Azure Machine Learning e, a seguir, executa uma implantação em lote nele. Siga essas etapas para executar um trabalho de ponto de extremidade em lote usando os dados armazenados em um armazenamento de dados.

  1. Acesse o armazenamento de dados padrão do workspace do Azure Machine Learning. Se seus dados estiverem em um armazenamento diferente, use esse armazenamento. Você não precisa usar o armazenamento de dados padrão.

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

    Observação

    A ID dos armazenamentos de dados seria semelhante ao seguinte: /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

    Dica

    O armazenamento de dados de blob padrão em um workspace é chamado de workspaceblobstore. Você poderá ignorar esta etapa se já souber a ID do recurso do armazenamento de dados padrão em seu workspace.

  2. Você precisa carregar algumas amostras de dados no armazenamento de dados. Esse exemplo pressupõe que você já carregou as amostras de dados incluídas no repositório da pasta sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data na pasta heart-disease-uci-unlabeled da conta de armazenamento de blobs. Certifique-se de ter feito isso antes de seguir em frente.

  3. Crie a entrada ou a solicitação:

    Coloque o caminho do arquivo na seguinte variável:

    DATA_PATH="heart-disease-uci-unlabeled"
INPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Observação

    Veja como o caminho paths é acrescentado à ID do recurso do armazenamento de dados para indicar que o seguinte é um caminho dentro dele.

    Dica

    Você também pode usar azureml://datastores/<data-store>/paths/<data-path> como uma maneira de especificar a entrada.

  4. Execute o ponto de extremidade:

    Use o argumento --set para especificar a entrada:

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

    No caso de um ponto de extremidade usado para uma implantação de modelo, você pode usar o argumento --input para especificar a entrada de dados, já que 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 várias entradas são especificadas. Nesses casos, coloque suas entradas em um arquivo YAML e use --file para especificar as entradas necessárias para a invocação do seu ponto de extremidade.

    inputs.yml

    inputs:
  heart_dataset:
    type: uri_folder
    path: azureml://datastores/<data-store>/paths/<data-path>

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

    Se os dados forem um arquivo, use uri_file como tipo.

Inserir dados de contas do Armazenamento do Azure

Os pontos de extremidade em lote do Azure Machine Learning podem ler dados de locais de nuvem nas contas do Armazenamento do Azure, tanto pública quanto privada. Siga as etapas a seguir para executar um trabalho de ponto de extremidade em lote usando os dados armazenados em uma conta de armazenamento:

Observação

Verifique a seção configurar clusters de cálculo para acesso a dados para saber mais sobre a configuração adicional necessária para ler com êxito dados de contas de armazenamento.

  1. Crie a entrada ou a solicitação:

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

    Se seus dados são um arquivo:

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

  2. Execute o ponto de extremidade:

    Use o argumento --set para especificar a entrada:

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

    No caso de um ponto de extremidade usado para uma implantação de modelo, você pode usar o argumento --input para especificar a entrada de dados, já que 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 argumento --set tende a produzir comandos longos quando várias entradas são especificadas. Nesses casos, coloque suas entradas em um arquivo YAML e use --file para especificar as entradas necessárias para a invocação do seu ponto de extremidade.

    inputs.yml

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

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

    Se os dados forem um arquivo, use uri_file como tipo.

Criar trabalhos com entradas literais

As implantações de componente de pipeline podem aceitar entradas literais. 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 e use --file para especificar as entradas necessárias para a invocação do seu ponto de extremidade.

inputs.yml

inputs:
  score_mode:
    type: string
    default: append

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

Você também pode usar o argumento --set para especificar o valor. No entanto, ele tende a produzir comandos longos quando várias entradas são especificadas:

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 em que uma saída chamada score é colocada. Para integridade, esses exemplos também configuram uma entrada chamada heart_dataset.

  1. Use o armazenamento de dados padrão no espaço de trabalho do Azure Machine Learning para salvar as saídas. Você pode usar qualquer outro armazenamento de dados em seu espaço de trabalho, desde que seja uma conta de armazenamento de blobs.

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

    Observação

    A ID dos armazenamentos de dados seria semelhante ao seguinte: /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

  2. Criar uma saída de dados:

    DATA_PATH="batch-jobs/my-unique-path"
OUTPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Para que o processo fique completo, você também deve criar uma entrada de dados:

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

    Observação

    Veja como o caminho paths é acrescentado à ID do recurso do armazenamento de dados para indicar que o seguinte é um caminho dentro dele.

  3. Execute a implantação:

    Use o argumento --set para especificar a entrada:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.path=$INPUT_PATH \
    --set outputs.score.path=$OUTPUT_PATH

Próximas etapas