Questa versione precedente di AI Platform Prediction è ritirata e non sarà più disponibile su Google Cloud dopo il 31 gennaio 2025. Tutti i modelli, i metadati associati e i deployment verranno eliminati dopo il 31 gennaio 2025. Esegui la migrazione delle tue risorse a Vertex AI per accedere a nuove funzionalità di machine learning non disponibili in AI Platform.

Questa pagina è stata tradotta dall'API Cloud Translation.

Requisiti per i container personalizzati

Per utilizzare un container personalizzato per fornire le previsioni, devi fornire a 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 anche in che modo AI Platform Prediction interagisce con il contenitore personalizzato una volta avviato. In altre parole, questo documento descrive cosa devi prendere in considerazione quando progetti un'immagine contenitore da utilizzare con AI Platform Prediction.

Per una 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 del 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 previsione. Le seguenti sottosezioni descriveranno 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'istruzione ENTRYPOINT, un'istruzione CMD o entrambe nel Dockerfile utilizzato 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 sostituire rispettivamente ENTRYPOINT e CMD dell'immagine del contenitore. 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 scoprire in che modo il contenitore può accedere a questo valore, leggi la sezione di questo documento relativa alla variabile di ambiente AIP_HTTP_PORT.

Controlli dell'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, AI Platform Prediction utilizza un sondaggio di attività TCP per tentare di stabilire una connessione TCP con il contenitore sulla porta configurata. La sonda esegue fino a 4 tentativi di stabilire una connessione, aspettando 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 per le richieste sulla porta configurata, il probe di attività è in grado di stabilire una connessione.

Controlli di integrità

AI Platform Prediction esegue intermittentemente controlli di integrità sul server HTTP mentre è in esecuzione per assicurarsi 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 routes.health campo quando 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 alla richiesta di controllo di integrità#39;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 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 corretta dal server, invia fino a 3 controlli di integrità aggiuntivi a intervalli di 10 secondi. Durante questo periodo, AI Platform Prediction considera ancora il tuo server in stato di salute. Se il probe riceve una risposta corretta a uno di questi controlli, torna immediatamente alla sua pianificazione intermittente dei controlli di integrità. Tuttavia, se il probe riceve 4 risposte consecutive non valide, AI Platform Prediction interrompe il routing del traffico di previsione al contenitore. 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 contenitore, ma il probe di integrità continua a inviare richieste di controllo di integrità intermittenti al server non integro. Se riceve una risposta positiva, contrassegna il contenitore come integro e inizia a reindirizzare nuovamente il traffico di previsione.

Indicazioni pratiche

In alcuni casi, è sufficiente che il server HTTP nel contenitore risponda sempre con il codice di stato 200 OK ai controlli di salute. Se il contenitore carica le risorse prima di avviare il server, il contenitore non è in stato corretto durante il periodo di avvio e durante i periodi in cui il server HTTP non funziona. 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 su un nodo per un determinato periodo in modo che il contenitore 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 ai requisiti relativi a richieste e risposte descritti nei link precedenti. In caso contrario, non è garantito che altre funzionalità di AI Platform Prediction, come logging, monitoraggio e spiegazioni dell'IA, funzionino correttamente.

Requisiti per la pubblicazione di immagini container

Per poter utilizzare l'immagine del contenitore con AI Platform Prediction, devi eseguire il push in Artifact Registry. 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 autorizzazioni e posizione.

Località

Il repository deve utilizzare una regione corrispondente all'endpoint regionale in cui prevedi di creare una 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 AI Platform Prediction deve disporre dell'autorizzazione per estrarre l'immagine del contenitore quando crei una versione del modello. Nello specifico, l'agente di servizio AI Platform deve disporre delle autorizzazioni del ruolo Lettore di Artifact Registry (roles/artifactregistry.reader) per il repository dell'immagine del contenitore.

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 AI Platform Prediction, devi concedere il ruolo Lettore di Artifact Registry per il repository di Artifact Registry all'agente di servizio AI Platform.

Accesso agli elementi 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 contenitore personalizzato, la fornitura degli artefatti del modello in Cloud Storage è facoltativa.

Se l'immagine del contenitore include gli elementi del modello necessari per fornire le previsioni, non è necessario caricare i 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 contenitore può scaricare la directory specificata da questo URI per accedere agli elementi 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. Al contrario, AIP_STORAGE_URI fa riferimento 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 i contenuti della directory. Se vuoi utilizzare nuovi elementi del modello, devi creare una nuova versione del modello.

L'account di servizio utilizzato per impostazione predefinita dal contenitore 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 supporta le Credenziali predefinite dell'applicazione (ADC) per caricare gli artefatti del modello. Non è necessario configurare esplicitamente l'autenticazione.

Poiché il contenitore supporta l'ADC per l'agente di servizio di AI Platform 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 contenitore

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 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 del contenitore

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 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 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.

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 della variabile `AIP_MODEL_NAME` e `VERSION` con il valore della variabile `AIP_VERSION_NAME`.	Quando crei una versione del modello, imposta il `routes.health` campo.	Queste variabili specificano il percorso HTTP sul contenitore a cui AI Platform Prediction invia i controlli di integrità.
AIP_HTTP_PORT	`8080`	Quando crei una versione del modello, imposta il `containerSpec.ports` campo. 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 del 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 su cui è in esecuzione il contenitore.
AIP_MODE	`PREDICTION`	Non configurabile	Questa variabile indica che il contenitore è 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 dei requisiti del contenitore personalizzato (questo documento) che AI Platform Prediction si aspetta che il contenitore soddisfi. Questo documento viene aggiornato in base al versionamento semantico.
AIP_MODEL_NAME	Nessun valore predefinito, deve essere configurato	Quando crei un modello (il modello principale della versione del modello che utilizza il contenitore), specifica il `name` campo.	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 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 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 Version

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

Passaggi successivi

Scopri di più sulla pubblicazione delle previsioni utilizzando un contenitore personalizzato.
Per provare a pubblicare le previsioni con un container personalizzato specifico, leggi il tutorial sulla pubblicazione delle previsioni PyTorch.