Looker ダッシュボード要約拡張機能の Codelab

残り 15 分

この Codelab について

最終更新: 6月 8, 2024

作成者: Jeremy Chang

1. 始める前に

この Codelab（1）では、Looker Dashboard Summarization Extension をローカルに設定し、ローカルで試して開発します。次に（2）拡張機能を本番環境にデプロイして、Looker インスタンス内の他の Looker ユーザーが使用できるようにします。最後に、（3）追加の手順に沿って拡張機能の機能を微調整、強化できます。オプションでないセクションはすべて順番に入力する必要があります。

Looker ダッシュボード要約拡張機能の概要

機能的には、Looker Dashboard Summarization Extension は Looker ダッシュボードのデータを Vertex AI の Gemini モデルに送信します。Gemini モデルは、ダッシュボードのデータの概要と次のステップの指示を返します。この拡張機能は、サマリーと次のステップがダッシュボードにタイルとして表示され、ダッシュボードに統合されます。また、概要と次のステップを Slack または Google Chat にエクスポートすることもできます。この拡張機能は、React フロントエンドアプリケーションと WebSocket バックエンドサービスを組み合わせて、Vertex AI の Gemini モデルとの間でデータを送受信します。

前提条件

ノード開発、Docker、Terraform に関する基本的な知識
Looker LookML プロジェクトの設定に精通していること

学習内容

拡張機能をローカルで設定して開発する方法
拡張機能を本番環境にデプロイして、Looker インスタンス内の他の Looker ユーザーが使用できるようにする方法
拡張機能のパフォーマンスを微調整して機能を拡張する方法（省略可）。
本番環境でデプロイされた拡張機能を管理する方法

必要なもの

Looker インスタンス（Looker オリジナルライセンス、有効な Looker Core トライアル、または有効な Looker Core ライセンスのいずれか）。
Looker インスタンスに対する develop 権限と deploy 権限。
拡張機能で試すダッシュボードを編集する権限。
Looker インスタンスの Looker API キー。
課金が有効になっている Google Cloud プロジェクト。
プロジェクトで有効になっている Cloud Run API、Vertex AI API、Artifact Registry API。
gcloud CLI がインストールされているローカル環境へのアクセス。Codelab のステップでは、Linux スタイルの環境を前提としています。

2. ローカル開発用のバックエンドの設定

このセクションでは、WebSocket のバックエンドサービスをセットアップして試し、ローカルで開発できるようにします。このサービスから Vertex AI にアクセスできるようになります。

Node バージョン 18 以降をローカル環境にインストールします。こちらの手順に沿って Node をインストールします。
拡張機能のリポジトリのクローンをローカルのホームディレクトリに作成し、リポジトリのルートディレクトリに移動します。この Codelab の目的上、すべてのコードサンプルでは、クローンを作成したリポジトリがローカルホームディレクトリにあることを前提としています。

cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git

クローンリポジトリのルートディレクトリに移動し、.env.example ファイルの名前を .env に変更して、この Codelab の後のセクションで環境変数を設定できるようにします。

cd ~/dashboard-summarization
mv .env.example .env

クローン作成したリポジトリのウェブソケットバックエンドの src ディレクトリに移動します。このディレクトリには、サーバーのソースコードが含まれています。

cd ~/dashboard-summarization/websocket-service/src

NPM を使用してサービスの依存関係をインストールします。

npm install

ファイル名を looker-example.ini から looker.ini に変更します。

mv looker-example.ini looker.ini

looker.ini ファイルの更新内容:
client_id と client_secret は、Looker API キーから取得したものに置き換えます。
base_url は、Looker インスタンスの URL（https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999 の形式）に置き換えます。
かっこで囲まれたテキスト（セクションヘッダー）と、Looker インスタンスの URL のホスト。

たとえば、クライアント ID が ABC123、クライアントシークレットが XYZ789、Looker インスタンスの URL が https://mycompany.cloud.looker.com の場合、looker.ini ファイルは次のようになります。

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true

Google Cloud プロジェクト ID を確認し、PROJECT 環境変数に設定します。YOUR_PROJECT_ID は、実際のプロジェクト ID に置き換えます。

export PROJECT="YOUR_PROJECT_ID"

Vertex AI は、こちらに記載されている複数のリージョンで Gemini モデルを提供しています。ローカルバックエンドが Vertex AI の Gemini モデルとデータを送受信するリージョンを決定します。REGION 環境変数でリージョンを設定します。YOUR_VERTEX_REGION は、使用するリージョン（us-central1 など）に置き換えます。

export REGION="YOUR_VERTEX_REGION"

ローカルサービスを起動します。

npm start

ローカルの WebSocket バックエンドサービスは http://localhost:5000 で実行されます。

これで、ローカル環境での WebSocket バックエンドサービスの設定が完了しました。

このサービスは、フロントエンド拡張機能と Vertex AI の Gemini モデル間のインターフェースとして機能します。このサービスは、Looker からクエリされたデータとともにフロントエンド拡張機能からダッシュボードと LookML のデータを取得し、Vertex AI の Gemini モデルにプロンプトを送信します。その後、Gemini のレスポンスがフロントエンド拡張機能にストリーミングされて、ダッシュボードに表示されます。

バックエンドサービスのソースコードを変更することもできます。まずサービスプロセスを停止し、コードを変更してから、npm start を再度実行する必要があります。

3. ローカル開発用のフロントエンドを設定する

このセクションでは、フロントエンド拡張機能を設定して、ローカルで試して開発します。

前の手順と同じローカル環境で、クローンを作成したリポジトリのルートディレクトリに移動し、フロントエンドサーバーの依存関係をフロントエンドにインストールします。

cd ~/dashboard-summarization
npm install

ローカルフロントエンド開発用サーバーを起動する

npm run develop

これで、ローカルのフロントエンドサーバーが拡張機能の JavaScript を http://localhost:8080/bundle.js で配信できるようになりました。
ウェブブラウザを開き、Looker インスタンスにログインします。
こちらの手順に沿って、空の LookML プロジェクトを設定します。プロジェクトに dashboard-summarization という名前を付けます。現在のブラウザタブの Looker IDE に、空の LookML プロジェクトが自動的に開きます。
LookML プロジェクトのルートにプロジェクトマニフェストファイルを作成します。ファイル名は manifest.lkml になります。手順がわからない場合は、こちらの手順で LookML プロジェクトにファイルを追加します。
新しい manifest.lkml ファイルの内容を、閉じたリポジトリのルートディレクトリにある manifest.lkml の内容に置き換えます。[変更を保存] を選択します。] ボタンをクリックして、変更内容をファイルに保存します。
別のブラウザタブで、Looker インスタンスのデータベース接続のリストに移動します。設定方法がわからない場合は、こちらの手順に従ってください。
1 つの Looker データベース接続の名前を選択します。どの接続を選んでも問題ありません。データベース接続を表示する権限がない場合は、Looker 管理者に連絡して Looker データベース接続の名前を確認してください。
Looker IDE で LookML プロジェクトを開いたブラウザタブに戻ります。LookML プロジェクトでモデルファイルを作成し、そのファイルに「dashboard-summarization」という名前を付けます。
dashboard-summarization.model.lkml ファイルの内容を次のコードサンプルに置き換えます。二重引用符で囲まれた文字列は、手順 9 で選択したデータベース接続名に置き換えてください。ファイルへの変更を保存します。

connection: "<YOUR_CONNECTION_NAME>"

プロジェクトを保存するリポジトリを設定します。[Configure Git] を選択します。] ボタンを押します。[代わりにベアリポジトリを設定する] を選択します。[リポジトリを作成] を選択します。
これで、LookML プロジェクトファイルを保存する基本的な最小限のリポジトリが完成しました。Looker IDE で [プロジェクトに戻る] を選択してプロジェクトに戻る手動で戻ることもできます
[Validate LookML] を選択します。ボタンをタップします。ボタンが [変更を commit して push ] に変わります。
[変更を commit して push] を選択します。] ボタンを離します。必要なメッセージを追加して [commit] を選択します。
[Deploy to Production] を選択します。[Looker IDE]の右上にありますこれで、Looker インスタンスに拡張機能が追加されました。
拡張機能を追加する Looker ダッシュボードに移動します。
手順に沿って、ダッシュボードに拡張機能タイルを追加します。新しい拡張機能をタイルとしてダッシュボードに追加します。
先ほど設定したローカル WebSocket バックエンドサービスが実行されていることを確認します。

これで、ダッシュボードで Looker Dashboard Summarization Extension をお試しいただけます。拡張機能はダッシュボードのメタデータをローカルの WebSocket バックエンドサービスに送信し、バックエンドサービスからの Gemini 出力をダッシュボード拡張機能タイル内に表示します。

ローカルフロントエンドサーバーの稼働中に拡張機能の JavaScript ソースコードに変更を加えると、サーバーが自動的に変更をビルドして提供します。変更を確認するには、拡張機能またはダッシュボードページを再読み込みする必要があります。

4. バックエンドを本番環境にデプロイする

このセクションでは、Looker インスタンスの任意のダッシュボードで、ダッシュボード要約拡張機能のあらゆるインスタンスを提供するように WebSocket バックエンドサービスを設定します。これにより、他の Looker ユーザーは、独自のバックエンドサービスを設定しなくても、各自のダッシュボードで拡張機能を試すことができます。以下の手順は、同じローカル環境でローカル開発用のバックエンドがすでに正常にデプロイされていることを前提としています。

こちらの手順に沿って、プロジェクト ID を使用してローカル環境でアプリケーションのデフォルト認証情報を設定します。
バックエンドサービスの Docker イメージ用の Artifact Registry リポジトリを作成します。YOUR_REGION は、リポジトリを配置するリージョンに置き換えます。

gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \

クローンを作成したリポジトリのウェブソケットバックエンドの src ディレクトリに移動します。

cd ~/dashboard-summarization/websocket-service/src

cloudbuild.yaml ファイルを編集し、YOUR_REGION と YOUR_PROJECT_ID のすべてのインスタンスをリージョンとプロジェクト ID に置き換えます。ファイルへの変更を保存します。
Cloud Build を使用してビルドを送信します。これにより、バックエンドサービスの Docker イメージがビルドされ、先ほど作成した Artifact Registry リポジトリに push されます。YOUR_REGION は、Cloud Build サービスを使用するリージョンに置き換えます。

gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml

先ほどビルドした Docker イメージの URL は YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest です。YOUR_PROJECT_ID は、実際のプロジェクト ID に置き換えます。YOUR_REGION は、ステップ 2 で Artifact Registry リポジトリの作成に使用したリージョンに置き換えます。
クローンを作成したリポジトリの websocket-service/terraform ディレクトリに移動します。

cd ~/dashboard-summarization/websocket-service/terraform

Google Cloud Run のどのロケーションで WebSocket バックエンドサービスを実行するかを決定します。こちらのロケーションから選択します。
variables.tf ファイルを編集し、YOUR_PROJECT_ID と YOUR_DOCKER_IMAGE_URL を適切な値に置き換えます。ステップ 6 で Docker イメージの URL を確認します。YOUR_REGION は、前のステップ 8 で選択したリージョンに置き換えます。変更をファイルに保存します。
Terraform を使用して、バックエンドサービスが使用するリソースをデプロイする。

terraform init
terraform plan
terraform apply

次のセクションのために、デプロイした Cloud Run URL エンドポイントを保存します。

おめでとうございます。WebSocket バックエンドサービスをデプロイし、Google Cloud Run で実行できるようになりました。これで、Looker Dashboard Summarization 拡張機能のすべてのインスタンスがバックエンドサービスと通信できるようになりました。Cloud Run で WebSocket バックエンドサービスのインスタンスを 1 つ以上常に実行しておくことをおすすめします。バックエンドサービスの永続性は、WebSocket バックエンドサービスと拡張機能のフロントエンド間のデータストリーミングの整合性を維持し、拡張機能を使用する各ユーザーのセッションを維持するのに役立ちます。

5. フロントエンドを本番環境にデプロイする

この最後のセクションでは、拡張機能のフロントエンドをデプロイする最後のステップを行い、Looker インスタンス内のすべての Looker ユーザーが使用できるようにします。

クローンを作成したリポジトリのルートディレクトリに移動します。

cd ~/dashboard-summarization

.env ファイル。YOUR_CLOUD_RUN_URL は、前のセクションの Cloud Run URL エンドポイントに置き換えます。ファイルの変更を保存します。これにより、本番環境拡張機能のフロントエンドが、Cloud Run で実行されている WebSocket バックエンドサービスを参照するようになります。
拡張機能の JavaScript を作成します。dist ディレクトリが、bundle.js ファイルとその中の他のファイルを含む自動的に生成されます。

npm run build

ウェブブラウザを開き、Looker インスタンスにログインします。左側の左側のナビゲーションを開いて [Development Mode] をオンにします。切り替えます。
左側のナビゲーションを開いて [Develop] を選択し、下にスクロールして [dashboard-summarization]、拡張機能の LookML プロジェクトを選択します。これで、LookML プロジェクトの Looker IDE が開きます。
[ファイルブラウザ] で、先ほど生成した dist ディレクトリ内のすべてのファイルを、プロジェクトのルートディレクトリにドラッグ&ドロップします。さらにサポートが必要な場合は、こちらの手順をご覧ください。
Looker IDE 内で manifest.lkml ファイルを開きます。ファイル内の

url: "http://localhost:8080/bundle.js"

と

file: "bundle.js"

YOUR_CLOUD_RUN_URL は、最後のセクションの最後に取得した Cloud Run URL エンドポイントに置き換えます。ファイルに変更を保存します。

[Validate LookML] を選択します。ボタンをタップします。ボタンが [変更を commit して push ] に変わります。
[変更を commit して push] を選択します。] ボタンを離します。必要なメッセージを追加して [commit] を選択します。
[Deploy to Production] を選択します。[Looker IDE]の右上にあります

おめでとうございます。これで、Looker インスタンス内のすべての Looker ユーザーが、Looker Dashboard Summarization Extension をダッシュボードに追加できるようになりました。他の Looker ユーザーが拡張機能を使用すると、拡張機能のすべてのインスタンスが、Google Cloud Run で実行されているデプロイ済みの WebSocket バックエンドサービスを呼び出します。

ソースコードを変更する場合は、次のことを行う必要があります。

拡張機能の JavaScript を再度ビルドする
LookML プロジェクトに追加した生成されたファイルを、dist ディレクトリから新しく生成されたファイルに置き換えます。
LookML プロジェクトの変更内容を検証、commit、本番環境にデプロイする

Looker ダッシュボードの要約拡張機能をお試しくださいLooker コミュニティのニーズにより適切に対処できるよう、拡張機能への貢献をお願いいたします。必要に応じて、リポジトリで pull リクエストを作成してください。

以下のオプションのセクションを確認して、Slack/Google Chat へのエクスポートの有効化、Gemini のサマリーと次のステップの微調整、Gemini ロギングの設定などを行ってください。

6. [省略可] エクスポート機能を設定する

ご自身と Looker ユーザーが Looker Dashboard Summarization 拡張機能を試したところで、この拡張機能の分析情報をより多くのオーディエンスと共有しましょう。このセクションに沿って拡張機能を有効にして、概要と次のステップを Google Chat または Slack に送信します。Codelab のこのセクションを続けるには、OAuth のセットアップに精通している必要があります。

Google Chat のエクスポートを有効にする

Google Cloud プロジェクトで Chat API を有効にします。
Google Workspace の OAuth 設定手順のステップ 1 を行います。スコープの場合は、spaces.messages.create を含める必要があります。
Google Workspace の OAuth 設定手順のステップ 2 を行います。[承認済みの JavaScript 生成元] に URI として Looker インスタンスの URL を追加します（例: https://mycompany.cloud.looker.com）。生成されたクライアント ID をメモします。
概要のエクスポート先となる Google Chat スペースの ID を決めます。設定方法がわからない場合は、こちらをご覧ください。
.env ファイル。YOUR_GOOGLE_CLIENT_ID は、クライアント ID に置き換えます。YOUR_GOOGLE_SPACE_ID は、Google Chat スペース ID に置き換えます。ファイルの変更を保存します。これにより、必要な Google Chat スペースに分析情報を送信できるように拡張機能のフロントエンドが構成されます。
拡張機能のフロントエンドをローカルで実行している場合は、拡張機能を再ビルドします。拡張機能のフロントエンドをデプロイしている場合は、拡張機能のフロントエンドを再デプロイします。

Slack へのエクスポートを有効にする

Slack のデベロッパー向け公式ドキュメントのステップ 1 と 2 に沿って、OAuth アプリケーションを設定します。スコープの場合は、chat:write と channels:read を含める必要があります。生成されたクライアント ID とクライアントシークレットをメモします。
サマリーのエクスポート先となる Slack チャンネルの ID を決めます。
.env ファイル。YOUR_SLACK_CLIENT_ID は、クライアント ID に置き換えます。YOUR_SLACK_CLIENT_SECRET は、クライアントシークレットに置き換えます。YOUR_SLACK_CHANNEL_ID は、チャンネル ID に置き換えます。ファイルの変更を保存します。これにより、必要な Slack チャンネルに分析情報を送信できるように拡張機能のフロントエンドが構成されます。
拡張機能のフロントエンドをローカルで実行している場合は、拡張機能を再ビルドします。拡張機能のフロントエンドをデプロイしている場合は、拡張機能のフロントエンドを再デプロイします。

拡張機能から Slack または Google Chat に要約を直接エクスポートできるようになりました。この拡張機能は、特定のハードコードされた Google Chat スペースまたは Slack チャンネルに対してのみ要約を送信できます。OAuth スコープをさらに追加し、コードを変更して、要約を送信するスペースとチャネルのリストを取得して表示することができます。

7. [省略可] まとめと次のステップを微調整する

この拡張機能は、ダッシュボードのすべてのメタデータとクエリデータを Gemini モデルに提供します。ダッシュボード自体にメタデータとコンテキストをできるだけ追加することで、要約や規範的な手順の精度、詳細、深さを改善できます。拡張機能が属しているダッシュボードごとに、次の手順を試してください。

ダッシュボードの詳細をダッシュボードに追加するには、こちらの手順に沿って操作してください。これは、ダッシュボードの一般的なコンテキストを LLM に伝えるのに役立ちます。
各ダッシュボードのタイルにメモを追加するには、こちらの手順に沿って操作してください。これにより、ダッシュボード上の個々のクエリのコンテキストを LLM に通知できます。小さなコンテキストメモは、生成されるサマリーに組み込まれます。

ダッシュボードに追加できる情報が多いほど、拡張機能の概要や次のステップはより適切なものになります。コードを変更して、Gemini モデルへのプロンプトに追加のダッシュボードメタデータを含めることができます。

8. [省略可] Gemini モデルのロギングを設定する

ユーザーがダッシュボードのサマリーを作成するように拡張機能に指示するたびに、拡張機能はダッシュボード内のクエリごとに Vertex AI を呼び出し、最後の 1 回ですべてのサマリーの書式設定を行います。このセクションに従って拡張機能が行った Vertex AI の呼び出しをログに記録すると、Vertex AI の費用とトラフィックの見積もりとモニタリングが可能になります。この手順は、WebSocket バックエンドサービスをデプロイしている場合にのみ行ってください。

デプロイした WebSocket バックエンドサービスの Cloud Run のロケーションを確認します。
こちらの手順に沿って、ログを BigQuery に転送するログシンクを設定します。シンクの宛先は BigQuery にする必要があります。次のコードサンプルを使用して包含フィルタを設定します。YOUR_CLOUD_RUN_LOCATION は、前のステップの Cloud Run ロケーションに置き換えます。

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. お疲れさまでした

試用できるように、Looker ダッシュボードの要約拡張機能をローカルに設定しました。また、この拡張機能を Google Cloud にデプロイして、他のユーザーも試せるようにしました。Gemini を活用したサマリーと次のステップにダッシュボードから直接アクセスできるようになりました。

10. 次のステップ

拡張機能のコードベースを変更して、組織のニーズに合わせて機能を調整します。
拡張機能のリポジトリに投稿し、お客様と Looker コミュニティのために拡張機能を改善します。
独自の拡張機能を開発して Looker エクスペリエンスを強化
拡張機能をタイルとしてダッシュボードに統合して、ダッシュボードのエクスペリエンスを向上させます。

誤りを報告