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 il modo in cui Agent Platform interagisce con il container personalizzato una volta avviata l'esecuzione. 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 fornire inferenze, consulta Utilizzo di un container personalizzato.
Requisiti delle immagini container
Quando l'immagine container Docker viene eseguita come container, quest'ultimo 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 sezioni seguenti descrivono questi requisiti in dettaglio.
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 gestione del 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 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 eseguire l'override rispettivamente di ENTRYPOINT e CMD dell'immagine container. La specifica di uno di questi campi consente di utilizzare un'immagine container che altrimenti non soddisfarebbe i requisiti a causa di un ENTRYPOINT o CMD incompatibile (o inesistente).
Indipendentemente da come determini il 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 questo caso, il container uscirà immediatamente 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 scoprire come il container può accedere a questo valore, leggi la sezione di questo documento sulla variabile di ambiente AIP_HTTP_PORT.
Controlli dell'attività
Agent Platform esegue un controllo di liveness 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 effettua 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. Se è in ascolto di 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 eseguito alcun probe di avvio 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 viene completato.
Le applicazioni legacy che potrebbero richiedere un tempo di avvio aggiuntivo 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 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, 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 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 del modello effettivo nel corpo della risposta indica che il modello potrebbe non essere caricato e quindi non essere pronto ad accettare il traffico. In questo caso, un probe di integrità deve essere configurato in modo da restituire un esito positivo solo quando il modello è caricato e pronto per gestire il traffico.
Per eseguire un probe, Agent Platform 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, la piattaforma dell'agente esegue controlli di integrità intermittenti sul tuo server HTTP mentre è in 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 tuo server. Specifica questo percorso nel campo containerSpec.healthRoute 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_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 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 o 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 di stato non integro 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 ancora il tuo server integro. Se il probe riceve una risposta di stato integro a uno di questi controlli, torna immediatamente alla pianificazione intermittente dei controlli di integrità. Tuttavia, se il probe riceve 4 risposte consecutive di stato non integro, Agent Platform interrompe il routing del traffico di inferenza al container. Se la risorsa DeployedModel è scalata per utilizzare più nodi di inferenza, Agent Platform indirizza le richieste di inferenza ad altri container integri.
Agent Platform non riavvia il container, ma il probe di integrità continua a inviare richieste di controllo di integrità intermittenti al server non integro. Se riceve una risposta di stato integro, contrassegna il container come integro e inizia nuovamente a instradare il traffico di inferenza verso il container.
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 progettare intenzionalmente 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 verso 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 di modelli. Uno definito da Gemini Enterprise Agent Platform (/predict) e l'altro che consente la personalizzazione completa, in modo da poter semplicemente inserire il server di modelli che preferisci (/invoke).
Route /predict definita da Vertex
Quando un client invia una richiesta projects.locations.endpoints.predict all'API Agent Platform, Agent Platform inoltra questa richiesta come richiesta HTTP POST a un percorso di inferenza 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 per la richiesta
Se il deployment del modello viene eseguito su un endpoint pubblico condiviso, ogni richiesta di inferenza deve avere una dimensione massima di 1,5 MB. Il server HTTP deve accettare richieste di inferenza con l'intestazione HTTP Content-Type: application/json e 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 container per facilitare la pubblicazione delle inferenze sulle istanze. La piattaforma dell'agente 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 di risposta
Se il deployment del modello viene eseguito 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 ciascuno dei INSTANCES nella richiesta corrispondente.
Dopo che il tuo server HTTP ha inviato questa risposta, la piattaforma dell'agente aggiunge un campo deployedModelId 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 di modelli 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 il campo Model.containerSpec.invokeRoutePrefix su "/*".
Una volta eseguito il deployment, una richiesta HTTP alla route /invoke/foo/bar verrà inoltrata al percorso /foo/bar del server di modelli. Per informazioni dettagliate, consulta Utilizzo di route personalizzate arbitrarie.
Requisiti per la pubblicazione di immagini container
Devi eseguire il push dell'immagine container in Artifact Registry per utilizzarla con Agent Platform. Scopri come eseguire il push di un'immagine container in Artifact Registry.
In particolare, l'immagine container e il repository devono soddisfare i seguenti requisiti di località, formato dell'URI 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.
Formato URI immagine
Quando crei un Model, specifica
containerSpec.imageUri
in uno dei seguenti formati:
- Per digest:
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:DIGEST - Per tag:
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG - Senza tag o digest (il valore predefinito è
:latest):LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE
Non includere sia un tag sia un digest nello stesso URI (ad esempio, IMAGE:TAG@sha256:DIGEST).
Agent Platform rifiuta gli URI delle immagini che combinano un tag e un digest durante il caricamento del modello.
Autorizzazioni
Agent Platform deve disporre dell'autorizzazione per eseguire il pull dell'immagine container quando crei un Model. In particolare, l'agente di servizio della piattaforma agente per il tuo progetto deve disporre delle autorizzazioni del ruolo Lettore Artifact Registry (roles/artifactregistry.reader) per il repository dell'immagine container.
Agent Platform utilizza l'agente di servizio Agent Platform per il tuo 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 di progetto
del tuo progetto Agent Platform.
Se hai eseguito il push dell'immagine container nello stesso progetto Google Cloud in cui utilizzi Agent Platform, non devi configurare alcuna autorizzazione. Le autorizzazioni predefinite concesse all'agente di servizio Agent Platform sono sufficienti.
Se invece hai eseguito il push dell'immagine container in un progettoGoogle Cloud diverso da quello in cui utilizzi Agent Platform, devi concedere il ruolo Artifact Registry Reader per il repository Artifact Registry all'agente di servizio Agent Platform.
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 artefatti del modello come campo artifactUri. Quando crei un Model con un container personalizzato, la fornitura di artefatti del modello in Cloud Storage è facoltativa.
Se l'immagine container include gli artefatti del modello necessari per fornire le inferenze, non è necessario caricare i file da Cloud Storage.
Tuttavia, se fornisci artefatti del modello specificando il campo artifactUri, il container deve caricarli all'avvio dell'esecuzione.
Quando la piattaforma dell'agente 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 Model. Invece, AIP_STORAGE_URI punta 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.
Il account di servizio utilizzato dal container per impostazione predefinita dispone dell'autorizzazione per leggere da questo URI.
Se invece specifichi un service account personalizzato quando esegui il deployment di Model in un Endpoint, Agent Platform concede automaticamente al service account specificato il ruolo Storage Object Viewer (roles/storage.objectViewer) per il bucket Cloud Storage dell'URI.
Utilizza una 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 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 dalla piattaforma Agent. Questa sezione descrive i vari modi 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 di Model.
Variabili impostate da Agent Platform
Quando Agent Platform 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 container può accedere a queste variabili. Per scoprire quali campi dell'API Agent Platform possono fare riferimento anche 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. |
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 l'DeployedModel in cui è stato eseguito il deployment del Model di questo contenitore. |
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 (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 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 Agent Platform invia i controlli di integrità. |
| AIP_HTTP_PORT | 8080 |
Quando crei un Model, imposta il campo containerSpec.ports. La prima voce di questo campo diventa il valore di AIP_HTTP_PORT. |
La piattaforma dell'agente invia controlli di attività, controlli di integrità e richieste di inferenza 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 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 Agent Platform per fornire inferenze online. Puoi utilizzare questa variabile di ambiente per aggiungere una logica personalizzata al tuo container, in modo che possa essere eseguito in più ambienti di computing, ma utilizzi solo determinati percorsi del 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 la piattaforma dell'agente 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 | Consulta la riga AIP_ENDPOINT_ID. Questa variabile esiste per motivi di compatibilità. |
| AIP_PREDICT_ROUTE | /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predictIn 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 Agent Platform inoltra le richieste di inferenza. |
| AIP_PROJECT_NUMBER | Il numero di progetto del progetto Google Cloud 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 | 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 campo containerSpec.env.
L'istruzione ENTRYPOINT del container può accedere a queste variabili. Per scoprire quali campi dell'API Agent Platform possono fare riferimento anche a queste variabili, consulta il Riferimento API per ModelContainerSpec.
Passaggi successivi
- Scopri di più sulla pubblicazione di inferenze utilizzando un container personalizzato, incluso come specificare i campi API relativi ai container quando importi un modello.