Esegui automaticamente il deployment dell'applicazione web Go di IA generativa dal controllo delle versioni a Cloud Run

1. Panoramica

Eseguire il deployment di un'applicazione web per la prima volta può sembrare difficile. Anche dopo il primo deployment, se il processo richiede troppo lavoro, potresti evitare di eseguire il deployment di nuove versioni dell'applicazione. Con il deployment continuo, puoi eseguire facilmente il deployment automatico delle modifiche dell'applicazione.

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

Cosa imparerai a fare

  • Scrivere un'applicazione web con l'editor di Cloud Shell
  • Memorizza il codice dell'applicazione su GitHub
  • Esegui automaticamente il deployment dell'applicazione in Cloud Run
  • Aggiungere l'IA generativa all'applicazione utilizzando Vertex AI

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 ti impediscono di attivare le API necessarie per questo lab.
  2. Se non hai ancora un account GitHub, devi crearne uno

3. Configurazione del progetto

  1. Accedi alla console Google Cloud.
  2. Attiva la fatturazione in Cloud Console.
    • Il completamento di questo lab dovrebbe costare meno di 1 $in risorse Cloud.
    • Per eliminare le risorse ed evitare ulteriori addebiti, puoi seguire i passaggi alla fine di questo lab.
    • I nuovi utenti sono idonei per la prova senza costi di 300$.
    • Parteciperai a un evento sull'IA generativa per gli sviluppatori? Potrebbe essere disponibile un credito di 1$.
  3. Crea un nuovo progetto o scegli di riutilizzare un progetto esistente.

4. Apri editor di Cloud Shell

  1. Vai a Cloud Shell Editor.
  2. Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
    • Fai clic sul menu a tre linee Icona del menu di navigazione.
    • Fai clic su Terminale.
    • Fai clic su Nuovo terminaleAprire un nuovo terminale nell'editor di Cloud Shell.
  3. Nel terminale, imposta il 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}'
        
      Impostare l'ID progetto nel terminale dell'editor di Cloud Shell
  4. Se ti viene chiesto di concedere l'autorizzazione, fai clic su Autorizza per continuare. Fai clic per autorizzare Cloud Shell
  5. Dovresti vedere questo messaggio:
    Updated property [core/project].
    
    Se vedi un WARNING e ti viene chiesto Do you want to continue (Y/N)?, è probabile che tu abbia 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 dell'utente Git globale:
    git config --global user.email "you@example.com"
    
  2. Imposta il 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 Go:

  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. Inizializza un file go.mod per dichiarare il nostro modulo:
    go mod init codelab-genai
    
  5. Crea un file main.go:
    touch main.go
    
  6. Apri il file main.go nell'editor di Cloud Shell:
    cloudshell edit main.go
    
    ora nella parte superiore dello schermo dovrebbe apparire un file vuoto. Qui puoi modificare il file main.go. Mostra che il codice deve essere inserito nella sezione superiore dello schermo
  7. Modifica main.go e incolla il seguente codice:
    package main
    
    import (
        "fmt"
        "log"
        "net/http"
        "os"
    )
    
    func main() {
        http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
            fmt.Fprintln(w, "Hello, world!")
        })
    
        port := os.Getenv("PORT")
    
        if port == "" {
            port = "8080"
        }
        if err := http.ListenAndServe(":"+port, nil); err != nil {
            log.Fatal(err)
        }
    }
    
    Dopo alcuni secondi, l'editor di Cloud Shell salverà automaticamente il codice. Questo codice risponde alle richieste HTTP con il saluto "Hello world!".

Il codice iniziale dell'applicazione è stato completato ed è pronto per essere archiviato nel controllo versione.

8. Crea un repository

  1. Torna al terminale Cloud Shell nella parte inferiore dello schermo.
  2. Assicurati di essere ancora nella directory corretta:
    cd ~/codelab-genai
    
  3. Inizializza il repository Git
    git init -b main
    
  4. Accedi a GitHub CLI
    gh auth login
    
    Premi Enter per accettare le opzioni predefinite e segui le istruzioni nello strumento GitHub CLI, tra cui:
    1. A quale account vuoi accedere? GitHub.com
    2. Qual è il protocollo che preferisci per le operazioni Git su questo host? HTTPS
    3. Autenticare Git con le credenziali di GitHub? Y (salta se non viene visualizzata).
    4. Come vuoi autenticare GitHub CLI? 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 GITHUB_USERNAMEvariabile
    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)
    
    Significa che hai già un repository denominato codelab-genai. Hai due opzioni per continuare a seguire questo tutorial:
  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 sul ramo 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/main.go \n\n"

10. Configurare i deployment automatici

  1. Lascia aperta la scheda dell'editor di Cloud Shell. Torneremo a questa scheda in seguito.
  2. In una nuova scheda, vai alla pagina Cloud Run.
  3. Seleziona il progetto Google Cloud corretto nella console Menu a discesa del progetto nella console Google Cloud
  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 Autenticare 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 Seleziona solo i repository 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 i repository connessi.
    6. Lascia Ramo su ^main$
    7. Fai clic su Go, Node.js, Python, Java, .NET Core, Ruby o PHP tramite i buildpack di 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 ad Autenticazione.
  7. Fai clic su Consenti chiamate non autenticate.
  8. Fai clic su CREA.

Al termine della compilazione (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

  1. Torna al terminale Cloud Shell nella parte inferiore dello schermo.
  2. Assicurati di essere ancora nella directory corretta:
    cd ~/codelab-genai
    
  3. Riapri main.go nell'editor di Cloud Shell
    cloudshell edit main.go
    
  4. Installa l'SDK Vertex AI per Go:
    go get cloud.google.com/go/vertexai/genai
    
  5. Installa la libreria di metadati per Go per ottenere l'ID progetto corrente:
    go get cloud.google.com/go/compute/metadata
    
  6. Sostituisci il codice nel file main.go con:
    package main
    
    import (
        "context"
        "fmt"
        "log"
        "net/http"
        "os"
    
        "cloud.google.com/go/compute/metadata"
        "cloud.google.com/go/vertexai/genai"
    )
    
    func main() {
        ctx := context.Background()
        var projectId string
        var err error
        projectId = os.Getenv("GOOGLE_CLOUD_PROJECT")
        if projectId == "" {
            projectId, err = metadata.ProjectIDWithContext(ctx)
            if err != nil {
                return
            }
        }
        var client *genai.Client
        client, err = genai.NewClient(ctx, projectId, "us-central1")
        if err != nil {
            return
        }
        defer client.Close()
    
        model := client.GenerativeModel("gemini-1.5-flash-001")
    
        http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
            animal := r.URL.Query().Get("animal")
            if animal == "" {
                animal = "dog"
            }
    
            resp, err := model.GenerateContent(
                ctx,
                genai.Text(
                    fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)),
            )
    
            if err != nil {
                w.WriteHeader(http.StatusServiceUnavailable)
                return
            }
    
            if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
                htmlContent := resp.Candidates[0].Content.Parts[0]
                w.Header().Set("Content-Type", "text/html; charset=utf-8")
                fmt.Fprint(w, htmlContent)
            }
        })
    
        port := os.Getenv("PORT")
    
        if port == "" {
            port = "8080"
        }
        if err := http.ListenAndServe(":"+port, nil); err != nil {
            log.Fatal(err)
        }
    }
    

12. Esegui di nuovo il deployment

  1. Assicurati di essere 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 su GitHub:
    git push
    
  4. Al termine della compilazione, esegui questo comando e vai all'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 alcuni minuti prima che la compilazione 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) Controlla l'utilizzo di Vertex AI

Come per altri servizi Google Cloud, puoi controllare le operazioni di Vertex AI. Gli audit log ti aiutano a rispondere a domande quali "Chi ha fatto cosa, dove e quando?". Gli audit log amministrativi per Vertex AI sono abilitati per impostazione predefinita. Per eseguire il controllo delle richieste di generazione di contenuti, devi abilitare gli audit log di accesso ai dati:

  1. Nella console Google Cloud, vai alla pagina Log di controllo:

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.
  2. Assicurati che il progetto Google Cloud esistente sia quello in cui crei l'applicazione Cloud Run.
  3. Nella tabella Configurazione degli audit log di accesso ai dati, seleziona Vertex AI API dalla colonna Servizio.
  4. Nella scheda Tipi di log, seleziona i tipi di log di controllo dell'accesso ai dati Admin read e Data read.
  5. Fai clic su Salva.

Dopo averlo attivato, potrai visualizzare i log di controllo per ogni chiamata dell'applicazione. Per visualizzare i log di controllo con i dettagli delle invocazioni:

  1. Torna all'applicazione di cui è stato eseguito il deployment e aggiorna la pagina per attivare il log.
  2. Nella console Google Cloud, vai alla pagina Esplora log:

  3. Nella finestra della query, digita:
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
    protoPayload.serviceName="aiplatform.googleapis.com"
    
  4. Fai clic su Esegui query.

I log di controllo acquisiscono l'utilizzo dell'API Vertex AI, ma non ti consentono di osservare i dati relativi al carico di lavoro, come i prompt o i dettagli della risposta.

14. (Facoltativo) Aumenta l'osservabilità del tuo carico di lavoro di IA

Gli audit log non acquisiscono informazioni relative al carico di lavoro. Per aumentare l'osservabilità dei carichi di lavoro, devi registrare esplicitamente queste informazioni. Per farlo, puoi utilizzare il tuo framework di logging preferito. I passaggi riportati di seguito mostrano un modo per farlo utilizzando la libreria di logging strutturato di Go.

  1. Riapri main.go nell'editor di Cloud Shell
    cloudshell edit ~/codelab-genai/main.go
    
  2. Modifica il blocco di importazione in modo da includere le librerie JSON e di logging strutturato di Go:
    import (
        "context"
        "encoding/json"
        "fmt"
        "log"
        "log/slog"
        "net/http"
        "os"
    
        "cloud.google.com/go/compute/metadata"
        "cloud.google.com/go/vertexai/genai"
    )
    
  3. Dopo aver inizializzato il client Vertex (riga 33), aggiungi le seguenti righe per inizializzare un logger strutturato che utilizzi i campi corretti per Google Cloud Logging:
    opts := &slog.HandlerOptions{
    	Level: slog.LevelDebug,
    	ReplaceAttr: func(group []string, a slog.Attr) slog.Attr {
            if a.Key == slog.LevelKey {
                return slog.Attr{Key: "severity", Value: a.Value}
            }
            if a.Key == slog.MessageKey {
                return slog.Attr{Key: "message", Value: a.Value}
            }
            return slog.Attr{Key: a.Key, Value: a.Value}
    	},
    }
    
    jsonHandler := slog.NewJSONHandler(os.Stdout, opts)
    slog.SetDefault(slog.New(jsonHandler))
    
  4. Dopo aver controllato la presenza di una risposta a GenerateContent (riga 69), aggiungi le seguenti righe all'interno del blocco if:
    jsonBytes, err := json.Marshal(resp)
    if err != nil {
        slog.Error("Failed to marshal response to JSON", "error", err)
    } else {
        jsonString := string(jsonBytes)
        slog.Debug("Complete response content", "json_response", jsonString)
    }
    
    Questo codice scrive in stdout informazioni sui contenuti generati utilizzando il formato logging strutturato. Un agente di logging in Cloud Run acquisisce l'output stampato su stdout e scrive questo formato in Cloud Logging.
  5. Riapri Cloud Shell e digita il seguente comando per assicurarti di trovarti nella directory corretta:
    cd ~/codelab-genai
    
  6. Esegui il commit delle modifiche:
    git commit -am "Observe generated content"
    
  7. Esegui il push delle modifiche su GitHub per attivare il ricollocamento della versione modificata:
    git push
    

Dopo il deployment della nuova versione, puoi osservare le informazioni di debug sulle chiamate a Vertex AI.

Per visualizzare i log dell'applicazione:

  1. Nella console Google Cloud, vai alla pagina Esplora log:

  2. Nella finestra della query, digita:
    LOG_ID("run.googleapis.com%2Fstdout")
    severity=DEBUG
    
  3. Fai clic su Esegui query.

Il risultato della query mostra i log con il prompt e la risposta di Vertex AI, incluse le "valutazioni di sicurezza" che possono essere utilizzate per monitorare le pratiche di sicurezza.

15. (Facoltativo) Pulizia

Sebbene non siano previsti addebiti per Cloud Run quando il servizio non è in uso, ti potrebbero comunque essere addebitati i costi di archiviazione dell'immagine container in Artifact Registry. Puoi eliminare il progetto Cloud per evitare addebiti. L'eliminazione del progetto Cloud interrompe la fatturazione per tutte le risorse utilizzate al suo interno.

Se vuoi, elimina il progetto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Ti consigliamo inoltre di eliminare le risorse non necessarie dal disco CloudShell. Puoi:

  1. Elimina la directory del progetto codelab:
    rm -rf ~/codelab-genai
    
  2. Elimina i pacchetti Go che potresti non aver più bisogno:
    cd ~
    go clean -modcache
    
  3. Attenzione. Questa azione non può essere annullata. Se vuoi eliminare tutto su Cloud Shell per liberare spazio, puoi eliminare l'intera home directory. Assicurati che tutto ciò che vuoi conservare sia salvato altrove.
    sudo rm -rf $HOME
    

16. Complimenti

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

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

Se ti interessa partecipare a uno studio di ricerca sull'esperienza utente (UX) per migliorare i prodotti che utilizzi oggi, registrati qui.

Ecco alcune opzioni per continuare a imparare: