Exigences relatives aux conteneurs personnalisés

Afin d'utiliser un conteneur personnalisé pour diffuser des prédictions, vous devez fournir à AI Platform Prediction une image de conteneur Docker exécutant un serveur HTTP. Ce document décrit les exigences qu'une image de conteneur doit respecter pour être compatible avec AI Platform Prediction. Il décrit également la manière dont AI Platform Prediction interagit avec votre conteneur personnalisé une fois que celui-ci est lancé. Ce document décrit les éléments à prendre en compte lors de la conception d'une image de conteneur à utiliser avec AI Platform Prediction.

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 KFServing 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 la version de votre modèle afin de remplacer ENTRYPOINT et CMD, respectivement, dans votre image de 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 la commande 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 une version de modèle, spécifiez ce port dans le champ containerSpec.ports. Pour savoir comment le conteneur peut accéder à cette valeur, lisez la section de ce document sur la variable d'environnement AIP_HTTP_PORT.

Vérifications de vivacité

AI Platform Prediction effectue une vérification d'activité lorsque votre conteneur commence à s'assurer que votre serveur est en cours d'exécution. Pendant le processus de création de la version, AI Platform Prediction 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, AI Platform Prediction 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

AI Platform Prediction 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 routes.health lorsque vous créez une version de modèle. Pour savoir comment le conteneur peut accéder à cette valeur, lisez la section de ce document sur 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 à la requête de vérification d'état avec le code d'état 200 OK. Le contenu du corps de la réponse n'a pas d'importance. AI Platform Prediction 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 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 signifie que le serveur n'est pas opérationnel.

Si la vérification de l'état reçoit une réponse non opérationnelle de votre serveur, elle envoie jusqu'à trois vérifications d'état supplémentaires à intervalles de 10 secondes. Pendant cette période, AI Platform Prediction considère toujours 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, AI Platform Prediction arrête le routage du trafic de prédiction vers le conteneur. (Si la version du modèle est mise à l'échelle pour utiliser plusieurs nœuds de prédiction, AI Platform Prediction dirige les requêtes de prédiction vers d'autres conteneurs opérationnels.)

AI Platform Prediction ne redémarre pas le conteneur. La vérification de l'é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, celui-ci 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.predict à l'API AI Platform Training and Prediction, AI Platform Prediction transmet cette requête en tant que requête HTTP POST à un chemin d'accès de prédiction configurable sur votre serveur. Spécifiez ce chemin d'accès dans le champ routes.predict lorsque vous créez une version de modèle. Pour savoir comment le conteneur peut accéder à cette valeur, lisez la section de ce document sur la variable d'environnement AIP_PREDICT_ROUTE.

AI Platform Prediction ne valide pas les requêtes et les réponses de prédiction. Il transmet chaque requête de prédiction sans les modifier au serveur HTTP de votre conteneur et transmet les réponses du serveur au client.

La taille de chaque requête et réponse de prédiction ne doit pas dépasser 1,5 Mo. Toutefois, vous n'êtes pas obligé de respecter les autres exigences concernant les demandes de requêtes, ni les exigences concernant les corps de réponse. Ces exigences ne s'appliquent qu'aux versions de modèle qui n'utilisent pas de conteneur personnalisé. Lorsque vous utilisez un conteneur personnalisé, le corps de vos requêtes et de vos réponses peut prendre n'importe quelle forme.

Toutefois, nous vous conseillons de concevoir votre serveur HTTP pour répondre aux exigences des requêtes et des réponses décrites dans les liens précédents. Si vous ne le faites pas, rien ne garantit que d'autres fonctionnalités d'AI Platform Prediction, telles que la journalisation, la monitoring et AI Explanations, fonctionnent correctement.

Exigences relatives à la publication d'images de conteneurs

Vous devez transférer votre image de conteneur vers Artifact Registry pour pouvoir l'utiliser avec AI Platform Prediction. 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.

Location (Emplacement)

Le dépôt doit utiliser une région correspondant au point de terminaison régional dans lequel vous prévoyez de créer une version de modèle. Par exemple, si vous envisagez de créer une version de modèle sur le point de terminaison us-central1-ml.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

AI Platform Prediction doit être autorisé à extraire l'image de conteneur lorsque vous créez une version de modèle. Plus précisément, le compte de service AI Platform géré par Google doit disposer des autorisations du rôle lecteur d'Artifact Registry (roles/artifactregistry.reader) pour le dépôt de l'image de conteneur.

Si vous avez transféré votre image de conteneur vers le projet Google Cloud sur lequel vous utilisez AI Platform Prediction, vous n'avez pas besoin de configurer des autorisations. Les autorisations par défaut accordées au compte de service géré par Google 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 AI Platform Prediction, vous devez attribuer le rôle lecteur d'Artifact Registry pour le dépôt Artifact Registry au compte de service AI Platform géré par Google.

Accéder aux artefacts de modèle

Lorsque vous créez une version de modèle sans conteneur personnalisé, vous devez spécifier l'URI d'un répertoire Cloud Storage avec des artefacts de modèle en tant que champ deploymentUri. Lorsque vous créez une version de modèle avec un conteneur personnalisé, vous n'êtes pas obligé de fournir des artefacts de modèle dans Cloud Storage.

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 deploymentUri, le conteneur doit charger ces artefacts lorsqu'il démarre. Lorsque AI Platform Prediction démarre votre conteneur, il définit la variable d'environnement AIP_STORAGE_URI sur un URI Cloud Storage qui commence par gs://. La commande entrypoint du conteneur peut télécharger le répertoire spécifié par cet URI pour accéder aux artefacts de 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 deploymentUri lorsque vous créez la version de modèle. AIP_STORAGE_URI pointe vers une copie du répertoire d'artefacts du modèle dans un autre bucket Cloud Storage, géré par AI Platform Prediction. AI Platform Prediction remplit ce répertoire lorsque vous créez une version de modèle. 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 une nouvelle version de modèle.

Le compte de service utilisé par votre conteneur par défaut est autorisé à lire des données à partir de cet URI. D'autre part, si vous spécifiez un compte de service personnalisé lorsque vous créez une version de modèle, AI Platform Prediction accorde automatiquement à votre compte de service spécifié le rôle de lecteur des objets Storage (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.

Étant donné que le conteneur est compatible avec les identifiants par défaut de l'application pour le compte de service AI Platform géré par Google, ou pour un compte de service personnalisé si vous en avez spécifié un, il peut également accéder à d'autres services Google Cloud pour lesquels son compte de service dispose des autorisations nécessaires.

Variables d'environnement disponibles dans le conteneur

Lors de son exécution, la commande 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 AI Platform Prediction. 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 AI Platform Prediction.

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_.

La commande entrypoint du conteneur peut utiliser ces variables d'environnement, mais vous ne pouvez les référencer dans aucun des champs d'API de la version de modèle.

Variables définies par AI Platform Prediction

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

La commande entrypoint du conteneur peut accéder à ces variables. Pour savoir quels champs de l'API AI Platform Training and Prediction peuvent également référencer ces variables, reportez-vous à la documentation de référence de l'API pour ContainerSpec.

Nom de la variable Valeur par défaut Configurer la valeur Détails
AIP_ACCELERATOR_TYPE Non défini Lorsque vous créez une version de modèle, définissez le champ acceleratorConfig.type. 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_FRAMEWORK CUSTOM_CONTAINER Non configurable
AIP_HEALTH_ROUTE /v1/models/MODEL/versions/VERSION

Dans cette chaîne, remplacez MODEL par la valeur de la variable AIP_MODEL_NAME et VERSION par la valeur de la variable AIP_VERSION_NAME.		 Lorsque vous créez une version de modèle, définissez le champ routes.health. Cette variable spécifie le chemin HTTP du conteneur auquel AI Platform Prediction envoie des vérifications d'état.
AIP_HTTP_PORT 8080 Lorsque vous créez une version de modèle, définissez le champ containerSpec.ports. La première entrée de ce champ devient la valeur de AIP_HTTP_PORT. AI Platform Prediction envoie des vérifications de l'activité, des vérifications de l'état et des requêtes 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 créez une version de modèle, définissez le champ 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 est exécuté sur AI Platform Prediction pour diffuser les 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, mais n'utiliser que certains chemins de code lors de son exécution sur AI Platform Prediction.
AIP_MODE_VERSION 1.0.0 Non configurable Cette variable correspond à la version des exigences relatives aux conteneurs personnalisés (ce document) qu'AI Platform Prediction attend que le conteneur respecte. Ce document est mis à jour en fonction de la gestion sémantique des versions.
AIP_MODEL_NAME Aucune valeur par défaut, doit être configuré Lorsque vous créez un modèle (le parent de la version de modèle utilisant le conteneur), spécifiez le champ name. La valeur n'inclut pas le préfixe projects/PROJECT_ID/models/ généré par l'API AI Platform Training and Prediction en sortie.
AIP_PREDICT_ROUTE /v1/models/MODEL/versions/VERSION:predict

Dans cette chaîne, remplacez MODEL par la valeur de la variable AIP_MODEL_NAME et VERSION par la valeur de la variable AIP_VERSION_NAME.		 Lorsque vous créez une version de modèle, définissez le champ routes.predict. Cette variable spécifie le chemin HTTP du conteneur vers lequel AI Platform Prediction transfère des requêtes de prédiction.
AIP_PROJECT_NUMBER Numéro du projet Google Cloud dans lequel vous utilisez AI Platform Prediction Non configurable
AIP_STORAGE_URI
  • Si vous ne définissez pas le champ deploymentUri lorsque vous créez une version de modèle : une chaîne vide.
  • Si vous définissez le champ deploymentUri lorsque vous créez une version de modèle : un URI Cloud Storage (commençant par gs://) spécifiant un répertoire dans un bucket géré par AI Platform Prediction.
 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 Aucune valeur par défaut, doit être configuré Lorsque vous créez une version de modèle, définissez le champ name. La valeur n'inclut pas le préfixe projects/PROJECT_ID/models/MODEL/versions/ généré par l'API AI Platform Training and Prediction en sortie.

Variables définies dans la ressource Version

Lorsque vous créez une version de modèle, vous pouvez définir des variables d'environnement supplémentaires dans le champ container.env.

La commande entrypoint du conteneur peut accéder à ces variables. Pour savoir quels champs de l'API AI Platform Training and Prediction peuvent également référencer ces variables, reportez-vous à la documentation de référence de l'API pour ContainerSpec.

Étapes suivantes