Importar modelos a Vertex AI

En esta guía, se describe cómo importar modelos a Model Registry. Después de importar el modelo, se puede ver en Model Registry. Desde Model Registry, puedes implementar el modelo importado en un extremo y ejecutar predicciones.

Roles obligatorios

A fin de obtener los permisos que necesitas para importar modelos, pídele a tu administrador que te otorgue el rol de IAM Usuario de Vertex AI (roles/aiplatform.user) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Contenedores compilados previamente o personalizados

Cuando importas un modelo, lo asocias con un contenedor para que Vertex AI ejecute solicitudes de predicción. Puedes usar contenedores prediseñados proporcionados por Vertex AI o usar tus propios contenedores personalizados que compilas y envías a Artifact Registry.

Puedes usar un contenedor previamente compilado si tu modelo cumple con los siguientes requisitos:

Si importas un modelo tabular de AutoML que exportaste antes, debes usar un contenedor personalizado específico que proporciona Vertex AI.

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

Sube artefactos de modelos en Cloud Storage

Debes almacenar los artefactos de tu modelo en un bucket de Cloud Storage, en el que la región del depósito coincida con el extremo regional que estás usando.

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

Si usas un contenedor previamente compilado, asegúrate de que los artefactos de tu modelo tengan nombres de archivo que coincidan de manera exacta con los siguientes ejemplos:

  • Modelo guardado de TensorFlow: saved_model.pb
  • PyTorch: model.mar
  • scikit-learn: model.joblib o model.pkl
  • XGBoost: model.bst, model.joblib o model.pkl

Obtén más información a fin de exportar artefactos del modelo para la predicción.

Importa un modelo con la consola de Google Cloud

Para importar un modelo con la consola de Google Cloud, haz lo siguiente:

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

    Ir a la página Modelos

  2. Haga clic en Import.

  3. Selecciona 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 un modelo existente. Para obtener más información sobre el control de versiones de modelos, consulta Control de versiones de modelos.

  5. Nombre y región: ingresa un nombre para el modelo. Selecciona la región que coincida con la región de tu bucket y el extremo regional de Vertex AI que uses. Haga clic en Continuar.

  6. Si expandes Opciones avanzadas, tienes la opción de agregar una clave de encriptación administrada por el cliente.

Según el tipo de contenedor que uses, selecciona la pestaña correspondiente que se encuentra a continuación.

Contenedor previamente compilado

  1. Selecciona Importar artefactos del modelo en un contenedor precompilado nuevo.

  2. Selecciona el framework del modelo y la versión del framework del modelo que usaste para entrenar tu modelo.

  3. Si deseas usar GPU para entregar predicciones, establece el tipo de acelerador en GPU.

    Selecciona el tipo de GPU más adelante, cuando implementes el modelo en un extremo.

  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 esquema de predicción.

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

    Una vez que se complete la importación, tu modelo aparecerá en la página Modelos.

    De lo contrario, sigue configurando tu modelo. Para ello, ingresa tu configuración de explicación en la pestaña Explicabilidad. Obtén más información sobre la configuración de explicabilidad.

Contenedor personalizado

  1. Selecciona Importar un contenedor personalizado existente.

  2. Configura el URI de la imagen del contenedor.

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

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

  4. Especifica los valores de cualquiera de los otros campos.

    Obtén más información sobre estos campos opcionales.

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

    Una vez que se complete la importación, tu modelo aparecerá en la página Modelos.

    De lo contrario, sigue configurando tu modelo. Para ello, ingresa tu configuración de explicación en la pestaña Explicabilidad. Obtén más información sobre la configuración de explicabilidad.

Contenedor tabular de AutoML

  1. Selecciona Importar un contenedor personalizado existente.

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

    Reemplaza MULTI_REGION por us, europe o asia para seleccionar el repositorio de Docker desde el que deseas extraer la imagen de Docker. Cada repositorio proporciona la misma imagen de 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 acceso de Cloud Storage al directorio que contiene los artefactos del modelo.

    La ruta de acceso es similar a la del siguiente ejemplo:

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

  4. Deja todos los otros campos en blanco.

  5. Haga clic en Import.

    Una vez que se complete la importación, tu modelo aparecerá en la página Modelos. Puedes usar este modelo como otros modelos tabulares de AutoML, pero los modelos tabulares de AutoML importados no admiten Vertex Explainable AI.

Importa un modelo de manera programática

En los siguientes ejemplos, se muestra cómo importar un modelo mediante 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

Reemplaza lo siguiente:

  • LOCATION_ID: la región en la que usas Vertex AI.
  • MODEL_NAME: Un nombre visible para Model.
  • IMAGE_URI: el URI de la imagen de contenedor que se usará para entregar predicciones. Por ejemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest Usa un contenedor previamente compilado o un contenedor personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: El URI de Cloud Storage (que comienza con gs://) de un directorio en 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 previamente compilado para la predicción, es probable que debas especificar algunas marcas opcionales adicionales a fin de que Vertex AI pueda usar tu imagen de contenedor. Estas marcas, que comienzan con --container-, corresponden a los campos de containerSpec del Model.

REST

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

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

  • LOCATION_ID: la región en la que usas Vertex AI.
  • PROJECT_ID: El ID del proyecto.
  • MODEL_NAME: Un nombre visible para Model.
  • MODEL_DESCRIPTION: Opcional Es una descripción del modelo.
  • IMAGE_URI: el URI de la imagen de contenedor que se usará para entregar predicciones. Por ejemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest Usa un contenedor previamente compilado o un contenedor personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: El URI de Cloud Storage (que comienza con gs://) de un directorio en 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 LABEL_NAME y LABEL_VALUE para las etiquetas que deseas 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 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 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 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 la configuración de Vertex Explainable AI habilitada, consulta los ejemplos de importación de Vertex Explainable AI.

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.

Limitaciones

  • El tamaño máximo admitido del modelo es de 10 GiB.

¿Qué sigue?