Mendapatkan prediksi online dari model terlatih kustom

Halaman ini menunjukkan cara mendapatkan prediksi online (real-time) dari model terlatih kustom Anda menggunakan konsol Google Cloud atau API Vertex AI.

Memformat input untuk prediksi online

Bagian ini menunjukkan cara memformat dan mengenkode instance input prediksi Anda sebagai JSON, yang diperlukan jika Anda menggunakan predict atau explain. Tindakan ini tidak diperlukan jika Anda menggunakan metode rawPredict. Untuk mengetahui informasi tentang metode yang harus dipilih, lihat Mengirim permintaan ke endpoint.

Jika Anda menggunakan Vertex AI SDK untuk Python untuk mengirim permintaan prediksi, tentukan daftar instance tanpa kolom instances. Misalnya, tentukan [ ["the","quick","brown"], ... ], bukan { "instances": [ ["the","quick","brown"], ... ] }.

Jika model Anda menggunakan container kustom, input Anda harus diformat sebagai JSON, dan ada kolom parameters tambahan yang dapat digunakan untuk container Anda. Pelajari input prediksi format dengan container kustom lebih lanjut.

Memformat instance sebagai string JSON

Format dasar untuk prediksi online adalah daftar instance data. Ini dapat berupa daftar nilai biasa atau anggota objek JSON, bergantung pada cara Anda mengonfigurasi input dalam aplikasi pelatihan Anda. Model TensorFlow dapat menerima input yang lebih kompleks, sementara sebagian besar model scikit-learn dan XGBoost mengharapkan daftar angka sebagai input.

Contoh ini menunjukkan tensor input dan kunci instance ke model TensorFlow:

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

Susunan string JSON bisa menjadi kompleks selama mengikuti aturan berikut:

  • Data instance tingkat teratas harus berupa objek JSON: kamus key-value pair.

  • Nilai individual dalam objek instance dapat berupa string, angka, atau daftar. Anda tidak dapat menyematkan objek JSON.

  • Daftar hanya boleh berisi item dari jenis yang sama (termasuk daftar lainnya). Anda tidak boleh mencampur nilai string dan numerik.

Anda meneruskan instance input untuk prediksi online sebagai isi pesan untuk panggilan projects.locations.endpoints.predict. Pelajari lebih lanjut persyaratan pemformatan isi permintaan.

Jadikan setiap instance sebagai item dalam array JSON, dan sediakan array sebagai kolom instances dari objek JSON. Contoh:

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

Mengenkode data biner untuk input prediksi

Data biner tidak dapat diformat sebagai string berenkode UTF-8 yang didukung JSON. Jika Anda memiliki data biner dalam input, Anda harus menggunakan encoding base64 untuk merepresentasikannya. Diperlukan format khusus berikut:

  • String yang dienkode harus diformat sebagai objek JSON dengan satu kunci bernama b64. Dalam Python 3, encoding base64 menghasilkan output urutan byte. Anda harus mengonversinya menjadi string agar JSON dapat diserialisasi:

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

  • Dalam kode model TensorFlow, Anda harus memberi nama alias untuk tensor input dan output biner agar diakhiri dengan '_bytes'.

Contoh permintaan dan respons

Bagian ini menjelaskan format isi permintaan prediksi dan isi respons, dengan contoh untuk TensorFlow, scikit-learn, dan XGBoost.

Detail isi permintaan

TensorFlow

Isi permintaan berisi data dengan struktur berikut (representasi JSON):

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

Objek instances[] wajib ada, dan harus berisi daftar instance untuk mendapatkan prediksi.

Struktur setiap elemen dari daftar instance ditentukan oleh definisi input model Anda. Instance dapat menyertakan input bernama (sebagai objek) atau hanya berisi nilai tak berlabel.

Tidak semua data menyertakan input bernama. Beberapa instance merupakan nilai JSON sederhana (boolean, angka, atau string). Namun, instance sering kali berupa daftar nilai sederhana, atau daftar bertingkat yang kompleks.

Berikut adalah beberapa contoh isi permintaan.

Data CSV dengan setiap baris yang dienkode sebagai nilai string:

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

Teks biasa:

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

Kalimat yang dienkode sebagai daftar kata (vektor string):

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

Nilai skalar floating point:

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

Vektor bilangan bulat:

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

Tensor (dalam hal ini, tensor dua dimensi):

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

Gambar, yang dapat direpresentasikan dengan berbagai cara. Dalam skema encoding ini, dua dimensi pertama mewakili baris dan kolom gambar, dan dimensi ketiga berisi daftar (vektor) nilai R, G, dan B untuk setiap piksel:

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

Encoding data

String JSON harus dienkode sebagai UTF-8. Untuk mengirim data biner, Anda harus mengenkode data dengan base64 dan menandainya sebagai biner. Untuk menandai string JSON sebagai biner, ganti string tersebut dengan objek JSON dengan atribut tunggal bernama b64: 

{"b64": "..."}

Contoh berikut menunjukkan dua instance tf.Examples serial, yang memerlukan encoding base64 (data palsu, hanya untuk tujuan ilustrasi):

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

Contoh berikut menunjukkan dua string byte gambar JPEG, yang memerlukan encoding base64 (data palsu, hanya untuk tujuan ilustrasi):

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

Tensor multi input

Beberapa model memiliki grafik TensorFlow dasar yang menerima tensor multi input. Dalam hal ini, gunakan nama dari pasangan nama/nilai JSON untuk mengidentifikasi tensor input.

Untuk grafik dengan alias tensor input "tag" (string) dan "image" (string berenkode base64): 

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

Untuk grafik dengan alias tensor input "tag" (string) dan "image" (array 3 dimensi int 8-bit):

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

Isi permintaan berisi data dengan struktur berikut (representasi JSON):

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

Objek instances[] wajib ada, dan harus berisi daftar instance untuk mendapatkan prediksi. Pada contoh berikut, setiap instance input adalah daftar float:

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

Dimensi instance input harus sesuai dengan harapan model Anda. Misalnya, jika model Anda memerlukan tiga fitur, panjang setiap instance input harus 3.

XGBoost

Isi permintaan berisi data dengan struktur berikut (representasi JSON):

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

Objek instances[] wajib ada, dan harus berisi daftar instance untuk mendapatkan prediksi. Pada contoh berikut, setiap instance input adalah daftar float:

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

Dimensi instance input harus sesuai dengan harapan model Anda. Misalnya, jika model Anda memerlukan tiga fitur, panjang setiap instance input harus 3.

Vertex AI tidak mendukung representasi renggang instance input untuk XGBoost.

Layanan prediksi online menafsirkan angka nol dan NaN secara berbeda. Jika nilai fitur adalah nol, gunakan 0.0 dalam input yang sesuai. Jika nilai fitur tidak ada, gunakan "NaN" dalam input yang sesuai.

Contoh berikut merepresentasikan permintaan prediksi dengan instance input tunggal, dengan nilai fitur pertama adalah 0,0, nilai fitur kedua adalah 1,1, dan nilai fitur ketiga tidak ada:

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

PyTorch

Jika model Anda menggunakan container bawaan PyTorch, pengendali default TorchServe mengharapkan setiap instance digabungkan dalam kolom data. Contoh:

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

Detail isi respons

Jika panggilan berhasil, isi respons berisi satu entri prediksi per instance di dalam isi permintaan, yang diberikan dalam urutan yang sama:

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

Jika prediksi gagal untuk instance apa pun, isi respons tidak akan berisi prediksi. Sebagai gantinya, respons akan berisi satu entri error:

{
  "error": string
}

Objek predictions[] berisi daftar prediksi, satu untuk setiap instance dalam permintaan.

Jika terjadi error, string error berisi pesan yang menjelaskan masalahnya. Jika terjadi error saat memproses instance, maka yang akan ditampilkan adalah error, bukan daftar prediksi.

Meskipun ada satu prediksi per instance, format prediksi tidak terkait langsung dengan format instance. Prediksi mengambil format apa pun yang ditentukan dalam koleksi output yang ditentukan dalam model. Kumpulan prediksi akan ditampilkan dalam daftar JSON. Setiap anggota daftar dapat berupa nilai sederhana, daftar, atau objek JSON dengan kompleksitas apa pun. Jika model Anda memiliki lebih dari satu tensor output, setiap prediksi akan menjadi objek JSON yang berisi pasangan nama/nilai untuk setiap output. Nama-nama tersebut mengidentifikasi alias output di dalam grafik.

Contoh isi respons

TensorFlow

Contoh berikut menampilkan beberapa kemungkinan respons:

  • Kumpulan prediksi sederhana untuk tiga instance input, dengan setiap prediksi merupakan nilai bilangan bulat:

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

  • Rangkaian prediksi yang lebih kompleks, masing-masing berisi dua nilai bernama yang sesuai dengan tensor output, yang masing-masing bernama label dan scores. Nilai label adalah kategori yang diprediksi ("mobil" atau "pantai") dan scores berisi daftar probabilitas untuk instance tersebut di seluruh kategori yang memungkinkan.

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

  • Respons jika terjadi error saat memproses instance input:

    {"error": "Divide by zero"}

scikit-learn

Contoh berikut menampilkan beberapa kemungkinan respons:

  • Kumpulan prediksi sederhana untuk tiga instance input, dengan setiap prediksi merupakan nilai bilangan bulat:

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

  • Respons jika terjadi error saat memproses instance input:

    {"error": "Divide by zero"}

XGBoost

Contoh berikut menampilkan beberapa kemungkinan respons:

  • Kumpulan prediksi sederhana untuk tiga instance input, dengan setiap prediksi merupakan nilai bilangan bulat:

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

  • Respons jika terjadi error saat memproses instance input:

    {"error": "Divide by zero"}

Mengirim permintaan ke endpoint

Ada tiga cara untuk mengirim permintaan:

Mengirim permintaan prediksi online

gcloud

Contoh berikut menggunakan perintah gcloud ai endpoints predict:

  1. Tulis objek JSON berikut untuk diajukan di lingkungan lokal Anda. Nama file tidak penting, tetapi untuk contoh ini, beri nama file request.json.

    {
 "instances": INSTANCES
}

    Ganti kode berikut:

    • INSTANCES: Array JSON dari instance yang ingin Anda dapatkan prediksinya. Format setiap instance bergantung pada input mana yang diharapkan oleh model ML terlatih Anda. Untuk informasi selengkapnya, lihat Memformat input untuk prediksi online.

  2. Jalankan perintah berikut:

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

    Ganti kode berikut:

    • ENDPOINT_ID: ID untuk endpoint.
    • LOCATION_ID: Region tempat Anda menggunakan Vertex AI.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION_ID: Region tempat Anda menggunakan Vertex AI.
  • PROJECT_ID: project ID Anda
  • ENDPOINT_ID: ID untuk endpoint.
  • INSTANCES: Array JSON dari instance yang ingin Anda dapatkan prediksinya. Format setiap instance bergantung pada input mana yang diharapkan oleh model ML terlatih Anda. Untuk informasi selengkapnya, lihat Memformat input untuk prediksi online.

Metode HTTP dan URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict

Isi JSON permintaan: 

{
  "instances": INSTANCES
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
Jika berhasil, Anda akan menerima respons JSON yang mirip dengan yang berikut ini. Dalam respons tersebut, Anda akan menerima penggantian berikut:
  • PREDICTIONS: Array prediksi JSON, satu untuk setiap instance yang Anda sertakan dalam isi permintaan.
  • DEPLOYED_MODEL_ID: ID DeployedModel yang menayangkan prediksi. 
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Python API. 

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

Mengirim permintaan prediksi mentah online

gcloud

Contoh berikut menggunakan perintah gcloud ai endpoints raw-predict:

  • Untuk meminta prediksi dengan objek JSON di REQUEST yang ditentukan pada command line:

     gcloud ai endpoints raw-predict ENDPOINT_ID 
    
 --region=LOCATION 
    
 --request REQUEST

  • Untuk meminta prediksi dengan image yang disimpan dalam file image.jpeg dan header Content-Type yang sesuai:

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

    Ganti kode berikut:

    • ENDPOINT_ID: ID untuk endpoint.
    • LOCATION_ID: Region tempat Anda menggunakan Vertex AI.
    • REQUEST: Isi permintaan yang ingin Anda dapatkan prediksinya. Format permintaan bergantung pada ekspektasi container kustom Anda, yang mungkin tidak selalu berupa objek JSON.

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Python API. 

# -*- coding: utf-8 -*-
# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Generated code. DO NOT EDIT!
#
# Snippet for RawPredict
# NOTE: This snippet has been automatically generated for illustrative purposes only.
# It may require modifications to work in your environment.

# To install the latest published package dependency, execute the following:
#   python3 -m pip install google-cloud-aiplatform

from google.cloud import aiplatform_v1

def sample_raw_predict():
    # Create a client
    client = aiplatform_v1.PredictionServiceClient()

    # Initialize request argument(s)
    request = aiplatform_v1.RawPredictRequest(
        endpoint="endpoint_value",
    )

    # Make the request
    response = client.raw_predict(request=request)

    # Handle the response
    print(response)

Responsnya mencakup header HTTP berikut:

  • X-Vertex-AI-Endpoint-Id: ID dari Endpoint yang menayangkan prediksi ini.

  • X-Vertex-AI-Deployed-Model-Id: ID DeployedModel Endpoint yang menayangkan prediksi ini.

Mengirim permintaan penjelasan online

gcloud

Contoh berikut menggunakan perintah gcloud ai endpoints explain:

  1. Tulis objek JSON berikut untuk diajukan di lingkungan lokal Anda. Nama file tidak penting, tetapi untuk contoh ini, beri nama file request.json.

    {
 "instances": INSTANCES
}

    Ganti kode berikut:

    • INSTANCES: Array JSON dari instance yang ingin Anda dapatkan prediksinya. Format setiap instance bergantung pada input mana yang diharapkan oleh model ML terlatih Anda. Untuk informasi selengkapnya, lihat Memformat input untuk prediksi online.

  2. Jalankan perintah berikut:

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

    Ganti kode berikut:

    • ENDPOINT_ID: ID untuk endpoint.
    • LOCATION_ID: Region tempat Anda menggunakan Vertex AI.

    Secara opsional, jika Anda ingin mengirim permintaan penjelasan ke DeployedModel tertentu di Endpoint, Anda dapat menentukan flag --deployed-model-id:

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

    Selain placeholder yang dijelaskan sebelumnya, ganti placeholder berikut:

    • DEPLOYED_MODEL_ID Opsional: ID model yang di-deploy yang ingin Anda lihat penjelasannya. ID disertakan dalam respons metode predict. Jika Anda perlu meminta penjelasan untuk model tertentu dan Anda memiliki lebih dari satu model yang di-deploy ke endpoint yang sama, Anda dapat menggunakan ID ini untuk memastikan penjelasan ditampilkan untuk model tertentu.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION_ID: Region tempat Anda menggunakan Vertex AI.
  • PROJECT_ID: project ID Anda
  • ENDPOINT_ID: ID untuk endpoint.
  • INSTANCES: Array JSON dari instance yang ingin Anda dapatkan prediksinya. Format setiap instance bergantung pada input mana yang diharapkan oleh model ML terlatih Anda. Untuk informasi selengkapnya, lihat Memformat input untuk prediksi online.

Metode HTTP dan URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain

Isi JSON permintaan: 

{
  "instances": INSTANCES
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
Jika berhasil, Anda akan menerima respons JSON yang mirip dengan yang berikut ini. Dalam respons tersebut, Anda akan menerima penggantian berikut:
  • PREDICTIONS: Array prediksi JSON, satu untuk setiap instance yang Anda sertakan dalam isi permintaan.
  • EXPLANATIONS: Array JSON yang berisi penjelasan, satu untuk setiap prediksi.
  • DEPLOYED_MODEL_ID: ID DeployedModel yang menayangkan prediksi. 
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Python API. 

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)

Langkah selanjutnya