Automatycznie wdrażaj aplikację internetową Genkit Genkit generatywnej AI z kontroli wersji do Cloud Run

1. Omówienie

Wdrażanie aplikacji internetowej po raz pierwszy może wydawać się niezwykle skomplikowanym zadaniem. Nawet po pierwszym wdrożeniu, jeśli proces wymaga zbyt dużo pracy, możesz nie wdrażać nowych wersji aplikacji. Dzięki ciągłemu wdrażaniu możesz łatwo wdrażać zmiany w aplikacji.

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

Czego się nauczysz

• Tworzenie 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ą Genkit
• Zarządzanie promptami LLM za pomocą biblioteki dotprompt

2. Wymagania wstępne

1. Jeśli nie masz jeszcze konta Google, utwórz je.
   • Używasz konta osobistego, a nie 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 laboratorium.
2. Jeśli nie masz jeszcze konta GitHub, musisz utworzyć je.
   • Użyj istniejącego konta GitHub, jeśli je masz. GitHub chętniej blokuje nowe konta jako spam.
   • Skonfiguruj uwierzytelnianie dwuskładnikowe na koncie GitHub, aby zmniejszyć ryzyko oznaczenia Twojego konta jako spamu.

3. Konfigurowanie projektu

1. Zaloguj się w konsoli Google Cloud.
2. Włącz rozliczenia w Cloud Console.
   • Ukończenie tego ćwiczenia powinno kosztować mniej niż 1 USD w zasobach Cloud.
   • Aby uniknąć dalszych opłat, możesz usunąć zasoby, wykonując czynności opisane na końcu tego laboratorium.
   • Nowi użytkownicy mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.
   • Bierzecie udział w wydarzeniu poświęconym generatywnej sztucznej inteligencji dla programistów? Możesz otrzymać 1 USD w gotówce.
3. Utwórz nowy projekt lub użyj istniejącego.

4. Otwórz edytor Cloud Shell

1. Otwórz Edytor Cloud Shell.
2. Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
   • Kliknij menu z 3 kreskami 
   • Kliknij Terminal.
   • Kliknij Nowy terminal.
3. W terminalu skonfiguruj 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ć wszystkie identyfikatory projektów, użyj:

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

     
4. Jeśli pojawi się pytanie o autoryzację, kliknij Autoryzuj, aby kontynuować.
5. Powinien wyświetlić się ten komunikat:

   Updated property [core/project].
   

   Jeśli zobaczysz WARNING i usłyszysz pytanie Do you want to continue (Y/N)?, prawdopodobnie nieprawidłowo wpisano identyfikator projektu. Naciśnij N, a potem Enter i spróbuj ponownie uruchomić polecenie gcloud config set project.

5. Włącz interfejsy API

Włącz w terminalu te interfejsy API:

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

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

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

6. Skonfiguruj Git

1. Ustaw adres e-mail globalnego użytkownika git:

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

2. Ustaw globalną nazwę użytkownika Git:

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

3. Ustaw globalną gałąź domyślną git na main:

   git config --global init.defaultBranch main
   

7. Tworzenie kodu

Aby napisać aplikację w Node.js:

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. Utwórz plik index.js:

   touch index.js
   

5. Utwórz plik package.json:

   npm init es6 -y
   

6. Dodaj express jako zależność

   npm install express
   

7. Dodaj plik .gitignore, aby zapobiec zatwierdzaniu node_modules

   echo node_modules/ >> .gitignore
   

8. Otwórz plik index.js w edytorze Cloud Shell:

   cloudshell edit index.js
   

   W górnej części ekranu powinien pojawić się pusty plik. Tutaj możesz edytować plik index.js.
9. Skopiuj ten kod i wklej go do otwartego pliku index.js:

   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}`);
   });
   

   Po kilku sekundach edytor Cloud Shell automatycznie zapisze 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 na dole ekranu.
2. Upewnij się, że nadal jesteś w właściwym katalogu:

   cd ~/codelab-genai
   

3. Inicjowanie repozytorium Git

   git init -b main
   

4. Zaloguj się w GitHub CLI

   gh auth login
   

   Naciśnij Enter, aby zaakceptować domyślne opcje, i postępuj zgodnie z instrukcjami w narzędziu GitHub CLI, w tym:
   1. Na które konto chcesz się zalogować? GitHub.com
   2. Który protokół jest preferowany do operacji Git na tym hoście? HTTPS
   3. Uwierzytelnianie Git za pomocą danych logowania do GitHuba? Y (pomiń, jeśli ta opcja się nie wyświetla).
   4. Jak chcesz uwierzytelnić GitHub CLI? 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. Zaloguj się
5. Sprawdź, czy jesteś zalogowany(-a):

   gh api user -q ".login"
   

   jeśli się uda, powinna zostać wyświetlona Twoja nazwa użytkownika w GitHub.
6. Utwórz zmienną GITHUB_USERNAME

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

7. Sprawdź, czy utworzysz zmienną środowiskową:

   echo ${GITHUB_USERNAME}
   

   Jeśli utworzenie zmiennej się powiedzie, powinna zostać wyświetlona nazwa użytkownika GitHub.
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 opcje:
   • Usuń istniejące repozytorium GitHub
   • Utwórz repozytorium o innej nazwie i pamiętaj, aby zmienić ją w kolejnych poleceniach.
9. Dodaj repozytorium codelab-genai jako repozytorium zdalne origin:

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

9. Udostępnianie kodu

1. Sprawdź, czy jesteś w właściwym katalogu:

   cd ~/codelab-genai
   

2. Dodaj wszystkie pliki w bieżącym katalogu do tego zatwierdzenia:

   git add .
   

3. Utwórz pierwszy commit:

   git commit -m "add http server"
   

4. Wypchnij zatwierdzanie do gałęzi main repozytorium origin:

   git push -u origin main
   

Aby wyświetlić kod aplikacji na GitHubie, uruchom to polecenie i otwórz otrzymany adres URL:

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

1. Pozostaw otwartą kartę Edytor Cloud Shell. Wrócimy do tej karty później.
2. W nowej karcie otwórz stronę Cloud Run.
3. Wybierz odpowiedni projekt Google Cloud w konsoli
4. Kliknij POŁĄCZ REPOSITORYUM.
5. Kliknij SKONFIGURETUJ Z CLOUD BUILD
   .
   1. Jako Dostawca repozytorium
      wybierz GitHub.
      • Jeśli nie jesteś zalogowany(-a) na konto GitHub w przeglądarce, zaloguj się, podając swoje dane logowania.
   2. Kliknij kolejno Uwierzytelnij i 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 wybierz repozytorium codelab-genai utworzone za pomocą CLI.
      • Kliknij Zainstaluj.
      • Uwaga: jeśli masz dużo repozytoriów GitHub, wczytywanie może potrwać kilka minut.
   5. Jako repozytorium
      wybierz your-user-name/codelab-genai.
      • Jeśli repozytorium jest nieobecne, 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 zostanie ukończona (co może potrwać kilka minut), uruchom to polecenie i otwórz adres URL, który zostanie wyświetlony, aby wyświetlić uruchomioną 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

Wróć do edytora Cloud Shell

Jeśli nadal masz otwarty edytor Cloud Shell, możesz pominąć te czynności.

1. Otwórz Edytor Cloud Shell.
2. Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
   • Kliknij menu z 3 kreskami 
   • Kliknij Terminal.
   • Kliknij Nowy terminal.
3. W terminalu skonfiguruj 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ć wszystkie identyfikatory projektów, użyj:

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

     
4. Jeśli pojawi się pytanie o autoryzację, kliknij Autoryzuj, aby kontynuować.
5. Powinien wyświetlić się ten komunikat:

   Updated property [core/project].
   

   Jeśli zobaczysz WARNING i usłyszysz pytanie Do you want to continue (Y/N)?, prawdopodobnie nieprawidłowo wpisano identyfikator projektu. Naciśnij N, naciśnij Enter i spróbuj ponownie uruchomić polecenie gcloud config set project.

Dodawanie Vertex AI do aplikacji

1. Wróć do terminala Cloud Shell na dole ekranu.
2. Upewnij się, że nadal jesteś w właściwym katalogu:

   cd ~/codelab-genai
   

3. Zainstaluj pakiet SDK Genkit dla Node.js:

   npm install @genkit-ai/ai
   

4. Zainstaluj pakiet SDK Genkit dla Vertex AI w Node.js:

   npm install @genkit-ai/vertexai
   

5. Zainstaluj pakiet Google Auth SDK dla Node.js:

   npm install google-auth-library
   

6. Ponownie otwórz plik index.js w edytorze Cloud Shell

   cloudshell edit ~/codelab-genai/index.js
   

7. Zastąp kod w pliku index.js kodem:

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

12. Wdróż ponownie

1. Upewnij się, że nadal jesteś w odpowiednim katalogu w Cloud Shell:

   cd ~/codelab-genai
   

2. Aby zacommitować nową wersję aplikacji do lokalnego repozytorium Git, uruchom te polecenia:

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

3. Prześlij 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"
   

Utworzenie wersji może potrwać kilka minut.

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

13. (Opcjonalnie) Sprawdzanie korzystania z Vertex AI

Podobnie jak w przypadku innych usług Google Cloud, możesz przeprowadzić audyt operacji Vertex AI. Logi kontrolne pomagają odpowiedzieć na pytania „kto, co, gdzie i kiedy?”. Logi kontrolne administracyjne Vertex AI są domyślnie włączone. Aby weryfikować prośby o generowanie treści, musisz włączyć logi kontrolne dostępu do danych:

Logi kontroli danych mogą powodować dodatkowe koszty.

1. W konsoli Google Cloud otwórz stronę Logi audytu:
   Otwórz stronę Logi audytu
   Jeśli do znalezienia tej strony użyjesz paska wyszukiwania, wybierz wynik z podtytułem Administracja.
2. Upewnij się, że tworzysz aplikację Cloud Run w istniejącym projekcie Google Cloud.
3. W tabeli Konfiguracja logów kontrolnych dostępu do danych znajdź kolumnę Usługa i kliknij Vertex AI API.
4. Na karcie Typy logów wybierz typy logów kontrolnych Dostęp do danych: Admin read i Data read.
5. Kliknij Zapisz.

Po włączeniu tej opcji będziesz mieć dostęp do dzienników kontrolnych dotyczących każdego wywołania aplikacji. Aby wyświetlić dzienniki kontrolne z informacjami o wywołaniu, wykonaj te czynności:

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

   LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
   protoPayload.serviceName="aiplatform.googleapis.com"
   

4. Kliknij Uruchom zapytanie.

W logach audytu rejestrowane jest korzystanie z interfejsu Vertex AI API, ale nie zawierają one danych związanych z obciążeniem, takich jak prompty czy szczegóły odpowiedzi.

14. (Opcjonalnie) Zwiększanie możliwości obserwacji zadań związanych z AI

Logi audytu nie zawierają informacji związanych z obciążeniem pracą. Aby zwiększyć możliwości monitorowania obciążeń, musisz jawnie rejestrować te informacje. W tym celu możesz użyć ulubionego frameworku rejestrowania. W następujących krokach pokażemy, jak to zrobić za pomocą natywnego mechanizmu rejestrowania Node.js.

1. Ponownie otwórz plik index.js w edytorze Cloud Shell

   cloudshell edit ~/codelab-genai/index.js
   

2. Po wywołaniu funkcji await generativeModel.generateContent(prompt) (wiersz 19) dodaj ten wiersz:

       console.log(JSON.stringify({
           severity: 'DEBUG',
           message: 'Content is generated',
           prompt: prompt,
           response: resp.response,
       }));
   

   Ten kod zapisuje w pliku stdout informacje o wygenerowanej treści w formacie zrejestrowanego logowania. Agent rejestrowania w Cloud Run rejestruje dane wyjściowe wydrukowane w formacie stdout i zapisuje je w Cloud Logging.
3. Ponownie otwórz Cloud Shell i wpisz to polecenie, aby sprawdzić, czy jesteś we właściwym katalogu:

   cd ~/codelab-genai
   

4. Zatwierdź zmiany:

   git commit -am "observe generated content"
   

5. Prześlij zmiany do GitHuba, aby wywołać ponowne wdrożenie zmodyfikowanej wersji:

   git push
   

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

Aby wyświetlić dzienniki aplikacji:

1. W konsoli Google Cloud otwórz stronę Eksplorator logów:
   Otwórz Eksplorator logów
   
2. W oknie zapytania wpisz:

   LOG_ID("run.googleapis.com%2Fstdout")
   severity=DEBUG
   

3. Kliknij Uruchom zapytanie.

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

Zachowaj ostrożność podczas logowania promptów, ponieważ mogą one zawierać informacje poufne, które nie są przeznaczone do obserwacji. Możesz zamaskować te informacje lub w inny sposób je ukryć. Aby dowiedzieć się więcej, zapoznaj się z dokumentacją DLP.

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 Cloud powoduje zaprzestanie naliczania opłat za wszystkie zasoby używane w tym projekcie.

Jeśli chcesz, możesz usunąć projekt:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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

1. Usuń katalog projektu ćwiczeń z programowania:

   rm -rf ~/codelab-genai
   

2. 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 gdzie indziej.

   sudo rm -rf $HOME
   

16. Gratulacje

W tym module napisano aplikację internetową i skonfigurowano Cloud Run, aby automatycznie wdrażać aplikację po wprowadzeniu zmiany w kodzie źródłowym. Następnie zmodyfikowałeś aplikację i ponownie ją wdrożyłeś.

Jeśli podobał Ci się ten warsztat, możesz go powtórzyć w innym języku programowania lub środowisku programistycznym:

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

Jeśli chcesz wziąć udział w badaniu wrażeń użytkowników (UX), aby ulepszyć produkty, z których korzystasz, zarejestruj się tutaj.

Oto kilka opcji dalszej nauki:

• Dokumentacja: użyj Firebase GenKit jako elastycznej abstrakcji modelu, która ułatwia integrację dowolnego interfejsu API modelu i używanie modeli obsługiwanych przez społeczność.
• Ćwiczenie: jak wdrożyć aplikację do czatu z użyciem Gemini w Cloud Run
• Jak używać wywoływania funkcji Gemini z Cloud Run
• Jak za pomocą interfejsu Cloud Run Jobs Video Intelligence API przetwarzać filmy według scen
• Warsztat na żądanie: Wprowadzenie do Google Kubernetes Engine