Obtenha inferências online a partir de um modelo preparado personalizado

Esta página mostra-lhe como obter inferências online (em tempo real) dos seus modelos com preparação personalizada através da CLI Google Cloud ou da API Vertex AI.

Formate a sua entrada para inferência online

Esta secção mostra como formatar e codificar as suas instâncias de entrada de inferência como JSON, o que é necessário se estiver a usar o método predict ou explain. Este passo não é obrigatório se usar o método rawPredict. Para obter informações sobre o método a escolher, consulte o artigo Enviar pedido para o ponto final.

Se estiver a usar o SDK do Vertex AI para Python para enviar pedidos de inferência, 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 seu modelo usar um contentor personalizado, a entrada tem de estar formatada como JSON e existe um campo parameters adicional que pode ser usado para o seu contentor. Saiba mais sobre a entrada de inferência de formato com contentores personalizados.

Formate instâncias como strings JSON

O formato básico para a inferência online é uma lista de instâncias de dados. Podem ser listas simples de valores ou membros de um objeto JSON, consoante a forma como configurou as entradas na sua aplicação de preparação. Os modelos do TensorFlow podem aceitar entradas mais complexas, enquanto a maioria dos modelos do scikit-learn e do XGBoost espera uma lista de números como entrada.

Este exemplo mostra um tensor de entrada e uma chave de instância para um modelo do TensorFlow:

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

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

  • O nível superior dos dados de instâncias tem de ser um objeto JSON: um dicionário de pares de chave/valor.

  • Os valores individuais num objeto de instância podem ser strings, números ou listas. Não pode incorporar objetos JSON.

  • As listas só podem conter itens do mesmo tipo (incluindo outras listas). Não pode misturar valores de string e numéricos.

Transmite instâncias de entrada para a inferência online como o corpo da mensagem para a chamada projects.locations.endpoints.predict. Saiba mais acerca dos requisitos de formatação do corpo do pedido.

Faça de cada instância um item numa 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}
]}

Codifique dados binários para entrada de inferência

Não é possível formatar dados binários como as strings codificadas em UTF-8 que o JSON suporta. Se tiver dados binários nas suas entradas, tem de usar a codificação base64 para os representar. É necessária a seguinte formatação especial:

  • A string codificada tem de ser formatada como um objeto JSON com uma única chave denominada b64. No Python 3, a codificação base64 gera uma sequência de bytes. Tem de converter este valor numa string para o tornar serializável em JSON:

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
    
  • No código do modelo do TensorFlow, tem de dar nomes aos alias dos tensores de entrada e saída binários para que terminem com "_bytes".

Exemplos de pedidos e respostas

Esta secção descreve o formato do corpo do pedido de inferência e do corpo da resposta, com exemplos para o TensorFlow, o scikit-learn e o XGBoost.

Detalhes do corpo do pedido

TensorFlow

O corpo do pedido contém dados com a seguinte estrutura (representação JSON):

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

O objeto instances[] é obrigatório e tem de conter a lista de instâncias para obter inferências.

A estrutura de cada elemento da lista de instâncias é determinada pela definição de entrada do seu modelo. As instâncias podem incluir entradas com nome (como objetos) ou podem conter apenas valores sem etiqueta.

Nem todos os dados incluem entradas com nome. Algumas instâncias são valores JSON simples (booleanos, numéricos ou de string). No entanto, as instâncias são frequentemente listas de valores simples ou listas aninhadas complexas.

Seguem-se alguns exemplos de corpos de pedidos.

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 escalares de vírgula flutuante:

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

Vetores de números inteiros:

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

Tensores (neste caso, tensores bidimensionais):

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

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

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

Codificação de dados

As strings JSON têm de ser codificadas como UTF-8. Para enviar dados binários, tem de 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 seguinte mostra duas instâncias serializadas de tf.Examples, que requerem codificação base64 (dados falsos, apenas para fins ilustrativos):

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

O exemplo seguinte mostra duas strings de bytes de imagens JPEG, que requerem a codificação base64 (dados falsos, apenas para fins ilustrativos):

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

Vários tensores de entrada

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

Para um gráfico com aliases de tensores de entrada "tag" (string) e "image" (string codificada em base64):

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

Para um gráfico com aliases de tensores de entrada "tag" (string) e "image" (matriz tridimensional de números inteiros de 8 bits):

{
  "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 do pedido contém dados com a seguinte estrutura (representação JSON):

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

O objeto instances[] é obrigatório e tem de conter a lista de instâncias para obter inferências. No exemplo seguinte, cada instância de entrada é uma lista de números de vírgula flutuante:

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

A dimensão das instâncias de entrada tem de corresponder ao que o seu modelo espera. Por exemplo, se o seu modelo exigir três caraterísticas, o comprimento de cada instância de entrada tem de ser 3.

XGBoost

O corpo do pedido contém dados com a seguinte estrutura (representação JSON):

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

O objeto instances[] é obrigatório e tem de conter a lista de instâncias para obter inferências. No exemplo seguinte, cada instância de entrada é uma lista de números de vírgula flutuante:

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

A dimensão das instâncias de entrada tem de corresponder ao que o seu modelo espera. Por exemplo, se o seu modelo exigir três caraterísticas, o comprimento de cada instância de entrada tem de ser 3.

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

O serviço de inferência online interpreta os zeros e os NaNs de forma diferente. Se o valor de uma funcionalidade for zero, use 0.0 na entrada correspondente. Se o valor de uma funcionalidade estiver em falta, use "NaN" na entrada correspondente.

O exemplo seguinte representa um pedido de inferência com uma única instância de entrada, em que o valor da primeira caraterística é 0,0, o valor da segunda caraterística é 1,1 e o valor da terceira caraterística está em falta:

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

PyTorch

Se o seu modelo usar um contentor pré-criado do PyTorch, os controladores predefinidos do TorchServe esperam que cada instância esteja envolvida num campo data. Por exemplo:

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

Detalhes do corpo da resposta

Se a chamada for bem-sucedida, o corpo da resposta contém uma entrada de inferência por instância no corpo do pedido, apresentada na mesma ordem:

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

Se a inferência falhar para qualquer instância, o corpo da resposta não contém inferências. Em alternativa, contém uma única entrada de erro:

{
  "error": string
}

O objeto predictions[] contém a lista de inferências, uma para cada instância no pedido.

Em caso de erro, a string error contém uma mensagem que descreve o problema. O erro é devolvido em vez de uma lista de inferências se ocorrer um erro durante o processamento de qualquer instância.

Embora exista uma inferência por instância, o formato de uma inferência não está diretamente relacionado com o formato de uma instância. As inferências usam o formato especificado na coleção de resultados definida no modelo. A coleção de inferências é devolvida numa 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 inferência será um objeto JSON que contém um par nome-valor para cada saída. Os nomes identificam os alias de saída no gráfico.

Exemplos de corpos de respostas

TensorFlow

Os exemplos seguintes mostram algumas respostas possíveis:

  • Um conjunto simples de previsões para 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 com nomes que correspondem a tensores de saída, denominados label e scores, respetivamente. O valor de label é a categoria prevista ("carro" ou "praia") e scores contém uma lista de probabilidades para essa instância nas possíveis categorias.

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ],
      "deployedModelId": 123456789012345678
    }
    
  • Uma resposta quando existe um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}
    

scikit-learn

Os exemplos seguintes mostram algumas respostas possíveis:

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

    {"predictions":
       [5, 4, 3],
       "deployedModelId": 123456789012345678
    }
    
  • Uma resposta quando existe um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}
    

XGBoost

Os exemplos seguintes mostram algumas respostas possíveis:

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

    {"predictions":
       [5, 4, 3],
       "deployedModelId": 123456789012345678
    }
    
  • Uma resposta quando existe um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}
    

Envie um pedido para um ponto final

Existem quatro formas de enviar uma solicitação:

Envie um pedido de inferência online para um ponto final público dedicado

Os pontos finais dedicados facilitam a comunicação através dos protocolos HTTP e gRPC. Para pedidos gRPC, a inclusão do cabeçalho x-vertex-ai-endpoint-id é obrigatória para garantir a identificação precisa do ponto final. As seguintes APIs são suportadas através destes pontos finais dedicados:

  • Prever
  • RawPredict
  • StreamRawPredict
  • Conclusão de chat (apenas no Model Garden)
  • Invocar

Os pontos finais dedicados usam um novo caminho de URL. Pode obter este caminho a partir do campo dedicatedEndpointDns na API REST ou a partir de Endpoint.dedicated_endpoint_dns no SDK Vertex AI para Python. Também pode construir o caminho do ponto final manualmente através do 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 o seguinte:

  • ENDPOINT_ID: o ID do ponto final.
  • LOCATION_ID: a região onde está a usar o Vertex AI.
  • PROJECT_NUMBER: o número do projeto. É diferente do ID do projeto. Pode encontrar o número do projeto na página Definições do projeto do Google Cloud projeto na consola.

Para enviar uma inferência para um ponto final dedicado através do SDK Vertex AI para Python, defina o parâmetro use_dedicated_endpoint como True:

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

Envie um pedido de inferência online para um ponto final público partilhado

gcloud

O exemplo seguinte usa o comando gcloud ai endpoints predict:

  1. Escreva o seguinte objeto JSON no ficheiro no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome request.json ao ficheiro.

    {
     "instances": INSTANCES
    }
    

    Substitua o seguinte:

    • INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.

  2. Execute o seguinte comando:

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

    Substitua o seguinte:

    • ENDPOINT_ID: o ID do ponto final.
    • LOCATION_ID: a região onde está a usar o Vertex AI.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION_ID: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu ID do projeto
  • ENDPOINT_ID: o ID do ponto final.
  • INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.

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 do pedido:

{
  "instances": INSTANCES
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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, recebe uma resposta JSON semelhante à seguinte. Na resposta, espere as seguintes substituições:
  • PREDICTIONS: uma matriz JSON de previsões, uma para cada instância que incluiu no corpo do pedido.
  • DEPLOYED_MODEL_ID: o ID do DeployedModel que publicou as previsões.
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 {
    PredictionServicPredictionServiceSettingsceSettings =
        PredictionServicPredictionServiceSettings          .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 (PredictionServicPredictionServiceClientceClient =
        PredictionServicPredictionServiceClientonServiceSettings)) {
      String location = "us-central1";
      EndpointName endEndpointNameEndpointName.of(EndpointNameation, endpointId);

      ListValue.BuildeListValueue = ListValue.newBuiListValue     JsonFormat.parseJsonFormatinstance, listValue);
      List<Value> instanListValuelistValue.getValuesList();

      PredictRequest pPredictRequest=
          PredictRequest.nPredictRequest            .setEndpoint(endpointName.toSendpointName.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.predictResponse.getDeployedModelId()out.println("Predictions");
      for (Value predictionValueedictResponse.predictResponse.getPredictionsList()em.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }
}

Node.js

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API.

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

Envie um pedido de inferência raw online

gcloud

Os exemplos seguintes usam o comando gcloud ai endpoints raw-predict:

  • Para pedir a inferência com o objeto JSON em REQUEST especificado na linha de comandos:

     gcloud ai endpoints raw-predict ENDPOINT_ID \
         --region=LOCATION_ID \
         --request=REQUEST
     
  • Para pedir inferências com uma imagem armazenada no ficheiro image.jpeg e o cabeçalho Content-Type adequado:

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

    Substitua o seguinte:

    • ENDPOINT_ID: o ID do ponto final.
    • LOCATION_ID: a região onde está a usar o Vertex AI.
    • REQUEST: o conteúdo do pedido para o qual quer obter inferências. O formato do pedido depende do que o seu contentor personalizado espera, que pode não ser necessariamente um objeto JSON.

Python

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

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 publicou esta inferência.

  • X-Vertex-AI-Deployed-Model-Id: ID do DeployedModel do ponto final que serviu esta inferência.

Envie um pedido de explicação online

gcloud

O exemplo seguinte usa o comando gcloud ai endpoints explain:

  1. Escreva o seguinte objeto JSON no ficheiro no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome request.json ao ficheiro.

    {
     "instances": INSTANCES
    }
    

    Substitua o seguinte:

    • INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.

  2. Execute o seguinte comando:

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

    Substitua o seguinte:

    • ENDPOINT_ID: o ID do ponto final.
    • LOCATION_ID: a região onde está a usar o Vertex AI.

    Opcionalmente, se quiser enviar um pedido de explicação a um DeployedModel específico no Endpoint, pode especificar a flag --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 implementado para o qual quer obter explicações. O ID está incluído na resposta do método predict. Se precisar de pedir explicações para um modelo específico e tiver mais do que um modelo implementado no mesmo ponto final, pode usar este ID para garantir que as explicações são devolvidas para esse modelo específico.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION_ID: a região onde está a usar o Vertex AI.
  • PROJECT_ID:
  • ENDPOINT_ID: o ID do ponto final.
  • INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.

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 do pedido:

{
  "instances": INSTANCES
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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, recebe uma resposta JSON semelhante à seguinte. Na resposta, espere as seguintes substituições:
  • PREDICTIONS: uma matriz JSON de previsões, uma para cada instância que incluiu no corpo do pedido.
  • EXPLANATIONS: uma matriz JSON de explicações, uma para cada previsão.
  • DEPLOYED_MODEL_ID: o ID do DeployedModel que publicou as previsões.
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

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

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)

Envie um pedido de invocação online

A rota de invocação permite o acesso a todos os caminhos de pedidos não raiz na implementação. Por exemplo, /invoke/foo/bar vai ser encaminhado como /foo/bar para o servidor do modelo. Existem duas formas de aceder ao trajeto.

encaminhar pedidos personalizados para um ponto final dedicado

Python

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

def invoke_tabular_sample(
    project: str,
    location: str,
    endpoint_id: str,
    request_path: str,
    http_request_body: Dict[str, Any],
    stream: bool = False,
):
    aiplatform.init(project=project, location=location)

    dedicated_endpoint = aiplatform.Endpoint(endpoint_id)
    if stream:
        for chunk in dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            stream=True,
        ):
            print(chunk)
    else:
        response = dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
        )
        print(response)

Encaminhe o pedido de rota personalizada diretamente para o modelo implementado

Python

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

def invoke_direct_deployed_model_inference_tabular_sample(
    project: str,
    location: str,
    endpoint_id: str,
    request_path: str,
    http_request_body: Dict[str, Any],
    deployed_model_id: str,
    stream: bool = False,
):
    aiplatform.init(project=project, location=location)

    dedicated_endpoint = aiplatform.Endpoint(endpoint_id)
    if stream:
        for chunk in dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            deployed_model_id=deployed_model_id,
            stream=True,
        ):
            print(chunk)
    else:
        response = dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            deployed_model_id=deployed_model_id,
        )
        print(response)

O que se segue?