Looker 資訊主頁摘要擴充功能程式碼研究室

Looker 資訊主頁摘要擴充功能程式碼研究室

程式碼研究室簡介

subject上次更新時間：6月 8, 2024
account_circle作者：Jeremy Chang

1. 事前準備

在本程式碼研究室 (1) 中，您將在本機設定 Looker 資訊主頁摘要擴充功能，以便在本機試用及開發。接著 (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 Original 授權、有效的 Looker Core 試用方案或有效的 Looker Core 授權。
  • Looker 執行個體的 develop 和 deploy 權限。
  • 您想透過擴充功能試用的資訊主頁編輯權限。
  • Looker 執行個體的 Looker API 金鑰。
  • 已啟用計費功能的 Google Cloud 專案。
  • 已為專案啟用 Cloud Run API、Vertex AI API 和 Artifact Registry API。
  • 可在已安裝 gcloud CLI 的情況下存取本機環境。程式碼研究室的步驟假設使用的是 Linux 樣式環境。

2. 設定本機開發作業的後端

在本節中，您將設定 websocket 後端服務，試著在本機進行開發。服務將可使用 Vertex AI。

  1. 在本機環境中安裝安裝的節點版本 18 以上版本。請按照這些指示安裝節點。
  2. 將擴充功能的存放區複製到本機主目錄，然後前往存放區的根目錄。就本程式碼研究室而言，所有程式碼範例都會假設複製的存放區位於本機主目錄中。
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. 請前往複製的存放區根目錄，並將 .env.example 檔案重新命名為 .env，以便在本程式碼研究室的後續章節中設定環境變數。
cd ~/dashboard-summarization
mv .env.example .env
  1. 前往複製的存放區 Web Socket 後端的 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. 含有 Looker API 金鑰中的 client_id 和 client_secret。
  3. 將 base_url 換成 Looker 執行個體網址，格式為：https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. 括號 (區段標頭) 之間的文字與 Looker 執行個體網址的主機。

舉例來說，如果您的用戶端 ID 為 ABC123，用戶端密鑰為 XYZ789，而 Looker 執行個體的網址為 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 模型之間的介面。這項服務會從前端擴充功能擷取資訊主頁和 LookML 資料，以及透過 Looker 查詢的資料，以及提示 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 專案。為專案資訊主頁摘要命名。在目前的瀏覽器分頁中，Looker IDE 中現在應該會自動開啟空白的 LookML 專案。
  4. 在 LookML 專案的根目錄中建立專案資訊清單檔案。檔案名稱為 manifest.lkml。如果您不知道做法，請按照這些操作說明將檔案新增至 LookML 專案。
  5. 將新 manifest.lkml 檔案的內容替換為關閉存放區根目錄中的 manifest.lkml 內容。選取 [儲存變更]按鈕即可儲存檔案變更。
  6. 在另一個瀏覽器分頁中，前往 Looker 執行個體中的資料庫連線清單。如果您不知道該如何操作，請按照這些操作說明進行。
  7. 選擇其中一個 Looker 資料庫連線的名稱。選擇何種連線並不重要。如果權限不足，無法查看資料庫連線，請與 Looker 管理員聯絡，並索取一個 Looker 資料庫連線的名稱。
  8. 在 Looker IDE 中開啟 LookML 專案，返回瀏覽器分頁。在 LookML 專案中建立模型檔案，並命名為檔案資訊主頁摘要。
  9. 將 Dashboard-summarization.model.lkml 檔案的內容替換為下列程式碼範例。請務必將雙引號內的字串替換成您在步驟 9 中選擇的資料庫連線名稱。儲存對檔案所做的變更。
connection: "<YOUR_CONNECTION_NAME>"
  1. 設定要儲存專案的存放區。選取 [Configure Git] (設定 Git)右上方的按鈕。選取「改為設定裸機存放區」。選取 [建立存放區]。
  2. 現在您已擁有基本裸存放區，可以用來儲存 LookML 專案檔案。選取「返回專案」即可返回 Looker IDE 中的專案或手動返回上一個畫面
  3. 選取「驗證 LookML」。該按鈕會變更為「Commit changes and 推送」。
  4. 選取 [Commit changes andPush] (提交變更及推送)按鈕。新增所需的任何訊息，然後選取 [修訂]。
  5. 選取「部署至實際工作環境」。您已成功將擴充功能新增至 Looker 執行個體！
  6. 前往要新增擴充功能的 Looker 資訊主頁。
  7. 按照操作說明在資訊主頁中加入擴充功能圖塊。將新的擴充功能以圖塊的形式新增到資訊主頁。
  8. 確保您先前設定的本機 websocket 後端服務正在執行。

恭喜！您現在可以在資訊主頁中試用 Looker 資訊主頁摘要擴充功能。擴充功能會將資訊主頁的中繼資料傳送至本機 websocket 後端服務，再透過資訊主頁擴充功能圖塊，顯示後端服務的 Gemini 輸出內容。

在本機前端伺服器執行時，您可以變更擴充功能的 JavaScript 原始碼，伺服器隨即會自動建立並提供變更。你必須重新載入擴充功能或資訊主頁，才能看到變更。

4. 將後端部署至實際工作環境

在本節中，您將設定 websocket 後端服務，在 Looker 執行個體的任何資訊主頁中，提供資訊主頁摘要擴充功能的所有執行個體。這樣一來，其他 Looker 使用者就能在自己的資訊主頁試用這項擴充功能，不必自行設定後端服務。這些步驟假設您之前已經在同一個本機環境中成功部署用於本機開發的後端。

  1. 按照這些操作說明，使用專案 ID 在本機環境中設定應用程式預設憑證，以便執行後續步驟。
  2. 為後端服務的 Docker 映像檔建立 Artifact Registry 存放區。將 YOUR_REGION 替換為您要位於存放區的區域。
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. 前往複製的存放區 Web Socket 後端的 src 目錄。
cd ~/dashboard-summarization/websocket-service/src
  1. 編輯 cloudbuild.yaml 檔案，並將 YOUR_REGION 和 YOUR_PROJECT_ID 的所有執行個體替換為您的區域和專案 ID。儲存對檔案所做的變更。
  2. 透過 Cloud Build 提交建構作業，藉此建構後端服務 Docker 映像檔，並推送至您剛建立的 Artifact Registry 存放區。將 YOUR_REGION 替換為您要使用 Cloud Build 服務的區域。
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. 提醒您，新建構的 Docker 映像檔網址為 YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest。將 YOUR_PROJECT_ID 替換為您的專案 ID。將 YOUR_REGION 替換為您在步驟 2 中用於建立 Artifact Registry 存放區的區域。
  2. 前往複製的存放區中的 websocket-service/terraform 目錄。
cd ~/dashboard-summarization/websocket-service/terraform
  1. 決定要在哪個 Google Cloud Run 位置執行 websocket 後端服務。從這些地區中選擇。
  2. 請編輯 Variable.tf 檔案，並將 YOUR_PROJECT_ID 和 YOUR_DOCKER_IMAGE_URL 替換為適當的值。檢查步驟 6，找出 Docker 映像檔網址。將 YOUR_REGION 替換為您在上一個步驟 8 中選擇的區域。將變更儲存至檔案。
  3. 透過 terraform 部署後端服務要使用的資源。
terraform init
terraform plan
terraform apply
  1. 儲存已部署的 Cloud Run 網址端點，供下節使用。

恭喜！您已部署 websocket 後端服務，現在這項服務正在 Google Cloud Run 上執行。現在，Looker 資訊主頁摘要擴充功能的所有執行個體都能與後端服務通訊。建議您持續在 Cloud Run 執行至少一個 websocket 後端服務執行個體。維持後端服務的持續性，就能在 websocket 後端服務和擴充功能前端之間，維持資料串流的完整性，並協助每位使用者在使用擴充功能時維持工作階段。

5. 將前端部署至實際工作環境

在最後一節中，您將執行部署擴充功能前端的最後一個步驟，讓 Looker 執行個體中的所有 Looker 使用者使用。

  1. 前往複製的存放區根目錄。
cd ~/dashboard-summarization
  1. 編輯 .env 檔案。將 YOUR_CLOUD_RUN_URL 替換為上一節的 Cloud Run 網址端點。儲存檔案變更。這會將實際工作環境擴充功能的前端指向在 Cloud Run 執行的 websocket 後端服務。
  2. 建立擴充功能的 JavaScript。系統會自動使用 bundle.js 檔案和當中的其他檔案產生 dist 目錄。
npm run build
  1. 開啟網路瀏覽器，然後登入 Looker 執行個體。開啟左側導覽列並開啟「開發模式」切換面板
  2. 在左側導覽列開啟的情況下，選取「開發」，然後向下捲動並選取「dashboard-summarization」，也就是擴充功能的 LookML 專案。現在應該會在 Looker IDE 中進入 LookML 專案。
  3. 將先前產生的 Dist 目錄中的所有檔案，拖曳到專案的「File Browser」(檔案瀏覽器) 根目錄中。如需進一步協助，請按照這些說明操作。
  4. 在 Looker IDE 中開啟 manifest.lkml 檔案。在檔案中，將這一行程式碼
url: "http://localhost:8080/bundle.js"

套用後

file: "bundle.js"

將 YOUR_CLOUD_RUN_URL 替換為最後一節結尾的 Cloud Run 網址端點。儲存檔案變更。

  1. 選取「驗證 LookML」。該按鈕會變更為「Commit changes and 推送」。
  2. 選取 [Commit changes andPush] (提交變更及推送)按鈕。新增所需的任何訊息，然後選取 [修訂]。
  3. 選取「部署至實際工作環境」。

恭喜！您現已啟用 Looker 執行個體中的所有 Looker 使用者，將 Looker 資訊主頁摘要擴充功能新增至他們的資訊主頁。其他 Looker 使用者使用這個擴充功能時，擴充功能的所有執行個體都會呼叫您在 Google Cloud Run 中運作的已部署 WebSocket 後端服務。

請注意，如果您對原始碼進行任何變更，請務必：

  1. 再次建構擴充功能的 JavaScript
  2. 請將您新增至 LookML 專案產生的檔案，替換為 dist 目錄中新產生的檔案。
  3. 驗證及修訂 LookML 專案變更，並部署至實際工作環境

試用 Looker 資訊主頁摘要擴充功能！建議您對這項擴充功能貢獻一己之力，協助這項擴充功能更符合 Looker 社群的需求。如有需要，您可以在存放區建立提取要求。

請參考下列選用章節，瞭解如何啟用 Slack/Google Chat 匯出功能、調整 Gemini 的摘要功能和後續步驟，並設定 Gemini 記錄功能。

6. [選用] 設定匯出功能

您和 Looker 使用者已試用過 Looker 資訊主頁摘要擴充功能，現在可以與更多目標對象分享擴充功能的深入分析資訊。請按照這個部分啟用擴充功能，將摘要和後續步驟資料傳送到 Google Chat 或 Slack。請先熟悉 OAuth 設定，才能繼續完成本程式碼研究室的這個部分。

啟用 Google Chat 匯出功能

  1. 在 Google Cloud 專案中啟用 Chat API。
  2. 按照 Google Workspace OAuth 設定操作說明的步驟 1 操作。範圍必須包含 spaces.messages.create。
  3. 按照 Google Workspace OAuth 設定操作說明的步驟 2 操作。在「已授權的 JavaScript 來源」下方將 Looker 執行個體的網址新增為 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 對資訊主頁中的每項查詢，以及一次呼叫以設定所有摘要格式的最終呼叫。請按照這一節的說明記錄擴充功能發出的 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. 後續步驟

bug_report 回報錯誤