Onlinevorhersagen aus benutzerdefinierten Modellen abrufen

Vertex AI-Onlinevorhersage ist ein Dienst, der dahingehend optimiert ist, Ihre Daten mit so wenig Latenz wie möglich durch gehostete Modelle auszuführen. Sie senden kleine Mengen von Daten an den Dienst und dieser gibt Ihre Vorhersagen in der Antwort zurück.

Vorbereitung

Sie müssen zuerst folgende Schritte ausführen, um Vorhersagen anzufordern:

Modellbereitstellung konfigurieren

Bei der Modellbereitstellung müssen Sie für die Ausführung der Onlinevorhersage für folgende Bereiche Festlegungen treffen:

Erstellte Ressource Einstellung bei der Ressourcenerstellung
Endpunkt Speicherort zur Ausführung von Vorhersagen
Modell Zu verwendender Container (ModelContainerSpec)
DeployedModel Maschinen für die Onlinevorhersage

Nach der ersten Erstellung des Modells oder Endpunkts können Sie die oben aufgeführten Einstellungen nicht mehr ändern. Sie können sie auch nicht in der Anfrage für eine Onlinevorhersage überschreiben. Wenn Sie diese Einstellungen ändern möchten, müssen Sie das Modell neu bereitstellen.

Eingabe für Onlinevorhersagen formatieren

Wenn Sie einen unserer vordefinierten Container für die Bereitstellung von Vorhersagen mit TensorFlow, scikit-learn oder XGBoost verwenden, müssen Ihre Instanzen der Vorhersageeingabe im JSON-Format formatiert sein.

Wenn Ihr Modell einen benutzerdefinierten Container nutzt, muss Ihre Eingabe im JSON-Format angegeben werden. Außerdem gibt es ein zusätzliches Feld parameters, das für Ihren Container verwendet werden kann. Weitere Informationen zum Formatieren von Vorhersageeingaben mit benutzerdefinierten Containern finden Sie in diesem Artikel.

In diesem Abschnitt wird gezeigt, wie Sie die Instanzen der Vorhersageeingabe im JSON-Format angeben und Binärdaten mit base64-Codierung verarbeiten.

Instanzen als JSON-Strings formatieren

Das Basisformat für Onlinevorhersagen ist eine Liste mit Dateninstanzen. Dies können einfache Wertelisten oder Mitglieder eines JSON-Objekts sein, je nachdem, wie Sie die Eingaben in der Trainingsanwendung konfiguriert haben. TensorFlow-Modelle akzeptieren auch komplexere Eingaben. Die meisten scikit-learn- und XGBoost-Modelle erwarten dagegen eine Liste von Zahlen als Eingabe.

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 – 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 die Eingabeinstanzen für die Onlinevorhersage als Nachrichtentext für den projects.locations.endpoints.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. 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 von JSON unterstützte UTF-8-codierte Strings formatiert werden. Wenn Sie Binärdaten in Ihren Eingaben verwenden, müssen Sie für deren Darstellung die base64-Codierung verwenden. Folgende besondere Formatierungen sind erforderlich:

  • Ihre codierte Zeichenfolge muss als JSON-Objekt mit einem einzelnen Schlüssel namens b64 formatiert sein. In Python 3.5 gibt die Base64-Codierung eine Byte-Sequenz aus. Diese müssen Sie in einen String konvertieren, um die Serialisierung in JSON zu ermöglichen:

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
    
  • Die Namen der Aliase für die binären Ein- und Ausgabetensoren in Ihrem TensorFlow-Modellcode müssen mit "_bytes" enden.

Anfrage- und Antwortbeispiele

In diesem Abschnitt werden das Format des Anfrage- und Antworttexts für Vorhersagen sowie Beispiele für TensorFlow, scikit-learn und XGBoost beschrieben.

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.

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

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

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],
       "deployedModelId": 123456789012345678
    }
    
  • 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],
       "deployedModelId": 123456789012345678
    }
    
  • Eine Antwort, wenn bei der Verarbeitung einer Eingabeinstanz ein Fehler auftritt:

    {"error": "Divide by zero"}
    

Anfrage für eine Onlinevorhersage senden

Wenn Sie eine Onlinevorhersage anfordern möchten, senden Sie die Instanzen Ihrer Eingabedaten als JSON-String in einer Vorhersageanfrage. Informationen zum Formatieren des Anfrage- und Antworttextes finden Sie unter Details zur Vorhersageanfrage

Jede Vorhersageanfrage darf maximal 1,5 MB groß sein.

gcloud

Im folgenden Beispiel wird der Befehl gcloud ai endpoints predict verwendet:

  1. Schreiben Sie das folgende JSON-Objekt, um es in Ihrer lokalen Umgebung zu speichern: Der Dateiname spielt keine Rolle. Für dieses Beispiel verwenden Sie request.json.

    {
     "instances": INSTANCES
    }
    

    Dabei gilt:

    • INSTANCES ist ein JSON-Array von Instanzen, für die Sie Vorhersagen abrufen möchten. Das Format der einzelnen Instanzen hängt von den Eingaben ab, die Ihr jeweiliges trainiertes ML-Modell erwartet. Weitere Informationen finden Sie im Abschnitt Eingabe für Onlinevorhersagen formatieren in diesem Dokument.

  2. Führen Sie dazu diesen Befehl aus:

    gcloud ai endpoints predict ENDPOINT_ID \
      --region=LOCATION \
      --json-request=request.json
    

    Dabei gilt:

    • ENDPOINT_ID: Die ID des Endpunkts.
    • LOCATION: Die Region, in der Sie Vertex AI verwenden.

REST UND BEFEHLSZEILE

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • LOCATION: Die Region, in der Sie Vertex AI verwenden.
  • PROJECT: Ihre Projekt-ID oder Projektnummer
  • ENDPOINT_ID: Die ID des Endpunkts.
  • INSTANCES ist ein JSON-Array von Instanzen, für die Sie Vorhersagen abrufen möchten. Das Format der einzelnen Instanzen hängt von den Eingaben ab, die Ihr jeweiliges trainiertes ML-Modell erwartet. Weitere Informationen finden Sie im Abschnitt Eingabe für Onlinevorhersagen formatieren in diesem Dokument.

HTTP-Methode und URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict

JSON-Text der Anfrage:

{
  "instances": INSTANCES
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth application-default 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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
Bei erfolgreicher Ausführung erhalten Sie eine JSON-Antwort ähnlich der folgenden. Die Antwort enthält folgende Parameter:
  • PREDICTIONS: Ein JSON-Array von Vorhersagen, jeweils eine für jede Instanz, die Sie im Anfragetext angegeben haben.
  • DEPLOYED_MODEL_ID: Die ID des DeployedModel, das diese Vorhersagen bereitgestellt hat.
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java


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

/**
 * 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

In diesem Beispiel wird das Vertex SDK for Python verwendet. Bevor Sie das folgende Codebeispiel ausführen, müssen Sie die Authentifizierung einrichten.

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

Onlineanfrage für Rohvorhersage senden

Alternativ können Sie eine Anfrage für eine Rohvorhersage senden, wodurch Sie eine beliebige HTTP-Nutzlast verwenden können, anstatt den strengen Richtlinien aus den vorherigen Abschnitten dieses Leitfadens zu folgen.

Sie möchten vielleicht Rohvorhersagen erhalten, wenn Sie einen benutzerdefinierten Container verwenden, der Anfragen empfängt und Antworten sendet, die von den Richtlinien abweichen.

gcloud

Im folgenden Beispiel wir der Befehl gcloud ai endpoints raw-predict verwendet:

  • So fordern Sie Vorhersagen mit dem JSON-Objekt in REQUESTüber die Befehlszeile an:

    gcloud ai endpoints raw-predict ENDPOINT_ID \
      --region=LOCATION \
      --request REQUEST
    
  • So fordern Sie Vorhersagen mit einem in der Datei image.jpeg gespeicherten Bild und dem entsprechenden Content-Type-Header an:

    gcloud ai endpoints raw-predict ENDPOINT_ID \
      --region=LOCATION \
      --http-headers=Content-Type=image/jpeg \
      --request @image.jpeg
    

Dabei gilt:

  • ENDPOINT_ID: Die ID des Endpunkts.
  • LOCATION: Die Region, in der Sie Vertex AI verwenden.
  • REQUEST: Der Inhalt der Anfrage, für die Sie Vorhersagen erhalten möchten. Das Format der Anfrage hängt davon ab, was Ihr benutzerdefinierter Container erwartet. Es muss nicht unbedingt ein JSON-Objekt sein.

Die Antwort umfasst die folgenden HTTP-Header:

  • X-Vertex-AI-Endpoint-Id: ID des Endpoint, der diese Vorhersage bereitgestellt hat.

  • X-Vertex-AI-Deployed-Model-Id: ID des DeployedModel des Endpunkts, das diese Vorhersage bereitgestellt hat.

Anfrage für Onlineerläuterung senden

Wenn Sie Ihr Model für Explainable AI konfiguriert haben, können Sie Onlineerläuterungen abrufen. Anfragen für Onlineerläuterungen haben das gleiche Format wie Anfragen für Onlinevorhersagen und geben ähnliche Antworten zurück. Der einzige Unterschied besteht darin, dass Antworten für Onlineerläuterungen Feature-Attributionen sowie Vorhersagen enthalten.

Die folgenden Beispiele sind nahezu identisch mit den Beispielen aus dem vorherigen Abschnitt. Sie verwenden nur geringfügig andere Befehle:

gcloud

Im folgenden Beispiel wird der Befehl gcloud ai endpoints explain verwendet:

  1. Schreiben Sie das folgende JSON-Objekt, um es in Ihrer lokalen Umgebung zu speichern: Der Dateiname spielt keine Rolle. Für dieses Beispiel verwenden Sie request.json.

    {
     "instances": INSTANCES
    }
    

    Dabei gilt:

    • INSTANCES ist ein JSON-Array von Instanzen, für die Sie Vorhersagen abrufen möchten. Das Format der einzelnen Instanzen hängt von den Eingaben ab, die Ihr jeweiliges trainiertes ML-Modell erwartet. Weitere Informationen finden Sie im Abschnitt Eingabe für Onlinevorhersagen formatieren in diesem Dokument.

  2. Führen Sie dazu diesen Befehl aus:

    gcloud ai endpoints explain ENDPOINT_ID \
      --region=LOCATION \
      --json-request=request.json
    

    Dabei gilt:

    • ENDPOINT_ID: Die ID des Endpunkts.
    • LOCATION: Die Region, in der Sie Vertex AI verwenden.

    Wenn Sie eine Anfrage für Erläuterungen an ein bestimmtes DeployedModel im Endpoint senden möchten, geben Sie das Flag --deployed-model-id an:

    gcloud ai endpoints explain ENDPOINT_ID \
      --region=LOCATION \
      --deployed-model-id=DEPLOYED_MODEL_ID \
      --json-request=request.json
    

    Ersetzen Sie zusätzlich zu den zuvor beschriebenen Platzhaltern Folgendes:

    • DEPLOYED_MODEL_ID (optional) ist die ID des bereitgestellten Modells, für das Sie Erläuterungen abrufen möchten. Die ID ist in der Antwort der Methode predict enthalten. Wenn Sie Erläuterungen zu einem bestimmten Modell anfordern möchten und Sie mehr als ein Modell an einem bestimmten Endpunkt bereitgestellt haben, können Sie mit dieser ID festlegen, dass die Erläuterungen für das Modell zurückgegeben werden, das die vorherige Vorhersage bereitgestellt hat.

REST UND BEFEHLSZEILE

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • LOCATION: Die Region, in der Sie Vertex AI verwenden.
  • PROJECT: Ihre Projekt-ID oder Projektnummer
  • ENDPOINT_ID: Die ID des Endpunkts.
  • INSTANCES ist ein JSON-Array von Instanzen, für die Sie Vorhersagen abrufen möchten. Das Format der einzelnen Instanzen hängt von den Eingaben ab, die Ihr jeweiliges trainiertes ML-Modell erwartet. Weitere Informationen finden Sie im Abschnitt Eingabe für Onlinevorhersagen formatieren in diesem Dokument.

HTTP-Methode und URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain

JSON-Text der Anfrage:

{
  "instances": INSTANCES
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth application-default 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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
Bei erfolgreicher Ausführung erhalten Sie eine JSON-Antwort ähnlich der folgenden. Die Antwort enthält folgende Parameter:
  • PREDICTIONS: Ein JSON-Array von Vorhersagen, jeweils eine für jede Instanz, die Sie im Anfragetext angegeben haben.
  • EXPLANATIONS: Ein JSON-Array von Erläuterungen, eine für jede Vorhersage.
  • DEPLOYED_MODEL_ID: Die ID des DeployedModel, das diese Vorhersagen bereitgestellt hat.
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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)

Nächste Schritte