Utiliser un conteneur personnalisé pour l'inférence

Pour personnaliser la façon dont Agent Platform diffuse les inférences en ligne à partir de votre modèle personnalisé, vous pouvez spécifier un conteneur personnalisé au lieu d'un conteneur prédéfini lorsque vous créez une Model ressource. Lorsque vous utilisez un conteneur personnalisé, Agent Platform exécute le conteneur Docker de votre choix sur chaque nœud d'inférence.

Nous vous recommandons d'utiliser un conteneur personnalisé pour n'importe laquelle des raisons suivantes :

• Pour diffuser des inférences à partir d'un modèle de ML entraîné à l'aide d'un framework qui n'est pas disponible en tant que conteneur prédéfini.
• Pour prétraiter les requêtes d'inférence ou post-traiter les inférences générées par votre modèle.
• Pour exécuter un serveur d'inférence écrit dans le langage de programmation de votre choix.
• Pour installer des dépendances que vous souhaitez utiliser pour personnaliser les inférences.

Ce guide explique comment créer un modèle utilisant un conteneur personnalisé. Il ne fournit pas d'instructions détaillées concernant la conception et la création d'une image de conteneur Docker.

Préparer une image de conteneur

Pour créer un Model utilisant un conteneur personnalisé, vous devez fournir une image de conteneur Docker comme base de ce conteneur. Cette image de conteneur doit répondre aux exigences décrites dans Exigences concernant les conteneurs personnalisés.

Si vous envisagez d'utiliser une image de conteneur existante créée par un tiers de confiance, vous pouvez ignorer l'une des sections suivantes, ou les deux.

Créer une image de conteneur

Concevez et créez une image de conteneur Docker répondant aux exigences concernant les images de conteneur.

Pour apprendre les bases de la conception et de la création d'une image de conteneur Docker, consultez le guide de démarrage rapide de la documentation Docker.

Transférer l'image de conteneur vers Artifact Registry

Transférez votre image de conteneur vers un dépôt Artifact Registry.

Apprenez à transférer une image de conteneur vers Artifact Registry.

Créer un Model

Pour créer un Model qui utilise un conteneur personnalisé, effectuez l'une des opérations suivantes :

• Importez un modèle entraîné personnalisé.

• Créez un TrainingPipeline qui exécute un CustomJob et importe les artefacts obtenus en tant que Model.

Les sections suivantes montrent comment configurer les champs d'API associés aux conteneurs personnalisés lors de la création d'un Model de l'une de ces manières.

Champs d'API liés au conteneur

Lorsque vous créez le Model, assurez-vous de configurer le champ containerSpec avec les informations de votre conteneur personnalisé plutôt qu'avec un conteneur prédéfini.

Vous devez spécifier un message ModelContainerSpec dans le champ Model.containerSpec. Dans ce message, vous pouvez spécifier les sous-champs suivants :

imageUri (obligatoire)

URI Artifact Registry de votre image de conteneur

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-image-uri pour spécifier ce champ.

command (facultatif)

Tableau d'un fichier exécutable et d'arguments pour remplacer l'instruction ENTRYPOINT du conteneur. Pour en savoir plus sur la mise en forme de ce champ et son interaction avec le champ args, consultez la documentation de référence de l'API pour ModelContainerSpec.

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-command pour spécifier ce champ.

args (facultatif)

Tableau d'un fichier exécutable et d'arguments pour remplacer le CMD du conteneur. Pour en savoir plus sur la mise en forme de ce champ et son interaction avec le champ command, lisez la documentation de référence de l'API pour ModelContainerSpec.

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-args pour spécifier ce champ.

ports (facultatif)

Tableau de ports : Agent Platform envoie par défaut des vérifications d'activité, des vérifications d'état et des requêtes d'inférenceà votre conteneur sur le premier port répertorié, ou sur le port 8080. Spécifier des ports supplémentaires n'a aucun effet.

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-ports pour spécifier ce champ.

env (facultatif)

Tableau de variables d'environnement que l'instruction ENTRYPOINT du conteneur, ainsi que les champs command et args, peuvent référencer. Pour en savoir plus sur la manière dont d'autres champs peuvent faire référence à ces variables d'environnement, consultez la documentation de référence de l'API pour ModelContainerSpec.

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-env-vars pour spécifier ce champ.

healthRoute (facultatif)

Chemin du serveur HTTP de votre conteneur, vers lequel vous souhaitez qu'Agent Platform envoie des vérifications d'état.

Si vous ne spécifiez pas ce champ, la valeur par défaut est utilisée lors du déploiement du Model en tant que DeployedModel sur une ressource Endpoint, où ENDPOINT est remplacé par le dernier segment du champ name du Endpoint (précédé par endpoints/) et DEPLOYED_MODEL est remplacé par le champ id du DeployedModel./v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-health-route pour spécifier ce champ.

predictRoute (facultatif)

Chemin du serveur HTTP de votre conteneur vers lequel vous souhaitez qu' Agent Platform transfère les requêtes d'inférence.

Si vous ne spécifiez pas ce champ, la valeur par défaut est utilisée lors du déploiement du Model en tant que DeployedModel sur une ressource Endpoint, où ENDPOINT est remplacé par le dernier segment du champ name field du Endpoint (précédé par endpoints/) et DEPLOYED_MODEL est remplacé par le champ id field du DeployedModel./v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-predict-route pour spécifier ce champ.

invokeRoutePrefix (facultatif)

Préfixe de la route d'appel pour le conteneur personnalisé. Si vous définissez ce champ sur "/*", le routage arbitraire est activé pour le modèle. Une fois déployée, toute route non racine sur le serveur de modèles sera accessible avec un appel HTTP d'appel. Par exemple, "/invoke/foo/bar" sera transféré en tant que "/foo/bar" vers le serveur de modèles. Cette fonctionnalité est en version preview publique. Pour créer un modèle compatible avec l'appel, suivez les instructions pour utiliser des routes personnalisées arbitraires.

sharedMemorySizeMb (facultatif)

Quantité de mémoire de VM à réserver dans un volume de mémoire partagée pour le modèle, exprimée en mégaoctets.

La mémoire partagée est un mécanisme de communication inter-processus (IPC) qui permet à plusieurs processus d'accéder à un bloc de mémoire commun et de le manipuler. La quantité de mémoire partagée nécessaire, le cas échéant, constitue un détail d'implémentation de votre conteneur et de votre modèle. Consultez la documentation de votre serveur de modèles pour obtenir des instructions.

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-shared-memory-size-mb pour spécifier ce champ.

startupProbe (facultatif)

Spécification concernant la vérification chargée de contrôler que l'application de conteneur a bien démarré.

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds pour spécifier ce champ.

healthProbe (facultatif)

Spécification concernant la vérification chargée de contrôler si un conteneur est prêt à accepter du trafic.

Si vous exécutez la commande gcloud ai models upload, vous pouvez utiliser le flag --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds pour spécifier ce champ.

Outre les variables que vous avez définies dans le champ Model.containerSpec.env, Agent Platform définit plusieurs autres variables en fonction de votre configuration. Découvrez comment utiliser ces variables d'environnement dans ces champs et dans l'instruction ENTRYPOINT du conteneur.

Exemples d'importation de modèle

Les exemples suivants montrent comment spécifier des champs d'API liés au conteneur lorsque vous importez un modèle.

Remarque : Si vous utilisez un TrainingPipeline pour créer un Model, vous devez spécifier ces champs dans un contexte différent. Vous ne pouvez pas utiliser la Google Cloud CLI pour créer un TrainingPipeline. Découvrez comment créer des ressources TrainingPipeline personnalisées.

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

Le flag --container-image-uri est obligatoire et tous les autres flags commençant par --container- sont facultatifs. Pour en savoir plus sur les valeurs de ces champs, consultez la section précédente de ce guide.

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, 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 Node.js du guide de démarrage rapide d' Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, 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 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 davantage de contexte, consultez le guide d'importation de modèles.

Envoyer des requêtes d'inférence

Pour envoyer une requête d'inférence en ligne à votre Model, suivez les instructions de la section Obtenir des inférences à partir d'un modèle entraîné personnalisé: ce processus fonctionne de la même manière, que vous utilisiez un conteneur personnalisé ou non.

Apprenez-en plus sur les exigences concernant les requêtes et les réponses pour les conteneurs personnalisés.

Étape suivante

• Pour tout savoir sur la conception d'un conteneur personnalisé à utiliser avec Agent Platform, consultez la page Exigences concernant les conteneurs personnalisés.