Mettre en forme vos requêtes de prédiction

Utilisez les prédictions en ligne lorsque vous effectuez des requêtes en réponse à une entrée d'application ou dans des situations nécessitant une inférence rapide (réponses en temps réel).

Cette page explique comment mettre en forme les requêtes de prédiction en ligne à l'aide de l'API Online Prediction pour vos modèles entraînés personnalisés. Elle fournit également des exemples de requêtes et de réponses. Après avoir mis en forme votre requête, vous pouvez obtenir une prédiction en ligne.

Avant de commencer

Avant de mettre en forme une requête pour effectuer des prédictions en ligne, suivez les étapes suivantes :

1. Exportez votre artefact de modèle pour la prédiction.

2. Déployez la ressource de modèle sur un point de terminaison.

   Cette action associe des ressources de calcul au modèle afin qu'il puisse diffuser des prédictions en ligne avec une faible latence.

3. Vérifiez l'état de la ressource personnalisée DeployedModel de votre modèle et assurez-vous qu'il est prêt à accepter les requêtes de prédiction :

   kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f DEPLOYED_MODEL_NAME.yaml -o jsonpath='{.status.primaryCondition}'
   

   Remplacez les éléments suivants :

   • PREDICTION_CLUSTER_KUBECONFIG : chemin d'accès au fichier kubeconfig dans le cluster de prédiction.
   • DEPLOYED_MODEL_NAME : nom du fichier de définition DeployedModel.

   La condition principale doit indiquer que DeployedModel est prêt.

   Le résultat suivant affiche un exemple de réponse :

   {"firstObservedTime":"2024-01-19T01:18:30Z","lastUpdateTime":"2024-01-19T01:35:47Z","message":"DeployedModel is ready", "observedGeneration":1, "reason":"Ready", "resourceName":"my-tf-model","type":"DeployedModel"}
   

4. Vérifiez l'état de la ressource personnalisée Endpoint et assurez-vous qu'elle est prête à accepter les requêtes de prédiction :

   kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f ENDPOINT_NAME.yaml -o jsonpath='{$.status.conditions[?(@.type == "EndpointReady")]}'
   

   Remplacez les éléments suivants :

   • PREDICTION_CLUSTER_KUBECONFIG : chemin d'accès au fichier kubeconfig dans le cluster de prédiction.
   • ENDPOINT_NAME : nom du fichier de définition Endpoint.

   Le champ status de la condition EndpointReady doit afficher la valeur True.

   Le résultat suivant affiche un exemple de réponse :

   {"lastTransitionTime":"2024-01-19T05:12:26Z","message":"Endpoint Ready", "observedGeneration":1,"reason":"ResourceReady","status":"True","type":"EndpointReady"}%
   

Mettre en forme vos entrées pour les prédictions en ligne

La prédiction en ligne propose les deux méthodes suivantes pour envoyer des requêtes :

• Requête de prédiction : envoie une requête à la méthode predict pour obtenir une prédiction en ligne.
• Requête de prédiction brute : envoie une requête à la méthode rawPredict, ce qui vous permet d'utiliser une charge utile HTTP arbitraire au lieu de suivre un format JSON.

Si vous avez besoin d'une faible latence, obtenez des prédictions brutes, car rawPredict ignore les étapes de sérialisation et transfère directement la requête au conteneur de prédiction.

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. Ces informations ne sont pas nécessaires si vous utilisez la méthode rawPredict.

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"], ... ] }.

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 simples listes de valeurs ou de membres d'un objet JSON, selon la configuration des entrées dans votre application d'entraînement. Les modèles TensorFlow peuvent accepter des entrées plus complexes.

L'exemple suivant 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). Ne mélangez pas les chaînes et les valeurs numériques.

Vous devez transmettre les instances d'entrée pour la prédiction en ligne en tant que corps de message lors de l'appel 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, comme dans l'exemple suivant :

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

Vous ne pouvez pas mettre en forme les données binaires en tant que chaînes encodées au format UTF-8 compatibles avec JSON. Si vos données d'entrée comportent des données binaires, utilisez l'encodage base64 pour les représenter. Vous devez utiliser la mise en forme spéciale suivante :

• Mettez en forme votre chaîne encodée 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. Convertissez cette séquence 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, nommez les alias pour les Tensors 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 des corps de requête et de réponse de prédiction en ligne, avec des exemples pour TensorFlow et PyTorch.

Informations sur le corps de la requête

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

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

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

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

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

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

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

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

{"b64": "..."}

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

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

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

{
  "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],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

{
  "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 dans le 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, une liste ou un objet JSON de n'importe quelle complexité. Si votre modèle comporte plusieurs Tensors de sortie, chaque prédiction est un objet JSON contenant une paire clé/valeur pour chaque sortie. Les clés identifient les alias de sortie dans le graphique.

Exemples de corps de réponse

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

• Un ensemble 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"}