Per utilizzare un container personalizzato in modo da ottenere inferenze da un modello con addestramento personalizzato, devi fornire a Gemini Enterprise Agent Platform un'immagine container Docker che esegue un server HTTP. Questo documento descrive i requisiti che un'immagine container deve soddisfare per essere compatibile con Gemini Enterprise Agent Platform. Il documento descrive anche in che modo Agent Platform interagisce con il container personalizzato una volta avviato. In altre parole, questo documento descrive cosa devi considerare quando progetti un'immagine container da utilizzare con Agent Platform.
Per scoprire come utilizzare un'immagine container personalizzata per erogare inferenze, leggi Utilizzo di un container personalizzato.
Requisiti dell'immagine container
Quando l'immagine 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 inferenza. Le seguenti sottosezioni descrivono questi requisiti in dettaglio.
Puoi implementare il server HTTP in qualsiasi modo, utilizzando qualsiasi linguaggio di programmazione, purché soddisfi i requisiti descritti 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'ENTRYPOINT
istruzione, un'CMD
istruzione,
o entrambe 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 per sostituire rispettivamente ENTRYPOINT e CMD dell'immagine container. La specifica di uno di questi campi ti consente di utilizzare un'immagine container che altrimenti non soddisferebbe i requisiti a causa di un ENTRYPOINT o CMD incompatibile (o inesistente).
Indipendentemente dal comando 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 e poi esce; in caso contrario, il container uscirà immediatamente dopo l'avvio.
Il server HTTP deve rimanere in ascolto delle richieste su 0.0.0.0, su una porta a tua scelta. Quando crei un Model, specifica questa porta nel
containerSpec.ports
campo.
Per scoprire in che modo il container può accedere a questo valore, leggi la sezione di questo
documento relativa alla variabile di ambienteAIP_HTTP_PORT.
Controlli di attività
Agent Platform esegue un controllo di attività all'avvio del container per assicurarsi che il server sia in esecuzione. Quando esegui il deployment di un modello con addestramento personalizzato in
una risorsa Endpoint,
Agent Platform utilizza un probe di attività TCP
per tentare di stabilire una connessione TCP al container sulla
porta configurata. Il probe esegue fino a 4 tentativi di stabilire una connessione, attendendo 10 secondi dopo ogni errore. Se il probe non ha ancora stabilito una connessione a questo punto, Agent Platform riavvia il container.
Il server HTTP non deve eseguire alcun comportamento speciale per gestire questi controlli. Finché rimane in ascolto delle richieste sulla porta configurata, il probe di attività è in grado di stabilire una connessione.
Controlli di integrità
Puoi specificare facoltativamente startup_probe
o health_probe.
Il probe di avvio controlla se l'applicazione container è stata avviata. Se non viene fornito un probe di avvio, non ne viene eseguito nessuno e i controlli di integrità iniziano immediatamente. Se viene fornito un 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 un tempo di avvio aggiuntivo durante la 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 in modo che restituisca un esito positivo al termine dell'inizializzazione.
Il probe di integrità controlla se un container è pronto ad accettare il traffico. Se non viene fornito un probe di integrità, Agent Platform utilizza i controlli di integrità predefiniti descritti in Controlli di integrità predefiniti.
Le applicazioni legacy che non restituiscono 200 OK per indicare che il modello è stato caricato ed è pronto ad accettare il 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 effettivo del modello nel corpo della risposta indica che il modello potrebbe non essere caricato e quindi potrebbe non essere pronto ad accettare il traffico. In questo caso, è necessario configurare un probe di integrità in modo che restituisca un esito positivo solo quando il modello è stato caricato ed è pronto a gestire il traffico.
Per eseguire un probe, Agent Platform esegue il comando exec specificato nel container di destinazione. Se il comando va a buon fine, restituisce 0 e il container viene considerato attivo e integro.
Controlli di integrità predefiniti
Per impostazione predefinita, Agent Platform esegue periodicamente controlli di integrità sul server HTTP durante l'esecuzione per assicurarsi che sia pronto a gestire le richieste di inferenza.
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 container 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à nel seguente modo:
Se il server è pronto a gestire le richieste di inferenza, 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; Agent Platform li ignora.Questa risposta indica che il server è integro.
Se il server non è pronto a gestire le richieste di inferenza, non rispondere alla richiesta di controllo di integrità entro 10 secondi oppure rispondi con un codice di stato diverso da
200 OK. Ad esempio, rispondi con il codice di stato503 Service Unavailable.Questa risposta (o la mancanza di una risposta) indica che il server non è integro.
Se il probe di integrità riceve una risposta non integra dal server (inclusa l'assenza di risposta entro 10 secondi), invia fino a 3 controlli di integrità aggiuntivi a intervalli di 10 secondi. Durante questo periodo, Agent Platform considera comunque il server integro. Se il probe riceve una risposta integra a uno di questi controlli, torna immediatamente alla pianificazione intermittente dei controlli di integrità. Tuttavia, se il probe riceve 4 risposte non integre consecutive, Agent Platform interrompe il routing del traffico di inferenza al container. (Se la risorsa DeployedModel viene scalata per utilizzare più nodi di inferenza, Agent Platform esegue il routing delle richieste di inferenza ad altri container integri.)
Agent Platform 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 integra, contrassegna il container come integro e inizia di nuovo a eseguire il routing del traffico di inferenza.
Indicazioni pratiche
In alcuni casi, è sufficiente che il server HTTP nel 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, il container non è integro durante il periodo di avvio e durante i periodi in cui il server HTTP non funziona. In tutti gli altri casi, risponde come integro.
Per una configurazione più sofisticata, potresti voler progettare appositamente 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 inferenza a un nodo per un periodo di tempo in modo che il container possa eseguire la manutenzione.
Richieste di inferenza
Esistono due pattern per la configurazione delle route al server del modello. Uno definito da Gemini Enterprise Agent Platform (/predict) e l'altro che consente la personalizzazione completa in modo da poter inserire semplicemente il server del modello di tua scelta (/invoke).
Route /predict definita da Vertex
Quando un client invia una projects.locations.endpoints.predict
richiesta all'
API Agent Platform, Agent Platform inoltra questa richiesta come richiesta HTTP
POST a un percorso di inferenza configurabile sul server. Specifica questo
percorso nel containerSpec.predictRoute
campo
quando crei un Model. Per scoprire in che modo il container può accedere a questo
valore, leggi la sezione di questo documento relativa alla AIP_PREDICT_ROUTE
variabile di ambiente.
Requisiti della richiesta
Se il modello viene sottoposto a deployment su un endpoint pubblico condiviso, ogni richiesta di inferenza deve avere dimensioni pari o inferiori a 1,5 MB. Il server HTTP deve accettare le richieste di inferenza con l'intestazione HTTP Content-Type: application/json e i corpi 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 fornendo un'inferenza.
PARAMETERS è un oggetto JSON contenente tutti i parametri richiesti dal tuo container per erogare le inferenze sulle istanze. Agent Platform considera il campo
parametersfacoltativo, quindi puoi progettare il container in modo che lo richieda, lo utilizzi solo se fornito o lo ignori.
Scopri di più sui requisiti del corpo della richiesta.
Requisiti della risposta
Se il modello viene sottoposto a deployment su un endpoint pubblico condiviso, ogni risposta di inferenza deve avere dimensioni pari o inferiori a 1,5 MB. Il server HTTP deve inviare risposte con corpi JSON che soddisfano il seguente formato:
{
"predictions": INFERENCES
}
In queste risposte, sostituisci INFERENCES con un array di valori JSON che rappresentano le inferenze generate dal container per ciascuna delle INSTANCES nella richiesta corrispondente.
Dopo che il server HTTP invia questa risposta, Agent Platform aggiunge un
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 formato del corpo della risposta
.
Route di inferenza personalizzate
Se il server del modello implementa più route di inferenza, ti consigliamo di utilizzare l'API Invoke per accedere a più route di inferenza. L'API Invoke può essere abilitata
durante il caricamento del modello impostando Model.containerSpec.invokeRoutePrefix
campo su "/*".
Una volta eseguito il deployment, una richiesta HTTP alla route /invoke/foo/bar verrà inoltrata come
percorso /foo/bar del server del modello. Per scoprire i dettagli,
leggi Utilizzo di route personalizzate arbitrarie.
Requisiti di pubblicazione dell'immagine container
Per utilizzare l'immagine container con Agent Platform, 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 di località e autorizzazioni.
Località
Quando utilizzi Artifact Registry, il repository deve utilizzare una
regione che corrisponda all'
endpoint di località 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
Agent Platform deve avere l'autorizzazione per eseguire il pull dell'immagine container quando crei un Model. Nello specifico, l'agente di servizio Agent Platform per il tuo progetto deve avere le autorizzazioni del ruolo Lettore di Artifact Registry (roles/artifactregistry.reader) per il repository di immagini container.
Agent Platform utilizza l'agente di servizio Agent Platform per il tuo progetto per interagire con
altri Google Cloud servizi. 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 Agent Platform.
Se hai eseguito il push dell'immagine container nello stesso Google Cloud progetto in cui utilizzi Agent Platform, non devi configurare alcuna autorizzazione. Le autorizzazioni predefinite concesse all'agente di servizio Agent Platform sono sufficienti.
D'altra parte, se hai eseguito il push dell'immagine container in un progetto diverso da quello in cui utilizzi Agent Platform, devi concedere il ruolo Lettore di artefatti Artifact per il repository Artifact Registry all'agente di servizio Agent Platform.Google Cloud
Accedi agli artefatti del modello
Quando crei un Model con addestramento personalizzato senza un container personalizzato, devi
specificare l'URI di una directory Cloud Storage con gli 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 pubblicare le inferenze, non è necessario caricare i file da Cloud Storage.
Tuttavia, se fornisci gli artefatti del modello specificando il campo artifactUri, il container deve caricare questi artefatti all'avvio.
Quando Agent Platform avvia il container, imposta la variabile di ambiente AIP_STORAGE_URI su un URI Cloud Storage che inizia con gs://.
L'istruzione 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 Cloud Storage specificato nel campo artifactUri quando crei il Model. Al contrario, AIP_STORAGE_URI rimanda a una copia della directory degli artefatti del modello in un bucket Cloud Storage diverso, gestito da Agent Platform.
Agent Platform compila questa directory quando crei un 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 per impostazione predefinita dal container ha l'autorizzazione per leggere da questo URI.
D'altra parte, se specifichi un account di servizio personalizzato quando esegui il deployment del Model in un
Endpoint, Agent Platform 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 le 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, l'istruzione ENTRYPOINT del container può fare riferimento alle variabili di ambiente configurate manualmente, nonché alle variabili di ambiente impostate automaticamente da Agent Platform. Questa sezione descrive ogni modo in cui puoi impostare le variabili di ambiente e fornisce dettagli sulle variabili impostate automaticamente da Agent Platform.
Variabili impostate nell'immagine container
Per impostare le variabili di ambiente nell'immagine container durante la creazione, utilizza
l'istruzione ENV
di Docker.
Non impostare variabili di ambiente che iniziano con il prefisso AIP_.
L'istruzione ENTRYPOINT del container può utilizzare queste variabili di ambiente, ma non
puoi farvi riferimento in nessuno dei campi API
del Model's.
Variabili impostate da Agent Platform
Quando Agent Platform inizia a eseguire il container, imposta le seguenti variabili di ambiente nell'ambiente container. Ogni variabile inizia con il prefisso AIP_. Non impostare manualmente variabili di ambiente che utilizzano questo prefisso.
L'istruzione ENTRYPOINT del container può accedere a queste variabili. Per scoprire quali
campi API di Agent Platform possono anche fare riferimento a queste variabili, consulta 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 Model come DeployedModel
in una risorsa Endpoint, imposta il campo dedicatedResources.machineSpec.acceleratorType
field. |
Se applicabile, questa variabile specifica il tipo di acceleratore utilizzato da l'istanza di macchina virtuale (VM) su cui è in esecuzione il container. |
| AIP_DEPLOYED_MODEL_ID | Una stringa di cifre che identifica il DeployedModel in cui
è stato eseguito il deployment del Model di questo container. |
Non configurabile | Questo valore è il DeployedModel del id
campo. |
| AIP_ENDPOINT_ID | Una stringa di cifre che identifica il Endpoint in cui è stato eseguito il deployment del Model del container. |
Non configurabile | Questo valore è l'ultimo segmento del Endpoint's name
campo (dopo endpoints/). |
| AIP_FRAMEWORK | CUSTOM_CONTAINER |
Non configurabile | |
| AIP_HEALTH_ROUTE | /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODELIn questa stringa, sostituisci ENDPOINT con il valore della AIP_ENDPOINT_ID variabile e sostituisci
DEPLOYED_MODEL con il valore della
AIP_DEPLOYED_MODEL_ID variabile. |
Quando crei un Model, imposta il containerSpec.healthRoute
campo. |
Questa variabile specifica il percorso HTTP sul container a cui Agent Platform invia i controlli di integrità a. |
| 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. |
Agent Platform invia i controlli di attività, i controlli di integrità e le richieste di inferenza a questa porta sul 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 Model come DeployedModel
in una risorsa Endpoint, imposta il campo dedicatedResources.machineSpec.machineType
field. |
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 Agent Platform per erogare le inferenze online. Puoi utilizzare questa variabile di ambiente per aggiungere logica personalizzata al container, in modo che possa essere eseguito in più ambienti di computing, ma utilizzi solo determinati percorsi di codice quando viene eseguito su Agent Platform. |
| AIP_MODE_VERSION | 1.0.0 |
Non configurabile | Questa variabile indica la versione dei requisiti del container personalizzato (questo documento) che Agent Platform si aspetta che il container soddisfi. Questo documento viene aggiornato 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
compatibilità. |
| AIP_PREDICT_ROUTE | /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predictIn questa stringa, sostituisci ENDPOINT con il valore della AIP_ENDPOINT_ID variabile e sostituisci
DEPLOYED_MODEL con il valore della
AIP_DEPLOYED_MODEL_ID variabile. |
Quando crei un Model, imposta il containerSpec.predictRoute
campo. |
Questa variabile specifica il percorso HTTP sul container a cui Agent Platform inoltra le richieste di inferenza to. |
| AIP_PROJECT_NUMBER | Il numero di progetto del Google Cloud progetto in cui utilizzi Agent Platform | Non configurabile | |
| AIP_STORAGE_URI |
|
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 Model, puoi impostare variabili di ambiente aggiuntive in
il campo containerSpec.env.
L'istruzione ENTRYPOINT del container può accedere a queste variabili. Per scoprire quali
campi API di Agent Platform possono anche fare riferimento a queste variabili, consulta il
riferimento API per
ModelContainerSpec.