Requisiti dei container personalizzati per la previsione

Per utilizzare un container personalizzato al fine di fornire previsioni da un modello con addestramento personalizzato, deve fornire a Vertex AI un'immagine container Docker che esegue o server web. Questo documento descrive i requisiti che un'immagine container deve per la compatibilità con Vertex AI. Il documento descrive inoltre come Vertex AI interagisce con il container personalizzato all'avvio in esecuzione. In altre parole, il presente documento descrive gli aspetti da considerare per la progettazione di un'immagine container da usare con Vertex AI.

Per informazioni dettagliate sull'utilizzo di un'immagine container personalizzata per la pubblicazione di previsioni, consulta Utilizzare un container personalizzato.

Requisiti delle immagini container

Quando l'immagine container Docker viene eseguita come container, quest'ultimo deve eseguire HTTP(S). Nello specifico, il container deve ascoltare e rispondere all'attività controlli di integrità, controlli di integrità e richieste di previsione. Le seguenti sottosezioni a descrivere questi requisiti in dettaglio.

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

Esegui il server HTTP.

Puoi eseguire un server HTTP utilizzando un file ENTRYPOINT istruzione, un CMD istruzioni, nel Dockerfile che usi per creare l'immagine container. Informazioni l'interazione tra CMD e ENTRYPOINT.

In alternativa, puoi specificare il campo containerSpec.command e containerSpec.args quando crei la risorsa Model per eseguire l'override del tuo container rispettivamente ENTRYPOINT e CMD dell'immagine. Se specifichi uno di questi campi, si utilizza un'immagine container che altrimenti non soddisferebbe i requisiti a causa un ENTRYPOINT o CMD incompatibile (o inesistente).

Indipendentemente da quale sia il comando eseguito dal container all'avvio, assicurati che l'istruzione ENTRYPOINT venga eseguita all'infinito. Ad esempio, non eseguire un comando che avvia un server HTTP in background e poi si chiude; Se lo fai, il container uscirà subito dopo l'avvio.

Il tuo server HTTP deve rimanere in ascolto delle richieste su 0.0.0.0, su una porta del tuo scelta. Quando crei una Model, specifica questa porta nel containerSpec.ports . Per informazioni su come il contenitore può accedere a questo valore, leggi la sezione di questo documento sulla variabile di ambiente AIP_HTTP_PORT.

Controlli di attività

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

Il tuo server HTTP non deve eseguire alcun comportamento speciale per gestire questi controlli. Finché resta in ascolto delle 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 container è stata avviata. Se il probe di avvio non è fornito, non sono presenti probe di avvio e controlli di integrità iniziano immediatamente. Se viene fornito il probe di avvio, i controlli di integrità non vengono eseguiti. fino al completamento del probe di avvio.

Applicazioni legacy che potrebbero richiedere tempi di avvio aggiuntivi la prima volta l'inizializzazione deve configurare un probe di avvio. Ad esempio, se l'applicazione deve copiare gli artefatti del modello da un'origine esterna, deve essere configurato in modo da restituire l'esito positivo al termine dell'inizializzazione.

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

Applicazioni legacy che non restituiscono 200 OK per indicare che il modello è caricato e pronto ad accettare il traffico, devono configurare un probe di integrità. Ad esempio, un l'applicazione potrebbe restituire 200 OK per indicare l'esito positivo anche se l'effettiva Lo stato di caricamento del modello presente nel corpo della risposta indica che il modello potrebbe non è stato caricato e potrebbe quindi non essere pronto ad accettare il traffico. In questo caso, un il probe di integrità deve essere configurato in modo da restituire l'esito positivo solo quando il modello caricati e pronti a 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 un 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 assicurarti che sia pronto a gestire le richieste di previsione. Il servizio utilizza un probe di integrità per inviare richieste GET HTTP a un del controllo di integrità sul server. Specifica questo percorso nel containerSpec.healthRoute campo quando crei un Model. Per scoprire in che modo il container può accedere a questo valore, leggi la sezione di questo documento sull'ambiente AIP_HEALTH_ROUTE la variabile personalizzata.

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 al prompt. richiesta di controllo di integrità entro 10 secondi con codice di stato 200 OK. I contenuti del corpo di risposta non contano; 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 rispondere con un codice di stato tranne 200 OK. Ad esempio, rispondi con un 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 l'assenza di risposta entro 10 secondi), invia fino a 3 di integrità a intervalli di 10 secondi. Durante questo di tanto in tanto, Vertex AI considera comunque il tuo server integro. Se la sonda riceve una risposta integro a uno qualsiasi di questi controlli, il probe torna alla sua programmazione intermittente di controlli di integrità. Tuttavia, se il probe riceve 4 risposte in stato non integro consecutive, Vertex AI si arresta l'indirizzamento del traffico di previsione al container. (Se la risorsa DeployedModel è scalato per l'uso di più nodi di previsione, route di Vertex AI richieste di previsione ad altri container integri).

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

Indicazioni pratiche

In alcuni casi, è sufficiente che il server HTTP nel tuo contenitore abbia sempre rispondi con il codice di stato 200 OK ai controlli di integrità. Se il container carica prima di avviare il server, il container non è integro durante e durante i periodi in cui si verifica un errore del server HTTP. Tutti gli altri volte, risponde in modo sano.

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

Richieste di previsione

Quando un cliente invia un projects.locations.endpoints.predict richiesta alla API Vertex AI, Vertex AI inoltra questa richiesta come HTTP Richiesta POST a un percorso di previsione configurabile sul tuo server. Specifica questo percorso in containerSpec.predictRoute campo quando crei un Model. Per informazioni su come il container può accedere consulta la sezione di questo documento relativa all'attributo AIP_PREDICT_ROUTE variabile di ambiente.

Requisiti per le richieste

Se il modello viene distribuito in un endpoint pubblico, ogni richiesta di previsione deve essere Massimo 1,5 MB. Il server HTTP deve accettare le richieste di previsione con l'intestazione HTTP Content-Type: application/json e il corpo JSON con seguente formato:

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

In queste richieste:

  • INSTANCES è un array di uno o più valori JSON di qualsiasi tipo. Ciascuna rappresenta un'istanza per cui stai fornendo una previsione.

  • PARAMETERS è un oggetto JSON contenente qualsiasi parametro che il tuo per semplificare la generazione di previsioni sulle istanze. Vertex AI considera il campo parameters facoltativo, quindi puoi progetta il tuo container in modo da richiederlo, usalo solo se fornito o ignoralo.

Scopri di più sui requisiti del corpo della richiesta.

Requisiti per la risposta

Se il modello viene distribuito in un endpoint pubblico, ogni risposta della previsione deve essere Massimo 1,5 MB. Il server HTTP deve inviare le 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 dei INSTANCES nella richiesta corrispondente.

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

Requisiti di pubblicazione delle immagini container

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

In particolare, devi eseguire il push dell'immagine container a un repository che soddisfi le i requisiti relativi a località e autorizzazioni.

Località

Quando utilizzi Artifact Registry, il repository deve utilizzare un regione che corrisponde endpoint regionale in cui prevedi di creare un Model. Ad esempio, se prevedi di creare un Model nella Endpoint us-central1-aiplatform.googleapis.com, il nome completo del tuo l'immagine container deve iniziare con us-central1-docker.pkg.dev/. Non utilizzare un in più regioni per la tua immagine container.

Autorizzazioni

Vertex AI deve disporre dell'autorizzazione per eseguire il pull dell'immagine container crea un Model. Nello specifico, l'agente di servizio Vertex AI per il progetto deve disporre delle autorizzazioni del ruolo Lettore Artifact Registry (roles/artifactregistry.reader) per il repository dell'immagine container.

Vertex AI utilizza l'agente di servizio Vertex AI per interagire con il tuo progetto e altri servizi Google Cloud. Questo account di servizio ha l'indirizzo email service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, dove PROJECT_NUMBER è sostituito dal progetto numero 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 autorizzazioni aggiuntive. Le autorizzazioni predefinite concesse all'agente di servizio Vertex AI sono sufficienti.

Se invece hai eseguito il push dell'immagine container a un'altra progetto Google Cloud da quello in cui utilizzi Vertex AI, devi concedere il ruolo Lettore Artifact Registry per Artifact Registry repository tramite l'agente di servizio Vertex AI.

Accedi agli artefatti del modello

Quando crei un Model con addestramento personalizzato senza un container personalizzato, devi: specifica l'URI di una directory Cloud Storage con model artefatti come artifactUri . Quando crei un Model con un container personalizzato, fornendo artefatti del modello in Cloud Storage è facoltativo.

Se l'immagine container include gli artefatti del modello che devi pubblicare non è necessario caricare file da Cloud Storage. Tuttavia, se fornisci gli artefatti del modello specificando artifactUri , il container deve caricare questi artefatti all'avvio dell'esecuzione. Quando Vertex AI avvia il container, imposta il AIP_STORAGE_URI a un URI Cloud Storage che inizia con gs://. L'istruzione ENTRYPOINT del container può scaricare la directory specificata da questo 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 nella artifactUri quando crei il Model. Piuttosto, AIP_STORAGE_URI punta a una copia della directory dell'artefatto del modello in un in un altro bucket Cloud Storage gestito da Vertex AI. Vertex AI compila questa directory quando crei un Model. Non puoi aggiornare il contenuto della directory. Se vuoi usare un nuovo modello devi creare un nuovo elemento Model.

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

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

Utilizza qualsiasi libreria che supporti le impostazioni Impostazioni predefinite dell'applicazione (ADC) per caricare artefatti del modello; non devi configurare esplicitamente l'autenticazione.

Variabili di ambiente disponibili nel container

Durante l'esecuzione, l'istruzione ENTRYPOINT del container può fare riferimento all'ambiente le variabili configurate manualmente, nonché le variabili di ambiente viene impostata automaticamente da Vertex AI. Questa sezione descrive ogni modo che ti consente di impostare le variabili di ambiente, oltre a fornire dettagli impostate automaticamente da Vertex AI.

Variabili impostate nell'immagine container

Per impostare le variabili di ambiente nell'immagine container quando la crei, utilizza ENV di Docker istruzioni per l'uso. 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 nessuna delle API di Model campi.

Variabili impostate da Vertex AI

Quando Vertex AI avvia l'esecuzione del container, imposta quanto segue variabili di ambiente nell'ambiente del container. Ogni variabile inizia con il prefisso AIP_. Non impostare manualmente le variabili di ambiente che utilizzano questo metodo .

L'istruzione ENTRYPOINT del contenitore può accedere a queste variabili. Per sapere quali I campi dell'API Vertex AI possono anche fare riferimento a queste variabili. Leggi Riferimento API per ModelContainerSpec.

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

In questa stringa, sostituisci ENDPOINT con il valore del AIP_ENDPOINT_ID e sostituisci DEPLOYED_MODEL con il valore AIP_DEPLOYED_MODEL_ID.		 Quando crei un Model, imposta il containerSpec.healthRoute . Questa variabile specifica il percorso HTTP sul container Vertex AI invia controlli di integrità a.
AIP_HTTP_PORT 8080 Quando crei un Model, imposta il containerSpec.ports . La prima voce in questo campo diventa il valore AIP_HTTP_PORT. Vertex AI invia controlli di attività, controlli di integrità e a questa porta sul container. HTTP del container il server deve rimanere in ascolto delle richieste su questa porta.
AIP_MACHINE_TYPE Nessun valore predefinito, deve essere configurato Quando esegui il deployment di Model come DeployedModel a una risorsa Endpoint, imposta il valore dedicatedResources.machineSpec.machineType . Questa variabile specifica il tipo di VM in esecuzione dal container attiva.
AIP_MODE PREDICTION Non configurabile Questa variabile indica che il container è in esecuzione su Vertex AI per fornire previsioni online. Puoi utilizzare questo variabile di ambiente per aggiungere logica personalizzata al container, può essere eseguito in più ambienti di elaborazione, ma utilizza solo un certo codice quando vengono eseguiti su Vertex AI.
AIP_MODE_VERSION 1.0.0 Non configurabile Questa variabile indica la versione del container personalizzato (questo documento) che Vertex AI prevede containerizzato. Questo documento viene aggiornato in base al controllo delle versioni semantico.
AIP_MODEL_NAME Il valore della variabile AIP_ENDPOINT_ID Non configurabile Visualizza la riga AIP_ENDPOINT_ID. Questa variabile esiste per per motivi di compatibilità.
AIP_PREDICT_ROUTE /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict

In questa stringa, sostituisci ENDPOINT con il valore del AIP_ENDPOINT_ID e sostituisci DEPLOYED_MODEL con il valore AIP_DEPLOYED_MODEL_ID.		 Quando crei un Model, imposta il containerSpec.predictRoute . Questa variabile specifica il percorso HTTP sul container Vertex AI inoltra le previsioni richieste.
AIP_PROJECT_NUMBER Il progetto numero del progetto Google Cloud in cui stai utilizzando Vertex AI Non configurabile
AIP_STORAGE_URI
  • Se non imposti artifactUri quando crei un Model: un campo vuoto stringa
  • Se imposti il campo artifactUri quando crea Model: un URI Cloud Storage (a partire da gs://) specificando 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 Visualizza la riga AIP_DEPLOYED_MODEL_ID. Variabile esistente per motivi di compatibilità.

Variabili impostate nella risorsa Model

Quando crei un Model, puoi impostare altre variabili di ambiente in il containerSpec.env .

L'istruzione ENTRYPOINT del contenitore può accedere a queste variabili. Per sapere quali I campi dell'API Vertex AI possono anche fare riferimento a queste variabili. Leggi Riferimento API per ModelContainerSpec.

Passaggi successivi