Method: projects.predict

Performs online prediction on the data in the request.

AI Platform Prediction implementiert zusätzlich zu einer HTTP-POST-Methode ein benutzerdefiniertes predict. Die Methode predict liefert eine Vorhersage für die Daten in der Anfrage.

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/your-project-id/models/your-model-name/versions/your-version-name:predict

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

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name:predict

Auf dieser Seite werden das Format des Anfrage- und Antworttexts für Vorhersagen beschrieben. Ein Codebeispiel zum Senden einer Vorhersageanfrage finden Sie in der Anleitung zum Anfordern von Onlinevorhersagen.

Anfragetextdetails

TensorFlow

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

{
  "instances": [
    <value>|<simple/nested list>|<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 (wie Objekte) 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", "the lazy dog"]}

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

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

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. Zum Kennzeichnen eines JSON-Strings als binär ersetzen Sie ihn durch ein JSON-Objekt mit einem einzelnen Attribut namens b64:

{"b64": "..."} 

Das folgende Beispiel zeigt zwei serialisierte tf.Examples-Instanzen, die eine base64-Codierung erfordern (fiktive Daten, nur zur Veranschaulichung):

{"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 Prediction 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>|<object>,
    ...
  ],
  "<other-key>": <value>|<simple/nested list>|<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 Prediction 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 (wie Objekte) 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", "the lazy dog"]}

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

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

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

Antworttextdetails

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) enthält 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"}
    

API-Spezifikation

Im folgenden Abschnitt wird die Spezifikation der predict-Methode beschrieben, wie sie im Discovery-Dokument "AI Platform Training and Prediction API" definiert ist. Ausführliche Informationen zur Methode finden Sie in den vorherigen Abschnitten dieses Dokuments.

HTTP request

POST https://{endpoint}/v1/{name=projects/**}:predict

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version.

Authorization: requires the predict permission on the specified resource.

Authorization requires one or more of the following IAM permissions on the specified resource name:

  • ml.models.predict
  • ml.versions.predict

Request body

The request body contains data with the following structure:

JSON representation
{
  "httpBody": {
    object (HttpBody)
  }
}
Fields
httpBody

object (HttpBody)

Required. The prediction request body. Refer to the request body details section for more information on how to structure your request.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.