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。
- 在本機環境中安裝安裝的節點版本 18 以上版本。請按照這些指示安裝節點。
- 將擴充功能的存放區複製到本機主目錄,然後前往存放區的根目錄。就本程式碼研究室而言,所有程式碼範例都會假設複製的存放區位於本機主目錄中。
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
- 請前往複製的存放區根目錄,並將
.env.example
檔案重新命名為.env
,以便在本程式碼研究室的後續章節中設定環境變數。
cd ~/dashboard-summarization
mv .env.example .env
- 前往複製的存放區 Web Socket 後端的
src
目錄。這個目錄包含伺服器原始碼。
cd ~/dashboard-summarization/websocket-service/src
- 使用 NPM 安裝服務的依附元件。
npm install
- 將
looker-example.ini
檔案重新命名為looker.ini
。
mv looker-example.ini looker.ini
- Looker.ini 檔案更新內部:
- 含有 Looker API 金鑰中的
client_id
和client_secret
。 base_url
與 Looker 執行個體的網址,格式如下:https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
- 括號 (區段標頭) 之間的文字,以及 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
- 判定您的 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 模型之間的介面。這項服務會從前端擴充功能擷取資訊主頁和 LookML 資料,以及透過 Looker 查詢的資料,以及提示 Vertex AI 的 Gemini 模型。接著,服務會串流 Gemini 回覆的前端擴充功能,顯示在資訊主頁中。
您也可以修改後端服務的原始碼。您必須先停止服務程序、變更程式碼,然後再執行 npm start
。
3. 設定本機開發環境的前端
您將設定前端擴充功能,以便在本節中試用及開發本機版本。
- 在前面步驟所用的相同本機環境中,前往已複製的存放區的根目錄,然後為前端安裝前端伺服器的依附元件。
cd ~/dashboard-summarization
npm install
- 啟動本機前端開發伺服器
npm run develop
- 本機前端伺服器現在會在 http://localhost:8080/bundle.js 提供擴充功能的 JavaScript。
- 開啟網路瀏覽器,然後登入 Looker 執行個體。
- 請按照這些操作說明設定空白的 LookML 專案。為專案命名為「資訊主頁摘要」。目前的瀏覽器分頁中,空白 LookML 專案應會自動開啟在 Looker IDE 中。
- 在 LookML 專案的根目錄中建立專案資訊清單檔案。檔案名稱為 manifest.lkml。如果不知道如何操作,請按照這篇文章的操作說明,將檔案新增至 LookML 專案。
- 將新 manifest.lkml 檔案的內容替換為關閉存放區根目錄中的 manifest.lkml 內容。選取右上角的「儲存變更」按鈕,即可儲存檔案變更內容。
- 在另一個瀏覽器分頁中,前往 Looker 執行個體中的資料庫連線清單。如果您不知道該如何操作,請按照這些操作說明進行。
- 選擇一個 Looker 資料庫連線的名稱。選擇何種連線並不重要。如果權限不足,無法查看資料庫連線,請與 Looker 管理員聯絡,並索取一個 Looker 資料庫連線的名稱。
- 在 Looker IDE 中開啟 LookML 專案,返回瀏覽器分頁。在 LookML 專案中建立模型檔案,並命名為檔案資訊主頁摘要。
- 將 dashboard-summarization.model.lkml 檔案的內容替換為下列程式碼範例。請務必將雙引號內的字串,替換為您在步驟 9 中選擇的資料庫連線名稱。儲存對檔案所做的變更。
connection: "<YOUR_CONNECTION_NAME>"
- 設定要儲存專案的存放區。選取右上方的「Configure Git」按鈕。選取「改為設定裸露的存放區」。選取 [建立存放區]。
- 您現在有了基本的裸露存放區,可用於儲存 LookML 專案檔案。選取「返回專案」或手動返回上一個畫面,即可返回 Looker IDE 中的專案。
- 選取右上角的「驗證 LookML」按鈕。按鈕會變更為「Commit changes and push」。
- 選取 [修訂變更並推送] 按鈕。新增任何想要的訊息,然後選取「確認」。
- 選取 Looker IDE 右上角的「部署至實際工作環境」。您已成功將擴充功能新增至 Looker 執行個體!
- 前往要新增擴充功能的 Looker 資訊主頁。
- 按照操作說明在資訊主頁中加入擴充功能圖塊。將新的擴充功能新增至資訊主頁,做為資訊方塊。
- 確保您先前設定的本機 websocket 後端服務正在執行。
恭喜!您現在可以在資訊主頁中試用 Looker 資訊主頁摘要擴充功能。擴充功能會將資訊主頁的中繼資料傳送至本機 websocket 後端服務,再透過資訊主頁擴充功能圖塊,顯示後端服務的 Gemini 輸出內容。
當本機前端伺服器執行時,您可以變更擴充功能的 JavaScript 原始碼,伺服器會自動建構並提供變更。您需要重新載入擴充功能或資訊主頁,才能看到變更。
4. 將後端部署至實際工作環境
在本節中,您將設定 websocket 後端服務,在 Looker 執行個體的任何資訊主頁中,提供資訊主頁摘要擴充功能的所有執行個體。這樣一來,其他 Looker 使用者就能在自己的資訊主頁試用這項擴充功能,不必自行設定後端服務。這些步驟假設您之前已在相同的本機環境中,成功部署本機開發的後端。
- 請按照這些操作說明,在本機環境中設定應用程式預設憑證,並使用專案 ID 進行後續步驟。
- 為後端服務的 Docker 映像檔建立 Artifact Registry 存放區。將
YOUR_REGION
替換為您要放置存放區的區域。
gcloud artifacts repositories create dashboard-summarization-repo \
--repository-format=docker \
--location=YOUR_REGION \
- 前往複製的存放區 Web Socket 後端的
src
目錄。
cd ~/dashboard-summarization/websocket-service/src
- 編輯
cloudbuild.yaml
檔案,並將YOUR_REGION
和YOUR_PROJECT_ID
的所有執行個體替換為您的區域和專案 ID。儲存對檔案所做的變更。 - 使用 Cloud Build 提交建構作業,以便建構後端服務 Docker 映像檔,並將其推送至您剛建立的 Artifact Registry 存放區。將
YOUR_REGION
替換為您要使用 Cloud Build 服務的地區。
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
- 請注意,您新建的 Docker 映像檔網址位於
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 映像檔網址。將YOUR_REGION
替換為您在上一個步驟 8 中選擇的區域。將變更儲存至檔案。 - 透過 terraform 部署後端服務要使用的資源。
terraform init
terraform plan
terraform apply
- 儲存已部署的 Cloud Run 網址端點,供下節使用。
恭喜!您已部署 websocket 後端服務,這項服務正在 Google Cloud Run 中執行。現在,Looker 資訊主頁摘要擴充功能的所有執行個體都能與後端服務通訊。建議您在 Cloud Run 上始終至少執行一個 WebSocket 後端服務例項。維持後端服務的持續性,就能在 websocket 後端服務和擴充功能前端之間,維持資料串流的完整性,並協助每位使用者在使用擴充功能時維持工作階段。
5. 將前端部署至實際工作環境
在這個最後一節中,您將執行部署擴充功能前端的最後步驟,讓 Looker 執行個體中的所有 Looker 使用者都能使用。
- 前往複製的存放區根目錄。
cd ~/dashboard-summarization
- 編輯。
env
檔案。將YOUR_CLOUD_RUN_URL
替換為上一節的 Cloud Run 網址端點。儲存檔案變更。這會將實際工作環境擴充功能的前端指向在 Cloud Run 執行的 websocket 後端服務。 - 建立擴充功能的 JavaScript。系統會自動使用
bundle.js
檔案和當中的其他檔案產生dist
目錄。
npm run build
- 開啟網路瀏覽器,然後登入 Looker 執行個體。開啟左側導覽列,然後將底部的「開發模式」切換鈕設為開啟。
- 開啟左側導覽面板,選取「Develop」,然後向下捲動並選取「dashboard-summarization」,也就是擴充資料的 LookML 專案。現在應該會在 Looker IDE 中進入 LookML 專案。
- 將先前產生的 Dist 目錄中的所有檔案,拖曳到專案的「File Browser」(檔案瀏覽器) 根目錄中。如需進一步協助,請按照這些說明操作。
- 在 Looker IDE 中開啟
manifest.lkml
檔案。在檔案中,取代以下行
url: "http://localhost:8080/bundle.js"
套用後
file: "bundle.js"
將 YOUR_CLOUD_RUN_URL
替換為最後一節結尾的 Cloud Run 網址端點。儲存檔案的變更。
- 選取右上角的「驗證 LookML」按鈕。該按鈕會變更為「Commit changes and 推送」。
- 選取 [修訂變更並推送] 按鈕。新增任何想要的訊息,然後選取「確認」。
- 選取 Looker IDE 右上角的「部署至生產環境」。
恭喜!您現在已啟用 Looker 執行個體中的所有 Looker 使用者,讓他們在資訊主頁中新增 Looker 資訊主頁摘要擴充功能。當其他 Looker 使用者使用擴充功能時,所有擴充功能例項都會呼叫在 Google Cloud Run 上執行的已部署 WebSocket 後端服務。
請注意,如果您對原始碼進行任何變更,請務必:
- 再次建構擴充功能的 JavaScript
- 請將您新增至 LookML 專案產生的檔案,替換為
dist
目錄中新產生的檔案。 - 驗證 LookML 專案變更、提交,並將其部署至實際運作環境
試用 Looker 資訊主頁摘要擴充功能!歡迎您為擴充功能做出貢獻,協助我們更妥善地滿足 Looker 社群的需求。歡迎您在存放區中建立提取要求。
請參考下列選用章節,瞭解如何啟用 Slack/Google Chat 匯出功能、調整 Gemini 的摘要功能和後續步驟,並設定 Gemini 記錄功能。
6. [選用] 設定匯出功能
您和 Looker 使用者試用 Looker 資訊主頁摘要外掛程式後,現在可以將外掛程式的洞察資料分享給更多對象。請按照本節說明,讓擴充功能將摘要和後續步驟傳送至 Google 即時通訊或 Slack。請先熟悉 OAuth 設定,才能繼續完成本程式碼研究室的這個部分。
啟用 Google Chat 匯出功能
- 在 Google Cloud 專案中啟用 Chat API。
- 按照 Google Workspace OAuth 設定操作說明的步驟 1 操作。您必須加入
spaces.messages.create
這個範圍。 - 按照 Google Workspace OAuth 設定操作說明的步驟 2 操作。在「已授權的 JavaScript 來源」下方,將 Looker 例項的網址新增為 URI,例如
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 聊天室或 Slack 頻道。您可以新增其他 OAuth 範圍,並修改程式碼,擷取並顯示要傳送摘要的聊天室和頻道清單。
7. [選用] 調整摘要和後續步驟
擴充功能會向 Gemini 模型提示資訊主頁的所有中繼資料和查詢資料。您可以為資訊主頁加入盡可能多的中繼資料和背景資訊,藉此提升摘要和建議步驟的準確性、詳細程度和深度。請在擴充功能參與的每個資訊主頁中嘗試下列步驟:
- 請按照操作說明,在資訊主頁中新增資訊主頁詳細資料。讓 LLM 瞭解資訊主頁的一般背景資訊。
- 依照這些指示,為每個資訊主頁的圖塊新增附註。這有助於向 LLM 提供資訊,說明資訊主頁上每個個別查詢的脈絡。系統會將這些小型內容參考資料納入摘要中。
在資訊主頁中加入的資訊越多,額外資訊的摘要和後續步驟就越有參考價值。您可以修改程式碼,在 Gemini 模型的提示中加入其他資訊主頁中繼資料。
8. [選用] 設定 Gemini 模型記錄功能
每當使用者要求擴充功能為資訊主頁建立摘要時,擴充功能就會針對資訊主頁中的每項查詢呼叫 Vertex AI,並發出最後一次呼叫來設定所有摘要的格式。請按照本節的說明記錄外掛程式發出的 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 服務
- 將擴充功能以資訊方塊的形式整合至資訊主頁,強化資訊主頁的使用體驗。