Requisiti dei container personalizzati per la previsione

Per utilizzare un container personalizzato in modo da ottenere previsioni da un modello con addestramento personalizzato, devi fornire a Vertex AI un'immagine container Docker che esegue un server HTTP. Questo documento descrive i requisiti che un'immagine contenitore deve soddisfare per essere compatibile con Vertex AI. Il documento descrive anche in che modo Vertex AI interagisce con il tuo contenitore personalizzato una volta avviato. In altre parole, questo documento descrive cosa devi prendere in considerazione quando progetti un'immagine contenitore da utilizzare con Vertex AI.

Per una procedura dettagliata sull'utilizzo di un'immagine container personalizzata per fornire le previsioni, consulta Utilizzo di un container personalizzato.

Requisiti delle immagini container

Quando l'immagine del container Docker viene eseguita come container, il container deve eseguire un server HTTP. Nello specifico, il container deve ascoltare e rispondere ai controlli di attività, ai controlli di integrità e alle richieste di previsione. Le seguenti sottosezioni descriveranno questi requisiti in dettaglio.

Puoi implementare il server HTTP in qualsiasi modo, 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 o 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'istruzione CMD o entrambe nel Dockerfile utilizzato 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 per sostituire rispettivamente ENTRYPOINT e CMD dell'immagine del contenitore. La specifica di uno di questi campi consente di utilizzare un'immagine contenitore che altrimenti non soddisferebbe i requisiti a causa di un ENTRYPOINT o CMD incompatibile (o inesistente).

Indipendentemente da come stabilisci quale comando viene eseguito dal container all'avvio, assicurati che questa istruzione ENTRYPOINT venga eseguita a tempo indeterminato. Ad esempio, non eseguire un comando che avvia un server HTTP in background ed esce. In questo caso, il contenuto del container uscirà immediatamente dopo l'avvio.

Il server HTTP deve ascoltare le richieste su 0.0.0.0, su una porta di tua scelta. Quando crei un Model, specifica questa porta nel containerSpec.ports campo. Per scoprire in che modo il contenitore può accedere a questo valore, leggi la sezione di questo documento relativa alla variabile di ambiente AIP_HTTP_PORT.

Controlli dell'attività

Vertex AI esegue un controllo di attivazione quando il contenitore si avvia per verificare che il server sia in esecuzione. Quando esegui il deployment di un modello con addestramento personalizzato in una risorsa Endpoint, Vertex AI utilizza un sondaggio di attività TCP per tentare di stabilire una connessione TCP al container sulla porta configurata. La sonda esegue fino a 4 tentativi di stabilire una connessione, aspettando 10 secondi dopo ogni errore. Se a questo punto il probe non ha ancora stabilito una connessione, Vertex AI riavvia il container.

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

Controlli di integrità

Se vuoi, puoi specificare startup_probe o health_probe.

Il probe di avvio controlla se l'applicazione del contenitore è stata avviata. Se non viene fornito il probe di avvio, non viene eseguito alcun probe di avvio e i controlli dell'integrità iniziano 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 precedenti che potrebbero richiedere un tempo di avvio aggiuntivo alla prima inizializzazione devono configurare un controllo di avvio. Ad esempio, se l'applicazione deve copiare gli elementi del modello da un'origine esterna, deve essere configurata una prova di avvio per restituire il risultato positivo al termine dell'inizializzazione.

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

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

Per eseguire una sonda, Vertex AI esegue il comando exec specificato nel contenitore 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 intermittentemente controlli di integrità sul server HTTP mentre è in esecuzione per assicurarsi che sia pronto a gestire le richieste di previsione. Il servizio utilizza un probe di integrità per inviare richieste HTTP GET a un percorso di controllo di integrità configurabile sul server. Specifica questo percorso nel containerSpec.healthRoute campo quando crei un Model. Per scoprire in che modo il contenitore può accedere a questo valore, leggi la sezione di questo documento relativa alla 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 a gestire le richieste di previsione, non rispondere alla richiesta di controllo di integrità entro 10 secondi o rispondi con un codice di stato diverso da 200 OK. Ad esempio, rispondi con il codice di stato 503 Service Unavailable.

    Questa risposta (o la mancanza di una risposta) indica che il server non è in stato operativo.

Se il probe di integrità riceve una risposta non corretta dal 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 ancora il tuo server integro. Se il probe riceve una risposta corretta a uno di questi controlli, torna immediatamente alla sua pianificazione intermittente dei controlli di integrità. Tuttavia, se il probe riceve 4 risposte consecutive non attive, Vertex AI interrompe il routing del traffico di previsione al contenitore. Se la risorsa DeployedModel è scalata per l'utilizzo di più nodi di previsione, Vertex AI inoltra le richieste di previsione ad altri container funzionanti.

Vertex AI non riavvia il contenitore, ma il probe di integrità continua a inviare richieste di controllo di integrità intermittenti al server non integro. Se riceve una risposta positiva, contrassegna il contenitore come integro e inizia a reindirizzare nuovamente il traffico di previsione.

Indicazioni pratiche

In alcuni casi, è sufficiente che il server HTTP nel contenitore risponda sempre con il codice di stato 200 OK ai controlli di salute. Se il contenitore carica le risorse prima di avviare il server, il contenitore non è in stato corretto durante il periodo di avvio e durante i periodi in cui il server HTTP non funziona. In tutti gli altri casi, risponde come se fosse in buone condizioni.

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

Richieste di previsione

Quando un client invia una projects.locations.endpoints.predict richiesta all' API Vertex AI, Vertex AI la inoltra come richiesta HTTPPOST a un percorso di previsione configurabile sul tuo server. Specifica questo percorso nel campo containerSpec.predictRoute quando crei un Model. Per scoprire in che modo il contenitore può accedere a questo valore, consulta la sezione di questo documento relativa alla variabile di ambiente AIP_PREDICT_ROUTE.

Requisiti delle richieste

Se il modello viene implementato in un endpoint pubblico, ogni richiesta di previsione deve avere dimensioni massime pari a 1,5 MB. Il server HTTP deve accettare richieste di previsione che abbiano l'intestazione HTTP Content-Type: application/json e i relativi testi JSON nel seguente formato:

{
  "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 tutti i parametri richiesti dal tuo contenitore per contribuire a fornire le previsioni sulle istanze. Vertex AI considera facoltativo il campo parameters, pertanto puoi progettare il contenitore in modo che lo richieda, utilizzarlo solo se fornito o ignorarlo.

Scopri di più sui requisiti del corpo della richiesta.

Requisiti di risposta

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

{
  "predictions": PREDICTIONS
}

In queste risposte, sostituisci PREDICTIONS con un array di valori JSON rappresentanti le previsioni generate dal contenitore per ogni INSTANCES nella richiesta corrispondente.

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

Requisiti per la pubblicazione di immagini container

Per poter utilizzare l'immagine container con Vertex AI, devi eseguirne il push in Artifact Registry. Scopri come eseguire il push di un'immagine container in Artifact Registry.

In particolare, devi eseguire il push dell'immagine container in un repository che soddisfi i seguenti requisiti relativi a autorizzazioni e posizione.

Località

Quando utilizzi Artifact Registry, il repository deve utilizzare una regione corrispondente all'endpoint regionale in cui prevedi di creare un Model. Ad esempio, se prevedi di creare un Model sull'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 estrarre l'immagine container quando crei un Model. Nello specifico, l'agente di servizio Vertex AI per il tuo progetto deve avere le autorizzazioni del ruolo Lettore di Artifact Registry (roles/artifactregistry.reader) per il repository dell'immagine container.

Vertex AI utilizza l'agente di servizio Vertex AI per il progetto 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 del progetto del tuo progetto Vertex AI.

Se hai eseguito il push dell'immagine del contenitore 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.

D'altra parte, se hai eseguito il push dell'immagine del contenitore in un progetto Google Cloud diverso da quello in cui utilizzi Vertex AI, devi concedere il ruolo Lettore di Artifact Registry per il repository Artifact Registry all'agente di servizio Vertex AI.

Accedere agli elementi del modello

Quando crei un Model addestrato in modo personalizzato senza un contenitore personalizzato, devi specificare l'URI di una directory Cloud Storage con gli elementi del modello come artifactUri campo. Quando crei un Model con un contenitore personalizzato, la fornitura degli artefatti del modello in Cloud Storage è facoltativa.

Se l'immagine del contenitore include gli elementi del modello necessari per fornire le previsioni, non è necessario caricare i file da Cloud Storage. Tuttavia, se fornisci gli elementi del modello specificando il campo artifactUri, il contenitore deve caricarli 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://. L'istruzione ENTRYPOINT del contenitore può scaricare la directory specificata da questo URI per accedere agli elementi 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. Al contrario, AIP_STORAGE_URI fa riferimento a una copia della directory degli artefatti del modello in un altro bucket Cloud Storage, gestito da Vertex AI. Vertex AI compila questa directory quando crei un Model. Non puoi aggiornare i contenuti della directory. Se vuoi utilizzare nuovi elementi del modello, devi creare un nuovo Model.

L'account di servizio utilizzato per impostazione predefinita dal contenitore dispone dell'autorizzazione di lettura da questo URI.

D'altra parte, se specifichi un account di servizio personalizzato quando esegui il deployment del Model in un 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 supporta le Credenziali predefinite dell'applicazione (ADC) per caricare gli artefatti del modello. Non è necessario configurare esplicitamente l'autenticazione.

Variabili di ambiente disponibili nel contenitore

Durante l'esecuzione, l'istruzione ENTRYPOINT del contenitore può fare riferimento alle variabili di ambiente configurate manualmente, nonché 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 del contenitore

Per impostare le variabili di ambiente nell'immagine del contenitore durante la compilazione, utilizza l'ENV istruzione di Docker. Non impostare variabili di ambiente che iniziano con il prefisso AIP_.

L'istruzione ENTRYPOINT del contenitore può utilizzare queste variabili di ambiente, ma non puoi farvi riferimento in nessuno dei campi dell'API Model.

Variabili impostate da Vertex AI

Quando Vertex AI avvia l'esecuzione del 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.

L'istruzione ENTRYPOINT del contenitore può accedere a queste variabili. Per scoprire quali campi dell'API Vertex AI possono fare riferimento anche a queste variabili, consulta il riferimento all'API per ModelContainerSpec.

Nome variabile Valore predefinito Come configurare il valore Dettagli
AIP_ACCELERATOR_TYPE Non impostato Quando esegui il deployment di un Model come DeployedModel in una risorsa Endpoint, imposta il dedicatedResources.machineSpec.acceleratorType campo. Se applicabile, questa variabile specifica il tipo di acceleratore utilizzato dall'istanza della macchina virtuale (VM) su cui è in esecuzione il contenitore.
AIP_DEPLOYED_MODEL_ID Una stringa di cifre che identifica il DeployedModel su cui è stato eseguito il deployment del Model di questo contenitore. Non configurabile Questo valore è il id campo di DeployedModel.
AIP_ENDPOINT_ID Una stringa di cifre che identifica il Endpoint su cui è stato disegnato il Model del contenitore. Non configurabile Questo valore è l'ultimo segmento del name campo 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 DEPLOYED_MODEL con il valore della variabile AIP_DEPLOYED_MODEL_ID.		 Quando crei un Model, imposta il containerSpec.healthRoute campo. Queste variabili specificano il percorso HTTP sul contenitore a cui Vertex AI invia i controlli di integrità.
AIP_HTTP_PORT 8080 Quando crei un Model, imposta il containerSpec.ports campo. 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 tuo 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 Model come DeployedModel in una risorsa Endpoint, imposta il dedicatedResources.machineSpec.machineType campo. Questa variabile specifica il tipo di VM su cui è in esecuzione il contenitore.
AIP_MODE PREDICTION Non configurabile Questa variabile indica che il contenitore è in esecuzione su Vertex AI per fornire previsioni online. Puoi utilizzare questa variabile di ambiente per aggiungere logica personalizzata al contenitore, in modo che possa essere eseguito in più ambienti di calcolo, ma utilizzi solo determinati percorsi di codice quando viene eseguito su Vertex AI.
AIP_MODE_VERSION 1.0.0 Non configurabile Questa variabile indica la versione dei requisiti del contenitore personalizzato (questo documento) che Vertex AI si aspetta che il contenitore soddisfi. Questo documento viene aggiornato in base al versionamento semantico.
AIP_MODEL_NAME Il valore della variabile AIP_ENDPOINT_ID Non configurabile Consulta 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 DEPLOYED_MODEL con il valore della variabile AIP_DEPLOYED_MODEL_ID.		 Quando crei un Model, imposta il containerSpec.predictRoute campo. Questa variabile specifica il percorso HTTP nel contenitore a cui Vertex AI inoltra le richieste di previsione.
AIP_PROJECT_NUMBER Il numero del 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 (che inizia con gs://) che specifica una directory in un bucket gestito da Vertex AI
 Non configurabile Questa variabile specifica la directory che contiene una copia degli elementi del modello, se applicabile.
AIP_VERSION_NAME Il valore della variabile AIP_DEPLOYED_MODEL_ID Non configurabile Consulta la riga AIP_DEPLOYED_MODEL_ID. Questa variabile esiste per motivi di compatibilità.

Variabili impostate nella risorsa Model

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

L'istruzione ENTRYPOINT del contenitore può accedere a queste variabili. Per scoprire quali campi dell'API Vertex AI possono fare riferimento anche a queste variabili, consulta il riferimento all'API per ModelContainerSpec.

Passaggi successivi