Requisiti per i container personalizzati

Per utilizzare un container personalizzato per la pubblicazione delle previsioni, devi fornire AI Platform Prediction con un'immagine container Docker che esegue un server HTTP. Questo che descrive i requisiti che un'immagine container deve soddisfare per essere compatibili con AI Platform Prediction. Il documento descrive anche in che modo AI Platform Prediction interagisce con il contenitore personalizzato una volta avviato. In altre parole, il presente documento descrive gli aspetti da considerare per progettando un'immagine container da utilizzare con AI Platform Prediction.

Per la procedura dettagliata sull'utilizzo di un'immagine container personalizzata per fornire le previsioni, consulta Utilizzo di 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.

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 o utilizzare un software di pubblicazione di machine learning (ML) che esegue un server HTTP, come TensorFlow Serving, TorchServe o KFServing Server.

Eseguire 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 versione del modello per eseguire l'override dei campi rispettivamente ENTRYPOINT e CMD dell'immagine. La specifica di uno di questi campi consente di utilizzare un'immagine contenitore che altrimenti non soddisferebbe 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 questo comando del punto di ingresso venga eseguito a tempo indeterminato. Ad esempio, non eseguire un comando che avvia un server HTTP in background ed esce. In questo caso, il contenuto del container uscirà immediatamente dopo l'avvio.

Il server HTTP deve ascoltare le richieste su 0.0.0.0, su una porta di tua scelta. Quando crei una versione del modello, specifica questa porta nel containerSpec.ports campo. 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à

AI Platform Prediction esegue un controllo di attivazione quando il contenitore si avvia per verificare che il server sia in esecuzione. Durante la procedura di creazione della versione, Previsione di AI Platform utilizza un sondaggio di attività TCP per tentare di stabilire una connessione TCP con il contenitore sulla porta configurata. La sonda effettua fino a 4 tentativi di stabilire una connessione, aspettando 10 secondi dopo ogni errore. Se la sonda non ha ancora stabilito a questo punto, AI Platform Prediction riavvia il container.

Il tuo server HTTP non deve eseguire alcun comportamento speciale per gestire questi controlli. Finché è in ascolto per le 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 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 campo routes.health. campo se crei una versione del modello. Per scoprire in che modo il contenitore 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à come segue:

  • Se il server è pronto a gestire le richieste di previsione, rispondi al prompt. richiesta di controllo di integrità con codice di stato 200 OK. I contenuti della risposta il corpo non conta; 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à o rispondi con un codice di stato diverso da 200 OK. Ad esempio, rispondi con il codice di stato 503 Service Unavailable.

    Questa risposta indica che il server non è in stato normale.

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 la sonda riceve una risposta integro a uno qualsiasi di questi controlli, il probe torna alla programmazione intermittente dei controlli di integrità. Tuttavia, se il probe riceve 4 risposte non integre consecutive, poi AI Platform Prediction si interrompe l'indirizzamento del traffico di previsione al container. Se la versione del modello è scalata per utilizzare più nodi di previsione, AI Platform Prediction inoltra le richieste di previsione ad altri contenitori funzionanti.

AI Platform Prediction 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 positiva, contrassegna il contenitore come integro e inizia a inoltrarvi nuovamente 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. In tutti gli altri casi, risponde come se fosse in buone condizioni.

Per una configurazione più sofisticata, ti consigliamo di progettare intenzionalmente il server HTTP in modo che risponda ai controlli di integrità con uno stato non corretto in determinati momenti. 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 client invia una richiesta projects.predict all'API AI Platform Training & Prediction, AI Platform Prediction la inoltra come richiesta POST HTTP a un percorso di previsione configurabile sul tuo server. Specifica questo percorso nel routes.predict campo quando crei una versione del modello. Per scoprire in che modo il contenitore può accedere a questo valore, consulta la sezione di questo documento relativa alla variabile di ambiente AIP_PREDICT_ROUTE.

AI Platform Prediction non convalida le richieste e le risposte di previsione. Inoltre, gira ogni richiesta di previsione invariata al server HTTP nel contenitore e poi le risposte del server al client.

Ogni richiesta e risposta di previsione deve avere dimensioni massime pari a 1,5 MB. Tuttavia, non è necessario seguire gli altri requisiti per i corpo delle richieste e i requisiti per i corpo delle risposte. Questi requisiti si applicano solo alle versioni del modello che non utilizzano un contenitore personalizzato. Quando utilizzi un contenitore personalizzato, i corpi della richiesta e della risposta possono assumere qualsiasi forma.

Tuttavia, ti consigliamo comunque di progettare il tuo server HTTP in modo che sia conforme alle I requisiti di richiesta e risposta descritti nei link precedenti. In caso contrario, non c'è alcuna garanzia che altre funzionalità di AI Platform Prediction, come logging, monitoraggio e Spiegazioni IA: funzioneranno correttamente.

Requisiti per la pubblicazione di immagini container

Devi eseguire il push dell'immagine container in Artifact Registry in per usarlo con AI Platform Prediction. Scopri come eseguire il push di un'immagine del contenitore in Artifact Registry.

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

Località

Il repository deve utilizzare una proprietà regione che corrisponde endpoint regionale in cui prevedi di creare un alla versione del modello. Ad esempio, se prevedi di creare una versione del modello sull'endpoint us-central1-ml.googleapis.com, il nome completo dell'immagine del contenitore deve iniziare con us-central1-docker.pkg.dev/.

Non utilizzare un repository multiregionale per l'immagine del contenitore.

Autorizzazioni

Il servizio Previsione di AI Platform deve disporre dell'autorizzazione per estrarre l'immagine del contenitore quando crei una versione del modello. Nello specifico, il servizio AI Platform di accesso deve avere autorizzazioni del ruolo Lettore Artifact Registry (roles/artifactregistry.reader) per il repository dell'immagine container.

Se hai eseguito il push dell'immagine del contenitore 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.

D'altra parte, se hai eseguito il push dell'immagine del contenitore in un progetto Google Cloud diverso da quello in cui utilizzi la previsione di AI Platform, devi concedere il ruolo Lettore di Artifact Registry per il repository di Artifact Registry all'agente di servizio AI Platform.

Accesso agli artefatti del modello

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

Se l'immagine container include gli artefatti del modello che devi pubblicare non c'è bisogno di caricare file da Cloud Storage. Tuttavia, se fornisci gli elementi del modello specificando il campo deploymentUri , il contenitore deve caricarli all'avvio. Quando AI Platform Prediction avvia il contenitore, 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 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 deploymentUri quando crei la versione del modello. Piuttosto, AIP_STORAGE_URI punta a una copia della directory dell'artefatto del modello in un 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. Se vuoi utilizzare nuovi elementi del modello, devi creare una nuova versione del modello.

L'account di servizio utilizzato dal container default ha l'autorizzazione per 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 di visualizzatore di oggetti archiviazione (roles/storage.objectViewer) per il bucket Cloud Storage dell'URI.

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

Poiché il contenitore supporta l'ADC per l'agente di servizio della piattaforma AI o un account di servizio personalizzato, se ne hai specificato uno, può anche accedere a qualsiasi altro servizio Google Cloud per cui il suo account di servizio dispone delle autorizzazioni.

Variabili di ambiente disponibili nel container

Durante l'esecuzione, il comando entrypoint del contenitore 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 che ti consente di impostare le variabili di ambiente, oltre a fornire dettagli impostate automaticamente da AI Platform Prediction.

Variabili impostate nell'immagine container

Per impostare le variabili di ambiente nell'immagine del contenitore durante la compilazione, utilizza l'ENV istruzione di Docker. Non impostare variabili di ambiente che iniziano con il prefisso AIP_.

Il comando entrypoint del contenitore può utilizzare queste variabili di ambiente, ma non puoi farvi riferimento in nessuno dei campi dell'API della versione del modello.

Variabili impostate da AI Platform Prediction

Quando AI Platform Prediction avvia il 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 scoprire quali campi dell'API AI Platform Training e Prediction possono fare riferimento anche a queste variabili, consulta il riferimento all'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 acceleratorConfig.type campo. Se applicabile, questa variabile specifica il tipo di acceleratore utilizzato dall'istanza della macchina virtuale (VM) su cui è in esecuzione il contenitore.
AIP_FRAMEWORK CUSTOM_CONTAINER Non configurabile
AIP_HEALTH_ROUTE /v1/models/MODEL/versions/VERSION

In questa stringa, sostituisci MODEL con il valore del AIP_MODEL_NAME e sostituisci VERSION con il valore della variabile AIP_VERSION_NAME.		 Quando crei una versione del modello, imposta il routes.health campo. Questa variabile specifica il percorso HTTP sul container AI Platform Prediction invia controlli di integrità a.
AIP_HTTP_PORT 8080 Quando crei una versione del modello, imposta il containerSpec.ports campo. La prima voce in questo campo diventa il valore AIP_HTTP_PORT. Il servizio AI Platform Prediction invia controlli di attività, controlli di integrità e a questa porta sul container. Il server HTTP del tuo 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 machineType campo. 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 AI Platform Prediction per fornire previsioni online. Puoi utilizzare questa variabile di ambiente per aggiungere logica personalizzata al contenitore, in modo che possa essere eseguito in più ambienti di calcolo, ma utilizzi 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 del container personalizzato (questo documento) che AI Platform Prediction prevede container da soddisfare. Questo documento viene aggiornato in base al versionamento semantico.
AIP_MODEL_NAME Nessun valore predefinito, deve essere configurato Quando crei un modello (l'elemento padre della versione del modello che utilizza il parametro container), specifica name . Il valore non include il prefisso projects/PROJECT_ID/models/ prodotto dall'API AI Platform Training and Prediction in output.
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 routes.predict campo. Questa variabile specifica il percorso HTTP nel contenitore a cui AI Platform Prediction inoltra le richieste di previsione.
AIP_PROJECT_NUMBER Il numero del progetto del progetto Google Cloud in cui utilizzi AI Platform Prediction Non configurabile
AIP_STORAGE_URI
  • Se non imposti il deploymentUri campo quando crei una versione del modello: una stringa vuota
  • Se imposti il campo deploymentUri quando crea una versione del modello: un URI Cloud Storage (a partire da con gs://) specificando una directory in un bucket gestito AI Platform Prediction
 Non configurabile Questa variabile specifica la directory che contiene una copia degli elementi del modello, se applicabile.
AIP_VERSION_NAME Nessun valore predefinito, deve essere configurato Quando crei una versione del modello, imposta il name campo. Il valore non include il prefisso projects/PROJECT_ID/models/MODEL/versions/ prodotto dall'API AI Platform Training and Prediction in output.

Variabili impostate nella risorsa Versione

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

Il comando entrypoint del contenitore può accedere a queste variabili. Per scoprire quali campi dell'API AI Platform Training e Prediction possono fare riferimento anche a queste variabili, consulta il riferimento all'API per ContainerSpec.

Passaggi successivi