Vorhersageanfragen formatieren

Verwenden Sie Onlinevorhersagen, wenn Sie Anfragen als Reaktion auf Anwendungseingaben stellen oder wenn zeitnahe Inferenzen (Echtzeitantworten) erforderlich sind.

Auf dieser Seite wird beschrieben, wie Sie Onlinevorhersageanfragen mit der Online Prediction API für Ihre benutzerdefinierten trainierten Modelle formatieren. Außerdem finden Sie Beispiele für Anfragen und Antworten. Nachdem Sie Ihre Anfrage formatiert haben, können Sie eine Onlinevorhersage abrufen.

Hinweise

Bevor Sie eine Anfrage für Onlinevorhersagen formatieren, führen Sie die folgenden Schritte aus:

1. Modellartefakt für Vorhersagen exportieren

2. Modellressource in einem Endpunkt bereitstellen

   Durch diese Aktion werden dem Modell Rechenressourcen zugeordnet, sodass es Onlinevorhersagen mit niedriger Latenz bereitstellen kann.

3. Prüfen Sie den Status der benutzerdefinierten DeployedModel-Ressource Ihres Modells und stellen Sie sicher, dass sie bereit ist, Vorhersageanfragen anzunehmen:

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

   Ersetzen Sie Folgendes:

   • PREDICTION_CLUSTER_KUBECONFIG: Der Pfad zur kubeconfig-Datei im Vorhersagecluster.
   • DEPLOYED_MODEL_NAME: der Name der DeployedModel-Definitionsdatei.

   In der primären Bedingung muss angezeigt werden, dass DeployedModel bereit ist.

   Die folgende Ausgabe zeigt eine Beispielantwort:

   {"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. Prüfen Sie den Status der benutzerdefinierten Endpoint-Ressource und stellen Sie sicher, dass sie bereit ist, Vorhersageanfragen anzunehmen:

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

   Ersetzen Sie Folgendes:

   • PREDICTION_CLUSTER_KUBECONFIG: Der Pfad zur kubeconfig-Datei im Vorhersagecluster.
   • ENDPOINT_NAME: der Name der Endpoint-Definitionsdatei.

   Das Feld status der Bedingung EndpointReady muss den Wert True enthalten.

   Die folgende Ausgabe zeigt eine Beispielantwort:

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

Eingabe für Onlinevorhersagen formatieren

Für die Onlinevorhersage gibt es zwei Methoden zum Senden von Anfragen:

• Vorhersageanfrage: Senden Sie eine Anfrage an die Methode predict, um eine Onlinevorhersage abzurufen.
• Rohvorhersageanfrage: Sendet eine Anfrage an die Methode rawPredict. Sie können dann eine beliebige HTTP-Nutzlast nutzen, statt ein JSON-Format zu verwenden.

Wenn Sie eine niedrige Latenz benötigen, sollten Sie Rohvorhersagen abrufen, da rawPredict die Serialisierungsschritte überspringt und die Anfrage direkt an den Vorhersagecontainer weiterleitet.

In diesem Abschnitt wird gezeigt, wie Sie die Instanzen der Vorhersageeingabe im JSON-Format formatieren und codieren. Dies ist erforderlich, wenn Sie die predict-Methode verwenden. Diese Informationen sind nicht erforderlich, wenn Sie die Methode rawPredict verwenden.

Wenn Sie das Vertex AI SDK für Python verwenden, um Vorhersageanfragen zu senden, geben Sie die Liste der Instanzen ohne das Feld instances an. Geben Sie beispielsweise [ ["the","quick","brown"], ... ] anstelle von { "instances": [ ["the","quick","brown"], ... ] } an.

Instanzen als JSON-Strings formatieren

Das Basisformat für Onlinevorhersagen ist eine Liste mit Dateninstanzen. Es kann sich dabei um eine einfache Werteliste oder Elemente eines JSON-Objekts handeln, je nachdem, wie Sie die Eingaben in der Trainingsanwendung konfiguriert haben. TensorFlow-Modelle können komplexere Eingaben akzeptieren.

Dieses Beispiel zeigt einen Eingabetensor und einen Instanzschlüssel für ein TensorFlow-Modell:

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

Die Zusammensetzung des JSON-Strings kann komplex sein, solange diese Regeln eingehalten werden:

• Die oberste Ebene der Instanzdaten muss ein JSON-Objekt sein, also ein Wörterbuch aus Schlüssel/Wert-Paaren.

• Einzelne Werte in einem Instanzobjekt können Strings, Zahlen oder Listen sein. JSON-Objekte können nicht eingebettet werden.

• Listen dürfen nur Elemente des gleichen Typs (einschließlich anderer Listen) enthalten. Strings und numerische Werte dürfen nicht kombiniert werden.

Sie übergeben Eingabeinstanzen für die Onlinevorhersage als Nachrichtentext für den predict-Aufruf. Weitere Informationen zu den Formatierungsanforderungen des Anfragetextes finden Sie in diesem Artikel.

Nehmen Sie jede Instanz als Element in ein JSON-Array auf und geben Sie das Array als instances-Feld eines JSON-Objekts an, wie im folgenden Beispiel:

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

Binärdaten für Vorhersageeingaben codieren

Binärdaten können nicht als UTF-8-codierte Strings formatiert werden, die von JSON unterstützt werden. Wenn Sie in Ihren Eingaben Binärdaten verwenden, müssen Sie für deren Darstellung die base64-Codierung verwenden. Sie benötigen die folgende spezielle Formatierung:

• Formatieren Sie den codierten String als JSON-Objekt mit einem einzelnen Schlüssel namens b64. In Python 3.5 gibt die Base64-Codierung eine Byte-Sequenz aus. Konvertieren Sie diese Sequenz in einen String, um die Serialisierung in JSON zu ermöglichen:

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

• Benennen Sie die Aliase für die binären Ein- und Ausgabetensoren in Ihrem TensorFlow-Modellcode so, dass sie auf _bytes enden.

Anfrage- und Antwortbeispiele

In diesem Abschnitt werden das Format des Anfrage- und Antworttexts für Onlinevorhersagen sowie Beispiele für TensorFlow und PyTorch beschrieben.

Anfragetextdetails

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

Antworttextdetails

Wenn der Aufruf erfolgreich ist, enthält der Antworttext einen Vorhersageeintrag pro Instanz im Anfragetext, wobei die Einträge in derselben Reihenfolge angegeben werden:

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

Wenn die Vorhersage für eine Instanz fehlschlägt, enthält der Antworttext keine Vorhersagen. Stattdessen wird ein einziger Fehlereintrag zurückgegeben:

{
  "error": string
}

Das Objekt predictions[] enthält die Liste der Vorhersagen, eine für jede Instanz in der Anfrage.

Bei einem Fehler enthält der String error eine Nachricht, die das Problem beschreibt. Der Fehler wird anstelle einer Vorhersageliste zurückgegeben, wenn beim Verarbeiten einer Instanz ein Fehler aufgetreten ist.

Obwohl es pro Instanz eine Vorhersage gibt, hängt das Format einer Vorhersage nicht direkt mit dem Format einer Instanz zusammen. Vorhersagen haben das in der Ausgabensammlung angegebene Format. Die Ausgabensammlung ist wiederum im Modell definiert. Die Sammlung von Vorhersagen wird in einer JSON-Liste zurückgegeben. Jedes Element der Liste kann ein Wert, eine Liste oder ein JSON-Objekt beliebiger Komplexität sein. Wenn das Modell mehr als einen Ausgabetensor hat, ist jede Vorhersage ein JSON-Objekt, das ein Schlüssel/Wert-Paar für jede Ausgabe enthält. Die Schlüssel identifizieren die Ausgabealiasse im Diagramm.

Antworttextbeispiele

Die folgenden Beispiele zeigen einige mögliche Antworten für TensorFlow:

• Ein Satz von Vorhersagen für drei Eingabeinstanzen, wobei jede Vorhersage ein ganzzahliger Wert ist:

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

• Ein komplexerer Satz von Vorhersagen, wobei jede zwei benannte Werte enthält, die den Ausgabetensoren label bzw. scores entsprechen. Der Wert von label ist die vorhergesagte Kategorie (car oder beach) und scores enthält eine Liste von Wahrscheinlichkeiten für diese Instanz über die möglichen Kategorien hinweg:

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

• Eine Antwort, wenn bei der Verarbeitung einer Eingabeinstanz ein Fehler auftritt:

  {"error": "Divide by zero"}