Esportare i modelli tabulari AutoML

Questa pagina descrive come utilizzare Gemini Enterprise Agent Platform per esportare il modello tabulare AutoML in Cloud Storage, scaricare il modello su un server on-premise o su un server ospitato da un altro fornitore di servizi cloud e poi utilizzare Docker per rendere il modello disponibile per le previsioni.

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

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

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 utilizzando i modelli tabulari esportati. Se devi utilizzare Vertex Explainable AI, devi erogare le previsioni da un modello ospitato da Agent Platform.

• Il modello tabulare esportato può essere eseguito solo su CPU con architettura x86 che supportano i set di istruzioni Advanced Vector Extensions (AVX).

Processo di esportazione

I passaggi per esportare il modello sono:

1. Configura l'ambiente.
2. Esporta il modello.
3. Estrai ed esegui il server del modello.
4. Richiedi le 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.
• Addestra il modello che vuoi scaricare.
• Installa e inizializza Google Cloud CLI sul server che utilizzerai per eseguire il modello esportato.
• Installa Docker sul server.

Esporta il modello

Console

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

   Vai alla pagina Modelli

2. Fai clic sul modello tabulare che vuoi esportare per aprire la relativa pagina dei dettagli.

3. Fai clic su Esporta nella barra dei pulsanti per esportare il modello.

4. Seleziona o crea una cartella Cloud Storage nella località desiderata.

   Il bucket deve soddisfare i requisiti del 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. In un passaggio successivo copierai l'intero contenuto della cartella.

5. Fai clic su Esporta.

   Nella sezione successiva scaricherai il modello esportato sul server.

REST

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

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

• LOCATION: la tua regione.
• PROJECT: il tuo [ID progetto](/resource-manager/docs/creating-managing-projects#identifiers). .
• MODEL_ID: l'ID del modello che vuoi 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 soddisfare i requisiti del bucket.

  Per risultati ottimali, crea una nuova cartella. In un passaggio successivo copierai l'intero contenuto della cartella.

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 di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, e 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, e 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 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 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 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 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 Agent Platform per Python, consulta Installare l'SDK Agent Platform 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)

Verificare 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 visualizzare lo stato dell'operazione o annullarla. Colab Enterprise fornisce metodi di assistenza per effettuare chiamate a operazioni a lunga esecuzione. Per saperne di più, consulta Utilizzare le operazioni a lunga esecuzione.

Estrai ed esegui il server del modello

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

Per estrarre ed eseguire il server del modello:

1. Sulla macchina in cui eseguirai il modello, passa alla directory in cui vuoi salvare il modello esportato.

2. 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.

3. 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.

4. Estrai l'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. Dovrebbe avere il seguente percorso:

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

5. Avvia il container Docker utilizzando il nome della directory appena creata:

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

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

Aggiornare il container Docker del server del modello

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

docker pull MODEL_SERVER_IMAGE

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

Ottenere previsioni dal modello esportato

Il server del modello nel container dell'immagine di Agent Platform gestisce le richieste di previsione e restituisce i risultati della previsione.

La previsione in batch non è disponibile 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, … } , … ] }

Nota: i modelli di Agent Platform esportati non convalidano il formato dei dati delle richieste di previsione. Ciò significa che una richiesta di previsione altrimenti ben formata con colonne mancanti, errori nei nomi delle colonne o persino una richiesta per un modello completamente diverso restituisce una previsione (errata o potenzialmente priva di significato). Assicurati che le richieste di previsione ai modelli esportati siano corrette.

L'esempio seguente mostra una richiesta con tre colonne: una colonna categorica, un array numerico e una struct. 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"
      }
    }
  ]
}

Effettuare la richiesta di previsione

1. 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 sulla velocità effettiva della previsione. Maggiore è la dimensione del mini-batch, maggiore è la latenza e la velocità effettiva. Per ridurre la latenza, utilizza una dimensione del mini-batch più piccola. Per aumentare la velocità effettiva, aumenta la dimensione del mini-batch. Le dimensioni del mini-batch di uso comune sono 1, 32, 64, 128, 256, 512 e 1024.

2. Richiedi la previsione:

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

Formato dei risultati della previsione

Il formato dei risultati dipende dall'obiettivo del modello.

Risultati del modello di classificazione

I risultati della previsione per i modelli di classificazione (binari e multi-classe) restituiscono un punteggio di probabilità per ogni valore potenziale 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" è maggiore della soglia scelta e "B" in caso contrario. Per i set di dati sbilanciati, la soglia potrebbe avvicinarsi 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 importare di nuovo il modello tabulare esportato in Agent Platform.