Como receber previsões on-line com o scikit-learn

Esta amostra treina um modelo para prever o nível de renda de uma pessoa com base no conjunto de dados de renda do Censo (em inglês). Depois de treinar e salvar o modelo no local, você o implantará no AI Platform Prediction e o consultará para receber previsões on-line.

É possível implantar e exibir pipelines do scikit-learn (em inglês) no AI Platform Prediction. Com o módulo de pipeline no scikit-learn, é possível aplicar várias transformações de dados antes do treinamento com um estimator. Isso inclui várias etapas do processamento de dados e garante o uso dos mesmos dados de treinamento em cada uma.

Este tutorial também está disponível no GitHub como um notebook do Jupyter.

Como levar seu modelo para o AI Platform Prediction

É possível levar seu modelo para o AI Platform Prediction para receber previsões, basta seguir estas cinco etapas:

• Salve seu modelo em um arquivo.
• Faça upload do modelo salvo no Cloud Storage.
• Crie um recurso de modelo no AI Platform Prediction.
• Crie uma versão de modelo, vinculando seu modelo salvo.
• Faça uma previsão on-line.

Antes de começar

Conclua as etapas a seguir para configurar uma conta do GCP, ativar a API AI Platform Prediction, instalar e ativar o SDK do Cloud.

Configurar o projeto do GCP

1. 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.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. Enable the AI Platform Training & Prediction and Compute Engine APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

9. Enable the AI Platform Training & Prediction and Compute Engine APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

Configurar o ambiente

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 Prediction. No entanto, ele não é adequado para trabalhos de desenvolvimento contínuo.

macOS

1. Verificar a instalação do Python
   Verifique se o Python (em inglês) está instalado e, se necessário, instale-o.

   python -V

2. Verificar a pip instalação do
   pip é o gerenciador de pacote do Python, incluído nas versões atuais do Python. Execute pip --version para verificar se o pip já está instalado. Caso contrário, veja como instalar o pip (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.

3. Instalar virtualenv
virtualenv é uma ferramenta para criar ambientes Python isolados. Execute virtualenv --version para verificar se a virtualenv já está instalada. Caso contrário, instale virtualenv (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 chamado aip-env:

   virtualenv aip-env
   source aip-env/bin/activate

4. Neste tutorial, execute o restante dos comandos no ambiente virtual.

   Veja mais informações sobre o uso da virtualenv (em inglês). Para sair da virtualenv, execute deactivate.

Cloud Shell

1. Abra o console do Google Cloud.

   Console do Google Cloud

2. 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.

3. 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.

Instalar frameworks

macOS

No seu ambiente virtual, execute o comando a seguir para instalar as versões do scikit-learn e do pandas usadas na versão de ambiente de execução 2.11 do AI Platform Prediction:

(aip-env)$ pip install scikit-learn==1.0.2 pandas==1.3.5

Ao fornecer os números de versão no comando anterior, você garante que as dependências em seu ambiente virtual correspondam às dependências na versão do ambiente de execução. Assim, você evita comportamentos inesperados quando o código for executado no AI Platform Prediction.

Para mais detalhes, opções de instalação e solução de problemas, consulte as instruções de instalação de cada framework:

• Instruções de instalação do scikit-learn
• Instruções de instalação do pandas

Cloud Shell

Execute o seguinte comando para instalar o scikit-learn e o pandas:

pip install --user scikit-learn pandas

Para mais detalhes, opções de instalação e solução de problemas, consulte as instruções de instalação de cada framework:

• Instruções de instalação do scikit-learn
• Instruções de instalação do pandas

Fazer download dos dados

O conjunto de dados de renda do censo que esta amostra usa para treinamento é hospedada pelo Repositório de machine learning da UC Irvine (em inglês). Consulte Sobre os dados para mais informações.

• O arquivo de treinamento é adult.data.
• O arquivo de avaliação é adult.test.

Observação: o arquivo adult.test.csv tem um caractere de ponto final extra no fim de cada linha.

Treinar e salvar um modelo

Para treinar e salvar um modelo, conclua as etapas a seguir:

1. Carregue os dados em um DataFrame do pandas a fim de prepará-los para usos com o scikit-learn.
2. Treine um modelo simples no scikit-learn.
3. Salve o modelo em um arquivo que possa ser enviado ao AI Platform Prediction.

Se você já tem um modelo treinado para fazer upload, veja como exportar o modelo.

Carregar e transformar dados

É possível exportar objetos de Pipeline usando a versão de joblib incluída no scikit-learn ou o pickle, do mesmo modo como você exporta estimators do scikit-learn (em inglês). No exemplo a seguir, os pipelines são usados para converter recursos categóricos individuais em valores numéricos e depois são combinados. Em seguida, um RandomForestClassifier (em inglês) é utilizado para treinar o modelo.

Observação: para exportar um artefato de modelo joblib compatível com o AI Platform Prediction, você precisa usar a versão de joblib, que é distribuída com o scikit-learn, e não a versão autônoma. Para importar essa biblioteca em Python, use a instrução from sklearn.externals import joblib.

from sklearn.externals import joblib
import json
import numpy as np
import os
import pandas as pd
import pickle
from sklearn.ensemble import RandomForestClassifier
from sklearn.feature_selection import SelectKBest
from sklearn.pipeline import FeatureUnion
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import LabelBinarizer

# Define the format of your input data, including unused columns.
# These are the columns from the census data files.
COLUMNS = (
    'age',
    'workclass',
    'fnlwgt',
    'education',
    'education-num',
    'marital-status',
    'occupation',
    'relationship',
    'race',
    'sex',
    'capital-gain',
    'capital-loss',
    'hours-per-week',
    'native-country',
    'income-level'
)

# Categorical columns are columns that need to be turned into a numerical value to be used by scikit-learn
CATEGORICAL_COLUMNS = (
    'workclass',
    'education',
    'marital-status',
    'occupation',
    'relationship',
    'race',
    'sex',
    'native-country'
)


# Load the training census dataset
with open('./census_data/adult.data', 'r') as train_data:
    raw_training_data = pd.read_csv(train_data, header=None, names=COLUMNS)

# Remove the column we are trying to predict ('income-level') from our features list
# Convert the Dataframe to a lists of lists
train_features = raw_training_data.drop('income-level', axis=1).as_matrix().tolist()
# Create our training labels list, convert the Dataframe to a lists of lists
train_labels = (raw_training_data['income-level'] == ' >50K').as_matrix().tolist()


# Load the test census dataset
with open('./census_data/adult.test', 'r') as test_data:
    raw_testing_data = pd.read_csv(test_data, names=COLUMNS, skiprows=1)
# Remove the column we are trying to predict ('income-level') from our features list
# Convert the Dataframe to a lists of lists
test_features = raw_testing_data.drop('income-level', axis=1).as_matrix().tolist()
# Create our training labels list, convert the Dataframe to a lists of lists
test_labels = (raw_testing_data['income-level'] == ' >50K.').as_matrix().tolist()


# Since the census data set has categorical features, we need to convert
# them to numerical values. We'll use a list of pipelines to convert each
# categorical column and then use FeatureUnion to combine them before calling
# the RandomForestClassifier.
categorical_pipelines = []

# Each categorical column needs to be extracted individually and converted to a numerical value.
# To do this, each categorical column will use a pipeline that extracts one feature column via
# SelectKBest(k=1) and a LabelBinarizer() to convert the categorical value to a numerical one.
# A scores array (created below) will select and extract the feature column. The scores array is
# created by iterating over the COLUMNS and checking if it is a CATEGORICAL_COLUMN.
for i, col in enumerate(COLUMNS[:-1]):
    if col in CATEGORICAL_COLUMNS:
        # Create a scores array to get the individual categorical column.
        # Example:
        #  data = [39, 'State-gov', 77516, 'Bachelors', 13, 'Never-married', 'Adm-clerical',
        #         'Not-in-family', 'White', 'Male', 2174, 0, 40, 'United-States']
        #  scores = [0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
        #
        # Returns: [['Sate-gov']]
        scores = []
        # Build the scores array
        for j in range(len(COLUMNS[:-1])):
            if i == j: # This column is the categorical column we want to extract.
                scores.append(1) # Set to 1 to select this column
            else: # Every other column should be ignored.
                scores.append(0)
        skb = SelectKBest(k=1)
        skb.scores_ = scores
        # Convert the categorical column to a numerical value
        lbn = LabelBinarizer()
        r = skb.transform(train_features)
        lbn.fit(r)
        # Create the pipeline to extract the categorical feature
        categorical_pipelines.append(
            ('categorical-{}'.format(i), Pipeline([
                ('SKB-{}'.format(i), skb),
                ('LBN-{}'.format(i), lbn)])))

# Create pipeline to extract the numerical features
skb = SelectKBest(k=6)
# From COLUMNS use the features that are numerical
skb.scores_ = [1, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1, 1, 0]
categorical_pipelines.append(('numerical', skb))

# Combine all the features using FeatureUnion
preprocess = FeatureUnion(categorical_pipelines)

# Create the classifier
classifier = RandomForestClassifier()

# Transform the features and fit them to the classifier
classifier.fit(preprocess.transform(train_features), train_labels)

# Create the overall model as a single pipeline
pipeline = Pipeline([
    ('union', preprocess),
    ('classifier', classifier)
])

Exportar o modelo

Para exportar o modelo, use joblib ou a biblioteca pickle do Python:

joblib

Observação: para exportar um artefato de modelo joblib compatível com o AI Platform Prediction, você precisa usar a versão de joblib, que é distribuída com o scikit-learn, e não a versão autônoma. Para importar essa biblioteca em Python, use a instrução from sklearn.externals import joblib.

from sklearn.externals import joblib

# Export the model to a file
joblib.dump(pipeline, 'model.joblib')

pickle

# Export the model to a file
with open('model.pkl', 'wb') as model_file:
  pickle.dump(pipeline, model_file)

Requisitos de nomenclatura do arquivo de modelo

O arquivo de modelo salvo enviado ao Cloud Storage precisa ser nomeado como model.pkl ou model.joblib, dependendo da biblioteca usada. Essa restrição garante que o AI Platform Prediction use o mesmo padrão de reconstrução do modelo na importação e na exportação.

Biblioteca usada para exportar o modelo	Nome correto do modelo
pickle	model.pkl
sklearn.externals.joblib	model.joblib

Para iterações futuras do seu modelo, organize seu bucket do Cloud Storage de modo que cada novo modelo tenha um diretório dedicado.

Armazenar o modelo no Cloud Storage

Para este tutorial, é mais fácil usar um intervalo dedicado do Cloud Storage no mesmo projeto que você está utilizando no AI Platform Prediction.

Se você estiver usando um bucket em outro projeto, garanta que sua conta de serviço do AI Platform Prediction tenha acesso ao modelo no Cloud Storage. Sem as permissões adequadas, a solicitação para criar uma versão de modelo do AI Platform Prediction falhará. Veja mais sobre como conceder permissões para armazenamento.

Configurar o bucket do Cloud Storage

Nesta seção, você aprende a criar um novo bucket. É possível usar um bucket atual, mas ele precisa estar na mesma região em que você planeja executar os jobs do AI Platform. Além disso, se ele não fizer parte do projeto que você usa para executar o AI Platform Prediction, é necessário conceder acesso explícito às contas de serviço do AI Platform Prediction.

1. Especifique um nome para o novo bucket. Ele precisa ser único em todos os buckets no Cloud Storage.

   BUCKET_NAME="YOUR_BUCKET_NAME"

   Por exemplo, use o nome do seu projeto com -aiplatform anexado:

   PROJECT_ID=$(gcloud config list project --format "value(core.project)")
   BUCKET_NAME=${PROJECT_ID}-aiplatform

2. Verifique o nome do bucket que você criou.

   echo $BUCKET_NAME

3. Selecione a região do bucket e defina a variável de ambiente REGION.

   Use a mesma região em que você planeja executar jobs do AI Platform Prediction. Consulte as regiões disponíveis para os serviços do AI Platform Prediction.

   Por exemplo, o código a seguir cria REGION e a define como us-central1:

   REGION=us-central1

4. Crie o novo bucket:

   gcloud storage buckets create gs://$BUCKET_NAME --location=$REGION

Fazer upload do arquivo de modelo exportado para o Cloud Storage

Execute o comando a seguir para fazer upload do seu arquivo de modelo salvo para o bucket do Cloud Storage:

gcloud storage cp ./model.joblib gs://your_bucket_name/model.joblib

Formatar dados para previsão

Antes de enviar uma solicitação de previsão on-line, você precisa formatar os dados de teste a fim de prepará-los para uso pelo serviço de previsão do AI Platform Prediction. Certifique-se de que o formato das suas instâncias de entrada corresponda ao do seu modelo.

Observação: para limpar os dados, coloque as strings entre aspas duplas (") em vez de aspas simples ('). Isso ajuda a evitar um erro de análise do JSON.

gcloud

Crie um arquivo input.json com cada instância de entrada em uma linha separada. O exemplo a seguir usa as primeiras dez instâncias de dados na lista test_features que foi definida nas etapas anteriores.

    [25, "Private", 226802, "11th", 7, "Never-married", "Machine-op-inspct", "Own-child", "Black", "Male", 0, 0, 40, "United-States"]
    [38, "Private", 89814, "HS-grad", 9, "Married-civ-spouse", "Farming-fishing", "Husband", "White", "Male", 0, 0, 50, "United-States"]
    [28, "Local-gov", 336951, "Assoc-acdm", 12, "Married-civ-spouse", "Protective-serv", "Husband", "White", "Male", 0, 0, 40, "United-States"]
    [44, "Private", 160323, "Some-college", 10, "Married-civ-spouse", "Machine-op-inspct", "Husband", "Black", "Male", 7688, 0, 40, "United-States"]
    [18, "?", 103497, "Some-college", 10, "Never-married", "?", "Own-child", "White", "Female", 0, 0, 30, "United-States"]
    [34, "Private", 198693, "10th", 6, "Never-married", "Other-service", "Not-in-family", "White", "Male", 0, 0, 30, "United-States"]
    [29, "?", 227026, "HS-grad", 9, "Never-married", "?", "Unmarried", "Black", "Male", 0, 0, 40, "United-States"]
    [63, "Self-emp-not-inc", 104626, "Prof-school", 15, "Married-civ-spouse", "Prof-specialty", "Husband", "White", "Male", 3103, 0, 32, "United-States"]
    [24, "Private", 369667, "Some-college", 10, "Never-married", "Other-service", "Unmarried", "White", "Female", 0, 0, 40, "United-States"]
    [55, "Private", 104996, "7th-8th", 4, "Married-civ-spouse", "Craft-repair", "Husband", "White", "Male", 0, 0, 10, "United-States"]

O formato das instâncias de entrada precisa ser compatível com o modelo. Neste exemplo, como o modelo do Censo requer 14 recursos, a entrada precisa ser uma matriz de forma (num_instances, 14).

API REST

Crie um arquivo input.json formatado com cada instância de entrada em uma linha separada. O exemplo a seguir usa as primeiras dez instâncias de dados na lista test_features que foi definida nas etapas anteriores.

{
  "instances": [

    [25, "Private", 226802, "11th", 7, "Never-married", "Machine-op-inspct", "Own-child", "Black", "Male", 0, 0, 40, "United-States"],
    [38, "Private", 89814, "HS-grad", 9, "Married-civ-spouse", "Farming-fishing", "Husband", "White", "Male", 0, 0, 50, "United-States"],
    [28, "Local-gov", 336951, "Assoc-acdm", 12, "Married-civ-spouse", "Protective-serv", "Husband", "White", "Male", 0, 0, 40, "United-States"],
    [44, "Private", 160323, "Some-college", 10, "Married-civ-spouse", "Machine-op-inspct", "Husband", "Black", "Male", 7688, 0, 40, "United-States"],
    [18, "?", 103497, "Some-college", 10, "Never-married", "?", "Own-child", "White", "Female", 0, 0, 30, "United-States"],
    [34, "Private", 198693, "10th", 6, "Never-married", "Other-service", "Not-in-family", "White", "Male", 0, 0, 30, "United-States"],
    [29, "?", 227026, "HS-grad", 9, "Never-married", "?", "Unmarried", "Black", "Male", 0, 0, 40, "United-States"],
    [63, "Self-emp-not-inc", 104626, "Prof-school", 15, "Married-civ-spouse", "Prof-specialty", "Husband", "White", "Male", 3103, 0, 32, "United-States"],
    [24, "Private", 369667, "Some-college", 10, "Never-married", "Other-service", "Unmarried", "White", "Female", 0, 0, 40, "United-States"],
    [55, "Private", 104996, "7th-8th", 4, "Married-civ-spouse", "Craft-repair", "Husband", "White", "Male", 0, 0, 10, "United-States"]
  ]
}

O formato das instâncias de entrada precisa ser compatível com o modelo. Neste exemplo, como o modelo Census requer 14 recursos, a entrada precisa ser uma matriz de forma (num_instances, 14).

Veja mais informações sobre como formatar a entrada para predição on-line.

Testar o modelo com predições locais

É possível usar o comando gcloud ai-platform local predict para testar como seu modelo exibe previsões antes de implantá-lo no AI Platform Prediction. O comando usa dependências em seu ambiente local para realizar a previsão e retorna resultados no mesmo formato que gcloud ai-platform predict usa ao realizar previsões on-line. Testar previsões localmente pode ser útil para detectar erros antes de gerar custos para solicitações de previsões on-line.

Para o argumento --model-dir, especifique um diretório que contenha seu modelo exportado de machine learning, na sua máquina local ou no Cloud Storage. Para o argumento --framework, especifique tensorflow, scikit-learn ou xgboost. Não é possível usar o comando gcloud ai-platform local predict com uma rotina de previsão personalizada.

Veja no exemplo abaixo como realizar uma previsão local:

gcloud ai-platform local predict --model-dir LOCAL_OR_CLOUD_STORAGE_PATH_TO_MODEL_DIRECTORY/ \
  --json-instances LOCAL_PATH_TO_PREDICTION_INPUT.JSON \
  --framework NAME_OF_FRAMEWORK

Implantar modelos e versões

O AI Platform Prediction organiza seus modelos treinados usando recursos de modelo e versão. Um modelo do AI Platform Prediction é um contêiner para as versões do seu modelo de machine learning.

Para implantar um modelo, crie no AI Platform Prediction um recurso e uma versão desse modelo. Depois, vincule essa versão ao arquivo de modelo armazenado no Cloud Storage.

Criar um recurso de modelo

O AI Platform Prediction usa recursos de modelo para organizar versões diferentes do seu modelo.

Decida agora se quer que as versões de modelo pertencentes a esse modelo usem um endpoint regional ou o endpoint global. Na maioria dos casos, escolha um endpoint regional. Se você precisar de funcionalidades disponíveis apenas nos tipos de máquina legados (MLS1), use o endpoint global.

Decida agora também se você quer que as versões de modelo pertencentes a ele exportem os registros ao exibirem previsões. Os exemplos a seguir não ativam a geração de registros. Saiba como ativar a geração de registros.

Console

1. Abra a página Modelos do AI Platform Prediction no console do Google Cloud:

   Acessar a página de modelos

2. Clique no botão Novo modelo, na parte superior da página Modelos. Você será direcionado para a página Criar modelo.

3. Insira um nome exclusivo para o modelo no campo Nome do modelo.

4. Quando a caixa de seleção Usar endpoint regional está marcada, o AI Platform Prediction usa um endpoint regional. Para usar o endpoint global, desmarque a caixa de seleção Usar endpoint regional.

5. Na lista suspensa Região, selecione um local para os nós de previsão. As regiões disponíveis diferem dependendo do uso de um endpoint regional ou global.

6. Clique em Criar.

7. Verifique se você voltou à página Modelos e se o novo modelo é exibido na lista.

gcloud

Endpoint regional

Execute este comando:

gcloud ai-platform models create MODEL_NAME \
  --region=REGION

Substitua:

• MODEL_NAME: um nome que você escolhe para o modelo.
• REGION: a região do endpoint regional em que você quer que os nós de previsão sejam executados. Precisa ser uma região compatível com os tipos de máquina N1 do Compute Engine.

Se você não especificar a sinalização --region, a gcloud CLI solicitará que você selecione um endpoint regional (ou use us-central no endpoint global).

Como alternativa, defina a propriedade ai_platform/region como uma região específica para garantir que a gcloud CLI sempre use o endpoint regional correspondente para AI Platform Prediction, mesmo quando você não especificar a sinalização --region. Essa configuração não se aplica a comandos no grupo de comandos gcloud ai-platform operations.

Endpoint global

Execute este comando:

gcloud ai-platform models create MODEL_NAME \
  --regions=REGION

Substitua:

• MODEL_NAME: um nome que você escolhe para o modelo.
• REGION: a região no endpoint global em que você quer que os nós de previsão sejam executados. Precisa ser uma região compatível com os tipos de máquina legada MLS1.

Se você não especificar a sinalização --regions, a gcloud CLI solicitará que você selecione um endpoint regional (ou use us-central1 no endpoint global).

API REST

Endpoint regional

1. Coloque o objeto de modelo no corpo da solicitação para formatá-la. No mínimo, especifique um nome para o modelo substituindo MODEL_NAME no exemplo a seguir:

   {
     "name": "MODEL_NAME"
   }
   

2. Faça uma chamada da API REST para o URL a seguir, substituindo PROJECT_ID pelo ID do projeto do Google Cloud:

   POST https://REGION-ml.googleapis.com/v1/projects/PROJECT_ID/models/
   

   Substitua:

   • REGION: a região do endpoint regional em que será implantado o modelo. Precisa ser uma região compatível com os tipos de máquina N1 do Compute Engine.

   • PROJECT_ID pelo ID do projeto no Google Cloud.

   Por exemplo, é possível fazer a solicitação a seguir usando o comando curl. Esse comando autoriza a solicitação usando as credenciais associadas à instalação da Google Cloud CLI.

   curl -X POST -H "Content-Type: application/json" \
     -d '{"name": "MODEL_NAME"}' \
     -H "Authorization: Bearer `gcloud auth print-access-token`" \
     "https://REGION-ml.googleapis.com/v1/projects/PROJECT_ID/models"
   

   A API retorna uma resposta semelhante a esta:

   {
     "name": "projects/PROJECT_ID/models/MODEL_NAME",
     "regions": [
       "REGION"
     ]
   }
   

Endpoint global

1. Coloque o objeto de modelo no corpo da solicitação para formatá-la. No mínimo, especifique um nome para o modelo substituindo MODEL_NAME na amostra a seguir. Além disso, especifique uma região substituindo REGION por uma região compatível com os tipos de máquina legada MLS1.:

   {
     "name": "MODEL_NAME",
     "regions": ["REGION"]
   }
   

2. Faça uma chamada da API REST para o URL a seguir, substituindo PROJECT_ID pelo ID do projeto do Google Cloud:

   POST https://ml.googleapis.com/v1/projects/PROJECT_ID/models/
   

   Por exemplo, é possível fazer a solicitação a seguir usando o comando curl. Esse comando autoriza a solicitação usando as credenciais associadas à instalação da Google Cloud CLI.

   curl -X POST -H "Content-Type: application/json" \
     -d '{"name": "MODEL_NAME", "regions": ["REGION"]}' \
     -H "Authorization: Bearer `gcloud auth print-access-token`" \
     "https://ml.googleapis.com/v1/projects/PROJECT_ID/models"
   

   A API retorna uma resposta semelhante a esta:

   {
     "name": "projects/PROJECT_ID/models/MODEL_NAME",
     "regions": [
       "REGION"
     ]
   }
   

Consulte a API de modelo do AI Platform Prediction para mais detalhes.

Criar uma versão de modelo

Agora está tudo pronto para criar uma versão com o modelo treinado enviado anteriormente para o Cloud Storage. Ao criar uma versão, você pode especificar vários parâmetros. A lista a seguir descreve parâmetros comuns, alguns dos quais são obrigatórios:

• name: precisa ser exclusivo no modelo do AI Platform Prediction.

• deploymentUri: o caminho para o diretório do modelo no Cloud Storage.

  • Caso você esteja implantando um modelo do TensorFlow, será o diretório do SavedModel.
  • Caso você esteja implantando um modelo scikit-learn ou XGBoost, este será o diretório que contém seu arquivo model.joblib, model.pkl ou model.bst.
  • Caso você esteja implantando uma rotina de previsão personalizada, será o diretório que contém todos os artefatos de modelo. O tamanho total desse diretório não pode ultrapassar 500 MB.

• framework: TENSORFLOW, SCIKIT_LEARN ou XGBOOST.

• runtimeVersion: uma versão do ambiente de execução com base nas dependências que o modelo precisa. Precisa ser 1.4, no mínimo, se você estiver implantando um modelo scikit-learn ou XGBoost. Se você planeja usar a versão do modelo para previsão em lote, use a versão 2.1 ou anterior do ambiente de execução.

• pythonVersion: precisa ser definida como “3.5” (para as versões de ambiente de execução 1.4 a 1.14) ou “3.7” (para as versões de ambiente de execução a partir de 1.15) para que seja compatível com os arquivos de modelo exportados usando o Python 3. Ele também pode ser definido como "2.7" quando usado com a versão de ambiente de execução até 1.15.

• machineType (opcional): o tipo de máquina virtual que o AI Platform Prediction usa para os nós que exibem previsões. Saiba mais sobre os tipos de máquinas. Se não estiver definido, o padrão será n1-standard-2 em endpoints regionais e mls1-c1-m2 no endpoint global.

  Se a versão do modelo usar um tipo de máquina do Compute Engine (N1) e menos de dois nós, ela será excluída do Contrato de nível de serviço (SLA, na sigla em inglês) do AI Platform Training e Prediction.

  Em outras palavras, se você usa um tipo de máquina do Compute Engine (N1), precisa definir manualScaling.nodes ou autoScaling.minNodes como 2 ou mais para que a versão do modelo seja coberta pelo SLA.

  Além disso, o uso do escalonamento automático com GPUs está disponível na visualização. Portanto, as versões de modelo que usam escalonamento automático com GPUs não são cobertas pelo SLA.

Veja mais informações sobre cada um desses parâmetros, bem como outros parâmetros menos comuns, na referência da API para o recurso de versão.

Além disso, se você tiver criado o modelo em um endpoint regional, crie também a versão no mesmo endpoint regional.

Console

1. Abra a página Modelos do AI Platform Prediction no console do Google Cloud:

   Acessar a página de modelos

2. Na página Modelos, selecione o nome do recurso do modelo que quiser usar para criar a versão. Você será direcionado para a página Detalhes do modelo.

3. Clique no botão Nova versão, na parte superior da página Detalhes do modelo. Você será direcionado para a página Criar versão.

4. Digite o nome da versão no campo Nome. Se quiser, insira uma descrição para a versão no campo Descrição.

5. Digite as seguintes informações sobre o treinamento do modelo nas caixas suspensas correspondentes:

   • Selecione a versão do Python usada para treinar o modelo.
   • Selecione o framework e a versão dele.
   • Selecione a Versão do ambiente de execução de ML. Saiba mais sobre as versões de ambiente de execução do AI Platform Prediction.

6. Se quiser, selecione um tipo de máquina para executar a previsão on-line.

7. No campo URI do modelo, insira o local do bucket do Cloud Storage em que você fez o upload do arquivo de modelo. Use o botão Procurar para encontrar o caminho correto.

   Especifique o caminho para o diretório em que está o arquivo, não o caminho para o arquivo do modelo em si. Por exemplo, use gs://your_bucket_name/model-dir/ em vez de gs://your_bucket_name/model-dir/saved_model.pb ou gs://your_bucket_name/model-dir/model.pkl.

8. Selecione uma opção de escalonamento para implantação de previsão on-line:

   • Se você selecionar "Escalonamento automático", o campo opcional Número mínimo de nós será exibido. Insira o número mínimo de nós a serem mantidos sempre em execução quando o serviço for reduzido.

   • Se você selecionar "Escalonamento manual", digite o número de nós que quer manter em execução.

   Saiba como as opções de escalonamento variam de acordo com o tipo de máquina.

   Saiba mais sobre os custos de previsão.

9. Clique em Salvar para criar a versão do modelo.

gcloud

1. Defina variáveis de ambiente para armazenar o caminho do diretório do Cloud Storage em que o binário do modelo está localizado, o nome do modelo, o nome da versão e a opção de framework.

   Ao criar uma versão com a gcloud CLI, é possível inserir o nome do framework em letras maiúsculas com sublinhados (por exemplo, SCIKIT_LEARN) ou em letras minúsculas com hífens (por exemplo, scikit-learn). Ambas as opções produzem um comportamento idêntico.

   Substitua [VALUES_IN_BRACKETS] pelos valores apropriados:

   MODEL_DIR="gs://your_bucket_name/"
   VERSION_NAME="[YOUR-VERSION-NAME]"
   MODEL_NAME="[YOUR-MODEL-NAME]"
   FRAMEWORK="[YOUR-FRAMEWORK_NAME]"
   

2. Crie a versão:

   gcloud ai-platform versions create $VERSION_NAME \
     --model=$MODEL_NAME \
     --origin=$MODEL_DIR \
     --runtime-version=2.11 \
     --framework=$FRAMEWORK \
     --python-version=3.7 \
     --region=REGION \
     --machine-type=MACHINE_TYPE
   

   Substitua:

   • REGION: a região do endpoint regional em que você criou o modelo. Se você criou o modelo no endpoint global, omita a sinalização --region.

   • MACHINE_TYPE: um tipo de máquina que determina os recursos de computação disponíveis para os nós de previsão.

   A criação da versão leva alguns minutos. Quando ela estiver pronta, você verá a resposta abaixo:

   Creating version (this might take a few minutes)......done.

3. Veja informações sobre a nova versão:

   gcloud ai-platform versions describe $VERSION_NAME \
     --model=$MODEL_NAME
   

   A resposta será parecida com esta:

   createTime: '2018-02-28T16:30:45Z'
   deploymentUri: gs://your_bucket_name
   framework: [YOUR-FRAMEWORK-NAME]
   machineType: mls1-c1-m2
   name: projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions/[YOUR-VERSION-NAME]
   pythonVersion: '3.7'
   runtimeVersion: '2.11'
   state: READY

API REST

1. Formate o corpo da solicitação para conter o objeto da versão. Neste exemplo, são especificadas as versões name, deploymentUri, runtimeVersion, framework e machineType. Substitua [VALUES_IN_BRACKETS] pelos valores apropriados:

   {
     "name": "[YOUR-VERSION-NAME]",
     "deploymentUri": "gs://your_bucket_name/",
     "runtimeVersion": "2.11",
     "framework": "[YOUR_FRAMEWORK_NAME]",
     "pythonVersion": "3.7",
     "machineType": "[YOUR_MACHINE_TYPE]"
   }
   

2. Envie a chamada da API REST para o caminho a seguir, substituindo os [VALUES_IN_BRACKETS] pelos valores apropriados:

   POST https://REGION-ml.googleapis.com/v1/projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions
   

   Substitua REGION pela região do endpoint regional em que você criou seu modelo. Se você criou seu modelo no endpoint global, use ml.googleapis.com.

   Por exemplo, é possível fazer a solicitação a seguir usando o comando curl:

   curl -X POST -H "Content-Type: application/json" \
     -d '{"name": "[YOUR-VERSION-NAME]", "deploymentUri": "gs://your_bucket_name/", "runtimeVersion": "2.11", "framework": "[YOUR_FRAMEWORK_NAME]", "pythonVersion": "3.7", "machineType": "[YOUR_MACHINE_TYPE]"}' \
     -H "Authorization: Bearer `gcloud auth print-access-token`" \
     "https://REGION-ml.googleapis.com/v1/projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions"
   

   A criação da versão leva alguns minutos. Quando ela estiver pronta, você verá uma resposta parecida com esta:

   {
     "name": "projects/[YOUR-PROJECT-ID]/operations/create_[YOUR-MODEL-NAME]_[YOUR-VERSION-NAME]-[TIMESTAMP]",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.ml.v1.OperationMetadata",
       "createTime": "2018-07-07T02:51:50Z",
       "operationType": "CREATE_VERSION",
       "modelName": "projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]",
       "version": {
         "name": "projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions/[YOUR-VERSION-NAME]",
         "deploymentUri": "gs://your_bucket_name",
         "createTime": "2018-07-07T02:51:49Z",
         "runtimeVersion": "2.11",
         "framework": "[YOUR_FRAMEWORK_NAME]",
         "machineType": "[YOUR_MACHINE_TYPE]",
         "pythonVersion": "3.7"
       }
     }
   }
   

Enviar solicitação de previsão on-line

Depois de criar uma versão, o AI Platform Prediction iniciará um novo servidor pronto para exibir as solicitações de previsão.

Nesta seção, demonstramos o seguinte:

1. Como testar seu modelo com a gcloud enviando solicitações para conjuntos de dados menores.
2. Como enviar solicitações maiores para o conjunto de dados de teste completo usando a biblioteca de cliente do Python e ver os 10 primeiros resultados.

gcloud

Nesta seção, explicamos como enviar uma solicitação de previsão usando o arquivo input.json criado em uma etapa anterior.

Observação: se você quiser enviar uma solicitação para todo o conjunto de dados de teste, lembre-se de que a quantidade máxima de dados que pode ser enviada em uma solicitação é de 1,5 MB. Como o tamanho do conjunto de dados de teste do Censo excede esse limite, é preciso dividi-lo pela metade e enviar duas solicitações.

1. Defina variáveis de ambiente para os nomes do modelo, da versão e do arquivo de entrada. Substitua os [VALUES_IN_BRACKETS] pelos valores apropriados:

   MODEL_NAME="[YOUR-MODEL-NAME]"
   VERSION_NAME="[YOUR-VERSION-NAME]"
   INPUT_FILE="input.json"
   

2. Envie a solicitação de previsão:

   gcloud ai-platform predict --model $MODEL_NAME --version \
     $VERSION_NAME --json-instances $INPUT_FILE
   

   Os resultados da previsão retornam True quando a renda da pessoa é superior a US$ 50.000 por ano e False quando é inferior a esse valor. Por exemplo, os primeiros 10 resultados serão semelhantes a:

   [False, False, False, True, False, False, False, False, False, False]
   

API REST

Nesta seção, você verá como enviar uma solicitação de previsão usando o arquivo input.json criado na etapa anterior.

Observação: se você quiser enviar uma solicitação para todo o conjunto de dados de teste, lembre-se de que a quantidade máxima de dados que pode ser enviada em uma solicitação é de 1,5 MB. Como o tamanho do conjunto de dados de teste do Censo excede esse limite, é preciso dividi-lo pela metade e enviar duas solicitações.

Envie as solicitações de previsão:

curl -X POST -H "Content-Type: application/json" -d @input.json \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
"https://ml.googleapis.com/v1/projects/${PROJECT_ID}/models/${MODEL_NAME}/versions/${VERSION_NAME}:predict"

Os resultados da previsão retornam True quando a renda da pessoa é superior a US$ 50.000 por ano e False quando é inferior a esse valor. Esses resultados são exibidos no console como uma lista de valores booleanos. Por exemplo, os primeiros 10 resultados serão semelhantes a:

{"predictions": [false, false, false, true, false, false, false, false, false, false]}

Python

Neste exemplo, usamos a biblioteca de cliente do Python para enviar solicitações de predição para todo o conjunto de dados do Censo e imprimimos os primeiros 10 resultados. Veja mais informações sobre como usar a biblioteca de cliente Python.

Observação: a quantidade máxima de dados que pode ser enviada em uma única solicitação é de 1,5 MB. Como o tamanho do conjunto de dados de teste do Censo excede esse limite, ele é dividido pela metade neste exemplo, e duas solicitações são enviadas.

Substitua [VALUES_IN_BRACKETS] pelos valores apropriados:

import googleapiclient.discovery

# Fill in your PROJECT_ID, VERSION_NAME and MODEL_NAME before running
# this code.

PROJECT_ID = [YOUR PROJECT_ID HERE]
VERSION_NAME = [YOUR VERSION_NAME HERE]
MODEL_NAME = [YOUR MODEL_NAME HERE]

service = googleapiclient.discovery.build('ml', 'v1')
name = 'projects/{}/models/{}'.format(PROJECT_ID, MODEL_NAME)
name += '/versions/{}'.format(VERSION_NAME)

# Due to the size of the data, it needs to be split in 2
first_half = test_features[:int(len(test_features)/2)]
second_half = test_features[int(len(test_features)/2):]

complete_results = []
for data in [first_half, second_half]:
    responses = service.projects().predict(
        name=name,
        body={'instances': data}
    ).execute()

    if 'error' in responses:
        print(response['error'])
    else:
        complete_results.extend(responses['predictions'])

# Print the first 10 responses
for i, response in enumerate(complete_results[:10]):
    print('Prediction: {}\tLabel: {}'.format(response, test_labels[i]))

Os resultados da previsão retornam True quando a renda da pessoa é superior a US$ 50.000 por ano e False quando é inferior a esse valor. Por exemplo, os primeiros 10 resultados serão semelhantes a:

Prediction: False Label: False
Prediction: False Label: False
Prediction: True  Label: True
Prediction: True  Label: True
Prediction: False Label: False
Prediction: False Label: False
Prediction: False Label: False
Prediction: True  Label: True
Prediction: False Label: False
Prediction: False Label: False

Veja mais informações sobre cada parâmetro de entrada nos detalhes da solicitação de previsão da API AI Platform Prediction.

Sobre os dados

O conjunto de dados de renda do censo usado para treinamento nesta amostra está hospedado no Repositório de machine learning da UC Irvine (links em inglês).

Dados do Censo por cortesia de: Lichman, M. (2013). Repositório de machine learning da UCI http://archive.ics.uci.edu/ml (em inglês). Irvine, CA: University of California, School of Information and Computer Science. Este conjunto de dados está disponível publicamente para qualquer pessoa usar de acordo com a os seguintes termos fornecidos pela fonte do conjunto de dados: http://archive.ics.uci.edu/ml - e é fornecido "NO ESTADO EM QUE SE ENCONTRA" sem garantia, expressa ou implícita, do Google. O Google isenta-se de qualquer responsabilidade por eventuais danos, diretos ou indiretos, decorrentes do uso do conjunto de dados.

A seguir

• Teste este tutorial como um notebook do Jupyter no GitHub.
• Veja mais notebooks de amostra do scikit-learn no GitHub.