Utilizzo di un container personalizzato per la previsione

Per personalizzare il modo in cui Vertex AI fornisce le previsioni online dal tuo modello addestrato, puoi specificare un container personalizzato invece di un container predefinito quando crei una risorsa Model. Quando usi un container personalizzato, Vertex AI esegue un container Docker a tua scelta su ciascun nodo di previsione.

Puoi utilizzare un container personalizzato per uno dei seguenti motivi:

• per fornire previsioni da un modello ML addestrato usando un framework non disponibile come container predefinito
• per pre-elaborare le richieste di previsione o post-elaborare le previsioni generate dal modello
• per eseguire un server di previsione scritto in un linguaggio di programmazione a tua scelta
• per installare le dipendenze che vuoi utilizzare per personalizzare la previsione

Questa guida descrive come creare un Model che utilizza un container personalizzato. Non fornisce istruzioni dettagliate sulla progettazione e sulla creazione di un'immagine container Docker.

Prepara un'immagine container

Per creare un elemento Model che utilizza un container personalizzato, devi fornire un'immagine container Docker come base di quel container. Questa immagine container deve soddisfare i requisiti descritti in Requisiti dei container personalizzati.

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

Crea un'immagine container

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

Per conoscere le nozioni di base sulla progettazione e sulla creazione di un'immagine container Docker, leggi la guida rapida della documentazione di Docker

Esegui il push dell'immagine container in Artifact Registry

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

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

Crea un Model

Per creare un Model che utilizza un container personalizzato, esegui una delle seguenti operazioni:

• Importa un modello con addestramento personalizzato.

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

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

Campi API relativi al container

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

Devi specificare un messaggio ModelContainerSpec nel campo Model.containerSpec. All'interno di questo messaggio, puoi specificare i seguenti sottocampi:

imageUri (obbligatoria)

L'URI Artifact Registry della tua immagine container.

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

command (facoltativo)

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

Se usi 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 di argomenti per eseguire l'override del parametro CMD del container per scoprire di più su come formattare questo campo e su come interagisce con il campo command, leggi il riferimento API per ModelContainerSpec.

Se usi 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 elencata oppure 8080 per impostazione predefinita. La specifica di porte aggiuntive non ha alcun effetto.

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

env (facoltativo)

Un array di variabili di ambiente a cui il comando del punto di ingresso del container e i campi command e args possono fare riferimento. Per scoprire di più su come altri campi possono fare riferimento a queste variabili di ambiente, leggi il riferimento API per ModelContainerSpec.

Se usi 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 che Vertex AI invii i controlli di integrità.

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

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

predictRoute (facoltativo)

Il percorso sul server HTTP del container in cui vuoi che Vertex AI inoltri le richieste di previsione.

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

Se usi 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 prenotare in un volume di memoria condivisa per il modello, espressa in megabyte.

La memoria condivisa è un meccanismo di comunicazione tra processi (IPC) che consente a più processi di accedere a un blocco comune di memoria e di manipolarlo. La quantità di memoria condivisa necessaria, se presente, è un dettaglio di implementazione del container e del modello. Consulta la documentazione del server dei modelli per le linee guida.

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

startupProbe (facoltativo)

Specifica per il probe che verifica se l'applicazione container è stata avviata.

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

healthProbe (facoltativo)

Specifica per il probe che verifica se un container è pronto ad accettare traffico.

Se usi 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ù sull'utilizzo di queste variabili di ambiente in questi campi e nel comando del punto di ingresso del container.

Esempi di importazione di modelli

I seguenti esempi mostrano come specificare i campi API relativi ai container quando importi un modello.

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

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());
    }
  }
}

/**
 * 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();

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, leggi la guida all'importazione dei modelli.

Invia richieste di previsione

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

Leggi ulteriori informazioni sui requisiti previsti per richieste e risposte per i container personalizzati.

Passaggi successivi

• Per scoprire tutto quello da considerare quando progetti un container personalizzato da utilizzare con Vertex AI, leggi i requisiti per i container personalizzati.