Importer des modèles dans Vertex AI

Ce guide explique comment importer des modèles dans Model Registry. Une fois votre modèle importé, il est visible dans Model Registry. À partir de Model Registry, vous pouvez déployer votre modèle importé sur un point de terminaison et exécuter des prédictions.

Rôles requis

Pour obtenir les autorisations nécessaires pour importer des modèles, demandez à votre administrateur de vous attribuer le rôle IAM Utilisateur Vertex AI (roles/aiplatform.user) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Conteneurs prédéfinis ou personnalisés

Lorsque vous importez un modèle, vous l'associez à un conteneur permettant à Vertex AI d'exécuter des requêtes de prédiction. Vous pouvez utiliser des conteneurs prédéfinis fournis par Vertex AI, ou utiliser vos propres conteneurs personnalisés que vous créez et transférez vers Artifact Registry.

Vous pouvez utiliser un conteneur prédéfini si votre modèle répond aux exigences suivantes :

Si vous importez un modèle AutoML tabulaire que vous avez précédemment exporté, vous devez utiliser un conteneur personnalisé spécifique fourni par Vertex AI.

Sinon, créez un conteneur personnalisé ou utilisez un conteneur personnalisé existant que vous avez dans Artifact Registry.

Importer des artefacts de modèle dans Cloud Storage

Vous devez stocker vos artefacts de modèle dans un bucket Cloud Storage, où la région du bucket correspond au point de terminaison régional que vous utilisez.

Si votre bucket Cloud Storage se trouve dans un autre projet Google Cloud, vous devez accorder l'accès à Vertex AI pour lire les artefacts de votre modèle.

Si vous utilisez un conteneur prédéfini, assurez-vous que le nom de vos artefacts de modèles correspond exactement aux exemples suivants :

  • Modèle SavedModel TensorFlow : saved_model.pb
  • PyTorch : model.mar
  • scikit-learn : model.joblib ou model.pkl
  • XGBoost : model.bst, model.joblib ou model.pkl

Découvrez comment exporter des artefacts de modèle pour la prédiction.

Importer un modèle à l'aide de la console Google Cloud

Pour importer un modèle à l'aide de la console Google Cloud, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page Modèles de Vertex AI.

    Accéder à la page des modèles

  2. Cliquez sur Importer.

  3. Sélectionnez Importer en tant que nouveau modèle pour importer un nouveau modèle.

  4. Sélectionnez Importer en tant que nouvelle version pour importer un modèle en tant que version d'un modèle existant. Pour en savoir plus sur la gestion des versions de modèles, consultez la section Gestion des versions de modèles.

  5. Nom et région : saisissez le nom du modèle. Sélectionnez la région qui correspond à la région de votre bucket et au point de terminaison régional Vertex AI que vous utilisez. Cliquez sur Continue (Continuer).

  6. En développant Options avancées, vous pouvez éventuellement décider d'ajouter une clé de chiffrement gérée par le client.

Selon le type de conteneur que vous utilisez, sélectionnez l'onglet approprié ci-dessous.

Conteneur prédéfini

  1. Sélectionnez Importer des artefacts de modèle dans un nouveau conteneur prédéfini.

  2. Sélectionnez le framework de modèle et la version du framework de modèle que vous avez utilisés pour entraîner le modèle.

  3. Si vous souhaitez utiliser des GPU pour diffuser des prédictions, définissez le type d'accélérateur sur GPU.

    Vous sélectionnerez le type de GPU ultérieurement, lorsque vous déploierez le modèle sur un point de terminaison.

  4. Indiquez le chemin d'accès Cloud Storage au répertoire contenant les artefacts de votre modèle.

    Exemple : gs://BUCKET_NAME/models/

  5. Laissez le champ Predict schemata (Schémas de prédiction) vide.

  6. Pour importer votre modèle sans paramètres Vertex Explainable AI, cliquez sur Importer.

    Une fois l'importation terminée, votre modèle s'affiche sur la page Modèles.

    Sinon, poursuivez la configuration du modèle en saisissant vos paramètres d'explicabilité dans l'onglet Explicabilité. En savoir plus sur les paramètres d'explicabilité.

Conteneur personnalisé

  1. Sélectionnez Importer un conteneur personnalisé existant.

  2. Définissez l'URI de l'image de conteneur.

  3. Si vous souhaitez fournir des artefacts de modèle en plus d'une image de conteneur, spécifiez le chemin d'accès Cloud Storage au répertoire contenant les artefacts de votre modèle.

    Par exemple, gs://BUCKET_NAME/models/.

  4. Spécifiez les valeurs de tous les autres champs.

    Pour en savoir plus sur ces champs facultatifs, cliquez ici.

  5. Pour importer votre modèle sans paramètres Vertex Explainable AI, cliquez sur Importer.

    Une fois l'importation terminée, votre modèle s'affiche sur la page Modèles.

    Sinon, poursuivez la configuration du modèle en saisissant vos paramètres d'explicabilité dans l'onglet Explicabilité. En savoir plus sur les paramètres d'explicabilité.

Conteneur tabulaire AutoML

  1. Sélectionnez Importer un conteneur personnalisé existant.

  2. Dans le champ Image du conteneur, saisissez MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.

    Remplacez MULTI_REGION par us, europe ou asia pour sélectionner le dépôt Docker à partir duquel vous souhaitez extraire l'image Docker. Chaque dépôt fournit la même image Docker, mais le choix de l'emplacement multirégional de Artifact Registry le plus proche de la machine sur laquelle vous exécutez Docker est susceptible de réduire la latence.

  3. Dans le champ Emplacement du package, spécifiez le chemin d'accès Cloud Storage vers le répertoire contenant les artefacts de votre modèle.

    Le chemin d'accès ressemble à l'exemple suivant :

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

  4. Laissez tous les autres champs vides.

  5. Cliquez sur Importer.

    Une fois l'importation terminée, votre modèle s'affiche sur la page Modèles. Vous pouvez utiliser ce modèle de la même manière que d'autres modèles tabulaires AutoML, à l'exception des modèles tabulaires AutoML importés n'étant pas compatibles avec Vertex Explainable AI.

Importer un modèle de manière automatisée

Les exemples suivants montrent comment importer un modèle à l'aide de divers outils :

gcloud

L'exemple suivant utilise la commande 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

Remplacez l'élément suivant :

  • LOCATION_ID : région dans laquelle vous utilisez Vertex AI.
  • MODEL_NAME : nom à afficher pour l'objet Model.
  • IMAGE_URI : URI de l'image de conteneur à utiliser pour diffuser les prédictions. Exemple : us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Utilisez un conteneur prédéfini ou un conteneur personnalisé.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY : URI Cloud Storage (commençant par gs://) d'un répertoire Cloud Storage contenant les artefacts de modèle.

L'exemple précédent montre toutes les options nécessaires pour importer la plupart des modèles. Si vous n'utilisez pas de conteneur prédéfini pour la prédiction, vous devrez probablement spécifier des options facultatives supplémentaires afin de permettre à AI Platform d'utiliser votre image de conteneur. Ces options, qui commencent par --container-, correspondent aux champs du containerSpec de votre Model.

REST

Utilisez l'exemple de code suivant pour importer un modèle à l'aide de la méthode upload de la ressource model.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION_ID : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : l'ID de votre projet.
  • MODEL_NAME : nom à afficher pour l'objet Model.
  • MODEL_DESCRIPTION : facultatif. Description du modèle.
  • IMAGE_URI : URI de l'image de conteneur à utiliser pour diffuser les prédictions. Exemple : us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Utilisez un conteneur prédéfini ou un conteneur personnalisé.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY : URI Cloud Storage (commençant par gs://) d'un répertoire Cloud Storage contenant les artefacts de modèle. Cette variable et le champ artifactUri sont facultatifs si vous utilisez un conteneur personnalisé.
  • labels : facultatif. Ensemble de paires clé/valeur pour organiser vos modèles. Exemple :
    • "env" : "prod"
    • "tier" : "backend"
  • Spécifiez les éléments LABEL_NAME et LABEL_VALUE pour toutes les étiquettes que vous souhaitez appliquer à ce pipeline d'entraînement.

Méthode HTTP et URL :

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

Corps JSON de la requête : 

{
  "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"
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Node.js.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'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

Pour importer un modèle avec les paramètres Vertex Explainable AI activés, reportez-vous aux exemples d'importation de modèles Vertex Explainable AI.

Obtenir l'état de l'opération

Certaines requêtes démarrent des opérations de longue durée qui nécessitent du temps. Ces requêtes renvoient un nom d'opération, que vous pouvez utiliser pour afficher l'état de l'opération ou pour annuler l'opération. Vertex AI propose des méthodes d'assistance pour appeler les opérations de longue durée. Pour en savoir plus, consultez la section Travailler avec des opérations de longue durée.

Limites

  • La taille maximale autorisée pour le modèle est de 10 GiB.

Étapes suivantes