Importar modelos a Vertex AI

En esta guía se describe cómo importar modelos al registro de modelos de Vertex AI. Una vez que hayas importado el modelo, estará visible en el registro de modelos. Desde el registro de modelos, puedes desplegar el modelo importado en un endpoint y ejecutar inferencias.

Roles obligatorios

Para obtener los permisos que necesitas para importar modelos, pide a tu administrador que te asigne el rol de gestión de identidades y accesos Usuario de Vertex AI (roles/aiplatform.user) en el proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Contenedores precompilados o personalizados

Cuando importas un modelo, lo asocias a un contenedor para que Vertex AI ejecute solicitudes de inferencia. Puedes usar los contenedores precompilados que proporciona Vertex AI o tus propios contenedores personalizados, que puedes compilar y enviar a Artifact Registry.

Puedes usar un contenedor prediseñado si tu modelo cumple los siguientes requisitos:

Si vas a importar un modelo tabular de AutoML que hayas exportado anteriormente, debes usar un contenedor personalizado específico proporcionado por Vertex AI.

De lo contrario, crea un contenedor personalizado o usa uno que ya tengas en Artifact Registry.

Subir artefactos de modelos a Cloud Storage

Debes almacenar los artefactos de tu modelo en un segmento de Cloud Storage cuya región coincida con el endpoint de ubicación que estés usando.

Si tu segmento de Cloud Storage está en un proyecto diferente, debes Google Cloud conceder acceso a Vertex AI para que pueda leer los artefactos de tu modelo.

Si usas un contenedor prediseñado, asegúrate de que los artefactos de tu modelo tengan nombres de archivo que coincidan exactamente con los siguientes ejemplos:

  • SavedModel de TensorFlow: saved_model.pb
  • PyTorch: model.mar
  • scikit-learn: model.joblib
  • XGBoost: model.bst o model.joblib

Más información sobre cómo exportar artefactos de modelos para la inferencia

Importar un modelo con la consola de Google Cloud

Para importar un modelo con la Google Cloud consola, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Modelos de Vertex AI.

    Ir a la página Modelos

  2. Haz clic en Importar.

  3. Seleccione Importar como modelo nuevo para importar un modelo nuevo.

  4. Selecciona Importar como versión nueva para importar un modelo como una versión de otro modelo. Para obtener más información sobre el control de versiones de modelos, consulte el artículo Control de versiones de modelos.

  5. Nombre y región: introduce un nombre para el modelo. Selecciona la región que coincida con la de tu contenedor y con el endpoint de ubicación de Vertex AI que estés usando. Haz clic en Continuar.

  6. Si despliegas Opciones avanzadas, puedes añadir una clave de cifrado gestionada por el cliente.

En función del tipo de contenedor que estés usando, selecciona la pestaña correspondiente a continuación.

Contenedor prediseñado

  1. Selecciona Importar artefactos del modelo a un contenedor predefinido nuevo.

  2. Selecciona el framework del modelo y la versión del framework del modelo que has usado para entrenar el modelo.

  3. Si quieres usar GPUs para publicar inferencias, define el tipo de acelerador como GPUs.

    El tipo de GPU se selecciona más adelante, cuando despliegues el modelo en un endpoint.

  4. Especifica la ruta de Cloud Storage al directorio que contiene los artefactos de tu modelo.

    Por ejemplo, gs://BUCKET_NAME/models/.

  5. Deja en blanco el campo Predecir esquemas.

  6. Para importar tu modelo sin la configuración de Vertex Explainable AI, haz clic en Importar.

    Una vez que se haya completado la importación, el modelo aparecerá en la página Modelos.

    De lo contrario, sigue configurando el modelo introduciendo los ajustes de interpretabilidad en la pestaña Interpretabilidad. Más información sobre los ajustes de explicabilidad

Contenedor personalizado

  1. Selecciona Importar un contenedor personalizado disponible.

  2. Define el URI de la imagen del contenedor.

  3. Si quiere proporcionar artefactos de modelo además de una imagen de contenedor, especifique la ruta de Cloud Storage al directorio que contiene los artefactos de modelo.

    Por ejemplo, gs://BUCKET_NAME/models/.

  4. Especifique valores para cualquiera de los demás campos.

    Consulta más información sobre estos campos opcionales.

  5. Para importar tu modelo sin la configuración de Vertex Explainable AI, haz clic en Importar.

    Una vez que se haya completado la importación, el modelo aparecerá en la página Modelos.

    De lo contrario, sigue configurando el modelo introduciendo los ajustes de interpretabilidad en la pestaña Interpretabilidad. Más información sobre los ajustes de explicabilidad

Contenedor tabular de AutoML

  1. Selecciona Importar un contenedor personalizado disponible.

  2. En el campo Imagen de contenedor, introduce MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.

    Sustituye MULTI_REGION por us, europe o asia para seleccionar el repositorio de Docker del que quieras extraer la imagen de Docker. Cada repositorio proporciona la misma imagen Docker, pero elegir la multirregión de Artifact Registry más cercana a la máquina en la que ejecutas Docker puede reducir la latencia.

  3. En el campo Ubicación del paquete, especifica la ruta de Cloud Storage al directorio que contiene los artefactos de tu modelo.

    La ruta es similar a la del siguiente ejemplo:

    gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/

  4. Deja el resto de los campos en blanco.

  5. Haz clic en Importar.

    Una vez que se haya completado la importación, el modelo aparecerá en la página Modelos. Puedes usar este modelo como cualquier otro modelo tabular de AutoML, pero los modelos tabulares de AutoML importados no admiten Vertex Explainable AI.

Importar un modelo mediante programación

En los siguientes ejemplos se muestra cómo importar un modelo con varias herramientas:

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 \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

Haz los cambios siguientes:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • MODEL_NAME: nombre visible del Model.
  • IMAGE_URI: el URI de la imagen del contenedor que se va a usar para publicar inferencias. Por ejemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Usa un contenedor prediseñado o un contenedor personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: el URI de Cloud Storage (que empieza por gs://) de un directorio de Cloud Storage que contiene los artefactos del modelo.

En el ejemplo anterior se muestran todas las marcas necesarias para importar la mayoría de los modelos. Si no usas un contenedor precompilado para la inferencia, probablemente tengas que especificar algunas marcas opcionales adicionales para que Vertex AI pueda usar tu imagen de contenedor. Estas marcas, que empiezan por --container-, se corresponden con los campos de la Model de tu containerSpec.

REST

Usa el siguiente código de ejemplo para subir un modelo con el método upload del recurso model.

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.
  • MODEL_NAME: nombre visible del Model.
  • MODEL_DESCRIPTION: opcional. Descripción del modelo.
  • IMAGE_URI: el URI de la imagen del contenedor que se va a usar para publicar inferencias. Por ejemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Usa un contenedor prediseñado o un contenedor personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: el URI de Cloud Storage (que empieza por gs://) de un directorio de Cloud Storage que contiene los artefactos del modelo. Esta variable y el campo artifactUri son opcionales si usas un contenedor personalizado.
  • labels: opcional. Cualquier conjunto de pares clave-valor para organizar tus modelos. Por ejemplo:
    • "env": "prod"
    • "tier": "backend"
  • Especifica el LABEL_NAME y el LABEL_VALUE de las etiquetas que quieras aplicar a esta canalización de entrenamiento.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "labels": {
      "LABEL_NAME_1": "LABEL_VALUE_1",
      "LABEL_NAME_2": "LABEL_VALUE_2"
    }
  }
}

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/models:upload"

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/models:upload" | Select-Object -Expand Content

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

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

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 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 importar un modelo con los ajustes de Vertex Explainable AI habilitados, consulta los ejemplos de importación de modelos de Vertex Explainable AI.

Obtener 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 a operaciones de larga duración. Para obtener más información, consulta Trabajar con operaciones de larga duración.

Limitaciones

  • El tamaño máximo de modelo admitido por el registro de modelos es de 1 TB.

Siguientes pasos