Esta versão legada do AI Platform Prediction está descontinuada e não estará mais disponível no Google Cloud após 31 de janeiro de 2025. Todos os modelos, metadados associados e implantações serão excluídos após 31 de janeiro de 2025. Migre seus recursos para a Vertex AI a fim de acessar novos recursos de machine learning que estão indisponíveis no AI Platform.

Esta página foi traduzida pela API Cloud Translation.

Como implantar modelos

Nesta página, explicamos como implantar seu modelo no AI Platform Prediction para receber previsões.

Para implantar seu modelo treinado no AI Platform Prediction, você precisa:

fazer upload do modelo salvo em um bucket do Cloud Storage;
criar um recurso de modelo do AI Platform Prediction;
criar um recurso de versão do AI Platform Prediction, especificando o caminho do Cloud Storage para seu modelo salvo.

Antes de começar

Treine seu modelo de machine learning e siga o guia de exportação de modelos para predição para criar artefatos de modelo implantáveis no AI Platform Prediction.

Armazenar o modelo no Cloud Storage

Geralmente, é mais fácil usar um bucket dedicado do Cloud Storage no mesmo projeto que você está usando para o 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.

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
```
Verifique o nome do bucket que você criou.
```
echo $BUCKET_NAME
```
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
```

Crie o novo intervalo:

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

Fazer o upload do modelo exportado para o Cloud Storage

Os exemplos a seguir mostram como fazer o upload de diferentes tipos de artefatos de modelo para um diretório no Cloud Storage:

TensorFlow SavedModel

SAVED_MODEL_DIR=$(ls ./YOUR_EXPORT_DIR_BASE | tail -1)
gcloud storage cp $SAVED_MODEL_DIR gs://YOUR_BUCKET --recursive

Ao exportar um SavedModel de tf.keras ou de um Estimator do TensorFlow, ele é salvo como um subdiretório com carimbo de data/hora de um diretório de exportação base escolhido. Por exemplo, YOUR_EXPORT_DIR_BASE/1487877383942. Neste exemplo, é possível ver como fazer o upload do diretório com o carimbo de data/hora mais recente. Se você criou o SavedModel de outra forma, ele pode estar em um local diferente no sistema de arquivos local.

Arquivo de modelo scikit-learn ou XGBoost

Dependendo de como você exportou o modelo treinado, faça upload do arquivo model.joblib, model.pkl ou model.bst.

Veja no exemplo abaixo como fazer o upload de um arquivo exportado pelo sklearn.externals.joblib.

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

Veja no exemplo abaixo como fazer o upload de um arquivo exportado pelo módulo pickle do Python:

gcloud storage cp ./model.pkl gs://YOUR_BUCKET/model.pkl

O exemplo a seguir mostra como fazer upload de um arquivo exportado pelo método save_model de xgboost.Booster:

gcloud storage cp ./model.bst gs://YOUR_BUCKET/model.bst

Se você estiver implantando uma rotina de previsão personalizada (Beta), faça também o upload de qualquer outro artefato de modelo para o diretório de modelos.

O tamanho total do arquivo do diretório do modelo precisa ser 500 MB ou menos se você usar um tipo de máquina legada MLS1 ou 10 GB ou menos se você usar um tipo de máquina N1 do Compute Engine. Saiba mais sobre tipos de máquinas para previsão on-line.

Ao criar versões posteriores do modelo, coloque cada uma em um diretório separado no bucket do Cloud Storage.

Fazer upload de código personalizado

Caso você esteja implantando um pipeline scikit-learn com código personalizado ou uma rotina de previsão personalizada, faça também o upload do pacote de distribuição de origem que contém o código personalizado. Exemplo:

gcloud storage cp dist/my_custom_code-0.1.tar.gz gs://YOUR_BUCKET/my_custom_code-0.1.tar.gz

É possível, mas não necessário, fazer upload desse tarball para o mesmo diretório no Cloud Storage como o seu arquivo de modelo. Na verdade, é mais organizado mantê-los separados, especialmente se implantar muitas versões do modelo e do código.

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

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

Acessar a página de modelos
Clique no botão Novo modelo, na parte superior da página Modelos. Você será direcionado para a página Criar modelo.
Insira um nome exclusivo para o modelo no campo Nome do modelo.
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.
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.
Clique em Criar.
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

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"
}
```
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

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"]
}
```

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. Omita esse parâmetro se você estiver implantando uma rotina de previsão personalizada.
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, um modelo XGBoost ou uma rotina de previsão personalizada. 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.
packageUris (opcional): uma lista de caminhos para seus pacotes de distribuição de código personalizados (arquivos .tar.gz) no Cloud Storage. Forneça este parâmetro somente se estiver implantando um pipeline scikit-learn com código personalizado ou uma rotina de previsão personalizada (ambos em versão Beta).
predictionClass (opcional): o nome da sua classe Predictor no formato module_name.class_name. Forneça este parâmetro somente se estiver implantando uma rotina de previsão personalizada (Beta).
serviceAccount (opcional): é possível especificar uma conta de serviço para sua versão de modelo se ela acessa os recursos do Google Cloud enquanto exibe as previsões. Saiba mais sobre como especificar uma conta de serviço. Forneça esse parâmetro somente se você estiver usando um contêiner personalizado ou uma rotina de previsão personalizada.
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

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

Acessar a página de modelos
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.
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.
Digite o nome da versão no campo Nome. Se quiser, insira uma descrição para a versão no campo Descrição.
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 do framework. Se você estiver implantando uma rotina de previsão personalizada (Beta), selecione "Rotina de previsão personalizada (BETA)" em Framework.
- 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.
Se quiser, selecione um tipo de máquina para executar a previsão on-line.
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.
Caso você esteja implantando um pipeline scikit-learn com código personalizado ou uma rotina de previsão personalizada (ambos em versão Beta), informe o caminho do Cloud Storage para todos os pacotes de código personalizado (.tar.gz) em Dependências e códigos personalizados. Se você estiver implantando uma rotina de previsão personalizada, insira o nome da sua classe do Predictor no campo Classe da predição.
Selecione uma opção de Dimensionamento para implantação de predições 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.
Clique em Salvar para criar a versão do modelo.

gcloud

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]"
```
No caso do pipeline scikit-learn com código personalizado (Beta), defina uma outra variável com o caminho para o tarball de código personalizado:
```
MODEL_DIR="gs://your_bucket_name/"
VERSION_NAME="[YOUR-VERSION-NAME]"
MODEL_NAME="[YOUR-MODEL-NAME]"
FRAMEWORK="scikit-learn"
CUSTOM_CODE_PATH="gs://your_bucket_name/my_custom_code-0.1.tar.gz"
```
No caso da rotina de previsão personalizada (Beta), omita a variável FRAMEWORK e defina outras com o caminho para o tarball de código personalizado e o nome da classe do preditor:
```
MODEL_DIR="gs://your_bucket_name/"
VERSION_NAME="[YOUR-VERSION-NAME]"
MODEL_NAME="[YOUR-MODEL-NAME]"
CUSTOM_CODE_PATH="gs://your_bucket_name/my_custom_code-0.1.tar.gz"
PREDICTOR_CLASS="[MODULE_NAME].[CLASS_NAME]"
```

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.

No caso do pipeline scikit-learn com código personalizado (Beta), use o componente gcloud beta e confirme se a sinalização --package-uris está configurada. Para implantar código personalizado, seu modelo precisa usar o endpoint global.

gcloud components install beta

gcloud beta ai-platform versions create $VERSION_NAME \
  --model=$MODEL_NAME \
  --origin=$MODEL_DIR \
  --runtime-version=2.11 \
  --framework=$FRAMEWORK \
  --python-version=3.7 \
  --machine-type=mls1-c1-m2 \
  --package-uris=$CUSTOM_CODE_PATH

No caso da rotina de previsão personalizada (Beta), use o componente gcloud beta, omita a sinalização --framework e configure as sinalizações --package-uris e --prediction-class. Para implantar código personalizado, seu modelo precisa usar o endpoint global.

gcloud components install beta

gcloud beta ai-platform versions create $VERSION_NAME \
  --model=$MODEL_NAME \
  --origin=$MODEL_DIR \
  --runtime-version=2.11 \
  --python-version=3.7 \
  --machine-type=mls1-c1-m2 \
  --package-uris=$CUSTOM_CODE_PATH \
  --prediction-class=$PREDICTOR_CLASS

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.

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

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]"
}

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"
    }
  }
}