Importazione di modelli in Vertex AI

Questa guida descrive come importare i modelli nel Registro modelli. Dopo averlo importato, il modello sarà visibile nel Model Registry. Da Model Registry, puoi eseguire il deployment del modello importato in un endpoint ed eseguire le previsioni.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per importare i modelli, chiedi all'amministratore di concederti il ruolo IAM Utente Vertex AI (roles/aiplatform.user) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Container predefiniti o personalizzati

Quando importi un modello, lo associ a un contenitore per consentire a Vertex AI di eseguire richieste di previsione. Puoi utilizzare container predefiniti forniti da Vertex AI oppure i tuoi container personalizzati che crei e invii ad Artifact Registry.

Puoi utilizzare un contenitore predefinito se il tuo modello soddisfa i seguenti requisiti:

Se importi un modello AutoML tabulare che hai precedentemente esportato, devi utilizzare un container personalizzato specifico fornito da Vertex AI.

In caso contrario, crea un nuovo container personalizzato o utilizza un container personalizzato esistente che hai in Artifact Registry.

Carica gli elementi del modello in Cloud Storage

Devi archiviare gli elementi del modello in un bucket Cloud Storage, dove la regione del bucket corrisponde all'endpoint regionale in uso.

Se il bucket Cloud Storage si trova in un altro progetto Google Cloud, devi concedere l'accesso a Vertex AI per leggere gli elementi del modello.

Se utilizzi un contenitore precompilato, assicurati che i nomi dei file degli elementi del modello corrispondano esattamente ai seguenti esempi:

  • SavedModel TensorFlow: saved_model.pb
  • PyTorch: model.mar
  • scikit-learn: model.joblib o model.pkl
  • XGBoost: model.bst, model.joblib o model.pkl

Scopri di più sull'esportazione degli elementi del modello per la previsione.

Importare un modello utilizzando la console Google Cloud

Per importare un modello utilizzando la console Google Cloud:

  1. Nella console Google Cloud, vai alla pagina Modelli di Vertex AI.

    Vai alla pagina Modelli

  2. Fai clic su Importa.

  3. Seleziona Importa come nuovo modello per importare un nuovo modello.

  4. Seleziona Importa come nuova versione per importare un modello come versione di un modello esistente. Per scoprire di più sul controllo delle versioni dei modelli, consulta Controllo delle versioni dei modelli.

  5. Nome e regione: inserisci un nome per il modello. Seleziona la regione corrispondente sia alla regione del bucket sia all'endpoint regionale di Vertex AI in uso. Fai clic su Continua.

  6. Se espandi Opzioni avanzate, puoi decidere di aggiungere facoltativamente una chiave di crittografia gestita dal cliente.

A seconda del tipo di contenitore in uso, seleziona la scheda appropriata riportata di seguito.

Container predefinito

  1. Seleziona Importa gli artefatti del modello in un nuovo container predefinito.

  2. Seleziona il framework del modello e la versione del framework del modello che hai utilizzato per addestrare il modello.

  3. Se vuoi utilizzare le GPU per pubblicare le previsioni, imposta Tipo di acceleratore su GPU.

    Seleziona il tipo di GPU in un secondo momento, quando esegui il deployment del modello in un endpoint.

  4. Specifica il percorso Cloud Storage della directory contenente gli elementi del modello.

    Ad esempio, gs://BUCKET_NAME/models/.

  5. Lascia vuoto il campo Schema di previsione.

  6. Per importare il modello senza le impostazioni di Vertex Explainable AI, fai clic su Importa.

    Al termine dell'importazione, il modello viene visualizzato nella pagina Modelli.

    In caso contrario, continua a configurare il modello inserendo le impostazioni di spiegabilità nella scheda Spiegabilità. Scopri di più sulle impostazioni di spiegabilità.

Container personalizzato

  1. Seleziona Importa un container personalizzato esistente.

  2. Imposta l'URI dell'immagine container.

  3. Se vuoi fornire gli elementi modello oltre a un'immagine contenitore, specifica il percorso Cloud Storage della directory contenente gli elementi modello.

    Ad esempio, gs://BUCKET_NAME/models/.

  4. Specifica i valori per uno degli altri campi.

    Scopri di più su questi campi facoltativi.

  5. Per importare il modello senza le impostazioni di Vertex Explainable AI, fai clic su Importa.

    Al termine dell'importazione, il modello viene visualizzato nella pagina Modelli.

    In caso contrario, continua a configurare il modello inserendo le impostazioni di spiegabilità nella scheda Spiegabilità. Scopri di più sulle impostazioni di spiegabilità.

Contenitore tabulare AutoML

  1. Seleziona Importa un container personalizzato esistente.

  2. Nel campo Immagine contenitore, inserisci MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.

    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.

  3. Nel campo Posizione pacchetto, specifica il percorso Cloud Storage della directory contenente gli elementi del modello.

    Il percorso è simile al seguente esempio:

    gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/

  4. Lascia vuoti tutti gli altri campi.

  5. Fai clic su Importa.

    Al termine dell'importazione, il modello viene visualizzato nella pagina Modelli. Puoi utilizzare questo modello come gli altri modelli tabulari AutoML, tranne per il fatto che i modelli tabulari AutoML importati non supportano l'Vertex Explainable AI.

Importare un modello tramite programmazione

Gli esempi seguenti mostrano come importare un modello utilizzando vari strumenti:

gcloud

Nell'esempio seguente viene utilizzato il comando gcloud ai models upload:

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

Sostituisci quanto segue:

  • LOCATION_ID: la regione in cui utilizzi Vertex AI.
  • MODEL_NAME: un nome visualizzato per Model.
  • IMAGE_URI: l'URI dell'immagine del contenitore da utilizzare per la pubblicazione delle previsioni. Ad esempio, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Utilizza un container predefinito o un container personalizzato.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: l'URI Cloud Storage (che inizia con gs://) di una directory in Cloud Storage contenente i artefatti del modello.

L'esempio precedente mostra tutti i flag necessari per importare la maggior parte dei modelli. Se non utilizzi un container predefinito per le previsioni, probabilmente dovrai specificare alcuni flag facoltativi in modo che Vertex AI possa utilizzare l'immagine del container. Questi flag, che iniziano con --container-, corrispondono ai campi del containerSpec di Model.

REST

Utilizza il seguente esempio di codice per caricare un modello utilizzando il metodo upload della risorsa model.

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

  • LOCATION_ID: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo ID progetto.
  • MODEL_NAME: un nome visualizzato per Model.
  • MODEL_DESCRIPTION: facoltativo. Una descrizione del modello.
  • IMAGE_URI: l'URI dell'immagine del contenitore da utilizzare per la pubblicazione delle previsioni. Ad esempio, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Utilizza un container predefinito o un container personalizzato.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: l'URI Cloud Storage (che inizia con gs://) di una directory in Cloud Storage contenente i componenti del modello. Questa variabile e il campo artifactUri sono facoltativi se utilizzi un contenitore personalizzato.
  • labels: facoltativo. Qualsiasi insieme di coppie chiave-valore per organizzare i modelli. Ad esempio:
    • "env": "prod"
    • "tier": "backend"
  • Specifica LABEL_NAME e LABEL_VALUE per le etichette da applicare a questa pipeline di addestramento.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "labels": {
      "LABEL_NAME_1": "LABEL_VALUE_1",
      "LABEL_NAME_2": "LABEL_VALUE_2"
    }
  }
}

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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload"

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

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.LocationName;
import com.google.cloud.aiplatform.v1.Model;
import com.google.cloud.aiplatform.v1.ModelContainerSpec;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import com.google.cloud.aiplatform.v1.UploadModelOperationMetadata;
import com.google.cloud.aiplatform.v1.UploadModelResponse;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UploadModelSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String modelDisplayName = "YOUR_MODEL_DISPLAY_NAME";
    String metadataSchemaUri =
        "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml";
    String imageUri = "YOUR_IMAGE_URI";
    String artifactUri = "gs://your-gcs-bucket/artifact_path";
    uploadModel(project, modelDisplayName, metadataSchemaUri, imageUri, artifactUri);
  }

  static void uploadModel(
      String project,
      String modelDisplayName,
      String metadataSchemaUri,
      String imageUri,
      String artifactUri)
      throws IOException, InterruptedException, ExecutionException, 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";
      LocationName locationName = LocationName.of(project, location);

      ModelContainerSpec modelContainerSpec =
          ModelContainerSpec.newBuilder().setImageUri(imageUri).build();

      Model model =
          Model.newBuilder()
              .setDisplayName(modelDisplayName)
              .setMetadataSchemaUri(metadataSchemaUri)
              .setArtifactUri(artifactUri)
              .setContainerSpec(modelContainerSpec)
              .build();

      OperationFuture<UploadModelResponse, UploadModelOperationMetadata> uploadModelResponseFuture =
          modelServiceClient.uploadModelAsync(locationName, model);
      System.out.format(
          "Operation name: %s\n", uploadModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      UploadModelResponse uploadModelResponse = uploadModelResponseFuture.get(5, TimeUnit.MINUTES);

      System.out.println("Upload Model Response");
      System.out.format("Model: %s\n", uploadModelResponse.getModel());
    }
  }
}

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.\
 */

// const modelDisplayName = 'YOUR_MODEL_DISPLAY_NAME';
// const metadataSchemaUri = 'YOUR_METADATA_SCHEMA_URI';
// const imageUri = 'YOUR_IMAGE_URI';
// const artifactUri = 'YOUR_ARTIFACT_URI';
// 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 uploadModel() {
  // Configure the parent resources
  const parent = `projects/${project}/locations/${location}`;
  // Configure the model resources
  const model = {
    displayName: modelDisplayName,
    metadataSchemaUri: '',
    artifactUri: artifactUri,
    containerSpec: {
      imageUri: imageUri,
      command: [],
      args: [],
      env: [],
      ports: [],
      predictRoute: '',
      healthRoute: '',
    },
  };
  const request = {
    parent,
    model,
  };

  console.log('PARENT AND MODEL');
  console.log(parent, model);
  // Upload Model request
  const [response] = await modelServiceClient.uploadModel(request);
  console.log(`Long running operation : ${response.name}`);

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

  console.log('Upload model response ');
  console.log(`\tModel : ${result.model}`);
}
uploadModel();

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 typing import Dict, Optional, Sequence

from google.cloud import aiplatform
from google.cloud.aiplatform import explain


def upload_model_sample(
    project: str,
    location: str,
    display_name: str,
    serving_container_image_uri: str,
    artifact_uri: Optional[str] = None,
    serving_container_predict_route: Optional[str] = None,
    serving_container_health_route: Optional[str] = None,
    description: Optional[str] = None,
    serving_container_command: Optional[Sequence[str]] = None,
    serving_container_args: Optional[Sequence[str]] = None,
    serving_container_environment_variables: Optional[Dict[str, str]] = None,
    serving_container_ports: Optional[Sequence[int]] = None,
    instance_schema_uri: Optional[str] = None,
    parameters_schema_uri: Optional[str] = None,
    prediction_schema_uri: Optional[str] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    sync: bool = True,
):

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

    model = aiplatform.Model.upload(
        display_name=display_name,
        artifact_uri=artifact_uri,
        serving_container_image_uri=serving_container_image_uri,
        serving_container_predict_route=serving_container_predict_route,
        serving_container_health_route=serving_container_health_route,
        instance_schema_uri=instance_schema_uri,
        parameters_schema_uri=parameters_schema_uri,
        prediction_schema_uri=prediction_schema_uri,
        description=description,
        serving_container_command=serving_container_command,
        serving_container_args=serving_container_args,
        serving_container_environment_variables=serving_container_environment_variables,
        serving_container_ports=serving_container_ports,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        sync=sync,
    )

    model.wait()

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

Per importare un modello con le impostazioni di Vertex Explainable AI abilitate, consulta gli esempi di importazione di modelli Vertex Explainable AI.

Recupera lo stato dell'operazione

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.

Limitazioni

  • La dimensione massima del modello supportata è 10 GiB.

Passaggi successivi