Obtén predicciones en línea de los modelos con entrenamiento personalizado

La predicción en línea de Vertex AI es un servicio optimizado para ejecutar tus datos mediante modelos alojados con la menor latencia posible. Envía lotes pequeños de datos al servicio y tus predicciones se mostrarán en la respuesta.

Antes de comenzar

Para solicitar predicciones, primero debes realizar las siguientes acciones:

• Entrena tu modelo. En tu código de entrenamiento, exporta tus artefactos de modelo entrenado como uno o más artefactos del modelo que se pueden implementar en Vertex AI.

• Implementa tu modelo entrenado en Vertex AI. Para ello, sube los artefactos de tu modelo y, luego, implementa el modelo en un extremo de Vertex AI.

Configura la implementación del modelo

Durante la implementación del modelo, toma las siguientes decisiones importantes sobre cómo ejecutar la predicción en línea:

Recurso creado	Configuración especificada durante la creación del recurso
Extremo	Ubicación en la que se ejecutan las predicciones
Modelo	Contenedor que se usará (ModelContainerSpec)
DeployedModel	Máquinas que se usan para la predicción en línea

No puedes actualizar la configuración que se indica antes después de la creación inicial del modelo o extremo, y no puedes anularlas en la solicitud de predicción en línea. Si necesitas cambiar esta configuración, debes volver a implementar tu modelo.

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

Si usas uno de nuestros contenedores compilados con anterioridad para entregar predicciones mediante TensorFlow, scikit-learn o XGBoost, las instancias de entrada de predicción deben tener formato JSON.

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.

En esta sección, se muestra cómo formatear las instancias de entrada de predicción como JSON y cómo controlar datos binarios con la codificación base64.

Dale 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

Nota: La siguiente sección solo se aplica a la predicción con TensorFlow.

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 un atributo, 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"]]}

Detalles del cuerpo de la respuesta

Las respuestas son muy similares a las solicitudes.

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 de predicción en línea

Envía tus instancias de datos de entrada como una string JSON en una solicitud de predicción para solicitar una predicción en línea. Si deseas dar formato al cuerpo de la solicitud y la respuesta, consulta los detalles de la solicitud de predicción.

Si el modelo se implementa en un extremo público, cada solicitud de predicción debe ser de 1.5 MB o menos.

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 los datos que espera tu modelo de AA entrenado específico. Consulta la sección Da formato a tus entradas para predicciones en línea de este documento.

2. Ejecuta el siguiente comando:

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

   Reemplaza lo siguiente:

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

LÍNEA DE REST Y CMD

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

• LOCATION: la región en la que usas Vertex AI.
• PROJECT: el ID de tu 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 los datos que espera tu modelo de AA entrenado específico. Consulta la sección Da formato a tus entradas para predicciones en línea de este documento.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict

Cuerpo JSON de la solicitud:

{
  "instances": INSTANCES
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Asegúrate de haber configurado la variable de entorno GOOGLE_APPLICATION_CREDENTIALS a la ruta para el archivo de clave privada de tu cuenta de servicio.

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

Nota: Asegúrate de haber configurado la variable de entorno GOOGLE_APPLICATION_CREDENTIALS a la ruta para el archivo de clave privada de tu cuenta de servicio.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

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ó estas predicciones.

{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Si deseas obtener información para instalar y usar la biblioteca cliente de Vertex AI, consulta las bibliotecas cliente de Vertex AI. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Java.

Ver en GitHubComentarios

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

Si deseas obtener información para instalar y usar la biblioteca cliente de Vertex AI, consulta las bibliotecas cliente de Vertex AI. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Node.js.

Ver en GitHubComentarios

/**
 * 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 y usar la biblioteca cliente de Vertex AI, consulta las bibliotecas cliente de Vertex AI. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Python.

Ver en GitHubComentarios

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

Como alternativa, puedes enviar una solicitud de predicción sin procesar, lo que te permite usar una carga útil de HTTP arbitraria en lugar de seguir los lineamientos estrictos que se describen en las secciones anteriores de esta guía.

Te recomendamos que obtengas predicciones sin procesar si usas un contenedor personalizado que recibe solicitudes y envía respuestas que difieren de los lineamientos.

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: 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.

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.

Nota: Si tu contenedor recibe solicitudes o envía respuestas que difieren de los lineamientos, entonces el contenedor no es compatible conVertex Explainable AI o Vertex AI Model Monitoring.

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

Si configuraste tu Model para Vertex Explainable AI, puedes obtener explicaciones en línea. Las solicitudes de explicación en línea tienen el mismo formato que las solicitudes de predicción en línea y muestran respuestas similares; la única diferencia es que las respuestas en las explicaciones en línea incluyen atribuciones de funciones y predicciones.

Los siguientes ejemplos son casi idénticos a los de la sección anterior, excepto que usan comandos un poco diferentes:

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 los datos que espera tu modelo de AA entrenado específico. Consulta la sección Da formato a tus entradas para predicciones en línea de este documento.

2. Ejecuta el siguiente comando:

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

   Reemplaza lo siguiente:

   • ENDPOINT_ID: Es el ID del extremo.
   • LOCATION: 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: El ID del modelo implementado para el que deseas obtener explicaciones (opcional). 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.

LÍNEA DE REST Y CMD

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

• LOCATION: la región en la que usas Vertex AI.
• PROJECT: el ID de tu 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 los datos que espera tu modelo de AA entrenado específico. Consulta la sección Da formato a tus entradas para predicciones en línea de este documento.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain

Cuerpo JSON de la solicitud:

{
  "instances": INSTANCES
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Asegúrate de haber configurado la variable de entorno GOOGLE_APPLICATION_CREDENTIALS a la ruta para el archivo de clave privada de tu cuenta de servicio.

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

Nota: Asegúrate de haber configurado la variable de entorno GOOGLE_APPLICATION_CREDENTIALS a la ruta para el archivo de clave privada de tu cuenta de servicio.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

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ó estas predicciones.

{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Si deseas obtener información para instalar y usar la biblioteca cliente de Vertex AI, consulta las bibliotecas cliente de Vertex AI. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Python.

Ver en GitHubComentarios

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?

• Obtén más información para obtener predicciones a partir de modelos de AutoML.