Requisiti per i container personalizzati

Per utilizzare un container personalizzato per fornire previsioni, devi fornire AI Platform Prediction con un'immagine container Docker che esegue un server HTTP. Questo documento descrive i requisiti che un'immagine container deve soddisfare per essere compatibile con AI Platform Prediction. Il documento descrive inoltre in che modo AI Platform Prediction interagisce con il container personalizzato una volta che viene eseguito. In altre parole, questo documento descrive cosa devi considerare quando progetti un'immagine container da utilizzare con AI Platform Prediction.

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

Requisiti delle immagini container

Quando l'immagine del container Docker viene eseguita come container, quest'ultimo deve eseguire un server HTTP. In particolare, il container deve rimanere in ascolto e rispondere ai controlli di attività, ai controlli di integrità e alle richieste di previsione. Le seguenti sottosezioni descrivono dettagliatamente questi requisiti.

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 oppure usare un software di gestione di machine learning (ML) che esegue un server HTTP, come TensorFlow Serve, TorchServe o KFServe Server.

Esecuzione del server HTTP

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

In alternativa, puoi specificare i campi containerSpec.command e containerSpec.args quando crei la versione del modello per sostituire rispettivamente i valori ENTRYPOINT e CMD dell'immagine container. Se specifichi uno di questi campi, puoi utilizzare un'immagine container che altrimenti non soddisferebbe i requisiti a causa di un elemento ENTRYPOINT o CMD incompatibile (o inesistente).

Tuttavia, sei tu a stabilire quale comando esegue il container all'avvio, assicurati che questo comando del punto di ingresso venga eseguito 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à subito dopo l'esecuzione.

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

Controlli di attività

AI Platform Prediction esegue un controllo di attività all'avvio del container per verificare che il server sia in esecuzione. Durante il processo di creazione della versione, AI Platform Prediction 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 per stabilire una connessione, attendendo 10 secondi dopo ogni errore. Se a questo punto il probe non ha ancora stabilito una connessione, AI Platform Prediction riavvia il container.

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

Controlli di integrità

Il servizio AI Platform Prediction esegue a intermittenza controlli di integrità sul server HTTP mentre è in esecuzione per garantire 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 campo routes.health quando crei una versione del modello. Per scoprire in che modo 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 previsione, rispondi alla richiesta di controllo di integrità con il codice di stato 200 OK. I contenuti del corpo della risposta non sono importanti, AI Platform Prediction li ignora.

    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à o rispondere con qualsiasi codice di stato tranne 200 OK. Ad esempio, rispondi con il codice di stato 503 Service Unavailable.

    Questa risposta indica che il server non è integro.

Se il probe di integrità riceve una risposta dal server, invia fino a tre controlli di integrità aggiuntivi a intervalli di 10 secondi. Durante questo periodo, AI Platform Prediction considera comunque il tuo server integro. Se il probe riceve una risposta in stato integro a uno di questi controlli, torna immediatamente alla sua pianificazione intermittente di controlli di integrità. Tuttavia, se il probe riceve 4 risposte non integri consecutive, AI Platform Prediction smette di instradare il traffico di previsione al container. Se la versione del modello viene scalata per utilizzare più nodi di previsione, AI Platform Prediction inoltra le richieste di previsione ad altri container integri.

Il servizio AI Platform Prediction non riavvia il container, ma il probe di integrità continua a inviare richieste di controllo di integrità intermittente al server in stato non integro. Se riceve una risposta in stato integro, contrassegna il container come in stato integro e inizia a instradare nuovamente il traffico di previsione verso di esso.

Indicazioni pratiche

In alcuni casi, è sufficiente che il server HTTP nel tuo container risponda sempre ai controlli di integrità con il codice di stato 200 OK. Se il container carica le risorse prima di avviare il server, significa che non è integro durante il periodo di avvio e in tutti i periodi in cui il server HTTP si arresta. In tutti gli altri momenti, risponde bene.

Per una configurazione più sofisticata, potresti voler progettare deliberatamente 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 previsione verso un nodo per un determinato periodo, in modo che il container possa eseguire la manutenzione.

Richieste di previsione

Quando un client invia una richiesta projects.predict all'API AI Platform Training and Prediction, AI Platform Prediction inoltra questa richiesta come richiesta HTTP POST a un percorso di previsione configurabile sul tuo server. Specifica questo percorso nel campo routes.predict quando crei una versione del modello. Per sapere come il container può accedere a questo valore, leggi la sezione di questo documento sulla variabile di ambiente AIP_PREDICT_ROUTE.

AI Platform Prediction non convalida le richieste e le risposte di previsione; passa ogni richiesta di previsione invariata al server HTTP nel tuo container e ritrasmette le risposte del server al client.

Ogni richiesta e risposta di previsione deve avere dimensioni massime pari a 1,5 MB. Tuttavia, non è necessario rispettare gli altri requisiti per gli corpi di richiesta e i requisiti per gli corpi di risposta; questi requisiti si applicano solo alle versioni del modello che non utilizzano un container personalizzato. Quando utilizzi un container personalizzato, i corpi di richiesta e risposta possono assumere qualsiasi forma.

Tuttavia, ti consigliamo comunque di progettare il tuo server HTTP in modo che sia conforme ai requisiti di richiesta e risposta descritti nei link precedenti. In caso contrario, non vi è alcuna garanzia che altre funzionalità di AI Platform Prediction, come logging, monitoring e AI Explanations, funzionino correttamente.

Requisiti di pubblicazione delle immagini container

Devi eseguire il push dell'immagine container ad Artifact Registry per utilizzarla con AI Platform Prediction. Scopri come eseguire il push di un'immagine container ad Artifact Registry.

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

Località

Il repository deve utilizzare una regione che corrisponda all'endpoint a livello di regione in cui prevedi di creare una versione del modello. Ad esempio, se prevedi di creare una versione del modello nell'endpoint us-central1-ml.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

Il servizio AI Platform Prediction deve disporre dell'autorizzazione per eseguire il pull dell'immagine container quando crei una versione del modello. In particolare, l'account di servizio gestito da Google per AI Platform deve avere le autorizzazioni del ruolo Lettore Artifact Registry (roles/artifactregistry.reader) per il repository dell'immagine container.

Se hai eseguito il push dell'immagine container nello stesso progetto Google Cloud in cui utilizzi AI Platform Prediction, non devi configurare alcuna autorizzazione. Le autorizzazioni predefinite concesse all'account di servizio gestito da Google sono sufficienti.

Se invece hai eseguito il push dell'immagine container a un altro progetto Google Cloud da quello in cui utilizzi AI Platform Prediction, devi concedere il ruolo Lettore di Artifact Registry per il repository Artifact Registry all'account di servizio gestito da Google per AI Platform.

Accesso agli artefatti del modello

Quando crei una versione del modello senza un container personalizzato, devi specificare l'URI di una directory Cloud Storage con artefatti del modello come campo deploymentUri. Quando crei una versione del modello con un container personalizzato, fornire gli artefatti del modello in Cloud Storage è facoltativo.

Se l'immagine container include gli artefatti del modello necessari per gestire le previsioni, non è necessario caricare file da Cloud Storage. Tuttavia, se fornisci gli artefatti del modello specificando il campo deploymentUri, il container deve caricare questi artefatti all'avvio. Quando AI Platform Prediction avvia il container, imposta la variabile di ambiente AIP_STORAGE_URI su un URI Cloud Storage che inizia con gs://. Il comando del punto di ingresso 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 deploymentUri quando crei la versione del modello. Piuttosto, AIP_STORAGE_URI rimanda a una copia della directory degli artefatti del modello in un altro bucket Cloud Storage, gestito da AI Platform Prediction. Il servizio AI Platform Prediction completa questa directory quando crei una versione del modello. Non puoi aggiornare i contenuti della directory. Se vuoi usare nuovi artefatti del modello, devi crearne una nuova.

L'account di servizio che il tuo container utilizza per impostazione predefinita dispone dell'autorizzazione per leggere da questo URI. Se invece specifichi un account di servizio personalizzato quando crei una versione del modello, AI Platform Prediction 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.

Poiché il container supporta ADC per l'account di servizio AI Platform gestito da Google (o un account di servizio personalizzato, se ne hai specificato uno), può anche accedere a qualsiasi altro servizio Google Cloud per i quali il suo account di servizio dispone delle autorizzazioni.

Variabili di ambiente disponibili nel container

Durante l'esecuzione, il comando del punto di ingresso del container può fare riferimento alle variabili di ambiente configurate manualmente, nonché alle variabili di ambiente impostate automaticamente da AI Platform Prediction. Questa sezione descrive ogni modo in cui è possibile impostare le variabili di ambiente e fornisce dettagli sulle variabili impostate automaticamente da AI Platform Prediction.

Variabili impostate nell'immagine container

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

Il comando del punto di ingresso del container può utilizzare queste variabili di ambiente, ma non puoi farvi riferimento in nessuno dei campi API della versione del modello.

Variabili impostate da AI Platform Prediction

Quando AI Platform Prediction 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 alcuna variabile di ambiente che utilizzi questo prefisso.

Il comando del punto di ingresso del container può accedere a queste variabili. Per sapere quali campi dell'API AI Platform Training e Prediction possono anche fare riferimento a queste variabili, leggi il riferimento API per ContainerSpec.

Nome variabile Valore predefinito Come configurare il valore Dettagli
AIP_ACCELERATOR_TYPE Non impostato Quando crei una versione del modello, imposta il campo acceleratorConfig.type. Se applicabile, questa variabile specifica il tipo di acceleratore utilizzato dall'istanza di macchina virtuale (VM) su cui è in esecuzione il container.
AIP_FRAMEWORK CUSTOM_CONTAINER Non configurabile
AIP_HEALTH_ROUTE /v1/models/MODEL/versions/VERSION

In questa stringa, sostituisci MODEL con il valore della variabile AIP_MODEL_NAME e sostituisci VERSION con il valore della variabile AIP_VERSION_NAME.		 Quando crei una versione del modello, imposta il campo routes.health. Questa variabile specifica il percorso HTTP sul container a cui AI Platform Prediction invia i controlli di integrità.
AIP_HTTP_PORT 8080 Quando crei una versione del modello, imposta il campo containerSpec.ports. La prima voce in questo campo diventa il valore di AIP_HTTP_PORT. AI Platform Prediction invia controlli di attività, controlli di integrità e richieste di previsione a questa porta sul container. Il server HTTP del contenitore deve rimanere in ascolto delle richieste su questa porta.
AIP_MACHINE_TYPE Nessun valore predefinito, deve essere configurato Quando crei una versione del modello, imposta il campo 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 AI Platform Prediction per fornire previsioni 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 utilizzare solo determinati percorsi di codice quando viene eseguito su AI Platform Prediction.
AIP_MODE_VERSION 1.0.0 Non configurabile Questa variabile indica la versione dei requisiti per i container personalizzati (questo documento) che AI Platform Prediction prevede che il container soddisfi. Questo documento si aggiorna in base al controllo delle versioni semantico.
AIP_MODEL_NAME Nessun valore predefinito, deve essere configurato Quando crei un modello (l'elemento padre della versione del modello che utilizza il contenitore), specifica il campo name. Il valore non include il prefisso projects/PROJECT_ID/models/ prodotto nell'output dall'API AI Platform Training and Prediction.
AIP_PREDICT_ROUTE /v1/models/MODEL/versions/VERSION:predict

In questa stringa, sostituisci MODEL con il valore della variabile AIP_MODEL_NAME e sostituisci VERSION con il valore della variabile AIP_VERSION_NAME.		 Quando crei una versione del modello, imposta il campo routes.predict. Questa variabile specifica il percorso HTTP sul container a cui AI Platform Prediction inoltra le richieste di previsione.
AIP_PROJECT_NUMBER Il numero del progetto Google Cloud in cui stai utilizzando AI Platform Prediction Non configurabile
AIP_STORAGE_URI
  • Se non imposti il campo deploymentUri quando crei una versione del modello: una stringa vuota
  • Se imposti il campo deploymentUri quando crei una versione del modello: un URI Cloud Storage (che inizia con gs://) che specifica una directory in un bucket gestito da AI Platform Prediction
 Non configurabile Questa variabile specifica la directory che contiene una copia degli artefatti del modello, se applicabile.
AIP_VERSION_NAME Nessun valore predefinito, deve essere configurato Quando crei una versione del modello, imposta il campo name. Il valore non include il prefisso projects/PROJECT_ID/models/MODEL/versions/ prodotto nell'output dall'API AI Platform Training and Prediction.

Variabili impostate nella risorsa Versione

Quando crei una versione del modello, puoi impostare variabili di ambiente aggiuntive nel campo container.env.

Il comando del punto di ingresso del container può accedere a queste variabili. Per sapere quali campi dell'API AI Platform Training e Prediction possono anche fare riferimento a queste variabili, leggi il riferimento API per ContainerSpec.

Passaggi successivi