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

1. 始める前に

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

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

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

前提条件

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

学習内容

  • 拡張機能をローカルでセットアップして開発する方法
  • Looker インスタンスの他の Looker ユーザーが使用できるように、拡張機能を本番環境にデプロイする方法
  • 必要に応じて拡張機能のパフォーマンスを微調整し、機能を拡張する方法。
  • 本番環境にデプロイした拡張機能を管理する方法

必要なもの

  • Looker オリジナル ライセンス、有効な Looker コア トライアル、または有効な Looker コア ライセンスのいずれかによる Looker インスタンス。
  • 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 にアクセスできます。

  1. ローカル環境に Node バージョン 18 以降をインストールします。こちらの手順に沿って Node をインストールします。
  2. 拡張機能のリポジトリをローカルのホーム ディレクトリにクローンし、リポジトリのルート ディレクトリに移動します。この Codelab では、クローンを作成したリポジトリがローカル ホーム ディレクトリにあることを前提として、すべてのコードサンプルを作成します。
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. クローンしたリポジトリのルート ディレクトリに移動し、.env.example ファイルの名前を .env に変更します。これにより、この Codelab の後半で環境変数を設定できるようになります。
cd ~/dashboard-summarization
mv .env.example .env
  1. クローン作成したリポジトリのウェブ ソケット バックエンドの src ディレクトリに移動します。このディレクトリには、サーバーのソースコードが含まれています。
cd ~/dashboard-summarization/websocket-service/src
  1. NPM を使用してサービスの依存関係をインストールします。
npm install
  1. ファイル looker-example.ini の名前を looker.ini に変更します。
mv looker-example.ini looker.ini
  1. looker.ini ファイル内で、次の内容を更新します。
  2. client_id と client_secret を Looker API キーのものに置き換えます。
  3. Looker インスタンスの URL を https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999 の形式で指定した base_url
  4. 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
  1. Google Cloud プロジェクト ID を特定し、PROJECT 環境変数に設定します。YOUR_PROJECT_ID は、実際のプロジェクト ID に置き換えます。
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI は、こちらに記載されている複数のリージョンで Gemini モデルを提供しています。ローカル バックエンドが Vertex AI の Gemini モデルからデータを送受信するリージョンを決定します。REGION 環境変数でリージョンを設定します。YOUR_VERTEX_REGION は、リージョン（us-central1 など）に置き換えます。
export REGION="YOUR_VERTEX_REGION"
  1. ローカル サービスを起動します。
npm start
  1. ローカルの WebSocket バックエンド サービスは http://localhost:5000 で実行されます。

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

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

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

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

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

  1. 前の手順と同じローカル環境で、クローン作成したリポジトリのルート ディレクトリに移動し、フロントエンドのフロントエンド サーバーの依存関係をインストールします。
cd ~/dashboard-summarization
npm install
  1. ローカル フロントエンド開発サーバーを起動する
npm run develop
  1. ローカルのフロントエンド サーバーが、http://localhost:8080/bundle.js で拡張機能の JavaScript を提供するようになりました。
  2. ウェブブラウザを開き、Looker インスタンスにログインします。
  3. こちらの手順に沿って、空の LookML プロジェクトを設定します。プロジェクトに dashboard-summarization という名前を付けます。現在のブラウザタブの Looker IDE で、空の LookML プロジェクトが自動的に開きます。
  4. LookML プロジェクトのルートにプロジェクト マニフェスト ファイルを作成します。ファイル名は manifest.lkml になります。方法がわからない場合は、LookML プロジェクトにファイルを追加する手順の説明をご覧ください。
  5. 新しい manifest.lkml ファイルの内容を、非公開リポジトリのルート ディレクトリにある manifest.lkml の内容に置き換えます。右上の [変更を保存] ボタンを選択して、ファイルへの変更を保存します。
  6. 別のブラウザタブで、Looker インスタンスのデータベース接続のリストに移動します。手順がわからない場合は、こちらの手順に沿って対応してください。
  7. Looker データベース接続の名前を 1 つ選択します。どの接続を選択してもかまいません。データベース接続を表示する権限がない場合は、Looker 管理者に連絡して、Looker データベース接続の名前を 1 つ尋ねます。
  8. Looker IDE で LookML プロジェクトが開いているブラウザタブに戻ります。LookML プロジェクトにモデルファイルを作成し、ファイル名を dashboard-summarization にします。
  9. dashboard-summarization.model.lkml ファイルの内容を次のコードサンプルに置き換えます。二重引用符内の文字列を、手順 9 で選択したデータベース接続名に置き換えてください。ファイルへの変更を保存します。
connection: "<YOUR_CONNECTION_NAME>"
  1. プロジェクトを保存するリポジトリを設定します。右上にある [Git を設定] ボタンを選択します。[代わりにベアリポジトリを設定する] を選択します。[リポジトリを作成] を選択します。
  2. これで、LookML プロジェクト ファイルを保存するための基本的なベア リポジトリができました。[プロジェクトに戻る] を選択するか、手動で戻って、Looker IDE のプロジェクトに戻ります。
  3. 右上にある [LookML を検証] ボタンを選択します。ボタンが [Commit changes and push] に変わります。
  4. [変更をコミットしてプッシュする] ボタンを選択します。任意のメッセージを追加して、[Commit] を選択します。
  5. Looker IDE の右上にある [Deploy to Production]（本番環境にデプロイ）を選択します。これで、拡張機能が Looker インスタンスに追加されました。
  6. 拡張機能を追加する Looker ダッシュボードに移動します。
  7. 手順に沿って、拡張機能タイルをダッシュボードに追加します。新しい拡張機能をタイルとしてダッシュボードに追加します。
  8. 前に設定したローカルの WebSocket バックエンド サービスが実行されていることを確認します。

おめでとうございます！Looker ダッシュボードの要約拡張機能をダッシュボードで試せるようになりました。拡張機能は、ダッシュボードのメタデータをローカルの WebSocket バックエンド サービスに送信し、バックエンド サービスからの Gemini の出力をダッシュボードの拡張機能タイル内に表示します。

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

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

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

  1. 次の手順に沿って、こちらの手順に沿って、ローカル環境でアプリケーションのデフォルト認証情報をプロジェクト ID を使用して設定します。
  2. バックエンド サービスの Docker イメージ用の Artifact Registry リポジトリを作成します。YOUR_REGION は、リポジトリを配置するリージョンに置き換えます。
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. クローン作成したリポジトリのウェブ ソケット バックエンドの src ディレクトリに移動します。
cd ~/dashboard-summarization/websocket-service/src
  1. cloudbuild.yaml ファイルを編集し、YOUR_REGION と YOUR_PROJECT_ID のすべてのインスタンスをリージョンとプロジェクト ID に置き換えます。ファイルへの変更を保存します。
  2. Cloud Build を使用してビルドを送信します。これにより、バックエンド サービスの Docker イメージがビルドされ、作成した Artifact Registry リポジトリに push されます。YOUR_REGION は、Cloud Build サービスを使用するリージョンに置き換えます。
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. 新しくビルドされた Docker イメージの URL は YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest にあります。YOUR_PROJECT_ID は、実際のプロジェクト ID に置き換えます。YOUR_REGION は、Artifact Registry リポジトリの作成に使用したステップ 2 のリージョンに置き換えます。
  2. クローン作成されたリポジトリの websocket-service/terraform ディレクトリに移動します。
cd ~/dashboard-summarization/websocket-service/terraform
  1. ウェブソケット バックエンド サービスを実行する Google Cloud Run のロケーションを決定します。こちらの地域から選択してください。
  2. variables.tf ファイルを編集し、YOUR_PROJECT_ID と YOUR_DOCKER_IMAGE_URL を適切な値に置き換えます。Docker イメージの URL については、ステップ 6 を確認してください。YOUR_REGION は、前の手順 8 で選択したリージョンに置き換えます。ファイルへの変更を保存します。
  3. Terraform を使用して、バックエンド サービスで使用するリソースをデプロイします。
terraform init
terraform plan
terraform apply
  1. 次のセクションで使用するため、デプロイされた Cloud Run URL エンドポイントを保存します。

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

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

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

  1. クローン作成したリポジトリのルート ディレクトリに移動します。
cd ~/dashboard-summarization
  1. 編集します。env ファイル。YOUR_CLOUD_RUN_URL は、前のセクションの Cloud Run URL エンドポイントに置き換えます。ファイルへの変更を保存します。これにより、本番環境の拡張機能フロントエンドが、Cloud Run で実行されている WebSocket バックエンド サービスを指すようになります。
  2. 拡張機能の JavaScript をビルドします。dist ディレクトリが自動的に生成され、その中に bundle.js ファイルなどのファイルが作成されます。
npm run build
  1. ウェブブラウザを開き、Looker インスタンスにログインします。左側のサイドナビゲーションを開き、下部にある [Development Mode] 切り替えボタンをオンにします。
  2. 左側のサイドナビゲーションを開いた状態で、[Develop] を選択し、下にスクロールして拡張機能の LookML プロジェクトである [dashboard-summarization] を選択します。これで、LookML プロジェクトの Looker IDE が表示されます。
  3. 前に生成した dist ディレクトリ内のすべてのファイルを、「ファイル ブラウザ」のプロジェクトのルート ディレクトリにドラッグ＆ドロップします。さらにサポートが必要な場合は、こちらの手順に沿って対応してください。
  4. Looker IDE 内で manifest.lkml ファイルを開きます。ファイル内で、次の行を
url: "http://localhost:8080/bundle.js"

と

file: "bundle.js"

YOUR_CLOUD_RUN_URL は、前のセクションの末尾にある Cloud Run URL エンドポイントに置き換えます。ファイルへの変更を保存します。

  1. 右上にある [LookML を検証] ボタンを選択します。ボタンが [Commit changes and push] に変わります。
  2. [変更をコミットしてプッシュする] ボタンを選択します。任意のメッセージを追加して、[Commit] を選択します。
  3. Looker IDE の右上にある [Deploy to Production] を選択します。

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

ソースコードを変更する場合は、次の点に注意してください。

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

Looker ダッシュボードの要約拡張機能をお試しください。拡張機能に貢献して、Looker コミュニティのニーズに合ったものにしてください。リポジトリで pull リクエストを作成してください。

次の省略可能なセクションでは、Slack/Google Chat のエクスポートを有効にする方法、Gemini の要約と次のステップを微調整する方法、Gemini のロギングを設定する方法について説明します。

6. [省略可] エクスポート機能をセットアップします。

Looker ユーザーが Looker ダッシュボードの要約拡張機能を試したので、拡張機能の分析情報をより多くのユーザーと共有しましょう。このセクションの手順に沿って、拡張機能で Google Chat または Slack に要約と次のステップを送信できるようにします。この Codelab のこのセクションに進むには、OAuth の設定について理解しておく必要があります。

Google Chat の書き出しを有効にする

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

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

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

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

7. [省略可] 要約と次のステップをファインチューニングする

拡張機能は、ダッシュボードのすべてのメタデータを使用して Gemini モデルにプロンプトを表示し、データをクエリします。ダッシュボード自体にメタデータとコンテキストをできるだけ多く追加することで、要約と推奨手順の精度、詳細度、深さを向上させることができます。拡張機能が組み込まれている各ダッシュボードで、次の手順を試してください。

  • こちらの手順に沿って、ダッシュボードの詳細をダッシュボードに追加します。これにより、LLM はダッシュボードの一般的なコンテキストを把握できます。
  • こちらの手順に沿って、各ダッシュボードのタイルにメモを追加します。これにより、ダッシュボードの個々のクエリのコンテキストが LLM に伝わるようになります。短いコンテキスト メモは、生成される要約に反映されます。

ダッシュボードに追加する情報が多いほど、拡張機能の要約と次のステップの精度が向上します。コードを変更して、Gemini モデルへのプロンプトにダッシュボードの追加のメタデータを含めることができます。

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

ユーザーが拡張機能にダッシュボードの概要の作成を指示するたびに、拡張機能はダッシュボード内のクエリごとに Vertex AI を呼び出し、最後にすべての概要をフォーマットする呼び出しを 1 回行います。このセクションでは、拡張機能が行う Vertex AI 呼び出しをロギングして、Vertex AI の費用とトラフィックを推定およびモニタリングする方法について説明します。この手順は、WebSocket バックエンド サービスをデプロイした場合にのみ行ってください。

  1. デプロイされた WebSocket バックエンド サービスの Cloud Run のロケーションを確認します。
  2. こちらの手順に沿って、ログを 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. 次のステップ