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

1. Zanim zaczniesz

W tym CodeLab (1) skonfigurujesz lokalnie rozszerzenie podsumowujące w panelu Looker, aby można było je wypróbować i rozwijać lokalnie. Następnie (2) wdrożysz rozszerzenie w środowisku produkcyjnym, 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ć działanie rozszerzenia. Wszystkie obowiązkowe sekcje należy wypełnić w kolejności.

Omówienie rozszerzenia do podsumowywania panelu Lookera

Funkcjonalnie rozszerzenie podsumowywania panelu Lookera wysyła dane z panelu Lookera do modelu Gemini w Vertex AI. Model Gemini zwraca podsumowanie danych z panelu oraz zalecenia dotyczące dalszych działań. Rozszerzenie wyświetla podsumowanie i kolejne kroki jako kafelek w panelu, integrując się z interfejsem panelu. To rozszerzenie może też eksportować podsumowanie i dalsze kroki do Slacka lub Google Chat. Rozszerzenie wykorzystuje aplikację frontendową React w połączeniu 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 rozwijać rozszerzenie lokalnie
  • Jak wdrożyć rozszerzenie w wersji produkcyjnej, aby mogli z niego korzystać inni użytkownicy Lookera w instancji Lookera
  • Jak opcjonalnie dostosować skuteczność rozszerzenia i rozszerzyć jego funkcjonalność.
  • Jak zarządzać wdrożonym rozszerzeniem w środowisku produkcyjnym

Czego potrzebujesz

  • instancja Lookera, uzyskana na podstawie licencji oryginalnej Lookera, aktywnej wersji próbnej Lookera Core lub aktywnej licencji Lookera Core.
  • uprawnienia develop i deploy w instancji Lookera.
  • Uprawnienia do edycji panelu, który chcesz wypróbować z rozszerzeniem.
  • klucz 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 tym ćwiczeniu zakładamy, że korzystasz z Linuxa.

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. Aby zainstalować Node, wykonaj te instrukcje.
  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 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 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 w zmiennej środowiskowej PROJECT. Zastąp YOUR_PROJECT_ID identyfikatorem projektu.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI udostępnia model Gemini w kilku 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ż wprowadzać 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 front-endu, aby można było je wypróbować i rozwijać 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. Uruchom lokalny serwer programistyczny dla interfejsu użytkownika
npm run develop
  1. Lokalny serwer interfejsu wyświetla teraz kod JavaScript rozszerzenia pod adresem http://localhost:8080/bundle.js.
  2. Otwórz przeglądarkę i zaloguj się w instancji Lookera.
  3. Wykonaj te instrukcje, aby skonfigurować pusty projekt LookML. Nadaj projektowi nazwę podsumowania panelu. 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 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, w prawym górnym rogu kliknij przycisk „Zapisz zmiany”.
  6. W osobnej karcie przeglądarki przejdź do listy 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 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 z takich połączeń.
  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. W prawym górnym rogu wybierz przycisk „Configure Git” (Skonfiguruj Git). Wybierz „Skonfiguruj puste repozytorium”. Kliknij „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 środowisku IDE Lookera, wybierając „Wróć do projektu” lub ręcznie wróć do niego.
  3. Kliknij przycisk „Sprawdź kod LookML” w prawym górnym rogu. Przycisk zmieni się na „Zatwierdź zmiany i wypchnij”.
  4. Kliknij przycisk „Zatwierdź zmiany i wypchnij”. Dodaj dowolną wiadomość i wybierz „Zatwierdź”.
  5. Wybierz „Wdróż w środowisku produkcyjnym” w prawym górnym rogu IDE Lookera. Udało Ci się dodać rozszerzenie do instancji Lookera.
  6. Otwórz panel Looker, do którego chcesz dodać rozszerzenie.
  7. Wykonaj instrukcje, aby dodać kafelek rozszerzenia do panelu. Dodaj nowe rozszerzenie do panelu jako kafelek.
  8. Upewnij się, że lokalna usługa backendu WebSocket skonfigurowana wcześniej działa.

Gratulacje! Możesz teraz wypróbować w panelu rozszerzenie do podsumowywania danych w panelu Looker. 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.

Podczas działania lokalnego serwera frontendowego możesz wprowadzać zmiany w źródłowym kodzie JavaScript rozszerzenia, a serwer będzie je automatycznie kompilował i przekazywał. Aby zobaczyć zmiany, musisz ponownie załadować rozszerzenie lub stronę panelu.

4. Wdrażanie backendu w gałęzi produkcyjnej

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ć rozszerzenie na swoich panelach bez konieczności konfigurowania własnej usługi backendowej. W tych instrukcjach zakładamy, że backend został już wdrożony na potrzeby prac programistycznych w tym samym środowisku lokalnym.

  1. Aby skonfigurować domyślne dane logowania w aplikacji w środowisku lokalnym z identyfikatorem projektu, wykonaj te instrukcje.
  2. Utwórz repozytorium Artifact Registry dla obrazów Dockera usługi backendu. Zastąp YOUR_REGION nazwą regionu, w którym ma znajdować się 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 kompilację za pomocą Cloud Build, która skompiluje obraz Dockera usługi zaplecza i prześle go do utworzonego przez Ciebie 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 utworzonego obrazu Dockera znajduje się na stronie 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. W sklonowanym repozytorium przejdź do katalogu websocket-service/terraform.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Określ, w której lokalizacji Google Cloud Run chcesz uruchomić usługę backendu Websocket. Wybierz spośród tych lokalizacji.
  2. Edytuj plik variables.tf i zastąp wartości YOUR_PROJECT_ID i 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! Backend usługi WebSocket został wdrożony i działa w Google Cloud Run. Teraz wszystkie instancje rozszerzenia do podsumowywania danych w panelu Looker mogą się komunikować z usługą backendową. Zalecamy, aby zawsze mieć co najmniej 1 występ usługi backendu WebSocket uruchomiony w Cloud Run. Dzięki trwałości usługi backendowej zachowana jest integralność danych przesyłanych WebSocket między usługą backendową a frontendem rozszerzenia. Pomaga to też zachować sesję każdego użytkownika podczas korzystania z rozszerzenia.

5. Wdrażanie frontendu w wersji produkcyjnej

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. Edytujenv. Zastąp YOUR_CLOUD_RUN_URL adresem URL punktu końcowego 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ę w instancji Lookera. Otwórz menu nawigacyjne po lewej stronie i u dołu włącz przełącznik „Tryb programisty”.
  2. Po otwarciu panelu nawigacyjnego po lewej stronie wybierz „Programowanie”, a potem przewiń w dół i wybierz „Podsumowanie panelu” (projekt LookML). Powinna się teraz otworzyć przeglądarka Looker dla projektu LookML.
  3. Przeciągnij i upuść wszystkie pliki z poprzednio wygenerowanego katalogu dist do katalogu głównego projektu w „Przeglądarce plików”. Jeśli potrzebujesz dodatkowej pomocy, postępuj zgodnie z tymi instrukcjami.
  4. Otwórz plik manifest.lkml w 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 poprzedniej sekcji. Zapisz zmiany w pliku.

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

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

Wypróbuj rozszerzenie do podsumowywania panelu Lookera. Zachęcamy do tworzenia rozszerzeń i ułatwiania pracy społeczności Looker. Utwórz żądanie pull w repozytorium.

Zapoznaj się z poniższymi opcjonalnymi sekcjami, aby włączyć eksportowanie do Slacka lub Google Chat, dostosować podsumowania i dalsze czynności w Gemini oraz skonfigurować rejestrowanie 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 kontynuować pracę z tą sekcją Codelab, musisz znać konfigurację OAuth.

Włączanie eksportu z Google Chat

  1. włączyć interfejs Chat API w projekcie Google Cloud;
  2. Wykonaj krok 1 instrukcji konfigurowania OAuth w Google Workspace. W przypadku zakresów musisz uwzględnić spaces.messages.create.
  3. Wykonaj krok 2 instrukcji konfigurowania 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. Edytujenv. Zastąp YOUR_GOOGLE_CLIENT_ID identyfikatorem klienta. Zastąp YOUR_GOOGLE_SPACE_ID identyfikatorem pokoju Google Chat. Zapisz zmiany w pliku. Dzięki temu interfejs rozszerzenia będzie mógł wysyłać statystyki do wybranego pokoju Google Chat.
  6. Jeśli interfejs rozszerzenia jest uruchamiany lokalnie, ponownie skompiluj rozszerzenie. Jeśli wdrażasz interfejs rozszerzenia, ponownie je wdróż.

Włączanie eksportu 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 Slack, na który chcesz wyeksportować podsumowania.
  3. Edytuj plikPlik 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. Spowoduje to skonfigurowanie frontendu rozszerzenia tak, aby możliwe było wysyłanie statystyk do wybranego kanału Slacka.
  4. Jeśli interfejs rozszerzenia jest uruchamiany lokalnie, ponownie skompiluj rozszerzenie. 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ć i wyświetlać listę pokoi i kanałów, do których chcesz wysyłać podsumowania.

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

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

  • Aby dodać szczegóły panelu do panelu, wykonaj te instrukcje. Pomoże to LLM zrozumieć ogólny kontekst panelu.
  • Aby dodać notatki do poszczególnych kart w panelu, postępuj zgodnie z tymi instrukcjami. Dzięki temu LLM będzie znać kontekst każdego zapytania na pulpicie. Te małe kontekstowe notatki 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] Konfigurowanie rejestrowania 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ń. W tej sekcji znajdziesz instrukcje rejestrowania wywołań Vertex AI przez Twoje rozszerzenie, aby można było oszacować i monitorować koszty oraz ruch w Vertex AI. Tych instrukcji należy przestrzegać tylko wtedy, gdy wdrożono usługę backendową WebSocket.

  1. Określ lokalizację Cloud Run dla 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ć. Rozmieściłeś/rozmieściłaś 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?