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

1. 事前準備

在本程式碼研究室中，您將 (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 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. 在本機環境中安裝 Node 18 以上版本。請按照這些操作說明安裝 Node。
2. 將擴充功能的存放區複製到本機主目錄，然後前往存放區的根目錄。為方便進行本程式碼實驗室，所有程式碼範例都會假設您複製的存放區位於本機主目錄中。

cd ~
git clone [e-mail]:looker-open-source/dashboard-summarization.git

3. 前往複製的存放區根目錄，並將 .env.example 檔案重新命名為 .env，以便在本程式碼研究室的後續章節中設定環境變數。

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

4. 前往複製存放區中網頁通訊端後端的 src 目錄。這個目錄包含伺服器的原始碼。

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

5. 使用 NPM 安裝服務的依附元件。

npm install  

6. 將 looker-example.ini 重新命名為 looker.ini。

mv looker-example.ini looker.ini  

7. 在 looker.ini 檔案中更新：
8. 將 client_id 和 client_secret 替換成 Looker API 金鑰中的值。
9. base_url，其中包含 Looker 執行個體網址，格式為：https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
10. 括號之間的文字 (區段標題)，其中包含 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 

8. 找出 Google Cloud 雲端專案 ID，並在 PROJECT 環境變數中設定。將 YOUR_PROJECT_ID 替換為專案 ID。

export PROJECT="YOUR_PROJECT_ID"

9. Vertex AI 在多個區域提供 Gemini 模型，詳情請參閱這篇文章。決定本機後端要從 Vertex AI 的 Gemini 模型傳送及接收資料的區域。在 REGION 環境變數中設定區域。將 YOUR_VERTEX_REGION 替換為您的區域，例如 us-central1。

export REGION="YOUR_VERTEX_REGION"

10. 現在啟動本機服務。

npm start

11. 本機 WebSocket 後端服務會在 http://localhost:5000 上執行。

您已完成在本機環境中設定 WebSocket 後端服務！

這項服務可做為前端擴充功能與 Vertex AI 的 Gemini 模型之間的介面。這項服務會從前端擴充功能擷取資訊主頁和 LookML 資料，並從 Looker 查詢資料，然後提示 Vertex AI 的 Gemini 模型。接著，服務會將 Gemini 的回覆串流傳輸至前端擴充功能，並顯示在資訊主頁中。

您也可以變更後端服務的原始碼。您必須先停止服務程序、變更程式碼，然後再次執行 npm start。

注意：您的本機 WebSocket 後端服務會呼叫 Vertex AI。

3. 設定前端以進行本機開發

在本節中，您將設定前端擴充功能，以便在本機上試用及開發。

1. 在與先前步驟相同的本機環境中，前往已複製存放區的根目錄，然後安裝前端伺服器的前端依附元件。

cd ~/dashboard-summarization
npm install

2. 啟動本機前端開發伺服器

npm run develop

3. 現在，本機前端伺服器會在 http://localhost:8080/bundle.js 提供擴充功能的 JavaScript。
4. 開啟網路瀏覽器，然後登入 Looker 執行個體。
5. 請按照這些操作說明設定空白 LookML 專案。將專案資訊主頁命名為「summarization」。現在，您應該會在目前瀏覽器分頁的 Looker IDE 中，自動開啟空白的 LookML 專案。
6. 在 LookML 專案的根目錄中建立專案資訊清單檔案。檔案名稱為 manifest.lkml。如不瞭解如何操作，請按照這些操作說明，將檔案新增至 LookML 專案。
7. 將新 manifest.lkml 檔案的內容，換成已關閉存放區根目錄中 manifest.lkml 的內容。選取右上角的「儲存變更」按鈕，將變更儲存至檔案。
8. 在另一個瀏覽器分頁中，前往 Looker 執行個體中的資料庫連線清單。如果不確定如何操作，請按照這些說明操作。
9. 選擇一個 Looker 資料庫連線的名稱。選擇哪種連線方式都可以。如果沒有查看資料庫連線的權限，請聯絡 Looker 管理員，並詢問其中一個 Looker 資料庫連線的名稱。
10. 返回瀏覽器分頁，在 Looker IDE 中開啟 LookML 專案。在 LookML 專案中建立模型檔案，並將檔案命名為「dashboard-summarization」。
11. 將 dashboard-summarization.model.lkml 檔案的內容替換為下列程式碼範例。請務必將雙引號內的字串，替換為您在步驟 9 中選擇的資料庫連線名稱。儲存對檔案所做的變更。

connection: "<YOUR_CONNECTION_NAME>"

注意：您在這個專案中定義的資料庫連線，不會定義資訊主頁摘要擴充功能查詢的資料庫。將擴充功能新增至資訊主頁後，擴充功能會查詢與該資訊主頁相關聯的資料庫。

12. 設定要儲存專案的存放區。選取右上角的「設定 Git」按鈕。選取「改為設定裸存放區」。選取「建立存放區」。
13. 您現在擁有基本的裸存放區，可儲存 LookML 專案檔案。選取「Back to project」或手動返回，即可在 Looker IDE 中返回專案。
14. 選取右上角的「驗證 LookML」按鈕。按鈕會變更為「Commit changes and push」。
15. 選取「Commit changes and push」(提交變更並推送) 按鈕。新增所需訊息，然後選取「Commit」。
16. 在 Looker IDE 右上角選取「Deploy to Production」(部署至正式環境)。您已將擴充功能新增至 Looker 執行個體！
17. 前往要新增擴充功能的 Looker 資訊主頁。
18. 按照操作說明將擴充功能動態磚新增至資訊主頁。將新擴充功能以資訊方塊的形式新增至資訊主頁。
19. 確認您先前設定的本機 WebSocket 後端服務正在執行。

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

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

注意：您可以按照本程式碼研究室結尾的選用章節，啟用擴充功能，將摘要和後續步驟匯出至 Slack 或 Google Chat。

注意：您也可以在本程式碼研究室結尾的選填章節中，瞭解如何提升擴充功能的摘要和後續步驟的準確率、詳細程度和深度。

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 \

3. 前往複製存放區中網頁通訊端後端的 src 目錄。

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

4. 編輯 cloudbuild.yaml 檔案，並將所有 YOUR_REGION 和 YOUR_PROJECT_ID 執行個體替換為您的區域和專案 ID。儲存對檔案所做的變更。
5. 使用 Cloud Build 提交建構作業，建構後端服務 Docker 映像檔，並推送至您剛建立的 Artifact Registry 存放區。將 YOUR_REGION 替換為要使用 Cloud Build 服務的區域。

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

6. 請注意，新建立的 Docker 映像檔網址位於 YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest。將 YOUR_PROJECT_ID 替換為專案 ID。將 YOUR_REGION 替換為您在步驟 2 中用於建立 Artifact Registry 存放區的區域。
7. 前往複製存放區中的 websocket-service/terraform 目錄。

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

8. 決定要執行 WebSocket 後端服務的 Google Cloud Run 位置。你可以選擇下列地點。
9. 編輯 variables.tf 檔案，並將 YOUR_PROJECT_ID 和 YOUR_DOCKER_IMAGE_URL 替換為適當的值。請參閱步驟 6，瞭解 Docker 映像檔網址。將 YOUR_REGION 替換為您在上一個步驟 8 中選擇的區域。儲存檔案變更。
10. 使用 Terraform 部署後端服務將使用的資源。

terraform init
terraform plan
terraform apply

11. 請儲存已部署的 Cloud Run 網址端點，以供下一節使用。

恭喜！您已部署 WebSocket 後端服務，該服務目前在 Google Cloud Run 上執行。現在，Looker 資訊主頁摘要擴充功能的任何執行個體，都能與後端服務通訊。建議您在 Cloud Run 上，至少執行一個 WebSocket 後端服務執行個體。後端服務的持續性可確保 WebSocket 後端服務與擴充功能前端之間資料串流的完整性，並協助維護每位使用者在擴充功能中的工作階段。

注意：在本程式碼研究室中，部署至 Cloud Run 的 WebSocket 後端服務會公開顯示。

注意：每當使用者要求擴充功能前端為資訊主頁建立摘要時，後端服務會針對資訊主頁中的每個查詢呼叫 Vertex AI，並進行最後一次呼叫來格式化所有摘要。您可以記錄後端服務發出的 Vertex AI 呼叫，協助估算及監控費用。如要瞭解如何設定，請參閱本程式碼研究室的「設定 Gemini 模型記錄」選用章節。

5. 將前端部署至正式環境

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

1. 前往複製的存放區根目錄。

cd ~/dashboard-summarization

2. 編輯 。env 檔案。將 YOUR_CLOUD_RUN_URL 替換為上一節的 Cloud Run 網址端點。儲存檔案變更。這會將正式版擴充功能前端指向在 Cloud Run 上執行的 WebSocket 後端服務。
3. 建構擴充功能的 JavaScript。系統會自動產生 dist 目錄，其中包含 bundle.js 檔案和其他檔案。

npm run build

4. 開啟網路瀏覽器，然後登入 Looker 執行個體。開啟左側導覽列，然後開啟底部的「開發模式」切換鈕。
5. 開啟左側導覽面板，選取「開發」，然後向下捲動並選取「dashboard-summarization」，也就是擴充功能的 LookML 專案。您現在應該位於 LookML 專案的 Looker IDE。
6. 將先前產生的 dist 目錄中的所有檔案，拖曳至「檔案瀏覽器」中的專案根目錄。如需進一步協助，請按照這些指示操作。
7. 在 Looker IDE 中開啟 manifest.lkml 檔案。在檔案中，將以下程式碼行

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

套用後

file: "bundle.js"

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

8. 選取右上角的「驗證 LookML」按鈕。按鈕會變更為「Commit changes and push」。
9. 選取「Commit changes and push」(提交變更並推送) 按鈕。新增所需訊息，然後選取「Commit」。
10. 選取 Looker IDE 右上角的「Deploy to Production」。

恭喜！您已為 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 瞭解資訊主頁的整體脈絡。
• 請按照這些指示在每個資訊主頁的動態磚中新增附註。這有助於讓大型語言模型瞭解資訊主頁上每個查詢的脈絡。系統會將這些簡短的情境附註納入生成的摘要。

您在資訊主頁中加入的資訊越多，擴充功能的摘要和後續步驟就越完善。您可以修改程式碼，在提示中加入其他資訊主頁中繼資料，提供給 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. 後續步驟

• 修改擴充功能的程式碼集，根據貴機構需求調整功能。
• 為擴充功能的存放區貢獻心力，為您和 Looker 社群改善擴充功能。
• 開發專屬擴充功能，提升 Looker 體驗
• 將擴充功能整合到資訊主頁中做為資訊方塊，提升資訊主頁體驗。