Exigences concernant l'utilisation de conteneurs personnalisés pour la prédiction

Remarque : Il s'agit de la version 1.0.0 de ce document. Celui-ci est mis à jour conformément à la gestion sémantique des versions.

Pour utiliser un conteneur personnalisé afin de réaliser des prédictions à partir d'un modèle personnalisé, vous devez fournir à Vertex AI une image de conteneur Docker qui exécute un serveur HTTP. Ce document décrit les conditions requises pour qu'une image de conteneur puisse être compatible avec Vertex AI. Le document décrit également la manière dont Vertex AI interagit avec votre conteneur personnalisé une fois celui-ci lancé. Ce document décrit les éléments à prendre en compte lors de la conception d'une image de conteneur à utiliser avec Vertex AI.

Pour découvrir comment utiliser une image de conteneur personnalisé pour diffuser des prédictions, consultez la section Utiliser un conteneur personnalisé.

Exigences relatives aux images de conteneurs

Lorsque votre image de conteneur Docker s'exécute en tant que conteneur, celui-ci doit exécuter un serveur HTTP. Plus précisément, le conteneur doit écouter les vérifications de l'activité, les vérifications de l'état et les requêtes de prédiction, et y répondre. Les sous-sections suivantes décrivent ces exigences en détail.

Pour mettre en œuvre le serveur HTTP, vous pouvez utiliser n'importe quel langage de programmation, à condition de répondre aux exigences décrites dans cette section. Par exemple, vous pouvez écrire un serveur HTTP personnalisé à l'aide d'un framework Web tel que Flask ou utiliser un logiciel de diffusion de machine learning (ML) exécutant un serveur HTTP, tel que TensorFlow Serving, TorchServe ou KFServe Python Server.

Exécuter le serveur HTTP

Vous pouvez exécuter un serveur HTTP à l'aide d'une instruction ENTRYPOINT, d'une instruction CMD, ou des deux dans le fichier Dockerfile que vous utilisez pour créer votre image de conteneur. Apprenez-en plus sur l'interaction entre CMD et ENTRYPOINT.

Vous pouvez également spécifier les champs containerSpec.command et containerSpec.args lorsque vous créez votre ressource Model afin de remplacer, respectivement, les ENTRYPOINT et CMD de votre image du conteneur. Spécifier l'un de ces champs vous permet d'utiliser une image de conteneur qui ne répondrait pas sinon aux exigences en raison d'un ENTRYPOINT ou d'un CMD incompatible (ou inexistant).

Quelle que soit la commande exécutée par votre conteneur au démarrage, assurez-vous que l'instruction ENTRYPOINT s'exécute indéfiniment. Par exemple, n'exécutez pas de commande qui démarre un serveur HTTP en arrière-plan, puis se ferme. Le cas échéant, le conteneur se ferme immédiatement après son démarrage.

Votre serveur HTTP doit écouter les requêtes sur 0.0.0.0, sur le port de votre choix. Lorsque vous créez un Model, spécifiez ce port dans le champ containerSpec.ports. Pour savoir comment le conteneur peut accéder à cette valeur, lisez la section du présent document concernant la variable d'environnement AIP_HTTP_PORT.

Vérifications de vivacité

Vertex AI effectue une vérification de l'activité lorsque votre conteneur commence à s'assurer que votre serveur est en cours d'exécution. Lorsque vous déployez un modèle personnalisé entraîné sur une ressource Endpoint, Vertex AI utilise une vérification d'activité TCP pour tenter d'établir une connexion TCP à votre conteneur sur le port configuré. La vérification utilise jusqu'à quatre tentatives pour établir une connexion, en attendant 10 secondes après chaque échec. Si la vérification n'a pas encore établi de connexion à ce stade, l'IA Vertex redémarre votre conteneur.

Votre serveur HTTP ne nécessite aucun comportement spécial pour gérer ces vérifications. Tant qu'il écoute les requêtes sur le port configuré, la vérification d'activité peut établir une connexion.

Vérifications d'état

Vous pouvez éventuellement spécifier startup_probe ou health_probe.

La vérification de démarrage vérifie si l'application de conteneur a bien démarré. Si la vérification de démarrage n'est pas spécifiée, aucun contrôle de bon démarrage n'est effectué et les vérifications d'état commencent immédiatement. Si la vérification de démarrage est spécifiée, les vérifications d'état ne commencent pas tant que la vérification de démarrage n'a pas été concluante.

Les anciennes applications pouvant nécessiter un temps de démarrage supplémentaire lors de leur première initialisation doivent configurer une vérification de démarrage. Par exemple, si l'application doit copier les artefacts de modèle à partir d'une source externe, une vérification de démarrage doit être configurée pour renvoyer un résultat concluant une fois l'initialisation terminée.

La vérification d'état vérifie si un conteneur est prêt à accepter du trafic. Si la vérification d'état n'est pas fournie, Vertex AI utilise les vérifications d'état par défaut, comme décrit dans la section Vérifications d'état par défaut.

Les anciennes applications qui ne renvoient pas 200 OK pour indiquer que le modèle est chargé et prêt à accepter du trafic doivent configurer une vérification d'état. Par exemple, une application peut renvoyer 200 OK pour indiquer la réussite, même si l'état de chargement réel du modèle figurant dans le corps de la réponse indique que le modèle peut ne pas être chargé et donc ne pas être prêt à accepter le trafic. Dans ce cas, une vérification d'état doit être configurée pour ne renvoyer un résultat de réussite que lorsque le modèle est chargé et prêt à diffuser du trafic.

Pour effectuer une vérification, Vertex AI exécute la commande exec spécifiée dans le conteneur cible. Si la commande aboutit, elle renvoie 0, et le conteneur est considéré comme actif et opérationnel.

Vérifications d'état par défaut

Par défaut, Vertex AI effectue par intermittence des vérifications d'état sur votre serveur HTTP pendant son exécution, afin de s'assurer qu'il est prêt à gérer les requêtes de prédiction. Le service utilise une vérification d'état pour envoyer des requêtes HTTP GET à un chemin de vérification d'état configurable sur votre serveur. Spécifiez ce chemin d'accès dans le champ containerSpec.healthRoute lorsque vous créez un Model. Pour savoir comment le conteneur peut accéder à cette valeur, lisez la section du présent document concernant la variable d'environnement AIP_HEALTH_ROUTE.

Configurez le serveur HTTP pour qu'il réponde à chaque requête de vérification d'état comme suit :

• Si le serveur est prêt à traiter les requêtes de prédiction, répondez dans un délai de 10 secondes en utilisant le code d'état 200 OK. Le contenu du corps de la réponse n'a pas d'importance. Vertex AI les ignore.

  Cette réponse signifie que le serveur est opérationnel.

• Si le serveur n'est pas prêt à gérer les requêtes de prédiction, ne répondez pas à la requête de vérification d'état dans le délai de 10 secondes et n'envoyez aucun code d'état, sauf 200 OK. Par exemple, répondez avec le code d'état 503 Service Unavailable.

  Cette réponse (ou le manque de réponse) signifie que le serveur n'est pas opérationnel.

Si la vérification d'état reçoit une réponse non opérationnelle de votre serveur (ou en cas d'absence de réponse sous 10 secondes), elle envoie jusqu'à trois vérifications d'état supplémentaires à intervalles de 10 secondes. Pendant cette période, Vertex AI considère que votre serveur est opérationnel. Si la vérification reçoit une réponse opérationnelle à l'une de ces vérifications, elle reprend les vérifications d'état intermittentes planifiées. Toutefois, si la vérification reçoit quatre réponses non opérationnelles consécutives, Vertex AI arrête d'acheminer le trafic de prédiction vers le conteneur. (Si la ressource DeployedModel est mise à l'échelle pour utiliser plusieurs nœuds de prédiction, Vertex AI achemine les requêtes de prédiction vers d'autres conteneurs opérationnels.)

Vertex AI ne redémarre pas le conteneur. La vérification d'état continue d'envoyer des requêtes de vérification d'état intermittentes au serveur non opérationnel. S'il reçoit une réponse opérationnelle, il marque que ce conteneur est opérationnel et recommence à acheminer le trafic de prédiction vers celui-ci.

Conseils pratiques

Dans certains cas, il est suffisant que le serveur HTTP de votre conteneur réponde toujours avec le code d'état 200 OK aux vérifications d'état. Si votre conteneur charge des ressources avant de démarrer le serveur, il n'est pas opérationnel pendant la période de démarrage et pendant les périodes où le serveur HTTP échoue. Dans les autres cas, il répond avec un état opérationnel.

Dans le cas d'une configuration plus sophistiquée, vous pouvez concevoir de manière intentionnelle le serveur HTTP pour qu'il réponde à des vérifications d'état avec un état non opérationnel à certains moments. Par exemple, vous pouvez bloquer le trafic de prédiction vers un nœud pendant une période donnée pour que le conteneur puisse effectuer la maintenance.

Requêtes de prédiction

Lorsqu'un client envoie une requête projects.locations.endpoints.predict à l'API Vertex AI, l'IA Vertex transfère cette requête sous forme de requête HTTP POST vers un chemin de prédiction configurable. sur votre serveur. Spécifiez ce chemin d'accès dans le champ containerSpec.predictRoute lorsque vous créez un Model. Pour savoir comment le conteneur peut accéder à cette valeur, lisez la section du présent document concernant la variable d'environnement AIP_PREDICT_ROUTE.

Exigences concernant les demandes

Si le modèle est déployé sur un point de terminaison public, la taille de chaque requête de prédiction ne doit pas dépasser 1,5 Mo. Le serveur HTTP doit accepter les requêtes de prédiction comportant l'en-tête HTTP Content-Type: application/json et les corps JSON au format suivant :

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

Dans ces demandes :

• INSTANCES est un tableau contenant une ou plusieurs valeurs JSON de n'importe quel type. Chaque valeur représente une instance pour laquelle vous fournissez une prédiction.

• PARAMETERS est un objet JSON contenant tous les paramètres dont votre conteneur a besoin pour diffuser des prédictions sur les instances. Vertex AI considère que le champ parameters est facultatif. Vous pouvez donc concevoir votre conteneur pour qu'il l'exige, pour qu'il ne l'utilise que lorsqu'il est fourni ou pour l'ignorer.

En savoir plus sur les exigences concernant le corps de la requête

Exigences concernant les réponses

Si le modèle est déployé sur un point de terminaison public, la taille de chaque réponse de prédiction ne doit pas dépasser 1,5 Mo. Le serveur HTTP doit envoyer des réponses avec des corps JSON au format suivant :

{
  "predictions": PREDICTIONS
}

Dans ces réponses, remplacez PREDICTIONS par un tableau de valeurs JSON représentant les prédictions générées par votre conteneur pour chacune des INSTANCES de la requête correspondante.

Une fois que votre serveur HTTP a envoyé cette réponse, Vertex AI ajoute un champ deployedModelId à la réponse avant de la renvoyer au client. Ce champ spécifie quel DeployedModel situé sur un Endpoint envoie la réponse. Apprenez-en plus sur le format du corps de la réponse.

Remarque : Si votre conteneur ne répond pas à ces exigences pour recevoir des requêtes et envoyer des réponses, vous pouvez toujours l'utiliser pour les prédictions brutes.

Exigences relatives à la publication d'images de conteneurs

Vous devez transférer votre image de conteneur vers Artifact Registry pour l'utiliser avec Vertex AI. Apprenez à transférer une image de conteneur vers Artifact Registry.

En particulier, vous devez transférer l'image de conteneur vers un dépôt qui répond aux exigences suivantes en termes d'emplacement et d'autorisations.

Emplacement

Lorsque vous utilisez Artifact Registry, le dépôt doit utiliser une région correspondant au point de terminaison régional sur lequel vous prévoyez de créer un Model. Par exemple, si vous envisagez de créer un Model sur le point de terminaison us-central1-aiplatform.googleapis.com, le nom complet de votre image de conteneur doit commencer par us-central1-docker.pkg.dev/. N'utilisez pas de dépôt multirégional pour votre image de conteneur.

Autorisations

Vertex AI doit être autorisée à extraire l'image du conteneur lorsque vous créez un Model. Plus précisément, l'agent de service Vertex AI de votre projet doit disposer des autorisations du rôle de lecteur d'Artifact Registry (roles/artifactregistry.reader) pour le dépôt de l'image du conteneur.

Vertex AI utilise l'agent de service Vertex AI pour votre projet afin d'interagir avec d'autres services Google Cloud. Ce compte de service possède l'adresse e-mail [e-mail], où PROJECT_NUMBER est remplacé par le numéro du projet de votre projet d'IA Vertex.

Si vous avez transféré votre image de conteneur vers le projet Google Cloud sur lequel vous utilisez Vertex AI, vous n'avez pas besoin de configurer ces autorisations. Les autorisations par défaut accordées à l'agent de service Vertex AI sont suffisantes.

Par ailleurs, si vous avez transféré votre image de conteneur vers un projet Google Cloud différent de celui sur lequel vous utilisez Vertex AI, vous devez accorder le rôle "Lecteur Artifact Registry" pour le dépôt Artifact Registry à l'agent de service Vertex AI.

Remarque : Même si vous envisagez d'utiliser un compte de service personnalisé dans votre conteneur personnalisé, il n'est pas nécessaire de lui accorder des autorisations pour Artifact Registry. Seul l'argent de service géré par Google a besoin de ces autorisations. Vertex AI n'utilise pas votre compte de service personnalisé pour extraire des images de conteneur. Il n'utilise que le compte de service personnalisé pour exécuter le code de diffusion de votre modèle.

Accéder aux artefacts de modèle

Lorsque vous créez un modèle personnalisé Model sans conteneur personnalisé, vous devez spécifier l'URI d'un répertoire Cloud Storage contenant des artefacts de modèle en utilisant le champ artifactUri. Lorsque vous créez un Model avec un conteneur personnalisé, la spécification d'artefacts de modèle dans Cloud Storage est facultative.

Si l'image de conteneur inclut les artefacts de modèle nécessaires à la diffusion des prédictions, il est inutile de charger les fichiers à partir de Cloud Storage. Toutefois, si vous fournissez des artefacts de modèle en spécifiant le champ artifactUri, le conteneur doit charger ces artefacts lorsqu'il démarre. Lorsque Vertex AI démarre votre conteneur, il définit la variable d'environnement AIP_STORAGE_URI sur un URI Cloud Storage commençant par gs://. L'instruction ENTRYPOINT du conteneur peut télécharger le répertoire spécifié par cet URI pour accéder aux artefacts du modèle.

Notez que la valeur de la variable d'environnement AIP_STORAGE_URI n'est pas identique à l'URI Cloud Storage que vous spécifiez dans le champ artifactUri lorsque vous créez le Model. AIP_STORAGE_URI pointe plutôt vers une copie du répertoire d'artefacts de modèle dans un autre bucket Cloud Storage géré par Vertex AI. L'IA Vertex renseigne ce répertoire lorsque vous créez un Model. Vous ne pouvez pas mettre à jour le contenu du répertoire. Si vous souhaitez utiliser de nouveaux artefacts de modèle, vous devez créer un Model.

Le compte de service utilisé par votre conteneur par défaut est autorisé à lire des données à partir de cet URI.

En revanche, le fait de spécifier un compte de service personnalisé lorsque vous déployez le Model sur un Endpoint, Vertex AI attribue automatiquement à votre compte de service spécifié le rôle de Lecteur des objets de l'espace de stockage (roles/storage.objectViewer) pour le bucket Cloud Storage de l'URI.

Utilisez une bibliothèque compatible avec les identifiants par défaut de l'application pour charger les artefacts de modèle. Vous n'avez pas besoin de configurer explicitement l'authentification.

Variables d'environnement disponibles dans le conteneur

Lors de son exécution, l'instruction ENTRYPOINT du conteneur peut référencer les variables d'environnement que vous avez configurées manuellement, ainsi que les variables d'environnement définies automatiquement par Vertex AI. Cette section décrit comment vous pouvez définir des variables d'environnement et fournit des détails sur les variables définies automatiquement par Vertex AI.

Variables définies dans l'image de conteneur

Pour définir des variables d'environnement dans l'image de conteneur lors de sa création, utilisez l'instruction ENV de Docker. Ne définissez aucune variable d'environnement commençant par le préfixe AIP_.

L'instruction ENTRYPOINT du conteneur peut utiliser ces variables d'environnement, mais vous ne pouvez les référencer dans aucun des champs d'API de votre Model.

Variables définies par Vertex AI

Lorsque Vertex AI commence à exécuter le conteneur, il définit les variables d'environnement suivantes dans l'environnement du conteneur. Chaque variable commence par le préfixe AIP_. Ne définissez pas manuellement des variables d'environnement qui utilisent ce préfixe.

L'instruction ENTRYPOINT du conteneur peut accéder à ces variables. Pour savoir quels champs de l'API Vertex AI peuvent également faire référence à ces variables, consultez la documentation de référence de l'API pour ModelContainerSpec.

Remarque : Les instructions Docker utilisées pour créer l'image de conteneur, telles que RUN, ne peuvent pas accéder à ces variables car vous devez créer l'image de conteneur avant de la fournir à Vertex AI.

Remarque : Vertex AI définit les valeurs de certaines des variables suivantes lorsque vous déployez votre Model en tant que DeployedModel sur un Endpoint. Vous pouvez faire référence à d'autres champs de l'API lorsque vous créez le Model et les valeurs seront développées à chaque déploiement du Model.

Nom de la variable	Valeur par défaut	Configurer la valeur	Détails
AIP_ACCELERATOR_TYPE	Non défini	Lorsque vous déployez un Model en tant que DeployedModel sur une ressource Endpoint, définissez le champ dedicatedResources.machineSpec.acceleratorType.	Le cas échéant, cette variable spécifie le type d'accélérateur utilisé par l'instance de machine virtuelle (VM) sur laquelle le conteneur est exécuté.
AIP_DEPLOYED_MODEL_ID	Chaîne de chiffres identifiant le DeployedModel sur lequel le Model de ce conteneur a été déployé.	Non configurable	Cette valeur correspond au champ id du DeployedModel.
AIP_ENDPOINT_ID	Chaîne de chiffres identifiant le Endpoint sur lequel le Model du conteneur a été déployé.	Non configurable	Cette valeur correspond au dernier segment du champ name du Endpoint (après endpoints/).
AIP_FRAMEWORK	CUSTOM_CONTAINER	Non configurable
AIP_HEALTH_ROUTE	/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL Dans cette chaîne, remplacez ENDPOINT par la valeur de la variable AIP_ENDPOINT_ID et DEPLOYED_MODEL par la valeur de la variable AIP_DEPLOYED_MODEL_ID.	Lorsque vous créez un Model, définissez le champ containerSpec.healthRoute.	Cette variable spécifie le chemin HTTP du conteneur auquel Vertex AI envoie des vérifications d'état.
AIP_HTTP_PORT	8080	Lorsque vous créez un Model, définissez le champ containerSpec.ports. La première entrée de ce champ devient la valeur de AIP_HTTP_PORT.	Vertex AI envoie des vérifications de vivacité, de vérification d'état et de prédiction à ce port sur le conteneur. Le serveur HTTP de votre conteneur doit écouter les requêtes sur ce port.
AIP_MACHINE_TYPE	Aucune valeur par défaut, doit être configuré	Lorsque vous déployez un Model en tant que DeployedModel sur une ressource Endpoint, définissez le champ dedicatedResources.machineSpec.machineType.	Cette variable spécifie le type de VM sur lequel le conteneur est exécuté.
AIP_MODE	PREDICTION	Non configurable	Cette variable signifie que le conteneur s'exécute sur Vertex AI pour diffuser des prédictions en ligne. Vous pouvez utiliser cette variable d'environnement pour ajouter une logique personnalisée à votre conteneur afin qu'il puisse s'exécuter dans plusieurs environnements informatiques et de n'utiliser que certains chemins de code lors de son exécution sur Vertex AI.
AIP_MODE_VERSION	1.0.0	Non configurable	Cette variable correspond à la version des exigences concernant les conteneurs personnalisés (le présent document) que Vertex AI attend que le conteneur respecte. Ce document est mis à jour en fonction de la gestion sémantique des versions.
AIP_MODEL_NAME	Valeur de la variable AIP_ENDPOINT_ID	Non configurable	Reportez-vous à la ligne AIP_ENDPOINT_ID. Cette variable existe pour des raisons de compatibilité.
AIP_PREDICT_ROUTE	/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict Dans cette chaîne, remplacez ENDPOINT par la valeur de la variable AIP_ENDPOINT_ID et DEPLOYED_MODEL par la valeur de la variable AIP_DEPLOYED_MODEL_ID.	Lorsque vous créez un Model, définissez le champ containerSpec.predictRoute.	Cette variable spécifie le chemin HTTP du conteneur vers lequel Vertex AI transfère des requêtes de prédiction.
AIP_PROJECT_NUMBER	Le numéro de projet du projet Google Cloud dans lequel vous utilisez Vertex AI	Non configurable
AIP_STORAGE_URI	Si vous ne définissez pas le champ artifactUri lorsque vous créez un Model : une chaîne vide. Si vous définissez le champ artifactUri lorsque vous créez un Model : un URI Cloud Storage (commençant par gs://) spécifiant un répertoire dans un bucket géré par Vertex AI.	Non configurable	Cette variable spécifie le répertoire contenant une copie des artefacts de votre modèle, le cas échéant.
AIP_VERSION_NAME	Valeur de la variable AIP_DEPLOYED_MODEL_ID	Non configurable	Reportez-vous à la ligne AIP_DEPLOYED_MODEL_ID. Cette variable existe pour des raisons de compatibilité.

Variables définies dans la ressource Model

Lorsque vous créez un Model, vous pouvez définir des variables d'environnement supplémentaires dans le champ containerSpec.env.

L'instruction ENTRYPOINT du conteneur peut accéder à ces variables. Pour savoir quels champs de l'API Vertex AI peuvent également faire référence à ces variables, consultez la documentation de référence de l'API pour ModelContainerSpec.

Remarque : Les instructions Docker utilisées pour créer l'image de conteneur, telles que RUN, ne peuvent pas accéder à ces variables car vous devez créer l'image de conteneur avant de la fournir à Vertex AI.

Étapes suivantes

• Apprenez-en plus sur la diffusion de prédictions à l'aide d'un conteneur personnalisé, ainsi que sur la spécification des champs d'API liés au conteneur lorsque vous importez un modèle.