Ottieni previsioni online da un modello addestrato personalizzato

Questa pagina mostra come ottenere previsioni online (in tempo reale) dai tuoi addestrati utilizzando la console Google Cloud o l'API Vertex AI.

Formatta l'input per la previsione online

Questa sezione mostra come formattare e codificare le istanze di input di previsione come JSON, che è obbligatorio se utilizzi Metodo predict o explain. Non è obbligatorio se sei rawPredict . Per informazioni sul metodo da scegliere, consulta Invia richiesta a endpoint.

Se utilizzi l'SDK Vertex AI per Python per inviare richieste di previsione, specifica l'elenco delle istanze senza il campo instances. Ad esempio, specifica [ ["the","quick","brown"], ... ] anziché { "instances": [ ["the","quick","brown"], ... ] }.

Se il modello utilizza un container personalizzato, l'input deve essere formattato come JSON e c'è un campo parameters aggiuntivo che possono essere utilizzate per il container. Scopri di più sull'input di previsione del formato grazie ai container personalizzati.

Formatta le istanze come stringhe JSON

Il formato di base per la previsione online è un elenco di istanze di dati. Questi possono essere semplici elenchi di valori o membri di un oggetto JSON, a seconda di come configurato gli input nell'applicazione di addestramento. I modelli TensorFlow possono accettano input più complessi, mentre la maggior parte dei modelli scikit-learn e XGBoost prevede elenco di numeri come input.

L'esempio seguente mostra un tensore di input e una chiave di istanza per un modello TensorFlow:

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

La composizione della stringa JSON può essere complessa, a condizione che segua queste regole:

  • Il livello superiore dei dati dell'istanza deve essere un oggetto JSON: un dizionario di coppie chiave-valore.

  • I singoli valori di un oggetto istanza possono essere stringhe, numeri o elenchi. Non puoi incorporare oggetti JSON.

  • Gli elenchi devono contenere solo elementi dello stesso tipo (inclusi altri elenchi). Tu non possono combinare stringhe con valori numerici.

Le istanze di input per la previsione online vengono passate come corpo del messaggio Chiamata projects.locations.endpoints.predict. Scopri di più sulla richiesta requisiti di formattazione del corpo.

Rendi ogni istanza un elemento in un array JSON e fornisci l'array come Campo instances di un oggetto JSON. Ad esempio:

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

Codifica i dati binari per l'input di previsione

I dati binari non possono essere formattati come stringhe con codifica UTF-8 supportate da JSON. Se gli input contengono dati binari, devi utilizzare la codifica base64 per che lo rappresentano. È richiesta la seguente formattazione speciale:

  • La stringa codificata deve essere formattata come oggetto JSON con una singola chiave denominato b64. In Python 3, la codifica base64 restituisce una sequenza di byte. Devi converti questo valore in una stringa per renderlo serializzabile in JSON:

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

  • Nel codice del modello TensorFlow, devi assegnare un nome agli alias del file binario di input e output in modo che terminino con "_bytes".

Esempi di richieste e risposte

Questa sezione descrive il formato del corpo della richiesta di previsione e corpo di risposta, con esempi per TensorFlow, scikit-learn e XGBoost.

Dettagli del corpo della richiesta

TensorFlow

Il corpo della richiesta contiene dati con la seguente struttura (JSON rappresentazione):

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

L'oggetto instances[] è obbligatorio e deve contenere l'elenco di istanze per cui ottenere previsioni.

La struttura di ogni elemento dell'elenco delle istanze è determinata definizione di input del modello. Le istanze possono includere input denominati (come oggetti) o può contenere solo valori senza etichetta.

Non tutti i dati includono input denominati. Alcune istanze sono semplici valori JSON (booleano, numero o stringa). Tuttavia, le istanze sono spesso elenchi di semplici oppure elenchi nidificati complessi.

Di seguito sono riportati alcuni esempi di corpo delle richieste.

Dati CSV con ogni riga codificata come valore di stringa:

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

Testo normale:

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

Frasi codificate come elenchi di parole (vettori di stringhe):

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

Valori scalari in virgola mobile:

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

Vettori di numeri interi:

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

Tensori (in questo caso, tensori bidimensionali):

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

Immagini, che possono essere rappresentate in modi diversi. In questo schema di codifica le prime due dimensioni rappresentano le righe e le colonne dell'immagine, e la terza dimensione contiene elenchi (vettori) di valori R, G e B per ciascun pixel:

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

Codifica dei dati

Le stringhe JSON devono essere codificate come UTF-8. Per inviare dati binari, devi codificano i dati in base64 e li contrassegnano come binari. Per contrassegnare una stringa JSON come binario, sostituiscilo con un oggetto JSON con un singolo attributo denominato b64: 

{"b64": "..."}

L'esempio seguente mostra due tf.Examples serializzati che richiedono la codifica Base64 (dati falsi, ad esempio solo a scopo di lucro):

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

L'esempio seguente mostra due stringhe di byte immagine JPEG, che richiedono il formato base64 codifica (dati falsi, a solo scopo illustrativo):

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

Tensori multipli di input

Alcuni modelli hanno un grafo TensorFlow sottostante che accetta più tensori di input. In questo caso, utilizza i nomi dei nomi/valori JSON per identificare i tensori di input.

Per un grafico con alias di tensori di input "tag" (stringa) e "immagine" (stringa con codifica base64): 

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

Per un grafico con alias di tensori di input "tag" (stringa) e "immagine" (array tridimensionale di numeri interi a 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

Il corpo della richiesta contiene dati con la seguente struttura (JSON rappresentazione):

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

L'oggetto instances[] è obbligatorio e deve contenere l'elenco di istanze per cui ottenere previsioni. Nell'esempio seguente, ogni istanza di input è un di numeri in virgola mobile:

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

La dimensione delle istanze di input deve corrispondere a quella prevista dal modello. Per Ad esempio, se il modello richiede tre caratteristiche, la lunghezza di ognuna l'istanza di input deve essere 3.

XGBoost

Il corpo della richiesta contiene dati con la seguente struttura (JSON rappresentazione):

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

L'oggetto instances[] è obbligatorio e deve contenere l'elenco di istanze per cui ottenere previsioni. Nell'esempio seguente, ogni istanza di input è un di numeri in virgola mobile:

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

La dimensione delle istanze di input deve corrispondere a quella prevista dal modello. Per Ad esempio, se il modello richiede tre caratteristiche, la lunghezza di ognuna l'istanza di input deve essere 3.

Vertex AI non supporta la rappresentazione sparsa dell'input per XGBoost.

Il servizio di previsione online interpreta in modo diverso gli zeri e i NaN. Se il valore di una caratteristica è zero, utilizza 0.0 nell'input corrispondente. Se valore di una caratteristica mancante, utilizza "NaN" nell'input corrispondente.

L'esempio seguente rappresenta una richiesta di previsione con un singolo input in cui il valore della prima caratteristica è 0, 0, il valore della la seconda caratteristica è 1.1 e manca il valore della terza caratteristica:

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

PyTorch

Se il modello utilizza un modello PyTorch predefinito container, I gestori predefiniti di TorchServe si aspettano che ogni istanza venga sottoposta a wrapping in un oggetto data . Ad esempio:

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

Dettagli del corpo della risposta

Se la chiamata ha esito positivo, il corpo della risposta contiene una voce di previsione per nel corpo della richiesta, indicato nello stesso ordine:

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

Se la previsione non riesce per un'istanza, il corpo della risposta non contiene previsioni. Contiene invece una singola voce di errore:

{
  "error": string
}

L'oggetto predictions[] contiene l'elenco di previsioni, una per ciascuna di Compute Engine nella richiesta.

In caso di errore, la stringa error contiene un messaggio che descrive il problema. La viene restituito un errore anziché un elenco di previsione se si è verificato un errore durante per l'elaborazione di qualsiasi istanza.

Anche se esiste una sola previsione per istanza, il formato di una previsione direttamente correlati al formato di un'istanza. Le previsioni prendono qualsiasi cosa viene specificato nella raccolta di output definita nel modello. La di previsioni, viene restituita in un elenco JSON. Ogni membro dell'elenco può essere un valore semplice, un elenco o un oggetto JSON di qualsiasi complessità. Se il modello ha più di un tensore di output, ogni previsione sarà un oggetto JSON contenente una coppia nome-valore per ogni output. I nomi identificano l'output alias nel grafico.

Esempi di corpo della risposta

TensorFlow

I seguenti esempi mostrano alcune possibili risposte:

  • Un semplice insieme di previsioni per tre istanze di input, in cui ognuna la previsione è un valore intero:

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

  • Un insieme più complesso di previsioni, ognuna contenente due valori denominati che corrispondono ai tensori di output, denominati label e rispettivamente scores. Il valore di label è la categoria prevista ("auto" o "spiaggia") e scores contiene un elenco di probabilità per quell'istanza tra le possibili categorie.

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

  • Una risposta in caso di errore durante l'elaborazione di un'istanza di input:

    {"error": "Divide by zero"}

scikit-learn

I seguenti esempi mostrano alcune possibili risposte:

  • Un semplice insieme di previsioni per tre istanze di input, in cui ognuna la previsione è un valore intero:

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

  • Una risposta in caso di errore durante l'elaborazione di un'istanza di input:

    {"error": "Divide by zero"}

XGBoost

I seguenti esempi mostrano alcune possibili risposte:

  • Un semplice insieme di previsioni per tre istanze di input, in cui ognuna la previsione è un valore intero:

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

  • Una risposta in caso di errore durante l'elaborazione di un'istanza di input:

    {"error": "Divide by zero"}

Invia una richiesta a un endpoint

Esistono tre modi per inviare una richiesta:

Invia una richiesta di previsione online

gcloud

L'esempio seguente utilizza la classe gcloud ai endpoints predict comando:

  1. Scrivi il seguente oggetto JSON da archiviare nel tuo ambiente locale. Il nome del file non importa, ma in questo esempio puoi assegnare al file il nome request.json.

    {
 "instances": INSTANCES
}

    Sostituisci quanto segue:

  2. Esegui questo comando:

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

    Sostituisci quanto segue:

    • ENDPOINT_ID: l'ID dell'endpoint.
    • LOCATION_ID: la regione in cui stai utilizzando Vertex AI.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "instances": INSTANCES
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo comando: 

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

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo comando: 

$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
Se l'operazione ha esito positivo, riceverai una risposta JSON simile alla seguente. Nella risposta, aspettati le seguenti sostituzioni:
  • PREDICTIONS: un array JSON di previsioni, una per ogni istanza inclusa nella corpo della richiesta.
  • DEPLOYED_MODEL_ID: l'ID del DeployedModel che ha pubblicato le previsioni. 
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Java Vertex AI documentazione di riferimento.

Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale. 


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

Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Node.js Vertex AI documentazione di riferimento.

Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta documentazione di riferimento dell'API Python. 

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

Invia una richiesta di previsione non elaborata online

gcloud

I seguenti esempi utilizzano la classe gcloud ai endpoints raw-predict comando:

  • Per richiedere previsioni con l'oggetto JSON in REQUEST specificato su la riga di comando:

     gcloud ai endpoints raw-predict ENDPOINT_ID \
     --region=LOCATION_ID \
     --request=REQUEST

  • Per richiedere previsioni con un'immagine archiviata nel file image.jpeg e l'intestazione Content-Type appropriata:

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

    Sostituisci quanto segue:

    • ENDPOINT_ID: l'ID dell'endpoint.
    • LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
    • REQUEST: i contenuti della richiesta che vuoi ricevere per le previsioni. Il formato della richiesta dipende da ciò che il tuo previsto, che potrebbe non essere necessariamente un oggetto JSON.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta documentazione di riferimento dell'API Python. 

# -*- 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)

La risposta include le seguenti intestazioni HTTP:

  • X-Vertex-AI-Endpoint-Id: ID di Endpoint che hanno pubblicato questa previsione.

  • X-Vertex-AI-Deployed-Model-Id: ID della DeployedModel dell'endpoint che ha pubblicato questa previsione.

Invia una richiesta di spiegazione online

gcloud

L'esempio seguente utilizza la classe gcloud ai endpoints explain comando:

  1. Scrivi il seguente oggetto JSON da archiviare nel tuo ambiente locale. Il nome del file non importa, ma in questo esempio puoi assegnare al file il nome request.json.

    {
 "instances": INSTANCES
}

    Sostituisci quanto segue:

  2. Esegui questo comando:

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

    Sostituisci quanto segue:

    • ENDPOINT_ID: l'ID dell'endpoint.
    • LOCATION_ID: la regione in cui stai utilizzando Vertex AI.

    Se vuoi inviare una richiesta di spiegazione a un DeployedModel specifico, se vuoi (facoltativo) In Endpoint, puoi specificare il flag --deployed-model-id:

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

    Oltre ai segnaposto descritti in precedenza, sostituisci quanto segue:

    • DEPLOYED_MODEL_ID Facoltativo: l'ID del modello di cui hai eseguito il deployment per il quale vuoi recuperare spiegazioni. L'ID è incluso nella risposta del metodo predict. Per richiedere spiegazioni per un determinato modello e se è stato eseguito il deployment di più modelli nello stesso endpoint, puoi utilizzare questo ID per assicurarti che vengano restituite le spiegazioni per quel particolare un modello di machine learning.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "instances": INSTANCES
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo comando: 

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

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo comando: 

$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
Se l'operazione ha esito positivo, riceverai una risposta JSON simile alla seguente. Nella risposta, aspettati le seguenti sostituzioni:
  • PREDICTIONS: un array JSON di previsioni, una per ogni istanza inclusa nella corpo della richiesta.
  • EXPLANATIONS: un array JSON di spiegazioni, uno per ogni previsione.
  • DEPLOYED_MODEL_ID: l'ID del DeployedModel che ha pubblicato le previsioni. 
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta documentazione di riferimento dell'API 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)

Passaggi successivi