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

1. Zanim zaczniesz

W tym ćwiczeniu (1) skonfigurujesz lokalnie rozszerzenie do podsumowywania paneli Lookera, aby móc je wypróbować i rozwijać lokalnie. Następnie (2) wdrożysz rozszerzenie w wersji produkcyjnej, aby mogli z niego korzystać inni użytkownicy Lookera w Twojej instancji Lookera. Na koniec (3) możesz wykonać dodatkowe czynności, aby dostosować i ulepszyć funkcje rozszerzenia. Wszystkie sekcje, które nie są opcjonalne, należy wypełniać w kolejności.

Omówienie rozszerzenia do podsumowywania paneli Lookera

Funkcjonalnie rozszerzenie Podsumowanie panelu Looker wysyła dane z panelu Looker do modelu Gemini w Vertex AI. Model Gemini zwraca podsumowanie danych z panelu i wskazuje kolejne kroki. Rozszerzenie wyświetla podsumowanie i dalsze kroki w formie kafelka w panelu, integrując się z jego funkcjami. Rozszerzenie może też eksportować podsumowanie i dalsze kroki do Slacka lub Google Chat. Rozszerzenie korzysta z aplikacji frontendu React połączonej z usługą backendu websocket do wysyłania i odbierania danych do i z modelu Gemini w Vertex AI.

Wymagania wstępne

  • Podstawowa znajomość tworzenia aplikacji w Node.js, Dockera i Terraform
  • znajomość konfiguracji projektu LookML w Lookerze;

Czego się nauczysz

  • Jak skonfigurować i opracować rozszerzenie lokalnie
  • Jak wdrożyć rozszerzenie w wersji produkcyjnej, aby inni użytkownicy Lookera w instancji Lookera mogli z niego korzystać
  • Jak opcjonalnie dostroić skuteczność rozszerzenia i rozszerzyć jego funkcjonalność.
  • Zarządzanie wdrożonym rozszerzeniem w środowisku produkcyjnym

Czego potrzebujesz

  • Instancja Lookera, która może być objęta oryginalną licencją Lookera, aktywną wersją próbną Lookera Core lub aktywną licencją Lookera Core.
  • uprawnienia develop i deploy w instancji Lookera.
  • uprawnienia do edytowania panelu, które chcesz wypróbować w rozszerzeniu.
  • Klucz interfejsu Looker API z instancji Lookera.
  • projekt Google Cloud z włączonymi płatnościami;
  • Interfejsy Cloud Run API, Vertex AI API i Artifact Registry API są włączone w projekcie.
  • Dostęp do środowiska lokalnego z zainstalowanym interfejsem wiersza poleceń gcloud. Instrukcje w tym ćwiczeniu w Codelabs zakładają środowisko w stylu Linuksa.

2. Konfigurowanie backendu na potrzeby programowania lokalnego

W tej sekcji skonfigurujesz usługę backendu websocket, aby móc ją wypróbować i lokalnie rozwijać. Usługa będzie mieć dostęp do Vertex AI.

  1. Zainstaluj w środowisku lokalnym Node w wersji 18 lub nowszej. Aby zainstalować Node, postępuj zgodnie z tymi instrukcjami.
  2. Sklonuj repozytorium rozszerzenia do lokalnego katalogu głównego i otwórz katalog główny repozytorium. Na potrzeby tego ćwiczenia wszystkie przykłady kodu będą zakładać, ż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 umożliwić ustawienie zmiennych środowiskowych w dalszych sekcjach tego kursu.
cd ~/dashboard-summarization
mv .env.example .env
  1. Przejdź do katalogu src backendu gniazda internetowego 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 pliku looker.ini zaktualizuj:
  2. Zastąp symbole client_id i client_secret symbolami z klucza interfejsu Looker API.
  3. base_url z adresem URL instancji Lookera w formacie: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Tekst między nawiasami (nagłówek sekcji) z hostem adresu URL instancji Lookera.

Jeśli na przykład Twój identyfikator klienta to ABC123, tajny klucz klienta to XYZ789, a adres URL instancji Lookera to https://mycompany.cloud.looker.com, Twój 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 w 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 region, z którego 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.

Konfigurowanie usługi backendu websocket w środowisku lokalnym zostało zakończone.

Usługa ta służy jako interfejs między rozszerzeniem frontendu a modelem Gemini w Vertex AI. Usługa pobierze dane z panelu i LookML z rozszerzenia interfejsu z danymi uzyskanymi z Lookera i wyśle prompt do modelu Gemini w Vertex AI. Następnie usługa przesyła strumieniowo odpowiedź Gemini do rozszerzenia interfejsu, aby wyświetlić ją w panelu.

Możesz też wprowadzać zmiany w kodzie źródłowym usługi backendu. Najpierw musisz zatrzymać proces usługi, wprowadzić zmiany w kodzie, a potem ponownie uruchomić polecenie npm start.

3. Konfigurowanie frontendu na potrzeby lokalnego środowiska programistycznego

W tej sekcji skonfigurujesz rozszerzenie interfejsu, aby móc je wypróbować i rozwijać lokalnie.

  1. W tym samym środowisku lokalnym, w którym wykonano poprzednie kroki, przejdź do katalogu głównego sklonowanego repozytorium i zainstaluj zależności serwera frontendu dla frontendu.
cd ~/dashboard-summarization
npm install
  1. Uruchom lokalny serwer programistyczny frontendu
npm run develop
  1. Lokalny serwer frontendu obsługuje teraz JavaScript rozszerzenia pod adresem http://localhost:8080/bundle.js.
  2. Otwórz przeglądarkę i zaloguj się w instancji Lookera.
  3. Aby skonfigurować pusty projekt LookML, postępuj zgodnie z tymi instrukcjami. Nadaj nazwę podsumowaniu panelu projektu. Pusty projekt LookML powinien się teraz automatycznie otworzyć w IDE Lookera na bieżącej karcie przeglądarki.
  4. Utwórz plik manifestu projektu w katalogu głównym projektu LookML. Plik będzie się nazywać manifest.lkml. Jeśli nie wiesz, jak to zrobić, postępuj zgodnie z tymi instrukcjami dotyczącymi dodawania pliku do projektu LookML.
  5. Zastąp zawartość nowego pliku manifest.lkml zawartością pliku manifest.lkml w katalogu głównym zamkniętego repozytorium. Aby zapisać zmiany w pliku, kliknij przycisk „Zapisz zmiany” w prawym górnym rogu.
  6. Na osobnej karcie przeglądarki otwórz listę połączeń z bazą danych w instancji Lookera. Jeśli nie wiesz, jak to zrobić, postępuj zgodnie z tymi instrukcjami.
  7. Wybierz nazwę jednego połączenia z bazą danych Lookera. Nie ma znaczenia, które połączenie wybierzesz. Jeśli nie masz uprawnień do wyświetlania połączeń z bazą danych, skontaktuj się z administratorem Lookera i poproś o podanie nazwy jednego połączenia z bazą danych Lookera.
  8. Wróć do karty przeglądarki z otwartym projektem LookML w środowisku IDE Looker. Utwórz plik modelu w projekcie LookML i nadaj mu nazwę dashboard-summarization.
  9. Zastąp zawartość pliku dashboard-summarization.model.lkml poniższym przykładowym kodem. Pamiętaj, aby zastąpić ciąg znaków 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 chcesz zapisać projekt. W prawym górnym rogu kliknij przycisk „Skonfiguruj Git”. Wybierz „Zamiast tego skonfiguruj puste repozytorium”. Kliknij „Utwórz repozytorium”.
  2. Masz teraz podstawowe puste repozytorium do przechowywania plików projektu LookML. Wróć do projektu w IDE Lookera, klikając „Wróć do projektu” lub ręcznie.
  3. W prawym górnym rogu kliknij przycisk „Sprawdź poprawność LookML”. Przycisk zmieni się na „Zatwierdź zmiany i wypchnij”.
  4. Kliknij przycisk „Zatwierdź zmiany i wypchnij”. Dodaj dowolną wiadomość i kliknij „Zatwierdź”.
  5. W prawym górnym rogu środowiska IDE Looker kliknij „Wdróż w środowisku produkcyjnym”. Rozszerzenie zostało dodane do instancji Lookera.
  6. Otwórz panel Looker, do którego chcesz dodać rozszerzenie.
  7. Aby dodać do panelu kafel rozszerzenia, postępuj zgodnie z instrukcjami. Dodaj nowe rozszerzenie do panelu jako kartę.
  8. Upewnij się, że skonfigurowana wcześniej lokalna usługa backendu WebSocket działa.

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

Gdy lokalny serwer frontendowy jest uruchomiony, możesz wprowadzać zmiany w kodzie źródłowym JavaScript rozszerzenia, a serwer automatycznie skompiluje i udostępni 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ę backendową websocket, aby obsługiwała wszystkie instancje rozszerzenia do podsumowywania paneli w dowolnym panelu w instancji Lookera. Dzięki temu inni użytkownicy Lookera będą mogli wypróbować rozszerzenie na swoich panelach bez konieczności konfigurowania własnej usługi backendu. Zakładamy, że backend został już wcześniej wdrożony na potrzeby lokalnego środowiska programistycznego.

  1. Aby wykonać kolejne kroki, postępuj zgodnie z tymi instrukcjami, aby skonfigurować domyślne dane logowania aplikacji w środowisku lokalnym za pomocą identyfikatora projektu.
  2. Utwórz repozytorium Artifact Registry na obrazy 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 gniazda internetowego 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 regionem i identyfikatorem projektu. Zapisz zmiany w pliku.
  2. Prześlij kompilację za pomocą Cloud Build, która utworzy obraz Dockera usługi backendu i prześle 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 adres 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, w którym zostało utworzone repozytorium Artifact Registry.
  2. W sklonowanym repozytorium przejdź do katalogu websocket-service/terraform.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Określ lokalizację Google Cloud Run, w której chcesz uruchomić usługę backendu WebSocket. Wybierz jedną z tych lokalizacji.
  2. Edytuj plik variables.tf i zastąp zmienne YOUR_PROJECT_ID i YOUR_DOCKER_IMAGE_URL odpowiednimi wartościami. Adres URL obrazu Dockera znajdziesz w kroku 6. Zastąp YOUR_REGION regionem wybranym w kroku 8. Zapisz zmiany w pliku.
  3. Wdróż zasoby, z których będzie korzystać usługa backendu, za pomocą Terraform.
terraform init
terraform plan
terraform apply
  1. Zapisz wdrożony punkt końcowy adresu URL Cloud Run, aby użyć go w następnej sekcji.

Gratulacje! Usługa backendu WebSocket została wdrożona i działa teraz w Google Cloud Run. Teraz wszystkie instancje rozszerzenia Podsumowanie panelu Looker mogą komunikować się z usługą backendową. Zalecamy, aby zawsze mieć co najmniej 1 instancję usługi backendu WebSocket działającą w Cloud Run. Trwałość usługi backendu zapewnia integralność danych przesyłanych strumieniowo między usługą backendu websocket a frontendem rozszerzenia i pomaga utrzymać sesję każdego użytkownika podczas korzystania z rozszerzenia.

5. Wdrażanie frontendu w środowisku produkcyjnym

W tej ostatniej sekcji wykonasz ostatnie kroki wdrażania interfejsu rozszerzenia, aby był on dostępny dla wszystkich użytkowników Lookera w Twojej instancji Lookera.

  1. Przejdź do katalogu głównego sklonowanego repozytorium.
cd ~/dashboard-summarization
  1. Edytuj .env. Zastąp YOUR_CLOUD_RUN_URL adresem URL punktu końcowego Cloud Run z poprzedniej sekcji. Zapisz zmiany w pliku. Spowoduje to skierowanie frontendu rozszerzenia produkcyjnego do usługi backendu WebSocket działającej w Cloud Run.
  2. Utwórz kod JavaScript rozszerzenia. Katalog dist zostanie wygenerowany automatycznie i będzie zawierać plik bundle.js oraz inne pliki.
npm run build
  1. Otwórz przeglądarkę i zaloguj się w instancji Lookera. Otwórz pasek nawigacyjny po lewej stronie i u dołu włącz przełącznik „Tryb programisty”.
  2. Otwórz panel nawigacyjny po lewej stronie, kliknij „Develop” (Programowanie), a potem przewiń w dół i wybierz „dashboard-summarization”, czyli projekt LookML rozszerzenia. Powinno otworzyć się środowisko IDE Lookera dla projektu LookML.
  3. Przeciągnij wszystkie pliki z wcześniej wygenerowanego katalogu dist do katalogu głównego projektu w „Przeglądarce plików”. Jeśli potrzebujesz więcej pomocy, postępuj zgodnie z tymi instrukcjami.
  4. Otwórz plik manifest.lkml w środowisku IDE Lookera. W pliku zastąp wiersz
url: "http://localhost:8080/bundle.js"

z

file: "bundle.js"

Zastąp YOUR_CLOUD_RUN_URL adresem URL punktu końcowego Cloud Run z końca ostatniej sekcji. Zapisz zmiany w pliku.

  1. W prawym górnym rogu kliknij przycisk „Sprawdź poprawność LookML”. Przycisk zmieni się na „Zatwierdź zmiany i wypchnij”.
  2. Kliknij przycisk „Zatwierdź zmiany i wypchnij”. Dodaj dowolną wiadomość i kliknij „Zatwierdź”.
  3. W prawym górnym rogu środowiska IDE Looker kliknij „Wdróż w środowisku produkcyjnym”.

Gratulacje! Wszyscy użytkownicy Lookera w Twojej instancji Lookera mogą teraz dodawać do swoich paneli rozszerzenie do podsumowywania paneli Lookera. Gdy inni użytkownicy Lookera będą korzystać z rozszerzenia, wszystkie jego instancje będą wykonywać wywołania do wdrożonej usługi backendu websocket działającej w Google Cloud Run.

Pamiętaj, że jeśli wprowadzisz jakiekolwiek zmiany w kodzie źródłowym, musisz:

  1. Ponownie skompiluj 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 paneli Lookera. Zachęcamy do współtworzenia rozszerzenia i pomagania w lepszym zaspokajaniu potrzeb społeczności Looker. Możesz utworzyć żądanie pull w repozytorium.

Zapoznaj się z opcjonalnymi sekcjami poniżej, aby włączyć eksportowanie do Slacka lub Google Chat, dostosować podsumowania i następne kroki generowane przez Gemini oraz skonfigurować rejestrowanie Gemini.

6. [Opcjonalnie] Skonfiguruj funkcje eksportu

Teraz, gdy Ty i użytkownicy Lookera wypróbowaliście rozszerzenie Podsumowanie panelu Lookera, podzielcie się jego statystykami z większą liczbą osób. W tej sekcji dowiesz się, jak włączyć wysyłanie podsumowań i dalszych kroków do Google Chat lub Slacka. Aby przejść do tej sekcji ćwiczenia, musisz znać konfigurację protokołu OAuth.

Włącz eksportowanie z Google Chat

  1. włączyć interfejs Chat API w projekcie Google Cloud,
  2. Wykonaj krok 1 z instrukcji konfiguracji OAuth w Google Workspace. W przypadku zakresów musisz dodać spaces.messages.create.
  3. Wykonaj krok 2 w instrukcjach konfiguracji OAuth w Google Workspace. Dodaj adres URL instancji Lookera jako identyfikator URI w sekcji „Autoryzowane źródła JavaScript”, np. https://mycompany.cloud.looker.com. Zapisz wygenerowany identyfikator klienta.
  4. Określ identyfikator pokoju Google Chat, do którego chcesz eksportować podsumowania. Jeśli nie wiesz, jak to zrobić, postępuj zgodnie z tymi instrukcjami.
  5. Edytuj .env. Zastąp YOUR_GOOGLE_CLIENT_ID identyfikatorem klienta. Zastąp YOUR_GOOGLE_SPACE_ID identyfikatorem pokoju czatu Google Chat. Zapisz zmiany w pliku. Skonfiguruje to frontend rozszerzenia, aby mógł wysyłać statystyki do wybranego pokoju czatu w Google Chat.
  6. Jeśli frontend rozszerzenia jest uruchamiany lokalnie, ponownie skompiluj rozszerzenie. Jeśli wdrażasz interfejs rozszerzenia, wdróż go ponownie.

Włącz eksportowanie do Slacka

  1. Aby skonfigurować aplikację OAuth, wykonaj kroki 1 i 2 z oficjalnej dokumentacji dla deweloperów Slacka. 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 Slack, do którego chcesz eksportować podsumowania.
  3. Edytuj .env. 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. Skonfiguruje to interfejs rozszerzenia, aby mógł wysyłać statystyki do wybranego kanału Slack.
  4. Jeśli frontend rozszerzenia jest uruchamiany lokalnie, ponownie skompiluj rozszerzenie. Jeśli wdrażasz interfejs rozszerzenia, wdróż go ponownie.

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, zakodowanego na stałe pokoju czatu Google lub kanału Slack. Możesz dodać kolejne zakresy protokołu OAuth i zmodyfikować kod, aby pobrać i wyświetlić listę przestrzeni i kanałów, na które mają być wysyłane podsumowania.

7. [Opcjonalnie] Dopracuj podsumowanie i dalsze kroki

Rozszerzenie wysyła do modelu Gemini wszystkie metadane panelu i wysyła zapytania o dane. Możesz zwiększyć dokładność, szczegółowość i głębię podsumowań oraz zaleceń, dodając do panelu jak najwięcej metadanych i kontekstu. Wykonaj te czynności w przypadku każdego panelu, którego częścią jest rozszerzenie:

  • Aby dodać szczegóły do panelu, postępuj zgodnie z tymi instrukcjami. Pomoże to modelowi LLM zrozumieć ogólny kontekst panelu.
  • Aby dodać notatki do każdego kafelka na panelu, postępuj zgodnie z tymi instrukcjami. Pomoże to LLM poznać kontekst każdego zapytania na panelu. Małe notatki kontekstowe będą uwzględniane w generowanych podsumowaniach.

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

8. [Opcjonalnie] Skonfiguruj logowanie modelu Gemini

Za każdym razem, gdy użytkownik poprosi rozszerzenie o utworzenie podsumowań dla panelu, rozszerzenie wywoła Vertex AI dla każdego zapytania w panelu oraz wykona jedno końcowe wywołanie w celu sformatowania wszystkich podsumowań. W tej sekcji dowiesz się, jak rejestrować wywołania Vertex AI wykonywane przez rozszerzenie, aby szacować i monitorować koszty i ruch w Vertex AI. Postępuj zgodnie z tymi instrukcjami tylko wtedy, gdy masz wdrożoną usługę backendu WebSocket.

  1. Określ lokalizację Cloud Run wdrożonej usługi backendu WebSocket.
  2. Aby skonfigurować ujście logów, które będzie przekierowywać logi do BigQuery, postępuj zgodnie z tymi instrukcjami. Miejsce docelowe ujścia powinno być BigQuery. Ustaw filtr uwzględniania za pomocą tego przykładowego kodu, w którym YOUR_CLOUD_RUN_LOCATION zastąpiono lokalizacją 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!

Rozszerzenie do podsumowywania paneli Lookera zostało skonfigurowane lokalnie, aby można było je wypróbować. Rozszerzenie zostało też wdrożone w Google Cloud, dzięki czemu inni użytkownicy mogą je wypróbować. Teraz Ty i inni użytkownicy możecie uzyskać dostęp do podsumowań i dalszych kroków opartych na Gemini bezpośrednio na swoich panelach.

10. Co dalej?