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:
- Configure o ambiente de desenvolvimento conforme descrito no guia de primeiros passos.
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.
Siga o guia para configurar um bucket do Cloud Storage no qual armazenar os dados e arquivos de seu aplicativo de treinamento.
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.
Como usar o gcloud
para empacotar e fazer upload do aplicativo (recomendado)
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 localMODULE_NAME
: o nome totalmente qualificado do módulo de treinamentoBUCKET_NAME
: o nome de um bucket do Cloud StorageJOB_NAME
: um nome para o job de treinamentoJOB_OUTPUT_PATH
: o URI de um diretório do Cloud Storage em que você quer que o job de treinamento salve a saídaREGION
: 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âmetrojob-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 arquivosetup.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á umsetup.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 dogcloud
e o início doUSER_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ê import
a 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. Usos do AI Platform Training
pip install
para instalar dependências personalizadas, para que possam ter dependências padrão de
por conta própria 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:
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.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óriotrainer
, se você seguir o padrão recomendado), inclua o arquivo do Setuptools (em inglês) denominadosetup.py
. Ele inclui:instruções de importação referentes a
setuptools.find_packages
esetuptools.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 comofind_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 comofrom trainer import util
) no "pacote de distribuição" (o arquivo `.tar.gz contendo todo o código);_include_package_data
_ definido comoTrue
.
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()
desetuptools
no arquivosetup.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.
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
- Configure e execute um job de treinamento.
- Monitore seu job de treinamento durante a execução.
- Saiba mais sobre como o treinamento funciona.