Utilizzo di un container personalizzato per l'inferenza

Per personalizzare il modo in cui Agent Platform gestisce le inferenze online dal modello con addestramento personalizzato, puoi specificare un container personalizzato anziché un container predefinito quando crei una Model risorsa. Quando utilizzi un container personalizzato, Agent Platform esegue un container Docker a tua scelta su ogni nodo di inferenza.

Potresti voler utilizzare un container personalizzato per uno dei seguenti motivi:

• Per erogare inferenze da un modello di ML addestrato utilizzando un framework non disponibile come container predefinito
• Per pre-elaborare le richieste di inferenza o post-elaborare le inferenze generate dal modello.
• Per eseguire un server di inferenza scritto in un linguaggio di programmazione a tua scelta.
• Per installare le dipendenze che vuoi utilizzare per personalizzare le inferenze.

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

Preparare 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 Requisiti dei container personalizzati.

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

Creare un'immagine container

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

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

Eseguire 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 in Artifact Registry.

Creare un Model

Per creare un Model che utilizza un container personalizzato, procedi in uno dei seguenti modi:

• 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 ai container

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

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

imageUri (obbligatorio)

L'URI di Artifact Registry dell'immagine container.

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

command (facoltativo)

Un array di un eseguibile e argomenti per sostituire l'istruzione ENTRYPOINT del container. Per saperne di più su come formattare questo campo e su come interagi sce con il campo args, consulta il riferimento 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 eseguibile e argomenti per sostituire il CMD Per saperne di più su come formattare questo campo e su come interagisce con il command campo, consulta il riferimento 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; Agent Platform invia controlli di attività, controlli di integrità e richieste di inferenza al container sulla prima porta elencata o 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 a cui l'istruzione ENTRYPOINT del container, nonché i campi command e args, possono fare riferimento. Per saperne di più su come altri campi possono fare riferimento a queste variabili di ambiente, consulta il riferimento 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 che Agent Platform invii i controlli di integrità.

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

Se utilizzi 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 Agent Platform inoltri le richieste di inferenza.

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

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

invokeRoutePrefix (facoltativo)

Richiama il prefisso della route per il container personalizzato. Se imposti questo campo su "/*", attivi il routing arbitrario per il modello. Una volta eseguito il deployment, qualsiasi route non principale sul server del modello sarà accessibile con la chiamata HTTP di chiamata. Ad esempio, "/invoke/foo/bar" verrà inoltrato come "/foo/bar" al server del modello. Questa funzionalità è in anteprima pubblica. Per creare un modello abilitato alla chiamata, segui le istruzioni per utilizzare route personalizzate arbitrarie.

sharedMemorySizeMb (facoltativo)

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

La memoria condivisa è un meccanismo di comunicazione tra processi (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 container e del modello. Consulta la documentazione del server del modello per le linee guida.

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

startupProbe (facoltativo)

Specifica del probe che controlla se l'applicazione container è stata avviata.

Se utilizzi 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 del probe che controlla se un container è pronto ad accettare 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 che imposti nel campo Model.containerSpec.env, Agent Platform imposta diverse altre variabili in base alla configurazione. Scopri di più sull' utilizzo di queste variabili di ambiente in questi campi e nell'istruzione ENTRYPOINT del container.

Esempi di importazione di modelli

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

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

gcloud

L'esempio seguente utilizza il gcloud ai models upload comando:

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 scoprire i valori di questi campi, consulta la sezione precedente di questa guida.

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 Configura 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 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 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 Python, consulta Installare l'SDK Vertex AI 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 maggiori informazioni, consulta la guida all'importazione dei modelli.

Inviare richieste di inferenza

Per inviare una richiesta di inferenza online al tuo Model, segui le istruzioni riportate in Ottenere inferenze da un modello con addestramento personalizzato: questa procedura funziona allo stesso modo indipendentemente dal fatto che utilizzi un container personalizzato.

Scopri di più sui requisiti di richiesta e risposta di previsione per i container personalizzati.

Passaggi successivi

• Per scoprire tutto ciò che devi considerare quando progetti un container personalizzato da utilizzare con Agent Platform, consulta Requisiti dei container personalizzati.