Generazione di inferenze online per i modelli AutoML

Questa pagina mostra come ottenere spiegazioni e inferenze online (in tempo reale) dai modelli di classificazione o regressione tabulare AutoML addestrati utilizzando la console Google Cloud o l'API Agent Platform.

Un'inferenza online è una richiesta sincrona, a differenza di un'inferenza batch, che è una richiesta asincrona. Utilizza le inferenze 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 utilizzare per fornire inferenze online. Il deployment di un modello associa le risorse fisiche al modello in modo che possa fornire inferenze online con bassa latenza.

Gli argomenti trattati sono:

  1. Esegui il deployment di un modello su un endpoint
  2. Ottenere un'inferenza online utilizzando il modello di cui hai eseguito il deployment
  3. Ottieni una spiegazione online utilizzando il modello di cui hai eseguito il deployment

Prima di iniziare

Prima di poter ottenere inferenze online, devi addestrare un modello di classificazione o regressione e valutarne l'accuratezza.

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ù endpoint. Per saperne di più sulle opzioni e sui casi d'uso per il deployment dei modelli, consulta Informazioni sul deployment dei modelli.

Utilizza uno dei seguenti metodi per eseguire il deployment di un modello:

Console Google Cloud

  1. Nella console Google Cloud , nella sezione Agent Platform, vai alla 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 hai già eseguito il deployment del modello in un endpoint, questo viene elencato nella sezione Esegui il deployment del modello.

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

  5. Nella pagina Definisci il tuo endpoint, configura quanto 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 fornisci 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 puoi aggiungere un modello a più di un endpoint. Scopri di più.

    2. Fai clic su Continua.

  6. Nella pagina Impostazioni del modello, configura quanto 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 è stato eseguito il deployment di uno o più modelli, devi aggiornare la percentuale di Suddivisione del traffico per il modello di cui stai eseguendo il deployment e per i modelli di cui è già stato eseguito il deployment in modo che la somma di tutte le percentuali sia pari al 100%.

    2. Inserisci il Numero minimo di nodi di computing che vuoi fornire per il tuo modello.

      Questo è il numero di nodi sempre disponibili per questo modello. Ti vengono addebitati i costi per i nodi utilizzati, sia per gestire il carico di inferenza sia per i nodi in standby (minimo), anche senza traffico di inferenza. Consulta la pagina dei prezzi.

    3. Seleziona il tipo di macchina.

      Risorse della macchina più grandi aumenteranno le prestazioni di inferenza e i costi.

    4. Scopri come modificare le impostazioni predefinite per il logging delle inferenze.

    5. Fai clic su Continua.

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

  8. Nella pagina Obiettivi di monitoraggio, configura quanto segue:

    1. Inserisci la posizione 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 sull'endpoint.

API

Quando esegui il deployment di un modello utilizzando l'API Agent Platform, devi completare i seguenti passaggi:

  1. Se necessario, crea un endpoint.
  2. Recupera l'ID endpoint.
  3. Esegui 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 Agent Platform.

  • ENDPOINT_NAME: il nome visualizzato dell'endpoint.

    La creazione dell'endpoint da parte dello strumento Google Cloud CLI potrebbe richiedere alcuni secondi.

REST

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

  • 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 di queste 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 dello stato dell'operazione finché la risposta non include "done": true.

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta 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 di Node.js nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta 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 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 Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la 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

L'esempio seguente utilizza 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 Agent Platform.

  • 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 sostituzioni seguenti:

  • LOCATION_ID: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: .
  • 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 di queste 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"
    }
  ]
}
Nota ENDPOINT_ID.

Esegui il deployment del modello

Seleziona la scheda di seguito per la tua lingua o il 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 distribuzione delle previsioni e senza suddividere il traffico tra più risorse DeployedModel:

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 utilizzi Agent Platform.
  • MODEL_ID: l'ID del modello di cui eseguire il deployment.
  • DEPLOYED_MODEL_NAME: un nome per DeployedModel. Puoi anche utilizzare il nome visualizzato di Model 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.
  • MIN_REPLICA_COUNT: il numero minimo di nodi per questo deployment. Il conteggio di nodi può essere aumentato o diminuito in base al carico di inferenza fino al numero massimo di nodi, ma non scenderà mai al di sotto di questo numero. Questo valore deve essere maggiore o uguale a 1. Se il flag --min-replica-count viene omesso, il valore predefinito sarà 1.
  • MAX_REPLICA_COUNT: il numero massimo di nodi per questo deployment. Il conteggio di nodi può essere aumentato o diminuito in base al carico di inferenza fino a questo numero di nodi, ma non scenderà mai al di sotto del 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 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=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% del traffico di previsione ricevuto da Endpoint al nuovo DeployedModel, rappresentato dall'ID temporaneo 0. Se il tuo Endpoint ha già altre risorse DeployedModel, puoi suddividere il traffico tra la nuova risorsa DeployedModel e quelle precedenti. Ad esempio, per inviare il 20% del traffico alla nuova DeployedModel e l'80% a una versione precedente, esegui questo comando.

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

  • OLD_DEPLOYED_MODEL_ID: l'ID della risorsa DeployedModel esistente.

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 un'inferenza online.

Esegui il deployment del modello.

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

  • LOCATION_ID: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: .
  • 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 anche utilizzare il nome visualizzato di Model 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: il tipo di acceleratore da collegare alla macchina. Facoltativo se ACCELERATOR_COUNT non è specificato o è pari a zero. Non consigliato per i modelli AutoML o i modelli con addestramento personalizzato 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 i modelli con addestramento personalizzato che utilizzano immagini non GPU.
  • MIN_REPLICA_COUNT: il numero minimo di nodi per questo deployment. Il conteggio di nodi può essere aumentato o diminuito in base al carico di inferenza fino al numero massimo di nodi, ma non scenderà mai al di sotto 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 di nodi può essere aumentato o diminuito in base al carico di inferenza fino a questo numero di nodi, ma non scenderà mai al di sotto del numero minimo di nodi.
  • REQUIRED_REPLICA_COUNT: (Facoltativo) Il numero di nodi richiesto affinché questo deployment venga contrassegnato come riuscito. Deve essere maggiore o uguale a 1 e minore o uguale al numero minimo di nodi. Se non specificato, il valore predefinito è il numero minimo di nodi.
  • TRAFFIC_SPLIT_THIS_MODEL: la percentuale del traffico di previsione verso questo endpoint da instradare 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 a 100. Scopri di più sulle suddivisioni del traffico.
  • DEPLOYED_MODEL_ID_N: (Facoltativo) Se su questo endpoint è stato eseguito il deployment di altri modelli, devi aggiornare le relative percentuali di suddivisione del traffico in modo che la somma di tutte le percentuali sia pari a 100.
  • TRAFFIC_SPLIT_MODEL_N: il valore percentuale della suddivisione del traffico per la chiave ID del modello di cui è stato eseguito il deployment.
  • PROJECT_NUMBER: il numero di progetto generato automaticamente per il tuo 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,
       "requiredReplicaCount": REQUIRED_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 di queste 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 di configurazione di Java nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta 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 Python, consulta Installa l'SDK Vertex AI 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

Scopri come modificare le impostazioni predefinite per il logging delle inferenze.

Ottieni lo stato di attività

Alcune richieste avviano operazioni a lunga esecuzione che richiedono tempo per essere completate. Queste richieste restituiscono un nome di operazione, che puoi utilizzare per visualizzare lo stato dell'operazione o annullarla. Agent Platform fornisce metodi helper per effettuare chiamate per operazioni a lunga esecuzione. Per saperne di più, consulta Utilizzo di operazioni a lunga esecuzione.

Ottieni un'inferenza online utilizzando il modello di cui hai eseguito il deployment

Per eseguire un'inferenza online, invia uno o più elementi di test a un modello per l'analisi. Il modello restituisce i risultati in base all'obiettivo del modello. Utilizza la console Google Cloud o l'API Agent Platform per richiedere un'inferenza online.

Console Google Cloud

  1. Nella console Google Cloud , nella sezione Agent Platform, vai alla pagina Modelli.

    Vai alla pagina Modelli

  2. Nell'elenco dei modelli, fai clic sul nome del modello da cui richiedere le inferenze.

  3. Seleziona la scheda Deployment e test.

  4. Nella sezione Testa il tuo modello, aggiungi elementi di test per richiedere un'inferenza. I dati di inferenza di riferimento vengono compilati automaticamente oppure puoi inserire i tuoi dati di inferenza e fare clic su Prevedi.

    Al termine dell'inferenza, Gemini Enterprise Agent Platform restituisce i risultati nella 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 chiavi come nomi delle caratteristiche e valori come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con tre caratteristiche (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 l'inferenza deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le inferenze.

  2. Esegui questo comando:

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

    Sostituisci quanto segue:

    • ENDPOINT_ID: l'ID dell'endpoint.
    • LOCATION_ID: la regione in cui utilizzi Agent Platform.

REST

Utilizza il metodo endpoints.predict per richiedere un'inferenza online.

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

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

  • PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi delle caratteristiche e valori come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con tre caratteristiche (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 l'inferenza deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le inferenze.

  • DEPLOYED_MODEL_ID: l'output del metodo predict, accettato come input dal metodo explain. L'ID del modello utilizzato per generare l'inferenza. Se devi richiedere spiegazioni per un'inferenza richiesta in precedenza e hai eseguito il deployment di più modelli, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per lo stesso modello che ha fornito l'inferenza 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 di queste opzioni:

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID: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 di configurazione di Java nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta 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 {
    PredictionServicPredictionServiceSettingsceSettings =
        PredictionServicPredictionServiceSettings          .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 (PredictionServicPredictionServiceClientceClient =
        PredictionServicPredictionServiceClientonServiceSettings)) {
      String location = "us-central1";
      EndpointName endEndpointNameEndpointName.of(EndpointNameation, endpointId);

      ListValue.BuildeListValueue = ListValue.newBuiListValue     JsonFormat.parseJsonFormatinstance, listValue);
      List<Value> instanListValuelistValue.getValuesList();

      Value parametersValuelue.newBuilderValuetListValue(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.predictResponse.getDeployedModelId().out.println("Predictions");
      for (Value predictionValueedictResponse.predictResponse.getPredictionsList()larClassificTabularClassificationPredictionResultuilder =
            TabularClassificTabularClassificationPredictionResult       TabularClassificTabularClassificationPredictionResult      (TabularClassificTabularClassificationPredictionResult  ValueConverter.fValueConvertertBuilder, prediction);

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

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta 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 Python, consulta Installa l'SDK Vertex AI 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 chiavi come nomi delle caratteristiche e valori come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con tre caratteristiche (un numero, un array di numeri e una categoria), la riga di dati potrebbe avere il seguente aspetto:

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

      È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per l'inferenza deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le inferenze.

  2. Esegui questo comando:

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

    Sostituisci quanto segue:

    • ENDPOINT_ID: l'ID dell'endpoint.
    • LOCATION_ID: la regione in cui utilizzi Agent Platform.

REST

Utilizza il metodo endpoints.predict per richiedere un'inferenza online.

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

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

  • PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi delle caratteristiche e valori come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con tre caratteristiche (un numero, un array di numeri e una categoria), la riga di dati potrebbe avere il seguente aspetto:

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

    È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per l'inferenza deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le inferenze.

  • DEPLOYED_MODEL_ID: l'output del metodo predict, accettato come input dal metodo explain. L'ID del modello utilizzato per generare l'inferenza. Se devi richiedere spiegazioni per un'inferenza richiesta in precedenza e hai eseguito il deployment di più modelli, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per lo stesso modello che ha fornito l'inferenza 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 di queste opzioni:

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID: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": [
    [
      {
        "value": 65.14233,
        "lower_bound": 4.6572,
        "upper_bound": 164.0279
      }
    ]
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta 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 {
    PredictionServicPredictionServiceSettingsceSettings =
        PredictionServicPredictionServiceSettings          .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 (PredictionServicPredictionServiceClientceClient =
        PredictionServicPredictionServiceClientonServiceSettings)) {
      String location = "us-central1";
      EndpointName endEndpointNameEndpointName.of(EndpointNameation, endpointId);

      ListValue.BuildeListValueue = ListValue.newBuiListValue     JsonFormat.parseJsonFormatinstance, listValue);
      List<Value> instanListValuelistValue.getValuesList();

      Value parametersValuelue.newBuilderValuetListValue(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.predictResponse.getDeployedModelId().out.println("Predictions");
      for (Value predictionValueedictResponse.predictResponse.getPredictionsList()larRegressioTabularRegressionPredictionResultuilder =
            TabularRegressioTabularRegressionPredictionResult        TabularRegressioTabularRegressionPredictionResult      (TabularRegressioTabularRegressionPredictionResult.fValueConvertertBuilder, prediction);

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

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta 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 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 Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la 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_)

Interpreta i risultati delle previsioni

Classificazione

I modelli di classificazione restituiscono un punteggio di affidabilità.

Il punteggio di affidabilità indica quanto il modello associa ogni classe o etichetta a un elemento di test. Più alto è il numero, maggiore è l'affidabilità del modello che l'etichetta debba essere applicata a quell'elemento. Sei tu a decidere quanto deve essere alto il punteggio di affidabilità per accettare i risultati del modello.

Regressione

I modelli di regressione restituiscono un valore di inferenza. Per le destinazioni BigQuery, restituiscono anche un intervallo di inferenza. L'intervallo di inferenza fornisce un intervallo di valori che il modello ha una confidenza del 95% che contenga il risultato effettivo.

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

Puoi richiedere un'inferenza con spiegazioni (chiamate anche attribuzioni delle caratteristiche) per vedere come il modello è arrivato a un'inferenza. I valori di importanza delle caratteristiche locali indicano in che misura ciascuna caratteristica ha contribuito al risultato dell'inferenza. Le attribuzioni delle caratteristiche sono incluse nelle inferenze di Agent Platform tramite Vertex Explainable AI.

Console

Quando utilizzi la console Google Cloud per richiedere un'inferenza online, vengono restituiti automaticamente i valori di importanza delle caratteristiche locali.

Se hai utilizzato i valori di previsione precompilati, i valori di importanza delle caratteristiche locali sono tutti pari a zero. Questo perché i valori precompilati sono i dati di previsione di riferimento, quindi la previsione restituita è il valore di previsione di riferimento.

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 chiavi come nomi delle caratteristiche e valori come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con tre caratteristiche (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 l'inferenza deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le inferenze.

  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 utilizzi Agent Platform.

    Facoltativamente, se vuoi inviare una richiesta di spiegazione a un DeployedModel specifico su 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 è stato eseguito il deployment per cui 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 nello stesso endpoint, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per quel modello specifico.

REST

L'esempio seguente mostra una richiesta di inferenza 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, apporta le sostituzioni seguenti:

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

  • PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi delle caratteristiche e valori come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con tre caratteristiche (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 l'inferenza deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le inferenze.

  • DEPLOYED_MODEL_ID (facoltativo): l'ID del modello di cui è stato eseguito il deployment per cui 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 nello stesso endpoint, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per quel modello specifico.

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 di queste 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, 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-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 Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la 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)

Ottieni spiegazioni per una previsione restituita in precedenza

Poiché le spiegazioni aumentano l'utilizzo delle risorse, ti consigliamo di richiederle solo quando ne hai effettivamente bisogno. A volte può essere utile richiedere spiegazioni per un risultato di inferenza che hai già ricevuto, ad esempio perché l'inferenza era un outlier o non aveva senso.

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

Interpreta i risultati della spiegazione

Per calcolare l'importanza delle caratteristiche locali, viene prima calcolato il punteggio di inferenza di riferimento. I valori di riferimento vengono calcolati dai dati di addestramento, utilizzando il valore mediano per le caratteristiche numeriche e la modalità per le caratteristiche categoriche. L'inferenza generata dai valori di riferimento è il punteggio di inferenza di riferimento. I valori di riferimento vengono calcolati una volta per un modello e non cambiano.

Per un'inferenza specifica, l'importanza delle caratteristiche locali per ciascuna caratteristica indica quanto questa ha aggiunto o sottratto al risultato rispetto al punteggio di inferenza di riferimento. La somma di tutti i valori di importanza delle caratteristiche è uguale alla differenza tra il punteggio di inferenza di riferimento e il risultato dell'inferenza.

Per i modelli di classificazione, il punteggio è sempre compreso tra 0,0 e 1,0, inclusi. 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 classificazione e regressione.

Output di esempio per inferenze e spiegazioni

Classificazione

Il payload restituito per un'inferenza online da un modello di classificazione tabulare con importanza delle caratteristiche è simile al seguente esempio.

Il valore instanceOutputValue di 0.928652400970459 è il punteggio di affidabilità della classe con il punteggio più alto, in questo caso class_a. Il campo baselineOutputValue contiene il punteggio di inferenza di riferimento, 0.808652400970459. La caratteristica che ha contribuito di più a questo risultato è 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 un'inferenza online con importanza delle caratteristiche da un modello di regressione tabulare AutoML è simile al seguente esempio.

instanceOutputValue di 1795.1246466281819 è il valore previsto. I campi lower_bound e upper_bound forniscono un intervallo di affidabilità del 95%. Il campo baselineOutputValue contiene il punteggio di inferenza di riferimento, 1788.7423095703125. La caratteristica che ha contribuito di più a questo risultato è feature_3.

{
"predictions": [
  {
    "value": 1795.1246466281819,
    "lower_bound": 246.32196807861328,
    "upper_bound": 8677.51904296875
  }
]
"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