Ćwiczenie z programowania dotyczące rozszerzenia do podsumowania w panelu Lookera

1. Zanim zaczniesz

W ramach tego ćwiczenia w Codelabs (1) skonfigurujesz rozszerzenie podsumowań panelu Lookera na poziomie lokalnym, aby móc je wypróbować i programować lokalnie. Następnie (2) wdrożysz rozszerzenie w środowisku produkcyjnym, aby mogli z niego korzystać inni użytkownicy Lookera w Twojej instancji Lookera. 3) Możesz też wykonać dodatkowe czynności, aby doprecyzować i ulepszyć funkcje rozszerzenia. Wszystkie nieopcjonalne sekcje należy wypełnić po kolei.

Omówienie rozszerzenia do podsumowywania panelu Lookera

Funkcjonalnie rozszerzenie podsumowywania panelu Lookera wysyła dane z panelu Lookera do modelu Gemini w Vertex AI. Następnie model Gemini zwróci podsumowanie danych z panelu i zlecenie kolejnych kroków. Rozszerzenie wyświetla podsumowanie i kolejne kroki w formie kafelka do panelu, integruje się z nim. To rozszerzenie może też eksportować podsumowanie i dalsze kroki do Slacka lub Google Chat. Rozszerzenie korzysta z aplikacji frontendowej React połączonej z usługą backendu Websocket do wysyłania i odbierania danych do modelu Gemini w Vertex AI.

Wymagania wstępne

  • Podstawowa znajomość programowania węzłów, Dockera i Terraform
  • Znajomość konfigurowania projektu LookML Lookera

Czego się nauczysz

  • Jak skonfigurować i opracować rozszerzenie lokalnie
  • Jak wdrożyć rozszerzenie w wersji produkcyjnej, aby mogli z niego korzystać inni użytkownicy Lookera w instancji Lookera
  • jak opcjonalnie dostosować wydajność rozszerzenia i rozszerzyć jego funkcje;
  • Jak zarządzać wdrożonym rozszerzeniem w środowisku produkcyjnym

Czego potrzebujesz

  • instancji Lookera za pomocą oryginalnej licencji Lookera, aktywnej wersji próbnej Looker Core lub aktywnej licencji Looker Core.
  • uprawnienia develop i deploy w instancji Lookera.
  • Uprawnienia do edytowania panelu, które chcesz wypróbować z rozszerzeniem.
  • klucz interfejsu API Lookera z instancji Lookera.
  • Projekt Google Cloud z włączonymi płatnościami.
  • Cloud Run API, Vertex AI API i Artifact Registry API zostały włączone w projekcie.
  • Dostęp do środowiska lokalnego z zainstalowanym interfejsem wiersza poleceń gcloud. W krokach ćwiczenia w Codelabs zakładamy, że używasz środowiska w stylu Linux.

2. Skonfiguruj backend na potrzeby programowania lokalnego

W tej sekcji skonfigurujesz usługę backendu websocket do wypróbowania i programowania lokalnie. Usługa będzie mieć dostęp do Vertex AI.

  1. Zainstaluj węzeł w wersji 18 lub nowszej zainstalowany w środowisku lokalnym. Postępuj zgodnie z tymi instrukcjami, aby zainstalować Node.
  2. Skopiuj repozytorium rozszerzenia do lokalnego katalogu głównego i przejdź do głównego katalogu repozytorium. Na potrzeby tego ćwiczenia w Codelabs wszystkie przykłady kodu zakładają, że sklonowane repozytorium znajduje się w lokalnym katalogu głównym.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Przejdź do katalogu głównego sklonowanego repozytorium i zmień nazwę pliku .env.example na .env, aby móc ustawić zmienne środowiskowe w dalszych sekcjach tego ćwiczenia z programowania.
cd ~/dashboard-summarization
mv .env.example .env
  1. Przejdź do katalogu src backendu sklonowanego repozytorium. Ten katalog zawiera kod źródłowy serwera.
cd ~/dashboard-summarization/websocket-service/src
  1. Zainstaluj zależności usługi za pomocą NPM.
npm install
  1. Zmień nazwę pliku looker-example.ini na looker.ini.
mv looker-example.ini looker.ini
  1. W aktualizacji pliku Looker.ini:
  2. client_id i client_secret z kluczami z Twojego klucza interfejsu API Lookera.
  3. Pole base_url z adresem URL instancji Lookera w formacie: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Tekst w nawiasach (nagłówku sekcji) z hostem adresu URL instancji Lookera.

Jeśli na przykład identyfikator klienta to ABC123, tajny klucz klienta to XYZ789, a URL instancji Lookera to https://mycompany.cloud.looker.com, plik looker.ini będzie wyglądać dokładnie tak:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Określ identyfikator projektu Google Cloud i ustaw go na zmiennej środowiskowej PROJECT. Zastąp YOUR_PROJECT_ID identyfikatorem projektu.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI udostępnia model Gemini w wielu regionach wymienionych tutaj. Określ, w którym regionie lokalny backend będzie wysyłać i odbierać dane z modelu Gemini w Vertex AI. Ustaw region w zmiennej środowiskowej REGION. Zastąp YOUR_VERTEX_REGION nazwą swojego regionu, np. us-central1.
export REGION="YOUR_VERTEX_REGION"
  1. Teraz uruchom usługę lokalną.
npm start
  1. Lokalna usługa backendu websocket będzie działać pod adresem http://localhost:5000.

Usługa backendu Websocket w środowisku lokalnym została skonfigurowana.

Usługa służy jako interfejs między rozszerzeniem frontendu a modelem Gemini w Vertex AI. Usługa pobierze dane panelu i LookML z rozszerzenia frontendu z danymi pobranymi z Lookera i wyświetli prompt dla modelu Gemini Vertex AI. Następnie usługa strumieniuje odpowiedź Gemini do rozszerzenia frontendu, która zostanie wyświetlona w panelu.

Możesz też wprowadzić zmiany w kodzie źródłowym usługi backendu. Musisz najpierw zatrzymać proces usługi, wprowadzić zmiany w kodzie, a następnie ponownie uruchomić npm start.

3. Skonfiguruj frontend na potrzeby programowania lokalnego

W tej sekcji skonfigurujesz rozszerzenie frontendu, aby je przetestować i programować lokalnie.

  1. W tym samym środowisku lokalnym z poprzednich kroków przejdź do katalogu głównego sklonowanego repozytorium i zainstaluj zależności serwera frontendu dla frontendu.
cd ~/dashboard-summarization
npm install
  1. Uruchamianie lokalnego serwera programistycznego frontendu
npm run develop
  1. Twój lokalny serwer frontendu wyświetla teraz kod JavaScript rozszerzenia dostępny na stronie http://localhost:8080/bundle.js.
  2. Otwórz przeglądarkę i zaloguj się do instancji Lookera.
  3. Wykonaj te instrukcje, aby skonfigurować pusty projekt LookML. Nazwij podsumowanie panelu projektu. Pusty projekt LookML powinien być teraz automatycznie otwierany w IDE Lookera na bieżącej karcie przeglądarki.
  4. Utwórz plik manifestu projektu w katalogu głównym projektu LookML. Będzie on nosił nazwę manifest.lkml. Jeśli nie wiesz, jak dodać plik do projektu LookML, wykonaj te instrukcje.
  5. Zastąp zawartość nowego pliku manifest.lkml zawartością pliku manifest.lkml w katalogu głównym zamkniętego repozytorium. Kliknij przycisk „Zapisz zmiany”. w prawym górnym rogu, aby zapisać zmiany w pliku.
  6. Na osobnej karcie przeglądarki przejdź do listy połączeń z bazą danych w instancji Lookera. Jeśli nie wiesz, jak to zrobić, skorzystaj z tych instrukcji.
  7. Wybierz nazwę jednego połączenia z bazą danych Lookera. Nie ma znaczenia, które połączenie zostanie wybrane. Jeśli nie masz uprawnień do wyświetlania połączeń z bazą danych, skontaktuj się z administratorem Lookera i poproś o nazwę jednego połączenia z bazą danych Lookera.
  8. Wróć do karty przeglądarki z projektem LookML otwartym w IDE Lookera. Utwórz plik modelu w projekcie LookML i nazwij panel podsumowania pliku.
  9. Zastąp zawartość pliku Dashboard-summarization.model.lkml poniższym przykładem kodu. Pamiętaj, aby zastąpić ciąg w cudzysłowie nazwą połączenia z bazą danych wybraną w kroku 9. Zapisz zmiany w pliku.
connection: "<YOUR_CONNECTION_NAME>"
  1. Skonfiguruj repozytorium, w którym będziesz zapisywać projekt. Wybierz opcję „Skonfiguruj Git” w prawym górnym rogu. Wybierz „Skonfiguruj wyłącznie repozytorium”. Wybierz „Utwórz repozytorium”.
  2. Masz teraz podstawowe repozytorium bez zasobów, w którym możesz przechowywać pliki projektów LookML. Wróć do projektu w IDE Lookera, wybierając „Powrót do projektu” lub ręcznie wróć do poprzedniej strony.
  3. Wybierz pole „Zweryfikuj kod LookML”. w prawym górnym rogu. Przycisk zmieni się na „Zatwierdź zmiany i wypchnij”.
  4. Kliknij „Zatwierdź zmiany i przekaż”. Przycisk Dodaj dowolną wiadomość i wybierz „Zatwierdź”.
  5. Wybierz „Wdróż w środowisku produkcyjnym” w prawym górnym rogu Lookera IDE. Udało Ci się dodać rozszerzenie do instancji Lookera.
  6. Przejdź do panelu Lookera, do którego chcesz dodać rozszerzenie.
  7. Wykonaj instrukcje, aby dodać kafelek rozszerzenia do panelu. Dodaj nowe rozszerzenie do panelu jako kafelek.
  8. Sprawdź, czy skonfigurowana wcześniej usługa backendu Websocket jest uruchomiona.

Gratulacje! Możesz teraz wypróbować w swoim panelu rozszerzenie do podsumowywania panelu Lookera. Rozszerzenie wyśle metadane panelu do lokalnego backendu usługi websocket i wyświetli dane wyjściowe Gemini z usługi backendu bezpośrednio w kafelku rozszerzenia panelu.

Gdy lokalny serwer frontendu będzie uruchomiony, możesz wprowadzić zmiany w kodzie źródłowym JavaScript rozszerzenia, a serwer automatycznie skompiluje i wyświetli te zmiany. Aby zobaczyć zmiany, musisz ponownie załadować rozszerzenie lub stronę panelu.

4. Wdrażanie backendu w środowisku produkcyjnym

W tej sekcji skonfigurujesz usługę backendu websocket tak, aby obsługiwała wszystkie instancje rozszerzenia podsumowania panelu w dowolnym panelu w instancji Lookera. Dzięki temu inni użytkownicy Lookera będą mogli wypróbować to rozszerzenie we własnych panelach bez konieczności konfigurowania własnej usługi backendu. Zakładamy w nich, że udało Ci się już wdrożyć backend na potrzeby programowania lokalnego w tym samym środowisku lokalnym.

  1. Postępuj zgodnie z tymi instrukcjami, aby skonfigurować domyślne dane uwierzytelniające aplikacji w środowisku lokalnym za pomocą identyfikatora projektu. Kolejne kroki przydadzą Ci się.
  2. Utwórz repozytorium Artifact Registry dla obrazów Dockera usługi backendu. Zastąp YOUR_REGION regionem, w którym ma się znajdować repozytorium.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Przejdź do katalogu src backendu sklonowanego repozytorium.
cd ~/dashboard-summarization/websocket-service/src
  1. Edytuj plik cloudbuild.yaml i zastąp wszystkie wystąpienia YOUR_REGION i YOUR_PROJECT_ID swoim regionem i identyfikatorem projektu. Zapisz zmiany w pliku.
  2. Prześlij za pomocą Cloud Build kompilację, która skompiluje obraz Dockera usługi backendu i przekaże go do utworzonego właśnie repozytorium Artifact Registry. Zastąp YOUR_REGION regionem, w którym chcesz używać usługi Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. Pamiętaj, że URL nowo utworzonego obrazu Dockera to YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Zastąp YOUR_PROJECT_ID identyfikatorem projektu. Zastąp YOUR_REGION regionem z kroku 2 użytym do utworzenia repozytorium Artifact Registry.
  2. Przejdź do katalogu websocket-service/terraform w sklonowanym repozytorium.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Określ, w której lokalizacji Google Cloud Run chcesz uruchomić usługę backendu Websocket. Wybierz jedną z tych lokalizacji.
  2. Edytuj plik hosts.tf i zastąp YOUR_PROJECT_ID oraz YOUR_DOCKER_IMAGE_URL odpowiednimi wartościami. Sprawdź adres URL obrazu Dockera w kroku 6. Zastąp YOUR_REGION regionem wybranym w poprzednim kroku 8. Zapisz zmiany w pliku.
  3. Wdróż za pomocą Terraform zasoby, których będzie używać usługa backendu.
terraform init
terraform plan
terraform apply
  1. Zapisz wdrożony punkt końcowy adresu URL Cloud Run dla następnej sekcji.

Gratulacje! Usługa backendu Websocket została wdrożona i działa w Google Cloud Run. Teraz wszystkie instancje rozszerzenia podsumowania panelu Lookera mogą komunikować się z usługą backendu. Zalecamy, aby w Cloud Run była zawsze uruchomiona co najmniej 1 instancja usługi backendu websocket. Trwałość usługi backendu zapewnia integralność strumieniowania danych między usługą backendu Websocket a frontendem rozszerzenia oraz pomaga utrzymywać sesję każdego użytkownika, gdy korzysta z rozszerzenia.

5. Wdrażanie frontendu w środowisku produkcyjnym

W tej ostatniej sekcji wykonasz ostatnie kroki wdrażania frontendu rozszerzenia, które będzie dostępne dla wszystkich użytkowników Lookera w Twojej instancji Lookera.

  1. Przejdź do katalogu głównego sklonowanego repozytorium.
cd ~/dashboard-summarization
  1. Edytuj plikenv. Zastąp YOUR_CLOUD_RUN_URL punktem końcowym adresu URL Cloud Run z poprzedniej sekcji. Zapisz zmiany w pliku. Spowoduje to przekierowanie frontendu produkcyjnego do usługi backendu Websocket działającej w Cloud Run.
  2. Utwórz kod JavaScript rozszerzenia. Katalog dist zostanie automatycznie wygenerowany z plikiem bundle.js i innymi plikami.
npm run build
  1. Otwórz przeglądarkę i zaloguj się do instancji Lookera. Otwórz boczny panel nawigacyjny po lewej stronie i włącz „Tryb deweloperski” na dole.
  2. Po otwarciu panelu nawigacyjnego po lewej stronie wybierz „Programowanie”, a potem przewiń w dół i wybierz „Podsumowanie panelu” (projekt LookML). Jesteś teraz w IDE Lookera dla projektu LookML.
  3. Przeciągnij wszystkie pliki z wygenerowanego wcześniej katalogu dist i upuść je w „przeglądarce plików” w katalogu głównym projektu. Jeśli potrzebujesz dodatkowej pomocy, postępuj zgodnie z tymi instrukcjami.
  4. Otwórz plik manifest.lkml w IDE Lookera. Zastąp wiersz w pliku
url: "http://localhost:8080/bundle.js"

z

file: "bundle.js"

Zastąp YOUR_CLOUD_RUN_URL punktem końcowym adresu URL Cloud Run z końca ostatniej sekcji. Zapisz zmiany w pliku.

  1. Wybierz pole „Zweryfikuj kod LookML”. w prawym górnym rogu. Przycisk zmieni się na „Zatwierdź zmiany i wypchnij”.
  2. Kliknij „Zatwierdź zmiany i przekaż”. Przycisk Dodaj dowolną wiadomość i wybierz „Zatwierdź”.
  3. Wybierz „Wdróż w środowisku produkcyjnym” w prawym górnym rogu Lookera IDE.

Gratulacje! Wszystkim użytkownikom Lookera w instancji Lookera włączono teraz możliwość dodania rozszerzenia podsumowań panelu Lookera do swoich paneli. Gdy inni użytkownicy Lookera będą używać tego rozszerzenia, wszystkie jego instancje będą wywoływać wdrożoną usługę backendu Websocket działającą w Google Cloud Run.

Jeśli wprowadzasz zmiany w kodzie źródłowym, musisz:

  1. Ponownie utwórz kod JavaScript rozszerzenia
  2. Zastąp wygenerowane pliki dodane do projektu LookML nowo wygenerowanymi plikami z katalogu dist.
  3. Weryfikowanie, zatwierdzanie i wdrażanie zmian w projekcie LookML w środowisku produkcyjnym

Wypróbuj rozszerzenie do podsumowywania panelu Lookera. Zachęcamy do współtworzenia tego rozszerzenia i pomagania w nim lepiej zaspokajać potrzeby społeczności Lookera. Żądanie pull możesz utworzyć w repozytorium.

Zapoznaj się z sekcjami opcjonalnymi, aby włączyć eksportowanie danych do Slacka/Google Chat, dostroić podsumowania i kolejne kroki Gemini oraz skonfigurować logowanie w Gemini.

6. [Opcjonalnie] Skonfiguruj funkcje eksportu.

Po wypróbowaniu przez Ciebie i Twoich użytkowników Lookera rozszerzenia do podsumowania panelu Lookera możesz udostępniać statystyki tego rozszerzenia większej liczbie odbiorców. Z tej sekcji dowiesz się, jak zezwolić rozszerzeniu na wysyłanie podsumowań i kolejnych kroków do Google Chat lub Slacka. Aby przejść do tej sekcji ćwiczenia z programowania, musisz znać konfigurację protokołu OAuth.

Włączanie eksportu Google Chat

  1. włączyć interfejs Chat API w projekcie Google Cloud;
  2. Wykonaj krok 1 z instrukcji konfiguracji protokołu OAuth w Google Workspace. W przypadku zakresów musisz uwzględnić spaces.messages.create.
  3. Wykonaj krok 2 z instrukcji konfiguracji protokołu OAuth w Google Workspace. Dodaj adres URL instancji Lookera jako identyfikator URI w sekcji „Autoryzowane źródła JavaScript”, na przykład https://mycompany.cloud.looker.com. Zapisz wygenerowany identyfikator klienta.
  4. Określ identyfikator pokoju Google Chat, do którego chcesz wyeksportować podsumowania. Jeśli nie wiesz, jak to zrobić, wykonaj te wskazówki.
  5. Edytuj plikenv. Zastąp YOUR_GOOGLE_CLIENT_ID identyfikatorem klienta. Zastąp YOUR_GOOGLE_SPACE_ID identyfikatorem pokoju Google Chat. Zapisz zmiany w pliku. Spowoduje to skonfigurowanie frontendu rozszerzenia w taki sposób, że będzie on mógł wysyłać statystyki do wybranego pokoju Google Chat.
  6. Jeśli korzystasz z frontendu lokalnie, utwórz rozszerzenie ponownie. W innym przypadku, jeśli wdrażasz frontend rozszerzenia, wdróż ponownie frontend rozszerzenia.

Włącz eksport do Slacka

  1. Wykonaj kroki 1 i 2 z oficjalnych dokumentów dla deweloperów Slack, aby skonfigurować aplikację OAuth. W przypadku zakresów musisz uwzględnić chat:write i channels:read. Zapisz wygenerowany identyfikator klienta i tajny klucz klienta.
  2. Określ identyfikator kanału Slacka, do którego chcesz wyeksportować podsumowania.
  3. Edytuj plikenv. Zastąp YOUR_SLACK_CLIENT_ID identyfikatorem klienta. Zastąp YOUR_SLACK_CLIENT_SECRET tajnym kluczem klienta. Zastąp YOUR_SLACK_CHANNEL_ID identyfikatorem kanału. Zapisz zmiany w pliku. Spowoduje to skonfigurowanie frontendu rozszerzenia tak, aby możliwe było wysyłanie statystyk do wybranego kanału Slacka.
  4. Jeśli korzystasz z frontendu lokalnie, utwórz rozszerzenie ponownie. W innym przypadku, jeśli wdrażasz frontend rozszerzenia, wdróż ponownie frontend rozszerzenia.

Teraz rozszerzenie może eksportować podsumowania bezpośrednio do Slacka lub Google Chat. Pamiętaj, że rozszerzenie może wysyłać podsumowania tylko do określonego na stałe pokoju czatu Google lub kanału na Slacku. Możesz dodać dodatkowe zakresy protokołu OAuth i zmodyfikować kod, aby pobierać oraz wyświetlać listę pokoi i kanałów, do których chcesz wysyłać podsumowania.

7. [Opcjonalnie] Dostosowywanie podsumowania i kolejnych kroków

Rozszerzenie prosi model Gemini o wszystkie metadane i dane zapytań z panelu. Możesz zwiększyć dokładność i szczegółowość podsumowań i kroków wymaganych, dodając jak najwięcej metadanych i kontekstu do samego panelu. W przypadku każdego panelu, do którego należy Twoje rozszerzenie, wykonaj te czynności:

  • Aby dodać szczegóły panelu do panelu, wykonaj te wskazówki. Dzięki temu LLM otrzyma informacje o ogólnym kontekście panelu.
  • Aby dodać notatki do kafelka każdego panelu, postępuj zgodnie z tymi instrukcjami. Dzięki temu LLM będzie wiedzieć o kontekście każdego zapytania w panelu. Niewielkie uwagi kontekstowe będą uwzględniane w wygenerowanych podsumowaniach.

Im więcej informacji dodasz do paneli, tym lepsze będą podsumowania rozszerzeń i kolejne kroki. Możesz zmodyfikować kod, aby uwzględnić dodatkowe metadane panelu w prompcie skierowanym do modelu Gemini.

8. [Opcjonalnie] Skonfiguruj logowanie modelu Gemini

Za każdym razem, gdy użytkownik poprosi rozszerzenie o utworzenie podsumowań dla panelu, wywoła ono w Vertex AI każde zapytanie w panelu oraz jedno ostatnie wywołanie w celu sformatowania wszystkich podsumowań. Z tej sekcji dowiesz się, jak rejestrować wywołania Vertex AI generowane przez rozszerzenie. Dzięki temu możesz oszacować i monitorować koszty oraz ruch Vertex AI. Wykonaj te instrukcje tylko wtedy, gdy usługa backendu Websocket została wdrożona.

  1. Określ lokalizację w Cloud Run wdrożonej usługi backendu Websocket.
  2. Wykonaj te instrukcje, aby skonfigurować ujście logów, które będzie kierować logi do BigQuery. Miejscem docelowym ujścia powinno być BigQuery. Ustaw filtr uwzględniania na podstawie poniższego przykładowego kodu, zastępując fragment YOUR_CLOUD_RUN_LOCATION lokalizacją w Cloud Run z poprzedniego kroku.
resource.type = "cloud_run_revision"
resource.labels.service_name = "websocket-service"
resource.labels.location = "YOUR_CLOUD_RUN_LOCATION"
 severity>=DEFAULT
jsonPayload.component="dashboard-summarization-logs"

9. Gratulacje!

Masz skonfigurowane lokalnie rozszerzenie podsumowania panelu Lookera, które możesz wypróbować. Wdrożyłeś też rozszerzenie w Google Cloud, aby inni użytkownicy mogli je wypróbować. Teraz Ty i inni użytkownicy możecie korzystać z podsumowań wygenerowanych przez Gemini i kolejnych kroków bezpośrednio w swoich panelach.

10. Co dalej?