Obtenir des inférences en ligne à partir d'un modèle entraîné personnalisé

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

Mettre en forme votre entrée pour l'inférence en ligne

Cette section explique comment formater et encoder vos instances d'entrée d'inférence 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 Envoyer une requête au point de terminaison.

Si vous utilisez le SDK Vertex AI pour Python pour envoyer des requêtes d'inférence, 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 d'inférence avec des conteneurs personnalisés.

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

Le format de base pour l'inférence en ligne est une liste d'instances de données. Il peut s'agir de simples 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 tenseur 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 l'inférence 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 d'inférence

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 en 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 tenseurs binaires d'entrée et de sortie de façon qu'ils se terminent par "_bytes".

Exemples de requêtes et de réponses

Cette section décrit le format du corps de la requête d'inférence 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 inférences 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 inférences 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 inférences 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.

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

Le service d'inférence 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 d'inférence 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. Par 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 d'inférence par instance du corps de la requête, dans le même ordre :

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

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

{
  "error": string
}

L'objet predictions[] contient la liste des inférences, 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 d'inférences si une erreur s'est produite lors du traitement d'une instance.

Même s'il existe une inférence par instance, le format d'une inférence n'est pas directement lié à celui d'une instance. Les inférences prennent le format spécifié dans l'ensemble de sorties défini dans le modèle. L'ensemble des inférences est renvoyé 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 inférence 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 quatre façons d'envoyer une demande :

  • Requête d'inférence : envoie une requête à predict pour obtenir une inférence en ligne.

  • Requête d'inférence brute : envoie une requête à rawPredict, ce qui vous permet d'utiliser une charge utile HTTP arbitraire au lieu de suivre les consignes décrites dans les sections de mise en forme des entrées de cette page. Vous pouvez obtenir des inférences brutes dans les cas suivants :

    • Vous utilisez un conteneur personnalisé qui reçoit des requêtes et envoie des réponses différentes des consignes.
    • Vous avez besoin d'une latence plus faible. rawPredict ignore les étapes de sérialisation et transfère directement la requête au conteneur d'inférence.
    • Vous diffusez des inférences avec NVIDIA Triton.
  • Requête d'explication : envoie une requête à explain. 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 d'inférence 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 inférences.

  • Invoke request (Appeler la requête) : transmet une requête arbitraire au serveur de modèle. Par exemple, "/invoke/foo/bar" serait transféré en tant que "/foo/bar" au serveur de modèle. Cette fonctionnalité est en version preview publique et n'est compatible qu'avec les appels HTTP sur des points de terminaison dédiés. Pour créer un modèle avec appel activé, suivez les instructions pour utiliser des routes personnalisées arbitraires.

Envoyer une requête d'inférence en ligne à un point de terminaison public dédié

Les points de terminaison dédiés facilitent la communication à l'aide des protocoles HTTP et gRPC. Pour les requêtes gRPC, l'inclusion de l'en-tête x-vertex-ai-endpoint-id est obligatoire pour assurer une identification précise du point de terminaison. Les API suivantes sont compatibles avec ces points de terminaison dédiés :

  • Predict
  • RawPredict
  • StreamRawPredict
  • Chat Completion (Model Garden uniquement)
  • Appeler

Les points de terminaison dédiés utilisent un nouveau chemin d'URL. Vous pouvez récupérer ce chemin d'accès à partir du champ dedicatedEndpointDns dans l'API REST ou à partir de Endpoint.dedicated_endpoint_dns dans le SDK Vertex AI pour Python. Vous pouvez également créer le chemin d'accès du point de terminaison manuellement à l'aide du code suivant :

f"https://ENDPOINT_ID.LOCATION_ID-PROJECT_NUMBER.prediction.vertexai.goog/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

Remplacez les éléments suivants :

  • ENDPOINT_ID : ID du point de terminaison.
  • LOCATION_ID : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_NUMBER : numéro du projet. Cette donnée est différente de l'ID du projet. Vous pouvez trouver le numéro de projet sur la page Paramètres du projet du projet dans la console Google Cloud .

Pour envoyer une inférence à un point de terminaison dédié à l'aide du SDK Vertex AI pour Python, définissez le paramètre use_dedicated_endpoint sur True :

endpoint.predict(instances=instances, use_dedicated_endpoint=True)

Envoyer une requête d'inférence en ligne à un point de terminaison public partagé

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 inférences. 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 l'inférence en ligne.

  2. 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 Vertex AI.

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 de votre projet.
  • ENDPOINT_ID : ID du point de terminaison.
  • INSTANCES : tableau JSON d'instances pour lesquelles vous souhaitez obtenir des inférences. 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 l'inférence 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, vous pouvez vous attendre au remplacement des éléments suivants :
  • PREDICTIONS : tableau JSON de prédictions, un pour chaque instance que vous avez incluse dans le corps de la requête.
  • DEPLOYED_MODEL_ID : ID du DeployedModel qui a livré 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 sur l'utilisation 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 sur l'utilisation 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 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.

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 d'inférence brute en ligne

gcloud

Les exemples suivants utilisent la commande gcloud ai endpoints raw-predict :

  • Pour demander une inférence 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_ID \
         --request=REQUEST
     
  • Pour demander des inférences 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_ID \
         --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 laquelle vous souhaitez obtenir des inférences. 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 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.

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 inférence.

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

Envoyer une requête 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 inférences. 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 l'inférence en ligne.

  2. 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 Vertex AI.

    Si vous souhaitez envoyer une demande d'explication à un élément 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 :
  • ENDPOINT_ID : ID du point de terminaison.
  • INSTANCES : tableau JSON d'instances pour lesquelles vous souhaitez obtenir des inférences. 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 l'inférence 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, vous pouvez vous attendre au remplacement des éléments suivants :
  • PREDICTIONS : tableau JSON de prédictions, un pour chaque instance que vous avez incluse dans le corps de la requête.
  • EXPLANATIONS : un tableau JSON d'explications, un pour chaque prédiction.
  • DEPLOYED_MODEL_ID : ID du DeployedModel qui a livré ces prédictions.
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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.

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)

Envoyer une requête d'appel en ligne

La route d'appel permet d'accéder à tous les chemins de requête non racine du déploiement. Par exemple, /invoke/foo/bar sera transmis en tant que /foo/bar au serveur de modèle. Il existe deux façons d'accéder à l'itinéraire.

demande de route personnalisée à un point de terminaison dédié.

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.

def invoke_tabular_sample(
    project: str,
    location: str,
    endpoint_id: str,
    request_path: str,
    http_request_body: Dict[str, Any],
    stream: bool = False,
):
    aiplatform.init(project=project, location=location)

    dedicated_endpoint = aiplatform.Endpoint(endpoint_id)
    if stream:
        for chunk in dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            stream=True,
        ):
            print(chunk)
    else:
        response = dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
        )
        print(response)

envoyer une requête d'itinéraire personnalisé directement au modèle déployé ;

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.

def invoke_direct_deployed_model_inference_tabular_sample(
    project: str,
    location: str,
    endpoint_id: str,
    request_path: str,
    http_request_body: Dict[str, Any],
    deployed_model_id: str,
    stream: bool = False,
):
    aiplatform.init(project=project, location=location)

    dedicated_endpoint = aiplatform.Endpoint(endpoint_id)
    if stream:
        for chunk in dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            deployed_model_id=deployed_model_id,
            stream=True,
        ):
            print(chunk)
    else:
        response = dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            deployed_model_id=deployed_model_id,
        )
        print(response)

Étapes suivantes