Usar un contenedor personalizado para la predicción

Para personalizar la forma en que Vertex AI entrega predicciones en línea desde tu modelo personalizado, puedes especificar un contenedor personalizado en lugar de un contenedor compilado previamente cuando creas un recurso Model. Cuando usas un contenedor personalizado, Vertex AI ejecuta un contenedor de Docker de tu elección en cada nodo de predicción.

Se recomienda usar un contenedor personalizado por las siguientes razones:

• para entregar predicciones a partir de un modelo de AA entrenado con un framework que no está disponible como contenedor compilado previamente
• procesar con anterioridad las solicitudes de predicción o procesar con posterioridad las predicciones que genera el modelo
• ejecutar un servidor de predicción escrito en el lenguaje de programación que quieras
• instalar las dependencias que deseas usar para personalizar la predicción

En esta guía, se describe cómo crear un modelo que use un contenedor personalizado. No proporciona instrucciones detalladas para diseñar y crear una imagen de contenedor de Docker.

Prepara una imagen de contenedor

Para crear un Model que use un contenedor personalizado, debes proporcionar una imagen de contenedor de Docker como base de ese contenedor. Esta imagen del contenedor debe cumplir con los requisitos descritos en los requisitos personalizados para contenedores.

Si planeas usar una imagen de contenedor existente creada por un tercero de confianza, es posible que puedas omitir una o ambas de las siguientes secciones.

Crea una imagen de contenedor

Diseña y compila una imagen de contenedor de Docker que cumpla con los requisitos de imagen de contenedor.

Para conocer los conceptos básicos del diseño y la compilación de una imagen de contenedor de Docker, consulta la guía de inicio rápido de la documentación de Docker.

Envía la imagen del contenedor a Artifact Registry

Envía tu imagen de contenedor a un repositorio de Artifact Registry.

Obtén información para enviar una imagen de contenedor a Artifact Registry.

Crea una Model

Para crear un Model que use un contenedor personalizado, realiza una de las siguientes acciones:

• Importa un modelo con entrenamiento personalizado.

• Crea un TrainingPipeline que ejecute un CustomJob y, luego, importe los artefactos resultantes como un Model.

En las secciones siguientes, se muestra cómo configurar los campos de API relacionados con contenedores personalizados cuando creas un Model de una de estas formas.

Campos de API relacionados con contenedores

Cuando creas el Model, asegúrate de configurar el campocontainerSpec con tus detalles de contenedor personalizados, en lugar de con un contenedor compilado previamente.

Debes especificar un mensaje ModelContainerSpec en el campo Model.containerSpec. En este mensaje, puedes especificar los siguientes subcampos:

imageUri (obligatorio)

El URI de Artifact Registry de la imagen de contenedor.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-image-uri para especificar este campo.

command (opcional)

Es un arreglo de un ejecutable y argumentos para anular la instrucción ENTRYPOINT del contenedor. Para obtener más información sobre cómo dar formato a este campo y cómo interactúa con el campo args, lee la referencia de la API para ModelContainerSpec.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-command para especificar este campo.

args (opcional)

Es un arreglo de un ejecutable y argumentos para anular el CMD del contenedor. Si deseas obtener más información sobre cómo dar formato a este campo y cómo interactúa con command, lee la referencia de la API para ModelContainerSpec.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-args para especificar este campo.

ports (opcional)

Un array de puertos. Vertex AI envía verificaciones de actividad, verificaciones de estado y solicitudes de predicción al contenedor en el primer puerto de la lista o a 8080 de forma predeterminada. La especificación de puertos adicionales no tiene efecto.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-ports para especificar este campo.

env (opcional)

Un array de variables de entorno a las que pueden hacer referencia la instrucción ENTRYPOINT del contenedor, así como los campos command y args. Para obtener más información sobre cómo otros campos pueden hacer referencia a estas variables de entorno, lee la referencia de la API para ModelContainerSpec.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-env-vars para especificar este campo.

healthRoute (opcional)

La ruta de acceso en el servidor HTTP de tu contenedor al que deseas que Vertex AI envíe verificaciones de estado.

Si no especificas este campo, cuando implementas Model como DeployedModel en un recurso Endpoint, la configuración predeterminada es /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL, en la que ENDPOINT se reemplaza por el último segmento del campo name de Endpoint (después de endpoints/) y DEPLOYED_MODEL se reemplaza por el campo id de DeployedModel.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-health-route para especificar este campo.

predictRoute (opcional)

La ruta del servidor HTTP del contenedor al que deseas que Vertex AI reenvíe las solicitudes de predicción.

Si no especificas este campo, cuando implementas Model como DeployedModel en un recurso Endpoint, la configuración predeterminada es /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict, en la que ENDPOINT se reemplaza por el último segmento del campo name de Endpoint (después de endpoints/) y DEPLOYED_MODEL se reemplaza por el campo id de DeployedModel.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-predict-route para especificar este campo.

sharedMemorySizeMb (opcional)

La cantidad de memoria de VM que se reservará en un volumen de memoria compartida para el modelo en megabytes.

La memoria compartida es un mecanismo de comunicación entre procesos (IPC) que permite que varios procesos accedan a un bloque común de memoria y lo manipulen. La cantidad de memoria compartida necesaria, si la hay, es un detalle de implementación de tu contenedor y modelo. Consulta la documentación de tu servidor de modelos para obtener lineamientos.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-shared-memory-size-mb para especificar este campo.

startupProbe (opcional)

Especificación para el sondeo que verifica si se inició la aplicación de contenedor.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds para especificar este campo.

healthProbe (opcional)

Especificación del sondeo que verifica si un contenedor está listo para aceptar tráfico.

Si usas el comando gcloud ai models upload, puedes usar la marca --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds para especificar este campo.

Además de las variables que estableces en el campo Model.containerSpec.env, Vertex AI establece muchas otras variables según la configuración. Obtén más información para usar estas variables de entorno en estos campos y en la instrucción ENTRYPOINT del contenedor.

Ejemplos de importación de modelos

En los siguientes ejemplos, se muestra cómo especificar campos de API relacionados con contenedores cuando importas un modelo.

Nota: Si usas un TrainingPipeline para crear una Model, debes especificar estos campos en un contexto diferente. No puedes usar Google Cloud CLI para crear una TrainingPipeline. Obtén más información para crear recursos de TrainingPipeline personalizados.

gcloud

En el siguiente ejemplo, se usa el comando gcloud ai models upload:

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --container-command=COMMAND \
  --container-args=ARGS \
  --container-ports=PORTS \
  --container-env-vars=ENV \
  --container-health-route=HEALTH_ROUTE \
  --container-predict-route=PREDICT_ROUTE \
  --container-shared-memory-size-mb=SHARED_MEMORY_SIZE \
  --container-startup-probe-exec=STARTUP_PROBE_EXEC \
  --container-startup-probe-period-seconds=STARTUP_PROBE_PERIOD \
  --container-startup-probe-timeout-seconds=STARTUP_PROBE_TIMEOUT \
  --container-health-probe-exec=HEALTH_PROBE_EXEC \
  --container-health-probe-period-seconds=HEALTH_PROBE_PERIOD \
  --container-health-probe-timeout-seconds=HEALTH_PROBE_TIMEOUT \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

La marca --container-image-uri es obligatoria. Todas las demás marcas que comienzan con --container- son opcionales. Para obtener más información sobre los valores de estos campos, consulta la sección anterior a esta guía.

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.LocationName;
import com.google.cloud.aiplatform.v1.Model;
import com.google.cloud.aiplatform.v1.ModelContainerSpec;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import com.google.cloud.aiplatform.v1.UploadModelOperationMetadata;
import com.google.cloud.aiplatform.v1.UploadModelResponse;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UploadModelSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String modelDisplayName = "YOUR_MODEL_DISPLAY_NAME";
    String metadataSchemaUri =
        "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml";
    String imageUri = "YOUR_IMAGE_URI";
    String artifactUri = "gs://your-gcs-bucket/artifact_path";
    uploadModel(project, modelDisplayName, metadataSchemaUri, imageUri, artifactUri);
  }

  static void uploadModel(
      String project,
      String modelDisplayName,
      String metadataSchemaUri,
      String imageUri,
      String artifactUri)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.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 (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);

      ModelContainerSpec modelContainerSpec =
          ModelContainerSpec.newBuilder().setImageUri(imageUri).build();

      Model model =
          Model.newBuilder()
              .setDisplayName(modelDisplayName)
              .setMetadataSchemaUri(metadataSchemaUri)
              .setArtifactUri(artifactUri)
              .setContainerSpec(modelContainerSpec)
              .build();

      OperationFuture<UploadModelResponse, UploadModelOperationMetadata> uploadModelResponseFuture =
          modelServiceClient.uploadModelAsync(locationName, model);
      System.out.format(
          "Operation name: %s\n", uploadModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      UploadModelResponse uploadModelResponse = uploadModelResponseFuture.get(5, TimeUnit.MINUTES);

      System.out.println("Upload Model Response");
      System.out.format("Model: %s\n", uploadModelResponse.getModel());
    }
  }
}

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.\
 */

// const modelDisplayName = 'YOUR_MODEL_DISPLAY_NAME';
// const metadataSchemaUri = 'YOUR_METADATA_SCHEMA_URI';
// const imageUri = 'YOUR_IMAGE_URI';
// const artifactUri = 'YOUR_ARTIFACT_URI';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

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

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

// Instantiates a client
const modelServiceClient = new ModelServiceClient(clientOptions);

async function uploadModel() {
  // Configure the parent resources
  const parent = `projects/${project}/locations/${location}`;
  // Configure the model resources
  const model = {
    displayName: modelDisplayName,
    metadataSchemaUri: '',
    artifactUri: artifactUri,
    containerSpec: {
      imageUri: imageUri,
      command: [],
      args: [],
      env: [],
      ports: [],
      predictRoute: '',
      healthRoute: '',
    },
  };
  const request = {
    parent,
    model,
  };

  console.log('PARENT AND MODEL');
  console.log(parent, model);
  // Upload Model request
  const [response] = await modelServiceClient.uploadModel(request);
  console.log(`Long running operation : ${response.name}`);

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

  console.log('Upload model response ');
  console.log(`\tModel : ${result.model}`);
}
uploadModel();

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.

from typing import Dict, Optional, Sequence

from google.cloud import aiplatform
from google.cloud.aiplatform import explain


def upload_model_sample(
    project: str,
    location: str,
    display_name: str,
    serving_container_image_uri: str,
    artifact_uri: Optional[str] = None,
    serving_container_predict_route: Optional[str] = None,
    serving_container_health_route: Optional[str] = None,
    description: Optional[str] = None,
    serving_container_command: Optional[Sequence[str]] = None,
    serving_container_args: Optional[Sequence[str]] = None,
    serving_container_environment_variables: Optional[Dict[str, str]] = None,
    serving_container_ports: Optional[Sequence[int]] = None,
    instance_schema_uri: Optional[str] = None,
    parameters_schema_uri: Optional[str] = None,
    prediction_schema_uri: Optional[str] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    sync: bool = True,
):

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

    model = aiplatform.Model.upload(
        display_name=display_name,
        artifact_uri=artifact_uri,
        serving_container_image_uri=serving_container_image_uri,
        serving_container_predict_route=serving_container_predict_route,
        serving_container_health_route=serving_container_health_route,
        instance_schema_uri=instance_schema_uri,
        parameters_schema_uri=parameters_schema_uri,
        prediction_schema_uri=prediction_schema_uri,
        description=description,
        serving_container_command=serving_container_command,
        serving_container_args=serving_container_args,
        serving_container_environment_variables=serving_container_environment_variables,
        serving_container_ports=serving_container_ports,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        sync=sync,
    )

    model.wait()

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

Para obtener más información, consulta la Guía de importación de modelos.

Envía solicitudes de predicción

Para enviar una solicitud de predicción en línea a tu Model, sigue las instrucciones en Obtén predicciones de un modelo entrenado personalizado: este proceso funciona de la misma manera, independientemente de que uses un contenedor personalizado.

Obtén más información sobre los requisitos de solicitud y respuesta de predicción para contenedores personalizados.

¿Qué sigue?

• Si deseas obtener información sobre todo lo que debes considerar cuando diseñas un contenedor personalizado para usar con Vertex AI, lee Requisitos personalizados para contenedores.