Veja neste tutorial como usar a biblioteca de cliente das APIs do Google para Python para chamar as APIs REST do AI Platform Training nos seus aplicativos em Python. Os snippets e exemplos de código no restante desta documentação usam essa biblioteca de cliente do Python.
Você também criará um modelo no seu projeto do Google Cloud. Trata-se de uma tarefa simples, facilmente desenvolvida como um pequeno exemplo.
Objetivos
Este é um tutorial básico, elaborado para você se familiarizar com a biblioteca de cliente do Python. Depois de terminá-lo, será possível executar as seguintes tarefas:- Conseguir uma representação em Python dos serviços do AI Platform.
- Usar essa representação para criar um modelo no projeto, que ajudará a chamar as outras APIs de gerenciamento de modelos e jobs.
Custos
Você não será cobrado pelas operações executadas neste tutorial. Consulte a página de preços para saber mais.Antes de começar
Configurar o projeto GCP
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Enable the AI Platform Training & Prediction and Compute Engine APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Enable the AI Platform Training & Prediction and Compute Engine APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
Configurar a autenticação
Para configurar a autenticação, crie uma chave da conta de serviço e defina uma variável de ambiente para o caminho do arquivo dessa chave.
-
Crie uma conta de serviço:
-
No Console do Google Cloud, acesse a página Criar conta de serviço.
- No campo Nome da conta de serviço, insira um nome.
- Opcional: no campo Descrição da conta de serviço, digite uma descrição.
- Clique em Criar.
- Clique no campo Selecionar um papel. Em Todos os papéis, selecione AI Platform > Administrador do AI Platform.
- Clique em Adicionar outro papel.
-
Clique no campo Selecionar um papel. Em Todos os papéis, selecione Armazenamento > Administrador de objetos do Storage.
-
Clique em Concluído para criar a conta de serviço.
Não feche a janela do navegador. Você vai usá-la na próxima etapa.
-
-
Crie uma chave da conta de serviço para autenticação:
- No console do Google Cloud, clique no endereço de e-mail da conta de serviço que você criou.
- Clique em Chaves.
- Clique em Adicionar chave e, depois, em Criar nova chave.
- Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
- Clique em Fechar.
-
Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável aplica-se apenas à sessão de shell atual. Portanto, se você abrir uma nova sessão, defina a variável novamente.
Configurar um ambiente de desenvolvimento em Python
Escolha uma das opções abaixo para configurar o ambiente localmente no macOS ou em um ambiente remoto no Cloud Shell.
Para usuários do macOS, recomendamos a configuração do ambiente usando a guia MACOS abaixo. O Cloud Shell, mostrado na guia CLOUD SHELL, está disponível para macOS, Linux e Windows. Com ele, você testa rapidamente o AI Platform Training. No entanto, ele não é adequado para trabalhos de desenvolvimento contínuos.
macOS
-
Verificar a instalação do Python
Verifique se o Python (em inglês) está instalado e, se necessário, instale-o.python -V
-
Verificar a
pip
instalação do
pip
é o gerenciador de pacote do Python, incluído nas versões atuais do Python. Executepip --version
para verificar se opip
já está instalado. Caso contrário, veja como instalar opip
(em inglês).É possível fazer upgrade do
pip
usando o comando a seguir:pip install -U pip
Consulte a documentação do pip para mais detalhes.
-
Instalar
virtualenv
virtualenv
é uma ferramenta para criar ambientes Python isolados. Executevirtualenv --version
para verificar se avirtualenv
já está instalada. Caso contrário, instalevirtualenv
(em inglês):pip install --user --upgrade virtualenv
Para criar um ambiente de desenvolvimento isolado para este guia, crie um novo ambiente virtual em
virtualenv
. Por exemplo, com o comando a seguir, você ativa um ambiente chamadoaip-env
:virtualenv aip-env source aip-env/bin/activate
-
Neste tutorial, execute o restante dos comandos no ambiente virtual.
Veja mais informações sobre o uso davirtualenv
(em inglês). Para sair davirtualenv
, executedeactivate
.
Cloud Shell
-
Abra o console do Google Cloud.
-
Clique no botão Ativar o Cloud Shell na parte superior da janela do console.
Uma sessão do Cloud Shell é aberta em um novo frame na parte inferior do console e um prompt de linha de comando é exibido. A inicialização da sessão do shell pode levar alguns segundos.
A sessão do Cloud Shell está pronta para ser usada.
-
Configure a ferramenta de linha de comando
gcloud
para usar o projeto selecionado.gcloud config set project [selected-project-id]
em que
[selected-project-id]
é o ID do projeto. Retire os colchetes incluídos.
Instale a biblioteca de cliente da API do Google para Python.
Instale a biblioteca de cliente da API do Google para Python.
- Conseguir uma representação em Python dos serviços do AI Platform.
- Usar essa representação para criar um modelo no projeto, que ajudará a chamar as outras APIs de gerenciamento de modelos e jobs.
Como importar os módulos necessários
Quando você quiser usar a biblioteca de cliente das APIs do Google para Python a fim de chamar as APIs REST do AI Platform Training no seu código, importe o respectivo pacote e o pacote OAuth2. Para este tutorial (e para a maioria dos usos padrão do AI Platform Training), será preciso apenas importar módulos específicos:
GoogleCredentials
do OAuth2discovery
da biblioteca de cliente da API do Google para Python.errors
da biblioteca de cliente da API do Google para Python
Consulte a documentação desses pacotes para saber mais sobre outros módulos disponíveis.
Crie um arquivo Python usando o editor que preferir e adicione estas linhas:
from oauth2client.client import GoogleCredentials from googleapiclient import discovery from googleapiclient import errors
Como criar uma representação em Python da API
Consiga a representação Python da API REST. Você chama o método build
porque a biblioteca de cliente da API usa a descoberta de serviço para configurar dinamicamente as conexões com os serviços que já existem quando a chamada é feita. Chame o objeto que encapsula os serviços ml
:
ml = discovery.build('ml','v1')
Como configurar os parâmetros e o corpo da solicitação
Para fazer uma chamada para um serviço, crie os parâmetros e o corpo da solicitação que serão informados à API REST. Informe os parâmetros como parâmetros regulares do Python para o método que representa a chamada. O corpo é um recurso JSON, igual ao que você usaria se chamasse diretamente a API com uma solicitação HTTP.
Observe a API REST para criar um modelo em uma nova guia do navegador, projects.models.create:
Observe o parâmetro de caminho
parent
, que é a parte do URI da solicitação que identifica o projeto. Se estiver fazendo a solicitação HTTP POST diretamente, você usará o seguinte URI:https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models
Quando você usa a biblioteca de cliente da API, a parte variável do URI é representada como um parâmetro do tipo string para a chamada da API. Defina-o como
'projects/<var>YOUR_PROJECT_ID</var>'
. Armazene o projeto em uma variável para tornar as chamadas da API mais limpas:project_id = 'projects/{}'.format('YOUR_PROJECT_ID')
O corpo da solicitação é um recurso JSON que representa a informação do modelo. Você pode ver no definição de recurso do modelo que ela tem dois valores de entrada: name e (opcionalmente) description. É possível transferir um dicionário Python no lugar do JSON e a biblioteca de cliente da API realizará a conversão necessária.
Para criar o dicionário Python:
request_dict = {'name': 'your-model-name', 'description': 'This is a machine learning model entry.'}
Como criar a solicitação
As chamadas para APIs com a biblioteca cliente Python têm duas etapas: primeiro, você cria uma solicitação, depois, você a usa para fazer a chamada.
Criar a solicitação
Use os objetos cliente que criou anteriormente como a raiz da hierarquia da API e especifique a API que você quer usar. Se tiver seguido exatamente o snippet de código, o objeto se chama ml
. Cada coleção no caminho da API se comporta como uma função que retorna uma lista das coleções e métodos existentes na API. Por exemplo, a raiz de todas as APIs do AI Platform Training é projects
, portanto, a chamada começa com ml.projects()
.
Use este código para criar a solicitação:
request = ml.projects().models().create(parent=project_id, body=request_dict)
Enviar a solicitação
A solicitação criada na última etapa expõe um método execute
que é chamado para enviar a solicitação ao serviço:
response = request.execute()
É comum que os desenvolvedores combinem esta etapa com a última:
response = ml.projects().models().create(parent=project_id, body=request_dict).execute()
Lidar com erros simples
Muitas coisas podem dar errado quando você faz chamadas de API pela Internet. É importante saber lidar com os erros mais comuns. A maneira mais simples de fazer isso é colocar sua solicitação em um bloco try
e capturar prováveis erros. A maioria dos erros que você provavelmente receberá do serviço é de HTTP, encapsulados na classe HttpError
. Para detectar esses erros, use o módulo errors
do pacote googleapiclient
.
Encapsule a chamada request.execute()
em um bloco try
. Para imprimir a resposta de uma chamada bem-sucedida, insira também uma declaração print
no bloco:
try: response = request.execute() print(response)
Por fim, adicione um bloco de detecção para processar os erros HTTP. É possível usar HttpError._get_reason()
para receber os campos de texto de razão da resposta:
except errors.HttpError, err: # Something went wrong, print out some information. print('There was an error creating the model. Check the details:') print(err._get_reason())
No entanto, uma declaração impressa simples pode não ser a abordagem correta para seu aplicativo.
Como realizar o funcionamento em conjunto
Veja o exemplo completo:
from googleapiclient import discovery from googleapiclient import errors # Store your full project ID in a variable in the format the API needs. project_id = 'projects/{}'.format('YOUR_PROJECT_ID') # Build a representation of the Cloud ML API. ml = discovery.build('ml', 'v1') # Create a dictionary with the fields from the request body. request_dict = {'name': 'your_model_name', 'description': 'your_model_description'} # Create a request to call projects.models.create. request = ml.projects().models().create( parent=project_id, body=request_dict) # Make the call. try: response = request.execute() print(response) except errors.HttpError, err: # Something went wrong, print out some information. print('There was an error creating the model. Check the details:') print(err._get_reason())
Como generalizar para outros métodos
É possível usar o procedimento aprendido aqui para fazer qualquer chamada da API. REST Algumas das APIs exigem recursos JSON muito mais complicados que a criação de um modelo, mas os princípios são os mesmos:
Importe
googleapiclient.discovery
egoogleapiclient.errors
.Use o módulo de descoberta para criar uma representação Python da API.
Use a representação da API como uma série de objetos aninhados para chegar à API que você quer e criar uma solicitação. Por exemplo,
request = ml.projects().models().versions().delete( name='projects/myproject/models/mymodel/versions/myversion')
Chame
request.execute()
para enviar a solicitação, lidando com as exceções da forma adequada ao aplicativo.Quando há um corpo de resposta, é possível tratá-lo como um dicionário Python e conseguir os objetos JSON especificados na referência da API. Muitos dos objetos nas respostas têm campos que estão presentes apenas em algumas circunstâncias. Verifique sempre para evitar erros de chave:
response = request.execute() some_value = response.get('some_key') or 'default_value'
A seguir
- Confira arquiteturas de referência, diagramas, tutoriais e práticas recomendadas do Google Cloud. Confira o Centro de arquitetura do Cloud.
- Conheça melhor a API AI Platform Training.
- Saiba como gerenciar modelos na visão geral de gerenciamento de modelos e jobs.