会話型分析で Looker を埋め込む

1. 始める前に

この Codelab では、埋め込み Looker ダッシュボードと会話型分析を利用したチャットを統合して、自然言語による統合データエクスペリエンスを作成する方法について説明します。この機能を最大限に活用するには、Looker の埋め込み、会話型分析、JavaScript、React について理解しておく必要があります。

学習内容

この Codelab を修了すると、次のことを学習できます。

Looker Embed リファレンスアプリケーションをローカルで設定する方法
Looker コンポーネントライブラリを使用してチャット React コンポーネントを構築する方法
埋め込みダッシュボードのフィルタをコンテキストとして会話型分析に送信する方法
会話型分析機能付きのチャットを有効にして、埋め込みダッシュボードのフィルタを制御する方法

必要なもの

この Codelab を完了するには、以下が必要です。

ASC Demographic Data Looker Block がインストールされ、SSO 埋め込みが有効になっている Looker インスタンス
Looker インスタンスへの API とデベロッパーのアクセス
Node v18、yarn、Git、gcloud がインストールされたローカル環境
ユーザーアカウントに次の IAM ロールが設定されているクラウドプロジェクト:
roles/bigquery.dataViewer BigQuery データ閲覧者
roles/bigquery.user BigQuery ユーザー
roles/looker.instanceUser Looker インスタンスユーザー

2. 会話型分析を設定する

埋め込みダッシュボードのチャットで自然言語の質問に回答するために使用する会話型分析データエージェントを設定しましょう。

gcloud で認証する

ローカル環境でユーザーアカウントを使用して認証します。

gcloud auth login

gcloud でアプリケーションのデフォルト認証情報（ADC）と課金プロジェクトを設定します。

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

会話型分析 API を有効にする

Cloud プロジェクトの API を有効にします。YOUR_PROJECT_ID は、Google Cloud プロジェクトの ID に置き換えてください。

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

データエージェントを作成する

Google Colab を開きます。
Google Colab 内で、Looker Embed Reference リポジトリからこのノートブックを読み込みます。
ノートブックのすべてのステップを実行します。Cloud プロジェクト ID と、末尾にスラッシュが付いた Looker インスタンスの URI（例: "https://my.looker.app/"）が必要です。ノートブックの最後に成功の結果が表示されます。

これで、会話型分析データエージェントが利用可能になり、チャットメッセージを受け取り、埋め込み Looker ダッシュボードで Looker Explore をクエリして、結果とビジュアリゼーションを返す準備が整いました。

3. Looker Embed Reference を設定する

ローカル環境に Looker Embed Reference アプリケーションを設定して、会話型分析チャットと埋め込み Looker ダッシュボードを統合する例を試してみましょう。

リポジトリのクローンを作成します。

GitHub リポジトリのクローンをローカル環境に作成します。次のコマンド例をご覧ください。

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

クローン作成した LookerEmbedReference ディレクトリに移動します。

cd LookerEmbedReference

ローカルフロントエンドサーバーを設定して実行する

Frontend ディレクトリに依存関係をインストールする

cd Frontend
yarn install

認証情報を使用して、Frontend ディレクトリのルートに .env ファイルを設定します。YOUR_LOOKER_INSTANCE_URI は、末尾にスラッシュのない Looker インスタンスの URI にする必要があります。ファイルの内容は次のとおりです。

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

次のコマンド例を使用してファイルを作成できます。

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

フロントエンド開発サーバーを実行します。

yarn run dev

バックエンドサーバーをローカルで設定して実行する

新しいシェル、ターミナル、コンソール、タブを開きます。Backend-Node ディレクトリに移動し、依存関係をインストールします。フロントエンドサーバーが実行されている前のシェル/ターミナルは開いたままにしておきます。

cd ../Backend-Node
yarn install

認証情報を使用して Backend-Node ディレクトリのルートに .env ファイルを設定します。

YOUR_LOOKER_CLIENT_ID は Looker クライアント ID です。
YOUR_LOOKER_CLIENT_SECRET は Looker クライアントシークレットです。
YOUR_LOOKER_EMBED_SECRET は埋め込みシークレットです。
YOUR_PROJECT_ID は Cloud プロジェクト ID です。
YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH は、末尾にスラッシュが付いた Looker インスタンスの URI です。
YOUR_LOOKER_INSTANCE_URI は、末尾のスラッシュがない Looker インスタンス URI です。

ファイルの内容は次のとおりです。

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

次のコマンド例を使用して、ファイルを作成できます。必要に応じて、すべての認証情報を置き換えます。

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

バックエンド開発サーバーを実行します。

yarn run dev

これで、フロントエンド開発サーバーが実行され、ウェブアプリケーションの JavaScript が提供されるようになりました。また、バックエンド開発サーバーも実行して、SSO 埋め込み URL リクエストを処理し、会話型分析エンドポイントにリクエストをプロキシします。

4. 例を試す

それでは、環境でローカルに実行されているウェブアプリケーションを試してみましょう。

会話を開始する

任意のブラウザで https://localhost:3001 を開きます。
左側のメインナビゲーションで [チャット付きの埋め込みダッシュボード] ページに移動します。
右側のチャットコンポーネントが読み込まれたら、「Hello, who are you?」と入力します。
レスポンスをメモします。

アプリケーションは、チャットの履歴を追跡するために会話型分析の会話オブジェクトを自動的に作成し、チャットインターフェースを読み込みました。チャットインターフェースに質問すると、フロントエンドはユーザーメッセージをローカルの Node バックエンドサーバーに送信しました。その後、リクエストとレスポンスを Conversational Analytics の chat エンドポイントにプロキシしました。

組み込みダッシュボードをフィルタする

埋め込みダッシュボードをよく理解し、操作してみましょう。

埋め込みダッシュボードをスクロールします。複数のディメンションと指標にわたる国勢調査データが対象となります。
ダッシュボードの左上にある [State] と [County] でダッシュボードをフィルタできます。ダッシュボードフィルタのフィルタを [Texas] に設定します。次に、新しく青色でハイライト表示された円形の矢印ボタンを選択して、ダッシュボードを再実行します。
すべてのビジュアリゼーションデータが州 Texas でフィルタされていることに注目してください。

ダッシュボードのコンテキストを指定して質問する

ダッシュボードをフィルタしたので、ダッシュボードのデータの調査を続けます。

チャットで「家賃が最も安い上位 5 つの郡を教えて」と送信します。
会話型分析へのプロンプトに、「Filter on dimension ‘state.state_name' being Texas.」という追加の単語が含まれるようになりました。
レスポンスのクエリとデータが州 Texas でフィルタされていることに注目してください。
また、データ結果が返された後、埋め込みダッシュボードが再実行され、結果のデータで定義された 5 つの郡に [郡] フィルタが設定されています。

これで、5 つの郡がフィルタされた状態で、国勢調査データの調査を続行できます。

おめでとうございます！会話型分析チャットと統合された埋め込みダッシュボードの簡単な例を設定して試しました。

5. チャットコンポーネントをビルドする

まず Chat コンポーネントを調べて、内部で何が起こっているのかを理解しましょう。Looker Embed SDK を使用して Looker ダッシュボードを埋め込む方法を理解していることを前提としています。

Looker コンポーネントライブラリを使用する

お好みの IDE またはターミナルで、Frontend/src/components/EmbedChat/components/chat.js の Chat コンポーネントファイルを開きます。
Chat コンポーネントは、Looker コンポーネントライブラリパッケージの標準の Looker UI React コンポーネントで構築されています。

ユーザーメッセージを送信する

チャットインターフェースは、ユーザーのプロンプトを会話型分析に送信する必要があります。

Chat コンポーネントファイルの下部付近にある Chat コンポーネントには、ユーザーのプロンプトの入力フィールドを提供する ChatInput サブコンポーネントが含まれています。
送信時に、showAndSendUserPrompt メソッドはユーザーのプロンプトを会話型分析に送信します（Node バックエンドを介してプロキシされます）。

システムメッセージをストリーミングして表示する

ユーザーが会話型分析にメッセージを送信したら、その応答を表示する必要があります。

Chat コンポーネントファイルの下部付近にある Chat コンポーネントには、メッセージのタイプに基づいて会話型分析のメッセージを表示するロジックを含む MessageList サブコンポーネントが含まれています。
streamAndParseResponse メソッドは、ストリーミング JSON レスポンスから有効なシステムメッセージを常に解析しようとして、レスポンスを処理します。有効なシステムメッセージが正常に解析されるたびに、MessageList に表示されます。

これで、Looker コンポーネントライブラリで構築された Chat コンポーネントがユーザーメッセージを送信し、レスポンスをストリーミングで返す方法について説明しました。

6. ダッシュボードフィルタを会話型分析に送信する

次に、会話型分析でダッシュボードのコンテキスト（フィルタ）を使用してクエリをフィルタできるように、ダッシュボードフィルタをユーザーのプロンプトに含める方法について説明します。

ダッシュボードのフィルタ変更イベントをリッスンする

Frontend/src/components/EmbedChat/EmbedChat.js, の EmbedChat コンポーネントファイルを開きます。これは、以前に説明した Chat コンポーネントと統合された組み込みダッシュボードを含むアプリケーションのページを表します。
EmbedChat コンポーネントは、Embed SDK の .on(...) メソッドを使用して、埋め込みダッシュボードからの "dashboard:filters:changed" イベントをリッスンします。コンポーネントは、現在のフィルタをフィルタの状態に保存します。

フィルタの状態を会話型分析に送信する

EmbedChat コンポーネントはフィルタを Chat コンポーネントに渡し、Chat コンポーネントは showAndSendUserPrompt メソッドで各フィルタを "Filter on dimension '...' being ..." のような文字列に変換して、ユーザーのプロンプトに接尾辞として追加します。

7. チャットからダッシュボードフィルタを制御する

最後に、Chat コンポーネントで埋め込みダッシュボードのフィルタを制御する方法について説明します。

設定するフィルタを決定する

Chat コンポーネントの streamAndParseResponse メソッドは、会話型分析のデータ結果を含むシステムメッセージを常にチェックしています。
streamAndParseResponse メソッドがデータ結果を含むシステムメッセージを解析するたびに、データ内のディメンションがフィルタ内のディメンションに対応しているかどうかが確認されます。
その場合、streamAndParseResponse メソッドはデータ列をダッシュボードフィルタに変換します。今回は、メソッドが FIELD_FILTER_MAP を逆方向に使用し、ディメンション名からフィルタのキーに変換します。フィルタの値は、データ列の値です。

フィルタ変更イベントを埋め込みダッシュボードに送信する

必要なダッシュボードフィルタを使用して、streamAndParseResponse メソッドは必要なフィルタで Chat コンポーネントの setFilters メソッドを呼び出します。
これにより、EmbedChat コンポーネントの setDashboardFilters メソッドが呼び出されます。このメソッドは、Embed SDK の send メソッドを使用して、フィルタを含む "dashboard:filters:update" と "dashboard:run" の 2 つのイベントを埋め込みダッシュボードに連続して送信します。
"dashboard:filters:update" イベントは埋め込みダッシュボードのフィルタを変更し、"dashboard:run" イベントは新しいフィルタを使用してダッシュボードのクエリを再実行します。

8. 結論と重要なポイント

会話型分析チャットと統合された Looker ダッシュボードの独自の動作例を設定しました。埋め込み Looker ダッシュボードと会話型分析を使用して、自然言語によるデータ探索を有効にする方法について説明しました。

Looker コンポーネントライブラリを使用してチャットコンポーネントを構築しました。
組み込み Looker ダッシュボードのコンテキストを会話型分析に渡して、データ探索を容易にしました。
会話型分析を有効にして、データを探索する際のコンテキストを強化するために、埋め込みダッシュボードのフィルタを制御します。

次のステップ

会話型分析の機能について詳細を確認する。
独自の埋め込み Looker ダッシュボードで動作するように、Looker Embed Reference のサンプルアプリを更新します。
ローカルで実行されている Looker Embed Reference サンプルアプリで、他の埋め込みユースケースを試してみてください。