使用对话式分析和 Looker 构建聊天应用

1. 准备工作

此 Codelab 将引导您使用 Looker 中的 Conversational Analytics API (CA API) 构建自己的聊天应用，以便查询数据。为了充分发挥这些功能的价值，您应熟悉 BigQuery、Looker、LLM 和代理，以及 Python。

学习内容

完成此 Codelab 后，您将学习到以下内容：

• 如何将对话式分析与 Looker 搭配使用
• 如何设置和使用 Conversational Analytics Python 快速入门应用（以及该应用的工作原理）
• 使用 Looker 通过 Conversational Analytics 进行语义建模的优势

所需条件

要完成本 Codelab，您需要：

• 安装了 ASC 人口统计数据 Looker Block 的 Looker 实例
• 对 Looker 实例的 API 和开发者访问权限
• 已安装 Python v3.11+、Git 和 gcloud 的本地环境。
• 已为您的用户账号设置以下 IAM 角色的云项目：
• roles/bigquery.dataViewer BigQuery Data Viewer
• roles/bigquery.user BigQuery User
• roles/looker.instanceUser Looker Instance User

2. 使用 BigQuery 构建并试用聊天应用

我们先来设置并试用以 BigQuery 为数据源的对话式分析快速入门应用。

进行身份验证并启用 Cloud API

1. 使用您的用户账号在本地进行身份验证：

gcloud auth login

2. 启用 Cloud 项目 API。请将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID：

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

3. 设置应用默认凭据 (ADC) 和结算：

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

设置快速入门应用

4. 将快速入门 GitHub 代码库克隆到本地环境中。请参阅以下示例命令：

git clone "https://github.com/looker-open-source/ca-api-quickstarts"

5. 进入您克隆的 ca-api-quickstarts 目录：

cd ca-api-quickstarts

6. 在 .streamlit 目录中创建一个 secrets.toml 文件。YOUR_LOOKER_CLIENT_ID 和 YOUR_LOOKER_CLIENT_SECRET 应该是您 Looker 实例中的 Looker 客户端 ID 和 Looker 客户端密钥。文件内容应如下所示：

[cloud]
project_id = "YOUR_PROJECT_ID"

[looker]
client_id = "YOUR_LOOKER_CLIENT_ID"
client_secret = "YOUR_LOOKER_CLIENT_SECRET"

您可以使用以下示例命令来创建该文件。请务必将这些值替换为您的项目 ID、客户端 ID 和客户端密钥：

cat > .streamlit/secrets.toml <<'EOF'
[cloud]
project_id = "YOUR_PROJECT_ID"

[looker]
client_id = "YOUR_LOOKER_CLIENT_ID"
client_secret = "YOUR_LOOKER_CLIENT_SECRET"
EOF

7. 安装快速入门应用的 Python 要求：

pip install -r requirements.txt

8. 运行快速入门应用：

streamlit run app.py

您正在运行自定义构建的 Streamlit 应用，这是一个开源 Python 应用框架，可让您制作交互式数据应用原型。如需了解详情，请参阅 Streamlit 文档。

9. 在您选择的浏览器中打开 https://localhost:8501。

试用快速入门应用

您现在位于快速入门应用的代理页面。您没有可用的数据代理。

什么是数据 AI 智能体？AI 智能体是使用 AI 来实现目标并代表用户完成任务的软件系统。它们展现出推理、规划和记忆能力，并在一定程度上能够自主学习、适应和做出决策。在我们的使用场景中，我们使用 AI 智能体来了解数据。智能体的行为由为其定义的系统指令决定。如需了解详情，请参阅什么是 AI 智能体？。

10. 现在，我们来创建一个说话像海盗的数据智能体，在创建智能体表单中执行以下操作：
11. 设置显示名称字段：

Pirate BQ Agent

2. 设置系统指令字段：

You are a pirate. Answer questions like a pirate

3. 选择 BigQuery 选项。
4. 设置项目字段：

bigquery-public-data

5. 设置数据集字段：

google_trends

6. 设置表格字段：

top_rising_terms

11. 选择创建代理。

快速入门应用的创建代理表单通过 gcloud 的 Python SDK 调用 CA API 的 create dataAgent 端点，并传入代理的系统指令和数据源。该应用使用 gcloud Python SDK 进行所有 CA API 调用。

12. 现在，让我们通过左侧主导航前往聊天页面。我们新创建的客服人员可以聊天。我们先添加提示/消息“你好，你怎么样？”，开始对话：
13. 现在，我们来简单了解一下此数据集：“此数据集是关于什么的？”

在聊天中发送提示（或消息）时会发生什么情况？该应用将您的消息作为载荷发送到 CA API 的 chat 端点。在幕后，CA API 会使用数据代理的系统指令和数据源中的信息作为提示的上下文，并将提示和上下文发送给 Gemini。然后，CA API 会将 Gemini 的回答以流式传输方式返回。

14. 再问一个问题，例如：
15. “数据集中有哪些 [输入州] 的位置？”
16. “Can you give me the data for the last 2 weeks for [City, State]?”
17. “你能创建可视化图表吗？”

您刚刚在自己的聊天应用中与数据代理进行了多轮对话，并使用了 BigQuery 数据。

3. 在 Looker 中对数据进行建模和探索

现在，我们将在 Looker 中对同一 BigQuery 数据进行建模和探索。

查询 BigQuery 人口普查数据

连接到更大的关系型数据集时会发生什么情况？首先，我们将创建一个新代理。

1. 返回到代理页面上的创建代理表单。
2. 设置显示名称字段：

BQ Census Agent

2. 设置系统指令字段：

You are really excited about census data, you love learning about the demographics in your area because you want to come up with marketing campaigns for your company

3. 选择 BigQuery 选项。
4. 设置项目字段：

bigquery-public-data

5. 设置数据集字段：

census_bureau_acs

6. 设置表格字段：

blockgroup_2018_5yr

2. 选择创建代理。
3. 向新创建的代理提出以下两个问题：
4. “您拥有哪些数据？”
5. “你能否向我展示数据预览”？

当您要求代理预览数据时，您会发现该表没有与位置相关联的人类可读信息，只有地理位置标识符 (geo_id)。

使用 Looker 对人口普查数据进行建模

现在，我们将使用 LookML 模型来定义 BigQuery 人口普查数据。我们将解决刚才看到的问题。

4. 登录 Looker 实例
5. 如需找到 ACS 人口统计数据块文件，请前往左侧主导航栏，选择开发，然后选择 marketplace_acs_census-v2。
6. 我们来看一下 Looker 视图。打开 imported_project 目录、acs_census-v2 目录和 geography 目录。
7. 最后，打开 cbsa.view 文件。
8. 在第 17 行，我们可以看到 LookML 正在创建派生表。换句话说，此代码通过联接两个 BigQuery 公开数据集（一个包含人口普查数据，另一个包含地理边界数据）来创建一个新的合并表。借助 LookML，我们可以通过创建持久派生表来查询多个数据集，从而实现联接。

永久性派生表 (PDT) 是由 Looker 创建并存储在数据库（在本例中为 BigQuery）中的表。它是复杂查询的具体化视图。Looker 可以更高效地查询预计算的 PDT，从而提高性能并缩短查询时间，而无需在每次用户请求报告时都运行相同的耗时查询。

此外，联接是在可版本化的代码 (LookML) 中定义的，而不是在系统指令中定义的，这使得代理开发更具可伸缩性。借助 LookML，您可以围绕数据定义特定的假设和限制，以便在用户通过数据代理与数据对话时为他们提供支持。

探索 Looker 建模的人口普查数据

我们来在探索中运行一个快速查询，以演示我们有一个集中式数据源可供查询。

9. 在左侧主导航菜单中，依次选择探索、人口普查数据块和州和县。
10. 依次选择衡量指标教育 > 副学士学位。
11. 选择以下维度：
12. 地理位置 > 街区组
13. 地理位置 > 县 > 县名称
14. 地理位置 > 省/市/自治区 > 省/市/自治区。
15. 运行查询（右上角），您现在会看到这些地理位置 ID（称为“街区组”）已与人类可读的字符串相关联。
16. 打开可视化标签页，您将在地图中看到这些数据。

4. 试用 Looker 的聊天应用

现在，我们来为 Looker 创建数据代理。

1. 前往快速入门应用的代理页面上的创建代理表单：
2. 设置显示名称字段：

Cartoon character data analyst

2. 设置系统指令字段：

You are [fill in your favorite cartoon character, Bugs Bunny is a favorite]. Answer questions like that cartoon character

3. 选择 Looker 选项。
4. 将 Url 字段设置为 Looker 实例的网址：“https://...”
5. 设置模型字段：

data_block_acs_bigquery

6. 设置 Explore 字段：

cbsa

7. 选择创建代理。
8. 前往聊天页面，然后选择新创建的代理。
9. 我们先添加提示/消息“你好，你怎么样？”，开始对话：
10. 我们来让代理描述一下数据集：“您有哪些可用数据？”
11. 我们再问几个问题：
12. “纽约哪个县的人口最多？”
13. “那么，人均高中毕业生人数最多的国家/地区是哪个？”
14. “你能告诉我各州的人口性别分布情况吗？”
15. “我想查看人口最多的前 10 个州的条形图。”

您是否在对话中看到了该条形图可视化图表？CA API 向应用发送了一条包含 Vega 图表规范的消息。Vega 图表规范包含可视化图表的数据和配置（例如颜色、轴、图表类型等）。借助该规范，Streamlit 应用可将其呈现为交互式 Vega 图表，供您查看和互动。借助 CA API，您不仅可以查询数据，还可以通过数据代理直观呈现数据，方法是生成标准的可视化配置，以便轻松实现可视化。

5. 快速入门应用还能做什么？

您现在可以：

• 在本地设置聊天应用
• 创建了 BigQuery 数据代理和 Looker 数据代理
• 与数据智能体进行对话
• 了解了 Looker 语义模型作为聊天上下文的优势

我们来试用一下快速入门应用的其他功能：

1. 重新加载快速入门应用的网页，然后前往聊天页面。
2. 您可以查看与 BigQuery 和 Looker 代理的所有过往对话，以及其中的所有相应消息。应用的前端不会存储过往对话或消息，而是从 CA API 中提取它们。

CA API 提供了用于所有过往对话及其消息的端点。应用从 CA API 的列出对话端点中提取过往对话。然后，应用会从列出消息端点提取对话的所有历史消息。当您向对话发送消息时，CA API 可以将消息与对话相关联，从而将对话中的所有历史消息作为上下文，以便进行更有用的多轮对话。

3. 现在，前往代理页面，然后从列表中选择您的 Looker 代理。
4. 您可以更新代理的配置，也可以根据需要删除代理。应用的前端中不存储任何代理。

应用调用 CA API 提供的端点来列出、创建、更新和删除代理。该应用利用 CA API 存储和管理其代理。CA API 还提供了针对代理的其他操作！

6. 可选挑战和进一步探索

如果您愿意，可以借此机会熟悉对话式分析和快速入门应用。或者，您可以挑战一下自己，修改快速入门应用。您可以尝试以下建议和挑战，也可以直接跳到最后一部分。

详细了解 CA API 和快速入门应用

• 详细了解用于控制智能体行为的深入系统指令。
• 设置另一个指向新 BigQuery 数据集的数据代理。
• 在 Looker 实例中安装新的 Looker 模块，创建代理，并将其指向新的 Looker 数据集。

快速入门应用修改挑战

• 您熟悉 Looker 嵌入吗？如果是，请尝试在快速入门应用中嵌入 Looker 信息中心。考虑使用 Streamlit 的 iframe 组件。
• 找到包含视频网址的公开数据集，并更新应用的聊天渲染逻辑，以在聊天中显示视频。

7. 总结和要点

本测验到此结束！您已使用 Conversational Analytics API 构建了一个聊天应用、创建了数据代理，并与数据进行了对话。我们来回顾一些关键功能和概念！

对话分析功能

我们介绍了许多对话式分析功能，例如：

• 创建、更新、列出、获取和删除数据代理。
• 将数据代理指向 BigQuery 或 Looker 作为数据源。
• 创建、列出和获取对话及其各自的消息。
• 生成 Vega 图表规范，以便在对话中实现沉浸式可视化。
• 将对话中的过往消息用作未来消息的有用上下文。

将 Looker 与 CA API 搭配使用的优势

Looker 可对数据进行集中式、可测试且可管控的语义建模。Looker 与对话式分析相结合，提供了一种可扩缩的方式来为数据代理提供上下文。

后续操作

• 如需了解更多指南、功能和使用情形，请参阅对话分析文档。
• 及时了解并贡献于快速入门应用代码库。