Receber previsões on-line de modelos treinados de forma personalizada

A previsão on-line da Vertex AI é um serviço otimizado que executa dados em 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.

Antes de começar

Antes de solicitar previsões:

Configurar a implantação do modelo

Durante a implantação do modelo, você toma as seguintes decisões importantes sobre como executar a previsão on-line:

Recurso criado Configuração especificada na criação de recursos
Endpoint Local onde executar predições
Modelo Contêiner a ser usado (ModelContainerSpec)
DeployedModel Máquinas para usar na previsão on-line

Não é possível atualizar as configurações listadas acima após a criação inicial do modelo ou do endpoint. Não é possível modificá-las na solicitação de previsão on-line. Se você precisar alterar essas configurações, é necessário reimplantar o modelo.

Formatar a entrada para previsão on-line

Se você estiver usando um dos nossos contêineres pré-criados para disponibilizar predições usando o TensorFlow, o scikit-learn ou o XGBoost, as instâncias de entrada da previsão precisarão ser formatadas como JSON.

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.

Nesta seção, você verá como formatar instâncias de entrada de previsão como JSON e como processar dados binários com a codificação base64.

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. 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 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 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 é compatível com 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"]]}

Detalhes do corpo da resposta

As respostas são muito semelhantes às solicitações.

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 da previsão não está diretamente relacionado ao 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. Caso seu modelo tenha mais de um tensor de saída, cada previsão será um objeto JSON que contém 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 de previsão on-line

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

Se o modelo for implantado em um endpoint público, cada solicitação de previsão precisará ter 1,5 MB ou menos.

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. O nome de arquivo não importa, mas, nesse exemplo, o nome é request.json.

    {
     "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 que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.

  2. Execute este comando:

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

    Substitua:

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

REST e linha de comando

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

  • LOCATION: a região em que você está usando a Vertex AI.
  • PROJECT: 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 que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/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 chamado request.json e execute o comando a seguir:

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

PowerShell

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

$cred = gcloud auth application-default 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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/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

Para saber como instalar e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonJava.


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

Para saber como instalar e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonNode.js.

/**
 * 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 e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonPython.

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 bruta on-line

Outra opção é enviar uma solicitação de previsão bruta. Ela permite que você use um payload HTTP arbitrário em vez de seguir as diretrizes rígidas descritas nas seções anteriores deste guia.

É possível receber previsões brutas se você estiver usando um contêiner personalizado que recebe solicitações e envia respostas diferentes das diretrizes.

gcloud

O exemplo a seguir usa 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 \
      --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 \
      --http-headers=Content-Type=image/jpeg \
      --request @image.jpeg
    

Substitua:

  • ENDPOINT_ID: o ID do endpoint.
  • LOCATION: 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.

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

Se você tiver configurado seu Model para Vertex Explainable AI, será possível receber explicações on-line. As solicitações de explicação on-line têm o mesmo formato que as solicitações de previsão on-line e retornam respostas semelhantes. A única diferença é que as respostas de explicação on-line incluem atribuições de recursos, bem como previsões.

Os exemplos a seguir são quase idênticos aos da seção anterior, mas usam comandos um pouco diferentes:

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. O nome de arquivo não importa, mas, nesse exemplo, o nome é request.json.

    {
     "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 que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.

  2. Execute este comando:

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

    Substitua:

    • ENDPOINT_ID: o ID do endpoint.
    • LOCATION: 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 obter 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 e LINHA DE CMD

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

  • LOCATION: a região em que você está usando a Vertex AI.
  • PROJECT: 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 que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/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 chamado request.json e execute o comando a seguir:

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

PowerShell

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

$cred = gcloud auth application-default 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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/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 e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonPython.

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