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 模型发送和接收数据。

前提条件

  • 基本熟悉节点开发、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 git@github.com:looker-open-source/dashboard-summarization.git
  1. 进入克隆的代码库的根目录，并将 .env.example 文件重命名为 .env，以便在此 Codelab 的后续部分中设置环境变量。
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. 将 client_id 和 client_secret 替换为 Looker API 密钥中的值。
  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 项目。将项目命名为 dashboard-summarization。现在，您应该会在当前浏览器标签页中的 Looker IDE 中自动打开空白的 LookML 项目。
  4. 在 LookML 项目的根目录中创建一个项目清单文件。该文件将命名为 manifest.lkml。如果您不清楚该如何操作，请按照有关向 LookML 项目添加文件的说明操作。
  5. 将新 manifest.lkml 文件的内容替换为封闭代码库根目录中的 manifest.lkml 的内容。选择右上角的“保存更改”按钮，保存对文件所做的更改。
  6. 在单独的浏览器标签页中，前往 Looker 实例中的数据库连接列表。如果您不清楚如何操作，请按照这些说明操作。
  7. 选择一个 Looker 数据库连接的名称。您选择哪种连接方式都无妨。如果您无权查看数据库连接，请与您的 Looker 管理员联系，并询问一个 Looker 数据库连接的名称。
  8. 返回到已在 Looker IDE 中打开的 LookML 项目的浏览器标签页。在 LookML 项目中创建模型文件，并将文件命名为 Dashboard-summarization。
  9. 将 Dashboard-summarization.model.lkml 文件的内容替换为以下代码示例。请务必用您在第 9 步中选择的数据库连接名称替换双引号内的字符串。保存对文件所做的更改。
connection: "<YOUR_CONNECTION_NAME>"
  1. 设置要将项目保存到的代码库。选择右上角的“Configure Git”（配置 Git）按钮。选择“改为设置裸代码库”。选择“创建代码库”。
  2. 现在，您有一个基本的裸代码库，用于存储您的 LookML 项目文件。通过选择“返回项目”或手动返回，在 Looker IDE 中导航回项目。
  3. 选择右上角的“验证 LookML”按钮。该按钮将更改为“提交更改并推送”。
  4. 选择“提交更改并推送”按钮。添加所需的任何消息，然后选择“提交”。
  5. 选择 Looker IDE 右上角的“部署到生产环境”。现在，您已将该扩展程序添加到您的 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 套接字后端的 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. 修改 variables.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。系统会自动生成 dist 目录，其中包含 bundle.js 文件和其他文件。
npm run build
  1. 打开网络浏览器，然后登录您的 Looker 实例。打开左侧边栏导航栏，然后开启底部的“开发者模式”切换开关。
  2. 打开侧边导航栏，选择“开发”，然后向下滚动并选择“dashboard-summarization”（扩展程序的 LookML 项目）。您现在应该位于该 LookML 项目的 Looker IDE 中。
  3. 将之前生成的 dist 目录中的所有文件拖放到“文件浏览器”中的项目根目录中。如果您需要更多帮助，请按照这些说明操作。
  4. 在 Looker IDE 中打开 manifest.lkml 文件。在文件内，将以下代码行
url: "http://localhost:8080/bundle.js"

通过

file: "bundle.js"

将 YOUR_CLOUD_RUN_URL 替换为最后一部分末尾的 Cloud Run 网址端点。保存对文件所做的更改。

  1. 选择右上角的“验证 LookML”按钮。该按钮将更改为“提交更改并推送”。
  2. 选择“提交更改并推送”按钮。添加所需的任何消息，然后选择“提交”。
  3. 选择 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 步操作。将您的 Looker 实例的网址作为 URI 添加到“已获授权的 JavaScript 来源”下，例如 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. 后续操作