Como receber predições em lote

Quando não precisar das previsões imediatamente ou tiver um grande número de instâncias para recebê-las, use o serviço de previsão em lote. Nesta página, descrevemos como iniciar jobs de previsão em lote do AI Platform Prediction. O AI Platform Prediction é compatível apenas com previsões em lote de modelos do TensorFlow.

Veja uma comparação entre a previsão on-line e em lote ou leia a visão geral sobre os conceitos de previsão.

Antes de começar

Antes de solicitar previsões:

  • Crie um recurso de modelo e outro de versão ou coloque um SavedModel do TensorFlow em um local do Cloud Storage que o projeto possa acessar.

  • Configure um local do Cloud Storage que o projeto possa acessar para armazenar:

    • Arquivos de dados de entrada. Podem ser vários locais, e o projeto precisa ter autorização para fazer a leitura de cada um deles.

    • Arquivos de saída. Só pode ser especificado um caminho de saída, e o projeto precisa ter autorização para gravar dados nele.

  • Verifique se o arquivo de entrada está no formato correto para predição em lote.

Como configurar um job de predição em lote

Para iniciar o job de previsão em lote, você precisa coletar alguns dados de configuração. São os mesmos dados contidos no objeto PredictionInput utilizado por você ao chamar a API diretamente:

Formato de dados

O tipo de formato de entrada que você usa para os arquivos de entrada. Todos os arquivos de entrada para um determinado job têm que usar o mesmo formato de dados. Defina um destes valores:

JSON

Arquivos de entrada de texto simples com uma instância em cada linha. Este é o formato descrito na página de conceitos da previsão.

TF_RECORD

Arquivos no formato TFRecord do TensorFlow.

TF_RECORD_GZIP

Arquivos TFRecord compactados com GZIP.

Caminhos de entrada

Os URIs dos arquivos de dados de entrada, que precisam estar em locais do Cloud Storage. Veja o que é possível especificar:

  • Caminhos para arquivos específicos: 'gs://path/to/my/input/file.json'.

  • Caminhos para diretórios com um único caractere curinga de asterisco para indicar todos os arquivos nesses diretórios: 'gs://path/to/my/input/*'.

  • Caminhos para nomes de arquivo parciais com um único caractere curinga de asterisco no final para indicar todos os arquivos que começam com a sequência fornecida: 'gs://path/to/my/input/file*'.

Combine vários URIs. No Python, você cria uma lista deles. Se você usa Google Cloud CLI ou chama a API diretamente, é possível listar vários URIs separados por vírgulas, mas sem espaço entre eles. Este é o formato correto da sinalização --input-paths:

 --input-paths gs://a/directory/of/files/*,gs://a/single/specific/file.json,gs://a/file/template/data*
Caminho de saída

O caminho para o local do Cloud Storage em que você quer que o serviço de predição salve os resultados. O projeto precisa ter permissões para gravar nesse local.

Nome de modelo e nome de versão

O nome do modelo e, opcionalmente, a versão da qual você quer receber as previsões. Se você não especificar uma versão, será usada a padrão do modelo. Na previsão em lote, a versão precisa ter o tipo de máquina mls1-c1-m2.

Se você fornecer um URI do modelo (consulte a seção a seguir), omita esses campos.

URI do modelo

É possível fazer previsões de um modelo que não esteja implantado no AI Platform Prediction especificando o URI do SavedModel que você quer usar. O SavedModel precisa estar armazenado no Cloud Storage.

Para resumir, você tem três opções para especificar o modelo a ser usado para a predição em lote. Você pode usar:

  • o próprio nome de modelo para a versão padrão de modelo;

  • os nomes de versão e de modelo para uma determinada versão de modelo;

  • o URI do modelo para usar um SavedModel que esteja no Cloud Storage, mas não implantado no AI Platform Prediction.

Região

A região do Google Compute Engine em que você pretende executar o job. Para atingir o melhor desempenho, é preciso executar o job de previsão e armazenar os dados de entrada e saída na mesma região, especialmente para conjuntos de dados muito grandes. A previsão em lote do AI Platform Prediction está disponível nas seguintes regiões:

  -   us-central1
  -   us-east1
  -   europe-west1
  -   asia-east1

Para entender completamente as regiões disponíveis aos serviços do AI Platform Prediction, incluindo treinamento de modelo e previsão on-line, leia o guia de regiões.

Nome do job

Um nome para o job, que precisa:

  • conter apenas letras maiúsculas e minúsculas misturadas, dígitos e sublinhados;
  • começar com uma letra;
  • conter no máximo 128 caracteres;
  • ser único entre todos os nomes de job de treinamento e de predição em lote já utilizados no projeto. Isso inclui todos os jobs criados no projeto, independentemente do sucesso ou do status deles.
Tamanho do lote (opcional)

O número de registros por lote. O serviço armazenará em buffer o número de registros batch_size na memória antes de invocar o modelo. Se não for especificado, o padrão 64 será usado.

Rótulos (opcional)

É possível adicionar rótulos ao job para organizá-los e classificá-los em categorias ao visualizar ou monitorar recursos. Por exemplo, você pode classificar jobs por equipe (adicionando rótulos como engineering ou research) ou por fase de desenvolvimento (prod ou test). Para adicionar rótulos ao job de previsão, forneça uma lista de pares KEY=VALUE.

Contagem máxima de worker (opcional)

O número máximo de nodes de previsão a serem usados no cluster de processamento para este job. Esta é uma maneira de colocar um limite superior no recurso de escalonamento automático da previsão em lote. Se você não especificar um valor, ele será definido por padrão como 10. Independentemente do valor especificado, o escalonamento é limitado pela cota do node de previsão.

Versão de tempo de execução (opcional)

A versão do AI Platform Prediction que será usada com o job. Essa opção é incluída para especificar uma versão de ambiente de execução que será usada com modelos não implantados no AI Platform Prediction. Sempre omita esse valor para versões de modelo implantadas. Com isso, o serviço será instruído a usar a mesma versão que foi especificada durante a implantação da versão de modelo.

Nome da assinatura (opcional)

Se o modelo salvo tiver várias assinaturas, use esta opção para especificar um nome de assinatura TensorFlow personalizado, que permite selecionar um mapa de entrada/saída alternativo definido no TensorFlow SavedModel. Consulte a documentação do TensorFlow SavedModel se quiser ver o guia para usar assinaturas e especificar as saídas de um modelo personalizado (páginas em inglês). O padrão é DEFAULT_SERVING_SIGNATURE_DEF_KEY, que tem o valor serving_default.

Os exemplos a seguir definem variáveis para armazenar dados de configuração.

gcloud

Não é necessário criar variáveis ao usar a ferramenta de linha de comando gcloud para iniciar um job. No entanto, isso facilita muito a inserção e a leitura do comando de envio de jobs.

DATA_FORMAT="text" # JSON data format
INPUT_PATHS='gs://path/to/your/input/data/*'
OUTPUT_PATH='gs://your/desired/output/location'
MODEL_NAME='census'
VERSION_NAME='v1'
REGION='us-east1'
now=$(date +"%Y%m%d_%H%M%S")
JOB_NAME="census_batch_predict_$now"
MAX_WORKER_COUNT="20"
BATCH_SIZE="32"
LABELS="team=engineering,phase=test,owner=sara"

Python

Com a biblioteca de cliente das APIs do Google para Python, é possível usar dicionários nessa linguagem para representar os recursos de Job e PredictionInput.

  1. Formate os nomes do projeto, do modelo ou da versão com a sintaxe usada pelas APIs REST AI Platform Prediction:

    • project_name -> 'projects/project_name'
    • model_name -> 'projects/project_name/models/model_name'
    • version_name -> 'projects/project_name/models/model_name/versions/version_name'

  2. Crie um dicionário para o recurso Job e preencha-o com dois itens:

    • Uma chave chamada 'jobId' com o nome do job que você quer usar como valor.

    • Uma chave denominada 'predictionInput' que contém outro objeto de dicionário que acomode todos os membros necessários do PredictionInput e qualquer membro opcional que você queira usar.

    O exemplo a seguir mostra uma função que recebe as informações de configuração como variáveis de entrada e retorna o corpo da solicitação de previsão. Além dos conceitos básicos, o exemplo também gera um identificador de job exclusivo com base no nome do projeto, no nome do modelo e na hora atual.

    import time
import re

def make_batch_job_body(project_name, input_paths, output_path,
        model_name, region, data_format='JSON',
        version_name=None, max_worker_count=None,
        runtime_version=None):

    project_id = 'projects/{}'.format(project_name)
    model_id = '{}/models/{}'.format(project_id, model_name)
    if version_name:
        version_id = '{}/versions/{}'.format(model_id, version_name)

    # Make a jobName of the format "model_name_batch_predict_YYYYMMDD_HHMMSS"
    timestamp = time.strftime('%Y%m%d_%H%M%S', time.gmtime())

    # Make sure the project name is formatted correctly to work as the basis
    # of a valid job name.
    clean_project_name = re.sub(r'\W+', '_', project_name)

    job_id = '{}_{}_{}'.format(clean_project_name, model_name,
                           timestamp)

    # Start building the request dictionary with required information.
    body = {'jobId': job_id,
            'predictionInput': {
                'dataFormat': data_format,
                'inputPaths': input_paths,
                'outputPath': output_path,
                'region': region}}

    # Use the version if present, the model (its default version) if not.
    if version_name:
        body['predictionInput']['versionName'] = version_id
    else:
        body['predictionInput']['modelName'] = model_id

    # Only include a maximum number of workers or a runtime version if specified.
    # Otherwise let the service use its defaults.
    if max_worker_count:
        body['predictionInput']['maxWorkerCount'] = max_worker_count

    if runtime_version:
        body['predictionInput']['runtimeVersion'] = runtime_version

    return body

Como enviar um job de predição em lote

Para enviar o job, basta fazer uma chamada simplesprojects.jobs.create ou para a ferramenta de linha de comando correspondente gcloud ai-platform jobs submit prediction.

gcloud

O exemplo a seguir usa as variáveis definidas na seção anterior para iniciar a predição em lote.

gcloud ai-platform jobs submit prediction $JOB_NAME \
    --model $MODEL_NAME \
    --input-paths $INPUT_PATHS \
    --output-path $OUTPUT_PATH \
    --region $REGION \
    --data-format $DATA_FORMAT

Python

Os procedimentos para iniciar um job de predição em lote com a biblioteca de cliente das APIs do Google para Python seguem um padrão semelhante ao SDK de outros clientes:

  1. Prepare o corpo da solicitação a ser usada na chamada conforme mostrado na seção anterior.

  2. Formule a solicitação chamando ml.projects.jobs.create.

  3. Chame a execução na solicitação para receber uma resposta e verifique se há erros HTTP.

  4. Use a resposta como um dicionário para ver os valores do recurso Job.

Use a biblioteca de cliente de APIs do Google para Python para chamar a API AI Platform Training and Prediction sem gerar solicitações HTTP manualmente. Antes de executar o código de exemplo a seguir, é preciso configurar a autenticação.

    import googleapiclient.discovery as discovery

    project_id = 'projects/{}'.format(project_name)

    ml = discovery.build('ml', 'v1')
    request = ml.projects().jobs().create(parent=project_id,
                                          body=batch_predict_body)

    try:
        response = request.execute()

        print('Job requested.')

        # The state returned will almost always be QUEUED.
        print('state : {}'.format(response['state']))

    except errors.HttpError as err:
        # Something went wrong, print out some information.
        print('There was an error getting the prediction results.' +
              'Check the details:')
        print(err._get_reason())

Como monitorar o job de predição em lote

Um job de previsão em lote pode demorar muito para terminar. É possível monitorar o andamento do job no Console do Google Cloud:

  1. Acesse a página "Jobs" do AI Platform Prediction no Console do Google Cloud:

    Acessar a página "Jobs" do console do Google Cloud

  2. Clique no nome do seu job na lista ID do job. Isso abre a página Detalhes do job.

  3. O status atual é exibido com o nome do job no topo da página.

  4. Caso queira mais detalhes, clique em Ver registros para visualizar a entrada do seu job no Cloud Logging.

Há outras maneiras de acompanhar o andamento do job de previsão em lote. Elas seguem os mesmos padrões do monitoramento de jobs de treinamento. Você encontrará mais informações na página que descreve como monitorar os jobs de treinamento. Para trabalhar com jobs de previsão, talvez seja preciso ajustar ligeiramente as instruções fornecidas na página, mas os mecanismos são os mesmos.

Como conseguir resultados de predição

O serviço grava predições no local do Cloud Storage especificado. Há dois tipos de saída de arquivos que podem apresentar resultados interessantes:

  • Os arquivos denominados prediction.errors_stats-NNNNN-of-NNNNN contêm informações sobre problemas ocorridos durante a execução do job.

  • Os arquivos de linhas de JSON denominados prediction.results-NNNNN-of-NNNNN contêm as próprias previsões, conforme definido pela saída do modelo.

Os nomes de arquivo incluem números de índice (mostrados acima como 'N' para cada dígito) que capturam o total de arquivos que devem ser encontrados. Por exemplo, um job que tenha seis arquivos de resultados inclui prediction.results-00000-of-00006 até prediction.results-00005-of-00006.

Todas as linhas de cada arquivo de previsão são um objeto JSON que representa um único resultado de previsão. É possível abrir os documentos de previsão com o editor de texto de sua preferência. Para dar uma rápida olhada na linha de comando, use gsutil cat:

gsutil cat $OUTPUT_PATH/prediction.results-NNNNN-of-NNNNN|less

Lembre-se de que os resultados de previsão normalmente não são emitidos na mesma ordem das instâncias de entrada, ainda que você utilize um único arquivo de entrada. Para encontrar a previsão de uma instância, combine as chaves de instância.

Próximas etapas