Automatyczne wdrażanie generatywnej aplikacji internetowej w Go z kontrolą wersji do Cloud Run

1. Przegląd

Wdrożenie aplikacji internetowej po raz pierwszy może być trudne. Nawet po pierwszym wdrożeniu, jeśli proces jest zbyt pracochłonny, możesz unikać wdrażania nowych wersji aplikacji. Ciągłe wdrażanie umożliwia łatwe automatyczne wdrażanie zmian w aplikacji.

W tym module napiszesz aplikację internetową i skonfigurujesz Cloud Run, aby automatycznie wdrażać aplikację, gdy w kodzie źródłowym aplikacji zostaną wprowadzone zmiany. Następnie zmodyfikuj aplikację i wdroż ją ponownie.

Czego się nauczysz

  • Pisanie aplikacji internetowej za pomocą edytora Cloud Shell
  • Przechowywanie kodu aplikacji w GitHubie
  • Automatyczne wdrażanie aplikacji w Cloud Run
  • Dodawanie generatywnej AI do aplikacji za pomocą Vertex AI

2. Wymagania wstępne

  1. Jeśli nie masz jeszcze konta Google, musisz je utworzyć.
    • Używaj konta osobistego zamiast konta służbowego lub szkolnego. Konta służbowe i szkolne mogą mieć ograniczenia, które uniemożliwiają włączenie interfejsów API potrzebnych w tym module.
  2. Jeśli nie masz jeszcze konta GitHub, musisz utworzyć konto GitHub

3. Konfigurowanie projektu

  1. Zaloguj się w konsoli Google Cloud.
  2. Włącz płatności w konsoli Google Cloud.
  3. Utwórz nowy projekt lub użyj już istniejącego.
  4. Sprawdź, czy płatności są włączone w sekcji Moje projekty na stronie Płatności Cloud.
    • Jeśli w kolumnie Billing account przy nowym projekcie widnieje Billing is disabled:
      1. Kliknij 3 kropki w kolumnie Actions.
      2. Kliknij Zmień płatności.
      3. Wybierz konto rozliczeniowe, którego chcesz używać.
    • Jeśli uczestniczysz w wydarzeniu Gen AI for Devs, konto prawdopodobnie będzie się nazywać Próbne konto rozliczeniowe Google Cloud Platform.

4. Otwórz edytor Cloud Shell

  1. Otwórz edytor Cloud Shell.
  2. Jeśli terminal nie pojawi się u dołu ekranu, otwórz go:
    • Kliknij menu Ikona menu z 3 kreskami.
    • Kliknij Terminal.
    • Kliknij Nowy terminalOtwieranie nowego terminala w edytorze Cloud Shell.
  3. W terminalu ustaw projekt za pomocą tego polecenia:
    • Format:
      gcloud config set project [PROJECT_ID]
    • Przykład:
      gcloud config set project lab-project-id-example
    • Jeśli nie pamiętasz identyfikatora projektu:
      • Aby wyświetlić listę wszystkich identyfikatorów projektów, użyj tego polecenia:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Ustawianie identyfikatora projektu w terminalu edytora Cloud Shell
  4. Jeśli pojawi się pytanie o autoryzację, kliknij Autoryzuj, aby przejść dalej. Kliknij, aby uwierzytelnić się w Cloud Shell
  5. Powinien wyświetlić się ten komunikat:
    Updated property [core/project].
    Jeśli widzisz symbol WARNING i pojawia się pytanie Do you want to continue (Y/N)?, prawdopodobnie identyfikator projektu został wpisany nieprawidłowo. Naciśnij N, a potem Enter i spróbuj ponownie uruchomić polecenie gcloud config set project.

5. Włącz interfejsy API

W terminalu włącz interfejsy API:

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

Wykonanie tego polecenia może potrwać kilka minut, ale powinno ostatecznie wyświetlić komunikat o sukcesie podobny do tego:

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

6. Skonfiguruj Git

  1. Ustaw globalny adres e-mail użytkownika Git:
    git config --global user.email "you@example.com"
  2. Ustaw globalną nazwę użytkownika Git:
    git config --global user.name "Your Name"
  3. Ustaw domyślną gałąź globalną Git na main:
    git config --global init.defaultBranch main

7. Napisz kod

Aby napisać aplikację w Go:

  1. Przejdź do katalogu domowego:
    cd ~
  2. Utwórz katalog codelab-genai:
    mkdir codelab-genai
  3. Przejdź do katalogu codelab-genai:
    cd codelab-genai
  4. Zainicjuj plik go.mod, aby zadeklarować moduł:
    go mod init codelab-genai
  5. Utwórz plik main.go:
    touch main.go
  6. Otwórz plik main.go w edytorze Cloud Shell:
    cloudshell edit main.go
    U góry ekranu powinien pojawić się pusty plik. W tym miejscu możesz edytować plik main.go. Pokaż, że kod należy wpisać w górnej części ekranu
  7. Edytuj plik main.go i wklej do niego ten kod:
    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)
    }
}
    Po kilku sekundach edytor Cloud Shell automatycznie zapisze Twój kod. Ten kod odpowiada na żądania HTTP pozdrowieniem „Hello world!”.

Początkowy kod aplikacji jest gotowy i możesz go zapisać w systemie kontroli wersji.

8. Tworzenie repozytorium

  1. Wróć do terminala Cloud Shell u dołu ekranu.
  2. Upewnij się, że nadal jesteś w odpowiednim katalogu:
    cd ~/codelab-genai
  3. Zainicjuj repozytorium Git
    git init -b main
  4. Logowanie się w GitHub CLI
    gh auth login
    Naciśnij Enter, aby zaakceptować opcje domyślne, i postępuj zgodnie z instrukcjami w narzędziu interfejsu wiersza poleceń GitHub, w tym:
    1. Na które konto chcesz się zalogować? GitHub.com
    2. Jaki jest preferowany protokół operacji Git na tym hoście? HTTPS
    3. Uwierzytelnić Git za pomocą danych logowania do GitHuba? Y (Pomiń, jeśli się nie pojawi).
    4. Jak chcesz uwierzytelnić interfejs wiersza poleceń GitHub? Login with a web browser
    5. Skopiuj kod jednorazowy
    6. Otwórz stronę https://github.com/login/device.
    7. Wklej kod jednorazowy
    8. Kliknij Autoryzuj GitHub.
    9. Dokończ logowanie
  5. Sprawdź, czy jesteś zalogowany:
    gh api user -q ".login"
    Jeśli logowanie się powiodło, powinna się wyświetlić Twoja nazwa użytkownika GitHuba.
  6. Tworzenie zmiennej GITHUB_USERNAME
    GITHUB_USERNAME=$(gh api user -q ".login")
  7. Sprawdź, czy zmienna środowiskowa została utworzona:
    echo ${GITHUB_USERNAME}
    Jeśli zmienna została utworzona, powinna wyświetlić Twoją nazwę użytkownika GitHuba.
  8. Utwórz puste repozytorium GitHub o nazwie codelab-genai:
    gh repo create codelab-genai --private
    Jeśli pojawi się błąd:
    GraphQL: Name already exists on this account (createRepository)
    Masz już repozytorium o nazwie codelab-genai. Aby kontynuować ten samouczek, masz 2 możliwości:
  9. Dodaj repozytorium codelab-genai jako zdalne repozytorium origin:
    git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai

9. Udostępnianie kodu

  1. Sprawdź, czy jesteś w odpowiednim katalogu:
    cd ~/codelab-genai
  2. Dodaj wszystkie pliki z bieżącego katalogu do tego zatwierdzenia:
    git add .
  3. Utwórz pierwszy commit:
    git commit -m "add http server"
  4. Wypchnij zatwierdzenie do gałęzi main repozytorium origin:
    git push -u origin main

Możesz uruchomić to polecenie i otworzyć wynikowy adres URL, aby wyświetlić kod aplikacji na GitHubie:

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. Konfigurowanie automatycznych wdrożeń

  1. Pozostaw otwartą kartę edytora Cloud Shell. Wrócimy do tej karty później.
  2. Na nowej karcie otwórz stronę Cloud Run.
  3. Wybierz odpowiedni projekt Google Cloud w konsoli Menu projektu w konsoli Google Cloud.
  4. Kliknij POŁĄCZ REPOZYTORIUM.
  5. Kliknij SKONFIGURUJ Z CLOUD BUILD.
    1. Jako dostawcę repozytorium wybierz GitHub
        .
      • Jeśli nie jesteś zalogowany(-a) na konto GitHub w przeglądarce, zaloguj się za pomocą swoich danych logowania.
    2. Kliknij Uwierzytelnij, a następnie Dalej.
    3. Po zalogowaniu się na stronie Cloud Run zobaczysz komunikat Aplikacja na GitHubie nie jest zainstalowana w żadnym Twoim repozytorium.
    4. Kliknij przycisk ZAINSTALUJ GOOGLE CLOUD BUILD.
      • Na stronie Konfiguracja instalacji wybierz Tylko wybrane repozytoria i wskaż repozytorium codelab-genai utworzone za pomocą interfejsu CLI.
      • Kliknij Zainstaluj.
      • Uwaga: jeśli masz dużo repozytoriów GitHub, wczytanie listy może potrwać kilka minut.
    5. Wybierz your-user-name/codelab-genai jako repozytorium
        .
      • Jeśli repozytorium nie jest widoczne, kliknij link Zarządzaj połączonymi repozytoriami.
    6. W polu Gałąź pozostaw wartość ^main$.
    7. Kliknij Go, Node.js, Python, Java, .NET Core, Ruby lub PHP za pomocą pakietów kompilacji Google Cloud
        .
      • Pozostaw pozostałe pola (Build context directory, Entrypoint i Function target) bez zmian.
    8. Kliknij Zapisz.
  6. Przewiń w dół do sekcji Uwierzytelnianie.
  7. Kliknij Zezwalaj na nieuwierzytelnione wywołania.
  8. Kliknij UTWÓRZ.

Gdy kompilacja się zakończy (co potrwa kilka minut), uruchom to polecenie i otwórz wynikowy adres URL, aby wyświetlić działającą aplikację:

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. Zmień kod

  1. Wróć do terminala Cloud Shell u dołu ekranu.
  2. Upewnij się, że nadal jesteś w odpowiednim katalogu:
    cd ~/codelab-genai
  3. Ponowne otwieranie pliku main.go w edytorze Cloud Shell
    cloudshell edit main.go
  4. Zainstaluj pakiet Vertex AI SDK dla Go:
    go get cloud.google.com/go/vertexai/genai
  5. Aby uzyskać bieżący identyfikator projektu, zainstaluj bibliotekę metadanych dla języka Go:
    go get cloud.google.com/go/compute/metadata
  6. Zastąp kod w pliku main.go tym kodem:
    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. Wdróż ponownie

  1. Upewnij się, że w Cloud Shell nadal jesteś w odpowiednim katalogu:
    cd ~/codelab-genai
  2. Uruchom te polecenia, aby zatwierdzić nową wersję aplikacji w lokalnym repozytorium Git:
    git add .
git commit -m "add latest changes"
  3. Wypchnij zmiany do GitHuba:
    git push
  4. Po zakończeniu kompilacji uruchom to polecenie i otwórz wdrożoną aplikację:
    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"

Zanim zobaczysz zmiany, może minąć kilka minut, zanim kompilacja się zakończy.

Historię wszystkich wersji znajdziesz tutaj: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (Opcjonalnie) Sprawdzanie wykorzystania Vertex AI

Podobnie jak w przypadku innych usług Google Cloud możesz kontrolować operacje Vertex AI. Logi kontrolne pomagają odpowiedzieć na pytania „kto, co, gdzie i kiedy?”. Logi kontrolne administracyjne dotyczące Vertex AI są domyślnie włączone. Aby kontrolować żądania generowania treści, musisz włączyć logi kontrolne dostępu do danych:

  1. W konsoli Google Cloud otwórz stronę Logi kontrolne:

    Jeśli do znalezienia tej strony użyjesz paska wyszukiwania, wybierz wynik z podtytułem Administracja.
  2. Upewnij się, że istniejący projekt Google Cloud to ten, w którym tworzysz aplikację Cloud Run.
  3. W tabeli Konfiguracja logów kontrolnych dostępu do danych znajdź i wybierz Vertex AI API w kolumnie Usługa.
  4. Na karcie Typy logów wybierz typy logów kontrolnych dostępu do danych Admin read i Data read.
  5. Kliknij Zapisz.

Po włączeniu tej funkcji będziesz mieć dostęp do dzienników kontrolnych każdego wywołania aplikacji. Aby wyświetlić dzienniki kontrolne ze szczegółami wywołań, wykonaj te czynności:

  1. Wróć do wdrożonej aplikacji i odśwież stronę, aby wywołać log.
  2. W konsoli Google Cloud otwórz stronę Eksplorator logów:

  3. W oknie zapytania wpisz:
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"
  4. Kliknij Uruchom zapytanie.

Dzienniki kontroli rejestrują użycie interfejsu Vertex AI API, ale nie umożliwiają obserwowania danych związanych z obciążeniem, takich jak prompty czy szczegóły odpowiedzi.

14. (Opcjonalnie) Zwiększ widoczność zbioru zadań AI

Dzienniki kontroli nie rejestrują informacji związanych ze zbiorem zadań. Aby zwiększyć widoczność zbiorów zadań, musisz jawnie rejestrować te informacje. Możesz to zrobić za pomocą ulubionego frameworka do rejestrowania. Poniższe kroki pokazują jeden ze sposobów na to, jak to zrobić za pomocą biblioteki rejestrowania strukturalnego Go.

  1. Ponowne otwieranie pliku main.go w edytorze Cloud Shell
    cloudshell edit ~/codelab-genai/main.go
  2. Zmień blok importu, aby uwzględnić biblioteki Go do rejestrowania strukturalnego i JSON:
    import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "log/slog"
    "net/http"
    "os"

    "cloud.google.com/go/compute/metadata"
    "cloud.google.com/go/vertexai/genai"
)
  3. Po zainicjowaniu klienta Vertex (wiersz 33) dodaj te wiersze, aby zainicjować rejestrator strukturalny, który używa odpowiednich pól do rejestrowania w Google Cloud:
    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. Po sprawdzeniu odpowiedzi na GenerateContent (wiersz 69) dodaj w bloku if te wiersze:
    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)
}
    Ten kod zapisuje w stdout informacje o wygenerowanych treściach w formacie logowania strukturalnego. Agent logowania w Cloud Run przechwytuje dane wyjściowe drukowane w stdout i zapisuje je w tym formacie w Cloud Logging.
  5. Ponownie otwórz Cloud Shell i wpisz to polecenie, aby sprawdzić, czy jesteś w odpowiednim katalogu:
    cd ~/codelab-genai
  6. Zatwierdź zmiany:
    git commit -am "Observe generated content"
  7. Prześlij zmiany do GitHuba, aby wywołać ponowne wdrożenie zmodyfikowanej wersji:
    git push

Po wdrożeniu nowej wersji możesz obserwować informacje o debugowaniu dotyczące wywołań Vertex AI.

Aby wyświetlić logi aplikacji:

  1. W konsoli Google Cloud otwórz stronę Eksplorator logów:

  2. W oknie zapytania wpisz:
    LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG
  3. Kliknij Uruchom zapytanie.

Wynik zapytania pokazuje logi z promptem i odpowiedzią Vertex AI, w tym „oceny bezpieczeństwa”, które można wykorzystać do monitorowania praktyk związanych z bezpieczeństwem.

15. (Opcjonalnie) Czyszczenie

Cloud Run nie nalicza opłat, gdy usługa nie jest używana, ale może zostać pobrana należność za przechowywanie obrazu kontenera w Artifact Registry. Aby uniknąć opłat, możesz usunąć projekt Cloud. Usunięcie projektu w Cloud spowoduje zaprzestanie naliczania opłat za wszelkie zasoby wykorzystywane w ramach tego projektu.

Jeśli chcesz, usuń projekt:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Możesz też usunąć niepotrzebne zasoby z dysku Cloud Shell. Możesz:

  1. Usuń katalog projektu ćwiczeń z programowania: 
    rm -rf ~/codelab-genai
  2. Usuń pakiety Go, których już nie potrzebujesz: 
    cd ~
go clean -modcache
  3. Ostrzeżenie! Tej czynności nie można cofnąć. Jeśli chcesz usunąć wszystko z Cloud Shell, aby zwolnić miejsce, możesz usunąć cały katalog domowy. Upewnij się, że wszystko, co chcesz zachować, jest zapisane w innym miejscu. 
    sudo rm -rf $HOME

16. Gratulacje

W tym module napiszesz aplikację internetową i skonfigurujesz Cloud Run, aby automatycznie wdrażać aplikację, gdy w jej kodzie źródłowym zostaną wprowadzone zmiany. Następnie zmodyfikowano aplikację i ponownie ją wdrożono.

Jeśli to laboratorium Ci się spodobało, możesz spróbować ponownie w innym języku programowania lub frameworku:

Jeśli chcesz wziąć udział w badaniu wrażeń użytkowników, aby pomóc nam ulepszyć usługi, z których korzystasz, zarejestruj się tutaj.

Oto kilka opcji, które pozwolą Ci kontynuować naukę: