Generazione di previsioni online da modelli con addestramento personalizzato

La previsione online di Vertex AI è un servizio ottimizzato per eseguire i dati in modelli ospitati con la minore latenza possibile. Invia piccoli gruppi di dati al servizio e restituisce le tue previsioni nella risposta.

Prima di iniziare

Per richiedere le previsioni, devi prima:

• Addestrare il modello. Nel codice di addestramento, esporta gli artefatti del modello addestrato come uno o più artefatti del modello di cui è possibile eseguire il deployment in Vertex AI.

• Esegui il deployment del tuo modello addestrato su Vertex AI caricando gli artefatti del modello ed eseguendo il deployment del modello su un endpoint Vertex AI.

Configura deployment modello

Durante il deployment del modello, prendi le seguenti decisioni importanti su come eseguire la previsione online:

Risorsa creata	Impostazione specificata al momento della creazione della risorsa
Endpoint	Località in cui eseguire le previsioni
Modello	Contenitore da utilizzare (ModelContainerSpec)
Modello sottoposto a deployment	Macchine da utilizzare per la previsione online

Non puoi aggiornare le impostazioni elencate sopra dopo la creazione iniziale del modello o dell'endpoint e non puoi sostituirle nella richiesta di previsione online. Se devi modificare queste impostazioni, devi eseguire nuovamente il deployment del modello.

Formatta il tuo input per la previsione online

Se utilizzi uno dei nostri container predefiniti per gestire le previsioni con TensorFlow, scikit-learn o XGBoost, le tue istanze di input di previsione devono essere formattate come JSON.

Se il modello utilizza un contenitore personalizzato, l'input deve essere formattato come JSON e esiste un campo parameters aggiuntivo che può essere utilizzato per il contenitore. Scopri di più sull'input previsione della formattazione con contenitori personalizzati.

Questa sezione mostra come formattare le istanze di input di previsione in formato JSON e come gestire i dati binari con la codifica base64.

Formattare le istanze come stringhe JSON

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

In questo esempio è mostrato un tensore di input e una chiave di istanza per un modello TensorFlow:

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

La configurazione della stringa JSON può essere complessa purché rispetti le seguenti regole:

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

• I singoli valori in 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). Non puoi combinare stringhe e valori numerici.

Passi le istanze di input per la previsione online come corpo del messaggio per la chiamata projects.locations.endpoints.predict. Scopri di più sui requisiti di formattazione del corpo della richiesta.

Assegna a 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 dei dati binari per l'input della previsione

Nota: questa sezione si applica solo alla previsione con TensorFlow.

I dati binari non possono essere formattati come stringhe codificate UTF-8 supportate da JSON. Se nei tuoi input sono presenti dati binari, devi utilizzare la codifica Base64 per rappresentarli. La seguente formattazione speciale è obbligatoria:

• La stringa codificata deve essere formattata come oggetto JSON con un'unica chiave denominata b64. In Python 3, la codifica Base64 restituisce una sequenza di byte. Devi convertirlo in una stringa per renderlo serializzabile JSON:

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

• Nel codice del modello TensorFlow devi assegnare un nome agli alias per i tensori di input e output binari, in modo che terminino con '_bytes'.

Esempi di richieste e risposte

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

Dettagli corpo richiesta

TensorFlow

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

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

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

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

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

Di seguito sono riportati alcuni esempi di corpi di richieste.

Dati CSV con ogni riga codificata come valore 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],
    ...
  ]
}

Tensor (in questo caso i tensori bidimensionali):

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

Le 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, mentre la terza dimensione contiene 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 codificare i dati in base64 e contrassegnarli 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 istanze tf.Examples serializzate, che richiedono la codifica Base64 (dati falsi, a solo scopo illustrativo):

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

L'esempio seguente mostra due stringhe di byte immagine JPEG, che richiedono la codifica Base64 (dati falsi, a scopo puramente illustrativo):

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

Più tensori di ingresso

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 gli alias tensore di input "tag" (stringa) e "image" (stringa con codifica base64):

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

Per un grafico con alias tensore di input "tag" (stringa) e "immagine" (array 3D di int 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 i dati con la seguente struttura (rappresentazione JSON):

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

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

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

La dimensione delle istanze di input deve corrispondere a quanto previsto 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 i dati con la seguente struttura (rappresentazione JSON):

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

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

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

La dimensione delle istanze di input deve corrispondere a quanto previsto dal modello. Ad esempio, se il modello richiede tre funzionalità, la lunghezza di ogni istanza di input deve essere 3.

Vertex AI non supporta la rappresentazione sparsa delle istanze di input per XGBoost.

Il servizio di previsione online interpreta gli zeri e i NaN in modo diverso. Se il valore di una caratteristica è zero, utilizza 0.0 nell'input corrispondente. Se il valore di una caratteristica non è presente, 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 manca il valore della terza.

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

Dettagli corpo della risposta

Le risposte sono molto simili alle richieste.

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

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

Se la previsione non va a buon fine per qualsiasi istanza, il corpo della risposta non conterrà previsioni. Contiene invece una singola voce di errore:

{
  "error": string
}

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

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

Anche se è presente una sola previsione per istanza, il formato di una previsione non è direttamente correlato al formato di un'istanza. Le previsioni utilizzano il formato specificato nella raccolta di output definita nel modello. La raccolta 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ù tensor di output, ogni previsione sarà un oggetto JSON contenente una coppia nome/valore per ogni output. I nomi identificano gli alias di output nel grafico.

Esempi di corpo delle risposte

TensorFlow

Negli esempi seguenti sono riportate alcune possibili risposte:

• Un semplice set 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, ciascuna contenente due valori denominati che corrispondono a tensori di output, denominati rispettivamente label e scores. Il valore di label è la categoria prevista ("auto" o "spiaggia") e scores contiene un elenco di probabilità per tale istanza nelle 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

Negli esempi seguenti sono riportate alcune possibili risposte:

• Un semplice set di previsioni per tre istanze di input, in cui ogni 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

Negli esempi seguenti sono riportate alcune possibili risposte:

• Un semplice set di previsioni per tre istanze di input, in cui ogni 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 di previsione online

Richiedi una previsione online inviando le istanze di dati di input come stringa JSON in una richiesta previsione. Per la formattazione del corpo della richiesta e della risposta, consulta i dettagli della richiesta di previsione.

Ogni richiesta di previsione deve avere una dimensione massima di 1,5 MB.

gcloud

L'esempio seguente utilizza il comando gcloud ai endpoints predict:

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

   {
    "instances": INSTANCES
   }
   

   Sostituisci quanto segue:

   • INSTANCES: un array di istanze JSON per cui vuoi ottenere previsioni. Il formato di ogni istanza dipende da ciò che ti aspetta il tuo modello di machine learning addestrato specifico. Consulta la sezione Formattazione dell'input per la previsione online di questo documento.

2. Esegui questo comando:

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

   Sostituisci quanto segue:

   • ENDPOINT_ID: l'ID dell'endpoint.
   • LOCATION: l'area geografica in cui utilizzi Vertex AI.

REST &CMD LINE

Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:

• LOCATION: l'area geografica in cui utilizzi Vertex AI.
• PROJECT: ID o numero del progetto
• ENDPOINT_ID: l'ID dell'endpoint.
• INSTANCES: un array di istanze JSON per cui vuoi ottenere previsioni. Il formato di ogni istanza dipende da ciò che ti aspetta il tuo modello di machine learning addestrato specifico. Consulta la sezione Formattazione dell'input per la previsione online di questo documento.

Metodo HTTP e URL:

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

Corpo JSON richiesta:

{
  "instances": INSTANCES
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

Curling

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

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

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

$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

In caso di esito positivo, ricevi una risposta JSON simile alla seguente. Nella risposta, aspettati le seguenti sostituzioni:

• PREDICTIONS: un array JSON di previsioni, una per ogni istanza che hai incluso nel corpo della richiesta.
• DEPLOYED_MODEL_ID: l'ID di DeployedModel che ha pubblicato queste previsioni.

{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Per informazioni su come installare e utilizzare la libreria client per Vertex AI, consulta le librerie client di Vertex AI. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di AI AI.

Visualizza su GitHub Feedback

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

Per informazioni su come installare e utilizzare la libreria client per Vertex AI, consulta le librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Vertex AI.js.

Visualizza su GitHub Feedback

/**
 * 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 informazioni su come installare e utilizzare la libreria client per Vertex AI, consulta le librerie client di Vertex AI. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python AI Vertex.

Visualizza su GitHub Feedback

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

In alternativa, puoi inviare una richiesta Raw predict, che ti consente di utilizzare un payload HTTP arbitrario, invece di seguire le rigide linee guida descritte nelle sezioni precedenti di questa guida.

Potresti ricevere previsioni non elaborate se utilizzi un container personalizzato che riceve richieste e invia risposte diverse dalle linee guida.

gcloud

L'esempio seguente utilizza il comando gcloud ai endpoints raw-predict:

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

  gcloud ai endpoints raw-predict ENDPOINT_ID \
    --region=LOCATION \
    --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 \
    --http-headers=Content-Type=image/jpeg \
    --request @image.jpeg
  

Sostituisci quanto segue:

• ENDPOINT_ID: l'ID dell'endpoint.
• LOCATION: l'area geografica in cui utilizzi Vertex AI.
• REQUEST: i contenuti della richiesta per cui vuoi ottenere previsioni. Il formato della richiesta dipende da ciò che il container personalizzato si aspetta, che potrebbe non essere necessariamente un oggetto JSON.

La risposta include le seguenti intestazioni HTTP:

• X-Vertex-AI-Endpoint-Id: ID del Endpoint che ha pubblicato la previsione.

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

Nota: se il container riceve richieste o invia risposte diverse dalle linee guida, il container non è compatibile con Vertex Explainable AI o Vertex AI Model Monitoring.

Invia una richiesta di spiegazione online

Se hai configurato il tuo sistema Model per Vertex Explainable AI, puoi ricevere spiegazioni online. Le richieste di spiegazione online hanno lo stesso formato delle richieste di previsione online e restituiscono risposte simili; l'unica differenza è che le risposte alla spiegazione online includono attribuzioni delle funzionalità e previsioni.

I seguenti esempi sono quasi identici a quelli della sezione precedente, ad eccezione del fatto che utilizzano comandi leggermente diversi:

gcloud

L'esempio seguente utilizza il comando gcloud ai endpoints explain:

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

   {
    "instances": INSTANCES
   }
   

   Sostituisci quanto segue:

   • INSTANCES: un array di istanze JSON per cui vuoi ottenere previsioni. Il formato di ogni istanza dipende da ciò che ti aspetta il tuo modello di machine learning addestrato specifico. Consulta la sezione Formattazione dell'input per la previsione online di questo documento.

2. Esegui questo comando:

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

   Sostituisci quanto segue:

   • ENDPOINT_ID: l'ID dell'endpoint.
   • LOCATION: l'area geografica in cui utilizzi Vertex AI.

   Se vuoi, se vuoi inviare una richiesta di spiegazione a un DeployedModel specifico 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:

   • (Facoltativo) DEPLOYED_MODEL_ID: l'ID del modello di cui hai eseguito il deployment per il quale vuoi ottenere spiegazioni. L'ID è incluso nella risposta del metodo predict. Se devi richiedere spiegazioni per un determinato modello e hai eseguito il deployment di più modelli sullo stesso endpoint, puoi utilizzare questo ID per assicurarti che vengano restituite le spiegazioni per quel modello specifico.

REST &CMD LINE

Prima di utilizzare uno qualsiasi dei dati della richiesta, effettua le seguenti sostituzioni:

• LOCATION: l'area geografica in cui utilizzi Vertex AI.
• PROJECT: ID o numero del progetto
• ENDPOINT_ID: l'ID dell'endpoint.
• INSTANCES: un array di istanze JSON per cui vuoi ottenere previsioni. Il formato di ogni istanza dipende da ciò che ti aspetta il tuo modello di machine learning addestrato specifico. Consulta la sezione Formattazione dell'input per la previsione online di questo documento.

Metodo HTTP e URL:

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

Corpo JSON richiesta:

{
  "instances": INSTANCES
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

Curling

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

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

Nota: assicurati di aver impostato la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave privata dell'account di servizio.

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

$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

In caso di esito positivo, ricevi una risposta JSON simile alla seguente. Nella risposta, aspettati le seguenti sostituzioni:

• PREDICTIONS: un array JSON di previsioni, una per ogni istanza che hai incluso nel corpo della richiesta.
• EXPLANATIONS: un array JSON di spiegazioni, uno per ogni previsione.
• DEPLOYED_MODEL_ID: l'ID di DeployedModel che ha pubblicato queste previsioni.

{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

Per informazioni su come installare e utilizzare la libreria client per Vertex AI, consulta le librerie client di Vertex AI. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python AI Vertex.

Visualizza su GitHub Feedback

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

• Scopri come ottenere previsioni dai modelli AutoML.