Utilizzo di un container personalizzato per la previsione

Per personalizzare il modo in cui Vertex AI fornisce le previsioni online dal tuo con addestramento personalizzato, puoi specificare un container personalizzato anziché una container quando crei un Model risorsa. Quando utilizzi un container personalizzato, Vertex AI esegue un container Docker di tua scelta su ogni nodo di previsione.

Ti consigliamo di utilizzare un contenitore personalizzato per uno dei seguenti motivi:

• per generare previsioni da un modello ML addestrato utilizzando un framework non disponibile come container predefinito
• per pre-elaborare le richieste di previsione o post-elaborare le previsioni generate il tuo modello
• per eseguire un server di previsione scritto nel linguaggio di programmazione che preferisci
• per installare le dipendenze che vuoi utilizzare per personalizzare la previsione

Questa guida descrive come creare un modello che utilizza un container personalizzato. Non fornisce istruzioni dettagliate su come progettare e creare un'immagine container Docker.

prepara un'immagine container

Per creare un Model che utilizza un container personalizzato, devi fornire un'immagine container Docker come base del container. Questa immagine container deve soddisfare i requisiti descritti in Container personalizzato requisiti.

Se prevedi di utilizzare un'immagine container esistente creata da una terza parte potresti essere in grado di saltare una o entrambe le seguenti sezioni.

Crea un'immagine container

Progetta e crea un'immagine container Docker che soddisfi i requisiti delle immagini container.

Per apprendere le nozioni di base della progettazione e della creazione di un'immagine container Docker, leggi il Documentazione di Docker Guida rapida

Esegui il push dell'immagine del contenitore in Artifact Registry

Esegui il push dell'immagine container in un repository Artifact Registry.

Scopri come eseguire il push di un'immagine container in Artifact Registry.

Crea un Model

Per creare un Model che utilizza un contenitore personalizzato, svolgi una delle seguenti operazioni:

• Importa un modello con addestramento personalizzato.

• Crea un TrainingPipeline che esegue un CustomJob e importa gli elementi risultanti come Model.

Le seguenti sezioni mostrano come configurare i campi API relativi alle dei container quando crei un elemento Model in uno di questi modi.

Campi dell'API relativi ai container

Quando crei Model, assicurati di configurare il campo containerSpec con i dettagli del tuo contenitore personalizzato anziché con un contenitore predefinito.

Devi specificare un ModelContainerSpec messaggio in il campo Model.containerSpec. In questo messaggio, puoi specificare i seguenti campi secondari:

imageUri (obbligatorio)

L'URI di Artifact Registry dell'immagine container.

Se utilizzi gcloud ai models upload comando, puoi usare il flag --container-image-uri per specificare questo campo.

command (facoltativo)

Un array di un file eseguibile e degli argomenti per eseguire l'override dell'istruzione ENTRYPOINT del container. Per scoprire di più su come formattare questo campo e su come interagisce con il campo args, leggi la documentazione di riferimento dell'API per ModelContainerSpec.

Se utilizzi il comando gcloud ai models upload, puoi utilizzare il flag --container-command per specificare questo campo.

args (facoltativo)

Un array di un file eseguibile e degli argomenti per eseguire l'override del valore CMD del contenitore. Per scoprire di più su come formattare questo campo e su come interagisce con il campo command, consulta la documentazione di riferimento dell'API per ModelContainerSpec.

Se utilizzi il comando gcloud ai models upload, puoi utilizzare il flag --container-args per specificare questo campo.

ports (facoltativo)

Un array di porte. Vertex AI invia controlli di attività, controlli di integrità e richieste di previsione al tuo container sulla prima porta indicata o su 8080 per impostazione predefinita. La specifica di porte aggiuntive non ha alcun effetto.

Se utilizzi il comando gcloud ai models upload, puoi utilizzare il flag --container-ports per specificare questo campo.

env (facoltativo)

Un array di variabili di ambiente che l'istruzione ENTRYPOINT del container, così come i campi command e args. Per scoprire di più su come altri campi possono fare riferimento a queste variabili di ambiente, consulta il riferimento all'API per ModelContainerSpec.

Se utilizzi il comando gcloud ai models upload, puoi utilizzare il flag --container-env-vars per specificare questo campo.

healthRoute (facoltativo)

Il percorso sul server HTTP del container in cui vuoi Vertex AI per inviare integrità controlli.

Se non specifichi questo campo, quando esegui il deployment di Model come DeployedModel a una risorsa Endpoint che utilizza per impostazione predefinita /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL, dove ENDPOINT è sostituito dall'ultimo segmento del name di Endpoint campo (seguente endpoints/) e DEPLOYED_MODEL è sostituito dal id di DeployedModel .

Se utilizzi gcloud ai models upload, puoi usare il flag --container-health-route per specificare questo campo.

predictRoute (facoltativo)

Il percorso sul server HTTP del container in cui vuoi Vertex AI per inoltrare le previsioni richieste.

Se non specifichi questo campo, quando esegui il deployment di Model come DeployedModel in una risorsa Endpoint, per impostazione predefinita viene utilizzato /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict, dove ENDPOINT viene sostituito dall'ultimo segmento del name Endpoint (dopo endpoints/) e DEPLOYED_MODEL viene sostituito dal DeployedModel id .

Se utilizzi il comando gcloud ai models upload, puoi utilizzare il flag --container-predict-route per specificare questo campo.

sharedMemorySizeMb (facoltativo)

La quantità di memoria VM da riservare in un volume di memoria condivisa per il modello in megabyte.

La memoria condivisa è un meccanismo di comunicazione interprocessuale (IPC) che consente a più processi di accedere e manipolare un blocco di memoria comune. La quantità di memoria condivisa necessaria, se presente, è un dettaglio di implementazione del contenitore e del modello. Per le linee guida, consulta la documentazione del server di modelli.

Se utilizzi gcloud ai models upload, puoi usare il flag --container-shared-memory-size-mb per specificare questo campo.

startupProbe (facoltativo)

Specifica del probe che verifica se l'applicazione container è iniziata.

Se utilizzi gcloud ai models upload, puoi usare il flag --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds per specificare questo campo.

healthProbe (facoltativo)

Specifica del probe che verifica se un container è pronto per accettano il traffico.

Se utilizzi il comando gcloud ai models upload, puoi utilizzare il flag --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds per specificare questo campo.

Oltre alle variabili impostate nel campo Model.containerSpec.env , Vertex AI imposta diverse altre variabili in base alla configurazione. Scopri di più su utilizzando queste variabili di ambiente in questi campi e nell'istruzione ENTRYPOINT del contenitore.

Esempi di importazione del modello

Gli esempi riportati di seguito mostrano come specificare i campi dell'API relativi ai contenitori quando importi un modello.

Nota: se utilizzi TrainingPipeline per creare Model, devi specificare questi campi in un contesto diverso. Non puoi utilizzare Google Cloud CLI per crea un TrainingPipeline. Scopri di più sulla creazione di risorse TrainingPipeline personalizzate.

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 \
  --container-command=COMMAND \
  --container-args=ARGS \
  --container-ports=PORTS \
  --container-env-vars=ENV \
  --container-health-route=HEALTH_ROUTE \
  --container-predict-route=PREDICT_ROUTE \
  --container-shared-memory-size-mb=SHARED_MEMORY_SIZE \
  --container-startup-probe-exec=STARTUP_PROBE_EXEC \
  --container-startup-probe-period-seconds=STARTUP_PROBE_PERIOD \
  --container-startup-probe-timeout-seconds=STARTUP_PROBE_TIMEOUT \
  --container-health-probe-exec=HEALTH_PROBE_EXEC \
  --container-health-probe-period-seconds=HEALTH_PROBE_PERIOD \
  --container-health-probe-timeout-seconds=HEALTH_PROBE_TIMEOUT \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

Il flag --container-image-uri è obbligatorio; tutti gli altri flag che iniziano con --container- sono facoltativi. Per informazioni sui valori di questi campi, consulta la sezione precedente di questa guida.

Java

Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Java Vertex AI documentazione di riferimento.

Per autenticarti in Vertex AI, configura le credenziali predefinite dell'applicazione. Per maggiori 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 per la configurazione di Node.js nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Node.js Vertex AI documentazione di riferimento.

Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 ulteriori informazioni, consulta 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 ulteriori informazioni, consulta la guida all'importazione dei modelli.

Inviare richieste di previsione

Per inviare una richiesta di previsione online al tuo Model, segui le istruzioni alla pagina Ottieni previsioni da un modello con addestramento personalizzato: questo processo funziona allo stesso modo a prescindere dal fatto che utilizzi o meno un container personalizzato.

Scopri di più sui requisiti per le richieste e le risposte di previsione per i container personalizzati.

Passaggi successivi

• Per saperne di più su tutti gli aspetti da considerare quando progetti un container personalizzato da utilizzare con Vertex AI, leggi Custom container requisiti.