Predict-Anfragedetails

Die Methode predict liefert eine Vorhersage für die Daten in der Anfrage.

Auf dieser Seite werden das Format des Anfrage- und Antworttexts für Vorhersagen sowie das URL-Format der HTTP-Anfrage beschrieben. Ein Codebeispiel zum Senden einer Vorhersageanfrage finden Sie im Leitfaden zum Abrufen von Onlinevorhersagen mit TensorFlow und in der Anleitung zum Abrufen von Onlinevorhersagen mit scikit-learn und XGBoost.

Anfragetext

TensorFlow

Der Anfragetext enthält Daten mit folgender Struktur (JSON-Darstellung):

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

Das Objekt instances[] ist erforderlich und muss die Liste der Instanzen enthalten, für die Vorhersagen abgerufen werden sollen.

Die Struktur der einzelnen Elemente in der Liste der Instanzen wird durch die Eingabedefinition des Modells bestimmt. Instanzen können benannte Eingaben oder nur Werte ohne Label enthalten.

Nicht alle Daten enthalten benannte Eingaben. Einige Instanzen sind einfache JSON-Werte (boolesch, Zahl oder String). Allerdings sind Instanzen häufig Listen mit einfachen Werten oder komplexe verschachtelte Listen.

Im Folgenden sehen Sie einige Beispiele für Anfragetexte.

CSV-Daten, wobei jede Zeile als Stringwert codiert ist:

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

Nur Text:

{"instances": ["the quick brown fox", "la bruja le dio"]}

Sätze, die als Wortlisten codiert sind (Vektoren von Strings):

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

Skalare Gleitkommawerte:

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

Vektoren von Ganzzahlen:

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

Tensoren (in diesem Fall zweidimensionale Tensoren):

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

Bilder, die unterschiedlich dargestellt werden können. In diesem Codierungsschema stellen die ersten zwei Dimensionen die Zeilen und Spalten des Bildes dar und die dritte Dimension enthält Listen (Vektoren) der R-, G- und B-Werte für jedes Pixel:

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

Datencodierung

JSON-Strings müssen als UTF-8 codiert sein. Um Binärdaten zu senden, müssen Sie die Daten base64-codieren und als binär kennzeichnen. Sie kennzeichnen einen JSON-String als binär, indem Sie ihn durch ein JSON-Objekt mit einem einzelnen Attribut namens b64 ersetzen:

{"b64": "..."} 

Das folgende Beispiel zeigt zwei serialisierte Instanzen von tf.Examples, die eine Base64-Codierung erfordern. Die Beispiele beruhen auf fiktiven Daten:

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

Das folgende Beispiel zeigt zwei Bytestrings für ein JPEG-Bild, die eine base64-Codierung erfordern (fiktive Daten, nur zur Veranschaulichung):

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

Mehrere Eingabetensoren

Einigen Modellen liegt eine TensorFlow-Grafik zugrunde, die mehrere Eingabetensoren annimmt. Verwenden Sie in diesem Fall die Namen von JSON-Name/Wert-Paaren, um die Eingabetensoren zu identifizieren.

Für eine Grafik mit den Eingabetensor-Aliassen "tag" (String) und "image" (base64-codierter String):

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

Für eine Grafik mit den Eingabetensor-Aliassen "tag" (String) und "image" (dreidimensionales Array mit 8-Bit-Ganzzahlen):

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

Der Anfragetext enthält Daten mit folgender Struktur (JSON-Darstellung):

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

Das Objekt instances[] ist erforderlich und muss die Liste der Instanzen enthalten, für die Vorhersagen abgerufen werden sollen. Im folgenden Beispiel ist jede Eingabeinstanz eine Liste von Gleitkommazahlen:

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

Die Dimension der Eingabeinstanzen muss mit dem übereinstimmen, was Ihr Modell erwartet. Wenn Ihr Modell beispielsweise drei Funktionen benötigt, muss die Länge jeder Eingabeinstanz 3 sein.

XGBoost

Der Anfragetext enthält Daten mit folgender Struktur (JSON-Darstellung):

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

Das Objekt instances[] ist erforderlich und muss die Liste der Instanzen enthalten, für die Vorhersagen abgerufen werden sollen. Im folgenden Beispiel ist jede Eingabeinstanz eine Liste von Gleitkommazahlen:

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

Die Dimension der Eingabeinstanzen muss mit dem übereinstimmen, was Ihr Modell erwartet. Wenn Ihr Modell beispielsweise drei Funktionen benötigt, muss die Länge jeder Eingabeinstanz 3 sein.

AI Platform unterstützt keine dünnbesetzte Darstellung von Eingabeinstanzen für XGBoost.

Der Onlinevorhersagedienst interpretiert Nullen und NaN unterschiedlich. Wenn der Wert einer Funktion null ist, verwenden Sie in der entsprechenden Eingabe 0.0. Wenn der Wert einer Funktion fehlt, verwenden Sie in der entsprechenden Eingabe NaN.

Das folgende Beispiel stellt eine Vorhersageanfrage mit einer einzelnen Eingabeinstanz dar, wobei der Wert der ersten Funktion 0.0 beträgt, der Wert der zweiten Funktion 1.1 und der Wert der dritten Funktion fehlt.

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

Benutzerdefinierte Vorhersageroutine

Der Anfragetext enthält Daten mit folgender Struktur (JSON-Darstellung):

{
  "instances": [
    <value>|<simple/nested list&gt|<object>,
    ...
  ],
  "<other-key>": <value>|<simple/nested list&gt|<object>,
  ...
}

Das Objekt instances[] ist erforderlich und muss die Liste der Instanzen enthalten, für die Vorhersagen abgerufen werden sollen.

Sie können optional andere gültige JSON-Schlüsselwertpaare angeben. AI Platform parst den JSON-Code und stellt diese Felder für die Methode predict Ihrer Predictor-Klasse als Einträge im Wörterbuch **kwargs bereit.

Liste der Instanzen strukturieren

Die Struktur der einzelnen Elemente in der Liste der Instanzen wird durch die Methode predict Ihrer Predictor-Klasse bestimmt. Instanzen können benannte Eingaben oder nur Werte ohne Label enthalten.

Nicht alle Daten enthalten benannte Eingaben. Einige Instanzen sind einfache JSON-Werte (boolesch, Zahl oder String). Allerdings sind Instanzen häufig Listen mit einfachen Werten oder komplexe verschachtelte Listen.

Im Folgenden sehen Sie einige Beispiele für Anfragetexte.

CSV-Daten, wobei jede Zeile als Stringwert codiert ist:

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

Nur Text:

{"instances": ["the quick brown fox", "la bruja le dio"]}

Sätze, die als Wortlisten codiert sind (Vektoren von Strings):

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

Skalare Gleitkommawerte:

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

Vektoren von Ganzzahlen:

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

Tensoren (in diesem Fall zweidimensionale Tensoren):

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

Bilder, die unterschiedlich dargestellt werden können. In diesem Codierungsschema stellen die ersten zwei Dimensionen die Zeilen und Spalten des Bildes dar und die dritte Dimension enthält Listen (Vektoren) der R-, G- und B-Werte für jedes Pixel:

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

Mehrere Eingabetensoren

Einigen Modellen liegt eine TensorFlow-Grafik zugrunde, die mehrere Eingabetensoren annimmt. Verwenden Sie in diesem Fall die Namen von JSON-Name/Wert-Paaren, um die Eingabetensoren zu identifizieren.

Für eine Grafik mit den Eingabetensor-Aliassen "tag" (String) und "image" (dreidimensionales Array mit 8-Bit-Ganzzahlen):

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

Antworttext

Antworten sind Anfragen sehr ähnlich.

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

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. Für eine benutzerdefinierte Vorhersageroutine (Beta) enthalten predictions den Rückgabewert der Methode predict Ihrer Predictor-Klasse als JSON-Code serialisiert.

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 einfacher 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 Name/Wert-Paar für jede Ausgabe enthält. Die Namen identifizieren die Ausgabealiasse in der Grafik.

Antworttextbeispiele

TensorFlow

Die folgenden Beispiele zeigen einige mögliche Antworten:

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

    {"predictions": [5, 4, 3]}
    
  • 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]
        }
      ]
    }
    
  • Eine Antwort, wenn bei der Verarbeitung einer Eingabeinstanz ein Fehler auftritt:

    {"error": "Divide by zero"}
    

scikit-learn

Die folgenden Beispiele zeigen einige mögliche Antworten:

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

    {"predictions": [5, 4, 3]}
    
  • Eine Antwort, wenn bei der Verarbeitung einer Eingabeinstanz ein Fehler auftritt:

    {"error": "Divide by zero"}
    

XGBoost

Die folgenden Beispiele zeigen einige mögliche Antworten:

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

    {"predictions": [5, 4, 3]}
    
  • Eine Antwort, wenn bei der Verarbeitung einer Eingabeinstanz ein Fehler auftritt:

    {"error": "Divide by zero"}
    

Benutzerdefinierte Vorhersageroutine

Die folgenden Beispiele zeigen einige mögliche Antworten:

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

    {"predictions": [5, 4, 3]}
    
  • 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]
        }
      ]
    }
    
  • Eine Antwort, wenn bei der Verarbeitung einer Eingabeinstanz ein Fehler auftritt:

    {"error": "Divide by zero"}
    

HTTP-URL-Format

Ein Codebeispiel zum Senden einer Vorhersageanfrage finden Sie im Leitfaden zum Abrufen von Onlinevorhersagen mit TensorFlow und in der Anleitung zum Abrufen von Onlinevorhersagen mit scikit-learn und XGBoost. Nachstehend wird das von AI Platform implementierte HTTP-URL-Format beschrieben, falls Sie eine detaillierte Beschreibung benötigen.

AI Platform implementiert zusätzlich zu einer HTTP-POST-Methode ein benutzerdefiniertes predict. Die URL wird in der Syntax der Google API HTTP-Annotation beschrieben:

POST https://ml.googleapis.com/v1/{name=projects/**}:predict

Der Parameter name ist erforderlich. Er muss den Namen des Modells und optional eine Version enthalten. Wenn Sie ein Modell ohne eine Version angeben, wird die Standardversion für dieses Modell verwendet.

Beispiel, in dem ein Modell und eine Version angegeben werden:

POST https://ml.googleapis.com/v1/projects/my-project/models/my-model/versions/my-version:predict

Beispiel, in dem nur ein Modell angegeben wird. Für dieses Modell wird die Standardversion verwendet:

POST https://ml.googleapis.com/v1/projects/my-project/models/my-model:predict

Das Segment :predict am Ende des Pfads zeigt an, dass AI Platform ein benutzerdefiniertes Verb verwendet, wie in der HTTP-Dokumentation von Google API definiert. In diesem Fall lautet das benutzerdefinierte Verb predict.

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...