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

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 [e-mail]:looker-open-source/dashboard-summarization.git

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

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

4. 前往複製的存放區 Web Socket 後端的 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. 含有 Looker API 金鑰中的 client_id 和 client_secret。
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 專案。為專案命名為「資訊主頁摘要」。目前的瀏覽器分頁中，空白 LookML 專案應會自動開啟在 Looker IDE 中。
6. 在 LookML 專案的根目錄中建立專案資訊清單檔案。檔案名稱為 manifest.lkml。如果不知道如何操作，請按照這篇文章的操作說明，將檔案新增至 LookML 專案。
7. 將新 manifest.lkml 檔案的內容替換為關閉存放區根目錄中的 manifest.lkml 內容。選取右上角的「儲存變更」按鈕，即可儲存檔案變更內容。
8. 在另一個瀏覽器分頁中，前往 Looker 執行個體中的資料庫連線清單。如果您不知道該如何操作，請按照這些操作說明進行。
9. 選擇一個 Looker 資料庫連線的名稱。選擇何種連線並不重要。如果權限不足，無法查看資料庫連線，請與 Looker 管理員聯絡，並索取一個 Looker 資料庫連線的名稱。
10. 在 Looker IDE 中開啟 LookML 專案，返回瀏覽器分頁。在 LookML 專案中建立模型檔案，並命名為檔案資訊主頁摘要。
11. 將 dashboard-summarization.model.lkml 檔案的內容替換為下列程式碼範例。請務必將雙引號內的字串，替換為您在步驟 9 中選擇的資料庫連線名稱。儲存對檔案所做的變更。

connection: "<YOUR_CONNECTION_NAME>"

注意：您在這項專案中定義的資料庫連線，並未定義資訊主頁摘要擴充功能所查詢的資料庫。當擴充功能加入資訊主頁時，擴充功能會查詢與該資訊主頁相關聯的資料庫。

12. 設定要儲存專案的存放區。選取右上方的「Configure Git」按鈕。選取「改為設定裸露的存放區」。選取 [建立存放區]。
13. 您現在有了基本的裸露存放區，可用於儲存 LookML 專案檔案。選取「返回專案」或手動返回上一個畫面，即可返回 Looker IDE 中的專案。
14. 選取右上角的「驗證 LookML」按鈕。按鈕會變更為「Commit changes and push」。
15. 選取 [修訂變更並推送] 按鈕。新增任何想要的訊息，然後選取「確認」。
16. 選取 Looker IDE 右上角的「部署至實際工作環境」。您已成功將擴充功能新增至 Looker 執行個體！
17. 前往要新增擴充功能的 Looker 資訊主頁。
18. 按照操作說明在資訊主頁中加入擴充功能圖塊。將新的擴充功能新增至資訊主頁，做為資訊方塊。
19. 確保您先前設定的本機 websocket 後端服務正在執行。

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

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

注意：您可以按照本程式碼研究室結尾的選用部分操作，讓擴充功能將摘要和後續步驟匯出至 Slack 或 Gchat。

注意：您也可以在本程式碼研究室結尾的選用部分，提升擴充功能摘要和後續步驟的準確率、詳細資料和深度。

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. 前往複製的存放區 Web Socket 後端的 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. 決定要在哪個 Google Cloud Run 位置執行 websocket 後端服務。請從下列地點中選擇。
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 後端服務和擴充功能前端之間，維持資料串流的完整性，並協助每位使用者在使用擴充功能時維持工作階段。

注意：在這個程式碼研究室中，部署至雲端的 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。系統會自動使用 bundle.js 檔案和當中的其他檔案產生 dist 目錄。

npm run build

4. 開啟網路瀏覽器，然後登入 Looker 執行個體。開啟左側導覽列，然後將底部的「開發模式」切換鈕設為開啟。
5. 開啟左側導覽面板，選取「Develop」，然後向下捲動並選取「dashboard-summarization」，也就是擴充資料的 LookML 專案。現在應該會在 Looker IDE 中進入 LookML 專案。
6. 將先前產生的 Dist 目錄中的所有檔案，拖曳到專案的「File Browser」(檔案瀏覽器) 根目錄中。如需進一步協助，請按照這些說明操作。
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 推送」。
9. 選取 [修訂變更並推送] 按鈕。新增任何想要的訊息，然後選取「確認」。
10. 選取 Looker IDE 右上角的「部署至生產環境」。

恭喜！您現在已啟用 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 即時通訊或 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 聊天室或 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. 後續步驟

• 修改擴充功能的程式碼集，依據貴機構的需求自訂功能。
• 為擴充功能的存放區提供貢獻，為自己和 Looker 社群改善擴充功能。
• 自行開發擴充功能，強化 Looker 服務
• 將擴充功能以資訊方塊的形式整合至資訊主頁，強化資訊主頁的使用體驗。