Umieszczanie Lookera w analityce konwersacyjnej

1. Zanim zaczniesz

To ćwiczenie prowadzi użytkowników przez proces integrowania osadzonego panelu Looker z czatem opartym na analityce konwersacyjnej, aby stworzyć ujednoliconą platformę danych opartą na języku naturalnym. Aby w pełni wykorzystać tę funkcję, musisz znać osadzanie Lookera, analitykę konwersacyjną, JavaScript i React.

Czego się nauczysz

Po ukończeniu tego ćwiczenia nauczysz się:

• Konfigurowanie lokalnie aplikacji referencyjnej Looker Embed
• Tworzenie komponentu czatu w React za pomocą biblioteki komponentów Lookera
• Jak wysłać filtr panelu wbudowanego jako kontekst do analityki konwersacyjnej
• Jak włączyć czat oparty na analityce konwersacyjnej, aby kontrolować filtry w osadzonym panelu

Czego potrzebujesz

Aby ukończyć to ćwiczenie, potrzebujesz:

• Instancja Lookera z zainstalowanym blokiem Lookera ASC Demographic Data i włączonym osadzaniem SSO.
• Dostęp do interfejsu API i narzędzi dla deweloperów w instancji Lookera
• środowisko lokalne z zainstalowanymi Node w wersji 18, yarn, Git i gcloud;
• projekt w chmurze z tymi rolami IAM skonfigurowanymi na Twoim koncie użytkownika:
• roles/bigquery.dataViewer Wyświetlający dane BigQuery
• roles/bigquery.user Użytkownik BigQuery
• roles/looker.instanceUser Użytkownik instancji Lookera

2. Konfigurowanie analityki konwersacyjnej

Skonfigurujmy agenta danych analityki konwersacyjnej, którego czat w osadzonym panelu będzie używać do odpowiadania na pytania zadawane w języku naturalnym.

Uwierzytelnianie za pomocą gcloud

1. Uwierzytelnij się za pomocą konta użytkownika w środowisku lokalnym:

gcloud auth login

2. Ustaw domyślne dane logowania aplikacji (ADC) i projekt rozliczeniowy w gcloud:

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Włączanie interfejsów API analityki konwersacyjnej

3. Włącz interfejsy API projektu w chmurze. Zastąp YOUR_PROJECT_ID identyfikatorem Twojego projektu w chmurze Google Cloud:

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

Tworzenie agenta danych

4. Otwórz Google Colab.
5. W Google Colab załaduj ten notatnik z repozytorium Looker Embed Reference.
6. Uruchom wszystkie kroki w notatniku. Będziesz potrzebować identyfikatora projektu w chmurze i identyfikatora URI instancji Lookera z ukośnikiem na końcu, np. "https://my.looker.app/". Na końcu notatnika powinien pojawić się wynik.

Masz teraz dostępnego agenta danych Analityki konwersacyjnej, który jest gotowy do odbierania wiadomości na czacie, wysyłania zapytań do eksploracji Lookera w osadzonym panelu Lookera oraz zwracania wyników i wizualizacji.

3. Konfigurowanie dokumentacji umieszczania Lookera

Skonfigurujmy aplikację referencyjną Looker Embed w środowisku lokalnym, aby można było wypróbować przykład integracji czatu analityki konwersacyjnej z osadzonym panelem Lookera.

Klonowanie repozytorium

1. Sklonuj repozytorium GitHub w środowisku lokalnym. Oto przykładowe polecenie:

git clone "https://github.com/looker-open-source/LookerEmbedReference.git"

2. Przejdź do sklonowanego katalogu LookerEmbedReference:

cd LookerEmbedReference

Konfigurowanie i uruchamianie lokalnego serwera frontendu

3. Zainstaluj zależności w katalogu Frontend.

cd Frontend
yarn install

4. Skonfiguruj plik .env w katalogu głównym Frontend z danymi logowania. YOUR_LOOKER_INSTANCE_URI powinien być identyfikatorem URI instancji Lookera bez ukośnika na końcu. Zawartość pliku powinna wyglądać tak:

PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI

Aby utworzyć plik, możesz użyć tego przykładowego polecenia:

cat > .env <<'EOF'
PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
EOF

5. Uruchom serwer deweloperski frontendu:

yarn run dev

Konfigurowanie i uruchamianie serwera backendu lokalnie

6. Otwórz nową powłokę, terminal, konsolę lub kartę. Przejdź do katalogu Backend-Node i zainstaluj zależności. Nie zamykaj poprzedniej powłoki/terminala z działającym serwerem frontendu.

cd ../Backend-Node
yarn install

7. Skonfiguruj plik .env w katalogu głównym Backend-Node z danymi logowania:

• YOUR_LOOKER_CLIENT_ID to Twój identyfikator klienta Lookera.
• YOUR_LOOKER_CLIENT_SECRET to tajny klucz klienta Lookera.
• YOUR_LOOKER_EMBED_SECRET to Twój klucz obiektu tajnego do umieszczania.
• YOUR_PROJECT_ID to identyfikator Twojego projektu Cloud;
• YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH to identyfikator URI instancji Lookera z ukośnikiem na końcu.
• YOUR_LOOKER_INSTANCE_URI to identyfikator URI instancji Lookera bez ukośnika na końcu.

Zawartość pliku powinna wyglądać tak:

PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID

Aby utworzyć plik, możesz użyć tego przykładowego polecenia. Odpowiednio zastąp wszystkie dane logowania:

cat > .env <<'EOF'
PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID
EOF

8. Uruchom serwer deweloperski backendu:

yarn run dev

Serwer deweloperski frontendu jest już uruchomiony i obsługuje JavaScript dla aplikacji internetowej. Działa też serwer deweloperski backendu, który obsługuje żądania dotyczące adresu URL osadzania logowania jednokrotnego i przekazuje żądania do punktów końcowych analityki konwersacyjnej.

4. Wypróbuj przykład

Teraz wypróbuj aplikację internetową działającą lokalnie w Twoim środowisku.

Rozpoczynanie rozmowy

1. Otwórz adres https://localhost:3001 w wybranej przeglądarce.
2. W głównym menu nawigacyjnym po lewej stronie otwórz stronę Osadzony panel z czatem.
3. Gdy po prawej stronie pojawi się komponent czatu, wpisz „Cześć, kim jesteś?”.
4. Zanotuj odpowiedź.

Aplikacja automatycznie utworzyła obiekt rozmowy w analityce konwersacyjnej, aby śledzić historię czatu, i wczytała interfejs czatu. Gdy zadasz pytanie interfejsowi czatu, frontend wyśle wiadomość użytkownika do lokalnego serwera backendu Node. Następnie przekierował żądanie do punktu końcowego czatu analityki konwersacyjnej i odpowiedź z niego.

Filtrowanie umieszczonego panelu

Teraz zapoznaj się z osadzonym panelem i zacznij z niego korzystać.

5. Przewiń umieszczony panel. Obejmuje on dane spisu powszechnego w wielu wymiarach i wskaźnikach.
6. W lewym górnym rogu panelu możesz filtrować dane według stanu i hrabstwa. Ustaw filtr w filtrze panelu na Texas. Następnie kliknij nowo podświetlony na niebiesko przycisk z okrągłą strzałką, aby ponownie uruchomić panel.
7. Zwróć uwagę, że dane wszystkich wizualizacji są filtrowane według stanu Texas.

Zadawanie pytań z kontekstem panelu

Po przefiltrowaniu panelu kontynuujmy analizę danych w nim zawartych.

8. Na czacie wpisz „Podaj 5 powiatów z najniższym czynszem”.
9. Zwróć uwagę, że prompt do Analyticsa konwersacyjnego zawiera teraz dodatkowe słowa: „Filtruj według wymiaru „state.state_name” o wartości „Texas””.
10. Zwróć uwagę, że zapytanie i dane w odpowiedzi są filtrowane według stanu Texas.
11. Po zwróceniu wyników danych ponownie uruchomiliśmy wbudowany panel z filtrem County ustawionym na 5 okręgów zdefiniowanych w danych wyników.

Możesz teraz kontynuować analizę danych z cenzusu, ponieważ 5 hrabstw zostało już dla Ciebie odfiltrowanych.

Gratulacje! Skonfigurowano i wypróbowano prosty przykład osadzonego panelu zintegrowanego z czatem analityki konwersacyjnej.

5. Tworzenie komponentu czatu

Aby zrozumieć, co się dzieje w tle, najpierw przyjrzyjmy się komponentowi Chat. Zakładamy, że wiesz, jak umieścić panel Lookera za pomocą pakietu Looker Embed SDK.

Korzystanie z biblioteki komponentów Lookera

1. Otwórz plik komponentu Chat w lokalizacji Frontend/src/components/EmbedChat/components/chat.js w ulubionym środowisku IDE lub w terminalu.
2. Komponent Chat jest zbudowany ze standardowych komponentów interfejsu Lookera w React z pakietu Biblioteka komponentów Lookera.

Biblioteka komponentów Lookera umożliwia płynną integrację treści Lookera z aplikacją dzięki gotowym komponentom React, które są zgodne ze stylami i komponentami w osadzonym panelu Lookera.

Wysyłanie wiadomości do użytkownika

Interfejs czatu musi wysyłać prompt użytkownika do analityki konwersacyjnej.

3. U dołu pliku komponentu Chat znajduje się komponent Chat, który zawiera komponent podrzędny ChatInput. Ten komponent podrzędny udostępnia pole do wprowadzania danych dla promptu użytkownika.
4. Po przesłaniu metoda showAndSendUserPrompt wysyła prompt użytkownika do analityki konwersacyjnej (za pośrednictwem backendu Node).

Przesyłanie strumieniowe i wyświetlanie komunikatów systemowych

Gdy użytkownik wyśle wiadomość do analityki konwersacyjnej, musimy wyświetlić odpowiedź.

5. W dolnej części pliku komponentu Chat znajduje się komponent Chat, który zawiera subkomponent MessageList z logiką wyświetlania wiadomości z analityki konwersacyjnej na podstawie typu wiadomości.
6. Metoda streamAndParseResponse obsługuje odpowiedź, stale próbując przeanalizować prawidłowe wiadomości systemowe z odpowiedzi JSON strumieniowania. Gdy tylko uda się prawidłowo przeanalizować prawidłowy komunikat systemowy, zostanie on wyświetlony w MessageList.

Aby zapewnić użytkownikom większą wygodę, zalecamy wyświetlanie komunikatów systemowych z analityki konwersacyjnej od razu po ich otrzymaniu.

Odpowiedź Analityki konwersacyjnej na prompt użytkownika składa się z wielu wiadomości systemowych, które obejmują źródła danych, z których pochodzą zapytania, zapytania, wyniki, wizualizacje i inne informacje. Oczekiwanie na wszystkie wiadomości systemowe może sprawić, że użytkownik uzna, że występują problemy z wydajnością lub aplikacją.

Wiesz już, jak komponent Chat, utworzony za pomocą biblioteki Looker Components, wysyła wiadomość do użytkownika i przesyła z powrotem odpowiedź.

6. Wysyłanie filtrów panelu do analityki konwersacyjnej

Teraz dowiedzmy się, jak uwzględnić filtry panelu w prompcie użytkownika, aby analityka konwersacyjna mogła filtrować zapytanie w kontekście panelu (jego filtrów).

Nasłuchiwanie zdarzenia zmiany filtra w panelu

1. Otwórz plik komponentu EmbedChat w lokalizacji Frontend/src/components/EmbedChat/EmbedChat.js,, który reprezentuje stronę aplikacji zawierającą osadzony panel zintegrowany z komponentem Chat.
2. Komponent EmbedChat nasłuchuje zdarzenia "dashboard:filters:changed" z osadzonego panelu za pomocą metody .on(...) pakietu Embed SDK. Następnie komponent zapisuje bieżące filtry w stanie filtra.

Wysyłanie stanu filtra do analityki konwersacyjnej

3. Komponent EmbedChat przekazuje filtry do komponentu Chat, który przekształca każdy filtr w ciąg znaków, np. "Filter on dimension '...' being ...", w metodzie showAndSendUserPrompt, aby dodać go na końcu promptu użytkownika.

Nazwa lub klucz filtra panelu nie musi być taka sama jak nazwa rzeczywistego wymiaru. Klucz filtra musisz zmapować na nazwę rzeczywistego wymiaru, aby analityka konwersacyjna wiedziała, według których wymiarów ma filtrować dane.

W tym przypadku np. w komponencie Chat jego obiekt FIELD_FILTER_MAP mapuje nazwę wymiaru "state.state_name" na klucz filtra "State 📍". Następnie metoda showAndSendUserPrompt używa mapy do określenia nazwy wymiaru, według którego ma filtrować dane.

7. Sterowanie filtrami panelu z poziomu czatu

Na koniec przyjrzyjmy się, jak włączyć komponent Chat, aby sterować filtrami osadzonego panelu.

Określanie filtrów do ustawienia

1. Metoda streamAndParseResponse komponentu Chat zawsze sprawdza, czy nie ma wiadomości systemowej z wynikami danych z analityki konwersacyjnej.
2. Gdy metoda streamAndParseResponse analizuje komunikat systemowy z wynikami danych, sprawdza, czy którykolwiek z wymiarów w danych odpowiada wymiarom w filtrach.
3. W takim przypadku metoda streamAndParseResponse przekształca kolumny danych w filtry panelu. Tym razem metoda ponownie korzysta z FIELD_FILTER_MAP, ale w odwrotny sposób, przekształcając nazwę wymiaru w klucz filtra. Wartości filtra to wartości w kolumnie danych.

Wysyłanie zdarzenia zmiany filtra do osadzonego panelu

4. W przypadku wybranych filtrów panelu wywołanie metody streamAndParseResponse powoduje wywołanie metody setFilters komponentu Chat z odpowiednimi filtrami.
5. Wywołuje to metodę setDashboardFilters komponentu EmbedChat, która wysyła 2 zdarzenia: "dashboard:filters:update" z filtrami i "dashboard:run" do osadzonego panelu w szybkiej kolejności za pomocą metody send pakietu Embed SDK.
6. Zdarzenie "dashboard:filters:update" zmienia filtry w osadzonym panelu, a zdarzenie "dashboard:run" ponownie uruchamia zapytania panelu z nowymi filtrami.

Musisz wysłać "dashboard:run" po zdarzeniu "dashboard:filters:update". Zdarzenie "dashboard:filters:update" nie powoduje automatycznego ponownego uruchomienia zapytań w panelu.

8. Podsumowanie i najważniejsze informacje

Masz już własny przykład działania osadzonego panelu Looker zintegrowanego z czatem analityki konwersacyjnej. Wiesz już, jak włączyć eksplorowanie danych za pomocą języka naturalnego na osadzonym panelu Looker i w analityce konwersacyjnej.

• Masz już komponent czatu utworzony za pomocą biblioteki komponentów Lookera.
• Przekazujesz kontekst osadzonego panelu Lookera do analityki konwersacyjnej, aby ułatwić eksplorowanie danych.
• Włączono Analitykę konwersacyjną, aby kontrolować filtry osadzonego panelu informacyjnego i uzyskiwać więcej kontekstu podczas eksplorowania danych.

Co dalej

• Dowiedz się więcej o możliwościach analityki konwersacyjnej.
• Zaktualizuj przykładową aplikację Looker Embed Reference, aby działała z Twoimi osadzonymi panelami Lookera.
• Wypróbuj inne przypadki użycia osadzania dostępne w lokalnie uruchomionej aplikacji przykładowej Looker Embed Reference.