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 Core 试用许可或有效的 Looker Core 许可获得。
• 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 [e-mail]:looker-open-source/dashboard-summarization.git

3. 进入克隆的代码库的根目录，并将 .env.example 文件重命名为 .env，以便您在本 Codelab 的后续部分中设置环境变量。

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

4. 进入克隆的代码库的 WebSocket 后端的 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. 包含 Looker 实例网址的 base_url，格式为：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 项目。为项目信息中心摘要命名。现在，您应该会在当前浏览器标签页中的 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”按钮。选择“Set up a bare repository instead”（改为设置裸代码库）。选择“创建代码库”。
13. 现在，您有了一个基本的空代码库，可用于存储 LookML 项目文件。选择“返回项目”或手动返回，在 Looker IDE 中返回到项目。
14. 选择右上角的“验证 LookML”按钮。该按钮将变为“提交更改并推送”。
15. 选择“提交更改并推送”按钮。添加任意消息，然后选择“提交”。
16. 在 Looker IDE 的右上角选择“部署到生产环境”。您现在已将扩展程序添加到 Looker 实例！
17. 前往您要向其中添加扩展程序的 Looker 信息中心。
18. 按照说明将扩展程序板块添加到信息中心。将新扩展程序作为功能块添加到信息中心。
19. 确保您之前设置的本地 WebSocket 后端服务正在运行。

恭喜！您现在可以在信息中心内试用 Looker 信息中心摘要扩展程序。扩展程序会将信息中心的元数据发送到本地 WebSocket 后端服务，并直接在信息中心扩展程序模块中显示后端服务的 Gemini 输出。

在本地前端服务器运行期间，您可以更改扩展程序的 JavaScript 源代码，服务器会自动构建并提供更改。您需要重新加载扩展程序或信息中心页面才能看到更改。

注意：您可以按照此 Codelab 末尾的可选部分中的步骤操作，以使扩展程序能够将其总结和后续步骤导出到 Slack 或 Gchat。

注意：您还可以通过本 Codelab 末尾的可选部分，提高扩展程序摘要和后续步骤的准确性、详细程度和深度。

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. 进入克隆的代码库的 WebSocket 后端 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 后端服务与扩展程序前端之间进行数据流式传输时，数据的完整性得以保持，并有助于在用户使用扩展程序时保持每个用户的会话。

注意：在此代码实验中部署到 Cloud Run 的 WebSocket 后端服务是公开的。

注意：每次用户指示扩展程序前端为某个信息中心创建摘要时，后端服务都会针对信息中心内的每个查询调用 Vertex AI，并进行一次最终调用来格式化所有摘要。您可以记录后端服务发出的 Vertex AI 调用，以帮助估算和监控费用。请查看此 Codelab 的“设置 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”按钮。该按钮将变为“提交更改并推送”。
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 Chat 或 Slack 发送总结和后续步骤。您应该熟悉 OAuth 设置，才能继续学习本 Codelab 的这一部分。

启用 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. 后续步骤

• 修改扩展程序的代码库，以根据组织的需求定制其功能。
• 为扩展程序的代码库做出贡献，并为自己和 Looker 社区改进扩展程序。
• 开发自己的扩展程序，以增强 Looker 体验
• 将扩展程序作为功能块集成到信息中心，以提升信息中心的使用体验。