Obtenir des prédictions en ligne avec des modèles personnalisés

La prédiction en ligne Vertex AI est un service optimisé pour faire traiter vos données par des modèles hébergés avec le moins de latence possible. Vous envoyez de petits lots de données au service, et il renvoie vos prédictions dans la réponse.

Avant de commencer

Avant de lancer une requête de prédiction, vous devez suivre ces étapes :

Configurer le déploiement du modèle

Lors du déploiement du modèle, vous prenez les décisions importantes suivantes concernant l'exécution de la prédiction en ligne :

Ressource créée Paramètre spécifié lors de la création de la ressource
Point de terminaison Emplacement dans lequel exécuter les prédictions
Model Conteneur à utiliser (ModelContainerSpec)
DeployedModel Machines à utiliser pour la prédiction en ligne

Vous ne pouvez pas mettre à jour les paramètres répertoriés ci-dessus après la création initiale du modèle ou du point de terminaison, et vous ne pouvez pas les remplacer dans la requête de prédiction en ligne. Pour modifier ces paramètres, vous devez redéployer votre modèle.

Mettre en forme votre entrée pour la prédiction en ligne

Si vous utilisez l'un de nos conteneurs prédéfinis pour diffuser des prédictions à l'aide de TensorFlow, scikit-learn ou XGBoost, vos instances d'entrée de prédiction doivent être au format JSON.

Si votre modèle utilise un conteneur personnalisé, votre entrée doit être au format JSON et un champ parameters supplémentaire peut être utilisé pour votre conteneur. Apprenez-en plus sur la mise en forme des entrées de prédiction avec des conteneurs personnalisés.

Cette section explique comment formater vos instances d'entrée de prédiction au format JSON et comment gérer les données binaires avec l'encodage base64.

Mettre en forme les instances en tant que chaînes JSON

Le format de base pour la prédiction en ligne est une liste d'instances de données. Il peut s'agir de listes de valeurs ou de membres d'un objet JSON, selon la configuration des entrées dans l'application d'entraînement. Les modèles TensorFlow peuvent accepter des entrées plus complexes, tandis que la plupart des modèles scikit-learn et XGBoost attendent une liste de nombres en entrée.

Cet exemple illustre un Tensor d'entrée et une clé d'instance pour un modèle TensorFlow :

{"values": [1, 2, 3, 4], "key": 1}

La composition de la chaîne JSON peut être complexe tant qu'elle suit les règles suivantes :

  • Le premier niveau des données d'instance doit être un objet JSON, soit un dictionnaire de paires clé/valeur.

  • Les valeurs individuelles dans un objet d'instance peuvent être des chaînes, des nombres ou des listes. Vous ne pouvez pas intégrer d'objets JSON.

  • Les listes doivent contenir uniquement des éléments du même type (y compris d'autres listes). Vous ne pouvez pas mélanger des valeurs numériques et des chaînes.

Vous devez transmettre les instances d'entrée pour la prédiction en ligne en tant que corps de message lors de l'appel projects.locations.endpoints.predict. Apprenez-en plus sur les exigences concernant la mise en forme du corps de la requête.

Faites de chaque instance un élément dans un tableau JSON et fournissez le tableau en tant que champ instances d'un objet JSON. Exemple :

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

Encoder des données binaires pour l'entrée de prédiction

Les données binaires ne peuvent pas être mises en forme en tant que chaînes encodées UTF-8 compatibles avec JSON. Si des données binaires apparaissent dans les entrées, vous devez les représenter à l'aide de l'encodage base64. Le format spécial suivant est requis :

  • La chaîne encodée doit être mise en forme en tant qu'objet JSON avec une seule clé nommée b64. Dans Python 3.5, l'encodage base64 génère une séquence d'octets. Vous devez la convertir en chaîne pour la rendre sérialisable en JSON :

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}

  • Dans le code de modèle TensorFlow, vous devez nommer les alias pour les Tensors binaires d'entrée et de sortie de façon qu'ils se terminent par "_bytes".

Exemples de demandes et de réponses

Cette section décrit le format du corps de la requête de prédiction et du corps de la réponse, avec des exemples pour TensorFlow, scikit-learn et XGBoost.

Informations sur le corps de la requête

TensorFlow

Le corps de la requête contient des données respectant la structure suivante (représentation JSON) :

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

L'objet instances[] est requis et doit contenir la liste des instances pour lesquelles les prédictions sont demandées.

La structure de chaque élément de la liste d'instances est déterminée par la définition d'entrée de votre modèle. Les instances peuvent inclure des entrées nommées (sous forme d'objets) ou ne contenir que des valeurs sans étiquette.

Toutes les données ne comprennent pas des entrées nommées. Certaines instances sont des valeurs JSON simples (valeurs booléennes, nombres ou chaînes). Cependant, les instances sont souvent des listes de valeurs simples ou des listes imbriquées complexes.

Vous trouverez ci-dessous quelques exemples de corps de requête.

Données CSV avec chaque ligne encodée sous forme de valeur de chaîne :

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

Texte brut :

{"instances": ["the quick brown fox", "the lazy dog"]}

Phrases encodées sous forme de listes de mots (vecteurs de chaînes) :

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

Valeurs scalaires à virgule flottante :

{"instances": [0.0, 1.1, 2.2]}

Vecteurs d'entiers :

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

Tensors (ici, Tensors bidimensionnels) :

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

Images, qui peuvent être représentées de différentes manières. Dans ce schéma d'encodage, les deux premières dimensions représentent les lignes et les colonnes de l'image, et la troisième dimension contient les listes (vecteurs) de valeurs R, V et B pour chaque pixel :

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

Encodage des données

Les chaînes JSON doivent être encodées au format UTF-8. Pour envoyer des données binaires, vous devez encoder les données en base64 et les marquer comme binaires. Pour marquer une chaîne JSON comme binaire, remplacez-la par un objet JSON avec un seul attribut nommé b64 : 

{"b64": "..."}

L'exemple suivant montre deux instances tf.Examples sérialisées, nécessitant un codage en base64 (données fictives, uniquement à des fins d'illustration) :

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

L'exemple suivant montre deux chaînes d'octets d'image JPEG, nécessitant un encodage en base64 (données factices, uniquement à des fins d'illustration) :

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

Tensors d'entrée multiples

Certains modèles disposent d'un graphique TensorFlow sous-jacent qui accepte plusieurs Tensors d’entrée. Dans ce cas, utilisez les noms des paires nom/valeur JSON pour identifier les Tensors d'entrée.

Pour un graphique avec les alias de Tensor d'entrée "tag" (chaîne) et "image" (chaîne encodée en base64) :

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

Pour un graphique avec les alias de Tensor d'entrée "tag" (chaîne) et "image" (tableau tridimensionnel d'entiers de 8 bits) :

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

Le corps de la requête contient des données respectant la structure suivante (représentation JSON) :

{
  "instances": [
    <simple list>,
    ...
  ]
}

L'objet instances[] est requis et doit contenir la liste des instances pour lesquelles les prédictions sont demandées. Dans l'exemple suivant, chaque instance d'entrée est une liste de nombres à virgule flottante :

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

La dimension des instances d'entrée doit correspondre aux attentes de votre modèle. Par exemple, si le modèle nécessite trois caractéristiques, la longueur de chaque instance d'entrée doit être de 3.

XGBoost

Le corps de la requête contient des données respectant la structure suivante (représentation JSON) :

{
  "instances": [
    <simple list>,
    ...
  ]
}

L'objet instances[] est requis et doit contenir la liste des instances pour lesquelles les prédictions sont demandées. Dans l'exemple suivant, chaque instance d'entrée est une liste de nombres à virgule flottante :

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

La dimension des instances d'entrée doit correspondre aux attentes de votre modèle. Par exemple, si le modèle nécessite trois caractéristiques, la longueur de chaque instance d'entrée doit être de 3.

L'IA Vertex n'est pas compatible avec la représentation creuse des instances d'entrée pour XGBoost.

Le service de prédiction en ligne interprète les zéros et les NaN différemment. Si la valeur d'une caractéristique est de zéro, utilisez 0.0 dans l'entrée correspondante. Si la valeur d'une caractéristique est manquante, utilisez "NaN" dans l'entrée correspondante.

L'exemple suivant représente une requête de prédiction avec une seule instance d'entrée, où la valeur de la première caractéristique est 0.0, la valeur de la deuxième caractéristique est 1.1 et la valeur de la troisième caractéristique est manquante :

{"instances": [[0.0, 1.1, "NaN"]]}

Informations sur le corps de la réponse

Les réponses sont très semblables aux requêtes.

Si l'appel aboutit, le corps de la réponse contient une entrée de prédiction par instance du corps de la requête, dans le même ordre :

{
  "predictions": [
    {
      object
    }
  ],
  "deployedModelId": string
}

En cas d'échec de la prédiction pour une instance, le corps de la réponse ne contient aucune prédiction. Au lieu de cela, il contient une seule entrée d'erreur :

{
  "error": string
}

L'objet predictions[] contient la liste des prédictions, une pour chaque instance de la requête.

En cas d'erreur, la chaîne error contient un message décrivant le problème. L'erreur est affichée à la place d'une liste de prédictions si une erreur s'est produite lors du traitement d'une instance.

Même s'il existe une prédiction par instance, le format d'une prédiction n'est pas directement lié à celui d'une instance. Les prédictions prennent le format spécifié dans l'ensemble de sorties défini dans le modèle. L'ensemble de prédictions est affiché dans une liste JSON. Chaque membre de la liste peut être une valeur simple, une liste ou un objet JSON de n'importe quelle complexité. Si votre modèle comporte plusieurs Tensors de sortie, chaque prédiction sera un objet JSON contenant une paire nom/valeur pour chaque sortie. Les noms identifient les alias de sortie dans le graphique.

Exemples de corps de réponse

TensorFlow

Les exemples suivants présentent des réponses possibles :

  • Un ensemble simple de prédictions pour trois instances d'entrée, où chaque prédiction est une valeur entière :

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

  • Ensemble plus complexe de prédictions, chacune contenant deux valeurs nommées qui correspondent aux Tensors de sortie, respectivement nommés label et scores. La valeur label correspond à la catégorie prédite ("voiture" ou "plage") et scores contient une liste de probabilités pour cette instance parmi les catégories possibles.

    {
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ],
  "deployedModelId": 123456789012345678
}

  • Une réponse en cas d'erreur lors du traitement d'une instance d'entrée :

    {"error": "Divide by zero"}

scikit-learn

Les exemples suivants présentent des réponses possibles :

  • Un ensemble simple de prédictions pour trois instances d'entrée, où chaque prédiction est une valeur entière :

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

  • Une réponse en cas d'erreur lors du traitement d'une instance d'entrée :

    {"error": "Divide by zero"}

XGBoost

Les exemples suivants présentent des réponses possibles :

  • Un ensemble simple de prédictions pour trois instances d'entrée, où chaque prédiction est une valeur entière :

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

  • Une réponse en cas d'erreur lors du traitement d'une instance d'entrée :

    {"error": "Divide by zero"}

Envoyer une requête de prédiction en ligne

Effectuez une requête de prédiction en ligne en envoyant les instances de données d'entrée en tant que chaîne JSON dans une requête predict. Pour en savoir plus sur le format du corps de la requête et de la réponse, consultez les détails de la requête de prédiction.

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.

gcloud

L'exemple suivant utilise la commande gcloud ai endpoints predict :

  1. Écrivez l'objet JSON suivant dans un fichier dans votre environnement local. Le nom de fichier n'a pas d'importance, mais pour cet exemple, nommez le fichier request.json.

    {
 "instances": INSTANCES
}

    Remplacez l'élément suivant :

    • INSTANCES : tableau JSON d'instances pour lesquelles vous souhaitez obtenir des prédictions. Le format de chaque instance dépend des entrées attendues par un modèle de ML entraîné particulier. Consultez la section Formater vos entrées pour la prédiction en ligne de ce document.

  2. Exécutez la commande suivante :

    gcloud ai endpoints predict ENDPOINT_ID \
  --region=LOCATION \
  --json-request=request.json

    Remplacez l'élément suivant :

    • ENDPOINT_ID : ID du point de terminaison.
    • LOCATION : région dans laquelle vous utilisez l'IA Vertex.

API REST et ligne de commande

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

  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT : ID de votre projet
  • ENDPOINT_ID : ID du point de terminaison.
  • INSTANCES : tableau JSON d'instances pour lesquelles vous souhaitez obtenir des prédictions. Le format de chaque instance dépend des entrées attendues par un modèle de ML entraîné particulier. Consultez la section Formater vos entrées pour la prédiction en ligne de ce document.

Méthode HTTP et URL :

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict

Corps JSON de la requête : 

{
  "instances": INSTANCES
}

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 application-default 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:predict"

PowerShell

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

$cred = gcloud auth application-default 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:predict" | Select-Object -Expand Content
Si l'opération réussit, vous recevez une réponse JSON semblable à la suivante. Dans la réponse, attendez le remplacement des éléments suivants :
  • PREDICTIONS : tableau JSON de prédictions, une pour chaque instance que vous avez incluse dans le corps de la requête.
  • DEPLOYED_MODEL_ID : ID du DeployedModel qui a diffusé ces prédictions. 
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour Vertex AI, consultez Bibliothèques clientes Vertex AI. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java. 


import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.List;

public class PredictCustomTrainedModelSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String project = "YOUR_PROJECT_ID";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictCustomTrainedModel(project, endpointId, instance);
  }

  static void predictCustomTrainedModel(String project, String endpointId, String instance)
      throws IOException {
    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.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 (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      String location = "us-central1";
      EndpointName endpointName = EndpointName.of(project, location, endpointId);

      ListValue.Builder listValue = ListValue.newBuilder();
      JsonFormat.parser().merge(instance, listValue);
      List<Value> instanceList = listValue.getValuesList();

      PredictRequest predictRequest =
          PredictRequest.newBuilder()
              .setEndpoint(endpointName.toString())
              .addAllInstances(instanceList)
              .build();
      PredictResponse predictResponse = predictionServiceClient.predict(predictRequest);

      System.out.println("Predict Custom Trained model Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.getDeployedModelId());
      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        System.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }
}

Node.js

Pour savoir comment installer et utiliser la bibliothèque cliente pour Vertex AI, consultez Bibliothèques clientes Vertex AI. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Node.js. 

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const filename = "YOUR_PREDICTION_FILE_NAME";
// const endpointId = "YOUR_ENDPOINT_ID";
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const util = require('util');
const {readFile} = require('fs');
const readFileAsync = util.promisify(readFile);

// Imports the Google Cloud Prediction Service Client library
const {PredictionServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictCustomTrainedModel() {
  // Configure the parent resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = {
    structValue: {
      fields: {},
    },
  };
  const instanceDict = await readFileAsync(filename, 'utf8');
  const instanceValue = JSON.parse(instanceDict);
  const instance = {
    structValue: {
      fields: {
        Age: {stringValue: instanceValue['Age']},
        Balance: {stringValue: instanceValue['Balance']},
        Campaign: {stringValue: instanceValue['Campaign']},
        Contact: {stringValue: instanceValue['Contact']},
        Day: {stringValue: instanceValue['Day']},
        Default: {stringValue: instanceValue['Default']},
        Deposit: {stringValue: instanceValue['Deposit']},
        Duration: {stringValue: instanceValue['Duration']},
        Housing: {stringValue: instanceValue['Housing']},
        Job: {stringValue: instanceValue['Job']},
        Loan: {stringValue: instanceValue['Loan']},
        MaritalStatus: {stringValue: instanceValue['MaritalStatus']},
        Month: {stringValue: instanceValue['Month']},
        PDays: {stringValue: instanceValue['PDays']},
        POutcome: {stringValue: instanceValue['POutcome']},
        Previous: {stringValue: instanceValue['Previous']},
      },
    },
  };

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict custom trained model response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const prediction of predictions) {
    console.log(`\t\tPrediction : ${JSON.stringify(prediction)}`);
  }
}
predictCustomTrainedModel();

Python

Pour savoir comment installer et utiliser la bibliothèque cliente pour Vertex AI, consultez Bibliothèques clientes Vertex AI. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python. 

def endpoint_predict_sample(
    project: str, location: str, instances: list, endpoint: str
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint)

    prediction = endpoint.predict(instances=instances)
    print(prediction)
    return prediction

Envoyer une requête de prédiction brute en ligne

Vous pouvez également envoyer une requête de prédiction brute, qui vous permet d'utiliser une charge utile HTTP arbitraire au lieu de suivre les consignes strictes décrites dans les sections précédentes de ce guide.

Vous pouvez obtenir des prédictions brutes si vous utilisez un conteneur personnalisé qui reçoit des requêtes et envoie des réponses différentes des consignes.

gcloud

L'exemple suivant utilise la commande gcloud ai endpoints raw-predict :

  • Pour demander des prédictions avec l'objet JSON dans REQUEST spécifié sur la ligne de commande, procédez comme suit:

    gcloud ai endpoints raw-predict ENDPOINT_ID \
  --region=LOCATION \
  --request REQUEST
  • Pour demander des prédictions avec une image stockée dans le fichier image.jpeg et l'en-tête Content-Type approprié:

    gcloud ai endpoints raw-predict ENDPOINT_ID \
  --region=LOCATION \
  --http-headers=Content-Type=image/jpeg \
  --request @image.jpeg

Remplacez les éléments suivants :

  • ENDPOINT_ID : ID du point de terminaison.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • REQUEST: contenu de la requête pour lequel vous souhaitez obtenir des prédictions. Le format de la requête dépend des attentes de votre conteneur personnalisé, qui ne sont pas nécessairement un objet JSON.

La réponse inclut les en-têtes HTTP suivants:

  • X-Vertex-AI-Endpoint-Id: ID du Endpoint qui a diffusé cette prédiction.

  • X-Vertex-AI-Deployed-Model-Id : ID du DeployedModel du point de terminaison qui a diffusé cette prédiction.

Envoyer une demande d'explication en ligne

Si vous avez configuré votre Model pour Vertex Explainable AI, vous pouvez obtenir des explications en ligne. Les requêtes d'explication en ligne ont le même format que les requêtes de prédiction en ligne et renvoient des réponses similaires. La seule différence réside dans le fait que les réponses d'explications en ligne incluent les attributions de caractéristiques et les prédictions.

Les exemples suivants sont presque identiques à ceux de la section précédente, sauf qu'ils utilisent des commandes légèrement différentes :

gcloud

L'exemple suivant utilise la commande gcloud ai endpoints explain :

  1. Écrivez l'objet JSON suivant dans un fichier dans votre environnement local. Le nom de fichier n'a pas d'importance, mais pour cet exemple, nommez le fichier request.json.

    {
 "instances": INSTANCES
}

    Remplacez l'élément suivant :

    • INSTANCES : tableau JSON d'instances pour lesquelles vous souhaitez obtenir des prédictions. Le format de chaque instance dépend des entrées attendues par un modèle de ML entraîné particulier. Consultez la section Formater vos entrées pour la prédiction en ligne de ce document.

  2. Exécutez la commande suivante :

    gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION \
  --json-request=request.json

    Remplacez l'élément suivant :

    • ENDPOINT_ID : ID du point de terminaison.
    • LOCATION : région dans laquelle vous utilisez l'IA Vertex.

    Si vous souhaitez envoyer une demande d'explication à une DeployedModel spécifique sur Endpoint, 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.

API REST et ligne de commande

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

  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT : ID de votre projet
  • ENDPOINT_ID : ID du point de terminaison.
  • INSTANCES : tableau JSON d'instances pour lesquelles vous souhaitez obtenir des prédictions. Le format de chaque instance dépend des entrées attendues par un modèle de ML entraîné particulier. Consultez la section Formater vos entrées pour la prédiction en ligne de ce document.

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": INSTANCES
}

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 application-default 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 application-default 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
Si l'opération réussit, vous recevez une réponse JSON semblable à la suivante. Dans la réponse, attendez le remplacement des éléments suivants :
  • PREDICTIONS : tableau JSON de prédictions, une pour chaque instance que vous avez incluse dans le corps de la requête.
  • EXPLANATIONS : un tableau JSON d'explications, une pour chaque prédiction.
  • DEPLOYED_MODEL_ID : ID du DeployedModel qui a diffusé ces prédictions. 
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Pour savoir comment installer et utiliser la bibliothèque cliente pour Vertex AI, consultez Bibliothèques clientes Vertex AI. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python. 

def explain_tabular_sample(
    project: str, location: str, endpoint_id: str, instance_dict: Dict
):

    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_id)

    response = endpoint.explain(instances=[instance_dict], parameters={})

    for explanation in response.explanations:
        print(" explanation")
        # Feature attributions.
        attributions = explanation.attributions
        for attribution in attributions:
            print("  attribution")
            print("   baseline_output_value:", attribution.baseline_output_value)
            print("   instance_output_value:", attribution.instance_output_value)
            print("   output_display_name:", attribution.output_display_name)
            print("   approximation_error:", attribution.approximation_error)
            print("   output_name:", attribution.output_name)
            output_index = attribution.output_index
            for output_index in output_index:
                print("   output_index:", output_index)

    for prediction in response.predictions:
        print(prediction)

Étape suivante