1. 始める前に
この Codelab（1）では、Looker Dashboard Summarization Extension をローカルに設定し、ローカルで試して開発します。次に（2）拡張機能を本番環境にデプロイして、Looker インスタンス内の他の Looker ユーザーが使用できるようにします。最後に、（3）追加の手順に沿って拡張機能の機能を微調整、強化できます。必須ではないセクションもすべて順番に完了する必要があります。
Looker ダッシュボード要約拡張機能の概要
機能的には、Looker ダッシュボードの要約拡張機能は、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 changes and push] に変わります。
- [変更をコミットしてプッシュ] ボタンを選択します。必要なメッセージを追加して [commit] を選択します。
- 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 changes and push] に変わります。
- [変更を commit して push する] ボタンを選択します。必要なメッセージを追加して [commit] を選択します。
- Looker IDE の右上にある [本番環境にデプロイ] を選択します。
おめでとうございます。これで、Looker インスタンス内のすべての Looker ユーザーが、ダッシュボードに Looker ダッシュボードの要約拡張機能を追加できるようになりました。他の 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 の機能を拡張する
- 拡張機能をタイルとしてダッシュボードに統合して、ダッシュボードの利便性を高めましょう。