Como empacotar um aplicativo de treinamento

Antes de executar o aplicativo de treinamento com o AI Platform Training, é preciso fazer upload do código e de todas as dependências para um bucket do Cloud Storage que o projeto do Google Cloud possa acessar. Nesta página, você verá como empacotar e organizar o aplicativo na nuvem.

Para resultados melhores, teste o aplicativo de treinamento localmente antes de fazer upload para a nuvem. O treinamento com o AI Platform Training gera cobranças em sua conta pelos recursos utilizados.

Antes de começar

Antes de migrar seu aplicativo de treinamento para a nuvem, conclua as etapas a seguir:

  1. Configure o ambiente de desenvolvimento conforme descrito no guia de primeiros passos.

  2. Desenvolva o aplicativo de treinamento com um dos frameworks de machine learning hospedados do AI Platform Training: TensorFlow, scikit-learn ou XGBoost. Se preferir, crie um contêiner personalizado para personalizar o ambiente do aplicativo de treinamento. Assim, você terá a opção de usar frameworks de machine learning diferentes daqueles do AI Platform Training.

    Se você quiser implantar o modelo treinado no AI Platform Prediction após o treinamento, leia o guia sobre como exportar o modelo para previsão para garantir que o pacote de treinamento exporte artefatos de modelo que o AI Platform Prediction possa usar.

  3. Siga o guia para configurar um bucket do Cloud Storage no qual armazenar os dados e arquivos de seu aplicativo de treinamento.

  4. Conheça todas as bibliotecas de Python de que seu aplicativo de treinamento depende, sejam elas pacotes personalizados ou disponíveis gratuitamente por meio do PyPI.

Neste documento, discutimos os seguintes fatores que influenciam a maneira de empacotar o aplicativo e fazer upload dele para o Cloud Storage:

  • Uso da CLI gcloud (recomendado) ou codificação de sua própria solução.
  • Criação manual de um pacote, se necessário.
  • como incluir outras dependências não instaladas pelo ambiente de execução do AI Platform Training que você está usando.

A maneira mais simples de empacotar o aplicativo e fazer o upload com as dependências é usar a CLI gcloud. Use um único comando (gcloud ai-platform jobs submit training) para empacotar e fazer upload do aplicativo e enviar seu primeiro job de treinamento.

Por conveniência, é útil definir os valores de configuração como variáveis de shell:

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

Substitua:

  • LOCAL_PACKAGE_PATH: o caminho para o diretório do pacote Python no ambiente local
  • MODULE_NAME: o nome totalmente qualificado do módulo de treinamento
  • BUCKET_NAME: o nome de um bucket do Cloud Storage
  • JOB_NAME: um nome para o job de treinamento
  • JOB_OUTPUT_PATH: o URI de um diretório do Cloud Storage em que você quer que o job de treinamento salve a saída
  • REGION: a região em que você quer executar o job de treinamento

Veja mais detalhes sobre os requisitos desses valores na lista após o comando a seguir.

No exemplo a seguir, mostramos um comando gcloud ai-platform jobs submit training que empacota um aplicativo e envia o job de treinamento:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

  • --staging-bucket especifica um bucket do Cloud Storage em que você quer preparar seus pacotes de treinamento e de dependência. Seu projeto do Google Cloud precisa ter acesso a esse bucket do Cloud Storage, que precisa estar na mesma região em que o job é executado. Veja as regiões disponíveis para os serviços do AI Platform Training. Se você não especificar um bucket de preparo, o AI Platform Training organizará os pacotes no local especificado no parâmetro job-dir.

  • --job-dir especifica o local do Cloud Storage que você quer usar para os arquivos de saída do job de treinamento. Seu projeto do Google Cloud precisa ter acesso a esse bucket do Cloud Storage, que precisa estar na mesma região de execução do job. Veja as regiões disponíveis para os serviços do AI Platform Training.

  • --package-path especifica o caminho local para o diretório do aplicativo. A CLI gcloud cria um pacote de distribuição .tar.gz do código com base no arquivo setup.py no diretório pai do que foi especificado por --package-path. Em seguida, ele faz upload desse arquivo .tar.gz para o Cloud Storage e o usa para executar o job de treinamento.

    Se não houver nenhum arquivo setup.py no local esperado, a CLI gcloud criará um setup.py simples e temporário e incluirá apenas o diretório especificado por --package-path no arquivo .tar.gz.

  • --module-name especifica o nome do módulo principal do aplicativo, usando a notação de ponto de namespace do pacote. Trata-se do arquivo Python executado para iniciar o aplicativo. Por exemplo, se o módulo principal for .../my_application/trainer/task.py (consulte a estrutura de projeto recomendada), o nome do módulo será trainer.task.

  • Caso especifique uma opção no arquivo de configuração (config.yaml) e como uma sinalização de linha de comando, o valor na linha de comando modificará o valor no arquivo de configuração.
  • A sinalização -- vazia marca o fim das sinalizações específicas do gcloud e o início do USER_ARGS que você quer passar para seu aplicativo.
  • Sinalizações específicas do AI Platform Training, como --module-name, --runtime-version e --job-dir, precisam ser inseridas antes da sinalização -- vazia. O serviço do AI Platform Training interpreta essas sinalizações.
  • É necessário que a sinalização --job-dir, se especificada, venha antes da sinalização vazia -- porque o AI Platform Training usa --job-dir para validar o caminho.
  • Seu aplicativo também precisa manipular a sinalização --job-dir, se especificada. Mesmo que a sinalização venha antes do -- vazio, --job-dir também será passado ao seu aplicativo como uma sinalização de linha de comando.
  • Defina quantos USER_ARGS forem necessários. O AI Platform Training passa --user_first_arg, --user_second_arg e assim por diante até seu aplicativo.

Para saber mais sobre as sinalizações de envio de jobs, consulte o guia para executar um job de treinamento.

Como trabalhar com dependências

Dependências são pacotes que você importa no código. O aplicativo pode precisar de muitas dependências para funcionar.

Quando você executa um job de treinamento no AI Platform Training, ele é executado em instâncias de treinamento (máquinas virtuais especialmente configuradas) com muitos pacotes comuns do Python já instalados. Verifique os pacotes incluídos na versão de ambiente de execução usados para treinamento e observe quais dependências ainda não estão instaladas.

Há dois tipos de dependências que talvez seja necessário adicionar:

  • Dependências padrão, pacotes comuns em Python disponíveis em PyPI (em inglês).
  • Pacotes personalizados, como os que você desenvolve ou que são internos de uma organização.

Nas seções abaixo, descrevemos os procedimentos para cada tipo.

Como adicionar dependências padrão (PyPI)

É possível especificar as dependências padrão do pacote como parte do script setup.py correspondente. O AI Platform Training usa pip para instalar o pacote nas instâncias de treinamento alocadas para o job. O comando pip install procura e instala dependências configuradas.

Criar um arquivo denominado setup.py no diretório raiz do aplicativo, um diretório acima do diretório trainer se você seguir o padrão recomendado.

Insira o seguinte script em setup.py, usando seus próprios valores:

from setuptools import find_packages
from setuptools import setup

REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']

setup(
    name='trainer',
    version='0.1',
    install_requires=REQUIRED_PACKAGES,
    packages=find_packages(),
    include_package_data=True,
    description='My training application package.'
)

Se enviar o job de treinamento com a Google Cloud CLI, o arquivo setup.py é usado automaticamente para fazer o pacote.

Se você enviar o job de treinamento sem usar gcloud, use o seguinte comando para executar o script:

python setup.py sdist

Para mais informações, consulte a seção sobre como empacotar manualmente seu aplicativo de treinamento.

Como adicionar dependências personalizadas

Passe os caminhos das dependências personalizadas do aplicativo como parte da configuração do job para especificá-las. Para isso, você precisa do URI para o pacote de cada uma. As dependências personalizadas precisam estar em um local do Cloud Storage. O AI Platform Training usa pip install para instalar dependências personalizadas. Assim, elas podem ter dependências padrão próprias nos scripts setup.py.

Se você usar a CLI gcloud para executar o job de treinamento, poderá especificar dependências na máquina local e no Cloud Storage. A ferramenta vai organizar as dependências na nuvem por você: quando executar o comando gcloud ai-platform jobs submit training, defina a sinalização --packages para incluir as dependências em uma lista separada por vírgulas.

Cada URI incluído é o caminho para um pacote de distribuição, formatado como um tarball (.tar.gz) ou como uma roda (.whl). O AI Platform Training instala cada pacote usando pip install em cada máquina virtual alocada para o job de treinamento.

No exemplo abaixo, especificamos as dependências empacotadas denominadas dep1.tar.gz e dep2.whl (cada um dos tipos de pacote compatíveis) junto com um caminho para as origens do aplicativo:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MODULE_NAME \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Da mesma forma, no exemplo abaixo, especificamos as dependências empacotadas denominadas dep1.tar.gz e dep2.whl (cada um dos tipos de pacote compatíveis), mas com um aplicativo de treinamento criado:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Se você executar jobs de treinamento usando a API AI Platform Training and Prediction diretamente, precisará preparar os pacotes de dependência em um local do Cloud Storage e, em seguida, usar os caminhos para os pacotes nesse local.

Como criar o pacote manualmente

O código Python de empacotamento é um assunto amplo que ultrapassa muito o escopo desta documentação. Por conveniência, nesta seção você terá uma visão geral do uso do Setuptools para criar seu pacote. Há outras bibliotecas que podem ser usadas para fazer o mesmo.

Siga estas etapas para criar seu pacote manualmente:

  1. Em cada diretório do pacote de aplicativo, inclua um arquivo denominado __init__.py, que pode estar vazio ou conter o código a ser executado quando esse pacote (qualquer módulo nesse diretório) for importado.

  2. No diretório pai de todo o código que você quer incluir no pacote de distribuição .tar.gz (um diretório acima do diretório trainer, se você seguir o padrão recomendado), inclua o arquivo do Setuptools (em inglês) denominado setup.py. Ele inclui:

    • instruções de importação referentes a setuptools.find_packages e setuptools.setup;

    • uma chamada a setuptools.setup com, no mínimo, estes parâmetros definidos:

      • _name_ definido como o nome do namespace do pacote;

      • _version_ definido como o número da versão deste build do pacote;

      • _install_requires_ definido como uma lista de pacotes exigidos pelo aplicativo, com requisitos de versão, como 'docutils>=0.3';

      • _packages_ definido como find_packages(). Ele instrui o Setuptools a incluir todos os subdiretórios do diretório pai que contêm um arquivo __init__.py como "pacotes de importação" (importe módulos deles em Python com instruções como from trainer import util) no "pacote de distribuição" (o arquivo `.tar.gz contendo todo o código);

      • _include_package_data_ definido como True.

  3. Execute python setup.py sdist para criar o pacote de distribuição .tar.gz.

Estrutura de projeto recomendada

Você estrutura o aplicativo de treinamento da maneira que preferir. No entanto, a estrutura a seguir é normalmente usada em exemplos do AI Platform Training, e ter a organização do projeto semelhante aos exemplos facilita o acompanhamento deles.

  • Use um diretório principal do projeto, contendo o arquivo setup.py.

    Use a função find_packages() de setuptools no arquivo setup.py para garantir que todos os subdiretórios sejam incluídos no pacote de distribuição .tar.gz que você criar.

  • Use um subdiretório denominado trainer para armazenar o módulo principal do aplicativo.

  • Nomeie o módulo principal do aplicativo task.py.

  • Crie qualquer outro subdiretório que você precise para implementar o aplicativo no diretório de projeto principal.

  • Crie um arquivo __init__.py em cada subdiretório. Esses arquivos são usados pelo Setuptools (em inglês) para identificar diretórios com código a ser empacotado e podem estar vazios.

Nos exemplos do AI Platform Training, o diretório trainer geralmente contém os seguintes arquivos de origem:

  • task.py, contendo a lógica do aplicativo que gerencia o job de treinamento;

  • model.py, contendo a lógica do modelo;

  • util.py, se houver, contendo o código para executar o aplicativo de treinamento.

Estrutura recomendada de um projeto de aplicativo de treinamento

Ao executar gcloud ai-platform jobs submit training, defina --package-path como trainer. Com isso, a CLI gcloud procura um arquivo setup.py no pai de trainer, o diretório principal do projeto.

Módulos Python

O pacote do aplicativo pode conter vários módulos (arquivos Python). É preciso identificar aquele que contém o ponto de entrada do aplicativo. O serviço de treinamento executa esse módulo invocando o Python, do mesmo modo que você o executaria localmente.

Por exemplo, se você seguir a estrutura recomendada da seção anterior, o módulo principal será task.py. Como ele está dentro de um pacote de importação (diretório com um arquivo __init__.py) denominado trainer, o nome totalmente qualificado deste módulo é trainer.task. Portanto, se você enviar o job com gcloud ai-platform jobs submit training, defina a sinalização --module-name como trainer.task.

Consulte o Guia Python para pacotes (em inglês) para ver mais informações sobre módulos.

Como usar a CLI gcloud para fazer upload de um pacote atual

Se você criou o pacote por conta própria, faça o upload dele com a CLI gcloud. Execute o comando gcloud ai-platform jobs submit training:

  • Defina a sinalização --packages com o caminho para o aplicativo empacotado.

  • Defina a sinalização --module-name com o nome do módulo principal do aplicativo, usando a notação de ponto de namespace do pacote. Trata-se do arquivo Python executado para iniciar o aplicativo. Por exemplo, se o módulo principal for .../my_application/trainer/task.py (consulte a estrutura de projeto recomendada), o nome do módulo será trainer.task.

No exemplo abaixo, veja como usar um pacote tarball compactado denominado trainer-0.0.1.tar.gz que está no mesmo diretório de execução do comando. A função principal está em um módulo chamado task.py:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Como usar a CLI gcloud para usar um pacote atual que já está na nuvem

Se você criar seu próprio pacote, será possível fazer upload dele para um local do Cloud Storage com o gcloud. Execute o comando gcloud ai-platform jobs submit training:

  • Defina a sinalização --packages com o caminho para o aplicativo empacotado.

  • Defina a sinalização --module-name com o nome do módulo principal do aplicativo, usando a notação de ponto de namespace do pacote. Trata-se do arquivo Python executado para iniciar o aplicativo. Por exemplo, se o módulo principal for .../my_application/trainer/task.py (consulte a estrutura de projeto recomendada), o nome do módulo será trainer.task.

No exemplo abaixo, veja como usar um pacote tarball compactado que está em um bucket do Cloud Storage:

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Nele, $PATH_TO_PACKAGED_TRAINER é uma variável de ambiente que representa o caminho para um pacote atual que já está na nuvem. Por exemplo, o caminho pode apontar para o seguinte local do Cloud Storage, contendo um pacote tarball compactado denominado trainer-0.0.1.tar.gz:

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

Como carregar pacotes manualmente

É possível fazer upload dos pacotes manualmente se precisar. O motivo mais comum é chamar a API AI Platform Training and Prediction diretamente para iniciar o job de treinamento. A maneira mais fácil de fazer upload manual do pacote e de qualquer dependência personalizada para o bucket do Cloud Storage é usar a ferramenta comandos gcloud storage:

gcloud storage cp /local/path/to/package.tar.gz  gs://bucket/path/

No entanto, se for possível usar a linha de comando para esta operação, basta usar gcloud ai-platform jobs submit training para fazer upload dos pacotes como parte da configuração de um job de treinamento. Caso não seja possível usar a linha de comando, use a biblioteca de cliente do Cloud Storage para fazer upload programaticamente.

Próximas etapas

Próxima
Como executar um job de treinamento