Cette page vous explique comment obtenir des prédictions et des explications en ligne (en temps réel) à partir de vos modèles de classification ou de régression tabulaires à l'aide de la console Google Cloud ou de l'API Vertex AI.
Une prédiction en ligne est une requête synchrone plutôt qu'une prédiction par lot, qui est une requête asynchrone. Utilisez les prédictions en ligne lorsque vous effectuez des requêtes en réponse à une entrée d'une application ou dans d'autres situations nécessitant une inférence rapide.
Vous devez déployer un modèle sur un point de terminaison avant de pouvoir utiliser ce modèle pour diffuser des prédictions en ligne. Le déploiement d'un modèle associe des ressources physiques au modèle afin qu'il puisse diffuser des prédictions en ligne avec une faible latence.
Voici les thèmes abordés :
- Déployer un modèle sur un point de terminaison
- Obtenir une prédiction en ligne à l'aide du modèle déployé
- Obtenir une explication en ligne à l'aide du modèle déployé
Avant de commencer
Pour obtenir des prédictions en ligne, vous devez d'abord entraîner un modèle de classification ou de régression et l'évaluer pour en vérifier la justesse.
Déployer un modèle sur un point de terminaison
Vous pouvez déployer plusieurs modèles sur un point de terminaison et un modèle sur plusieurs points de terminaison. Pour en savoir plus sur les options et les cas d'utilisation du déploiement de modèles, consultez la page À propos du déploiement de modèles.
Utilisez l'une des méthodes suivantes pour déployer un modèle :
console Google Cloud
Accédez à la page Modèles de la console Google Cloud, dans la section Vertex AI.
Cliquez sur le nom du modèle que vous souhaitez déployer pour ouvrir sa page d'informations.
Sélectionnez l'onglet Déployer et tester.
Si votre modèle est déjà déployé sur des points de terminaison, ils sont répertoriés dans la section Déployer votre modèle.
Cliquez sur Déployer sur un point de terminaison.
Sur la page Define your endpoint (Définir votre point de terminaison), configurez les éléments comme suit :
Vous pouvez choisir de déployer votre modèle sur un nouveau point de terminaison ou sur un point de terminaison existant.
- Pour déployer votre modèle sur un nouveau point de terminaison, sélectionnez Créer un point de terminaison et nommez le nouvel élément.
- Pour déployer votre modèle sur un point de terminaison existant, sélectionnez Ajouter à un point de terminaison existant, puis sélectionnez le point de terminaison dans la liste déroulante.
- Vous pouvez ajouter plusieurs modèles à un point de terminaison et un modèle à plusieurs points de terminaison. En savoir plus.
Cliquez sur Continuer.
Sur la page Paramètres de modèle, configurez les éléments comme suit :
-
Si vous déployez votre modèle sur un nouveau point de terminaison, acceptez la valeur 100 pour la répartition du trafic. Si vous déployez votre modèle sur un point de terminaison existant qui contient un ou plusieurs modèles déployés, vous devez mettre à jour le pourcentage de répartition du trafic du modèle que vous déployez et des modèles déjà déployés afin que le pourcentage cumulé de tous les pourcentages soit égal à 100 %.
-
Saisissez le nombre minimal de nœuds de calcul que vous souhaitez fournir pour votre modèle.
Il s'agit du nombre de nœuds disponibles pour ce modèle à tout moment. Les nœuds utilisés vous sont facturés, que ce soit pour gérer la charge de prédiction ou pour les nœuds de secours (minimum), même sans le trafic de prédiction. Consultez la page des tarifs.
-
Sélectionnez un type de machine.
Des ressources de plus grande capacité améliorent les performances des prédictions et augmentent les coûts.
-
Découvrez comment modifier les paramètres par défaut pour la journalisation des prédictions.
-
Cliquez sur Continuer.
-
Sur la page Surveillance des modèles, cliquez sur Continuer.
Sur la page Objectifs de surveillance, procédez comme suit :
- Saisissez l'emplacement de vos données d'entraînement.
- Saisissez le nom de la colonne cible.
Cliquez sur Déployer pour déployer votre modèle sur le point de terminaison.
API
Pour déployer un modèle à l'aide de l'API Vertex AI, vous devez effectuer les étapes suivantes :
- Créez un point de terminaison si nécessaire.
- Obtenez l'ID du point de terminaison.
- Déployez le modèle sur le point de terminaison.
Créer un point de terminaison
Si vous déployez un modèle sur un point de terminaison existant, vous pouvez ignorer cette étape.
gcloud
L'exemple suivant utilise la commande gcloud ai endpoints create
:
gcloud ai endpoints create \
--region=LOCATION \
--display-name=ENDPOINT_NAME
Remplacez les éléments suivants :
- LOCATION_ID : région dans laquelle vous utilisez l'IA Vertex.
ENDPOINT_NAME : nom du point de terminaison à afficher.
La création du point de terminaison par l'outil Google Cloud CLI peut prendre quelques secondes.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- LOCATION_ID : votre région.
- PROJECT_ID : l'ID de votre projet.
- ENDPOINT_NAME : nom du point de terminaison à afficher.
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints
Corps JSON de la requête :
{ "display_name": "ENDPOINT_NAME" }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateEndpointOperationMetadata", "genericMetadata": { "createTime": "2020-11-05T17:45:42.812656Z", "updateTime": "2020-11-05T17:45:42.812656Z" } } }
"done": true
.
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.
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.
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.
Obtenez l'ID du point de terminaison.
Vous avez besoin de l'ID de point de terminaison pour déployer le modèle.
gcloud
L'exemple suivant utilise la commande gcloud ai endpoints list
:
gcloud ai endpoints list \
--region=LOCATION \
--filter=display_name=ENDPOINT_NAME
Remplacez les éléments suivants :
- LOCATION_ID : région dans laquelle vous utilisez l'IA Vertex.
ENDPOINT_NAME : nom du point de terminaison à afficher.
Notez le nombre qui s'affiche dans la colonne
ENDPOINT_ID
. Utilisez cet ID à l'étape suivante.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- LOCATION_ID : région dans laquelle vous utilisez Vertex AI.
- PROJECT_ID : l'ID de votre projet.
- ENDPOINT_NAME : nom du point de terminaison à afficher.
Méthode HTTP et URL :
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "endpoints": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID", "displayName": "ENDPOINT_NAME", "etag": "AMEw9yPz5pf4PwBHbRWOGh0PcAxUdjbdX2Jm3QO_amguy3DbZGP5Oi_YUKRywIE-BtLx", "createTime": "2020-04-17T18:31:11.585169Z", "updateTime": "2020-04-17T18:35:08.568959Z" } ] }
Déployer le modèle
Sélectionnez l'onglet correspondant à votre langage ou à votre environnement :
gcloud
Les exemples suivants utilisent la commande gcloud ai endpoints deploy-model
.
L'exemple suivant déploie un Model
sur un Endpoint
sans utiliser de GPU pour accélérer la diffusion des prédictions et répartir le trafic entre plusieurs ressources DeployedModel
:
Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :
- ENDPOINT_ID : ID du point de terminaison.
- LOCATION_ID : région dans laquelle vous utilisez Vertex AI.
- MODEL_ID : ID du modèle à déployer.
-
DEPLOYED_MODEL_NAME : nom de l'élément
DeployedModel
. Vous pouvez également utiliser le nom à afficher duModel
pour leDeployedModel
. -
MACHINE_TYPE : facultatif. Ressources machine utilisées pour chaque nœud de ce déploiement. Le paramètre par défaut est
n1-standard-2
. En savoir plus sur les types de machines. -
MIN_REPLICA_COUNT : nombre minimal de nœuds pour ce déploiement.
Le nombre de nœuds peut être augmenté ou réduit selon les besoins de la charge de prédiction, dans la limite du nombre maximal de nœuds et jamais moins que ce nombre de nœuds.
Cette valeur doit être supérieure ou égale à 1. Si l'option
--min-replica-count
est omise, la valeur par défaut est 1. -
MAX_REPLICA_COUNT : nombre maximal de nœuds pour ce déploiement.
Le nombre de nœuds peut être augmenté ou diminué selon les besoins de la charge de prédiction, jusqu'à atteindre ce nombre de nœuds mais jamais moins que le nombre minimal de nœuds.
Si vous omettez l'option
--max-replica-count
, le nombre maximal de nœuds est défini sur la valeur de--min-replica-count
.
Exécutez la commande gcloud ai endpoints deploy-model :
Linux, macOS ou Cloud Shell
gcloud ai endpoints deploy-model ENDPOINT_ID\ --region=LOCATION_ID \ --model=MODEL_ID \ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE \ --min-replica-count=MIN_REPLICA_COUNT \ --max-replica-count=MAX_REPLICA_COUNT \ --traffic-split=0=100
Windows (PowerShell)
gcloud ai endpoints deploy-model ENDPOINT_ID` --region=LOCATION_ID ` --model=MODEL_ID ` --display-name=DEPLOYED_MODEL_NAME ` --machine-type=MACHINE_TYPE ` --min-replica-count=MIN_REPLICA_COUNT ` --max-replica-count=MAX_REPLICA_COUNT ` --traffic-split=0=100
Windows (cmd.exe)
gcloud ai endpoints deploy-model ENDPOINT_ID^ --region=LOCATION_ID ^ --model=MODEL_ID ^ --display-name=DEPLOYED_MODEL_NAME ^ --machine-type=MACHINE_TYPE ^ --min-replica-count=MIN_REPLICA_COUNT ^ --max-replica-count=MAX_REPLICA_COUNT ^ --traffic-split=0=100
Répartir le trafic
L'option --traffic-split=0=100
des exemples précédents envoie 100 % du trafic de prédiction que Endpoint
reçoit à la nouvelle ressource DeployedModel
, correspondant à l'ID temporaire 0
. Si votre Endpoint
dispose déjà d'autres ressources DeployedModel
, vous pouvez répartir le trafic entre le nouveau DeployedModel
et les anciens.
Par exemple, pour envoyer 20 % du trafic vers le nouveau DeployedModel
et 80 % vers une ressource plus ancienne, exécutez la commande suivante.
Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :
- OLD_DEPLOYED_MODEL_ID : ID de la ressource
DeployedModel
existante.
Exécutez la commande gcloud ai endpoints deploy-model :
Linux, macOS ou Cloud Shell
gcloud ai endpoints deploy-model ENDPOINT_ID\ --region=LOCATION_ID \ --model=MODEL_ID \ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE \ --min-replica-count=MIN_REPLICA_COUNT \ --max-replica-count=MAX_REPLICA_COUNT \ --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
Windows (PowerShell)
gcloud ai endpoints deploy-model ENDPOINT_ID` --region=LOCATION_ID ` --model=MODEL_ID ` --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE ` --min-replica-count=MIN_REPLICA_COUNT ` --max-replica-count=MAX_REPLICA_COUNT ` --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
Windows (cmd.exe)
gcloud ai endpoints deploy-model ENDPOINT_ID^ --region=LOCATION_ID ^ --model=MODEL_ID ^ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE ^ --min-replica-count=MIN_REPLICA_COUNT ^ --max-replica-count=MAX_REPLICA_COUNT ^ --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
REST
Vous utilisez la méthode endpoints.predict pour demander une prédiction en ligne.
déployer le modèle ;
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.
- ENDPOINT_ID : ID du point de terminaison.
- MODEL_ID : ID du modèle à déployer.
-
DEPLOYED_MODEL_NAME : nom de l'élément
DeployedModel
. Vous pouvez également utiliser le nom à afficher duModel
pour leDeployedModel
. -
MACHINE_TYPE : facultatif. Ressources machine utilisées pour chaque nœud de ce déploiement. Le paramètre par défaut est
n1-standard-2
. En savoir plus sur les types de machines. - ACCELERATOR_TYPE : type d'accélérateur à associer à la machine. Facultatif si ACCELERATOR_COUNT n'est pas spécifié ou est égal à zéro. Il n'est pas recommandé pour les modèles AutoML ni les modèles personnalisés qui utilisent des images non GPU. En savoir plus
- ACCELERATOR_COUNT : nombre d'accélérateurs pour chaque instance dupliquée à utiliser. Facultatif. Doit être égal à zéro ou non spécifié pour les modèles AutoML ou les modèles personnalisés qui utilisent des images non GPU.
- MIN_REPLICA_COUNT : nombre minimal de nœuds pour ce déploiement. Le nombre de nœuds peut être augmenté ou réduit selon les besoins de la charge de prédiction, dans la limite du nombre maximal de nœuds et jamais moins que ce nombre de nœuds. Cette valeur doit être supérieure ou égale à 1.
- MAX_REPLICA_COUNT : nombre maximal de nœuds pour ce déploiement. Le nombre de nœuds peut être augmenté ou diminué selon les besoins de la charge de prédiction, jusqu'à atteindre ce nombre de nœuds mais jamais moins que le nombre minimal de nœuds.
- TRAFFIC_SPLIT_THIS_MODEL : pourcentage du trafic de prédiction vers ce point de terminaison à acheminer vers le modèle déployé avec cette opération. La valeur par défaut est 100. La somme des pourcentages de trafic doit être égale à 100. En savoir plus sur la répartition du trafic.
- DEPLOYED_MODEL_ID_N : facultatif. Si d'autres modèles sont déployés sur ce point de terminaison, vous devez mettre à jour les pourcentages de répartition du trafic pour que le pourcentage cumulé de tous les pourcentages soit égal à 100.
- TRAFFIC_SPLIT_MODEL_N : valeur en pourcentage de la répartition du trafic pour la clé de l'ID de modèle déployé.
- PROJECT_NUMBER : numéro de projet généré automatiquement pour votre projet
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:deployModel
Corps JSON de la requête :
{ "deployedModel": { "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID", "displayName": "DEPLOYED_MODEL_NAME", "dedicatedResources": { "machineSpec": { "machineType": "MACHINE_TYPE", "acceleratorType": "ACCELERATOR_TYPE", "acceleratorCount": "ACCELERATOR_COUNT" }, "minReplicaCount": MIN_REPLICA_COUNT, "maxReplicaCount": MAX_REPLICA_COUNT }, }, "trafficSplit": { "0": TRAFFIC_SPLIT_THIS_MODEL, "DEPLOYED_MODEL_ID_1": TRAFFIC_SPLIT_MODEL_1, "DEPLOYED_MODEL_ID_2": TRAFFIC_SPLIT_MODEL_2 }, }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "name": "projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployModelOperationMetadata", "genericMetadata": { "createTime": "2020-10-19T17:53:16.502088Z", "updateTime": "2020-10-19T17:53:16.502088Z" } } }
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.
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.
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.
Découvrez comment modifier les paramètres par défaut pour la journalisation des prédictions.
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.
Obtenir une prédiction en ligne à l'aide du modèle déployé
Pour effectuer une prédiction en ligne, envoyez un ou plusieurs éléments de test à un modèle pour analyse, et ce modèle renvoie des résultats basés sur l'objectif de votre modèle. Utilisez la console Google Cloud ou l'API Vertex AI pour demander une prédiction en ligne.
console Google Cloud
Accédez à la page Modèles de la console Google Cloud, dans la section Vertex AI.
Dans la liste des modèles, cliquez sur le nom du modèle à partir duquel demander les prédictions.
Sélectionnez l'onglet Déployer et tester.
Dans la section Tester votre modèle, ajoutez des éléments de test pour demander une prédiction. Les données de prédiction de base sont renseignées automatiquement, ou vous pouvez saisir vos propres données de prédiction, puis cliquer sur Prédiction.
Une fois la prédiction terminée, Vertex AI renvoie les résultats dans la console.
API : classification
gcloud
-
Créez un fichier nommé
request.json
avec le contenu suivant :{ "instances": [ { PREDICTION_DATA_ROW } ] }
Remplacez l'élément suivant :
-
PREDICTION_DATA_ROW : objet JSON avec des clés comme noms de caractéristiques et des valeurs en tant que valeurs de caractéristiques correspondantes. Par exemple, pour un ensemble de données comportant un nombre, un tableau de chaînes et une catégorie, la ligne de données peut ressembler à l'exemple de requête suivant :
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
Vous devez fournir une valeur pour chaque caractéristique incluse dans l'entraînement. Le format des données utilisées pour la prédiction doit correspondre à celui utilisé pour l'entraînement. Pour en savoir plus, consultez la section Format de données pour les prédictions.
-
-
Exécutez la commande suivante :
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Remplacez les éléments suivants :
- ENDPOINT_ID : ID du point de terminaison.
- LOCATION_ID : région dans laquelle vous utilisez l'IA Vertex.
REST
Vous utilisez la méthode endpoints.predict pour demander une prédiction en ligne.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
-
LOCATION_ID : région où se trouve le point de terminaison. Par exemple,
us-central1
. - PROJECT_ID : l'ID de votre projet.
- ENDPOINT_ID : ID du point de terminaison.
-
PREDICTION_DATA_ROW : objet JSON avec des clés comme noms de caractéristiques et des valeurs en tant que valeurs de caractéristiques correspondantes. Par exemple, pour un ensemble de données comportant un nombre, un tableau de chaînes et une catégorie, la ligne de données peut ressembler à l'exemple de requête suivant :
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
Vous devez fournir une valeur pour chaque caractéristique incluse dans l'entraînement. Le format des données utilisées pour la prédiction doit correspondre à celui utilisé pour l'entraînement. Pour en savoir plus, consultez la section Format de données pour les prédictions.
- DEPLOYED_MODEL_ID : sortie générée par la méthode
predict
et acceptée en tant qu'entrée par la méthodeexplain
. ID du modèle utilisé pour générer la prédiction. Si vous devez demander des explications pour une prédiction précédemment demandée et que vous avez déployé plusieurs modèles, vous pouvez utiliser cet ID pour vous assurer que les explications sont renvoyées pour le modèle qui a fourni la prédiction précédente.
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
Corps JSON de la requête :
{ "instances": [ { PREDICTION_DATA_ROW } ] }
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/endpoints/ENDPOINT_ID:predict"
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/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON de ce type :
{ "predictions": [ { "scores": [ 0.96771615743637085, 0.032283786684274673 ], "classes": [ "0", "1" ] } ] "deployedModelId": "2429510197" }
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.
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.
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.
API : régression
gcloud
-
Créez un fichier nommé "request.json" avec le contenu suivant :
{ "instances": [ { PREDICTION_DATA_ROW } ] }
Remplacez les éléments suivants :
-
PREDICTION_DATA_ROW : objet JSON avec des clés comme noms de caractéristiques et des valeurs en tant que valeurs de caractéristiques correspondantes. Par exemple, pour un ensemble de données comportant un nombre, un tableau de nombres et une catégorie, la ligne de données peut ressembler à l'exemple de requête suivant :
"age":3.6, "sq_ft":5392, "code": "90331"
Vous devez fournir une valeur pour chaque caractéristique incluse dans l'entraînement. Le format des données utilisées pour la prédiction doit correspondre à celui utilisé pour l'entraînement. Pour en savoir plus, consultez la section Format de données pour les prédictions.
-
-
Exécutez la commande suivante :
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Remplacez les éléments suivants :
- ENDPOINT_ID : ID du point de terminaison.
- LOCATION_ID : région dans laquelle vous utilisez l'IA Vertex.
REST
Vous utilisez la méthode endpoints.predict pour demander une prédiction en ligne.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
-
LOCATION_ID : région où se trouve le point de terminaison. Par exemple,
us-central1
. - PROJECT_ID : l'ID de votre projet.
- ENDPOINT_ID : ID du point de terminaison.
-
PREDICTION_DATA_ROW : objet JSON avec des clés comme noms de caractéristiques et des valeurs en tant que valeurs de caractéristiques correspondantes. Par exemple, pour un ensemble de données comportant un nombre, un tableau de nombres et une catégorie, la ligne de données peut ressembler à l'exemple de requête suivant :
"age":3.6, "sq_ft":5392, "code": "90331"
Vous devez fournir une valeur pour chaque caractéristique incluse dans l'entraînement. Le format des données utilisées pour la prédiction doit correspondre à celui utilisé pour l'entraînement. Pour en savoir plus, consultez la section Format de données pour les prédictions.
- DEPLOYED_MODEL_ID : sortie générée par la méthode
predict
et acceptée en tant qu'entrée par la méthodeexplain
. ID du modèle utilisé pour générer la prédiction. Si vous devez demander des explications pour une prédiction précédemment demandée et que vous avez déployé plusieurs modèles, vous pouvez utiliser cet ID pour vous assurer que les explications sont renvoyées pour le modèle qui a fourni la prédiction précédente.
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
Corps JSON de la requête :
{ "instances": [ { PREDICTION_DATA_ROW } ] }
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/endpoints/ENDPOINT_ID:predict"
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/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON de ce type :
{ "predictions": [ [ { "value": 65.14233, "lower_bound": 4.6572, "upper_bound": 164.0279 } ] ], "deployedModelId": "DEPLOYED_MODEL_ID" }
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.
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.
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.
Interpréter les résultats des prédictions
Classification
Les modèles de classification renvoient un score de confiance.
Le score de confiance indique à quel point votre modèle associe chaque classe ou étiquette à un élément de test. Plus le score est élevé, plus le modèle a de chances d'appliquer l'étiquette à cet élément. C'est vous qui décidez du seuil de confiance auquel vous acceptez les résultats du modèle.
Régression
Les modèles de régression renvoient une valeur de prédiction. Pour les destinations BigQuery, ils renvoient également un intervalle de prédiction. L'intervalle de prédiction fournit une plage de valeurs qui a, selon le modèle, 95 % de chances de contenir le bon résultat.
Obtenir une explication en ligne à l'aide du modèle déployé
Vous pouvez demander une prédiction avec des explications (également appelées attributions de caractéristiques) pour voir comment votre modèle est arrivé à une prédiction. Les valeurs d'importance des caractéristiques locales indiquent dans quelle mesure chaque caractéristique a contribué au résultat prédit. Les attributions de caractéristiques sont incluses dans les prédictions d'IA Vertex via Vertex Explainable AI.
Console
Lorsque vous utilisez la console Google Cloud pour demander une prédiction en ligne, les valeurs d'importance des caractéristiques locales sont automatiquement renvoyées.
Si vous avez utilisé les valeurs de prédiction préremplies, les valeurs d'importance des caractéristiques locales sont toutes nulles. En effet, comme les valeurs préremplies sont les données de prédiction de base, la prédiction renvoyée correspond à la valeur de prédiction de référence.
gcloud
Créez un fichier nommé
request.json
avec le contenu suivant :{ "instances": [ { PREDICTION_DATA_ROW } ] }
Remplacez l'élément suivant :
-
PREDICTION_DATA_ROW : objet JSON avec des clés comme noms de caractéristiques et des valeurs en tant que valeurs de caractéristiques correspondantes. Par exemple, pour un ensemble de données comportant un nombre, un tableau de chaînes et une catégorie, la ligne de données peut ressembler à l'exemple de requête suivant :
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
Vous devez fournir une valeur pour chaque caractéristique incluse dans l'entraînement. Le format des données utilisées pour la prédiction doit correspondre à celui utilisé pour l'entraînement. Pour en savoir plus, consultez la section Format de données pour les prédictions.
-
Exécutez la commande suivante :
gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Remplacez les éléments suivants :
- ENDPOINT_ID : ID du point de terminaison.
- LOCATION_ID : région dans laquelle vous utilisez l'IA Vertex.
Si vous souhaitez envoyer une demande d'explication à une
DeployedModel
spécifique surEndpoint
, vous pouvez également spécifier l'option--deployed-model-id
:gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION \ --deployed-model-id=DEPLOYED_MODEL_ID \ --json-request=request.json
Outre les espaces réservés décrits précédemment, remplacez les éléments suivants :
-
DEPLOYED_MODEL_ID (facultatif) : ID du modèle déployé pour lequel vous souhaitez obtenir des explications. L'ID est inclus dans la réponse de la méthode
predict
. Si vous devez demander des explications pour un modèle particulier et que plusieurs modèles sont déployés sur le même point de terminaison, vous pouvez utiliser cet ID pour vous assurer que les explications sont renvoyées pour ce modèle particulier.
REST
L'exemple suivant montre une requête de prédiction en ligne pour un modèle de classification tabulaire avec des attributions de caractéristiques locales. Le format de requête est le même pour les modèles de régression.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
-
LOCATION : région où se trouve le point de terminaison. Par exemple,
us-central1
. - PROJECT : l'ID de votre projet.
- ENDPOINT_ID : ID du point de terminaison.
-
PREDICTION_DATA_ROW : objet JSON avec des clés comme noms de caractéristiques et des valeurs en tant que valeurs de caractéristiques correspondantes. Par exemple, pour un ensemble de données comportant un nombre, un tableau de chaînes et une catégorie, la ligne de données peut ressembler à l'exemple de requête suivant :
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
Vous devez fournir une valeur pour chaque caractéristique incluse dans l'entraînement. Le format des données utilisées pour la prédiction doit correspondre à celui utilisé pour l'entraînement. Pour en savoir plus, consultez la section Format de données pour les prédictions.
-
DEPLOYED_MODEL_ID (facultatif) : ID du modèle déployé pour lequel vous souhaitez obtenir des explications. L'ID est inclus dans la réponse de la méthode
predict
. Si vous devez demander des explications pour un modèle particulier et que plusieurs modèles sont déployés sur le même point de terminaison, vous pouvez utiliser cet ID pour vous assurer que les explications sont renvoyées pour ce modèle particulier.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain
Corps JSON de la requête :
{ "instances": [ { PREDICTION_DATA_ROW } ], "deployedModelId": "DEPLOYED_MODEL_ID" }
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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain"
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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
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.
Obtenir des explications sur une prédiction précédemment renvoyée
Étant donné que les explications augmentent l'utilisation des ressources, vous souhaiterez peut-être réserver des explications au cas où vous en auriez besoin. Parfois, il peut être utile de demander des explications pour un résultat de prédiction que vous avez déjà reçu, peut-être parce que la prédiction présentait une anomalie ou n'a pas été logique.
Si toutes vos prédictions proviennent du même modèle, il vous suffit de renvoyer les données de requête, en indiquant que vous souhaitez cette fois obtenir des explications. Cependant, si plusieurs modèles renvoient des prédictions, vous devez vous assurer d'envoyer la requête d'explication au modèle approprié. Vous pouvez afficher les explications d'un modèle particulier en incluant l'ID deployedModelID
du modèle déployé dans votre requête, qui est inclus dans la réponse à la requête de prédiction d'origine.
Notez que l'ID de modèle déployé est différent de l'ID du modèle.
Interpréter les résultats des explications
Pour calculer l'importance des caractéristiques locales, commencez par calculer le score de prédiction de référence. Les valeurs de référence sont calculées à partir des données d'entraînement, en utilisant la valeur médiane pour les caractéristiques numériques et le mode pour les caractéristiques catégorielles. La prédiction générée à partir des valeurs de référence correspond au score de prédiction de référence. Les valeurs de référence sont calculées une fois pour un modèle et ne changent pas.
Pour une prédiction spécifique, l'importance des caractéristiques locales de chaque caractéristique indique dans quelle mesure cette caractéristique affecte le résultat par rapport au score de prédiction de référence. La somme de toutes les valeurs d'importance de caractéristique est la différence entre le score de prédiction de référence et le résultat de la prédiction.
Pour les modèles de classification, le score est toujours compris entre 0,0 et 1,0 inclus. Par conséquent, les valeurs d'importance des caractéristiques locales pour les modèles de classification sont toujours comprises entre -1,0 et 1,0 (inclus).
Pour obtenir des exemples de requêtes d'attribution de caractéristiques et en savoir plus, consultez la section Attributions de caractéristiques pour la classification et la régression.Exemple de résultat pour les prédictions et les explications
Classification
La charge utile renvoyée pour une prédiction en ligne à partir d'un modèle de classification tabulaire avec importance des caractéristiques est semblable à l'exemple suivant.
La valeur instanceOutputValue
de 0.928652400970459
est le score de confiance de la classe la mieux notée, soit class_a
dans le cas présent. Le champ baselineOutputValue
contient le score de prédiction de référence, 0.808652400970459
. La caractéristique qui a le plus contribué à ce résultat est feature_3
.
{
"predictions": [
{
"scores": [
0.928652400970459,
0.071347599029541
],
"classes": [
"class_a",
"class_b"
]
}
]
"explanations": [
{
"attributions": [
{
"baselineOutputValue": 0.808652400970459,
"instanceOutputValue": 0.928652400970459,
"approximationError": 0.0058915703929231,
"featureAttributions": {
"feature_1": 0.012394922231235,
"feature_2": 0.050212341234556,
"feature_3": 0.057392736534209,
},
"outputIndex": [
0
],
"outputName": "scores"
}
],
}
]
"deployedModelId": "234567"
}
Régression
La charge utile renvoyée pour une prédiction en ligne avec importance des caractéristiques à partir d'un modèle de régression tabulaire est semblable à l'exemple suivant.
La valeur instanceOutputValue
de 1795.1246466281819
est la valeur prédite et les champs lower_bound
et upper_bound
indiquent un intervalle de confiance de 95 %.
Le champ baselineOutputValue
contient le score de prédiction de référence, 1788.7423095703125
. La caractéristique qui a le plus contribué à ce résultat est feature_3
.
{
"predictions": [
{
"value": 1795.1246466281819,
"lower_bound": 246.32196807861328,
"upper_bound": 8677.51904296875
}
]
"explanations": [
{
"attributions": [
{
"baselineOutputValue": 1788.7423095703125,
"instanceOutputValue": 1795.1246466281819,
"approximationError": 0.0038215703911553,
"featureAttributions": {
"feature_1": 0.123949222312359,
"feature_2": 0.802123412345569,
"feature_3": 5.456264423211472,
},
"outputIndex": [
-1
]
}
]
}
],
"deployedModelId": "345678"
}
Étapes suivantes
- Découvrez comment exporter votre modèle.