Ottieni previsioni online da un modello addestrato personalizzato

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

Formattare 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 il metodo predict o explain. Non è obbligatorio se sei rawPredict . Per informazioni su quale metodo scegliere, consulta la sezione Inviare richiesta all'endpoint.

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

Se il modello utilizza un container personalizzato, il dato di input deve essere formattato come JSON ed è presente un campo parameters aggiuntivo che può essere utilizzato 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. Possono essere elenchi di valori semplici o membri di un oggetto JSON, a seconda di come hai 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.

Questo esempio 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 per la chiamataprojects.locations.endpoints.predict. Scopri di più sulla richiesta requisiti di formattazione del corpo.

Rendi ogni istanza un elemento di 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 rappresentarli. È richiesta la seguente formattazione speciale:

  • La stringa codificata deve essere formattata come oggetto JSON con una singola chiave chiamata 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 delle istanze per le quali ottenere le 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 (booleani, numeri o stringhe). 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 gli elenchi (vettori) dei valori R, G e B per ogni 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 binaria, sostituiscila 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 grafico TensorFlow sottostante che accetta più tensori di input. In questo caso, utilizza i nomi delle coppie nome/valore 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 (rappresentazione JSON):

{
  "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 elenco di valori float:

{
  "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. Ad esempio, se il modello richiede tre funzionalità, la lunghezza di ogni istanza di input deve essere 3.

XGBoost

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

{
  "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 elenco di valori float:

{
  "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 funzionalità è 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 una singola istanza di input, in cui il valore della prima caratteristica è 0,0, il valore della seconda caratteristica è 1,1 e il valore della terza caratteristica non è presente:

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

PyTorch

Se il tuo modello utilizza un container predefinito PyTorch, i gestori predefiniti di TorchServe si aspettano che ogni istanza sia racchiusa in un campo 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 va a buon fine per una qualsiasi istanza, il corpo della risposta non contiene previsioni. Contiene invece una singola voce di errore:

{
  "error": string
}

L'oggetto predictions[] contiene l'elenco delle previsioni, una per ogni istanza nella richiesta.

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

Anche se è presente 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 raccolta delle previsioni viene restituita in un elenco JSON. Ogni elemento dell'elenco può essere un valore semplice, un elenco o un oggetto JSON di qualsiasi complessità. Se il tuo 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 testo della risposta

TensorFlow

I seguenti esempi mostrano alcune possibili risposte:

  • Un semplice insieme di previsioni per tre istanze di input, in cui ogni 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 quando si verifica un errore durante l'elaborazione di un'istanza di input:

    {"error": "Divide by zero"}

Inviare una richiesta a un endpoint

Esistono tre modi per inviare una richiesta:

Inviare una richiesta di previsione online

gcloud

Nell'esempio seguente viene utilizzato il comando gcloud ai endpoints predict:

  1. Scrivi il seguente oggetto JSON da archiviare nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio, chiamalo request.json.

    {
 "instances": INSTANCES
}

    Sostituisci quanto segue:

    • INSTANCES: un array JSON di istanze per cui vuoi ottenere previsioni . Il formato di ogni istanza dipende dagli input previsti dal tuo modello ML addestrato. Per ulteriori informazioni, consulta la sezione Formattare l'input per la previsione online.

  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 utilizzi Vertex AI.

REST

Prima di utilizzare i dati della richiesta, apporta 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 nel 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 la documentazione di riferimento dell'API Java di Vertex AI.

Per autenticarti in Vertex AI, configura le 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 di configurazione Node.js riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta API Node.js Vertex AI documentazione di riferimento.

Per autenticarti in Vertex AI, configura le credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la 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 online a un endpoint dedicato

Gli endpoint dedicati utilizzano un nuovo percorso URL. Puoi recuperare questo percorso dal campo dedicatedEndpointDns nell'API REST o da Endpoint.dedicated_endpoint_dns nell'SDK Vertex AI per Python. Puoi anche costruisci manualmente il percorso dell'endpoint utilizzando il seguente codice:

f"https://ENDPOINT_ID.LOCATION_ID-PROJECT_NUMBER.prediction.vertexai.goog/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

Sostituisci quanto segue:

  • ENDPOINT_ID: l'ID dell'endpoint.
  • LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
  • PROJECT_NUMBER: il numero del progetto. È diverso dall'ID progetto. Puoi trovare il numero di progetto nella pagina Impostazioni progetto del progetto in Google Cloud Console.

Per inviare una previsione a un endpoint dedicato utilizzando l'SDK Vertex AI per Python, imposta il parametro use_dedicated_endpoint su True:

endpoint.predict(instances=instances, use_dedicated_endpoint=True)

Invia una richiesta di previsione non elaborata online

gcloud

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

  • Per richiedere le previsioni con l'oggetto JSON in REQUEST specificato nella 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 utilizzi Vertex AI.
    • REQUEST: i contenuti della richiesta per cui vuoi ricevere le predizioni. Il formato della richiesta dipende da ciò che il tuo 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 saperne di più, consulta la documentazione di riferimento dell'API Python. 

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 dei 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

Nell'esempio seguente viene utilizzato il comando gcloud ai endpoints explain:

  1. Scrivi il seguente oggetto JSON in un file nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio, chiamalo request.json.

    {
 "instances": INSTANCES
}

    Sostituisci quanto segue:

    • INSTANCES: un array JSON di istanze per cui vuoi ottenere previsioni . Il formato di ogni istanza dipende dagli input del modello ML addestrato si aspetta. Per ulteriori informazioni, consulta la sezione Formattare l'input per la previsione online.

  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, puoi inviare una richiesta di spiegazione a un DeployedModel specifico su Endpoint specificando 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 vuoi ricevere le spiegazioni. L'ID è incluso nella risposta del metodo predict. Se devi richiedere spiegazioni per un determinato modello e hai più di un modello di cui è stato eseguito il deployment nello stesso endpoint, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per quel determinato modello.

REST

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

  • LOCATION_ID: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo ID progetto
  • ENDPOINT_ID: l'ID dell'endpoint.
  • INSTANCES: un array JSON di istanze per le quali vuoi ottenere le previsioni. Il formato di ogni istanza dipende dagli input del modello ML addestrato si aspetta. Per ulteriori informazioni, consulta la sezione Formattare l'input per la previsione online.

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, quindi esegui il comando seguente: 

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 nel corpo della richiesta.
  • EXPLANATIONS: un array JSON di spiegazioni, una 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 saperne di più, consulta la 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