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

  • Artigo

Os pontos de extremidade em lote podem ser usados para executar operações de lote longas em grandes quantidades de dados. Esses dados podem ser colocados em diferentes locais. 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 suportados.

Antes de invocar um ponto de extremidade

Para invocar com êxito um ponto de extremidade em lote e criar trabalhos, certifique-se de ter 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 obter definições de funções personalizadas, leia Autorização em pontos de extremidade em lote para saber as permissões específicas necessárias.

  • Você tem um token de ID do Microsoft Entra válido representando 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. Em qualquer caso, depois que um ponto de extremidade é invocado, um trabalho de implantação em lote é criado sob a identidade associada ao token. Para fins de teste, você pode usar suas próprias credenciais para a invocação, conforme mencionado abaixo.

    Use a CLI do Azure para entrar usando autenticação interativa ou de 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 lote.

  • O cluster de computação onde o ponto de extremidade é implantado tem acesso para ler os dados de entrada.

    Gorjeta

    Se você estiver usando um armazenamento de dados sem credenciais ou uma Conta de Armazenamento do Azure externa como entrada de dados, certifique-se de configurar clusters de computação para acesso a dados. A identidade gerenciada do cluster de computação é usada para montar a conta de armazenamento. A identidade do trabalho (invocador) ainda é usada para ler os dados subjacentes, permitindo que você obtenha controle de acesso granular.

Criar noções básicas de empregos

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 de API REST. Os exemplos a seguir mostram os conceitos básicos de invocação para um ponto de extremidade em lote que recebe uma única pasta de dados de entrada para processamento. Consulte Noções básicas sobre entradas e saídas para obter exemplos com diferentes 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 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.

Nota

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

Configurar 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 mostrando como as entradas e saídas são usadas em pontos finais de lote.

Os pontos de extremidade em lote suportam 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 exigem uma entrada de dados e produzem uma saída de dados. Não há suporte para entradas literais. No entanto, as implantações de componentes de pipeline fornecem uma construção mais geral para criar pontos de extremidade e permitem especificar qualquer número de entradas (dados e 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 entrada Tipos de entrada suportados Número da saída 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. Esses nomes servem como chaves para identificá-los e passar o valor real durante a invocação. Para implantações de modelo, como elas sempre exigem uma entrada e uma saída, o nome é ignorado durante a invocação. Você pode atribuir o nome que melhor descreve seu caso de uso, como "sales_estimation".

Introdução 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 onde 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 em lote suportam a 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 Azure Data Lake Storage Gen1, Azure Data Lake Storage Gen2 e Azure Blob Storage.
  • Pastas/arquivos de dados locais (CLI do Azure Machine Learning ou SDK do Azure Machine Learning para Python). No entanto, essa operação resulta nos dados locais a serem carregados no Repositório de Dados do Azure Machine Learning padrão do espaço de trabalho em que você está trabalhando.

Importante

Aviso de descontinuação: os conjuntos de dados do tipo FileDataset (V1) foram preteridos e serão desativados no futuro. Os pontos de extremidade de lote existentes que dependem dessa funcionalidade continuarão a funcionar, mas os pontos de extremidade em lote criados com GA CLIv2 (2.4.0 e mais recente) ou GA REST API (2022-05-01 e mais recente) não suportarão o conjunto de dados 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 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. Consulte Criar trabalhos com entradas literais para saber como especificá-los.

Saídas de dados

As saídas de dados referem-se ao local onde 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 a cada saída nomeada. No entanto, você pode especificar outro caminho, se necessário.

Importante

Os pontos de extremidade em lote dão suporte apenas à gravação de saídas em armazenamentos de dados do Armazenamento de Blob do Azure. Se você precisar gravar em uma conta de armazenamento com namespaces hierárquicos habilitados (também conhecido 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, pois os serviços são totalmente compatíveis. Dessa forma, você pode gravar saídas de pontos de extremidade em lote para o 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.

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 usando dados 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. Primeiro, crie o ativo de dados. Esse ativo de dados consiste em uma pasta com vários arquivos CSV que você processará em paralelo, usando pontos de extremidade em lote. Você pode pular esta 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 solicitação:

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

    Nota

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

  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_dataset.type="uri_folder" inputs.heart_dataset.path=$DATASET_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, 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 YAML arquivo e use --file para especificar as entradas necessárias para sua chamada de ponto final.

    inputs.yml

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

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

Dados de entrada de armazenamentos de dados

Os dados dos armazenamentos de dados registrados do Azure Machine Learning podem ser referenciados diretamente por trabalhos de implantações em lote. Neste exemplo, você primeiro carrega alguns dados no armazenamento de dados padrão no espaço de trabalho do Aprendizado de Máquina do Azure e, em seguida, executa uma implantação em lote nele. Siga estas etapas para executar um trabalho de ponto de extremidade em lote usando dados armazenados em um armazenamento de dados.

  1. Acesse o armazenamento de dados padrão no espaço de trabalho do Azure Machine Learning. Se seus dados estiverem em um armazenamento diferente, você poderá usá-lo. Não é necessário usar o armazenamento de dados padrão.

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

    Nota

    O ID dos armazenamentos de dados seria parecido com /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>o .

    Gorjeta

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

  2. Você precisa carregar alguns dados de exemplo para o armazenamento de dados. Este exemplo pressupõe que você já carregou os dados de exemplo incluídos no repositório na pasta sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data na conta heart-disease-uci-unlabeled de armazenamento de blob. Certifique-se de ter feito isso antes de seguir em frente.

  3. Crie a entrada ou solicitação:

    Coloque o caminho do arquivo na seguinte variável:

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

    Nota

    Veja como o caminho paths é anexado à id do recurso do armazenamento de dados para indicar que o que se segue é um caminho dentro dele.

    Gorjeta

    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 --set argumento 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

    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, 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 YAML arquivo e use --file para especificar as entradas necessárias para sua chamada de ponto final.

    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.

Dados de entrada das Contas de Armazenamento do Azure

Os pontos de extremidade em lote do Azure Machine Learning podem ler dados de locais de nuvem nas Contas de Armazenamento do Azure, tanto públicas quanto privadas. Use as seguintes etapas para executar um trabalho de ponto de extremidade em lote usando dados armazenados em uma conta de armazenamento:

Nota

Consulte a seção Configurar clusters de computação para acesso a dados para saber mais sobre a configuração adicional necessária para ler com êxito os dados dos acessos de armazenamento.

  1. Crie a entrada ou solicitação:

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

    Se os seus dados forem um ficheiro:

    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_dataset.type="uri_folder" inputs.heart_dataset.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, 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 YAML arquivo e use --file para especificar as entradas necessárias para sua chamada de ponto final.

    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.

Crie trabalhos com entradas literais

As implantações de componentes de pipeline podem ter 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 YAML arquivo e use --file para especificar as entradas necessárias para sua chamada de 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 onde uma saída nomeada score é colocada. Para completar, 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 blob.

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

    Nota

    O ID dos armazenamentos de dados seria parecido com /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>o .

  2. Crie uma saída de dados:

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

    Para completar, crie também uma entrada de dados:

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

    Nota

    Veja como o caminho paths é anexado à id do recurso do armazenamento de dados para indicar que o que se segue é 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óximos passos