Obtén predicciones en línea a partir de un modelo entrenado personalizado

En esta página, se muestra cómo obtener predicciones en línea (en tiempo real) de tus modelos entrenados personalizados mediante la consola de Google Cloud o la API de Vertex AI.

Dale formato a tu entrada para la predicción en línea

En esta sección, se muestra cómo formatear y codificar las instancias de entrada de predicción como JSON, lo que es necesario si usas el método predict o explain. Esto no es necesario si usas el método rawPredict. Para obtener información sobre qué método elegir, consulta Enviar solicitud al extremo.

Si usas el SDK de Vertex AI para Python a fin de enviar solicitudes de predicción, especifica la lista de instancias sin el campo instances. Por ejemplo, especifica [ ["the","quick","brown"], ... ] en lugar de { "instances": [ ["the","quick","brown"], ... ] }.

Si tu modelo usa un contenedor personalizado, la entrada debe tener el formato JSON y hay un campo parameters adicional que se puede usar para tu contenedor. Obtén más información para formatear entradas de predicción con contenedores personalizados.

Dales formato a tus instancias como strings JSON

El formato básico de la predicción en línea es una lista de instancias de datos. Pueden ser listas sin formato de valores o miembros de un objeto JSON, según cómo configuraste las entradas en la aplicación de entrenamiento. Los modelos de TensorFlow pueden aceptar entradas más complejas, mientras que la mayoría de los modelos de scikit-learn y XGBoost esperan una lista de números como entrada.

En este ejemplo, se muestra un tensor de entrada y una clave de instancia para un modelo de TensorFlow:

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

La composición de la string JSON puede ser compleja, siempre y cuando siga estas reglas:

  • El nivel superior de los datos de instancia debe ser un objeto JSON: un diccionario de pares clave-valor.

  • Los valores individuales en un objeto de instancia pueden ser strings, números o listas. No puedes incorporar objetos JSON.

  • Las listas deben contener solo elementos del mismo tipo (incluidas otras listas). No puedes mezclar valores numéricos y strings.

Pasa instancias de entrada para la predicción en línea como el cuerpo del mensaje de la llamada projects.locations.endpoints.predict. Obtén más información sobre los requisitos de formato del cuerpo de la solicitud.

Convierte cada instancia en un array JSON y proporciona el array como el campo instances de un objeto JSON. Por ejemplo:

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

Codifica datos binarios para la entrada de predicción

No es posible darles a los datos binarios el formato de strings codificadas en UTF-8 que admite JSON. Si tienes datos binarios en tus entradas, debes usar la codificación base64 para representarlos. Se requiere el siguiente formato especial:

  • La string codificada debe tener el formato de un objeto JSON con una sola clave llamada b64. En Python 3, la codificación base64 genera una secuencia de bytes. Debes convertir esto en una string para que pueda serializarse con JSON.

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

  • En tu código de modelo TensorFlow, debes asignar los alias de los tensores de entrada y salida binarios de modo que finalicen con “_bytes”.

Ejemplos de solicitud y respuesta

En esta sección, se describe el formato del cuerpo de la solicitud de predicción y del cuerpo de la respuesta, con ejemplos para TensorFlow, scikit-learn y XGBoost.

Solicitar detalles del cuerpo

TensorFlow

El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):

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

El objeto instances[] es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones.

La estructura de cada elemento de la lista de instancias se determina con la definición de entrada del modelo. En las instancias, se pueden incluir entradas con nombre (como objetos) o solo valores sin etiqueta.

No en todos los datos se incluyen entradas con nombre. Algunas instancias son valores JSON sencillos (booleano, número o string). Sin embargo, las instancias suelen ser listas de valores sencillos o listas anidadas complejas.

A continuación, se presentan algunos ejemplos de cuerpos de solicitud.

Datos CSV con cada fila codificada como un valor de string:

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

Texto sin formato:

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

Oraciones codificadas como listas de palabras (vectores de strings):

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

Valores escalares de punto flotante:

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

Vectores de números enteros:

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

Tensores (en este caso, tensores de dos dimensiones):

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

Imágenes que se pueden representar de diferentes maneras. En este esquema de codificación, las dos primeras dimensiones representan las filas y columnas de la imagen, y la tercera dimensión contiene listas (vectores) de los valores R, G y B para cada píxel:

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

Codificación de datos

Las strings JSON se deben codificar como UTF-8. Para enviar datos binarios, debes codificar los datos en base64 y marcarlos como binarios. Para marcar una string JSON como binaria, reemplázala por un objeto JSON con un atributo único denominado b64: 

{"b64": "..."}

En el siguiente ejemplo, se muestran dos instancias serializadas tf.Examples que requieren codificación base64 (se usan datos falsos solo para fines ilustrativos):

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

En el siguiente ejemplo, se muestran dos strings de bytes de imagen JPEG, que requieren codificación base64 (se usan datos falsos solo para fines ilustrativos):

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

Tensores de varias entradas

Algunos modelos tienen un grafo de TensorFlow subyacente con el que se aceptan varios tensores de entrada. En este caso, usa los nombres de los pares nombre-valor JSON para identificar los tensores de entrada.

Para un grafo con alias de tensor de entrada "image" (string codificada en base64) y "tag" (string), utiliza lo siguiente:

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

Para un grafo con alias de tensor de entrada "image" (arreglo de 3 dimensiones de entradas de 8 bits) y "tag" (string):

{
  "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

El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):

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

El objeto instances[] es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones. En el siguiente ejemplo, cada instancia de entrada es una lista de números de puntos flotantes:

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

La dimensión de las instancias de entrada debe coincidir con lo que espera el modelo. Por ejemplo, si el modelo requiere tres atributos, la longitud de cada instancia de entrada debe ser 3.

XGBoost

El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):

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

El objeto instances[] es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones. En el siguiente ejemplo, cada instancia de entrada es una lista de números de puntos flotantes:

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

La dimensión de las instancias de entrada debe coincidir con lo que espera el modelo. Por ejemplo, si el modelo requiere tres atributos, la longitud de cada instancia de entrada debe ser 3.

Vertex AI no admite la representación dispersa de instancias de entrada para XGBoost.

Con el servicio de predicción en línea, los ceros y los NaN se interpretan de manera diferente. Si el valor de un atributo es cero, usa 0.0 en la entrada correspondiente. Si falta el valor de una función, usa "NaN" en la entrada correspondiente.

En el siguiente ejemplo, se representa una solicitud de predicción con una instancia de entrada única, en la que el valor del primer atributo es 0.0, el del segundo es 1.1 y falta el del tercero:

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

PyTorch

Si tu modelo usa un contenedor compilado previamente de PyTorch, los controladores predeterminados de TorchServe esperan que cada instancia esté unida a un campo data. Por ejemplo:

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

Detalles del cuerpo de la respuesta

Si la llamada se realiza de forma correcta, el cuerpo de la respuesta contiene una entrada de predicción por instancia en el cuerpo de la solicitud, que se da en el mismo orden:

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

Si en la predicción se producen errores para alguna instancia, el cuerpo de la respuesta no contiene predicciones. En su lugar, contiene una entrada de error:

{
  "error": string
}

El objeto predictions[] contiene la lista de predicciones, una para cada instancia de la solicitud.

En caso de que se produzca un error, la string error contiene un mensaje que describe el problema. Se muestra el error en lugar de una lista de predicciones si este se produjo mientras se procesaban las instancias.

A pesar de que hay una predicción por instancia, el formato de una predicción no está relacionado directamente con el formato de una instancia. Con las predicciones, se toma cualquier formato que se especifique en la colección de salidas definida en el modelo. La colección de predicciones se muestra en una lista JSON. Cada miembro de la lista puede ser un valor sencillo, una lista o un objeto JSON de cualquier complejidad. Si el modelo tiene más de un tensor de salida, cada predicción será un objeto JSON que contiene un par nombre/valor para cada salida. Con los nombres, se pueden identificar los alias de salida en el grafo.

Ejemplos del cuerpo de la respuesta

TensorFlow

En los siguientes ejemplos, se muestran algunas respuestas posibles:

  • Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:

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

  • Un conjunto de predicciones más complejo, en el que cada predicción contiene dos valores con nombre que corresponden a los tensores de salida, con los nombres respectivos label y scores. El valor de label es la categoría predicha (“automóvil” o “playa”) y scores contiene una lista de probabilidades para esa instancia en todas las categorías posibles.

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

  • Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:

    {"error": "Divide by zero"}

scikit-learn

En los siguientes ejemplos, se muestran algunas respuestas posibles:

  • Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:

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

  • Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:

    {"error": "Divide by zero"}

XGBoost

En los siguientes ejemplos, se muestran algunas respuestas posibles:

  • Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:

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

  • Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:

    {"error": "Divide by zero"}

Envía una solicitud a un extremo

Existen tres maneras de enviar una solicitud:

Envía una solicitud de predicción en línea

gcloud

En el siguiente ejemplo, se usa el comando gcloud ai endpoints predict:

  1. Escribe el siguiente objeto JSON para archivarlo en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama request.json.

    {
 "instances": INSTANCES
}

    Reemplaza lo siguiente:

    • INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.

  2. Ejecuta el siguiente comando:

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

    Reemplaza lo siguiente:

    • ENDPOINT_ID: Es el ID del extremo.
    • LOCATION_ID: la región en la que usas Vertex AI.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • PROJECT_ID: el ID del proyecto
  • ENDPOINT_ID: Es el ID del extremo.
  • INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "instances": INSTANCES
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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
Si se ejecuta de forma correcta, recibirás una respuesta JSON similar a la que se muestra a continuación: En la respuesta, espera los siguientes reemplazos:
  • PREDICTIONS: un arreglo de predicciones JSON, uno para cada instancia que incluiste en el cuerpo de la solicitud.
  • DEPLOYED_MODEL_ID: el ID de DeployedModel que entregó las predicciones. 
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Java.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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 probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Node.js.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de 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

Envía una solicitud de predicción sin procesar en línea

gcloud

En el siguiente ejemplo, se usa el comando gcloud ai endpoints raw-predict:

  • Para solicitar predicciones con el objeto JSON en REQUEST especificado en la línea de comandos, usa este comando:

     gcloud ai endpoints raw-predict ENDPOINT_ID 
    
 --region=LOCATION 
    
 --request REQUEST

  • Para solicitar predicciones con una imagen almacenada en el archivo image.jpeg y en el encabezado Content-Type adecuado, usa el siguiente comando:

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

    Reemplaza lo siguiente:

    • ENDPOINT_ID: Es el ID del extremo.
    • LOCATION_ID: la región en la que usas Vertex AI.
    • REQUEST: Es el contenido de la solicitud para la que deseas obtener predicciones. El formato de la solicitud depende de lo que espera tu contenedor personalizado, que puede no ser necesariamente un objeto JSON.

Python

Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de Python. 

# -*- coding: utf-8 -*-
# Copyright 2020 Google LLC
#
# 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.
#
# Generated code. DO NOT EDIT!
#
# Snippet for RawPredict
# NOTE: This snippet has been automatically generated for illustrative purposes only.
# It may require modifications to work in your environment.

# To install the latest published package dependency, execute the following:
#   python3 -m pip install google-cloud-aiplatform

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)

La respuesta incluye los siguientes encabezados HTTP:

  • X-Vertex-AI-Endpoint-Id: Es el ID de Endpoint que entregó esta predicción.

  • X-Vertex-AI-Deployed-Model-Id: Es el ID del DeployedModel del extremo que entregó esta predicción.

Envía una solicitud de explicación en línea

gcloud

En el siguiente ejemplo, se usa el comando gcloud ai endpoints explain:

  1. Escribe el siguiente objeto JSON para archivarlo en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama request.json.

    {
 "instances": INSTANCES
}

    Reemplaza lo siguiente:

    • INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.

  2. Ejecuta el siguiente comando:

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

    Reemplaza lo siguiente:

    • ENDPOINT_ID: Es el ID del extremo.
    • LOCATION_ID: la región en la que usas Vertex AI.

    De forma opcional, si deseas enviar una solicitud de explicación a un DeployedModel preciso en el Endpoint, puedes especificar la marca --deployed-model-id:

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

    Además de los marcadores de posición descritos anteriormente, reemplaza lo siguiente:

    • DEPLOYED_MODEL_ID Opcional: El ID del modelo implementado para el que deseas obtener explicaciones. Se incluye el ID en la respuesta del método predict. Si necesitas solicitar explicaciones para un modelo en particular y tienes más de un modelo implementado en el mismo extremo, puedes usar este ID a fin de garantizar que se muestren las explicaciones para ese modelo en particular.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • PROJECT_ID: el ID del proyecto
  • ENDPOINT_ID: Es el ID del extremo.
  • INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "instances": INSTANCES
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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
Si se ejecuta de forma correcta, recibirás una respuesta JSON similar a la que se muestra a continuación: En la respuesta, espera los siguientes reemplazos:
  • PREDICTIONS: un arreglo de predicciones JSON, uno para cada instancia que incluiste en el cuerpo de la solicitud.
  • EXPLANATIONS: Un arreglo JSON de explicaciones, una para cada predicción.
  • DEPLOYED_MODEL_ID: el ID de DeployedModel que entregó las predicciones. 
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de 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)

¿Qué sigue?