Esegui automaticamente il deployment dell'applicazione web Genkit Node.js per l'AI generativa dal controllo versione a Cloud Run

1. Panoramica

Il deployment di un'applicazione web per la prima volta può sembrare difficile. Anche dopo il primo deployment, se il processo è troppo laborioso, potresti evitare di eseguire il deployment di nuove versioni dell'applicazione. Con il deployment continuo, puoi eseguire il deployment automatico delle modifiche alla tua applicazione con facilità.

In questo lab scriverai un'applicazione web e configurerai Cloud Run per eseguire automaticamente il deployment dell'applicazione quando viene apportata una modifica al codice sorgente. Quindi, modifichi l'applicazione ed esegui nuovamente il deployment.

Cosa imparerai a fare

• Scrivere un'applicazione web con l'editor di Cloud Shell
• Archivia il codice dell'applicazione in GitHub
• Eseguire automaticamente il deployment dell'applicazione in Cloud Run

• Aggiungere l'AI generativa alla tua applicazione utilizzando Genkit
• Gestire i prompt LLM utilizzando la libreria dotprompt

2. Prerequisiti

1. Se non hai ancora un Account Google, devi crearne uno.
   • Utilizza un account personale anziché un account di lavoro o della scuola. Gli account di lavoro e della scuola potrebbero avere limitazioni che impediscono l'attivazione delle API necessarie per questo lab.
2. Se non hai già un account GitHub, devi crearne uno
   • Utilizza un account GitHub esistente, se ne hai uno. I nuovi account hanno maggiori probabilità di essere bloccati da GitHub come spam.
   • Configura l'autenticazione a due fattori sul tuo account GitHub per ridurre il rischio che il tuo account venga contrassegnato come spam.

3. Configurazione del progetto

1. Accedi alla console Google Cloud.
2. Abilita la fatturazione in Cloud Console.
   • Il completamento di questo lab dovrebbe costare meno di 1 $in risorse cloud.
   • Per evitare ulteriori addebiti, puoi seguire i passaggi alla fine di questo lab per eliminare le risorse.
   • I nuovi utenti hanno diritto alla prova senza costi di 300$.
   • Parteciperai a un evento Gen AI for Devs? Potrebbe essere disponibile un credito di 1$.
3. Crea un nuovo progetto o scegli di riutilizzarne uno esistente.
4. Verifica che la fatturazione sia abilitata in I miei progetti in Fatturazione Cloud
   • Se il nuovo progetto riporta Billing is disabled nella colonna Billing account:
     1. Fai clic sui tre puntini nella colonna Actions.
     2. Fai clic su Modifica fatturazione.
     3. Seleziona l'account di fatturazione che vuoi utilizzare.
   • Se partecipi a un evento Gen AI for Devs, l'account probabilmente si chiamerà Account di fatturazione di prova di Google Cloud Platform.

4. Apri editor di Cloud Shell

1. Vai all'editor di Cloud Shell.
2. Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
   • Fai clic sul menu a tre linee .
   • Fai clic su Terminale.
   • Fai clic su Nuovo terminale.
3. Nel terminale, imposta il tuo progetto con questo comando:
   • Formato:

     gcloud config set project [PROJECT_ID]
     

   • Esempio:

     gcloud config set project lab-project-id-example
     

   • Se non ricordi l'ID progetto:
     • Puoi elencare tutti gli ID progetto con:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. Se ti viene richiesto di concedere l'autorizzazione, fai clic su Autorizza per continuare.
5. Dovresti vedere questo messaggio:

   Updated property [core/project].
   

   Se visualizzi un WARNING e ti viene chiesto Do you want to continue (Y/N)?, probabilmente hai inserito l'ID progetto in modo errato. Premi N, premi Enter e prova a eseguire di nuovo il comando gcloud config set project.

5. Abilita API

Nel terminale, abilita le API:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

Il completamento di questo comando potrebbe richiedere alcuni minuti, ma alla fine dovrebbe essere visualizzato un messaggio di operazione riuscita simile a questo:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Configura Git

1. Imposta l'email utente Git globale:

   git config --global user.email "[e-mail]"
   

2. Imposta il tuo nome utente Git globale:

   git config --global user.name "Your Name"
   

3. Imposta il ramo predefinito di Git globale su main:

   git config --global init.defaultBranch main
   

7. Scrivi il tuo codice

Per scrivere un'applicazione in Node.js:

1. Vai alla home directory:

   cd ~
   

2. Crea la directory codelab-genai:

   mkdir codelab-genai
   

3. Vai alla directory codelab-genai:

   cd codelab-genai
   

4. Crea un file index.js:

   touch index.js
   

5. Crea il file package.json:

   npm init es6 -y
   

6. Aggiungi express come dipendenza

   npm install express
   

7. Aggiungi il file .gitignore per evitare il commit di node_modules

   echo node_modules/ >> .gitignore
   

8. Apri il file index.js nell'editor di Cloud Shell:

   cloudshell edit index.js
   

   Ora nella parte superiore dello schermo dovrebbe essere visualizzato un file vuoto. Qui puoi modificare questo file index.js.
9. Copia il seguente codice e incollalo nel file index.js aperto:

   import express from 'express';
   
   const app = express();
   app.get('/', async (req, res) => {
       res.send('Hello world!');
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

   Dopo alcuni secondi, Cloud Shell Editor salverà automaticamente il codice. Questo codice risponde alle richieste HTTP con il nostro saluto "Hello world!".

Il codice iniziale per la tua applicazione è pronto per essere archiviato nel controllo delle versioni.

8. Crea un repository

1. Torna al terminale Cloud Shell nella parte inferiore dello schermo.
2. Assicurati di trovarti ancora nella directory corretta:

   cd ~/codelab-genai
   

3. Inizializza il repository Git

   git init -b main
   

4. Accedi all'interfaccia a riga di comando di GitHub

   gh auth login
   

   Premi Enter per accettare le opzioni predefinite e segui le istruzioni nello strumento dell'interfaccia a riga di comando di GitHub, tra cui:
   1. A quale account vuoi accedere? GitHub.com
   2. Qual è il tuo protocollo preferito per le operazioni Git su questo host? HTTPS
   3. Autenticare Git con le tue credenziali GitHub? Y (Salta se non viene visualizzato.)
   4. In che modo vuoi autenticare l'interfaccia a riga di comando di GitHub? Login with a web browser
   5. Copia il codice monouso
   6. Apri https://github.com/login/device
   7. Incolla il codice monouso
   8. Fai clic su Autorizza GitHub.
   9. Completa l'accesso
5. Verifica di aver eseguito l'accesso:

   gh api user -q ".login"
   

   Se hai eseguito correttamente l'accesso, dovresti visualizzare il tuo nome utente GitHub.
6. Crea una variabile GITHUB_USERNAME

   GITHUB_USERNAME=$(gh api user -q ".login")
   

7. Verifica di aver creato la variabile di ambiente:

   echo ${GITHUB_USERNAME}
   

   Se hai creato correttamente la variabile, dovresti visualizzare il tuo nome utente GitHub.
8. Crea un repository GitHub vuoto denominato codelab-genai:

   gh repo create codelab-genai --private
   

   Se ricevi l'errore:

   GraphQL: Name already exists on this account (createRepository)
   

   In questo caso, hai già un repository denominato codelab-genai. Per continuare a seguire questo tutorial, hai due opzioni:
   • Elimina il repository GitHub esistente
   • Crea un repository con un nome diverso e ricordati di modificarlo nei comandi seguenti.
9. Aggiungi il repository codelab-genai come repository remoto origin:

   git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai
   

9. Condividere il codice

1. Verifica di trovarti nella directory corretta:

   cd ~/codelab-genai
   

2. Aggiungi tutti i file nella directory corrente a questo commit:

   git add .
   

3. Crea il primo commit:

   git commit -m "add http server"
   

4. Esegui il push del commit nel branch main del repository origin:

   git push -u origin main
   

Puoi eseguire questo comando e visitare l'URL risultante per visualizzare il codice dell'applicazione su GitHub:

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/index.js \n\n"

10. Configurare i deployment automatici

1. Lascia aperta la scheda dell'editor di Cloud Shell. Torneremo a questa scheda in un secondo momento.
2. In una nuova scheda, visita la pagina Cloud Run.
3. Seleziona il progetto Google Cloud corretto nella console
4. Fai clic su COLLEGA REPO.
5. Fai clic su CONFIGURA CON CLOUD BUILD
   .
   1. Seleziona GitHub come Provider di repository
      • Se non hai eseguito l'accesso al tuo account GitHub nel browser, accedi con le tue credenziali.
   2. Fai clic su Autentica e poi su Continua.
   3. Dopo aver eseguito l'accesso, nella pagina Cloud Run viene visualizzato il messaggio L'app GitHub non è installata in nessun repository.
   4. Fai clic sul pulsante INSTALLA GOOGLE CLOUD BUILD.
      • Nella pagina Configurazione dell'installazione, seleziona Solo repository selezionati e scegli il repository codelab-genai che hai creato tramite la CLI.
      • Fai clic su Installa.
      • Nota: se hai molti repository GitHub, il caricamento potrebbe richiedere alcuni minuti.
   5. Seleziona your-user-name/codelab-genai come repository
      • Se il repository non è presente, fai clic sul link Gestisci repository connessi.
   6. Lascia Branch come ^main$
   7. Fai clic su Go, Node.js, Python, Java, .NET Core, Ruby o PHP tramite i buildpack Google Cloud
      • Lascia invariati gli altri campi (Build context directory, Entrypoint e Function target).
   8. Fai clic su Salva.
6. Scorri verso il basso fino a Autenticazione.
7. Fai clic su Consenti chiamate non autenticate.
8. Fai clic su CREA.

Una volta terminata la build (operazione che richiederà diversi minuti), esegui questo comando e visita l'URL risultante per visualizzare l'applicazione in esecuzione:

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. Modificare il codice

Tornare all'editor di Cloud Shell

Se hai ancora aperto Cloud Shell Editor, puoi saltare questi passaggi.

1. Vai all'editor di Cloud Shell.
2. Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
   • Fai clic sul menu a tre linee .
   • Fai clic su Terminale.
   • Fai clic su Nuovo terminale.
3. Nel terminale, imposta il tuo progetto con questo comando:
   • Formato:

     gcloud config set project [PROJECT_ID]
     

   • Esempio:

     gcloud config set project lab-project-id-example
     

   • Se non ricordi l'ID progetto:
     • Puoi elencare tutti gli ID progetto con:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. Se ti viene richiesto di concedere l'autorizzazione, fai clic su Autorizza per continuare.
5. Dovresti vedere questo messaggio:

   Updated property [core/project].
   

   Se visualizzi un WARNING e ti viene chiesto Do you want to continue (Y/N)?, probabilmente hai inserito l'ID progetto in modo errato. Premi N, premi Enter e prova a eseguire di nuovo il comando gcloud config set project.

Aggiungi Genkit e Vertex AI alla tua applicazione

1. Torna al terminale Cloud Shell nella parte inferiore dello schermo.
2. Assicurati di trovarti ancora nella directory corretta:

   cd ~/codelab-genai
   

3. Installa l'SDK Genkit Node.js:

   npm install @genkit-ai/ai
   

4. Installa l'SDK Genkit Node.js per Vertex AI:

   npm install @genkit-ai/vertexai
   

5. Riapri index.js nell'editor di Cloud Shell

   cloudshell edit ~/codelab-genai/index.js
   

6. Sostituisci il codice nel file index.js con:

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
       const llmResponse = await ai.generate({
           model: gemini15Flash,
           prompt: prompt,
       });
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

1. Assicurati di trovarti ancora nella directory corretta in Cloud Shell:

   cd ~/codelab-genai
   

2. Esegui questi comandi per eseguire il commit di una nuova versione dell'applicazione nel repository Git locale:

   git add .
   git commit -m "add latest changes"
   

3. Esegui il push delle modifiche in GitHub:

   git push
   

4. Al termine della creazione, esegui questo comando e visita l'applicazione di cui è stato eseguito il deployment:

   echo -e "\n\nOnce the build finishes, visit your live application:\n \
       "$( \
           gcloud run services list | \
           grep codelab-genai | \
           awk '/URL/{print $2}' | \
           head -1 \
       )" \n\n"
   

Potrebbero essere necessari diversi minuti prima che la build venga completata e tu possa visualizzare le modifiche.

Puoi visualizzare la cronologia di tutte le revisioni qui: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

12. (Facoltativo) Utilizzare file .prompt con Genkit

1. Torna al terminale Cloud Shell nella parte inferiore dello schermo.
2. Assicurati di trovarti ancora nella directory corretta:

   cd ~/codelab-genai
   

3. Crea una cartella prompts in cui archiviare i prompt:

   mkdir prompts
   

4. Crea un file animal-facts.prompt per creare il tuo primo prompt:

   touch prompts/animal-facts.prompt
   

5. Apri il file animal-facts.prompt nell'editor di Cloud Shell:

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

6. Modifica animal-facts.prompt e incolla il seguente codice:

   ---
   model: vertexai/gemini-1.5-flash
   input:
       schema:
           animal: string
   ---
   
   Give me 10 fun facts about {{animal}}. Return the results as HTML without markdown backticks.
   

7. Apri il file index.js nell'editor di Cloud Shell:

   cloudshell edit ~/codelab-genai/index.js
   

8. Sostituisci il codice nel file index.js con:

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const animalPrompt = ai.prompt('animal-facts');
       const llmResponse = await animalPrompt({animal});
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

1. Assicurati di trovarti ancora nella directory corretta in Cloud Shell:

   cd ~/codelab-genai
   

2. Esegui questi comandi per eseguire il commit di una nuova versione dell'applicazione nel repository Git locale:

   git add .
   git commit -m "add latest changes"
   

3. Esegui il push delle modifiche in GitHub:

   git push
   

4. Al termine della creazione, esegui questo comando e visita l'applicazione di cui è stato eseguito il deployment:

   echo -e "\n\nOnce the build finishes, visit your live application:\n \
       "$( \
           gcloud run services list | \
           grep codelab-genai | \
           awk '/URL/{print $2}' | \
           head -1 \
       )" \n\n"
   

Potrebbero essere necessari diversi minuti prima che la build venga completata e tu possa visualizzare le modifiche.

Puoi visualizzare la cronologia di tutte le revisioni qui: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (Facoltativo) Utilizza i prompt di sistema

Questo passaggio presuppone che tu abbia già aggiunto i file .prompt nel passaggio precedente.

1. Torna al terminale Cloud Shell nella parte inferiore dello schermo.
2. Assicurati di trovarti ancora nella directory corretta:

   cd ~/codelab-genai
   

3. Apri il file animal-facts.prompt nell'editor di Cloud Shell:

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

4. Modifica animal-facts.prompt e incolla il seguente codice:

   ---
   model: vertexai/gemini-1.5-flash
   config:
       temperature: 0.9
   input:
       schema:
           animal: string
   ---
   
   role "system"
   The user should have submitted an animal.
   If the user requests anything besides animal fun facts, respond in a kind and firm manner that you only provide information about fun facts.
   Give the user 10 fun facts about the animal the user provided.
   All responses should be valid HTML without markdown backticks.
   
   role "user"
   {{animal}}
   

1. Assicurati di trovarti ancora nella directory corretta in Cloud Shell:

   cd ~/codelab-genai
   

2. Esegui questi comandi per eseguire il commit di una nuova versione dell'applicazione nel repository Git locale:

   git add .
   git commit -m "add latest changes"
   

3. Esegui il push delle modifiche in GitHub:

   git push
   

4. Al termine della creazione, esegui questo comando e visita l'applicazione di cui è stato eseguito il deployment:

   echo -e "\n\nOnce the build finishes, visit your live application:\n \
       "$( \
           gcloud run services list | \
           grep codelab-genai | \
           awk '/URL/{print $2}' | \
           head -1 \
       )" \n\n"
   

Potrebbero essere necessari diversi minuti prima che la build venga completata e tu possa visualizzare le modifiche.

Puoi visualizzare la cronologia di tutte le revisioni qui: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

14. Complimenti

In questo lab hai scritto un'applicazione web e configurato Cloud Run per eseguire automaticamente il deployment dell'applicazione quando viene apportata una modifica al codice sorgente. Poi hai modificato l'applicazione e l'hai eseguito di nuovo il deployment.

Se ti è piaciuto questo lab, puoi riprovare in un altro linguaggio di programmazione o framework:

• Python
• Node.js
• Go
• Java
• Angular
• Next.js

Ecco alcune opzioni per continuare a imparare:

• Documenti Genkit: Guida introduttiva
• Codelab per aggiungere l'osservabilità alla tua applicazione Node.js: Practical observability techniques for Generative AI application in Javascript
• Codelab per aggiungere un frontend all'applicazione con Next.js: Esegui automaticamente il deployment dell'applicazione web Next.js di IA generativa dal controllo della versione a Cloud Run
• Codelab per mostrare come utilizzare la chiamata di funzione: Come utilizzare la chiamata di funzione di Gemini con Cloud Run
• Codelab per utilizzare l'AI per elaborare i contenuti video: How to use Cloud Run Jobs Video Intelligence API to process a Video scene-by-scene