Requisiti per i container personalizzati

Per utilizzare un container personalizzato al fine di fornire previsioni, devi fornire ad AI Platform Prediction 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 avviata l'esecuzione. In altre parole, questo documento descrive gli aspetti da considerare quando si progetta un'immagine container da utilizzare con AI Platform Prediction.

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 un server HTTP. Nello specifico, il container deve ascoltare e rispondere ai controlli di attività, ai controlli di integrità e alle richieste di previsione. Le seguenti sottosezioni descrivono in dettaglio questi requisiti.

Puoi implementare il server HTTP in qualsiasi modo e utilizzando qualsiasi linguaggio di programmazione, purché soddisfi i requisiti illustrati in 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, come TensorFlowServing, TorchServe o KFServing Server.

Esecuzione del 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 versione del modello per eseguire l'override rispettivamente dei 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 valore ENTRYPOINT o CMD incompatibile (o inesistente).

Indipendentemente da quale sia il comando eseguito dal container all'avvio, assicurati che questo comando del punto di ingresso venga eseguito all'infinito. Ad esempio, non eseguire un comando che avvia un server HTTP in background e poi si chiude; in questo caso, il container si chiuderà subito dopo l'avvio.

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 informazioni su 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à quando il container inizia per assicurarti 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 di stabilire una connessione, attendendo 10 secondi dopo ogni errore. Se il probe non ha ancora stabilito una connessione a questo punto, AI Platform Prediction 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à

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 GET HTTP a un percorso di controllo di integrità configurabile sul tuo server. Specifica questo percorso nel campo routes.health quando crei una versione del modello. Per informazioni su 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 previsione, rispondi alla richiesta di controllo di integrità con il codice di stato 200 OK. I contenuti del corpo della risposta non sono importanti, ma AI Platform Prediction 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à e non rispondere con alcun codice di stato ad eccezione di 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 non integro 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 integro a uno di questi controlli, torna immediatamente alla programmazione intermittente dei controlli di integrità. Tuttavia, se il probe riceve quattro risposte non integre consecutive, AI Platform Prediction interrompe l'indirizzamento del traffico di previsione al container. Se la versione del modello viene scalata per utilizzare più nodi di previsione, AI Platform Prediction instrada le richieste di previsione ad altri container integri.

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

Indicazioni pratiche

In alcuni casi, è sufficiente che il server HTTP nel tuo 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, significa che non è integro durante il periodo di avvio e in tutti i periodi in cui si verifica un errore del server HTTP. In tutti gli altri momenti, risponde come salutare.

Per una configurazione più sofisticata, potrebbe essere utile progettare intenzionalmente il server HTTP in modo che risponda ai controlli di integrità con stato non integro in determinati momenti. Ad esempio, potresti voler bloccare il traffico di previsione verso un nodo per un periodo per consentire al container di 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 POST HTTP a un percorso di previsione configurabile sul tuo server. Specifica questo percorso nel campo routes.predict quando crei una versione del modello. Per informazioni su 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, ma passa ogni richiesta di previsione invariata al server HTTP nel tuo contenitore e ritrasmette le risposte del server al client.

Ogni richiesta di previsione e risposta deve avere dimensioni inferiori a 1,5 MB. Tuttavia, non devi rispettare gli altri requisiti per gli organismi 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, il corpo della richiesta e della risposta può assumere qualsiasi formato.

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 Explains, funzioneranno 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 a un repository che soddisfi i seguenti requisiti di posizione e autorizzazione.

Località

Il repository deve utilizzare una regione che corrisponda all'endpoint regionale 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

AI Platform Prediction deve disporre dell'autorizzazione per eseguire il pull dell'immagine container quando crei una versione del modello. In particolare, l'agente di servizio AI Platform deve disporre delle autorizzazioni del ruolo Lettore di 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'agente di servizio sono sufficienti.

Se invece hai eseguito il push dell'immagine container a un progetto Google Cloud diverso da quello in cui utilizzi AI Platform Prediction, devi concedere il ruolo Lettore Artifact Registry per il repository Artifact Registry all'agente di servizio 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 gli artefatti del modello come campo deploymentUri. Quando crei una versione del modello con un container personalizzato, l'invio degli artefatti del modello in Cloud Storage è facoltativo.

Se l'immagine container include gli artefatti del modello necessari per fornire 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 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 deploymentUri quando crei la versione del modello. Piuttosto, AIP_STORAGE_URI punta a una copia della directory degli artefatti del modello in un altro bucket Cloud Storage gestito da AI Platform Prediction. AI Platform Prediction compila questa directory quando crei una versione del modello. Non puoi aggiornare il contenuto della directory. Per usare nuovi artefatti del modello, devi creare una nuova versione del modello.

L'account di servizio utilizzato dal container per impostazione predefinita ha l'autorizzazione a leggere da questo URI. D'altra parte, se 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 Credenziali predefinite dell'applicazione (ADC) per caricare gli artefatti del modello. Non è necessario configurare esplicitamente l'autenticazione.

Poiché il container supporta ADC per l'agente di servizio AI Platform (o un account di servizio personalizzato, se ne hai specificato uno), può anche accedere a qualsiasi altro servizio Google Cloud per cui l'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 e alle variabili di ambiente impostate automaticamente da AI Platform Prediction. Questa sezione descrive tutti i modi in cui puoi 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 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.

Il comando del punto di ingresso del container può accedere a queste variabili. Per sapere quali campi dell'API AI Platform Training e API Prediction possono fare riferimento anche a queste variabili, leggi la documentazione di 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 della 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 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. Il servizio AI Platform Prediction invia controlli di attività, controlli di integrità e richieste di previsione a questa porta nel 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 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 pubblicare le previsioni online. Puoi utilizzare questa variabile di ambiente per aggiungere logica personalizzata al container, in modo che possa essere eseguito in più ambienti di elaborazione, 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 dei container personalizzati (questo documento) che AI Platform Prediction prevede che vengano soddisfatti dal container. Questo documento viene aggiornato in base al controllo delle versioni semantico.
AIP_MODEL_NAME Nessun valore predefinito, deve essere configurato Quando crei un modello (il 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 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 di progetto 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 specifichi 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 altre variabili di ambiente 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 API Prediction possono fare riferimento anche a queste variabili, leggi la documentazione di riferimento API per ContainerSpec.

Passaggi successivi