Obtener inferencias online a partir de un modelo entrenado personalizado

En esta página se explica cómo obtener inferencias online (en tiempo real) de tus modelos entrenados personalizados mediante la CLI de Google Cloud o la API de Vertex AI.

Dar formato a las entradas para la inferencia online

En esta sección se muestra cómo dar formato y codificar las instancias de entrada de inferencia como JSON, lo que es necesario si utiliza el método predict o explain. Este paso no es obligatorio si utilizas el método rawPredict. Para obtener información sobre qué método elegir, consulta Enviar una solicitud a un endpoint.

Si usas el SDK de Vertex AI para Python para enviar solicitudes de inferencia, 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, tu entrada debe tener el formato JSON y hay un campo parameters adicional que puedes usar para tu contenedor. Más información sobre la entrada de inferencia de formato con contenedores personalizados

Formatear instancias como cadenas JSON

El formato básico de la inferencia online es una lista de instancias de datos. Pueden ser listas de valores sin formato o miembros de un objeto JSON, en función de cómo hayas configurado las entradas en tu 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 cadena JSON puede ser compleja, siempre que 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 de un objeto de instancia pueden ser cadenas, números o listas. No puedes insertar objetos JSON.

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

Las instancias de entrada para la inferencia online se envían como cuerpo del mensaje de la llamada projects.locations.endpoints.predict. Más información sobre los requisitos de formato del cuerpo de la solicitud

Convierte cada instancia en un elemento de una matriz JSON y proporciona la matriz 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}
]}

Codificar datos binarios para la entrada de inferencia

Los datos binarios no se pueden formatear como las cadenas codificadas en UTF-8 que admite JSON. Si tienes datos binarios en tus entradas, debes usar la codificación base64 para representarlos. Es necesario aplicar el siguiente formato especial:

  • La cadena 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 convertirlo en una cadena para que se pueda serializar en JSON:

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
    
  • En el código de tu modelo de TensorFlow, debes asignar a los alias de tus tensores de entrada y salida binarios nombres que terminen en "_bytes".

Ejemplos de solicitudes y respuestas

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

Detalles del cuerpo de la solicitud

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 obtener las inferencias.

La estructura de cada elemento de la lista de instancias se determina mediante la definición de entrada de tu modelo. Las instancias pueden incluir entradas con nombre (como objetos) o contener solo valores sin etiqueta.

No todos los datos incluyen entradas con nombre. Algunas instancias son valores JSON simples (booleanos, números o cadenas). Sin embargo, las instancias suelen ser listas de valores simples o listas anidadas complejas.

A continuación se muestran algunos ejemplos de cuerpos de solicitud.

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

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

Texto sin formato:

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

Frases codificadas como listas de palabras (vectores de cadenas):

{
  "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 bidimensionales):

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

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

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

Codificación de datos

Las cadenas JSON deben codificarse como UTF-8. Para enviar datos binarios, debes codificarlos en Base64 y marcarlos como binarios. Para marcar una cadena JSON como binaria, sustitúyala por un objeto JSON con un solo atributo llamado b64:

{"b64": "..."} 

En el siguiente ejemplo se muestran dos instancias de tf.Examples serializadas, que requieren codificación en Base64 (datos falsos, solo con fines ilustrativos):

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

En el siguiente ejemplo se muestran dos cadenas de bytes de imágenes JPEG que requieren codificación Base64 (datos falsos, solo con fines ilustrativos):

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

Varios tensores de entrada

Algunos modelos tienen un gráfico de TensorFlow subyacente que acepta varios tensores de entrada. En este caso, usa los nombres de los pares nombre/valor de JSON para identificar los tensores de entrada.

En el caso de un gráfico con los alias de tensor de entrada "tag" (cadena) e "image" (cadena codificada en base64):

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

En un gráfico con los alias de tensor de entrada "tag" (cadena) e "image" (matriz tridimensional de números enteros 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

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 obtener las inferencias. En el siguiente ejemplo, cada instancia de entrada es una lista de números de coma flotante:

{
  "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 tu modelo requiere tres características, 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 obtener las inferencias. En el siguiente ejemplo, cada instancia de entrada es una lista de números de coma flotante:

{
  "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 tu modelo requiere tres características, la longitud de cada instancia de entrada debe ser 3.

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

El servicio de inferencia online interpreta los ceros y los NaN de forma diferente. Si el valor de una función 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 muestra una solicitud de inferencia con una sola instancia de entrada, en la que el valor de la primera característica es 0.0, el de la segunda es 1.1 y el de la tercera falta:

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

PyTorch

Si tu modelo usa un contenedor precompilado de PyTorch, los controladores predeterminados de TorchServe esperan que cada instancia se envuelva en un campo data. Por ejemplo:

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

Detalles del cuerpo de la respuesta

Si la llamada se realiza correctamente, el cuerpo de la respuesta contiene una entrada de inferencia por instancia en el cuerpo de la solicitud, en el mismo orden:

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

Si falla la inferencia de alguna instancia, el cuerpo de la respuesta no contendrá ninguna inferencia. En su lugar, contiene una sola entrada de error:

{
  "error": string
}

El objeto predictions[] contiene la lista de inferencias, una por cada instancia de la solicitud.

Si se produce un error, la cadena error contiene un mensaje que describe el problema. El error se devuelve en lugar de una lista de inferencias si se ha producido un error al procesar alguna instancia.

Aunque hay una inferencia por instancia, el formato de una inferencia no está directamente relacionado con el formato de una instancia. Las inferencias adoptan el formato que se especifica en la colección de salidas definida en el modelo. La colección de inferencias se devuelve en una lista JSON. Cada miembro de la lista puede ser un valor simple, una lista o un objeto JSON de cualquier complejidad. Si tu modelo tiene más de un tensor de salida, cada inferencia será un objeto JSON que contenga un par nombre-valor por cada salida. Los nombres identifican los alias de salida del gráfico.

Ejemplos de cuerpos de respuesta

TensorFlow

En los siguientes ejemplos se muestran algunas respuestas posibles:

  • Un conjunto sencillo de predicciones para tres instancias de entrada, donde cada predicción es un valor entero:

    {"predictions":
       [5, 4, 3],
       "deployedModelId": 123456789012345678
    }
    
  • Un conjunto de predicciones más complejo, cada una de las cuales contiene dos valores con nombre que se corresponden con tensores de salida, denominados label y scores respectivamente. El valor de label es la categoría predicha ("coche" o "playa") y scores contiene una lista de probabilidades de esa instancia en las posibles categorías.

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ],
      "deployedModelId": 123456789012345678
    }
    
  • Respuesta cuando se produce un error al procesar una instancia de entrada:

    {"error": "Divide by zero"}
    

scikit‑learn

En los siguientes ejemplos se muestran algunas respuestas posibles:

  • Un conjunto sencillo de predicciones para tres instancias de entrada, donde cada predicción es un valor entero:

    {"predictions":
       [5, 4, 3],
       "deployedModelId": 123456789012345678
    }
    
  • Respuesta cuando se produce un error al procesar una instancia de entrada:

    {"error": "Divide by zero"}
    

XGBoost

En los siguientes ejemplos se muestran algunas respuestas posibles:

  • Un conjunto sencillo de predicciones para tres instancias de entrada, donde cada predicción es un valor entero:

    {"predictions":
       [5, 4, 3],
       "deployedModelId": 123456789012345678
    }
    
  • Respuesta cuando se produce un error al procesar una instancia de entrada:

    {"error": "Divide by zero"}
    

Enviar una solicitud a un endpoint

Hay cuatro formas de enviar una solicitud:

Enviar una solicitud de inferencia online a un endpoint público específico

Los endpoints dedicados facilitan la comunicación mediante los protocolos HTTP y gRPC. En las solicitudes gRPC, es obligatorio incluir el encabezado x-vertex-ai-endpoint-id para identificar los endpoints con precisión. Las siguientes APIs se admiten a través de estos endpoints específicos:

  • Predicen
  • RawPredict
  • StreamRawPredict
  • Finalización de la conversación (solo en Model Garden)
  • Invocar

Los endpoints dedicados usan una nueva ruta de URL. Puedes obtener esta ruta del campo dedicatedEndpointDns de la API REST o de Endpoint.dedicated_endpoint_dns del SDK de Vertex AI para Python. También puedes crear la ruta del endpoint manualmente con el siguiente código:

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

Haz los cambios siguientes:

  • ENDPOINT_ID: ID del endpoint.
  • LOCATION_ID: la región en la que usas Vertex AI.
  • PROJECT_NUMBER: el número de proyecto. Es distinto del ID de proyecto. Puedes encontrar el número de proyecto en la página Configuración del proyecto de la Google Cloud consola.

Para enviar una inferencia a un endpoint específico mediante el SDK de Vertex AI para Python, define el parámetro use_dedicated_endpoint como True:

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

Enviar una solicitud de inferencia online a un endpoint público compartido

gcloud

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

  1. Escribe el siguiente objeto JSON en un archivo de tu entorno local. El nombre del archivo no importa, pero en este ejemplo, llámalo request.json.

    {
     "instances": INSTANCES
    }
    

    Haz los cambios siguientes:

    • INSTANCES: una matriz JSON de instancias de las que quieres obtener inferencias. El formato de cada instancia depende de las entradas que espere tu modelo de aprendizaje automático entrenado. Para obtener más información, consulta Dar formato a las entradas para la inferencia online.

  2. Ejecuta el siguiente comando:

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

    Haz los cambios siguientes:

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

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • PROJECT_ID: tu ID de proyecto
  • ENDPOINT_ID: ID del endpoint.
  • INSTANCES: una matriz JSON de instancias de las que quieres obtener inferencias. El formato de cada instancia depende de las entradas que espere tu modelo de aprendizaje automático entrenado. Para obtener más información, consulta Dar formato a las entradas para la inferencia online.

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 la solicitud se realiza correctamente, recibirás una respuesta JSON similar a la siguiente. En la respuesta, se harán los siguientes cambios:
  • PREDICTIONS: una matriz JSON de predicciones, una por cada instancia que hayas incluido en el cuerpo de la solicitud.
  • DEPLOYED_MODEL_ID: ID del DeployedModel que ha servido las predicciones.
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

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

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 {
    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 probar este ejemplo, sigue las Node.js instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

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

    endpoint = aiplatform.Endpoint(endpoint)

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

Enviar una solicitud de inferencia sin procesar online

gcloud

En los siguientes ejemplos se usa el comando gcloud ai endpoints raw-predict:

  • Para solicitar la inferencia con el objeto JSON de REQUEST especificado en la línea de comandos, haz lo siguiente:

     gcloud ai endpoints raw-predict ENDPOINT_ID \
         --region=LOCATION_ID \
         --request=REQUEST
     
  • Para solicitar inferencias con una imagen almacenada en el archivo image.jpeg y el encabezado Content-Type adecuado, haz lo siguiente:

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

    Haz los cambios siguientes:

    • ENDPOINT_ID: ID del endpoint.
    • LOCATION_ID: la región en la que usas Vertex AI.
    • REQUEST: el contenido de la solicitud para la que quieres obtener inferencias. El formato de la solicitud depende de lo que espere tu contenedor personalizado, que no tiene por qué ser un objeto JSON.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from google.cloud import aiplatform_v1


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

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

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

    # Handle the response
    print(response)

La respuesta incluye los siguientes encabezados HTTP:

  • X-Vertex-AI-Endpoint-Id: ID del Endpoint que ha servido esta inferencia.

  • X-Vertex-AI-Deployed-Model-Id: ID del DeployedModel del endpoint que ha proporcionado esta inferencia.

Enviar una solicitud de explicación online

gcloud

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

  1. Escribe el siguiente objeto JSON en un archivo de tu entorno local. El nombre del archivo no importa, pero en este ejemplo, llámalo request.json.

    {
     "instances": INSTANCES
    }
    

    Haz los cambios siguientes:

    • INSTANCES: una matriz JSON de instancias de las que quieres obtener inferencias. El formato de cada instancia depende de las entradas que espere tu modelo de aprendizaje automático entrenado. Para obtener más información, consulta Dar formato a las entradas para la inferencia online.

  2. Ejecuta el siguiente comando:

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

    Haz los cambios siguientes:

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

    De forma opcional, si quieres enviar una solicitud de explicación a un DeployedModel específico de la 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, sustituya lo siguiente:

    • DEPLOYED_MODEL_ID Opcional: ID del modelo implementado del que quiere obtener explicaciones. El ID se incluye en la respuesta del método predict. Si necesitas solicitar explicaciones de un modelo concreto y tienes más de un modelo desplegado en el mismo endpoint, puedes usar este ID para asegurarte de que las explicaciones se devuelvan para ese modelo concreto.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • PROJECT_ID:
  • ENDPOINT_ID: ID del endpoint.
  • INSTANCES: una matriz JSON de instancias de las que quieres obtener inferencias. El formato de cada instancia depende de las entradas que espere tu modelo de aprendizaje automático entrenado. Para obtener más información, consulta Dar formato a las entradas para la inferencia online.

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 la solicitud se realiza correctamente, recibirás una respuesta JSON similar a la siguiente. En la respuesta, se harán los siguientes cambios:
  • PREDICTIONS: una matriz JSON de predicciones, una por cada instancia que hayas incluido en el cuerpo de la solicitud.
  • EXPLANATIONS: un array JSON de explicaciones, una por cada predicción.
  • DEPLOYED_MODEL_ID: ID del DeployedModel que ha servido las predicciones.
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

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

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

    endpoint = aiplatform.Endpoint(endpoint_id)

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

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

    for prediction in response.predictions:
        print(prediction)

Enviar una solicitud de invocación online

La ruta de invocación permite acceder a todas las rutas de solicitud que no sean de raíz en la implementación. Por ejemplo, /invoke/foo/bar se reenviará como /foo/bar al servidor del modelo. Hay dos formas de acceder a la ruta.

solicitud de ruta personalizada a un endpoint específico

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

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)

Dirigir una solicitud de ruta personalizada a un modelo desplegado

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

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)

Siguientes pasos