Guida rapida: esegui il deployment del prompt di Vertex AI Studio come applicazione web

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

In Vertex AI Studio, puoi progettare e iterare i prompt e confrontare i risultati di diverse configurazioni e modelli. Una volta terminata la progettazione del prompt, puoi eseguirne il deployment come applicazione web da condividere con i tuoi collaboratori o utenti target per consentire loro di testare l'applicazione web. L'applicazione web è ospitata su Cloud Run ed è disponibile al di fuori della console Google Cloud .

In questa guida rapida imparerai a:

• Creare un prompt con variabili del prompt
• Esegui il deployment del prompt come applicazione web
• Monitora l'avanzamento del deployment e testa l'applicazione di cui è stato eseguito il deployment
• Aggiorna ed esegui nuovamente il deployment del prompt
• Testare l'invio di prompt con il supporto multimodale

Prima di iniziare

Se non hai mai utilizzato Vertex AI Studio, puoi seguire un'altra guida rapida o seguire il corso Google Cloud Skills Boost per imparare le basi di Vertex AI Studio. In questa guida devi avere quanto segue:

1. Un progetto Google Cloud creato con la fatturazione abilitata
2. API Vertex AI abilitata

Sono richieste autorizzazioni aggiuntive

Oltre alle autorizzazioni esistenti per utilizzare Vertex AI Studio, per eseguire il deployment del prompt devi disporre delle seguenti autorizzazioni:

Azione	Autorizzazioni obbligatorie	Finalità
Abilita API aggiuntive	serviceusage.services.enable	Abilita le seguenti API: API Cloud Run Admin (run.googleapis.com) API Identity-Aware Proxy (iap.googleapis.com) API Artifact Registry (artifactregistry.googleapis.com) API Cloud Build (cloudbuild.googleapis.com) API Cloud Logging (logging.googleapis.com)
Concedi le autorizzazioni ai service account	resourcemanager.projects.setIamPolicy	Concedi all' service account predefinito di Compute Engine i seguenti ruoli: Agente di servizio Vertex AI (roles/aiplatform.serviceAgent) Account di servizio Cloud Build (roles/cloudbuild.builds.builder)
Implementare autorizzazioni specifiche	storage.buckets.create run.services.create artifactregistry.repositories.create run.services.setIamPolicy	Durante il deployment, un insieme di codici sorgente verrà caricato in Cloud Storage e poi verrà eseguito il deployment in Cloud Run con la creazione di un nuovo servizio. artifactregistry.repositories.create è necessario per creare un repository per l'immagine container. Il run.services.setIamPolicy è necessario per rendere il servizio accessibile pubblicamente.

Se sei il proprietario del progetto, non devi eseguire ulteriori azioni, ma segui le guide in Vertex AI Studio. Se non sei il proprietario del progetto, chiedi all'amministratore del progetto di eseguire le prime due azioni e poi concederti i ruoli Editor (roles/editor) e Amministratore Cloud Run (roles/run.admin).

Creare un prompt con variabili del prompt

Vai alla pagina di creazione del prompt di Vertex AI Studio, poi fai clic su Aggiungi variabile nella casella di input del prompt.

Nella finestra di dialogo Gestisci variabili del prompt, inserisci un nome variabile e assegnagli un valore. Poi fai clic su Applica.

Nella casella di input del prompt, componi il prompt utilizzando la variabile, quindi regola gli altri parametri. Ad esempio, puoi attivare Grounding con Ricerca Google e impostare "Ottieni sempre le condizioni meteo attuali dal web" come istruzioni di sistema.

Esegui il deployment del prompt come applicazione web

Per eseguire il deployment del prompt come applicazione web, fai clic sul pulsante Crea con il codice nell'angolo in alto a destra. Poi fai clic su Esegui il deployment come app.

Salva il prompt

Verrà visualizzata la finestra di dialogo di salvataggio, poiché il salvataggio è necessario prima che un prompt possa essere implementato. La finestra di dialogo del deployment si aprirà automaticamente dopo il salvataggio del prompt.

Nota: il salvataggio del prompt in una regione per la prima volta può richiedere 2-3 minuti. Dopo 1 minuto, verrà visualizzato un riquadro di avviso. Questa operazione lenta dovrebbe essere eseguita una sola volta. Le successive azioni di salvataggio dei prompt quando utilizzi lo stesso progetto e la stessa regione richiederanno solo pochi secondi.

Abilitare le API per il primo deployment e concedere le autorizzazioni

1. Una volta salvato il prompt, il processo di deployment continuerà. Se questo è il tuo primo deployment, vedrai una finestra di dialogo per l'attivazione delle API richieste. Fai clic su Abilita le API richieste.
2. Una volta abilitate le API, viene visualizzata la finestra di dialogo Crea un'app web. Puoi scegliere tra Autenticazione obbligatoria (tramite Identity-Aware Proxy) o Consenti accesso pubblico.
   • Se viene scelta l'autenticazione richiesta, segui la guida per concedere l'accesso (incluso te).
   • Se scegli l'opzione Consenti accesso pubblico, chiunque può accedere all'app. Pertanto, non includere informazioni sensibili o che consentono l'identificazione personale (PII) nel prompt. Seleziona la casella di controllo Sono consapevole che il deployment di questa app sarà eseguito pubblicamente per confermare.
3. Fai clic su Crea app per avviare il deployment.
4. Se questo è il tuo primo deployment, verrà visualizzata un'altra finestra di dialogo che ti chiede di concedere i ruoli richiesti al account di servizio. Fai clic su Concedi tutto per procedere.

   Nota:se non disponi delle autorizzazioni per abilitare le API o concedere l'accesso, chiedi all'amministratore del progetto di concederti le autorizzazioni necessarie. Per maggiori dettagli, consulta le autorizzazioni aggiuntive richieste.

Se questo è il tuo primo deployment, verrà visualizzata un'altra finestra di dialogo che ti chiede di concedere i ruoli richiesti alaccount di serviziot. Fai clic su Concedi tutto per procedere.

Nota: se non disponi delle autorizzazioni per abilitare le API o concedere l'accesso, chiedi all'amministratore del progetto di concederti le autorizzazioni necessarie. Per maggiori dettagli, consulta le autorizzazioni aggiuntive richieste.

Inizia il deployment

Vertex AI Studio creerà un file ZIP contenente il codice sorgente dell'applicazione web e lo caricherà in un bucket Cloud Storage. Dopo l'avvio del deployment, viene visualizzata la finestra di dialogo Gestisci app web con informazioni sul deployment, come il nome dell'applicazione, la data dell'ultimo deployment, lo stato del deployment e altro ancora.

Monitoraggio dello stato del deployment

Il deployment richiede 2-3 minuti e il relativo stato viene visualizzato nella colonna Stato della finestra di dialogo Gestisci app web. Se chiudi la finestra di dialogo Gestisci app web, puoi riaprirla dal menu sotto il pulsante Crea con il codice.

Al termine del deployment, la colonna dello stato cambierà in Pronto e accanto al nome dell'applicazione verrà visualizzato il pulsante Apri.

Controllo dell'accesso e chiave segreta

La tua applicazione web viene implementata con il controllo dell'accesso Consenti accesso non autenticato attivato per impostazione predefinita. Puoi disattivarla facendo clic sul pulsante dell'icona a forma di matita . Per saperne di più, consulta la sezione Disattivare l'accesso pubblico.

Per fornire una protezione di base, l'applicazione web richiede l'aggiunta di una chiave segreta all'URL per l'invio del prompt. Puoi trovare la chiave segreta nella colonna Chiave segreta. Se apri l'applicazione web da Vertex AI Studio, la chiave verrà aggiunta all'URL.

Apri l'applicazione web e invia il prompt

Fai clic su Apri nella finestra di dialogo Gestisci app web per accedere all'applicazione di cui è stato eseguito il deployment. L'applicazione deve essere aperta con la chiave segreta aggiunta all'URL nel formato ?key=SECRET_KEY.

Inserisci un valore per la variabile e poi fai clic su Invia. Dovresti riuscire a vedere i risultati sulla destra.

Apri l'applicazione web dal menu del pulsante Crea con il codice

Se la tua applicazione web è pronta, puoi aprirla anche dal menu del pulsante Crea con il codice.

Cloud Run è un servizio serverless, il che significa che il container per l'applicazione verrà chiuso se non viene utilizzato attivamente. Pertanto, a volte l'applicazione web può impiegare alcuni secondi per caricarsi o un invio non funziona se l'applicazione web è rimasta inattiva per troppo tempo. L'aggiornamento della pagina dovrebbe risolvere il problema.

Monitorare lo stato dalla campanella di notifica

Puoi anche monitorare lo stato dal menu Notifiche facendo clic sull'icona a forma di campana. L'icona a forma di campana interromperà l'animazione di caricamento e mostrerà un cerchio verde se il deployment viene completato correttamente.

Se fai clic sulla notifica, si aprirà la pagina Cloud Run. L'URL nella pagina Cloud Run non ha la chiave segreta aggiunta. Dovrai aggiungerlo manualmente nel formato ?key=SECRET_KEY.

Aggiorna ed esegui nuovamente il deployment del prompt

Puoi modificare ulteriormente il prompt in Vertex AI Studio e trasformarlo in una conversazione. Poi fai clic sul pulsante Crea con il codice e su Gestisci app per aprire la finestra di dialogo Gestisci app web. Fai clic su Aggiorna app per eseguire nuovamente il deployment dell'applicazione web con il prompt aggiornato.

Viene visualizzata una finestra di dialogo di conferma. Ti informa che se esegui nuovamente il deployment, perderai tutte le modifiche apportate all'applicazione web di cui è stato eseguito il deployment al di fuori di Vertex AI Studio (ad esempio nell'editor del codice sorgente di Cloud Run). Fai clic su Conferma per procedere.

Verrà visualizzata di nuovo la finestra di dialogo Gestisci app web. La procedura è simile a quella del deployment iniziale. Puoi monitorare l'avanzamento nello stesso modo della prima implementazione.

Al termine dell'aggiornamento, puoi riaprire l'applicazione web. Vedrai l'interfaccia utente della conversazione con la variabile del prompt. Inserisci il valore e digita contenuti non vuoti per continuare la conversazione.

Inserire contenuti multimodali

Puoi inserire input come immagini, video, audio e documenti nell'interfaccia utente della conversazione. Gli input supportati dipendono dal modello selezionato per il prompt. Consulta la documentazione sul supporto multimodale per ciascun modello.

Per inserire un file, fai clic sul pulsante con l'icona della graffetta nella casella di input della conversazione.

Potrai interagire con il modello con l'input che fornisci.

Argomenti avanzati

Una volta acquisita familiarità con la procedura di deployment, puoi prendere in considerazione le seguenti azioni.

Modifica il codice sorgente in Cloud Run

Se vuoi personalizzare l'applicazione web, puoi apportare modifiche al codice sorgente in Cloud Run. Apri la pagina del codice sorgente di Cloud Run dalla finestra di dialogo Gestisci app web facendo clic sul pulsante Altro alla fine della riga.

In alternativa, puoi accedere alla pagina della sicurezza dall'applicazione web facendo clic sul link Editor di codice sorgente.

Nella pagina del codice sorgente di Cloud Run, fai clic su Modifica sorgente per avviare la modalità di modifica. Al termine, fai clic su Salva e ridistribuisci.

Nota:Cloud Run non supporta il controllo delle versioni direttamente. Se esegui nuovamente il deployment da Vertex AI Studio, anche le modifiche verranno sovrascritte. Per salvare una versione, puoi fare clic su Scarica ZIP nell'angolo in basso a sinistra per salvare la versione corrente prima di eseguire nuovamente il deployment.

Al termine del nuovo deployment, devi aprire l'applicazione da Vertex AI Studio. Puoi andare alla pagina di Vertex AI Studio dal link nel badge Deployment eseguito da Vertex AI.

Concedi l'accesso

Per concedere l'accesso all'app a utenti o gruppi:

1. Apri la finestra di dialogo Gestisci app web.
2. Fai clic sull'icona a forma di matita nella colonna Controllo accesso. La pagina Sicurezza di Cloud Run si apre in una nuova scheda.
3. Nella pagina di sicurezza di Cloud Run, individua la casella di controllo per Identity-Aware Proxy (IAP). Assicurati che sia selezionata, poi fai clic su Modifica criterio.
4. Verrà visualizzata un'attività secondaria che ti consente di modificare l'accesso. Inserisci gli indirizzi email degli utenti o dei gruppi nel campo Entità. Se sei un utente di un'organizzazione, puoi aggiungere solo utenti della stessa organizzazione.
   
5. Lascia vuoto il campo dei livelli di accesso.
6. Fai clic su Salva.
7. Dopo aver chiuso l'attività secondaria, fai di nuovo clic su Salva nella pagina Cloud Run.
   
   Il secondo passaggio di clic su Salva è necessario perché le modifiche abbiano effetto. Potrebbe anche verificarsi un potenziale ritardo di alcuni minuti prima che la modifica alle norme diventi effettiva.

Disattivare l'accesso pubblico

Quando non hai bisogno che l'applicazione web sia accessibile pubblicamente, puoi disattivarla in Cloud Run. Apri la finestra di dialogo Gestisci app web e fai clic sull'icona a forma di matita nella colonna Controllo accesso. La pagina sicurezza di Cloud Run si aprirà in una nuova scheda.

Puoi anche accedere alla pagina della sicurezza dall'applicazione web facendo clic sul link Impostazioni di sicurezza.

Nella pagina Sicurezza del servizio Cloud Run corrispondente alla tua applicazione web, seleziona Utilizza Cloud IAM per autenticare le richieste in entrata e scegli Autenticazione necessaria. Fai clic su Salva.

Di conseguenza, la tua applicazione web non sarà più accessibile tramite l'URL. Se provi ad accedervi, visualizzerai la pagina Errore: accesso negato.

Attivare di nuovo l'accesso pubblico

Se vuoi riattivare l'accesso pubblico, deseleziona la casella di controllo Utilizza Cloud IAM per autenticare le richieste in entrata e salva. Se scegli Consenti chiamate non autenticate, non funzionerà se il tuo progetto si trova in un'organizzazione. Per ulteriori dettagli, consulta Autenticazione in Cloud Run.

Configura l'accesso locale per lo sviluppo

Nell'anteprima pubblica, il controllo dell'accesso non è ancora supportato. Pertanto, una volta disattivato l'accesso pubblico, l'unico modo per accedere all'applicazione web è configurare un proxy locale. Puoi farlo tramite i comandi gcloud. Innanzitutto, apri Cloud Shell facendo clic sul pulsante icona del terminale nell'angolo in alto a destra della console Google Cloud . Ti verrà chiesto di autorizzare Cloud Shell. Fai clic su Autorizza per continuare.

Al termine, apri la finestra di dialogo Gestisci app web e fai clic sul pulsante Altro alla fine della riga per visualizzare altre azioni. Fai clic su Configura l'accesso locale tramite Cloud Shell.

Un comando verrà aggiunto a Cloud Shell. Premi Invio e attendi il termine della stampa. Fai clic sul link nella riga che inizia con Click on the link to preview. Potrai visualizzare la tua richiesta. Questo link funziona solo quando il comando gcloud è in esecuzione.

Problemi comuni

Errore di autenticazione: nessuna chiave segreta

Se visualizzi il seguente errore, significa che all'URL non è allegata alcuna chiave segreta. Segui le istruzioni per aprire l'applicazione web da Vertex AI Studio oppure copia la chiave segreta dalla finestra di dialogo Gestisci app e aggiungila all'URL nel formato ?key=SECRET_KEY.

Errore di autenticazione: codice segreto non valido

Il seguente errore indica che la chiave aggiunta all'URL non è valida. La chiave segreta è univoca per ogni prompt. Se hai una chiave segreta di un altro prompt, non funzionerà. Segui le istruzioni per aprire correttamente l'applicazione web.

400 Argomento non valido: input vuoto

Si verifica il seguente errore quando hai input nella variabile del prompt, ma la chat è vuota; verrà visualizzato un messaggio di errore 400. Per risolvere il problema, digita un valore non vuoto e invia di nuovo.

400 Argomento non valido: mimeType non è supportato

Se scegli un tipo di file non supportato dal modello, verrà restituito un errore 400. Questo è previsto e dovrai utilizzare altri tipi di file supportati dal modello. Consulta la documentazione sul supporto multimodale per ciascun modello.

Passaggi successivi

• Scopri altre funzionalità di Vertex AI Studio nella documentazione o nel corso Introduzione a Vertex AI Studio Google Cloud Skills Boost.

• Consulta i prezzi di Cloud Run.

• Consulta la sezione Autenticazione in Cloud Run.