Prepare o código de preparação

Realize preparação personalizada no Vertex AI para executar o seu próprio código de preparação de aprendizagem automática (ML) na nuvem, em vez de usar o AutoML. Este documento descreve as práticas recomendadas a considerar à medida que escreve código de preparação.

Escolha uma estrutura de código de preparação

Primeiro, determine a estrutura que quer que o seu código de preparação de ML tenha. Pode fornecer código de preparação ao Vertex AI de uma das seguintes formas:

  • Um script Python para usar com um contentor pré-criado. Use o SDK Vertex AI para criar uma tarefa personalizada. Este método permite-lhe fornecer a sua aplicação de preparação como um único script Python.

  • Uma aplicação de preparação Python para usar com um contentor pré-criado. Crie uma distribuição de origem Python com código que prepara um modelo de ML e o exporta para o Cloud Storage. Esta aplicação de preparação pode usar qualquer uma das dependências incluídas no contentor pré-criado com o qual planeia usá-la.

    Use esta opção se um dos contentores pré-criados do Vertex AI para preparação incluir todas as dependências de que precisa para a preparação. Por exemplo, se quiser fazer a preparação com o PyTorch, o scikit-learn, o TensorFlow ou o XGBoost, esta é provavelmente a melhor opção.

    Para saber mais sobre as práticas recomendadas específicas desta opção, leia o guia sobre como criar uma aplicação de preparação em Python.

  • Uma imagem de contentor personalizada. Crie uma imagem do contentor Docker com código que treina um modelo de ML e o exporta para o Cloud Storage. Inclua todas as dependências exigidas pelo seu código na imagem do contentor.

    Use esta opção se quiser usar dependências que não estejam incluídas num dos contentores pré-criados do Vertex AI para preparação. Por exemplo, se quiser preparar o modelo através da framework Python ML, que não está disponível num contentor pré-criado, ou se quiser preparar o modelo através de uma linguagem de programação que não Python, esta é a melhor opção.

    Para saber mais sobre as práticas recomendadas específicas desta opção, leia o guia sobre como criar uma imagem de contentor personalizada.

O resto deste documento descreve as práticas recomendadas relevantes para as estruturas de código de preparação.

Práticas recomendadas para todo o código de preparação personalizado

Quando escreve código de preparação personalizado para o Vertex AI, tenha em atenção que o código é executado numa ou mais instâncias de máquinas virtuais (VMs) geridas peloGoogle Cloud. Esta secção descreve as práticas recomendadas aplicáveis a todo o código de programação personalizado.

Aceda Google Cloud aos serviços no seu código

Várias das secções seguintes descrevem o acesso a outros Google Cloud serviços a partir do seu código. Para aceder aos Google Cloud serviços, escreva o seu código de preparação para usar as Credenciais padrão da aplicação (ADC). Muitas Google Cloud bibliotecas de cliente autenticam-se com o ADC por predefinição. Não precisa de configurar nenhuma variável de ambiente. O Vertex AI configura automaticamente o ADC para autenticar como o agente do serviço de código personalizado do Vertex AI para o seu projeto (por predefinição) ou uma conta de serviço personalizada (se tiver configurado uma).

No entanto, quando usa uma Google Cloud biblioteca de cliente no seu código, o Vertex AI pode nem sempre estabelecer ligação ao Google Cloud projeto correto por predefinição. Se encontrar erros de autorização, o problema pode estar relacionado com a ligação ao projeto errado.

Este problema ocorre porque o Vertex AI não executa o seu código diretamente no seu Google Cloud projeto. Em alternativa, o Vertex AI executa o seu código num de vários projetos separados geridos pela Google. A Vertex AI usa estes projetos exclusivamente para operações relacionadas com o seu projeto. Por conseguinte, não tente inferir um ID do projeto a partir do ambiente no código de preparação ou inferência. Especifique os IDs dos projetos explicitamente.

Se não quiser codificar um ID do projeto no seu código de preparação, pode fazer referência à variável de ambiente CLOUD_ML_PROJECT_ID: o Vertex AI define esta variável de ambiente em todos os contentores de preparação personalizados para conter o número do projeto do projeto onde iniciou a preparação personalizada. Muitas Google Cloud ferramentas podem aceitar um número do projeto onde quer que aceitem um ID do projeto.

Por exemplo, se quiser usar o cliente Python para o Google BigQuery para aceder a uma tabela do BigQuery no mesmo projeto, não tente inferir o projeto no seu código de preparação:

Seleção implícita de projetos

from google.cloud import bigquery

client = bigquery.Client()

Em alternativa, use código que selecione explicitamente um projeto:

Seleção explícita de projetos

import os

from google.cloud import bigquery

project_number = os.environ["CLOUD_ML_PROJECT_ID"]

client = bigquery.Client(project=project_number)

Se encontrar erros de autorização depois de configurar o código desta forma, consulte a secção seguinte sobre a que recursos o seu código pode aceder para ajustar as autorizações disponíveis para o seu código de preparação.

Aos recursos aos quais o seu código pode aceder

Por predefinição, a sua aplicação de preparação pode aceder a quaisquer Google Cloud recursos que estejam disponíveis para o agente do serviço de código personalizado (CCSA) do Vertex AI do seu projeto. Pode conceder à CCSA e, consequentemente, à sua aplicação de preparação, acesso a um número limitado de outros recursos seguindo as instruções em Conceda aos agentes de serviço do Vertex AI acesso a outros recursos. Se a sua aplicação de preparação precisar de mais do que acesso ao nível de leitura aos Google Cloud recursos que não estão listados nessa página, tem de adquirir um token de acesso OAuth 2.0 com o âmbito https://www.googleapis.com/auth/cloud-platform, o que só pode ser feito através de uma conta de serviço personalizada.

Por exemplo, considere o acesso do código de preparação aos recursos do Cloud Storage:

Por predefinição, o Vertex AI pode aceder a qualquer contentor do Cloud Storage no Google Cloud projeto onde está a realizar a preparação personalizada. Também pode conceder acesso do Vertex AI a contentores do Cloud Storage noutros projetos ou pode personalizar com precisão os contentores aos quais uma tarefa específica pode aceder usando uma conta de serviço personalizada.

Ler e escrever ficheiros do Cloud Storage com o Cloud Storage FUSE

Em todas as tarefas de preparação personalizadas, o Vertex AI monta contentores do Cloud Storage aos quais tem acesso no diretório /gcs/ do sistema de ficheiros de cada nó de preparação. Como alternativa conveniente à utilização do cliente Python para o Cloud Storage ou outra biblioteca para aceder ao Cloud Storage, pode ler e escrever diretamente no sistema de ficheiros local para ler dados do Cloud Storage ou escrever dados no Cloud Storage. Por exemplo, para carregar dados do gs://BUCKET/data.csv, pode usar o seguinte código Python:

file = open('/gcs/BUCKET/data.csv', 'r')

O Vertex AI usa o Cloud Storage FUSE para montar os contentores de armazenamento. Tenha em atenção que os diretórios montados pelo FUSE do Cloud Storage não são compatíveis com POSIX.

As credenciais que está a usar para a preparação personalizada determinam os contentores aos quais pode aceder desta forma. A secção anterior sobre a que recursos o seu código pode aceder descreve exatamente a que contentores pode aceder por predefinição e como personalizar este acesso.

Carregue dados de entrada

Normalmente, o código de ML opera em dados de preparação para preparar um modelo. Não armazene dados de preparação juntamente com o seu código, quer crie uma aplicação de preparação em Python ou uma imagem de contentor personalizada. O armazenamento de dados com código pode originar um projeto mal organizado, dificultar a reutilização de código em diferentes conjuntos de dados e causar erros em conjuntos de dados grandes.

Pode carregar dados de um conjunto de dados gerido do Vertex AI ou escrever o seu próprio código para carregar dados de uma origem fora do Vertex AI, como o BigQuery ou o Cloud Storage.

Para um melhor desempenho quando carrega dados do Cloud Storage, use um contentor na região onde está a fazer a preparação personalizada. Para saber como armazenar dados no Cloud Storage, leia os artigos Criar contentores de armazenamento e Carregar objetos.

Para saber de que contentores do Cloud Storage pode carregar dados, leia a secção anterior sobre a que recursos o seu código pode aceder.

Para carregar dados do Cloud Storage no seu código de preparação, use a funcionalidade FUSE do Cloud Storage descrita na secção anterior ou use qualquer biblioteca que suporte a ADC. Não tem de fornecer explicitamente credenciais de autenticação no seu código.

Por exemplo, pode usar uma das bibliotecas cliente demonstradas no guia do Cloud Storage para transferir objetos. O cliente Python para o Cloud Storage, em particular, está incluído em contentores pré-criados. A classe tf.io.gfile.GFile do TensorFlow também suporta ADC.

Carregue um conjunto de dados grande

Consoante os tipos de máquinas que planeia usar durante a preparação personalizada, as suas VMs podem não conseguir carregar a totalidade de um conjunto de dados grande na memória.

Se precisar de ler dados demasiado grandes para caberem na memória, transmita os dados ou leia-os de forma incremental. As diferentes estruturas de AA têm práticas recomendadas diferentes para o fazer. Por exemplo, a classe tf.data.Dataset do TensorFlow pode transmitir dados TFRecord ou de texto a partir do Cloud Storage.

A realização de formação personalizada em várias VMs com paralelismo de dados é outra forma de reduzir a quantidade de dados que cada VM carrega na memória. Consulte a secção Escrever código para preparação distribuída deste documento.

Exporte um modelo de ML preparado

Normalmente, o código de AA exporta um modelo preparado no final da preparação sob a forma de um ou mais artefactos do modelo. Em seguida, pode usar os artefactos do modelo para obter inferências.

Após a conclusão do treino personalizado, já não pode aceder às VMs que executaram o seu código de treino. Por conseguinte, o seu código de preparação tem de exportar os artefactos do modelo para uma localização fora do Vertex AI.

Recomendamos que exporte os artefactos do modelo para um contentor do Cloud Storage. Conforme descrito na secção anterior sobre a que recursos o seu código pode aceder, o Vertex AI pode aceder a qualquer contentor do Cloud Storage no Google Cloud projeto onde está a realizar o treino personalizado. Use uma biblioteca que suporte a ADC para exportar os artefactos do modelo. Por exemplo, as APIs TensorFlow para guardar modelos Keras podem exportar artefactos diretamente para um caminho do Cloud Storage.

Se quiser usar o seu modelo preparado para apresentar inferências no Vertex AI, o seu código tem de exportar artefactos do modelo num formato compatível com um dos contentores pré-criados para inferência. Saiba mais no guia de exportação de artefactos de modelos para inferência e explicação.

Variáveis de ambiente para diretórios especiais do Cloud Storage

Se especificar o campo baseOutputDirectory da API, o Vertex AI define as seguintes variáveis de ambiente quando executa o código de preparação:

Os valores destas variáveis de ambiente diferem ligeiramente consoante esteja a usar a otimização de hiperparâmetros. Para saber mais, consulte a referência da API para baseOutputDirectory.

A utilização destas variáveis de ambiente facilita a reutilização do mesmo código de preparação várias vezes, por exemplo, com diferentes dados ou opções de configuração, e guardar artefactos e pontos de verificação do modelo em localizações diferentes, apenas alterando o campo da API baseOutputDirectory. No entanto, não tem de usar as variáveis de ambiente no seu código se não quiser. Por exemplo, pode codificar de forma alternativa localizações para guardar pontos de verificação e exportar artefactos do modelo.

Além disso, se usar um TrainingPipeline para a preparação personalizada e não especificar o campo modelToUpload.artifactUri, o Vertex AI usa o valor da variável de ambiente AIP_MODEL_DIR para modelToUpload.artifactUri. (Para o ajuste de hiperparâmetros, a Vertex AI usa o valor da variável de ambiente AIP_MODEL_DIR da melhor tentativa.)

Assegure a resiliência aos reinícios

As VMs que executam o seu código de preparação são reiniciadas ocasionalmente. Por exemplo, o Google Compute Engine pode ter de reiniciar uma VM por motivos de manutenção.Google Cloud Quando uma VM é reiniciada, o Vertex AI volta a executar o seu código desde o início.

Se prevê que o seu código de preparação seja executado durante mais de quatro horas, adicione vários comportamentos ao código para o tornar resiliente a reinícios:

  • Exporte frequentemente o seu progresso de preparação para o Cloud Storage, pelo menos, uma vez a cada quatro horas, para não perder o progresso se as suas VMs forem reiniciadas.

  • No início do código de preparação, verifique se já existe algum progresso de preparação na localização de exportação. Se for o caso, carregue o estado de preparação guardado em vez de começar a preparação do zero.

Quatro horas é uma diretriz e não um limite rígido. Se garantir a resiliência for uma prioridade, considere adicionar estes comportamentos ao seu código, mesmo que não espere que seja executado durante tanto tempo.

A forma de alcançar estes comportamentos depende da estrutura de ML que usa. Por exemplo, se usar o TensorFlow Keras, saiba como usar o ModelCheckpoint callback para este fim.

Para saber como a Vertex AI gere as VMs, consulte o artigo Compreenda o serviço de preparação personalizada.

Práticas recomendadas para funcionalidades de preparação personalizada opcionais

Se quiser usar determinadas funcionalidades de preparação personalizada opcionais, pode ter de fazer alterações adicionais ao código de preparação. Esta secção descreve as práticas recomendadas de código para o ajuste de hiperparâmetros, as GPUs, a preparação distribuída e o Vertex AI TensorBoard.

Escreva código para ativar o registo automático

Pode ativar o registo automático através do SDK Vertex AI para Python para capturar automaticamente parâmetros e métricas de desempenho quando enviar a tarefa personalizada. Para ver detalhes, consulte o artigo Execute uma tarefa de preparação com o acompanhamento de experiências.

Escreva código para devolver registos de contentores

Quando escreve registos a partir do seu serviço ou tarefa, estes são recolhidos automaticamente pelo Cloud Logging, desde que sejam escritos em qualquer uma destas localizações:

Espera-se que a maioria dos programadores escreva registos usando a saída padrão e o erro padrão.

Os registos de contentores escritos nestas localizações suportadas são automaticamente associados ao serviço de preparação personalizada, à revisão e à localização do Vertex AI, ou à tarefa de preparação personalizada. As exceções contidas nestes registos são capturadas e comunicadas em Relatórios de erros.

Use texto simples em vez de JSON estruturado nos registos

Quando escreve registos, pode enviar uma string de texto simples ou uma única linha de JSON serializado, também denominada dados "estruturados". Esta informação é recolhida e analisada pelo Cloud Logging e é colocada em jsonPayload. Por outro lado, a mensagem de texto simples é colocada em textPayload.

Escreva registos estruturados

Pode transmitir registos JSON estruturados de várias formas. As formas mais comuns são através da biblioteca de registo do Python ou da transmissão de JSON não processado através de print.

Biblioteca de registo Python

import json
import logging
from pythonjsonlogger import jsonlogger


class CustomJsonFormatter(jsonlogger.JsonFormatter):
 """Formats log lines in JSON."""
  def process_log_record(self, log_record):
    """Modifies fields in the log_record to match Cloud Logging's expectations."""
    log_record['severity'] = log_record['levelname']
    log_record['timestampSeconds'] = int(log_record['created'])
    log_record['timestampNanos'] = int(
        (log_record['created'] % 1) * 1000 * 1000 * 1000)


    return log_record




def configure_logger():
  """Configures python logger to format logs as JSON."""
  formatter = CustomJsonFormatter(
        '%(name)s|%(levelname)s|%(message)s|%(created)f'
        '|%(lineno)d|%(pathname)s', '%Y-%m-%dT%H:%M:%S')
  root_logger = logging.getLogger()
  handler = logging.StreamHandler()
  handler.setFormatter(formatter)
  root_logger.addHandler(handler)
  root_logger.setLevel(logging.WARNING)


logging.warning("This is a warning log")

JSON não processado

import json


def log(severity, message):
  global_extras = {"debug_key": "debug_value"}
  structured_log = {"severity": severity, "message": message, **global_extras}
  print(json.dumps(structured_log))


def main(args):
  log("DEBUG", "Debugging the application.")
  log("INFO", "Info.")
  log("WARNING", "Warning.")
  log("ERROR", "Error.")
  log("CRITICAL", "Critical.")

Campos JSON especiais em mensagens

Quando fornece um registo estruturado como um dicionário JSON, alguns campos especiais são removidos do jsonPayload e são escritos no campo correspondente no LogEntry gerado, conforme descrito na documentação para campos especiais.

Por exemplo, se o seu JSON incluir uma propriedade severity, esta é removida do jsonPayload e aparece, em alternativa, como o severity da entrada do registo. A propriedade message é usada como o texto de apresentação principal da entrada do registo, se estiver presente.

Correlacione os registos do contentor com um registo de pedidos (apenas para serviços)

No Explorador de registos, os registos correlacionados pelo mesmo trace são visíveis no formato "principal-secundário": quando clica no ícone de triângulo à esquerda da entrada do registo de pedidos, os registos do contentor relacionados com esse pedido são apresentados aninhados no registo de pedidos.

Os registos de contentores não são correlacionados automaticamente com os registos de pedidos, a menos que use uma biblioteca de cliente do Cloud Logging. Para correlacionar os registos do contentor com os registos de pedidos sem usar uma biblioteca de cliente, pode usar uma linha de registo JSON estruturada que contenha um campo logging.googleapis.com/trace com o identificador de rastreio extraído do cabeçalho X-Cloud-Trace-Context.

Ver registos

Para ver os registos do contentor na Google Cloud consola, faça o seguinte:

  1. Na Google Cloud consola, aceda à página Tarefas personalizadas do Vertex AI.

    Aceda a Tarefas personalizadas

  2. Clique no nome da tarefa personalizada cujos registos quer ver.

  3. Clique em Ver registos.

Escreva código para o aperfeiçoamento de hiperparâmetros

O Vertex AI pode realizar o ajuste de hiperparâmetros no seu código de preparação de ML. Saiba como funciona a otimização de hiperparâmetros na Vertex AI e como configurar um recurso HyperparameterTuningJob.

Se quiser usar a otimização de hiperparâmetros, o código de preparação tem de fazer o seguinte:

  • Analise os argumentos da linha de comandos que representam os hiperparâmetros que quer ajustar e use os valores analisados para definir os hiperparâmetros para a preparação.

  • Comunique intermitentemente a métrica de aperfeiçoamento de hiperparâmetros ao Vertex AI.

Analise argumentos da linha de comandos

Para o ajuste de hiperparâmetros, o Vertex AI executa o seu código de preparação várias vezes, com diferentes argumentos da linha de comandos em cada execução. O código de treino tem de analisar estes argumentos de linha de comandos e usá-los como hiperparâmetros para o treino. Por exemplo, para ajustar a taxa de aprendizagem> do otimizador, pode querer analisar um argumento da linha de comandos denominado --learning_rate. Saiba como configurar os argumentos da linha de comandos que o Vertex AI fornece.

Recomendamos que use a argparsebiblioteca do Python para analisar argumentos da linha de comandos.

Comunique a métrica de aperfeiçoamento de hiperparâmetros

O seu código de preparação tem de comunicar intermitentemente a métrica de hiperparâmetros que está a tentar otimizar para o Vertex AI. Por exemplo, se quiser maximizar a precisão do seu modelo, pode querer comunicar esta métrica no final de cada época de preparação. A Vertex AI usa estas informações para decidir que hiperparâmetros usar para a próxima tentativa de treino. Saiba mais sobre como selecionar e especificar uma métrica de ajuste de hiperparâmetros.

Use a biblioteca cloudml-hypertunePython para comunicar a métrica de ajuste de hiperparâmetros. Esta biblioteca está incluída em todos os contentores pré-criados para preparação, e pode usar pip para a instalar num contentor personalizado.

Para saber como instalar e usar esta biblioteca, consulte o repositório do cloudml-hypertune GitHub ou consulte o Vertex AI: Hyperparameter Tuning codelab.

Escreva código para GPUs

Pode selecionar VMs com unidades de processamento de gráficos (GPUs) para executar o seu código de programação personalizado. Saiba como configurar a preparação personalizada para usar VMs com GPU.

Se quiser preparar com GPUs, certifique-se de que o código de preparação pode tirar partido delas. Consoante a framework de ML que usar, isto pode exigir alterações ao seu código. Por exemplo, se usar o TensorFlow Keras, só tem de ajustar o código se quiser usar mais do que uma GPU. Algumas frameworks de ML não podem usar GPUs.

Além disso, certifique-se de que o seu contentor suporta GPUs: selecione um contentor pré-criado para a preparação que suporte GPUs ou instale o NVIDIA CUDA Toolkit e o NVIDIA cuDNN no seu contentor personalizado. Uma forma de o fazer é usar a imagem base do nvidia/cuda repositório do Docker. Outra forma é usar uma instância do Deep Learning Containers como imagem base.

Escreva código para preparação distribuída

Para fazer a preparação em grandes conjuntos de dados, pode executar o seu código em várias VMs num cluster distribuído gerido pelo Vertex AI. Saiba como configurar várias VMs para a preparação.

Algumas frameworks de ML, como o TensorFlow e o PyTorch, permitem-lhe executar código de preparação idêntico em várias máquinas que coordenam automaticamente a forma de dividir o trabalho com base em variáveis de ambiente definidas em cada máquina. Descubra se a Vertex AI define variáveis de ambiente para tornar isto possível para a sua estrutura de ML.

Em alternativa, pode executar um contentor diferente em cada um dos vários conjuntos de trabalhadores. Um conjunto de trabalhadores é um grupo de VMs que configura para usar as mesmas opções de computação e contentor. Neste caso, provavelmente, ainda vai querer basear-se nas variáveis de ambiente definidas pelo Vertex AI para coordenar a comunicação entre as VMs. Pode personalizar o código de preparação de cada conjunto de trabalhadores para realizar as tarefas arbitrárias que quiser. A forma como o faz depende do seu objetivo e da framework de ML que usa.

Monitorize e visualize experiências de preparação personalizada com o Vertex AI TensorBoard

O Vertex AI TensorBoard é uma versão gerida do TensorBoard, um projeto de código aberto da Google para visualizar experiências de aprendizagem automática. Com o Vertex AI TensorBoard, pode monitorizar, visualizar e comparar experiências de AA e, em seguida, partilhá-las com a sua equipa. Também pode usar o Cloud Profiler para identificar e corrigir gargalos de desempenho para formar modelos mais rápida e economicamente.

Para usar o Vertex AI TensorBoard com a preparação personalizada, tem de fazer o seguinte:

  • Crie uma instância do Vertex AI TensorBoard no seu projeto para armazenar as suas experiências (consulte o artigo Crie uma instância do TensorBoard).

  • Configure uma conta de serviço para executar a tarefa de preparação personalizada com as autorizações adequadas.

  • Ajuste o código de preparação personalizado para escrever registos compatíveis com o TensorBoard no Cloud Storage (consulte Alterações ao script de preparação)

Para um guia passo a passo, consulte o artigo Usar o Vertex AI TensorBoard com preparação personalizada.

O que se segue?