Obtenir des prédictions à partir d'un modèle entraîné personnalisé

Cette page vous explique comment obtenir des prédictions en ligne (en temps réel) à partir de vos modèles entraînés personnalisés à l'aide de la console Google Cloud ou de l'API Vertex AI.

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

Cette section explique comment formater et encoder vos instances d'entrée de prédiction au format JSON, ce qui est nécessaire si vous utilisez la méthode predict ou explain. Cette étape n'est pas nécessaire si vous utilisez la méthode rawPredict. Pour savoir quelle méthode choisir, consultez la section Envoyer une requête au point de terminaison.

Si vous utilisez le SDK Vertex AI pour Python pour envoyer des requêtes de prédiction, spécifiez la liste des instances sans le champ instances. Par exemple, spécifiez [ ["the","quick","brown"], ... ] au lieu de { "instances": [ ["the","quick","brown"], ... ] }.

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.

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 : 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 au format 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, 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"]]}

PyTorch

Si votre modèle utilise un conteneur prédéfini PyTorch, les gestionnaires par défaut de TorchServe s'attendent à ce que chaque instance soit encapsulée dans un champ data. Exemple :

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

Informations sur le corps de la réponse

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 à un point de terminaison

Il existe trois façons d'envoyer une requête :

Envoyer une requête de prédiction en ligne

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 les éléments suivants :

    • 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 votre modèle de ML entraîné. Pour en savoir plus, consultez la section Mettre en forme vos entrées pour la prédiction en ligne.

  2. Exécutez la commande suivante :

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

    Remplacez l'élément suivant :

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

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 : ID du 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 votre modèle de ML entraîné. Pour en savoir plus, consultez la section Mettre en forme vos entrées pour la prédiction en ligne.

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

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. 


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

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. 

/**
 * 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 ou mettre à jour le SDK pour Python, consultez la page Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API 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

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_ID : 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.

Python

Pour savoir comment installer ou mettre à jour le SDK pour Python, consultez la page Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python. 

# -*- coding: utf-8 -*-
# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Generated code. DO NOT EDIT!
#
# Snippet for RawPredict
# NOTE: This snippet has been automatically generated for illustrative purposes only.
# It may require modifications to work in your environment.

# To install the latest published package dependency, execute the following:
#   python3 -m pip install google-cloud-aiplatform

from google.cloud import aiplatform_v1

def sample_raw_predict():
    # Create a client
    client = aiplatform_v1.PredictionServiceClient()

    # Initialize request argument(s)
    request = aiplatform_v1.RawPredictRequest(
        endpoint="endpoint_value",
    )

    # Make the request
    response = client.raw_predict(request=request)

    # Handle the response
    print(response)

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

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 les éléments suivants :

    • 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 votre modèle de ML entraîné. Pour en savoir plus, consultez la section Mettre en forme vos entrées pour la prédiction en ligne.

  2. Exécutez la commande suivante :

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

    Remplacez l'élément suivant :

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

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 : ID du 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 votre modèle de ML entraîné. Pour en savoir plus, consultez la section Mettre en forme vos entrées pour la prédiction en ligne.

Méthode HTTP et URL : 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/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 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: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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/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 ou mettre à jour le SDK pour Python, consultez la page Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API 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)

Étapes suivantes