Ricevere previsioni e spiegazioni online

Questa pagina mostra come ottenere spiegazioni e previsioni online (in tempo reale) dai modelli di classificazione o regressione tabulari utilizzando la console Google Cloud o l'API Vertex AI.

Una previsione online è una richiesta sincrona, anziché una previsione batch, che è una richiesta asincrona. Utilizza le previsioni online quando effettui richieste in risposta all'input dell'applicazione o in altre situazioni in cui hai bisogno di un'inferenza tempestiva.

Devi eseguire il deployment di un modello in un endpoint prima di poterlo usare per fornire previsioni online. Il deployment di un modello associa risorse fisiche al modello in modo che possa fornire previsioni online con bassa latenza.

Gli argomenti trattati sono:

  1. Deployment di un modello in un endpoint
  2. Ottieni una previsione online utilizzando il modello di cui è stato eseguito il deployment
  3. Ottieni una spiegazione online utilizzando il modello di cui è stato eseguito il deployment

Prima di iniziare

Prima di poter ottenere previsioni online, devi prima addestrare un modello di classificazione o regressione.

esegui il deployment di un modello in un endpoint

Puoi eseguire il deployment di più modelli in un endpoint e puoi eseguire il deployment di un modello in più di un endpoint. Per ulteriori informazioni sulle opzioni e sui casi d'uso per sul deployment dei modelli, consulta Informazioni sul deployment dei modelli.

Per eseguire il deployment di un modello, utilizza uno dei seguenti metodi:

Console Google Cloud

  1. Nella console Google Cloud, nella sezione Vertex AI, vai a la pagina Modelli.

    Vai alla pagina Modelli

  2. Fai clic sul nome del modello di cui vuoi eseguire il deployment per aprire la relativa pagina dei dettagli.

  3. Seleziona la scheda Deployment e test.

    Se il modello è già stato implementato in uno o più endpoint, questi sono elencati nella sezione Esegui il deployment del modello.

  4. Fai clic su Esegui il deployment nell'endpoint.

  5. Nella pagina Definisci l'endpoint, configura come segue:

    1. Puoi scegliere di eseguire il deployment del modello su un endpoint nuovo o esistente.

      • Per eseguire il deployment del modello in un nuovo endpoint, seleziona Crea nuovo endpoint e specificare un nome per il nuovo endpoint.
      • Per eseguire il deployment del modello in un endpoint esistente, seleziona Aggiungi a endpoint esistente e seleziona l'endpoint dall'elenco a discesa.
      • Puoi aggiungere più di un modello a un endpoint e aggiungerne uno a più di un endpoint. Scopri di più.

    2. Fai clic su Continua.

  6. Nella pagina Impostazioni modello, configura come segue:

    1. Se esegui il deployment del modello in un nuovo endpoint, accetta 100 per la Suddivisione del traffico. Se esegui il deployment del modello in un endpoint esistente in cui sono già stati dipiazzati uno o più modelli, devi aggiornare la percentuale di Suddivisione traffico per il modello di cui stai eseguendo il deployment e per i modelli già dipiazzati in modo che tutte le percentuali sommino al 100%.

    2. Inserisci il numero minimo di nodi di computing che vuoi fornire. del modello.

      Si tratta del numero di nodi disponibili per questo modello in qualsiasi momento. Ti vengono addebitati i nodi utilizzati, sia per gestire il carico di previsione sia per i nodi di riserva (minimi), anche senza traffico di previsione. Consulta la pagina relativa ai prezzi.

    3. Seleziona il tipo di macchina.

      L'utilizzo di risorse più grandi della macchina incrementerà le prestazioni di previsione e aumentare i costi.

    4. Scopri come modificare le impostazioni predefinite per la registrazione delle previsioni.

    5. Fai clic su Continua.

  7. Nella pagina Monitoraggio del modello, fai clic su Continua.

  8. Nella pagina Obiettivi di Monitoring, configura come segue:

    1. Inserisci la località dei dati di addestramento.
    2. Inserisci il nome della colonna di destinazione.

  9. Fai clic su Esegui il deployment per eseguire il deployment del modello nell'endpoint.

API

Quando esegui il deployment di un modello utilizzando l'API Vertex AI, completa i seguenti passaggi:

  1. Se necessario, crea un endpoint.
  2. Recupera l'ID endpoint.
  3. Eseguire il deployment del modello nell'endpoint.

Creazione di un endpoint

Se esegui il deployment di un modello in un endpoint esistente, puoi saltare questo passaggio.

gcloud

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

  gcloud ai endpoints create \
    --region=LOCATION \
    --display-name=ENDPOINT_NAME

Sostituisci quanto segue:

  • LOCATION_ID: la regione in cui utilizzi Vertex AI.

  • ENDPOINT_NAME: il nome visualizzato dell'endpoint.

    Lo strumento Google Cloud CLI potrebbe richiedere alcuni secondi per creare l'endpoint.

REST

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

  • LOCATION_ID: la tua regione.
  • PROJECT_ID: il tuo ID progetto.
  • ENDPOINT_NAME: il nome visualizzato dell'endpoint.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "display_name": "ENDPOINT_NAME"
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateEndpointOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-11-05T17:45:42.812656Z",
      "updateTime": "2020-11-05T17:45:42.812656Z"
    }
  }
}
Puoi eseguire il polling per lo stato dell'operazione finché la risposta non include "done": true.

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 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.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.CreateEndpointOperationMetadata;
import com.google.cloud.aiplatform.v1.Endpoint;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateEndpointSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String endpointDisplayName = "YOUR_ENDPOINT_DISPLAY_NAME";
    createEndpointSample(project, endpointDisplayName);
  }

  static void createEndpointSample(String project, String endpointDisplayName)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    EndpointServiceSettings endpointServiceSettings =
        EndpointServiceSettings.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 (EndpointServiceClient endpointServiceClient =
        EndpointServiceClient.create(endpointServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);
      Endpoint endpoint = Endpoint.newBuilder().setDisplayName(endpointDisplayName).build();

      OperationFuture<Endpoint, CreateEndpointOperationMetadata> endpointFuture =
          endpointServiceClient.createEndpointAsync(locationName, endpoint);
      System.out.format("Operation name: %s\n", endpointFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      Endpoint endpointResponse = endpointFuture.get(300, TimeUnit.SECONDS);

      System.out.println("Create Endpoint Response");
      System.out.format("Name: %s\n", endpointResponse.getName());
      System.out.format("Display Name: %s\n", endpointResponse.getDisplayName());
      System.out.format("Description: %s\n", endpointResponse.getDescription());
      System.out.format("Labels: %s\n", endpointResponse.getLabelsMap());
      System.out.format("Create Time: %s\n", endpointResponse.getCreateTime());
      System.out.format("Update Time: %s\n", endpointResponse.getUpdateTime());
    }
  }
}

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 eseguire l'autenticazione su Vertex AI, configura 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 endpointDisplayName = 'YOUR_ENDPOINT_DISPLAY_NAME';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

// Imports the Google Cloud Endpoint Service Client library
const {EndpointServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const endpointServiceClient = new EndpointServiceClient(clientOptions);

async function createEndpoint() {
  // Configure the parent resource
  const parent = `projects/${project}/locations/${location}`;
  const endpoint = {
    displayName: endpointDisplayName,
  };
  const request = {
    parent,
    endpoint,
  };

  // Get and print out a list of all the endpoints for this resource
  const [response] = await endpointServiceClient.createEndpoint(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  const result = response.result;

  console.log('Create endpoint response');
  console.log(`\tName : ${result.name}`);
  console.log(`\tDisplay name : ${result.displayName}`);
  console.log(`\tDescription : ${result.description}`);
  console.log(`\tLabels : ${JSON.stringify(result.labels)}`);
  console.log(`\tCreate time : ${JSON.stringify(result.createTime)}`);
  console.log(`\tUpdate time : ${JSON.stringify(result.updateTime)}`);
}
createEndpoint();

Python

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

def create_endpoint_sample(
    project: str,
    display_name: str,
    location: str,
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint.create(
        display_name=display_name,
        project=project,
        location=location,
    )

    print(endpoint.display_name)
    print(endpoint.resource_name)
    return endpoint

recupera l'ID endpoint

L'ID endpoint è necessario per eseguire il deployment del modello.

gcloud

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

  gcloud ai endpoints list \
    --region=LOCATION \
    --filter=display_name=ENDPOINT_NAME

Sostituisci quanto segue:

  • LOCATION_ID: la regione in cui utilizzi Vertex AI.

  • ENDPOINT_NAME: il nome visualizzato dell'endpoint.

    Prendi nota del numero visualizzato nella colonna ENDPOINT_ID. Utilizza questo ID nel passaggio successivo.

REST

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

  • LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
  • PROJECT_ID: il tuo ID progetto.
  • ENDPOINT_NAME: il nome visualizzato dell'endpoint.

Metodo HTTP e URL: 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "endpoints": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID",
      "displayName": "ENDPOINT_NAME",
      "etag": "AMEw9yPz5pf4PwBHbRWOGh0PcAxUdjbdX2Jm3QO_amguy3DbZGP5Oi_YUKRywIE-BtLx",
      "createTime": "2020-04-17T18:31:11.585169Z",
      "updateTime": "2020-04-17T18:35:08.568959Z"
    }
  ]
}
Prendi nota di ENDPOINT_ID.

Esegui il deployment del modello

Seleziona la scheda di seguito relativa alla tua lingua o al tuo ambiente:

gcloud

I seguenti esempi utilizzano il comando gcloud ai endpoints deploy-model.

L'esempio seguente esegue il deployment di un Model in un Endpoint senza utilizzare GPU per accelerare la fornitura delle previsioni e senza suddividere il traffico tra più DeployedModel risorse:

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • ENDPOINT_ID: l'ID dell'endpoint.
  • LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
  • MODEL_ID: l'ID del modello di cui eseguire il deployment.
  • DEPLOYED_MODEL_NAME: un nome per DeployedModel. Puoi utilizzare il nome visualizzato Model anche per DeployedModel.
  • MACHINE_TYPE: facoltativo. Le risorse macchina utilizzate per ogni nodo e deployment continuo. L'impostazione predefinita è n1-standard-2. Scopri di più sui tipi di macchine.
  • MIN_REPLICA_COUNT: il numero minimo di nodi per questo deployment. Il conteggio dei nodi può essere aumentato o diminuito in base al carico della previsione. fino al numero massimo di nodi e mai meno di questo numero. Questo valore deve essere maggiore o uguale a 1. Se il flag --min-replica-count viene omesso, il valore predefinito è 1.
  • MAX_REPLICA_COUNT: il numero massimo di nodi per questo deployment. Il numero di nodi può essere aumentato o diminuito in base al carico della previsione, fino a questo numero di nodi e mai inferiore al numero minimo di nodi. Se il flag --max-replica-count viene omesso, il numero massimo di nodi viene impostato sul valore di --min-replica-count.

Esegui la gcloud ai endpoint deploy-model :

Linux, macOS o Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=100

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME `
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=100

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME ^
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=100
  

Suddivisione del traffico

Il flag --traffic-split=0=100 negli esempi precedenti invia il 100% della previsione il traffico ricevuto dal Endpoint al nuovo DeployedModel, che rappresentato dall'ID temporaneo 0. Se il tuo Endpoint ha già altre risorse DeployedModel, puoi suddividere il traffico tra il nuovo DeployedModel e quelli precedenti. Ad esempio, per inviare il 20% del traffico al nuovo DeployedModel e l'80% a uno precedente, esegui il seguente comando.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • OLD_DEPLOYED_MODEL_ID: l'ID dell'attuale DeployedModel.

Esegui il comando gcloud ai endpoints deploy-model :

Linux, macOS o Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
  

REST

Utilizza il metodo endpoints.predict per richiedere una previsione online.

Esegui il deployment del modello.

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.
  • MODEL_ID: l'ID del modello di cui eseguire il deployment.
  • DEPLOYED_MODEL_NAME: un nome per DeployedModel. Puoi utilizzare il nome visualizzato Model anche per DeployedModel.
  • MACHINE_TYPE: facoltativo. Le risorse della macchina utilizzate per ogni nodo di questo deployment. L'impostazione predefinita è n1-standard-2. Scopri di più sui tipi di macchina.
  • ACCELERATOR_TYPE: tipo di acceleratore da associare alla macchina. Facoltativa se ACCELERATOR_COUNT non è specificato o è pari a zero. Sconsigliato per Modelli AutoML o modelli addestrati personalizzati che utilizzano immagini non GPU. Scopri di più.
  • ACCELERATOR_COUNT: il numero di acceleratori da utilizzare per ogni replica. Facoltativo. Deve essere pari a zero o non specificato per i modelli AutoML o con addestramento personalizzato che utilizzano immagini non GPU.
  • MIN_REPLICA_COUNT: numero minimo di nodi per questo deployment. Il conteggio dei nodi può essere aumentato o diminuito in base al carico della previsione. fino al numero massimo di nodi e mai meno di questo numero. Questo valore deve essere maggiore o uguale a 1.
  • MAX_REPLICA_COUNT: il numero massimo di nodi per questo deployment. Il conteggio dei nodi può essere aumentato o diminuito in base al carico della previsione. fino a questo numero di nodi e mai meno del numero minimo di nodi.
  • TRAFFIC_SPLIT_THIS_MODEL: la percentuale del traffico di previsione per questo endpoint da inoltrare al modello di cui viene eseguito il deployment con questa operazione. Il valore predefinito è 100. La somma di tutte le percentuali di traffico deve essere pari al 100%. Scopri di più sulle suddivisioni del traffico.
  • DEPLOYED_MODEL_ID_N: facoltativo. Se viene eseguito il deployment di altri modelli su questo endpoint, devono aggiornare le rispettive percentuali di suddivisione del traffico in modo che la somma di tutte le percentuali arrivi a 100.
  • TRAFFIC_SPLIT_MODEL_N: il valore percentuale di suddivisione del traffico per l'ID del modello di cui è stato eseguito il deployment chiave.
  • PROJECT_NUMBER: il numero di progetto generato automaticamente del progetto

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "deployedModel": {
    "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID",
    "displayName": "DEPLOYED_MODEL_NAME",
    "dedicatedResources": {
       "machineSpec": {
         "machineType": "MACHINE_TYPE",
         "acceleratorType": "ACCELERATOR_TYPE",
         "acceleratorCount": "ACCELERATOR_COUNT"
       },
       "minReplicaCount": MIN_REPLICA_COUNT,
       "maxReplicaCount": MAX_REPLICA_COUNT
     },
  },
  "trafficSplit": {
    "0": TRAFFIC_SPLIT_THIS_MODEL,
    "DEPLOYED_MODEL_ID_1": TRAFFIC_SPLIT_MODEL_1,
    "DEPLOYED_MODEL_ID_2": TRAFFIC_SPLIT_MODEL_2
  },
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-10-19T17:53:16.502088Z",
      "updateTime": "2020-10-19T17:53:16.502088Z"
    }
  }
}

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 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.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.DedicatedResources;
import com.google.cloud.aiplatform.v1.DeployModelOperationMetadata;
import com.google.cloud.aiplatform.v1.DeployModelResponse;
import com.google.cloud.aiplatform.v1.DeployedModel;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.MachineSpec;
import com.google.cloud.aiplatform.v1.ModelName;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ExecutionException;

public class DeployModelCustomTrainedModelSample {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String endpointId = "ENDPOINT_ID";
    String modelName = "MODEL_NAME";
    String deployedModelDisplayName = "DEPLOYED_MODEL_DISPLAY_NAME";
    deployModelCustomTrainedModelSample(project, endpointId, modelName, deployedModelDisplayName);
  }

  static void deployModelCustomTrainedModelSample(
      String project, String endpointId, String model, String deployedModelDisplayName)
      throws IOException, ExecutionException, InterruptedException {
    EndpointServiceSettings settings =
        EndpointServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // 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 (EndpointServiceClient client = EndpointServiceClient.create(settings)) {
      MachineSpec machineSpec = MachineSpec.newBuilder().setMachineType("n1-standard-2").build();
      DedicatedResources dedicatedResources =
          DedicatedResources.newBuilder().setMinReplicaCount(1).setMachineSpec(machineSpec).build();

      String modelName = ModelName.of(project, location, model).toString();
      DeployedModel deployedModel =
          DeployedModel.newBuilder()
              .setModel(modelName)
              .setDisplayName(deployedModelDisplayName)
              // `dedicated_resources` must be used for non-AutoML models
              .setDedicatedResources(dedicatedResources)
              .build();
      // key '0' assigns traffic for the newly deployed model
      // Traffic percentage values must add up to 100
      // Leave dictionary empty if endpoint should not accept any traffic
      Map<String, Integer> trafficSplit = new HashMap<>();
      trafficSplit.put("0", 100);
      EndpointName endpoint = EndpointName.of(project, location, endpointId);
      OperationFuture<DeployModelResponse, DeployModelOperationMetadata> response =
          client.deployModelAsync(endpoint, deployedModel, trafficSplit);

      // You can use OperationFuture.getInitialFuture to get a future representing the initial
      // response to the request, which contains information while the operation is in progress.
      System.out.format("Operation name: %s\n", response.getInitialFuture().get().getName());

      // OperationFuture.get() will block until the operation is finished.
      DeployModelResponse deployModelResponse = response.get();
      System.out.format("deployModelResponse: %s\n", deployModelResponse);
    }
  }
}

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 deploy_model_with_dedicated_resources_sample(
    project,
    location,
    model_name: str,
    machine_type: str,
    endpoint: Optional[aiplatform.Endpoint] = None,
    deployed_model_display_name: Optional[str] = None,
    traffic_percentage: Optional[int] = 0,
    traffic_split: Optional[Dict[str, int]] = None,
    min_replica_count: int = 1,
    max_replica_count: int = 1,
    accelerator_type: Optional[str] = None,
    accelerator_count: Optional[int] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    metadata: Optional[Sequence[Tuple[str, str]]] = (),
    sync: bool = True,
):
    """
    model_name: A fully-qualified model resource name or model ID.
          Example: "projects/123/locations/us-central1/models/456" or
          "456" when project and location are initialized or passed.
    """

    aiplatform.init(project=project, location=location)

    model = aiplatform.Model(model_name=model_name)

    # The explanation_metadata and explanation_parameters should only be
    # provided for a custom trained model and not an AutoML model.
    model.deploy(
        endpoint=endpoint,
        deployed_model_display_name=deployed_model_display_name,
        traffic_percentage=traffic_percentage,
        traffic_split=traffic_split,
        machine_type=machine_type,
        min_replica_count=min_replica_count,
        max_replica_count=max_replica_count,
        accelerator_type=accelerator_type,
        accelerator_count=accelerator_count,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        metadata=metadata,
        sync=sync,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    return model

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 la documentazione di riferimento dell'API Node.js di Vertex AI.

Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

const automl = require('@google-cloud/automl');
const client = new automl.v1beta1.AutoMlClient();

/**
 * Demonstrates using the AutoML client to create a model.
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = '[PROJECT_ID]' e.g., "my-gcloud-project";
// const computeRegion = '[REGION_NAME]' e.g., "us-central1";
// const datasetId = '[DATASET_ID]' e.g., "TBL2246891593778855936";
// const tableId = '[TABLE_ID]' e.g., "1991013247762825216";
// const columnId = '[COLUMN_ID]' e.g., "773141392279994368";
// const modelName = '[MODEL_NAME]' e.g., "testModel";
// const trainBudget = '[TRAIN_BUDGET]' e.g., "1000",
// `Train budget in milli node hours`;

// A resource that represents Google Cloud Platform location.
const projectLocation = client.locationPath(projectId, computeRegion);

// Get the full path of the column.
const columnSpecId = client.columnSpecPath(
  projectId,
  computeRegion,
  datasetId,
  tableId,
  columnId
);

// Set target column to train the model.
const targetColumnSpec = {name: columnSpecId};

// Set tables model metadata.
const tablesModelMetadata = {
  targetColumnSpec: targetColumnSpec,
  trainBudgetMilliNodeHours: trainBudget,
};

// Set datasetId, model name and model metadata for the dataset.
const myModel = {
  datasetId: datasetId,
  displayName: modelName,
  tablesModelMetadata: tablesModelMetadata,
};

// Create a model with the model metadata in the region.
client
  .createModel({parent: projectLocation, model: myModel})
  .then(responses => {
    const initialApiResponse = responses[1];
    console.log(`Training operation name: ${initialApiResponse.name}`);
    console.log('Training started...');
  })
  .catch(err => {
    console.error(err);
  });

Scopri come modificare le impostazioni predefinite per la registrazione delle previsioni.

Ottieni stato dell'operazione

Alcune richieste avviano operazioni a lunga esecuzione il cui completamento richiede tempo. Queste richieste restituiscono un nome dell'operazione, che puoi utilizzare per visualizzarne lo stato o annullarla. Vertex AI fornisce metodi di assistenza per effettuare chiamate a operazioni di lunga durata. Per ulteriori informazioni, consulta la sezione Utilizzo di modelli operazioni.

Ottenere una previsione online utilizzando il modello di cui è stato eseguito il deployment

Per fare una previsione online, invia uno o più elementi di test a un modello per e il modello restituisce risultati basati sui dati del modello obiettivo. Utilizza la console Google Cloud o l'API Vertex AI per richiedere un la previsione online.

Console Google Cloud

  1. Nella console Google Cloud, nella sezione Vertex AI, vai a la pagina Modelli.

    Vai alla pagina Modelli

  2. Nell'elenco dei modelli, fai clic sul nome del modello per richiedere previsioni da cui proviene.

  3. Seleziona la scheda Deployment e test.

  4. Nella sezione Testa il modello, aggiungi elementi di test per richiedere un la previsione. I dati di previsione di riferimento sono compilati automaticamente oppure inserire i tuoi dati di previsione e fare clic su Prevedi.

    Una volta completata la previsione, Vertex AI restituisce i risultati in la console.

API: classificazione

gcloud

  1. Crea un file denominato request.json con i seguenti contenuti: 

          {
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

    Sostituisci quanto segue:

    • PREDICTION_DATA_ROW: un oggetto JSON con le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:

      "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

      È necessario specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere al formato utilizzato per l'addestramento. Consulta Formato dei dati per le previsioni per maggiori dettagli.

  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

Utilizza il metodo endpoints.predict per richiedere una previsione online.

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

  • LOCATION_ID: regione in cui si trova l'endpoint. Ad esempio, us-central1.
  • PROJECT_ID: il tuo ID progetto.
  • ENDPOINT_ID: l'ID dell'endpoint.

  • PREDICTION_DATA_ROW: un oggetto JSON con le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:

    "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

    È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere al formato utilizzato per l'addestramento. Consulta Formato dei dati per le previsioni per maggiori dettagli.

  • DEPLOYED_MODEL_ID: output con il metodo predict e accettato come input con il metodo explain. L'ID del modello utilizzato per generare la previsione. Se devi richiedere spiegazioni per una previsione richiesta in precedenza, e hai eseguito il deployment di più modelli, puoi utilizzare questo ID per assicurarti che le spiegazioni vengono restituiti per lo stesso modello che ha fornito la previsione precedente.

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": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

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

$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

Dovresti ricevere una risposta JSON simile alla seguente:

   {
     "predictions": [
      {
         "scores": [
           0.96771615743637085,
           0.032283786684274673
         ],
         "classes": [
           "0",
           "1"
         ]
      }
     ]
     "deployedModelId": "2429510197"
   }

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 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.util.ValueConverter;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.cloud.aiplatform.v1.schema.predict.prediction.TabularClassificationPredictionResult;
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 PredictTabularClassificationSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictTabularClassification(instance, project, endpointId);
  }

  static void predictTabularClassification(String instance, String project, String endpointId)
      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();

      Value parameters = Value.newBuilder().setListValue(listValue).build();
      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instanceList, parameters);
      System.out.println("Predict Tabular Classification Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.getDeployedModelId());

      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        TabularClassificationPredictionResult.Builder resultBuilder =
            TabularClassificationPredictionResult.newBuilder();
        TabularClassificationPredictionResult result =
            (TabularClassificationPredictionResult)
                ValueConverter.fromValue(resultBuilder, prediction);

        for (int i = 0; i < result.getClassesCount(); i++) {
          System.out.printf("\tClass: %s", result.getClasses(i));
          System.out.printf("\tScore: %f", result.getScores(i));
        }
      }
    }
  }
}

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 la documentazione di riferimento dell'API Node.js 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. 

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const endpointId = 'YOUR_ENDPOINT_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const aiplatform = require('@google-cloud/aiplatform');
const {prediction} =
  aiplatform.protos.google.cloud.aiplatform.v1.schema.predict;

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = 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 predictTablesClassification() {
  // Configure the endpoint resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = helpers.toValue({});

  const instance = helpers.toValue({
    petal_length: '1.4',
    petal_width: '1.3',
    sepal_length: '5.1',
    sepal_width: '2.8',
  });

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict tabular classification response');
  console.log(`\tDeployed model id : ${response.deployedModelId}\n`);
  const predictions = response.predictions;
  console.log('Predictions :');
  for (const predictionResultVal of predictions) {
    const predictionResultObj =
      prediction.TabularClassificationPredictionResult.fromValue(
        predictionResultVal
      );
    for (const [i, class_] of predictionResultObj.classes.entries()) {
      console.log(`\tClass: ${class_}`);
      console.log(`\tScore: ${predictionResultObj.scores[i]}\n\n`);
    }
  }
}
predictTablesClassification();

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 predict_tabular_classification_sample(
    project: str,
    location: str,
    endpoint_name: str,
    instances: List[Dict],
):
    """
    Args
        project: Your project ID or project number.
        location: Region where Endpoint is located. For example, 'us-central1'.
        endpoint_name: A fully qualified endpoint name or endpoint ID. Example: "projects/123/locations/us-central1/endpoints/456" or
               "456" when project and location are initialized or passed.
        instances: A list of one or more instances (examples) to return a prediction for.
    """
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_name)

    response = endpoint.predict(instances=instances)

    for prediction_ in response.predictions:
        print(prediction_)

API: regressione

gcloud

  1. Crea un file denominato "request.json" con i seguenti contenuti: 

          {
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

    Sostituisci quanto segue:

    • PREDICTION_DATA_ROW: un oggetto JSON con le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di numeri e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:

      "age":3.6,
"sq_ft":5392,
"code": "90331"

      È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Consulta Formato dei dati per le previsioni per maggiori dettagli.

  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

Utilizza il metodo endpoints.predict per richiedere una previsione online.

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

  • LOCATION_ID: regione in cui si trova l'endpoint. Ad esempio, us-central1.
  • PROJECT_ID: il tuo ID progetto.
  • ENDPOINT_ID: l'ID dell'endpoint.

  • PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi delle funzionalità e valori come i valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con un numero, un array di numeri e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:

    "age":3.6,
"sq_ft":5392,
"code": "90331"

    È necessario specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Consulta Formato dei dati per le previsioni per maggiori dettagli.

  • DEPLOYED_MODEL_ID: output con il metodo predict e accettato come input con il metodo explain. L'ID del modello utilizzato per generare la previsione. Se devi richiedere spiegazioni per una previsione richiesta in precedenza e hai implementato più di un modello, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per lo stesso modello che ha fornito la previsione precedente.

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": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

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

Dovresti ricevere una risposta JSON simile alla seguente:


{
  "predictions": [
    [
      {
        "value": 65.14233
      }
    ]
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Vertex AI.

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.util.ValueConverter;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.cloud.aiplatform.v1.schema.predict.prediction.TabularRegressionPredictionResult;
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 PredictTabularRegressionSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictTabularRegression(instance, project, endpointId);
  }

  static void predictTabularRegression(String instance, String project, String endpointId)
      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();

      Value parameters = Value.newBuilder().setListValue(listValue).build();
      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instanceList, parameters);
      System.out.println("Predict Tabular Regression Response");
      System.out.format("\tDisplay Model Id: %s\n", predictResponse.getDeployedModelId());

      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        TabularRegressionPredictionResult.Builder resultBuilder =
            TabularRegressionPredictionResult.newBuilder();

        TabularRegressionPredictionResult result =
            (TabularRegressionPredictionResult) ValueConverter.fromValue(resultBuilder, prediction);

        System.out.printf("\tUpper bound: %f\n", result.getUpperBound());
        System.out.printf("\tLower bound: %f\n", result.getLowerBound());
        System.out.printf("\tValue: %f\n", result.getValue());
      }
    }
  }
}

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 endpointId = 'YOUR_ENDPOINT_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const aiplatform = require('@google-cloud/aiplatform');
const {prediction} =
  aiplatform.protos.google.cloud.aiplatform.v1.schema.predict;

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = 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 predictTablesRegression() {
  // Configure the endpoint resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = helpers.toValue({});

  // TODO (erschmid): Make this less painful
  const instance = helpers.toValue({
    BOOLEAN_2unique_NULLABLE: false,
    DATETIME_1unique_NULLABLE: '2019-01-01 00:00:00',
    DATE_1unique_NULLABLE: '2019-01-01',
    FLOAT_5000unique_NULLABLE: 1611,
    FLOAT_5000unique_REPEATED: [2320, 1192],
    INTEGER_5000unique_NULLABLE: '8',
    NUMERIC_5000unique_NULLABLE: 16,
    STRING_5000unique_NULLABLE: 'str-2',
    STRUCT_NULLABLE: {
      BOOLEAN_2unique_NULLABLE: false,
      DATE_1unique_NULLABLE: '2019-01-01',
      DATETIME_1unique_NULLABLE: '2019-01-01 00:00:00',
      FLOAT_5000unique_NULLABLE: 1308,
      FLOAT_5000unique_REPEATED: [2323, 1178],
      FLOAT_5000unique_REQUIRED: 3089,
      INTEGER_5000unique_NULLABLE: '1777',
      NUMERIC_5000unique_NULLABLE: 3323,
      TIME_1unique_NULLABLE: '23:59:59.999999',
      STRING_5000unique_NULLABLE: 'str-49',
      TIMESTAMP_1unique_NULLABLE: '1546387199999999',
    },
    TIMESTAMP_1unique_NULLABLE: '1546387199999999',
    TIME_1unique_NULLABLE: '23:59:59.999999',
  });

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict tabular regression response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const predictionResultVal of predictions) {
    const predictionResultObj =
      prediction.TabularRegressionPredictionResult.fromValue(
        predictionResultVal
      );
    console.log(`\tUpper bound: ${predictionResultObj.upper_bound}`);
    console.log(`\tLower bound: ${predictionResultObj.lower_bound}`);
    console.log(`\tLower bound: ${predictionResultObj.value}`);
  }
}
predictTablesRegression();

Python

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

def predict_tabular_regression_sample(
    project: str,
    location: str,
    endpoint_name: str,
    instances: List[Dict],
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_name)

    response = endpoint.predict(instances=instances)

    for prediction_ in response.predictions:
        print(prediction_)

Interpretare i risultati delle previsioni

Classificazione

I modelli di classificazione restituiscono un punteggio di affidabilità.

Il punteggio di confidenza indica il livello di associazione di ogni modello una classe o un'etichetta con un elemento di test. Più alto è il numero, più alto è il valore con la certezza che l'etichetta deve essere applicata all'elemento. Sei tu a decidere quanto in alto il punteggio di confidenza deve consentire l'accettazione dei risultati del modello.

Regressione

I modelli di regressione restituiscono un valore di previsione.

Se il tuo modello utilizza l'inferenza probabilistica, il campo value contiene il parametro minimizzando l'obiettivo di ottimizzazione. Ad esempio, se la tua ottimizzazione l'obiettivo è minimize-rmse, il campo value contiene il valore medio. Se è minimize-mae, il campo value contiene il valore mediano.

Se il tuo modello utilizza l'inferenza probabilistica con i quantili, Vertex AI fornisce valori dei quantili e previsioni oltre al minimo obiettivo di ottimizzazione. I valori quantili vengono impostati durante l'addestramento del modello. Le predizioni quantili sono i valori di previsione associati ai valori quantili.

Ricevi una spiegazione online utilizzando il modello di cui hai eseguito il deployment

Puoi richiedere una previsione con spiegazioni (chiamate anche attribuzioni delle caratteristiche) per vedere in che modo il modello è arrivato a una previsione. La funzionalità locale i valori di importanza indicano in che misura ciascuna caratteristica ha contribuito alla previsione o il risultato finale. Le attribuzioni delle caratteristiche sono incluse nelle previsioni di Vertex AI tramite Vertex Explainable AI.

Console

Quando utilizzi la console Google Cloud per richiedere una previsione online, i valori dell'importanza delle funzionalità locali vengono restituiti automaticamente.

Se hai utilizzato i valori di previsione precompilati, i valori dell'importanza delle funzionalità locali sono tutti pari a zero. Questo perché i valori precompilati rappresentano la base di riferimento i dati di previsione, quindi la previsione restituita è il valore della previsione di riferimento.

gcloud

  1. Crea un file denominato request.json con il seguente contenuto:

    {
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

    Sostituisci quanto segue:

    • PREDICTION_DATA_ROW: un oggetto JSON con le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:

      "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

      È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere al formato utilizzato per l'addestramento. Per informazioni dettagliate, consulta Formato dei dati per le previsioni.

  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 vuoi ricevere le spiegazioni. L'ID è incluso nella risposta del metodo predict. Per 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

L'esempio riportato di seguito mostra una richiesta di previsione online per un modello di classificazione tabulare con attribuzioni delle caratteristiche locali. Il formato della richiesta è lo stesso per i modelli di regressione.

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

  • LOCATION: regione in cui si trova l'endpoint. Ad esempio, us-central1.
  • PROJECT: il tuo ID progetto.
  • ENDPOINT_ID: l'ID dell'endpoint.

  • PREDICTION_DATA_ROW: un oggetto JSON con le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:

    "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

    È necessario specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per informazioni dettagliate, consulta Formato dei dati per le previsioni.

  • DEPLOYED_MODEL_ID (facoltativo): l'ID del modello di cui vuoi ottenere 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.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/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-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
 

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_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)

Ricevere spiegazioni per una previsione restituita in precedenza

Poiché le spiegazioni aumentano l'utilizzo delle risorse, ti consigliamo di prenotare richiedere spiegazioni per le situazioni in cui ti servono specificamente. A volte può essere utile richiedere spiegazioni per un risultato di previsione che hai già ricevuto, ad esempio perché la previsione era un outlier o non aveva senso.

Se tutte le previsioni provengono dallo stesso modello, puoi semplicemente inviare di nuovo i dati della richiesta, con le spiegazioni richieste questa volta. Tuttavia, se hai più modelli che restituiscono previsioni, devi assicurarti di inviare la richiesta di spiegazione al modello corretto. Puoi visualizzare le spiegazioni per un del modello specifico includendo l'ID deployedModelID del modello di cui hai eseguito il deployment , che è incluso nella risposta della richiesta di previsione originale. Tieni presente che l'ID del modello di cui è stato eseguito il deployment è diverso dall'ID modello.

Interpreta i risultati della spiegazione

Per calcolare l'importanza locale delle caratteristiche, prima la previsione di riferimento automaticamente. I valori di riferimento vengono calcolati a partire dall'addestramento utilizzando il valore mediano per le caratteristiche numeriche e la modalità caratteristiche categoriche. La previsione generata dai valori di riferimento è il punteggio di previsione di riferimento. I valori di riferimento vengono calcolati una volta per un modello e non cambiano.

Per una previsione specifica, l'importanza locale della caratteristica per ogni caratteristica indica quanto la caratteristica ha aggiunto o sottratto al risultato rispetto al punteggio di previsione di riferimento. La somma di tutti i valori di importanza delle caratteristiche è uguale alla differenza tra il punteggio di base e il risultato della previsione.

Per i modelli di classificazione, il punteggio è sempre compreso tra 0,0 e 1,0, compreso. Pertanto, i valori di importanza delle caratteristiche locali per i modelli di classificazione sono sempre compresi tra -1,0 e 1,0 (inclusi).

Per esempi di query di attribuzione delle caratteristiche e per saperne di più, consulta Attribuzioni delle caratteristiche per la classificazione e la regressione.

Esempio di output per previsioni e spiegazioni

Classificazione

Il payload restituito per una previsione online da un modello di classificazione tabulare con importanza delle caratteristiche è simile a questo esempio.

Il instanceOutputValue di 0.928652400970459 è di confidenza della classe con il punteggio più alto, in questo caso class_a. Il campo baselineOutputValue contiene il punteggio di previsione di base, 0.808652400970459. La funzionalità ha contribuito maggiormente a questo risultato è stato feature_3.

{
"predictions": [
  {
    "scores": [
      0.928652400970459,
      0.071347599029541
    ],
    "classes": [
      "class_a",
      "class_b"
    ]
  }
]
"explanations": [
  {
    "attributions": [
      {
        "baselineOutputValue": 0.808652400970459,
        "instanceOutputValue": 0.928652400970459,
        "approximationError":  0.0058915703929231,
        "featureAttributions": {
          "feature_1": 0.012394922231235,
          "feature_2": 0.050212341234556,
          "feature_3": 0.057392736534209,
        },
        "outputIndex": [
          0
        ],
        "outputName": "scores"
      }
    ],
  }
]
"deployedModelId": "234567"
}

Regressione

Il payload restituito per una previsione online con importanza delle caratteristiche da un modello di regressione tabulare è simile a questo esempio.

Il instanceOutputValue di 1795.1246466281819 è il valore previsto. Il campo baselineOutputValue contiene il punteggio di previsione di base, 1788.7423095703125. La funzionalità ha contribuito maggiormente a questo risultato è stato feature_3.

{
"predictions": [
  {
    "value": 1795.1246466281819
  }
]
"explanations": [
  {
    "attributions": [
      {
        "baselineOutputValue": 1788.7423095703125,
        "instanceOutputValue": 1795.1246466281819,
        "approximationError": 0.0038215703911553,
        "featureAttributions": {
          "feature_1": 0.123949222312359,
          "feature_2": 0.802123412345569,
          "feature_3": 5.456264423211472,
        },
        "outputIndex": [
          -1
        ]
      }
    ]
  }
],
"deployedModelId": "345678"
}

Passaggi successivi