Obtén predicciones y explicaciones en línea

En esta página, se muestra cómo obtener predicciones y explicaciones en línea (en tiempo real) de tus modelos de regresión o clasificación tabulares con la consola de Google Cloud o la API de Vertex AI.

Una predicción en línea es una solicitud síncrona, en lugar de una predicción por lotes, que es una solicitud asíncrona. Usa predicciones en línea cuando realices solicitudes en respuesta a la entrada de la aplicación o en otras situaciones en las que necesites una inferencia oportuna.

Debes implementar un modelo en un extremo antes de que se pueda usar para entregar predicciones en línea. La implementación de un modelo asocia recursos físicos con el modelo para que pueda entregar predicciones en línea con baja latencia.

Se tratan los siguientes temas:

  1. Implementa un modelo en un extremo
  2. Realiza una predicción en línea con el modelo implementado
  3. Obtén una explicación en línea con tu modelo implementado

Antes de comenzar

Antes de obtener predicciones en línea, primero debes entrenar un modelo de regresión o clasificación y evaluar su precisión.

Implementa un modelo en un extremo

Puedes implementar más de un modelo en un extremo y puedes implementar un modelo en más de un extremo. Si deseas obtener más información sobre las opciones y los casos de uso a fin de implementar modelos, consulta Acerca de la implementación de modelos.

Usa uno de los siguientes métodos para implementar un modelo:

Consola de Google Cloud

  1. En la sección Vertex AI de la consola de Google Cloud, vaya a la página Modelos.

    Ir a la página Modelos

  2. Haz clic en el nombre del modelo que deseas implementar para abrir su página de detalles.

  3. Selecciona la pestaña Implementar y probar.

    Si tu modelo ya está implementado en un extremo, se enumeran en la sección Implementa tu modelo.

  4. Haz clic en Implementar en el extremo.

  5. En la página Define tu extremo, configura lo siguiente:

    1. Puedes implementar tu modelo en un extremo nuevo o en uno existente.

      • Para implementar el modelo en un extremo nuevo, selecciona Crear extremo nuevo y proporciona un nombre para el extremo nuevo.
      • Para implementar tu modelo en un extremo existente, selecciona Agregar a extremo existente y selecciona el extremo de la lista desplegable.
      • Puedes agregar más de un modelo a un extremo y se puede agregar a un modelo más de un extremo. Obtén más información.
    2. Haz clic en Continuar.

  6. En la página Ajustes del modelo, configura lo siguiente:

    1. Si implementas tu modelo en un extremo nuevo, acepta 100 para la división del tráfico. Si implementas tu modelo en un extremo existente que tiene uno o más modelos implementados, debes actualizar el porcentaje de división del tráfico del modelo que estás implementando y el que ya se implementó, para que todos los porcentajes sumen 100%.

    2. Ingresa la cantidad mínima de nodos de procesamiento que deseas proporcionar para el modelo.

      Esta es la cantidad de nodos disponibles para este modelo en todo momento. Se te cobrará por los nodos que se usaron, ya sea a fin de controlar la carga de la predicción o para los nodos en espera (mínimo), incluso sin tráfico de predicción. Consulta la página de precios.

    3. Selecciona el Tipo de máquina.

      Los recursos de máquina más grandes aumentarán el rendimiento de tu predicción y los costos.

    4. Obtén más información a fin de cambiar la configuración predeterminada para el registro de predicción.

    5. Haga clic en Continue.

  7. En la página Supervisión de modelos, haz clic en Continuar.

  8. En la página Objetivos de monitorización, configura lo siguiente:

    1. Ingresa la ubicación de tus datos de entrenamiento.
    2. Ingresa el nombre de la columna de destino.
  9. Haz clic en Implementar para implementar el modelo en el extremo.

API

Cuando implementas un modelo con la API de Vertex AI, realiza los siguientes pasos:

  1. Crea un extremo si es necesario.
  2. Obtén el ID de extremo.
  3. Implementa el modelo en el extremo.

Crear un extremo

Si implementas un modelo en un extremo existente, puedes omitir este paso.

gcloud

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

  gcloud ai endpoints create \
    --region=LOCATION \
    --display-name=ENDPOINT_NAME

Reemplaza lo siguiente:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • ENDPOINT_NAME: el nombre visible para el extremo.

    La herramienta de la CLI de Google Cloud puede tardar unos segundos en crear el extremo.

REST

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

  • LOCATION_ID: Tu región.
  • PROJECT_ID: El ID del proyecto.
  • ENDPOINT_NAME: el nombre visible para el extremo.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "display_name": "ENDPOINT_NAME"
}

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateEndpointOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-11-05T17:45:42.812656Z",
      "updateTime": "2020-11-05T17:45:42.812656Z"
    }
  }
}
Puedes consultar el estado de la operación hasta que la respuesta incluya "done": true.

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.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.CreateEndpointOperationMetadata;
import com.google.cloud.aiplatform.v1.Endpoint;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateEndpointSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String endpointDisplayName = "YOUR_ENDPOINT_DISPLAY_NAME";
    createEndpointSample(project, endpointDisplayName);
  }

  static void createEndpointSample(String project, String endpointDisplayName)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    EndpointServiceSettings endpointServiceSettings =
        EndpointServiceSettings.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 (EndpointServiceClient endpointServiceClient =
        EndpointServiceClient.create(endpointServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);
      Endpoint endpoint = Endpoint.newBuilder().setDisplayName(endpointDisplayName).build();

      OperationFuture<Endpoint, CreateEndpointOperationMetadata> endpointFuture =
          endpointServiceClient.createEndpointAsync(locationName, endpoint);
      System.out.format("Operation name: %s\n", endpointFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      Endpoint endpointResponse = endpointFuture.get(300, TimeUnit.SECONDS);

      System.out.println("Create Endpoint Response");
      System.out.format("Name: %s\n", endpointResponse.getName());
      System.out.format("Display Name: %s\n", endpointResponse.getDisplayName());
      System.out.format("Description: %s\n", endpointResponse.getDescription());
      System.out.format("Labels: %s\n", endpointResponse.getLabelsMap());
      System.out.format("Create Time: %s\n", endpointResponse.getCreateTime());
      System.out.format("Update Time: %s\n", endpointResponse.getUpdateTime());
    }
  }
}

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 endpointDisplayName = 'YOUR_ENDPOINT_DISPLAY_NAME';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

// Imports the Google Cloud Endpoint Service Client library
const {EndpointServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const endpointServiceClient = new EndpointServiceClient(clientOptions);

async function createEndpoint() {
  // Configure the parent resource
  const parent = `projects/${project}/locations/${location}`;
  const endpoint = {
    displayName: endpointDisplayName,
  };
  const request = {
    parent,
    endpoint,
  };

  // Get and print out a list of all the endpoints for this resource
  const [response] = await endpointServiceClient.createEndpoint(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  const result = response.result;

  console.log('Create endpoint response');
  console.log(`\tName : ${result.name}`);
  console.log(`\tDisplay name : ${result.displayName}`);
  console.log(`\tDescription : ${result.description}`);
  console.log(`\tLabels : ${JSON.stringify(result.labels)}`);
  console.log(`\tCreate time : ${JSON.stringify(result.createTime)}`);
  console.log(`\tUpdate time : ${JSON.stringify(result.updateTime)}`);
}
createEndpoint();

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 create_endpoint_sample(
    project: str,
    display_name: str,
    location: str,
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint.create(
        display_name=display_name,
        project=project,
        location=location,
    )

    print(endpoint.display_name)
    print(endpoint.resource_name)
    return endpoint

Obtén el ID de extremo

Necesitas el ID de extremo para implementar el modelo.

gcloud

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

  gcloud ai endpoints list \
    --region=LOCATION \
    --filter=display_name=ENDPOINT_NAME

Reemplaza lo siguiente:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • ENDPOINT_NAME: el nombre visible para el extremo.

    Toma nota del número que aparece en la columna ENDPOINT_ID. Usa este ID en el paso siguiente.

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_NAME: el nombre visible para el extremo.

Método HTTP y URL:

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "endpoints": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID",
      "displayName": "ENDPOINT_NAME",
      "etag": "AMEw9yPz5pf4PwBHbRWOGh0PcAxUdjbdX2Jm3QO_amguy3DbZGP5Oi_YUKRywIE-BtLx",
      "createTime": "2020-04-17T18:31:11.585169Z",
      "updateTime": "2020-04-17T18:35:08.568959Z"
    }
  ]
}
Observa el ENDPOINT_ID.

Implementa el modelo

Selecciona la pestaña correspondiente a tu idioma o entorno:

gcloud

En los siguientes ejemplos se usa el comando gcloud ai endpoints deploy-model.

En el siguiente ejemplo, se implementa un Model en un Endpoint sin usar GPU para acelerar la entrega de predicciones y sin dividir el tráfico entre varios recursos DeployedModel:

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

  • ENDPOINT_ID: Es el ID del extremo.
  • LOCATION_ID: la región en la que usas Vertex AI.
  • MODEL_ID: El ID del modelo que se implementará.
  • DEPLOYED_MODEL_NAME: Un nombre para DeployedModel También puedes usar el nombre comercial de Model para DeployedModel.
  • MACHINE_TYPE: Opcional Los recursos de máquina que se usan para cada nodo de esta implementación. Su configuración predeterminada es n1-standard-2. Obtén más información sobre los tipos de máquinas.
  • MIN_REPLICA_COUNT: La cantidad mínima de nodos para esta implementación. El recuento de nodos se puede aumentar o disminuir según lo requiera la carga de predicción, hasta la cantidad máxima de nodos y nunca menos que esta cantidad. Este valor debe ser mayor o igual que 1% Si se omite la marca --min-replica-count, el valor predeterminado es 1.
  • MAX_REPLICA_COUNT: La cantidad máxima de nodos para esta implementación. El recuento de nodos se puede aumentar o disminuir, según lo requiera la carga de predicción, hasta esta cantidad de nodos y nunca menos que la cantidad mínima de nodos. Si omites la marca --max-replica-count, la cantidad máxima de nodos se establece en el valor de --min-replica-count.

Ejecuta el comando gcloud ai endpoints deploy-model:

Linux, macOS o Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=100

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME `
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=100

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME ^
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=100
 

Divide el tráfico

La marca --traffic-split=0=100 en los ejemplos anteriores envía el 100% del tráfico de predicción que Endpoint recibe al nuevo DeployedModel, que se representa mediante el ID temporal 0. Si tu Endpoint ya tiene otros recursos DeployedModel, puedes dividir el tráfico entre el DeployedModel nuevo y los anteriores. Por ejemplo, para enviar el 20% del tráfico al DeployedModel nuevo y el 80% a uno anterior, ejecuta el siguiente comando.

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

  • OLD_DEPLOYED_MODEL_ID: Es el ID del DeployedModel existente.

Ejecuta el comando gcloud ai endpoints deploy-model:

Linux, macOS o Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
 

REST

Usa el método endpoints.predict para solicitar una predicción en línea.

Implementar el modelo

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.
  • MODEL_ID: El ID del modelo que se implementará.
  • DEPLOYED_MODEL_NAME: Un nombre para DeployedModel También puedes usar el nombre comercial de Model para DeployedModel.
  • MACHINE_TYPE: Opcional Los recursos de máquina que se usan para cada nodo de esta implementación. Su configuración predeterminada es n1-standard-2. Obtén más información sobre los tipos de máquinas.
  • ACCELERATOR_TYPE: El tipo de acelerador que se adjuntará a la máquina. Es opcional si no se especifica ACCELERATOR_COUNT o es cero. No recomendado para modelos de AutoML ni modelos personalizados con capacitación personalizado que usan imágenes que no son de GPU. Obtén más información.
  • ACCELERATOR_COUNT: La cantidad de aceleradores que usa cada réplica. Opcional. Debe ser cero o no especificado para los modelos de AutoML o los modelos de capacitación personalizados que usan imágenes que no son de GPU.
  • MIN_REPLICA_COUNT: La cantidad mínima de nodos para esta implementación. El recuento de nodos se puede aumentar o disminuir según lo requiera la carga de predicción, hasta la cantidad máxima de nodos y nunca menos que esta cantidad. Este valor debe ser mayor o igual que 1%
  • MAX_REPLICA_COUNT: La cantidad máxima de nodos para esta implementación. El recuento de nodos se puede aumentar o disminuir, según lo requiera la carga de predicción, hasta esta cantidad de nodos y nunca menos que la cantidad mínima de nodos.
  • TRAFFIC_SPLIT_THIS_MODEL: El porcentaje del tráfico de predicción a este extremo para enrutar al modelo que se implementa con esta operación. La configuración predeterminada es 100. Todos los porcentajes de tráfico deben sumar hasta 100. Obtén más información sobre las divisiones del tráfico.
  • DEPLOYED_MODEL_ID_N: Opcional Si se implementan otros modelos en este extremo, debes actualizar sus porcentajes de división del tráfico para que todos los porcentajes sumen hasta 100.
  • TRAFFIC_SPLIT_MODEL_N: El valor de porcentaje de división del tráfico para la clave del ID del modelo implementado
  • PROJECT_NUMBER: el número de proyecto de tu proyecto generado de forma automática.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "deployedModel": {
    "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID",
    "displayName": "DEPLOYED_MODEL_NAME",
    "dedicatedResources": {
       "machineSpec": {
         "machineType": "MACHINE_TYPE",
         "acceleratorType": "ACCELERATOR_TYPE",
         "acceleratorCount": "ACCELERATOR_COUNT"
       },
       "minReplicaCount": MIN_REPLICA_COUNT,
       "maxReplicaCount": MAX_REPLICA_COUNT
     },
  },
  "trafficSplit": {
    "0": TRAFFIC_SPLIT_THIS_MODEL,
    "DEPLOYED_MODEL_ID_1": TRAFFIC_SPLIT_MODEL_1,
    "DEPLOYED_MODEL_ID_2": TRAFFIC_SPLIT_MODEL_2
  },
}

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-10-19T17:53:16.502088Z",
      "updateTime": "2020-10-19T17:53:16.502088Z"
    }
  }
}

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.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.DedicatedResources;
import com.google.cloud.aiplatform.v1.DeployModelOperationMetadata;
import com.google.cloud.aiplatform.v1.DeployModelResponse;
import com.google.cloud.aiplatform.v1.DeployedModel;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.MachineSpec;
import com.google.cloud.aiplatform.v1.ModelName;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ExecutionException;

public class DeployModelCustomTrainedModelSample {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String endpointId = "ENDPOINT_ID";
    String modelName = "MODEL_NAME";
    String deployedModelDisplayName = "DEPLOYED_MODEL_DISPLAY_NAME";
    deployModelCustomTrainedModelSample(project, endpointId, modelName, deployedModelDisplayName);
  }

  static void deployModelCustomTrainedModelSample(
      String project, String endpointId, String model, String deployedModelDisplayName)
      throws IOException, ExecutionException, InterruptedException {
    EndpointServiceSettings settings =
        EndpointServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // 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 (EndpointServiceClient client = EndpointServiceClient.create(settings)) {
      MachineSpec machineSpec = MachineSpec.newBuilder().setMachineType("n1-standard-2").build();
      DedicatedResources dedicatedResources =
          DedicatedResources.newBuilder().setMinReplicaCount(1).setMachineSpec(machineSpec).build();

      String modelName = ModelName.of(project, location, model).toString();
      DeployedModel deployedModel =
          DeployedModel.newBuilder()
              .setModel(modelName)
              .setDisplayName(deployedModelDisplayName)
              // `dedicated_resources` must be used for non-AutoML models
              .setDedicatedResources(dedicatedResources)
              .build();
      // key '0' assigns traffic for the newly deployed model
      // Traffic percentage values must add up to 100
      // Leave dictionary empty if endpoint should not accept any traffic
      Map<String, Integer> trafficSplit = new HashMap<>();
      trafficSplit.put("0", 100);
      EndpointName endpoint = EndpointName.of(project, location, endpointId);
      OperationFuture<DeployModelResponse, DeployModelOperationMetadata> response =
          client.deployModelAsync(endpoint, deployedModel, trafficSplit);

      // You can use OperationFuture.getInitialFuture to get a future representing the initial
      // response to the request, which contains information while the operation is in progress.
      System.out.format("Operation name: %s\n", response.getInitialFuture().get().getName());

      // OperationFuture.get() will block until the operation is finished.
      DeployModelResponse deployModelResponse = response.get();
      System.out.format("deployModelResponse: %s\n", deployModelResponse);
    }
  }
}

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 deploy_model_with_dedicated_resources_sample(
    project,
    location,
    model_name: str,
    machine_type: str,
    endpoint: Optional[aiplatform.Endpoint] = None,
    deployed_model_display_name: Optional[str] = None,
    traffic_percentage: Optional[int] = 0,
    traffic_split: Optional[Dict[str, int]] = None,
    min_replica_count: int = 1,
    max_replica_count: int = 1,
    accelerator_type: Optional[str] = None,
    accelerator_count: Optional[int] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    metadata: Optional[Sequence[Tuple[str, str]]] = (),
    sync: bool = True,
):
    """
    model_name: A fully-qualified model resource name or model ID.
          Example: "projects/123/locations/us-central1/models/456" or
          "456" when project and location are initialized or passed.
    """

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

    model = aiplatform.Model(model_name=model_name)

    # The explanation_metadata and explanation_parameters should only be
    # provided for a custom trained model and not an AutoML model.
    model.deploy(
        endpoint=endpoint,
        deployed_model_display_name=deployed_model_display_name,
        traffic_percentage=traffic_percentage,
        traffic_split=traffic_split,
        machine_type=machine_type,
        min_replica_count=min_replica_count,
        max_replica_count=max_replica_count,
        accelerator_type=accelerator_type,
        accelerator_count=accelerator_count,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        metadata=metadata,
        sync=sync,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    return model

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.

const automl = require('@google-cloud/automl');
const client = new automl.v1beta1.AutoMlClient();

/**
 * Demonstrates using the AutoML client to create a model.
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = '[PROJECT_ID]' e.g., "my-gcloud-project";
// const computeRegion = '[REGION_NAME]' e.g., "us-central1";
// const datasetId = '[DATASET_ID]' e.g., "TBL2246891593778855936";
// const tableId = '[TABLE_ID]' e.g., "1991013247762825216";
// const columnId = '[COLUMN_ID]' e.g., "773141392279994368";
// const modelName = '[MODEL_NAME]' e.g., "testModel";
// const trainBudget = '[TRAIN_BUDGET]' e.g., "1000",
// `Train budget in milli node hours`;

// A resource that represents Google Cloud Platform location.
const projectLocation = client.locationPath(projectId, computeRegion);

// Get the full path of the column.
const columnSpecId = client.columnSpecPath(
  projectId,
  computeRegion,
  datasetId,
  tableId,
  columnId
);

// Set target column to train the model.
const targetColumnSpec = {name: columnSpecId};

// Set tables model metadata.
const tablesModelMetadata = {
  targetColumnSpec: targetColumnSpec,
  trainBudgetMilliNodeHours: trainBudget,
};

// Set datasetId, model name and model metadata for the dataset.
const myModel = {
  datasetId: datasetId,
  displayName: modelName,
  tablesModelMetadata: tablesModelMetadata,
};

// Create a model with the model metadata in the region.
client
  .createModel({parent: projectLocation, model: myModel})
  .then(responses => {
    const initialApiResponse = responses[1];
    console.log(`Training operation name: ${initialApiResponse.name}`);
    console.log('Training started...');
  })
  .catch(err => {
    console.error(err);
  });

Obtén más información para cambiar la configuración predeterminada para el registro de predicción.

Obtén el estado de la operación

Algunas solicitudes inician operaciones de larga duración que requieren tiempo para completarse. Estas solicitudes devuelven un nombre de operación que puedes usar para ver el estado de la operación o cancelarla. Vertex AI proporciona métodos auxiliares para hacer llamadas en operaciones de larga duración. Para obtener más información, consulta Trabaja con operaciones de larga duración.

Realiza una predicción en línea con el modelo implementado

Si quieres realizar una predicción en línea, envía uno o más elementos de prueba a un modelo para su análisis, y el modelo mostrará resultados basados en el objetivo de tu modelo. Usa la consola de Google Cloud o la API de Vertex AI para solicitar una predicción en línea.

Consola de Google Cloud

  1. En la sección Vertex AI de la consola de Google Cloud, vaya a la página Modelos.

    Ir a la página Modelos

  2. En la lista de modelos, haz clic en el nombre del modelo desde el que quieres solicitar predicciones.

  3. Selecciona la pestaña Implementar y probar.

  4. En la sección Test your model, agrega elementos de prueba para solicitar una predicción. Los datos de la predicción de referencia se completan por ti o puedes ingresar tus propios datos de predicción y hacer clic en Predecir.

    Una vez que se completa la predicción, Vertex AI muestra los resultados en la consola.

API: Clasificación

gcloud

  1. Crea un archivo llamado request.json con el siguiente contenido:

          {
      "instances": [
        {
          PREDICTION_DATA_ROW
        }
      ]
    }
        

    Reemplaza lo siguiente:

    • PREDICTION_DATA_ROW: Un objeto JSON con claves como nombres de funciones y valores como los valores de atributo correspondientes. Por ejemplo, para un conjunto de datos con un número, un array de strings y una categoría, la fila de datos puede tener el siguiente ejemplo de solicitud:

      "length":3.6,
      "material":"cotton",
      "tag_array": ["abc","def"]
      

      Debes proporcionar un valor para cada atributo incluido en el entrenamiento. El formato de los datos usados para la predicción debe coincidir con el formato que se usa para el entrenamiento. Consulta Formato de datos para predicciones si quieres obtener más detalles.

  2. Ejecute 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

Usa el método endpoints.predict para solicitar una predicción en línea.

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

  • LOCATION_ID: Es la región en la que se encuentra el extremo. Por ejemplo, us-central1
  • PROJECT_ID: El ID del proyecto.
  • ENDPOINT_ID: Es el ID del extremo.
  • PREDICTION_DATA_ROW: Un objeto JSON con claves como nombres de funciones y valores como los valores de atributo correspondientes. Por ejemplo, para un conjunto de datos con un número, un array de strings y una categoría, la fila de datos puede tener el siguiente ejemplo de solicitud:

    "length":3.6,
    "material":"cotton",
    "tag_array": ["abc","def"]
    

    Debes proporcionar un valor para cada atributo incluido en el entrenamiento. El formato de los datos usados para la predicción debe coincidir con el formato que se usa para el entrenamiento. Consulta Formato de datos para predicciones si quieres obtener más detalles.

  • DEPLOYED_MODEL_ID: salida del método predict y se acepta como entrada mediante el método explain. El ID del modelo que se usó para generar la predicción. Si necesitas solicitar explicaciones de una predicción solicitada con anterioridad y tienes más de un modelo implementado, puedes usar este ID a fin de asegurarte de que se muestren las explicaciones para el mismo modelo que proporcionó la predicción anterior.

HTTP method and 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": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

   {
     "predictions": [
      {
         "scores": [
           0.96771615743637085,
           0.032283786684274673
         ],
         "classes": [
           "0",
           "1"
         ]
      }
     ]
     "deployedModelId": "2429510197"
   }
   

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.util.ValueConverter;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.cloud.aiplatform.v1.schema.predict.prediction.TabularClassificationPredictionResult;
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 PredictTabularClassificationSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String instance = "[{ feature_column_a: value, feature_column_b: value}]";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictTabularClassification(instance, project, endpointId);
  }

  static void predictTabularClassification(String instance, String project, String endpointId)
      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();

      Value parameters = Value.newBuilder().setListValue(listValue).build();
      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instanceList, parameters);
      System.out.println("Predict Tabular Classification Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.getDeployedModelId());

      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        TabularClassificationPredictionResult.Builder resultBuilder =
            TabularClassificationPredictionResult.newBuilder();
        TabularClassificationPredictionResult result =
            (TabularClassificationPredictionResult)
                ValueConverter.fromValue(resultBuilder, prediction);

        for (int i = 0; i < result.getClassesCount(); i++) {
          System.out.printf("\tClass: %s", result.getClasses(i));
          System.out.printf("\tScore: %f", result.getScores(i));
        }
      }
    }
  }
}

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 endpointId = 'YOUR_ENDPOINT_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const aiplatform = require('@google-cloud/aiplatform');
const {prediction} =
  aiplatform.protos.google.cloud.aiplatform.v1.schema.predict;

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = 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 predictTablesClassification() {
  // Configure the endpoint resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = helpers.toValue({});

  const instance = helpers.toValue({
    petal_length: '1.4',
    petal_width: '1.3',
    sepal_length: '5.1',
    sepal_width: '2.8',
  });

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict tabular classification response');
  console.log(`\tDeployed model id : ${response.deployedModelId}\n`);
  const predictions = response.predictions;
  console.log('Predictions :');
  for (const predictionResultVal of predictions) {
    const predictionResultObj =
      prediction.TabularClassificationPredictionResult.fromValue(
        predictionResultVal
      );
    for (const [i, class_] of predictionResultObj.classes.entries()) {
      console.log(`\tClass: ${class_}`);
      console.log(`\tScore: ${predictionResultObj.scores[i]}\n\n`);
    }
  }
}
predictTablesClassification();

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 predict_tabular_classification_sample(
    project: str,
    location: str,
    endpoint_name: str,
    instances: List[Dict],
):
    """
    Args
        project: Your project ID or project number.
        location: Region where Endpoint is located. For example, 'us-central1'.
        endpoint_name: A fully qualified endpoint name or endpoint ID. Example: "projects/123/locations/us-central1/endpoints/456" or
               "456" when project and location are initialized or passed.
        instances: A list of one or more instances (examples) to return a prediction for.
    """
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_name)

    response = endpoint.predict(instances=instances)

    for prediction_ in response.predictions:
        print(prediction_)

API: Regresión

gcloud

  1. Crea un archivo llamado “request.json” con el siguiente contenido:

          {
      "instances": [
        {
          PREDICTION_DATA_ROW
        }
      ]
    }
        

    Reemplaza lo siguiente:

    • PREDICTION_DATA_ROW: Un objeto JSON con claves como nombres de funciones y valores como los valores de atributo correspondientes. Por ejemplo, para un conjunto de datos con un número, un array de strings y una categoría, la fila de datos puede tener el siguiente ejemplo de solicitud:

      "age":3.6,
      "sq_ft":5392,
      "code": "90331"
      

      Debes proporcionar un valor para cada atributo incluido en el entrenamiento. El formato de los datos usados para la predicción debe coincidir con el formato que se usa para el entrenamiento. Consulta Formato de datos para predicciones si quieres obtener más detalles.

  2. Ejecute 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

Usa el método endpoints.predict para solicitar una predicción en línea.

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

  • LOCATION_ID: Es la región en la que se encuentra el extremo. Por ejemplo, us-central1
  • PROJECT_ID: El ID del proyecto.
  • ENDPOINT_ID: Es el ID del extremo.
  • PREDICTION_DATA_ROW: Un objeto JSON con claves como nombres de funciones y valores como los valores de atributo correspondientes. Por ejemplo, para un conjunto de datos con un número, un array de strings y una categoría, la fila de datos puede tener el siguiente ejemplo de solicitud:

    "age":3.6,
    "sq_ft":5392,
    "code": "90331"
    

    Debes proporcionar un valor para cada atributo incluido en el entrenamiento. El formato de los datos usados para la predicción debe coincidir con el formato que se usa para el entrenamiento. Consulta Formato de datos para predicciones si quieres obtener más detalles.

  • DEPLOYED_MODEL_ID: salida del método predict y se acepta como entrada mediante el método explain. El ID del modelo que se usó para generar la predicción. Si necesitas solicitar explicaciones de una predicción solicitada con anterioridad y tienes más de un modelo implementado, puedes usar este ID a fin de asegurarte de que se muestren las explicaciones para el mismo modelo que proporcionó la predicción anterior.

HTTP method and 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": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:


{
  "predictions": [
    [
      {
        "value": 65.14233,
        "lower_bound": 4.6572,
        "upper_bound": 164.0279
      }
    ]
  ],
  "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.util.ValueConverter;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.cloud.aiplatform.v1.schema.predict.prediction.TabularRegressionPredictionResult;
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 PredictTabularRegressionSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String instance = "[{ feature_column_a: value, feature_column_b: value}]";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictTabularRegression(instance, project, endpointId);
  }

  static void predictTabularRegression(String instance, String project, String endpointId)
      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();

      Value parameters = Value.newBuilder().setListValue(listValue).build();
      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instanceList, parameters);
      System.out.println("Predict Tabular Regression Response");
      System.out.format("\tDisplay Model Id: %s\n", predictResponse.getDeployedModelId());

      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        TabularRegressionPredictionResult.Builder resultBuilder =
            TabularRegressionPredictionResult.newBuilder();

        TabularRegressionPredictionResult result =
            (TabularRegressionPredictionResult) ValueConverter.fromValue(resultBuilder, prediction);

        System.out.printf("\tUpper bound: %f\n", result.getUpperBound());
        System.out.printf("\tLower bound: %f\n", result.getLowerBound());
        System.out.printf("\tValue: %f\n", result.getValue());
      }
    }
  }
}

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 endpointId = 'YOUR_ENDPOINT_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const aiplatform = require('@google-cloud/aiplatform');
const {prediction} =
  aiplatform.protos.google.cloud.aiplatform.v1.schema.predict;

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = 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 predictTablesRegression() {
  // Configure the endpoint resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = helpers.toValue({});

  // TODO (erschmid): Make this less painful
  const instance = helpers.toValue({
    BOOLEAN_2unique_NULLABLE: false,
    DATETIME_1unique_NULLABLE: '2019-01-01 00:00:00',
    DATE_1unique_NULLABLE: '2019-01-01',
    FLOAT_5000unique_NULLABLE: 1611,
    FLOAT_5000unique_REPEATED: [2320, 1192],
    INTEGER_5000unique_NULLABLE: '8',
    NUMERIC_5000unique_NULLABLE: 16,
    STRING_5000unique_NULLABLE: 'str-2',
    STRUCT_NULLABLE: {
      BOOLEAN_2unique_NULLABLE: false,
      DATE_1unique_NULLABLE: '2019-01-01',
      DATETIME_1unique_NULLABLE: '2019-01-01 00:00:00',
      FLOAT_5000unique_NULLABLE: 1308,
      FLOAT_5000unique_REPEATED: [2323, 1178],
      FLOAT_5000unique_REQUIRED: 3089,
      INTEGER_5000unique_NULLABLE: '1777',
      NUMERIC_5000unique_NULLABLE: 3323,
      TIME_1unique_NULLABLE: '23:59:59.999999',
      STRING_5000unique_NULLABLE: 'str-49',
      TIMESTAMP_1unique_NULLABLE: '1546387199999999',
    },
    TIMESTAMP_1unique_NULLABLE: '1546387199999999',
    TIME_1unique_NULLABLE: '23:59:59.999999',
  });

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict tabular regression response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const predictionResultVal of predictions) {
    const predictionResultObj =
      prediction.TabularRegressionPredictionResult.fromValue(
        predictionResultVal
      );
    console.log(`\tUpper bound: ${predictionResultObj.upper_bound}`);
    console.log(`\tLower bound: ${predictionResultObj.lower_bound}`);
    console.log(`\tLower bound: ${predictionResultObj.value}`);
  }
}
predictTablesRegression();

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 predict_tabular_regression_sample(
    project: str,
    location: str,
    endpoint_name: str,
    instances: List[Dict],
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_name)

    response = endpoint.predict(instances=instances)

    for prediction_ in response.predictions:
        print(prediction_)

Interpreta los resultados de la predicción

Clasificación

Los modelos de clasificación muestran una puntuación de confianza.

La puntuación de confianza comunica cuán fuerte tu modelo asocia cada clase o etiqueta con un elemento de prueba. Cuanto más alto sea el número, mayor será la confianza del modelo de que la etiqueta se debe aplicar a ese elemento. Tú decides qué tan alta debe ser la puntuación de confianza para que aceptes los resultados del modelo.

Regresión

Los modelos de regresión muestran un valor de predicción. En el caso de los destinos de BigQuery, también muestran un intervalo de predicción. El intervalo de predicción proporciona un rango de valores en el cual el modelo tiene un 95% de confianza de que contiene el resultado real.

Obtén una explicación en línea con el modelo implementado

Puedes solicitar una predicción con explicaciones (también llamadas atribuciones de atributos) para ver cómo el modelo llegó a una predicción. Los valores de importancia de los atributos locales indican cuánto contribuyó cada atributo al resultado de la predicción. Las atribuciones de funciones se incluyen en las predicciones de Vertex AI a través de Vertex Explainable AI.

Console

Cuando usas la consola de Google Cloud para solicitar una predicción en línea, los valores de importancia de los atributos locales se muestran de forma automática.

Si usaste los valores de predicción completados previamente, los valores de importancia de los atributos locales son todos iguales a cero. Esto se debe a que los valores completados previamente son los datos de predicción del modelo de referencia, por lo que la predicción que se muestra es el valor de predicción del modelo de referencia.

gcloud

  1. Crea un archivo llamado request.json con el siguiente contenido:

    {
      "instances": [
        {
          PREDICTION_DATA_ROW
        }
      ]
    }
    

    Reemplaza lo siguiente:

    • PREDICTION_DATA_ROW: Un objeto JSON con claves como nombres de funciones y valores como los valores de atributo correspondientes. Por ejemplo, para un conjunto de datos con un número, un array de strings y una categoría, la fila de datos puede tener el siguiente ejemplo de solicitud:

      "length":3.6,
      "material":"cotton",
      "tag_array": ["abc","def"]
      

      Debes proporcionar un valor para cada atributo incluido en el entrenamiento. El formato de los datos usados para la predicción debe coincidir con el formato que se usa para el entrenamiento. Consulta Formato de datos para predicciones si quieres obtener más detalles.

  2. Ejecute 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

En el siguiente ejemplo, se muestra una solicitud de predicción en línea para un modelo de clasificación tabular con atribuciones de funciones locales. El formato de la solicitud es el mismo para los modelos de regresión.

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

  • LOCATION: Es la región en la que se encuentra el extremo. Por ejemplo, us-central1
  • PROJECT: El ID del proyecto.
  • ENDPOINT_ID: Es el ID del extremo.
  • PREDICTION_DATA_ROW: Un objeto JSON con claves como nombres de funciones y valores como los valores de atributo correspondientes. Por ejemplo, para un conjunto de datos con un número, un array de strings y una categoría, la fila de datos puede tener el siguiente ejemplo de solicitud:

    "length":3.6,
    "material":"cotton",
    "tag_array": ["abc","def"]
    

    Debes proporcionar un valor para cada atributo incluido en el entrenamiento. El formato de los datos usados para la predicción debe coincidir con el formato que se usa para el entrenamiento. Consulta Formato de datos para predicciones si quieres obtener más detalles.

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

HTTP method and URL:

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

Cuerpo JSON de la solicitud:

{
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
 

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

Obtén explicaciones para una predicción generada anteriormente

Debido a que las explicaciones aumentan el uso de recursos, te recomendamos reservar explicaciones de solicitud para situaciones en las que las necesitas específicamente. A veces, puede ser útil solicitar explicaciones para un resultado de predicción que ya recibiste, tal vez porque la predicción fue un valor atípico o no tenía sentido.

Si todas tus predicciones provienen del mismo modelo, puedes volver a enviar los datos de la solicitud con las explicaciones solicitadas esta vez. Sin embargo, si tienes varios modelos que muestran predicciones, debes asegurarte de enviar la solicitud de explicación al modelo correcto. Para ver las explicaciones de un modelo en particular, puedes incluir el ID del modelo implementado deployedModelID en tu solicitud, lo que se incluye en la respuesta de la solicitud de predicción original. Ten en cuenta que el ID del modelo implementado es diferente del ID del modelo.

Interpreta los resultados de la explicación

Para calcular la importancia de los atributos locales, primero se calcula la puntuación de predicción de modelo de referencia. Los valores del modelo de referencia se calculan a partir de los datos de entrenamiento, y se usa el valor de la mediana para los atributos numéricos y el modo para los atributos categóricos. La predicción que se genera a partir de los valores del modelo de referencia es la puntuación de predicción del modelo de referencia. Los valores del modelo de referencia se calculan una vez para un modelo y no cambian.

Para una predicción específica, la importancia de los atributos locales de cada atributo indica cuánto agregó o cuánto quitó ese atributo al resultado en comparación con la puntuación de predicción del modelo de referencia. La suma de todos los valores de importancia de los atributos equivale a la diferencia entre la puntuación de predicción del modelo de referencia y el resultado de la predicción.

Para los modelos de clasificación, la puntuación siempre se encuentra entre 0.0 y 1.0, inclusive. Por lo tanto, los valores de importancia de los atributos locales para los modelos de clasificación siempre se encuentran entre -1.0 y 1.0 (inclusive).

Si deseas obtener ejemplos de consultas de atribución de atributos y obtener más información, consulta Atribuciones de atributos para la clasificación y la regresión.

Resultado de ejemplo para predicciones y explicaciones

Clasificación

La carga útil de retorno para una predicción en línea de un modelo de clasificación tabular con importancia de atributos es similar al siguiente ejemplo.

El instanceOutputValue de 0.928652400970459 es la puntuación de confianza de la clase con la puntuación más alta, en este caso class_a. El campo baselineOutputValue contiene la puntuación de predicción del modelo de referencia, 0.808652400970459. El atributo que contribuyó más a este resultado fue feature_3.

{
"predictions": [
  {
    "scores": [
      0.928652400970459,
      0.071347599029541
    ],
    "classes": [
      "class_a",
      "class_b"
    ]
  }
]
"explanations": [
  {
    "attributions": [
      {
        "baselineOutputValue": 0.808652400970459,
        "instanceOutputValue": 0.928652400970459,
        "approximationError":  0.0058915703929231,
        "featureAttributions": {
          "feature_1": 0.012394922231235,
          "feature_2": 0.050212341234556,
          "feature_3": 0.057392736534209,
        },
        "outputIndex": [
          0
        ],
        "outputName": "scores"
      }
    ],
  }
]
"deployedModelId": "234567"
}

Regresión

La carga útil de retorno de una predicción en línea con una importancia de atributos de un modelo de regresión tabular es similar al siguiente ejemplo.

El instanceOutputValue de 1795.1246466281819 es el valor previsto, con los campos lower_bound y upper_bound que proporcionan el intervalo de confianza del 95%. El campo baselineOutputValue contiene la puntuación de predicción del modelo de referencia, 1788.7423095703125. El atributo que contribuyó más a este resultado fue feature_3.

{
"predictions": [
  {
    "value": 1795.1246466281819,
    "lower_bound": 246.32196807861328,
    "upper_bound": 8677.51904296875
  }
]
"explanations": [
  {
    "attributions": [
      {
        "baselineOutputValue": 1788.7423095703125,
        "instanceOutputValue": 1795.1246466281819,
        "approximationError": 0.0038215703911553,
        "featureAttributions": {
          "feature_1": 0.123949222312359,
          "feature_2": 0.802123412345569,
          "feature_3": 5.456264423211472,
        },
        "outputIndex": [
          -1
        ]
      }
    ]
  }
],
"deployedModelId": "345678"
}

¿Qué sigue?