Requisiti dei container personalizzati per la previsione

Per utilizzare un container personalizzato per fornire previsioni da un modello addestrato, devi fornire a Vertex AI un'immagine container Docker che esegue un server HTTP. Questo documento descrive i requisiti che un'immagine container deve soddisfare per essere compatibile con Vertex AI. Il documento descrive anche come Vertex AI interagisce con il container personalizzato una volta avviato. In altre parole, questo documento descrive cosa devi considerare quando progetta un'immagine container da utilizzare con Vertex AI.

Per informazioni dettagliate sull'uso di un'immagine container personalizzata per fornire previsioni, consulta Utilizzare un container personalizzato.

Requisiti delle immagini container

Quando l'immagine container Docker viene eseguita come container, quest'ultimo deve eseguire un server HTTP. In particolare, il container deve rimanere in ascolto e rispondere a controlli di attività, controlli di integrità e richieste di previsione. Le seguenti sottosezioni descrivono questi requisiti in modo dettagliato.

Puoi implementare il server HTTP in qualsiasi modo e utilizzando qualsiasi linguaggio di programmazione, purché soddisfi i requisiti indicati in questa sezione. Ad esempio, puoi scrivere un server HTTP personalizzato utilizzando un framework web come Flask oppure utilizzare un software di pubblicazione di machine learning (ML) che esegue un server HTTP, come TensorFlow Serving, TorchServe o KServe Python Server.

Esegui il server HTTP

Puoi eseguire un server HTTP utilizzando un'istruzione ENTRYPOINT, un'CMD istruzione o entrambi nel Dockerfile che utilizzi per creare l'immagine container. Scopri di più sull'interazione tra CMD e ENTRYPOINT.

In alternativa, puoi specificare i campi containerSpec.command e containerSpec.args quando crei la risorsa Model, in modo da sostituire rispettivamente i valori ENTRYPOINT e CMD dell'immagine container. Se specifichi uno di questi campi, puoi utilizzare un'immagine container che altrimenti non soddisferebbe i requisiti a causa di un elemento ENTRYPOINT o CMD incompatibile (o inesistente).

Indipendentemente da quale sia il comando eseguito dal container all'avvio, assicurati che questo comando del punto di ingresso venga eseguito a tempo indeterminato. Ad esempio, non eseguire un comando che avvia un server HTTP in background e poi si chiude: in questo caso, il container verrà chiuso subito dopo l'avvio dell'esecuzione.

Il tuo server HTTP deve rimanere in ascolto per le richieste su 0.0.0.0, su una porta a tua scelta. Quando crei un elemento Model, specifica questa porta nel campo containerSpec.ports. Per scoprire come il container può accedere a questo valore, consulta la sezione di questo documento sulla variabile di ambiente AIP_HTTP_PORT.

Controlli di attività

Vertex AI esegue un controllo di attività all'avvio del container per garantire che il server sia in esecuzione. Quando esegui il deployment di un modello con addestramento personalizzato in una risorsa Endpoint, Vertex AI utilizza un probe di attività TCP per tentare di stabilire una connessione TCP al tuo container sulla porta configurata. Il probe effettua fino a 4 tentativi per stabilire una connessione, attendendo 10 secondi dopo ogni errore. Se a questo punto il probe non ha ancora stabilito una connessione, Vertex AI riavvia il container.

Il tuo server HTTP non deve eseguire alcun comportamento speciale per gestire questi controlli. Finché è in ascolto delle richieste sulla porta configurata, il probe di attività è in grado di stabilire una connessione.

Controlli di integrità

Facoltativamente, puoi specificare startup_probe o health_probe.

Il probe di avvio controlla se l'applicazione del container è stata avviata. Se non viene fornito un probe di avvio, non viene fornito alcun probe di avvio e i controlli di integrità vengono avviati immediatamente. Se viene fornito il probe di avvio, i controlli di integrità non vengono eseguiti finché il probe di avvio non va a buon fine.

Le applicazioni legacy che potrebbero richiedere tempi di avvio aggiuntivi alla prima inizializzazione devono configurare un probe di avvio. Ad esempio, se l'applicazione deve copiare gli artefatti del modello da un'origine esterna, è necessario configurare un probe di avvio che restituisca successo al termine dell'inizializzazione.

Il probe di integrità controlla se un container è pronto ad accettare traffico. Se il probe di integrità non viene fornito, Vertex AI utilizza i controlli di integrità predefiniti come descritto in Controlli di integrità predefiniti.

Le applicazioni legacy che non restituiscono 200 OK per indicare che il modello è caricato e pronto ad accettare traffico devono configurare un probe di integrità. Ad esempio, un'applicazione potrebbe restituire 200 OK per indicare l'esito positivo anche se lo stato di caricamento del modello effettivo nel corpo della risposta indica che il modello potrebbe non essere caricato e pertanto potrebbe non essere pronto ad accettare traffico. In questo caso, è necessario configurare un probe di integrità in modo che restituisca un errore solo quando il modello è caricato ed è pronto per gestire il traffico.

Per eseguire un probe, Vertex AI esegue il comando exec specificato nel container di destinazione. Se il comando ha esito positivo, restituisce 0 e il container è considerato attivo e integro.

Controlli di integrità predefiniti

Per impostazione predefinita, Vertex AI esegue a intermittenza controlli di integrità sul server HTTP mentre è in esecuzione per garantire che sia pronto a gestire le richieste di previsione. Il servizio utilizza un probe di integrità per inviare richieste GET HTTP a un percorso di controllo di integrità configurabile sul server. Specifica questo percorso nel campo containerSpec.healthRoute quando crei un Model. Per informazioni su come il container può accedere a questo valore, consulta la sezione di questo documento sulla variabile di ambiente AIP_HEALTH_ROUTE.

Configura il server HTTP in modo che risponda a ogni richiesta di controllo di integrità come segue:

  • Se il server è pronto a gestire le richieste di previsione,rispondi alla richiesta di controllo di integrità entro 10 secondi con il codice di stato 200 OK. I contenuti del corpo della risposta non sono importanti, Vertex AI li ignora.

    Questa risposta indica che il server è integro.

  • Se il server non è pronto per gestire le richieste di previsione, non rispondere alla richiesta di controllo di integrità entro 10 secondi o rispondere con qualsiasi codice di stato tranne 200 OK. Ad esempio, rispondi con il codice di stato 503 Service Unavailable.

    Questa risposta (o l'assenza di una risposta) indica che il server non è integro.

Se il probe di integrità riceve una risposta non integro dal tuo server (inclusa nessuna risposta entro 10 secondi), invia fino a 3 controlli di integrità aggiuntivi a intervalli di 10 secondi. Durante questo periodo, Vertex AI considera comunque il tuo server integro. Se il probe riceve una risposta in stato integro a uno di questi controlli, torna immediatamente alla pianificazione intermittente dei controlli di integrità. Tuttavia, se il probe riceve quattro risposte in stato non integro consecutive, Vertex AI interrompe il routing del traffico di previsione verso il container. (Se la risorsa DeployedModel è scalata per utilizzare più nodi di previsione, Vertex AI instrada le richieste di previsione ad altri container integri.)

Vertex AI non riavvia il container; al contrario, il probe di integrità continua a inviare richieste di controllo di integrità intermittenti al server non integro. Se riceve una risposta in stato integro, contrassegna il container come integro e inizia a instradare nuovamente il traffico di previsione verso il container.

Indicazioni pratiche

In alcuni casi, è sufficiente che il server HTTP nel tuo container risponda sempre con il codice di stato 200 OK ai controlli di integrità. Se il container carica le risorse prima di avviare il server, questo non è integro durante il periodo di avvio e in tutti i periodi in cui il server HTTP si arresta. In tutti gli altri momenti risponde in modo sano.

Per una configurazione più sofisticata, potresti voler progettare deliberatamente il server HTTP in modo che risponda ai controlli di integrità con uno stato non integro in determinati momenti. Ad esempio, potresti voler bloccare il traffico di previsione verso un nodo per un determinato periodo, in modo che il container possa eseguire la manutenzione.

Richieste di previsione

Quando un client invia una richiesta projects.locations.endpoints.predict all'API Vertex AI, Vertex AI inoltra questa richiesta come richiesta HTTP POST a un percorso di previsione configurabile sul tuo server. Specifica questo percorso nel campo containerSpec.predictRoute quando crei un Model. Per scoprire come il container può accedere a questo valore, leggi la sezione di questo documento sulla variabile di ambiente AIP_PREDICT_ROUTE.

Requisiti della richiesta

Se viene eseguito il deployment del modello su un endpoint pubblico, ogni richiesta di previsione deve avere dimensioni massime pari a 1,5 MB. Il server HTTP deve accettare richieste di previsione con l'intestazione HTTP Content-Type: application/json e corpi JSON con il formato seguente:

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

In queste richieste:

  • INSTANCES è un array di uno o più valori JSON di qualsiasi tipo. Ogni valore rappresenta un'istanza per la quale stai fornendo una previsione.

  • PARAMETERS è un oggetto JSON contenente i parametri necessari dal container per fornire previsioni sulle istanze. Vertex AI considera il campo parameters facoltativo, quindi puoi progettare il container in modo che lo richieda, utilizzarlo solo quando fornito o ignorarlo.

Scopri di più sui requisiti del corpo della richiesta.

Requisiti di risposta

Se viene eseguito il deployment del modello su un endpoint pubblico, ogni risposta di previsione deve avere dimensioni massime pari a 1,5 MB. Il server HTTP deve inviare risposte con corpi JSON che soddisfano il seguente formato:

{
  "predictions": PREDICTIONS
}

In queste risposte, sostituisci PREDICTIONS con un array di valori JSON che rappresentano le previsioni generate dal container per ciascuno degli INSTANCES nella richiesta corrispondente.

Dopo che il server HTTP invia questa risposta, Vertex AI aggiunge un campo deployedModelId alla risposta prima di restituirla al client. Questo campo specifica quale DeployedModel su una Endpoint sta inviando la risposta. Scopri di più sul formato del corpo della risposta.

Requisiti per la pubblicazione delle immagini container

Devi eseguire il push dell'immagine container in Artifact Registry per utilizzarla con Vertex AI. Scopri come eseguire il push di un'immagine container ad Artifact Registry.

In particolare, devi eseguire il push dell'immagine container in un repository che soddisfi i seguenti requisiti di località e autorizzazioni.

Località

Quando utilizzi Artifact Registry, il repository deve utilizzare una regione corrispondente all'endpoint a livello di regione in cui prevedi di creare un Model. Ad esempio, se prevedi di creare un Model nell'endpoint us-central1-aiplatform.googleapis.com, il nome completo dell'immagine container deve iniziare con us-central1-docker.pkg.dev/. Non utilizzare un repository multiregionale per l'immagine container.

Autorizzazioni

Vertex AI deve disporre dell'autorizzazione per eseguire il pull dell'immagine container quando crei un Model. In particolare, l'agente di servizio Vertex AI per il tuo progetto deve avere le autorizzazioni del ruolo Lettore Artifact Registry (roles/artifactregistry.reader) per il repository dell'immagine container.

L'agente di servizio Vertex AI per il tuo progetto è l'account di servizio gestito da Google che Vertex AI utilizza per interagire con altri servizi Google Cloud. Questo account di servizio ha l'indirizzo email service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, dove PROJECT_NUMBER viene sostituito con il numero di progetto del tuo progetto Vertex AI.

Se hai eseguito il push dell'immagine container nello stesso progetto Google Cloud in cui utilizzi Vertex AI, non devi configurare alcuna autorizzazione. Le autorizzazioni predefinite concesse all'agente di servizio Vertex AI sono sufficienti.

Se invece hai eseguito il push dell'immagine container su un progetto Google Cloud diverso da quello in cui utilizzi Vertex AI, devi concedere il ruolo di lettore Artifact Registry per il repository Artifact Registry all'agente di servizio Vertex AI.

Accedi agli artefatti del modello

Quando crei un oggetto Model con addestramento personalizzato senza un container personalizzato, devi specificare l'URI di una directory Cloud Storage con artefatti del modello come campo artifactUri. Quando crei un Model con un container personalizzato, fornire gli artefatti del modello in Cloud Storage è facoltativo.

Se l'immagine container include gli artefatti del modello necessari per gestire le previsioni, non è necessario caricare file da Cloud Storage. Tuttavia, se fornisci gli artefatti del modello specificando il campo artifactUri, il container deve caricare questi artefatti all'avvio. Quando Vertex AI avvia il container, imposta la variabile di ambiente AIP_STORAGE_URI su un URI Cloud Storage che inizia con gs://. Il comando del punto di ingresso del container può scaricare la directory specificata da questo URI per accedere agli artefatti del modello.

Tieni presente che il valore della variabile di ambiente AIP_STORAGE_URI non è identico all'URI Cloud Storage specificato nel campo artifactUri quando crei Model. Piuttosto, AIP_STORAGE_URI rimanda a una copia della directory degli artefatti del modello in un diverso bucket Cloud Storage, gestito da Vertex AI. Vertex AI completa questa directory quando crei un oggetto Model. Non puoi aggiornare i contenuti della directory. Se vuoi utilizzare nuovi artefatti del modello, devi creare un nuovo Model.

L'account di servizio utilizzato dal tuo container per impostazione predefinita ha l'autorizzazione di lettura da questo URI.

Se invece specifichi un account di servizio personalizzato quando esegui il deployment di Model in Endpoint, Vertex AI concede automaticamente all'account di servizio specificato il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) per il bucket Cloud Storage dell'URI.

Utilizza qualsiasi libreria che supporti Credenziali predefinite dell'applicazione (ADC) per caricare gli artefatti del modello. Non è necessario configurare esplicitamente l'autenticazione.

Variabili di ambiente disponibili nel container

Durante l'esecuzione, il comando del punto di ingresso del container può fare riferimento alle variabili di ambiente che hai configurato manualmente e alle variabili di ambiente impostate automaticamente da Vertex AI. Questa sezione descrive tutti i modi in cui puoi impostare le variabili di ambiente e fornisce dettagli sulle variabili impostate automaticamente da Vertex AI.

Variabili impostate nell'immagine container

Per impostare le variabili di ambiente nell'immagine container quando la crei, utilizza l'istruzione ENV di Docker. Non impostare variabili di ambiente che iniziano con il prefisso AIP_.

Il comando del punto di ingresso del container può utilizzare queste variabili di ambiente, ma non puoi farvi riferimento in nessuno dei campi dell'API di Model.

Variabili impostate da Vertex AI

Quando Vertex AI inizia a eseguire il container, imposta le seguenti variabili di ambiente nell'ambiente del container. Ogni variabile inizia con il prefisso AIP_. Non impostare manualmente variabili di ambiente che utilizzano questo prefisso.

Il comando del punto di ingresso del container può accedere a queste variabili. Per scoprire quali campi dell'API Vertex AI possono anche fare riferimento a queste variabili, leggi il riferimento API per ModelContainerSpec.

Nome variabile Valore predefinito Come configurare il valore Dettagli
AIP_ACCELERATOR_TYPE Non impostato Quando esegui il deployment di un elemento Model come DeployedModel in una risorsa Endpoint, imposta il campo dedicatedResources.machineSpec.acceleratorType. Se applicabile, questa variabile specifica il tipo di acceleratore utilizzato dall'istanza di macchina virtuale (VM) su cui è in esecuzione il container.
AIP_DEPLOYED_MODEL_ID Una stringa di cifre che identifica il campo DeployedModel in cui è stato eseguito il deployment di Model di questo container. Non configurabile Questo valore è il campo id di DeployedModel.
AIP_ENDPOINT_ID Una stringa di cifre che identifica Endpoint in cui è stato eseguito il deployment di Model del container. Non configurabile Questo valore è l'ultimo segmento del campo name di Endpoint (dopo endpoints/).
AIP_FRAMEWORK CUSTOM_CONTAINER Non configurabile
AIP_HEALTH_ROUTE /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL

In questa stringa, sostituisci ENDPOINT con il valore della variabile AIP_ENDPOINT_ID e sostituisci DEPLOYED_MODEL con il valore della variabile AIP_DEPLOYED_MODEL_ID.		 Quando crei un Model, imposta il campo containerSpec.healthRoute. Questa variabile specifica il percorso HTTP sul container a cui Vertex AI invia i controlli di integrità.
AIP_HTTP_PORT 8080 Quando crei un Model, imposta il campo containerSpec.ports. La prima voce in questo campo diventa il valore di AIP_HTTP_PORT. Vertex AI invia controlli di attività, controlli di integrità e richieste di previsione a questa porta del container. Il server HTTP del container deve rimanere in ascolto delle richieste su questa porta.
AIP_MACHINE_TYPE Nessun valore predefinito, deve essere configurato Quando esegui il deployment di un elemento Model come DeployedModel in una risorsa Endpoint, imposta il campo dedicatedResources.machineSpec.machineType. Questa variabile specifica il tipo di VM su cui è in esecuzione il container.
AIP_MODE PREDICTION Non configurabile Questa variabile indica che il container è in esecuzione su Vertex AI per fornire previsioni online. Puoi utilizzare questa variabile di ambiente per aggiungere una logica personalizzata al container, in modo che possa essere eseguita in più ambienti di computing, ma utilizzare solo determinati percorsi di codice su Vertex AI.
AIP_MODE_VERSION 1.0.0 Non configurabile Questa variabile indica la versione dei requisiti dei container personalizzati (questo documento) che Vertex AI si aspetta che il container soddisfi. Questo documento si aggiorna in base al controllo delle versioni semantico.
AIP_MODEL_NAME Il valore della variabile AIP_ENDPOINT_ID Non configurabile Vedi la riga AIP_ENDPOINT_ID. Questa variabile esiste per motivi di compatibilità.
AIP_PREDICT_ROUTE /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict

In questa stringa, sostituisci ENDPOINT con il valore della variabile AIP_ENDPOINT_ID e sostituisci DEPLOYED_MODEL con il valore della variabile AIP_DEPLOYED_MODEL_ID.		 Quando crei un Model, imposta il campo containerSpec.predictRoute. Questa variabile specifica il percorso HTTP sul container a cui Vertex AI inoltra le richieste di previsione.
AIP_PROJECT_NUMBER Il numero di progetto del progetto Google Cloud in cui utilizzi Vertex AI Non configurabile
AIP_STORAGE_URI
  • Se non imposti il campo artifactUri quando crei un Model: una stringa vuota
  • Se imposti il campo artifactUri quando crei un Model: un URI Cloud Storage (a partire da gs://) che specifica una directory in un bucket gestito da Vertex AI
 Non configurabile Questa variabile specifica la directory che contiene una copia degli artefatti del modello, se applicabile.
AIP_VERSION_NAME Il valore della variabile AIP_DEPLOYED_MODEL_ID Non configurabile Vedi la riga AIP_DEPLOYED_MODEL_ID. Questa variabile esiste per motivi di compatibilità.

Variabili impostate nella risorsa Model

Quando crei un elemento Model, puoi impostare altre variabili di ambiente nel campo containerSpec.env.

Il comando del punto di ingresso del container può accedere a queste variabili. Per scoprire quali campi dell'API Vertex AI possono anche fare riferimento a queste variabili, leggi il riferimento API per ModelContainerSpec.

Passaggi successivi