Coloque em contentores e execute código de preparação localmente

Pode usar o comando gcloud ai custom-jobs local-run para criar uma imagem de contentor do Docker com base no seu código de preparação e executar a imagem como um contentor no seu computador local. Esta funcionalidade oferece várias vantagens:

  • Pode criar uma imagem de contentor com conhecimentos mínimos do Docker. Não precisa de escrever o seu próprio Dockerfile. Posteriormente, pode enviar esta imagem para o Artifact Registry e usá-la para formação de contentores personalizados.

    Para exemplos de utilização avançada, pode querer escrever o seu próprio Dockerfile.

  • A imagem do contentor pode executar uma aplicação de preparação Python ou um script Bash.

    Pode usar um script Bash para executar código de preparação escrito noutra linguagem de programação (desde que também especifique uma imagem de contentor base que suporte a outra linguagem).

  • A execução de um contentor localmente executa o código de preparação de forma semelhante à execução no Vertex AI.

    A execução do código localmente pode ajudar a depurar problemas com o código antes de realizar a preparação personalizada no Vertex AI.

Antes de começar

  1. Configure o seu ambiente de desenvolvimento do Vertex AI.

  2. Instale o Docker Engine.

  3. Se estiver a usar o Linux, configure o Docker para o poder executar sem sudo.

    O comando local-run requer esta configuração para usar o Docker.

Use o comando local-run

Execute o seguinte comando para criar uma imagem de contentor com base no seu código de treino e executar um contentor localmente:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME

Substitua o seguinte:

  • BASE_IMAGE_URI: o URI de uma imagem de Docker a usar como base do contentor. Escolha uma imagem base que inclua as dependências necessárias para o seu código de preparação.

    Pode usar o URI para uma imagem de contentor de preparação ou qualquer outro valor que seja válido para uma instrução DockerfileFROM; por exemplo, uma imagem do Docker disponível publicamente ou uma imagem do Docker no Artifact Registry à qual tem acesso.

  • WORKING_DIRECTORY: o diretório de nível mais baixo no seu sistema de ficheiros que contém todo o código de preparação e as dependências locais que precisa de usar para a preparação.

    Por predefinição, o comando apenas copia o diretório principal do ficheiro especificado pela flag --script (consulte o item da lista seguinte) para a imagem do Docker resultante. A imagem do Docker não inclui necessariamente todos os ficheiros em WORKING_DIRECTORY. Para personalizar os ficheiros incluídos, consulte a secção neste documento sobre incluir dependências.

    Se omitir a flag --local-package-path (e este marcador de posição), o comando local-run usa o diretório de trabalho atual para este valor.

  • SCRIPT_PATH: o caminho, relativo a WORKING_DIRECTORY no seu sistema de ficheiros local, para o script que é o ponto de entrada para o seu código de preparação. Pode ser um script Python (terminado em .py) ou um script Bash.

    Por exemplo, se quiser executar /hello-world/trainer/task.py e WORKING_DIRECTORY for /hello-world, use trainer/task.py para este valor.

    Se especificar um script Python, a imagem base tem de ter o Python instalado. Se especificar um script bash, a imagem base tem de ter o Bash instalado. (Todos os contentores de preparação pré-criados e muitas outras imagens do Docker disponíveis publicamente incluem estas duas dependências.)

    Use --python-module em vez de --script

    Se omitir a flag --script (e SCRIPT_PATH), tem de usar a flag --python-module para especificar o nome de um módulo Python em WORKING_DIRECTORY a executar como ponto de entrada para a preparação. Por exemplo, em vez de --script=trainer/task.py, pode especificar --python-module=trainer.task.

    Neste caso, o contentor Docker resultante carrega o seu código como um módulo em vez de como um script. É provável que queira usar esta opção se o script do ponto de entrada importar outros módulos Python em WORKING_DIRECTORY.

  • OUTPUT_IMAGE_NAME: um nome para a imagem de Docker resultante criada pelo comando. Pode usar qualquer valor aceite pela flag -t de docker build.

    Se planeia enviar posteriormente a imagem para o Artifact Registry, é recomendável usar um nome de imagem que cumpra os requisitos do Artifact Registry. (Em alternativa, pode etiquetar a imagem com nomes adicionais mais tarde).

    Se omitir a flag --output-image-uri (e este marcador de posição), o comando local-run marca a imagem com um nome baseado na hora atual e no nome do ficheiro do seu script de ponto de entrada.

O comando cria uma imagem de contentor Docker com base na sua configuração. Depois de criar a imagem, o comando imprime a seguinte saída:

A training image is built.
Starting to run ...

Em seguida, o comando usa imediatamente esta imagem de contentor para executar um contentor no seu computador local. Quando o contentor é terminado, o comando imprime a seguinte saída:

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

Opções adicionais

As secções seguintes descrevem opções adicionais que pode usar para personalizar o comportamento do comando local-run.

Instale dependências

O seu código de preparação pode basear-se em quaisquer dependências instaladas na sua imagem base (por exemplo, as imagens do contentor de preparação pré-criado incluem muitas bibliotecas Python para aprendizagem automática), bem como em quaisquer ficheiros que inclua na imagem Docker criada pelo comando local-run.

Quando especifica um script com a flag --script ou a flag --python-module, o comando copia o diretório principal do script (e os respetivos subdiretórios) para a imagem do Docker. Por exemplo, se especificar --local-package-path=/hello-world e --script=trainer/task.py, o comando copia /hello-world/trainer/ para a imagem do Docker.

Também pode incluir dependências Python adicionais ou ficheiros arbitrários do seu sistema de ficheiros concluindo os passos adicionais descritos numa das seguintes secções:

Instale dependências adicionais do Python

Pode incluir dependências adicionais do Python na imagem do Docker de várias formas:

Usar um ficheiro requirements.txt

Se existir um ficheiro com o nome requirements.txt no diretório de trabalho, o comando local-run trata-o como um ficheiro de requisitos do pip e usa-o para instalar dependências do Python na imagem do Docker.

Usar um ficheiro setup.py

Se existir um ficheiro denominado setup.py no diretório de trabalho, o comando local-run trata-o como um ficheiro Python setup.py, copia o ficheiro para a imagem do Docker e executa pip install no diretório na imagem do Docker que contém este ficheiro.

Por exemplo, pode adicionar um install_requires argumento a setup.py para instalar dependências do Python na imagem do Docker.

Especifique dependências individuais do PyPI

Pode usar a flag --requirements para instalar dependências específicas do PyPI na imagem do Docker. Por exemplo:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --requirements=REQUIREMENTS

Substitua REQUIREMENTS por uma lista separada por vírgulas de especificadores de requisitos do Python.

Especifique dependências locais adicionais do Python

Pode usar a flag --extra-packages para instalar dependências locais específicas do Python. Estas dependências do Python têm de estar no diretório de trabalho e cada dependência tem de estar num formato que o pip install suporta; por exemplo, um ficheiro wheel ou uma distribuição de origem do Python.

Por exemplo:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-packages=LOCAL_DEPENDENCIES

Substitua LOCAL_DEPENDENCIES por uma lista separada por vírgulas de caminhos de ficheiros locais, expressos relativamente ao diretório de trabalho.

Inclua outros ficheiros

Para copiar diretórios adicionais para a imagem do Docker (sem os instalar como dependências do Python), pode usar a flag --extra-dirs. Só pode especificar diretórios no diretório de trabalho. Por exemplo:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-dirs=EXTRA_DIRECTORIES

Substitua EXTRA_DIRECTORIES por uma lista de diretórios locais separados por vírgulas, expressos relativamente ao diretório de trabalho.

Argumentos da aplicação de preparação

Se o script do ponto de entrada da sua aplicação de preparação esperar argumentos da linha de comandos, pode especificá-los quando executar o comando local-run. Estes argumentos não são guardados na imagem do Docker. Em vez disso, são transmitidos como argumentos quando a imagem é executada como um contentor.

Para transmitir argumentos ao script do ponto de entrada, transmita o argumento -- seguido dos argumentos do script para o comando local-run após todas as outras flags do comando.

Por exemplo, imagine um script que executa localmente com o seguinte comando:

python /hello-world/trainer/task.py \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Quando usa o comando local-run, pode usar as seguintes flags para executar o script no contentor com os mesmos argumentos:

gcloud ai custom-jobs local-run \\
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=/hello-world \
  --script=/trainer/task.py \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  -- \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Acelere a preparação de modelos com GPUs

Se quiser implementar a imagem Docker criada pelo comando local-run no Vertex AI e usar GPUs para o treino, certifique-se de que escreve código de treino que tira partido das GPUs e usa uma imagem Docker com GPUs ativadas para o valor da flag --executor-image-uri. Por exemplo, pode usar uma das imagens de contentores de preparação pré-criadas que suportam GPUs.

Se o seu computador local executar o Linux e tiver GPUs, também pode configurar o comando local-run para usar as GPUs quando executar um contentor localmente. Isto é opcional, mas pode ser útil se quiser testar como o seu código de preparação funciona com GPUs. Faça o seguinte:

  1. Instale o NVIDIA Container Toolkit (nvidia-docker) no seu computador local, se ainda não o tiver feito.

  2. Especifique a flag --gpu quando executar o comando local-run. Por exemplo:

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --gpu

Especifique uma conta de serviço personalizada

Por predefinição, quando o comando local-runexecuta o código de preparação num contentor local, monta as credenciais disponíveis no seu ambiente local através das credenciais predefinidas da aplicação (ADC) no contentor, para que o código de preparação possa usar as ADC para autenticação com as mesmas credenciais. Google Cloud Por outras palavras, as credenciais disponíveis pelo ADC na sua shell local também estão disponíveis pelo ADC para o seu código quando executa o comando local-run.

Pode usar o comando gcloud auth application-default login para usar a sua conta de utilizador para o ADC ou definir uma variável de ambiente na sua shell para usar uma conta de serviço para o ADC.

Se quiser que o contentor seja executado com Google Cloud credenciais diferentes das disponíveis através do ADC no seu shell local, faça o seguinte:

  1. Crie ou selecione uma conta de serviço com as autorizações às quais quer que o seu código de preparação tenha acesso.

  2. Transfira uma chave da conta de serviço para esta conta de serviço para o seu computador local.

  3. Quando executar o comando local-run, especifique a flag --service-account-key-file. Por exemplo:

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --service-account-key-file=KEY_PATH

    Substitua KEY_PATH pelo caminho para a chave da conta de serviço no seu sistema de ficheiros local. Este caminho tem de ser absoluto ou relativo ao diretório de trabalho atual do seu shell, não relativo ao diretório especificado pela flag --local-package-path.

No contentor resultante, o seu código de preparação pode usar o ADC para fazer a autenticação com as credenciais da conta de serviço especificadas.

Comparação com a preparação no Vertex AI

Quando realiza uma preparação personalizada no Vertex AI, o Vertex AI usa o agente de serviço de código personalizado do Vertex AI para o seu projeto por predefinição para executar o seu código. Também pode anexar uma conta de serviço diferente para o treino personalizado.

Quando usa o comando local-run, não pode autenticar como o agente do serviço de código personalizado do Vertex AI, mas pode criar uma conta de serviço com autorizações semelhantes e usá-la localmente.

O que se segue?