Receber previsões de um modelo treinado personalizado

Nesta página, mostramos como receber previsões on-line (em tempo real) dos modelos treinados personalizados usando o Console do Google Cloud ou a API Vertex AI.

Formatar a entrada para previsão on-line

Nesta seção, mostramos como formatar e codificar suas instâncias de entrada de previsão como JSON, o que é necessário se você estiver usando o método predict ou explain. Isso não será necessário ao usar o método rawPredict. Para mais informações sobre qual método escolher, consulte Enviar solicitação para o endpoint.

Se você estiver usando o SDK da Vertex AI para Python para enviar solicitações de previsão, especifique a lista de instâncias sem o campo instances. Por exemplo, especifique [ ["the","quick","brown"], ... ] em vez de { "instances": [ ["the","quick","brown"], ... ] }.

Se o modelo usa um contêiner personalizado, a entrada precisa ser formatada como JSON e há um campo parameters extra que pode ser usado para o contêiner. Saiba mais sobre como formatar a entrada de previsão com contêineres personalizados.

Formatar instâncias como strings JSON

O formato básico da previsã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 aceitam 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 para 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.locations.endpoints.predict. Saiba mais sobre os requisitos de formatação do corpo da solicitação.

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

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

Codificar dados binários para entrada de previsão

Os dados binários não podem ser formatados como as strings codificadas em UTF-8 compatíveis com JSON. Se houver dados binários nas entradas, você terá que 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 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".

Exemplos de solicitação e resposta

Nesta seção, descreveremos o formato do corpo da solicitação de previsão e da resposta, com exemplos para TensorFlow, scikit-learn e XGBoost.

Detalhes do corpo da solicitação

TensorFlow

O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

O objeto instances[] é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões.

A estrutura de cada elemento da lista é determinada pela definição de entrada do modelo. As instâncias podem incluir entradas nomeadas, como objetos, ou conter apenas valores sem rótulo.

Nem todos os dados incluem entradas nomeadas. Algumas instâncias são valores JSON simples como booleanos, números ou strings. No entanto, as instâncias costumam ser listas de valores simples ou listas aninhadas complexas.

Veja abaixo alguns exemplos de corpo de solicitação.

Dados CSV com cada linha codificada como um valor de string:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

Texto simples:

{"instances": ["the quick brown fox", "the lazy dog"]}

Frases codificadas como listas de palavras (vetores de strings):

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

Valores de ponto flutuante escalares:

{"instances": [0.0, 1.1, 2.2]}

Vetores de números inteiros:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

Tensores (neste caso, bidimensionais):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

Imagens, que podem ser representadas de maneiras diferentes. Neste esquema de codificação, as duas primeiras dimensões representam as linhas e colunas da imagem. Já a terceira dimensão contém listas (vetores) dos valores R, G e B de cada pixel:

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

Codificação de dados

As strings JSON precisam ser codificadas em UTF-8. Para enviar dados binários, é necessário codificar os dados em base64 e marcá-los como binários. Para marcar uma string JSON como binária, substitua-a por um objeto JSON com um único atributo denominado b64: 

{"b64": "..."}

O exemplo a seguir mostra duas instâncias tf.Examples serializadas, que exigem codificação base64 (dados falsos, apenas para fins ilustrativos):

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

O exemplo a seguir mostra duas strings de byte de imagem JPEG que exigem a codificação base64 (dados meramente ilustrativos):

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

Vários tensores de entrada

Alguns modelos têm um gráfico subjacente do TensorFlow que aceita vários tensores de entrada. Nesse caso, use os nomes dos pares JSON de nome/valor para identificar esses tensores:

Para um gráfico com os aliases de tensor de entrada "tag" (string) e "image" (string codificada em Base64), use o seguinte:

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

Para um gráfico com os aliases de tensor de entrada "tag" (string) e "image" (matriz tridimensional com ints de 8 bits), use o seguinte:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:

{
  "instances": [
    <simple list>,
    ...
  ]
}

O objeto instances[] é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões. No exemplo a seguir, cada instância de entrada é uma lista de floats:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

A dimensão das instâncias de entrada precisa corresponder ao que seu modelo espera. Por exemplo, se o modelo precisar de três recursos, o comprimento de cada instância de entrada será 3.

XGBoost

O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:

{
  "instances": [
    <simple list>,
    ...
  ]
}

O objeto instances[] é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões. No exemplo a seguir, cada instância de entrada é uma lista de floats:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

A dimensão das instâncias de entrada precisa corresponder ao que seu modelo espera. Por exemplo, se o modelo precisar de três recursos, o comprimento de cada instância de entrada será 3.

A Vertex AI não aceita a representação esparsa de instâncias de entrada para XGBoost.

O serviço de previsão on-line interpreta zeros e NaNs de maneira diferente. Se o valor de um recurso for zero, use 0.0 na entrada correspondente. Se o valor de um elemento estiver ausente, use "NaN" na entrada correspondente.

O exemplo a seguir representa uma solicitação de previsão com uma única instância de entrada, em que o valor do primeiro recurso é 0.0, o valor do segundo recurso é 1.1 e o valor do terceiro está ausente:

{"instances": [[0.0, 1.1, "NaN"]]}

PyTorch

Se o modelo usa um contêiner pré-criado do PyTorch, os gerenciadores padrão do TorchServe esperam que cada instância seja encapsulada em um campo data. Por exemplo:

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

Detalhes do corpo da resposta

Se a chamada for bem-sucedida, o corpo da resposta terá uma entrada de previsão por instância no corpo da solicitação, dadas na mesma ordem:

{
  "predictions": [
    {
      object
    }
  ],
  "deployedModelId": string
}

Se a previsão falhar em qualquer instância, o corpo da resposta não terá previsões. Em vez disso, ele inclui uma única entrada de erro:

{
  "error": string
}

O objeto predictions[] contém a lista de previsões, uma para cada instância na solicitação.

Em caso de erro, a string error contém uma mensagem descrevendo o problema. Se ocorrer um erro durante o processamento de qualquer instância, ele será retornado em vez de uma lista de previsão.

Há uma previsão por instância, mas o formato dela não está diretamente relacionado ao formato da instância. As previsões recebem o formato especificado no conjunto de saídas definido no modelo. O conjunto de previsões é retornado em uma lista JSON. Cada membro da lista pode ser um valor simples, uma lista ou um objeto JSON de qualquer complexidade. Se o seu modelo tiver mais de um tensor de saída, cada previsão será um objeto JSON com um par de nome/valor para cada saída. Os nomes identificam os aliases de saída no gráfico.

Exemplos de corpo de resposta

TensorFlow

Nos exemplos a seguir, mostramos algumas respostas possíveis:

  • Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

  • Um conjunto mais complexo de previsões, cada uma contendo dois valores nomeados que correspondem aos tensores de saída, denominados label e scores, respectivamente. O valor de label é a categoria prevista ("carro" ou "praia") e scores contém uma lista de probabilidades para essa instância nas categorias possíveis.

    {
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ],
  "deployedModelId": 123456789012345678
}

  • Resposta quando há um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}

scikit-learn

Nos exemplos a seguir, mostramos algumas respostas possíveis:

  • Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

  • Resposta quando há um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}

XGBoost

Nos exemplos a seguir, mostramos algumas respostas possíveis:

  • Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

  • Resposta quando há um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}

Enviar uma solicitação para um endpoint

Há três maneiras de enviar uma solicitação:

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

gcloud

O exemplo a seguir usa o comando gcloud ai endpoints predict:

  1. Grave o objeto JSON a seguir para o arquivo no ambiente local. Embora o nome do arquivo não seja importante, dê a ele o nome request.json para este exemplo.

    {
 "instances": INSTANCES
}

    Substitua:

    • INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas esperadas pelo modelo de ML treinado. Para mais informações, consulte Como formatar a entrada para previsão on-line.

  2. Execute este comando:

    gcloud ai endpoints predict ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json

    Substitua:

    • ENDPOINT_ID: o ID do endpoint.
    • LOCATION_ID: a região em que você está usando a Vertex AI.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION_ID: a região em que você está usando a Vertex AI.
  • PROJECT_ID: o ID do projeto
  • ENDPOINT_ID: o ID do endpoint.
  • INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas esperadas pelo modelo de ML treinado. Para mais informações, consulte Como formatar a entrada para previsão on-line.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict

Corpo JSON da solicitação:

{
  "instances": INSTANCES
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
Se for bem-sucedido, você receberá uma resposta JSON semelhante à seguinte. Na resposta, espere as seguintes substituições:
  • PREDICTIONS: uma matriz JSON de previsões, uma para cada instância incluída no corpo da solicitação.
  • DEPLOYED_MODEL_ID: o ID do DeployedModel que veiculou essas previsões. 
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.List;

public class PredictCustomTrainedModelSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String project = "YOUR_PROJECT_ID";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictCustomTrainedModel(project, endpointId, instance);
  }

  static void predictCustomTrainedModel(String project, String endpointId, String instance)
      throws IOException {
    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      String location = "us-central1";
      EndpointName endpointName = EndpointName.of(project, location, endpointId);

      ListValue.Builder listValue = ListValue.newBuilder();
      JsonFormat.parser().merge(instance, listValue);
      List<Value> instanceList = listValue.getValuesList();

      PredictRequest predictRequest =
          PredictRequest.newBuilder()
              .setEndpoint(endpointName.toString())
              .addAllInstances(instanceList)
              .build();
      PredictResponse predictResponse = predictionServiceClient.predict(predictRequest);

      System.out.println("Predict Custom Trained model Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.getDeployedModelId());
      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        System.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }
}

Node.js

Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const filename = "YOUR_PREDICTION_FILE_NAME";
// const endpointId = "YOUR_ENDPOINT_ID";
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const util = require('util');
const {readFile} = require('fs');
const readFileAsync = util.promisify(readFile);

// Imports the Google Cloud Prediction Service Client library
const {PredictionServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictCustomTrainedModel() {
  // Configure the parent resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = {
    structValue: {
      fields: {},
    },
  };
  const instanceDict = await readFileAsync(filename, 'utf8');
  const instanceValue = JSON.parse(instanceDict);
  const instance = {
    structValue: {
      fields: {
        Age: {stringValue: instanceValue['Age']},
        Balance: {stringValue: instanceValue['Balance']},
        Campaign: {stringValue: instanceValue['Campaign']},
        Contact: {stringValue: instanceValue['Contact']},
        Day: {stringValue: instanceValue['Day']},
        Default: {stringValue: instanceValue['Default']},
        Deposit: {stringValue: instanceValue['Deposit']},
        Duration: {stringValue: instanceValue['Duration']},
        Housing: {stringValue: instanceValue['Housing']},
        Job: {stringValue: instanceValue['Job']},
        Loan: {stringValue: instanceValue['Loan']},
        MaritalStatus: {stringValue: instanceValue['MaritalStatus']},
        Month: {stringValue: instanceValue['Month']},
        PDays: {stringValue: instanceValue['PDays']},
        POutcome: {stringValue: instanceValue['POutcome']},
        Previous: {stringValue: instanceValue['Previous']},
      },
    },
  };

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict custom trained model response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const prediction of predictions) {
    console.log(`\t\tPrediction : ${JSON.stringify(prediction)}`);
  }
}
predictCustomTrainedModel();

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

def endpoint_predict_sample(
    project: str, location: str, instances: list, endpoint: str
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint)

    prediction = endpoint.predict(instances=instances)
    print(prediction)
    return prediction

Enviar uma solicitação de previsão on-line para um endpoint dedicado

Os endpoints dedicados usam um novo caminho de URL. É possível extrair esse caminho do campo dedicatedEndpointDns na API REST ou de Endpoint.dedicated_endpoint_dns no SDK da Vertex AI para Python. Também é possível criar o caminho do endpoint manualmente usando o seguinte código:

f"https://ENDPOINT_ID.LOCATION_ID-PROJECT_NUMBER.prediction.vertexai.goog/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

Substitua:

  • ENDPOINT_ID: o ID do endpoint.
  • LOCATION_ID: a região em que você está usando a Vertex AI.
  • PROJECT_NUMBER: o número do projeto. Ele é diferente do ID do projeto. Encontre esse número na página Configurações do projeto no console do Google Cloud.

Para enviar uma previsão a um endpoint dedicado usando o SDK da Vertex AI para Python, defina o parâmetro use_dedicated_endpoint como True:

endpoint.predict(instances=instances, use_dedicated_endpoint=True)

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

gcloud

Estes exemplos usam o comando gcloud ai endpoints raw-predict.

  • Para solicitar previsões com o objeto JSON em REQUEST especificado na linha de comando:

     gcloud ai endpoints raw-predict ENDPOINT_ID \
     --region=LOCATION_ID \
     --request=REQUEST

  • Para solicitar previsões com uma imagem armazenada no arquivo image.jpeg e no cabeçalho Content-Type apropriado:

     gcloud ai endpoints raw-predict ENDPOINT_ID \
     --region=LOCATION_ID \
     --http-headers=Content-Type=image/jpeg \
     --request=@image.jpeg

    Substitua:

    • ENDPOINT_ID: o ID do endpoint.
    • LOCATION_ID: a região em que você está usando a Vertex AI.
    • REQUEST: o conteúdo da solicitação para a qual você quer receber previsões. O formato da solicitação depende do que o contêiner personalizado espera, que talvez não seja necessariamente um objeto JSON.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

from google.cloud import aiplatform_v1


def sample_raw_predict():
    # Create a client
    client = aiplatform_v1.PredictionServiceClient()

    # Initialize request argument(s)
    request = aiplatform_v1.RawPredictRequest(
        endpoint="endpoint_value",
    )

    # Make the request
    response = client.raw_predict(request=request)

    # Handle the response
    print(response)

A resposta inclui os seguintes cabeçalhos HTTP:

  • X-Vertex-AI-Endpoint-Id: ID do Endpoint que exibiu essa previsão.

  • X-Vertex-AI-Deployed-Model-Id: ID do DeployedModel do endpoint que exibiu essa previsão.

Enviar uma solicitação de explicação on-line

gcloud

O exemplo a seguir usa o comando gcloud ai endpoints explain:

  1. Grave o objeto JSON a seguir para o arquivo no ambiente local. Embora o nome do arquivo não seja importante, dê a ele o nome request.json para este exemplo.

    {
 "instances": INSTANCES
}

    Substitua:

    • INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas esperadas pelo modelo de ML treinado. Para mais informações, consulte Como formatar a entrada para previsão on-line.

  2. Execute este comando:

    gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json

    Substitua:

    • ENDPOINT_ID: o ID do endpoint.
    • LOCATION_ID: a região em que você está usando a Vertex AI.

    Opcionalmente, se você quiser enviar uma solicitação de explicação para um DeployedModel específico em Endpoint, especifique a sinalização --deployed-model-id:

    gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION \
  --deployed-model-id=DEPLOYED_MODEL_ID \
  --json-request=request.json

    Além dos marcadores de posição descritos anteriormente, substitua o seguinte:

    • DEPLOYED_MODEL_ID (opcional): o ID do modelo implantado que você quer receber explicações. O ID está incluído na resposta do método predict. Se você precisar solicitar explicações para um modelo específico e tiver mais de um modelo implantado no mesmo endpoint, use esse ID para garantir que as explicações sejam retornadas.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION_ID: a região em que você está usando a Vertex AI.
  • PROJECT_ID: o ID do projeto
  • ENDPOINT_ID: o ID do endpoint.
  • INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas esperadas pelo modelo de ML treinado. Para mais informações, consulte Como formatar a entrada para previsão on-line.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain

Corpo JSON da solicitação:

{
  "instances": INSTANCES
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
Se for bem-sucedido, você receberá uma resposta JSON semelhante à seguinte. Na resposta, espere as seguintes substituições:
  • PREDICTIONS: uma matriz JSON de previsões, uma para cada instância incluída no corpo da solicitação.
  • EXPLANATIONS: uma matriz JSON de explicações, uma para cada previsão.
  • DEPLOYED_MODEL_ID: o ID do DeployedModel que veiculou essas previsões. 
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

def explain_tabular_sample(
    project: str, location: str, endpoint_id: str, instance_dict: Dict
):

    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_id)

    response = endpoint.explain(instances=[instance_dict], parameters={})

    for explanation in response.explanations:
        print(" explanation")
        # Feature attributions.
        attributions = explanation.attributions
        for attribution in attributions:
            print("  attribution")
            print("   baseline_output_value:", attribution.baseline_output_value)
            print("   instance_output_value:", attribution.instance_output_value)
            print("   output_display_name:", attribution.output_display_name)
            print("   approximation_error:", attribution.approximation_error)
            print("   output_name:", attribution.output_name)
            output_index = attribution.output_index
            for output_index in output_index:
                print("   output_index:", output_index)

    for prediction in response.predictions:
        print(prediction)

A seguir