Questa pagina è stata tradotta dall'API Cloud Translation.

Esportare i modelli tabulari AutoML

Questa pagina descrive come utilizzare Vertex AI per esportare il modello tabulare AutoML in Cloud Storage, scaricarlo su un server on-premise o su un server ospitato da un altro provider cloud e poi utilizzare Docker per renderlo disponibile per le previsioni.

Per informazioni sull'esportazione di modelli Edge di immagini e video, consulta Esportare i modelli AutoML Edge.

Dopo aver esportato il modello tabulare, se vuoi importarlo di nuovo in Vertex AI, consulta Importare modelli in Vertex AI.

Limitazioni

L'esportazione dei modelli tabulari AutoML presenta le seguenti limitazioni:

Puoi esportare solo i modelli di classificazione e regressione tabulari AutoML. L'esportazione dei modelli di previsione tabulari AutoML non è supportata.
Vertex Explainable AI non è disponibile con i modelli tabulari esportati. Se devi utilizzare Vertex Explainable AI, devi pubblicare le previsioni da un modello ospitato da Vertex AI.
Il modello tabulare esportato può essere eseguito solo su CPU con architettura x86 che supportano gli insiemi di istruzioni AVX (Advanced Vector Extensions).

Processo di esportazione

I passaggi per esportare il modello sono:

Configura l'ambiente.
Esporta il modello.
Esegui il pull e l'esecuzione del server del modello.
Richiedi previsioni.

Prima di iniziare

Prima di poter completare questa attività, devi aver completato le seguenti attività:

Configura il progetto come descritto in Configurare un progetto e un ambiente di sviluppo.
Addestrare il modello che vuoi scaricare.
Installa e inizializza Google Cloud CLI sul server che utilizzerai per eseguire il modello esportato.
Installa Docker sul tuo server.

Esporta il modello

Console

Nella console Google Cloud, nella sezione Vertex AI, vai alla pagina Modelli.

Vai alla pagina Modelli
Fai clic sul modello tabulare da esportare per aprire la relativa pagina dei dettagli.
Fai clic su Esporta nella barra dei pulsanti per esportare il modello.
Seleziona o crea una cartella Cloud Storage nella posizione che preferisci.

Il bucket deve soddisfare i requisiti dei bucket.

Non puoi esportare un modello in un bucket di primo livello. Devi utilizzare almeno un livello di cartella.

Per risultati ottimali, crea una nuova cartella vuota. Dovrai copiare l'intero contenuto della cartella in un passaggio successivo.
Fai clic su Esporta.

Nella sezione successiva scaricherai il modello esportato sul tuo server.

REST

Utilizza il metodo models.export per esportare un modello in Cloud Storage.

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

LOCATION: la tua regione.
PROJECT: il tuo ID progetto.
MODEL_ID: l'ID del modello da esportare.
GCS_DESTINATION : la cartella di destinazione in Cloud Storage. Ad esempio, gs://export-bucket/exports.
Non puoi esportare un modello in un bucket di primo livello. Devi utilizzare almeno un livello di cartella.

La cartella deve essere conforme ai requisiti dei bucket.

Per risultati ottimali, crea una nuova cartella. Dovrai copiare l'intero contenuto della cartella in un passaggio successivo.

Metodo HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID:export

Corpo JSON della richiesta:

{
  "outputConfig": {
    "exportFormatId": "tf-saved-model",
    "artifactDestination": {
      "outputUriPrefix": "GCS_DESTINATION"
    }
  }
}

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/models/MODEL_ID:export"

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/models/MODEL_ID:export" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.ExportModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-10-12T20:53:40.130785Z",
      "updateTime": "2020-10-12T20:53:40.130785Z"
    },
    "outputInfo": {
      "artifactOutputUri": "gs://OUTPUT_BUCKET/model-MODEL_ID/EXPORT_FORMAT/YYYY-MM-DDThh:mm:ss.sssZ"
    }
  }
}

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 autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.ExportModelOperationMetadata;
import com.google.cloud.aiplatform.v1.ExportModelRequest;
import com.google.cloud.aiplatform.v1.ExportModelResponse;
import com.google.cloud.aiplatform.v1.GcsDestination;
import com.google.cloud.aiplatform.v1.ModelName;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ExportModelTabularClassificationSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String gcsDestinationOutputUriPrefix = "gs://your-gcs-bucket/destination_path";
    String project = "YOUR_PROJECT_ID";
    String modelId = "YOUR_MODEL_ID";
    exportModelTableClassification(gcsDestinationOutputUriPrefix, project, modelId);
  }

  static void exportModelTableClassification(
      String gcsDestinationOutputUriPrefix, String project, String modelId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.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 (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";
      ModelName modelName = ModelName.of(project, location, modelId);

      GcsDestination.Builder gcsDestination = GcsDestination.newBuilder();
      gcsDestination.setOutputUriPrefix(gcsDestinationOutputUriPrefix);
      ExportModelRequest.OutputConfig outputConfig =
          ExportModelRequest.OutputConfig.newBuilder()
              .setExportFormatId("tf-saved-model")
              .setArtifactDestination(gcsDestination)
              .build();

      OperationFuture<ExportModelResponse, ExportModelOperationMetadata> exportModelResponseFuture =
          modelServiceClient.exportModelAsync(modelName, outputConfig);
      System.out.format(
          "Operation name: %s\n", exportModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      ExportModelResponse exportModelResponse =
          exportModelResponseFuture.get(300, TimeUnit.SECONDS);
      System.out.format(
          "Export Model Tabular Classification Response: %s", exportModelResponse.toString());
    }
  }
}

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 autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori 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 gcsDestinationOutputUriPrefix ='YOUR_GCS_DESTINATION_\
// OUTPUT_URI_PREFIX'; eg. "gs://<your-gcs-bucket>/destination_path"
// const modelId = 'YOUR_MODEL_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

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

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

// Instantiates a client
const modelServiceClient = new ModelServiceClient(clientOptions);

async function exportModelTabularClassification() {
  // Configure the name resources
  const name = `projects/${project}/locations/${location}/models/${modelId}`;
  // Configure the outputConfig resources
  const outputConfig = {
    exportFormatId: 'tf-saved-model',
    artifactDestination: {
      outputUriPrefix: gcsDestinationOutputUriPrefix,
    },
  };
  const request = {
    name,
    outputConfig,
  };

  // Export Model request
  const [response] = await modelServiceClient.exportModel(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  console.log(`Export model response : ${JSON.stringify(response.result)}`);
}
exportModelTabularClassification();

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.

from google.cloud import aiplatform_v1beta1


def export_model_tabular_classification_sample(
    project: str,
    model_id: str,
    gcs_destination_output_uri_prefix: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
    timeout: int = 300,
):
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform_v1beta1.ModelServiceClient(client_options=client_options)
    gcs_destination = {"output_uri_prefix": gcs_destination_output_uri_prefix}
    output_config = {
        "artifact_destination": gcs_destination,
        "export_format_id": "tf-saved-model",
    }
    name = client.model_path(project=project, location=location, model=model_id)
    response = client.export_model(name=name, output_config=output_config)
    print("Long running operation:", response.operation.name)
    print("output_info:", response.metadata.output_info)
    export_model_response = response.result(timeout=timeout)
    print("export_model_response:", export_model_response)

Visualizzare lo stato di un'operazione di esportazione

Alcune richieste avviano operazioni a lunga esecuzione che richiedono tempo per essere completate. 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 Utilizzo delle operazioni di lunga durata.

Esegui il pull e l'esecuzione del server del modello

In questa attività, scaricherai il modello esportato da Cloud Storage e avvierai il contenitore Docker, in modo che il modello sia pronto per ricevere richieste di previsione.

Per estrarre ed eseguire il server del modello:

Sulla macchina in cui eseguirai il modello, vai alla directory in cui vuoi salvare il modello esportato.
Scarica il modello esportato:
```
gcloud storage cp <var>gcs-destination</var> . --recursive
```
dove gcs-destination è il percorso della posizione del modello esportato in Cloud Storage.

Il modello viene copiato nella directory corrente, nel seguente percorso:

./model-<model-id>/tf-saved-model/<export-timestamp>

Il percorso può contenere tf-saved-model o custom-trained.
Rinomina la directory in modo che il timestamp venga rimosso.
```
mv model-<model-id>/tf-saved-model/<export-timestamp> model-<model-id>/tf-saved-model/<new-dir-name>
```
Il timestamp rende la directory non valida per Docker.
Esegui il pull dell'immagine Docker del server del modello.
```
sudo docker pull MODEL_SERVER_IMAGE
```
L'immagine del server del modello da estrarre si trova nel file environment.json nella directory del modello esportato. Deve avere il seguente percorso:

./model-<model-id>/tf-saved-model/<new-dir-name>/environment.json

Se non è presente alcun file environment.json, utilizza:

MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1

Sostituisci MULTI_REGION con us, europe o asia per selezionare il repository Docker da cui vuoi estrarre l'immagine Docker. Ogni repository fornisce la stessa immagine Docker, ma la scelta della regione multipla di Artifact Registry più vicina alla macchina su cui esegui Docker potrebbe ridurre la latenza.

Avvia il container Docker utilizzando il nome della directory appena creato:

docker run -v `pwd`/model-<model-id>/tf-saved-model/<new-dir-name>:/models/default -p 8080:8080 -it MODEL_SERVER_IMAGE

Puoi interrompere il server del modello in qualsiasi momento utilizzando Ctrl-C.

Aggiorna il container Docker del server del modello

Poiché scarichi il container Docker del server di modelli quando esporti il modello, devi aggiornare esplicitamente il server di modelli per ricevere aggiornamenti e correzioni di bug. Devi aggiornare il server del modello periodicamente utilizzando il seguente comando:

docker pull MODEL_SERVER_IMAGE

Assicurati che l'URI dell'immagine Docker corrisponda all'URI dell'immagine Docker che hai recuperato in precedenza.

Ottenere le previsioni dal modello esportato

Il server di modelli nel contenitore di immagini Vertex AI gestisce le richieste di previsione e restituisce i risultati delle previsioni.

Le previsioni in batch non sono disponibili per i modelli esportati.

Formato dei dati di previsione

Fornisci i dati (campo payload) per la richiesta di previsione nel seguente formato JSON:

{ "instances": [ { "column_name_1": value, "column_name_2": value, … } , … ] }

L'esempio seguente mostra una richiesta con tre colonne: una colonna categorica, un array numerico e una struttura. La richiesta include due righe.

{
  "instances": [
    {
      "categorical_col": "mouse",
      "num_array_col": [
        1,
        2,
        3
      ],
      "struct_col": {
        "foo": "piano",
        "bar": "2019-05-17T23:56:09.05Z"
      }
    },
    {
      "categorical_col": "dog",
      "num_array_col": [
        5,
        6,
        7
      ],
      "struct_col": {
        "foo": "guitar",
        "bar": "2019-06-17T23:56:09.05Z"
      }
    }
  ]
}

Effettua la richiesta di previsione

Inserisci i dati della richiesta in un file di testo, ad esempio tmp/request.json.

Il numero di righe di dati nella richiesta di previsione, chiamato dimensione del mini-batch, influisce sulla latenza e sul throughput della previsione. Maggiore è il mini- batch, maggiore è la latenza e la velocità in uscita. Per ridurre la latenza, utilizza un volume del mini-batch più piccolo. Per aumentare la velocità effettiva, aumenta la dimensione del mini-batch. Le dimensioni dei mini-batch più utilizzate sono 1, 32, 64, 128, 256, 512 e 1024.

Richiedi la previsione:

curl -X POST --data @/tmp/request.json http://localhost:8080/predict

Formato dei risultati di previsione

Il formato dei risultati dipende dallo scopo del modello.

Risultati del modello di classificazione

I risultati di previsione per i modelli di classificazione (binari e multi-classe) restituiscono un punteggio di probabilità per ogni potenziale valore della colonna target. Devi determinare come vuoi utilizzare i punteggi. Ad esempio, per ottenere una classificazione binaria dai punteggi forniti, devi identificare un valore di soglia. Se sono presenti due classi, "A" e "B", devi classificare l'esempio come "A" se il punteggio per "A" è superiore alla soglia scelta e come "B" in caso contrario. Per i set di dati sbilanciati, la soglia potrebbe tendere al 100% o allo 0%.

Il payload dei risultati per un modello di classificazione è simile a questo esempio:

{
  "predictions": [
    {
      "scores": [
        0.539999994635582,
        0.2599999845027924,
        0.2000000208627896
      ],
      "classes": [
        "apple",
        "orange",
        "grape"
      ]
    },
    {
      "scores": [
        0.23999999463558197,
        0.35999998450279236,
        0.40000002086278963
      ],
      "classes": [
        "apple",
        "orange",
        "grape"
      ]
    }
  ]
}

Risultati del modello di regressione

Viene restituito un valore previsto per ogni riga valida della richiesta di previsione. Gli intervalli di previsione non vengono restituiti per i modelli esportati.

Il payload dei risultati per un modello di regressione è simile a questo esempio:

{
  "predictions": [
    {
      "value": -304.3663330078125,
      "lower_bound": -56.32196807861328,
      "upper_bound": 126.51904296875
    },
    {
      "value": -112.3663330078125,
      "lower_bound": 16.32196807861328,
      "upper_bound": 255.51904296875
    }
  ]
}

Passaggi successivi

Scopri come reimportare il modello tabulare esportato in Vertex AI.