Como implantar modelos

Nesta página, você verá como implantar o modelo no AI Platform para receber predições.

Para implantar o modelo treinado no AI Platform, é preciso:

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

Antes de começar

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

Armazenar o modelo no Cloud Storage

Geralmente, é mais fácil usar um intervalo dedicado do Cloud Storage no mesmo projeto que o AI Platform.

Se usar um intervalo em um projeto diferente, verifique se a conta de serviço do AI Platform tem acesso ao modelo no Cloud Storage. Sem as permissões apropriadas, a solicitação para criar uma versão do modelo do AI Platform falhará. Veja mais sobre a concessão de permissões para armazenamento.

Configurar o intervalo do Cloud Storage

Nesta seção, você aprende a criar um novo intervalo. É possível usar um intervalo 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ê está usando para executar o AI Platform, será preciso conceder acesso às contas de serviço do AI Platform.

  1. Dê um nome ao intervalo novo. Ele precisa ser único em todos os intervalos no Cloud Storage.

    BUCKET_NAME="your_bucket_name"

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

    PROJECT_ID=$(gcloud config list project --format "value(core.project)")
    BUCKET_NAME=${PROJECT_ID}-mlengine
  2. Verifique o nome do intervalo que você criou.

    echo $BUCKET_NAME
  3. Selecione uma região do intervalo e configure uma variável de ambiente REGION.

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

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

    REGION=us-central1
  4. Crie o novo intervalo:

    gsutil mb -l $REGION gs://$BUCKET_NAME

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)
gsutil cp -r $SAVED_MODEL_DIR gs://your-bucket

Ao exportar um SavedModel a partir de tf.kerasou 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.

gsutil 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:

gsutil 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:

gsutil 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 2 GB ou menos se você usa um tipo de máquina do Compute Engine (N1) (Beta). 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 intervalo 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:

gsutil 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 previsõ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 incorrer em custos para solicitações de previsões on-line.

No argumento --model-dir, especifique um diretório que contenha o modelo de machine learning exportado, que pode ser 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 organiza seus modelos treinados usando recursos de modelo e versão. Um modelo é um contêiner das versões do seu modelo de machine learning.

Para implantar um modelo, é preciso criar um recurso de modelo no AI Platform, gerar uma versão dele e vincular essa versão ao arquivo de modelo armazenado no Cloud Storage.

Criar um recurso de modelo

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

Console

  1. Abra a página de modelos do AI Platform no Console do GCP:

    Abrir modelos no Console do GCP

  2. Se necessário, crie o modelo a que a nova versão será adicionada:

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

    2. Digite um nome exclusivo para o modelo na caixa Nome do modelo. Se quiser, insira uma descrição para o modelo no campo Descrição.

    3. Clique em Criar.

    4. Verifique se você retornou para a página Modelos e se o modelo novo aparece na lista.

gcloud

Crie um recurso para suas versões de modelo inserindo o nome dele sem os colchetes:

gcloud ai-platform models create "[YOUR-MODEL-NAME]"

API REST

  1. Coloque o objeto de modelo no corpo da solicitação para formatá-la. É preciso especificar pelo menos um nome para seu modelo. Insira o nome do modelo sem os colchetes:

    {"name": "[YOUR-MODEL-NAME]"}
    
  2. Envie a chamada da API REST para o caminho a seguir, substituindo [VALUES_IN_BRACKETS] pelos valores apropriados:

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

    Por exemplo, é possível fazer a seguinte solicitação usando cURL:

    curl -X POST -H "Content-Type: application/json" \
      -d '{"name": "[YOUR-MODEL-NAME]"}' \
      -H "Authorization: Bearer `gcloud auth print-access-token`" \
      "https://ml.googleapis.com/v1/projects/[YOUR-PROJECT-ID]/models"
    

    A resposta será parecida com esta:

    {
      "name": "projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]",
      "regions": [
        "us-central1"
      ]
    }
    

Veja o artigo API modelo do AI Platform 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, especifique os seguintes parâmetros:

  • name: precisa ser exclusivo no modelo do AI Platform.
  • deploymentUri: o caminho para o diretório do modelo no Cloud Storage.

    • Caso você esteja implantando um modelo do TensorFlow, este 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, este 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 seu modelo precisa. Se você estiver implantando um modelo scikit-learn, um modelo XGBoost ou uma rotina de previsão personalizada, ele precisa ser 1.4 no mínimo.

  • 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): se quiser, especifique uma conta de serviço a ser usada pela versão do modelo para acessar os recursos do GCP ao exibir previsões. Saiba mais sobre como especificar uma conta de serviço. Forneça este parâmetro somente se estiver implantando uma rotina de previsão personalizada (Beta).

  • pythonVersion: precisa ser definido como "3.5" para ser compatível com arquivos de modelo exportados com o Python 3. Se não for definido, o valor padrão será "2.7".

  • 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 tipos de máquinas. Se não for definido, o padrão será mls1-c1-m2.

Veja mais informações sobre cada um desses parâmetros no artigo API AI Platform Training and Prediction para um recurso de versão.

Veja os detalhes completos de cada versão do ambiente de execução.

Console

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

    Abrir modelos no Console do GCP

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

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

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

  5. Se quiser, selecione um tipo de máquina para executar a previsão on-line. O padrão deste campo é "CPU de núcleo único".

  6. No campo URI do modelo, insira o local do intervalo 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.

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

  8. Selecione uma opção de dimensionamento para implantação de previsão online:

    • 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. O padrão desse campo é 0.

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

      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 ferramenta gcloud, é possível fornecer o nome do framework em letras maiúsculas com sublinhados (por exemplo, SCIKIT_LEARN) ou em letras minúsculas com hifens (por exemplo, scikit-learn). Ambas as opções levam a 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 Predictor:

    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]"
    
  2. Crie a versão:

    gcloud ai-platform versions create $VERSION_NAME \
      --model $MODEL_NAME \
      --origin $MODEL_DIR \
      --runtime-version=1.14 \
      --framework $FRAMEWORK \
      --python-version=3.5
    

    No caso do pipeline scikit-learn com código personalizado (Beta), use o componente gcloud beta e certifique-se de que a sinalização --package-uris está configurada:

    gcloud components install beta
    
    gcloud beta ai-platform versions create $VERSION_NAME \
      --model $MODEL_NAME \
      --origin $MODEL_DIR \
      --runtime-version=1.14 \
      --framework $FRAMEWORK \
      --python-version=3.5
      --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:

    gcloud components install beta
    
    gcloud beta ai-platform versions create $VERSION_NAME \
      --model $MODEL_NAME \
      --origin $MODEL_DIR \
      --runtime-version=1.14 \
      --python-version=3.5
      --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.

  3. Busque 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.5'
    runtimeVersion: '1.14'
    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 e framework. Substitua [VALUES_IN_BRACKETS] pelos valores apropriados:

      {
        "name": "[YOUR-VERSION-NAME]",
        "deploymentUri": "gs://your_bucket_name/"
        "runtimeVersion": "1.14"
        "framework": "[YOUR_FRAMEWORK_NAME]"
        "pythonVersion": "3.5"
      }
    
  2. Envie a chamada da API REST para o caminho a seguir, substituindo [VALUES_IN_BRACKETS] pelos valores apropriados:

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

    Por exemplo, é possível fazer a seguinte solicitação usando cURL:

        curl -X POST -H "Content-Type: application/json" \
          -d '{"name": "[YOUR-VERSION-NAME]", "deploymentUri": "gs://your_bucket_name/", "runtimeVersion": "1.14", "framework": "[YOUR_FRAMEWORK_NAME]", "pythonVersion": "3.5"}' \
          -H "Authorization: Bearer `gcloud auth print-access-token`" \
          "https://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": "1.14",
            "framework": "[YOUR_FRAMEWORK_NAME]",
            "machineType": "mls1-c1-m2",
            "pythonVersion": "3.5"
          }
        }
      }
    

Especificar uma conta de serviço para a versão do modelo

Por padrão, quando uma versão de modelo é implantada, ela recebe as mesmas permissões de uma conta de serviço gerenciada pelo Google com o papel de IAM Agente de serviço do Cloud ML. Essa conta de serviço padrão é suficiente para a maioria dos casos de uso. Por exemplo, ela pode fazer leituras em intervalos do Cloud Storage no mesmo projeto do Google Cloud Platform.

No entanto, se você estiver implantando uma rotina de previsão personalizada e precisar que a versão do modelo tenha um conjunto de permissões diferente, especifique a conta de serviço a ser usada. Por exemplo, se a versão do modelo precisar acessar um intervalo do Cloud Storage de outro projeto do GCP durante a previsão, especifique uma conta de serviço com permissão para fazer leituras nesse intervalo.

  1. Crie ou selecione uma conta de serviço para a versão do modelo. O usuário que está implantando a versão do modelo precisa ter o papel de criador do token da conta de serviço para essa conta de serviço.

  2. Especifique o nome da conta de serviço no campo serviceAccount quando você criar a versão do modelo. Se você implantar seu modelo usando a ferramenta gcloud, será possível usar a sinalização --service-account, como no exemplo a seguir:

    gcloud components install beta
    
    gcloud beta ai-platform versions create your-version-name \
      --service-account your-service-account-name@your-project-id.iam.gserviceaccount.com
      ...
    

A seguir