Como receber previsões on-line

O serviço de previsão on-line do AI Platform Prediction é otimizado para submeter seus dados a modelos hospedados com a menor latência possível. Você envia pequenos lotes de dados para o serviço e ele retorna as previsões na resposta.

Veja uma comparação entre a previsão on-line e em lote ou leia a visão geral sobre os conceitos de previsão.

Antes de começar

Antes de solicitar predições:

Regiões

A previsão on-line está disponível em determinadas regiões. Além disso, há tipos de máquina diferentes disponíveis em cada região. Para saber mais sobre a disponibilidade da previsão on-line em cada região, leia o guia para regiões.

Como criar modelos e versões

Você precisa tomar as seguintes decisões importantes sobre como executar a previsão on-line ao criar os recursos do modelo e da versão:

Recurso criado Decisão especificada na criação do recurso
Modelo Região em que as previsões serão feitas
Modelo Ativar os registros de previsão on-line
Versão Versão do ambiente de execução que será usada
Versão Versão do Python que será usada
Versão Tipo de máquina que será usada para previsões on-line

Não é possível atualizar as configurações listadas acima após a criação inicial de modelo e versão. Se você precisar alterar essas configurações, crie um novo modelo ou recurso de versão com as novas configurações e implemente novamente seu modelo.

Tipos de máquina disponíveis para previsão on-line

Ao criar uma versão, escolha o tipo de máquina virtual que o AI Platform Prediction usará para os nós de previsão on-line. Saiba mais sobre os tipos de máquinas.

Como pedir registros para solicitações de previsão on-line

Por padrão, o serviço de previsão do AI Platform Prediction não fornece informações registradas sobre solicitações, porque esses registros geram custos. A previsão on-line com uma alta taxa de consultas por segundo (QPS) pode produzir um número significativo de registros, que estão sujeitos aos preços do Cloud Logging ou aos preços do BigQuery.

Para ativar a geração de registros de previsão on-line, configure-a ao criar um recurso de modelo ou ao criar um recurso de versão de modelo, dependendo do tipo de geração de registros que você quer ativar. Há três tipos de geração de registros que podem ser ativados de maneira independente:

  • Geração de registros de acesso, que registra informações como carimbo de data/hora e latência para cada solicitação ao Cloud Logging.

    Ative-a ao criar um recurso de modelo.

  • Geração de registros do console, que registra os streams stderr e stdout dos nós de previsão no Cloud Logging e pode ser útil para depuração. Esse tipo de geração de registros está na visualização dos tipos de máquina N1 do Compute Engine e costuma estar disponível para os tipos de máquina legados (MLS1).

    Ative-a ao criar um recurso de modelo.

  • Geração de registros de solicitação-resposta, que registra uma amostra das solicitações e respostas de previsão on-line para uma tabela do BigQuery. Esse tipo de geração de registros está na versão Beta.

    Para ativar a geração de registros de solicitação/resposta, crie um recurso de versão de modelo e atualize-a.

gcloud

Para ativar a geração de registros de acesso, inclua a sinalização --enable-logging ao criar seu modelo com o comando gcloud ai-platform models create. Exemplo:

gcloud ai-platform models create MODEL_NAME \
  --region=us-central1 \
  --enable-logging

Para ativar a geração de registros do console (visualização), use o componente gcloud beta e inclua a sinalização --enable-console-logging. Exemplo:

gcloud components install beta

gcloud beta ai-platform models create MODEL_NAME \
  --region=us-central1 \
  --enable-console-logging

No momento, não é possível ativar a geração de registros de solicitação-resposta (Beta) usando a CLI gcloud. Apenas é possível ativar esse tipo de geração de registros quando você envia uma solicitação projects.models.versions.patch à API REST.

API REST

Para ativar a geração de registros de acesso, defina onlinePredictionLogging como True no recurso Modelo ao criar seu modelo com projects.models.create.

Para ativar a geração de registros do console (Beta), defina o campo onlinePredictionConsoleLogging como True no recurso Modelo.

Geração de registros de solicitação/resposta

Ao contrário dos outros tipos, não é possível ativar a geração de registros de solicitação-resposta ao criar um modelo. Em vez disso, avive-a usando o método projects.models.versions.patch em uma versão do modelo que já existe. Primeiro, crie a versão do modelo usando o console do Google Cloud, a CLI gcloud ou a API REST.

Para ativar a geração de registros de solicitação-resposta, preencha o campo requestLoggingConfig do recurso Versão com as seguintes entradas:

  • samplingPercentage: um número entre 0 ou 1 que define a fração de solicitações a serem registradas. Por exemplo, defina esse valor como 1 para registrar todas as solicitações ou como 0.1 para registrar 10% das solicitações.

  • bigqueryTableName: o nome totalmente qualificado (PROJECT_ID.DATASET_NAME.TABLE_NAME) da tabela do BigQuery onde você quer registrar solicitações e respostas. A tabela já precisa existir com o seguinte esquema:

    Nome do campoTipoModo
    modelSTRINGREQUIRED
    model_versionSTRINGREQUIRED
    timeTIMESTAMPREQUIRED
    raw_dataSTRINGREQUIRED
    raw_predictionSTRINGNULLABLE
    groundtruthSTRINGNULLABLE

    Saiba como criar uma tabela do BigQuery.

Inspecionar modelos com a Ferramenta What-If

Use a Ferramenta What-If, WIT, na sigla em inglês (em inglês), em ambientes de notebook para inspecionar modelos do AI Platform Prediction por meio de um painel interativo. Essa ferramenta integra-se ao TensorBoard, aos notebooks Jupyter, aos notebooks Colab e ao JupyterHub. Ela também vem pré-instalada nas instâncias do TensorFlow de notebooks do Vertex AI Workbench gerenciados pelo usuário.

Saiba como usar a ferramenta What-If com o AI Platform (em inglês).

Como formatar sua entrada para a previsão on-line

Como formatar instâncias como strings JSON

O formato básico da predição on-line é uma lista de instâncias de dados. Ela pode ser uma lista simples de valores ou membros de um objeto JSON, dependendo de como você configurou as entradas no aplicativo de treinamento. Os modelos do TensorFlow e as rotinas de predição personalizada podem aceitar entradas mais complexas, enquanto a maioria dos modelos do scikit-learn e do XGBoost esperam uma lista de números como entrada.

Este exemplo mostra um tensor de entrada e uma chave de instância em relação a um modelo do TensorFlow:

{"values": [1, 2, 3, 4], "key": 1}

A composição da string JSON pode ser complexa, contanto que siga estas regras:

  • O nível superior dos dados da instância precisa ser um objeto JSON, um dicionário de pares de chave-valor.

  • Os valores individuais em um objeto de instância podem ser strings, números ou listas. Não é possível incorporar objetos JSON.

  • As listas devem conter apenas itens do mesmo tipo (incluindo outras listas). Não é possível misturar strings e valores numéricos.

Transmita as instâncias de entrada para previsão on-line como o corpo da mensagem da chamada projects.predict. Saiba mais sobre os requisitos de formatação do corpo da solicitação.

gcloud

A formatação da entrada pode ser feita de duas maneiras, dependendo de como você planeja enviar a solicitação de previsão. Recomendamos usar a sinalização --json-request do comando gcloud ai-platform predict. Como alternativa, é possível usar a sinalização --json-instances com dados JSON delimitados por nova linha.

Para --json-request

Torne cada instância um item em uma matriz JSON e forneça a matriz como o campo instances de um arquivo JSON. Exemplo:

instances.json

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

Para --json-instances

Certifique-se de que o arquivo de entrada é um arquivo JSON delimitado por nova linha com cada instância como um objeto JSON, uma instância por linha. Exemplo:

instances.jsonl

{"values": [1, 2, 3, 4], "key": 1}
{"values": [5, 6, 7, 8], "key": 2}

API REST

Torne cada instância um item em uma matriz JSON e forneça a matriz como o campo instances de um objeto JSON. Exemplo:

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

Dados binários na entrada de previsão

Os dados binários não podem ser formatados como as strings codificadas em UTF-8 compatíveis com o JSON. Se houver dados binários nas entradas, é preciso usar a codificação base64 para representá-los. É necessária a seguinte formatação especial:

  • Sua string codificada precisa ser formatada como um objeto JSON com uma única chave chamada b64. No seguinte exemplo do Python 2.7, codificamos um buffer de dados JPEG brutos usando a biblioteca base64 para criar uma instância:

    {"image_bytes": {"b64": base64.b64encode(jpeg_data)}}

    No Python 3, a codificação base64 gera uma sequência de bytes. É preciso converter essa sequência em uma string para torná-la serializável em JSON:

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}

  • No código de modelo TensorFlow, é preciso nomear os aliases dos seus tensores binários de entrada e saída para que terminem com "_bytes".

Como solicitar previsões

Para solicitar uma previsão on-line, envie instâncias de dados de entrada como uma string JSON em uma solicitação de predict. Para formatar o corpo da solicitação e da resposta, consulte os detalhes da solicitação de previsão.

Se você não especificar uma versão de modelo, sua solicitação de previsão usará a versão padrão do modelo.

gcloud

  1. Crie variáveis de ambiente para manter os parâmetros, inclusive um valor de versão caso você decida especificar uma determinada versão de modelo:

    MODEL_NAME="[YOUR-MODEL-NAME]"
INPUT_DATA_FILE="instances.json"
VERSION_NAME="[YOUR-VERSION-NAME]"

  2. Use gcloud ai-platform predict para enviar instâncias a um modelo implantado. Observe que --version é opcional.

    gcloud ai-platform predict \
  --model=$MODEL_NAME \
  --version=$VERSION_NAME \
  --json-request=$INPUT_DATA_FILE \
  --region=REGION

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

  3. A ferramenta gcloud analisa a resposta e imprime as previsões no terminal em um formato legível. Você pode especificar um formato de saída diferente, como JSON ou CSV, usando a sinalização --format com seu comando de predição. Veja os formatos de saída disponíveis.

Python

Use a biblioteca de cliente de APIs do Google para Python para chamar a API AI Platform Training and Prediction sem gerar solicitações HTTP manualmente. Antes de executar o código de exemplo a seguir, é preciso configurar a autenticação.

# Create the AI Platform service object.
# To authenticate set the environment variable
# GOOGLE_APPLICATION_CREDENTIALS=<path_to_service_account_file>
service = googleapiclient.discovery.build("ml", "v1")

def predict_json(project, model, instances, version=None):
    """Send json data to a deployed model for prediction.

    Args:
        project (str): project where the AI Platform Model is deployed.
        model (str): model name.
        instances ([Mapping[str: Any]]): Keys should be the names of Tensors
            your deployed model expects as inputs. Values should be datatypes
            convertible to Tensors, or (potentially nested) lists of datatypes
            convertible to tensors.
        version: str, version of the model to target.
    Returns:
        Mapping[str: any]: dictionary of prediction results defined by the
            model.
    """
    name = f"projects/{project}/models/{model}"

    if version is not None:
        name += f"/versions/{version}"

    response = (
        service.projects().predict(name=name, body={"instances": instances}).execute()
    )

    if "error" in response:
        raise RuntimeError(response["error"])

    return response["predictions"]

Java

Use a biblioteca de cliente de APIs do Google para Java para chamar a API AI Platform Training and Prediction sem gerar solicitações HTTP manualmente. Antes de executar o código de exemplo a seguir, é preciso configurar a autenticação.

/*
 * Copyright 2017 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.FileContent;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpContent;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.UriTemplate;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.discovery.Discovery;
import com.google.api.services.discovery.model.JsonSchema;
import com.google.api.services.discovery.model.RestDescription;
import com.google.api.services.discovery.model.RestMethod;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.File;
import java.util.ArrayList;
import java.util.List;

/*
 * Sample code for sending an online prediction request to Cloud Machine Learning Engine.
 */

public class OnlinePredictionSample {
  public static void main(String[] args) throws Exception {
    HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
    JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
    Discovery discovery = new Discovery.Builder(httpTransport, jsonFactory, null).build();

    RestDescription api = discovery.apis().getRest("ml", "v1").execute();
    RestMethod method = api.getResources().get("projects").getMethods().get("predict");

    JsonSchema param = new JsonSchema();
    String projectId = "YOUR_PROJECT_ID";
    // You should have already deployed a model and a version.
    // For reference, see https://cloud.google.com/ml-engine/docs/deploying-models.
    String modelId = "YOUR_MODEL_ID";
    String versionId = "YOUR_VERSION_ID";
    param.set(
        "name", String.format("projects/%s/models/%s/versions/%s", projectId, modelId, versionId));

    GenericUrl url =
        new GenericUrl(UriTemplate.expand(api.getBaseUrl() + method.getPath(), param, true));
    System.out.println(url);

    String contentType = "application/json";
    File requestBodyFile = new File("input.txt");
    HttpContent content = new FileContent(contentType, requestBodyFile);
    System.out.println(content.getLength());

    List<String> scopes = new ArrayList<>();
    scopes.add("https://www.googleapis.com/auth/cloud-platform");

    GoogleCredentials credential = GoogleCredentials.getApplicationDefault().createScoped(scopes);
    HttpRequestFactory requestFactory =
        httpTransport.createRequestFactory(new HttpCredentialsAdapter(credential));
    HttpRequest request = requestFactory.buildRequest(method.getHttpMethod(), url, content);

    String response = request.execute().parseAsString();
    System.out.println(response);
  }
}

Como resolver problemas de previsões on-line

Veja a seguir erros comuns na previsão on-line:

  • erros de falta de memória
  • Dados de entrada formatados incorretamente.
  • Uma única solicitação de previsão on-line precisa conter no máximo 1,5 MB de dados. As solicitações criadas com a CLI gcloud não processam mais do que 100 instâncias por arquivo. Para receber previsões para mais instâncias simultaneamente, use a previsão em lote.

Tente reduzir o tamanho do seu modelo antes de implantá-lo no AI Platform Prediction para fazer previsões.

Veja mais detalhes sobre como resolver problemas on-line.

A seguir