Requisiti dei container personalizzati per la previsione

Per utilizzare un container personalizzato per fornire previsioni da un modello di addestramento personalizzato, devi fornire a Vertex AI con un'immagine del 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 inoltre in che modo l'IA Vertex interagisce con il tuo container personalizzato una volta che è in esecuzione. In altre parole, questo documento descrive ciò che devi considerare quando progetti un'immagine container da utilizzare con Vertex AI.

Per informazioni sull'utilizzo di un'immagine container personalizzata per fornire previsioni, leggi Utilizzo di un contenitore personalizzato.

Requisiti per le immagini container

Quando l'immagine del container Docker viene eseguita come container, il container deve eseguire un server HTTP. In particolare, il container deve ascoltare e rispondere a controlli di vita, controlli di integrità e richieste di previsione. Le seguenti sottosezioni illustrano in dettaglio questi requisiti.

Puoi implementare il server HTTP in qualsiasi modo, utilizzando qualsiasi linguaggio di programmazione, purché soddisfi i requisiti di questa sezione. Ad esempio, puoi scrivere un server HTTP personalizzato utilizzando un framework web come Flask o utilizzare un software di machine learning (ML) che esegue un server HTTP, ad esempio TensorFlow Elaborazione, TorchServe o KFserving server.

Esecuzione del server HTTP

Puoi eseguire un server HTTP utilizzando un'istruzione ENTRYPOINT, un'istruzione CMD o entrambi nel Dockerfile che utilizzi per creare l'immagine container. Leggi ulteriori informazioni sull'interazione tra CMD e ENTRYPOINT.

In alternativa, puoi specificare i campi containerSpec.command e containerSpec.args quando crei la risorsa Model per eseguire l'override dell'immagine del container ENTRYPOINT e CMD rispettivamente. Specificando uno di questi campi puoi utilizzare un'immagine container che non soddisfa i requisiti a causa di un valore ENTRYPOINT o CMD non compatibile.

Tuttavia, stabilisci il comando all'avvio del container, assicurati che questo comando entrypoint venga eseguito a tempo indeterminato. Ad esempio, non eseguire un comando che avvia un server HTTP in background e quindi esce; in caso contrario, il container verrà chiuso subito dopo l'avvio dell'esecuzione.

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

Controlli di vita

Vertex AI esegue un controllo di vita all'avvio del container per garantire che il server sia in esecuzione. Quandoeseguire il deployment di un modello personalizzato perEndpoint risorsa , l'IA Vertex utilizza unInvecchiamento della vita CPP per tentare di stabilire una connessione TCP al contenitore sulla porta configurata. La sfilata esegue fino a 4 tentativi per stabilire una connessione, aspettando 10 secondi dopo ogni errore. Se a questo punto la staging non è stata ancora stabilita una connessione, Vertex AI riavvia il container.

Il server HTTP non deve necessariamente eseguire un comportamento speciale per gestire questi controlli. Mentre ascolta le richieste sulla porta configurata, la probe di attività è in grado di stabilire una connessione.

Controlli di integrità

Vertex AI esegue in modo intermittente l'integrità dei controlli di integrità sul tuo server HTTP durante l'esecuzione per assicurarsi che sia pronto per 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 tuo server. Specifica questo percorso nel campo containerSpec.healthRoute quando crei un Model. Per ulteriori informazioni su come il container può accedere a questo valore, leggi la sezione di questo documento sulla variabile AIP_HEALTH_ROUTE dell'ambiente.

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

  • Se il server è pronto per 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 importa; Vertex AI ignora il suo nome.

    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 e non rispondere con un codice di stato, tranne 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 è integro.

Se la sferenza sanitaria riceve al server una risposta in stato non integro (senza risposta entro 10 secondi), invia fino a 3 controlli di integrità aggiuntivi a 10 secondi. Durante questo periodo, l'IA di Vertex prende in considerazione il tuo server in modo integro. Se la ricezione riceve una risposta soddisfacente a uno di questi controlli, la stregua immediatamente torna alla programmazione intermittente dei controlli di integrità. Tuttavia, se la ricezione riceve 4 risposte consecutive allo stato non integro, Vertex AI interrompe il routing del traffico di previsione al container. Se la risorsa DeployedModel viene scalata per utilizzare più nodi di previsione, il Vertex AI indirizzerà le richieste di previsione ad altri container sani.

L'IA Vertex non riavvia il container. la sferenza sanitaria continua a inviare richieste di controllo di integrità intermittente al server non integro. Se riceve una risposta in buone condizioni, contrassegna il contenitore come integro e inizia a instradare nuovamente il traffico di previsione.

Istruzioni pratiche

In alcuni casi, è sufficiente per il server HTTP del container di rispondere sempre ai codici di stato 200 OK per i controlli di integrità. Se il container carica le risorse prima di avviare il server, il container rimane in stato integro durante il periodo di avvio e durante i periodi in cui il server HTTP ha esito negativo. In qualsiasi altro momento, la risposta diventa salutare.

Per una configurazione più sofisticata, potresti voler progettare un server HTTP per rispondere ai controlli di integrità con uno stato non integro in determinati orari. Ad esempio, potresti voler bloccare il traffico di previsione per un nodo per un 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 la 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 informazioni su come il contenitore può accedere a questo valore, leggila sezione di questo documento suiAIP_PREDICT_ROUTE variabile di ambiente sul dispositivo mobile.

Requisiti per le richieste

Ogni richiesta di previsione non deve superare 1,5 MB. Il server HTTP deve accettare le richieste di previsione che contengono laContent-Type: application/json Le intestazioni HTTP e JSON con il 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 cui stai fornisce una previsione.

  • PARAMETERS è un oggetto JSON che contiene tutti i parametri che il tuo container richiede per supportare le previsioni sulle istanze. Vertex AI prende in considerazione il campo parameters facoltativo, quindi puoi progettare il container in modo che venga richiesto, utilizzarlo solo quando fornito o ignorarlo.

Leggi ulteriori informazioni sui requisiti del corpo delle richieste.

Requisiti per la risposta

Ogni risposta di previsione deve avere una dimensione massima di 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 tuo 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 DeployedModel su Endpoint che sta inviando la risposta. Ulteriori informazioni sul formato del corpo della risposta.

Requisiti per la pubblicazione di immagini container

Devi eseguire il push dell'immagine del container in Artifact Registry o in Container Registry per poterla utilizzare con Vertex AI. Scopri come eseguire il push di un'immagine container a Artifact Registry o come inviare un'immagine container a Container Registry.

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

Località

Se utilizzi Artifact Registry, il repository deve utilizzare un'area geografica corrispondente all'endpoint dell'area geografica in cui intendi creare un Model. Ad esempio, se prevedi di creare un Model nell'endpoint us-central1-aiplatform.googleapis.com, il nome completo dell'immagine del container deve iniziare con us-central1-docker.pkg.dev/. Non utilizzare un repository per più aree geografiche per l'immagine del container.

Se utilizzi Container Registry, il tuo repository può utilizzare qualsiasi nome host di Container Registry.

Autorizzazioni

L'IA Vertex deve disporre dell'autorizzazione per eseguire il pull dell'immagine del container quando crei un Model. In particolare:

L'agente di servizio AItex AI per il tuo progetto è l'account di servizio gestito da Google che l'IA di Vertex 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 progetto Vertex AI.

Se hai trasferito l'immagine del 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.

D'altra parte, se hai trasferito l'immagine del container in un altro progetto Google Cloud da quello in cui utilizzi Vertex AI, devi concedere il ruolo Lettore Artifact Registry per Artifact Registry. repository all'agente di servizio Vertex AI o a concedere il ruolo Visualizzatore oggetti Storage per il bucket Cloud Storage utilizzato da Container Registry per l'IA Vertex AI Agente di servizio.

Accesso agli artefatti dei modelli

Quando crei un modello di formazione personalizzatoModel senza un container personalizzato, devi specificare l'URI di una directory di Cloud Storage conmodellini comeartifactUri campo sul dispositivo mobile. Quando crei un Model con un container personalizzato, l'indicazione degli artefatti del modello in Cloud Storage è facoltativa.

Se l'immagine container include gli elementi del modello di cui hai bisogno per pubblicare le previsioni, non è necessario caricare i file da Cloud Storage. Tuttavia, se fornisci elementi del modello specificando il campo artifactUri, il contenitore deve caricarlo al momento dell'avvio. Quando Vertex AI avvia il container, imposta la variabile di ambiente AIP_STORAGE_URI su un URI di Cloud Storage che inizia con gs://. Il comando entrypoint 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 di Cloud Storage specificato nel campo artifactUri quando crei il valore Model. AIP_STORAGE_URI si riferisce invece a una copia della directory di artefatti del tuo modello in un diverso bucket Cloud Storage gestito da Vertex AI. Quando crei una Model, l'IA Vertex inserisce questa directory. Non puoi aggiornare i contenuti della directory. Se vuoi usare nuovi elementi modelli, devi creare un nuovo Model.

L'account di servizio utilizzato dal container per impostazione predefinita è autorizzato a leggere da questo URI.

D'altra parte, se specifichi un account di servizio personalizzato quando esegui il deployment di Model su Endpoint, Vertex AI concede automaticamente il servizio specificato account il ruolo Visualizzatore oggetti di archiviazione (roles/storage.objectViewer) per il bucket Cloud Storage dell'URI.

Utilizza qualsiasi libreria che supporti le credenziali predefinite dell'applicazione (ADC) per caricare gli elementi del modello; non è necessario configurare l'autenticazione in modo esplicito.

Variabili di ambiente disponibili nel container

Durante l'esecuzione, il comando entrypoint del container può fare riferimento alle variabili di ambiente configurate manualmente e alle variabili di ambiente impostate automaticamente da Vertex AI. Questa sezione descrive ogni modo per impostare le variabili di ambiente e fornisce dettagli sulle variabili impostate automaticamente da Vertex AI.

Variabili impostate nell'immagine del container

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

Il comando entrypoint del container può utilizzare queste variabili di ambiente, ma non puoi farvi riferimento in uno dei campi API del tuo 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 le variabili di ambiente che usano questo prefisso.

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

Nome variabile Valore predefinito Come configurare il valore Dettagli
AIP_ACCELERATOR_TYPE Non impostata Quando esegui il deployment di un Model come DeployedModel su 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 DeployedModel a cui è stato eseguito il deployment del Model di questo container. Non configurabile Questo valore è il campo id di DeployedModel.
AIP_ENDPOINT_ID Una stringa di cifre che identifica il Endpoint su cui è stato eseguito il deployment del Model del container. Non configurabile Questo valore è l'ultimo segmento del campo name di Endpoint (seguito dal giorno endpoints/).
ALLEGATO CUSTOM_CONTAINER Non configurabile
AIP_STOPS_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 di la variabile AIP_DEPLOYED_MODEL_ID.
Quando crei un Model, imposta il campo containerSpec.healthRoute. Questa variabile specifica il percorso HTTP nel container a cui l'IA Vertex invia i controlli di integrità.
AIP_HTTP_PORTAL 8080 Quando crei un Model, imposta il campo containerSpec.ports. La prima voce in questo campo diventa il valore di AIP_HTTP_PORT. L'IA Vertex invia controlli di integrità, controlli di integrità e richieste di previsione a questa porta sul container. Il server HTTP del container deve rimanere in ascolto delle richieste su questa porta.
AIP_MACHINE_TYPE Non predefinito, deve essere configurata Quando esegui il deployment di un Model come DeployedModel su una risorsa Endpoint, imposta il campo dedicatedResources.machineSpec.machineType. Questa variabile specifica il tipo di VM su cui viene eseguito il container.
AIP_MODE PREDICTION Non configurabile Questa variabile indica che il container è in esecuzione su Vertex AI per elaborare le previsioni online. Puoi utilizzare questa variabile di ambiente per aggiungere logica personalizzata al tuo container in modo che possa essere eseguita in più ambienti di elaborazione, ma utilizza solo determinati percorsi di codice quando viene eseguita su Vertex AI.
AIP_MODE_VERSION 1.0.0 Non configurabile Questa variabile indica la versione dei requisiti personalizzati del container (questo documento) che Vertex AI prevede che il container soddisfi. Questo documento si aggiorna in base al controllo della versione semantica.
AIP_MODEL_NAME Il valore della variabile AIP_ENDPOINT_ID Non configurabile Vedi la riga AIP_ENDPOINT_ID. Questa variabile è presente per i motivi di compatibilità.
PRIMO_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 di la variabile AIP_DEPLOYED_MODEL_ID.
Quando crei un Model, imposta il campo containerSpec.predictRoute. Questa variabile specifica il percorso HTTP nel container che Vertex AIinoltra 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 di Cloud Storage (che inizia con gs://) specificando una directory in un bucket gestito da Vertex AI
Non configurabile Questa variabile specifica la directory che contiene una copia degli elementi del tuo 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 Model, puoi impostare variabili di ambiente aggiuntive nel campo containerSpec.env.

Il comando entrypoint del container può accedere a queste variabili. Per sapere quali campi API Vertex AI possono fare riferimento a queste variabili, leggi il riferimento di API per ModelContainerSpec.

Passaggi successivi