使用数据分析智能体获取数据洞见

数据分析智能体是一款由 Google 打造的 AI 智能体。它可让您从 BigQuery 数据中获取数据分析。借助数据分析智能体，您无需预先了解 SQL。这能帮助您制定出有充分数据依据的明智业务决策，同时解放数据分析师，使其能专注于更复杂的任务。

本页面介绍了 Google Cloud 项目管理员如何使用Google Cloud 控制台和 REST API 授权、创建和部署数据分析智能体。此页面还介绍了最终用户如何使用智能体。

概览

数据分析智能体旨在执行以下操作：

了解用户意图：分析关联数据源的上下文和用户的自然语言查询，以了解用户的目标
生成 SQL：基于此理解，将用户的问题转换为语法和语义均正确的 SQL 查询。
检索数据：然后，它会执行生成的 SQL，直接从已关联的数据源（即 BigQuery 数据集）中提取相关数据。
提供数据分析：以图表和表格等可视化形式或基于文本的摘要来呈现检索到的数据，从而解答用户的查询。

您可以向数据分析智能体提出的查询示例

以下是一些您可以向数据分析智能体提出的查询示例：

数据聚合与可视化：
- “今年第二季度拉美地区的销售额与去年第二季度相比如何？”
- “绘制一个条形图，展示该地区排名前 5 的国家/地区的对比情况。”
趋势分析：
- “过去 6 个月内，按地点细分的出站通话量有何变化？”
- “分析里斯本评级高于 3 星的酒店的预订模式”
数据挖掘：
- “当客户购物时，哪些因素与总销售额相关？给我一张展示这种关系的热图。”
分析和报告：
- “汇总商机和客户表，并创建一份简要报告来重点说明所有关键趋势。”

准备工作

如需开始在 Gemini Enterprise 中使用数据分析智能体，请按以下步骤操作：

按照相关说明开始使用 Gemini Enterprise。
按照说明获取 Gemini Enterprise 许可。
如需访问数据分析智能体，请与您的 Google 客户经理联系。
准备 BigQuery 数据。如需了解详情，请参阅 BigQuery 文档。
为了充分发挥智能体的作用，请了解 BigQuery 数据集中的数据。

授予对 BigQuery 数据的访问权限

如需允许数据分析智能体查看和查询 BigQuery 数据，请向智能体的用户授予 Identity and Access Management (IAM) 角色：

工作流

设置和使用数据分析智能体的总体工作流程如下：

获取授权详细信息。
使用 Google Cloud 控制台或使用 REST API 设置智能体。
添加或修改用户及其权限
更改智能体实例的工作状态
使用智能体

获取授权详细信息

请按照以下步骤设置授权。您获取的详细信息用于授权数据洞察智能体连接到 BigQuery 数据。

在 Google Cloud 控制台中，前往 API 和服务中的凭证页面。

转到“凭据”页面
选择 Google Cloud 包含您希望智能体查询的 BigQuery 数据集的项目。
点击创建凭据并选择 OAuth 客户端 ID。
在应用类型中，选择 Web 应用。
在已获授权的重定向 URI 部分中，添加以下 URI：
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
点击创建。
在 OAuth 客户端已创建面板中，点击下载 JSON。下载的 JSON 文件包含所选Google Cloud 项目的以下详细信息。您需要以下详细信息才能创建授权资源：
- 客户端 ID：CLIENT_ID
- 授权 URI：
```
https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
```
- 令牌 URI：https://oauth2.googleapis.com/token
- 客户端密钥：CLIENT_SECRET

使用 Google Cloud 控制台设置智能体

本部分介绍如何使用 Google Cloud 控制台授权、创建和部署数据分析智能体的实例。您还可以添加用户权限，以确定哪些人可以访问已创建的智能体。

授权并创建智能体实例

按照以下步骤授权并创建数据分析智能体实例：

在 Google Cloud 控制台中，前往 Gemini Enterprise。

前往 Gemini Enterprise
选择要在其中创建智能体的应用。
在菜单中，点击智能体。

智能体页面会显示现有智能体。
点击添加智能体。
在创建智能体窗格中，点击数据智能体卡片中的创建。
在授权中，点击添加授权，然后输入授权详细信息。如需了解详情，请参阅获取授权。
点击完成。
点击下一步。
按如下方式配置智能体：
1. 输入智能体名称和说明。
2. 在 BigQuery 数据集中，点击浏览，然后执行以下操作之一：
  - 选择一个可用的数据集，然后点击选择。
  - 输入所需 BigQuery 数据集的路径，点击搜索，选择该数据集，然后选择选择。
3. 可选：点击显示更多可查看高级选项。
4. 选择正确的表访问权限选项。如果您想强制执行许可名单或屏蔽名单，请指定受限表的路径。
5. 可选：定义自然语言查询配置，以提供特定于自然语言到 SQL 或 Python 代码翻译的自定义设置。您还可以提供一个 SQL 示例，其中包含自然语言查询、其预期的 SQL 输出及其预期的响应。这有助于提高智能体的输出质量。
  - 架构说明：一个用于描述 BigQuery 数据集架构的自然语言字符串。
  - 自然语言查询到 SQL 的提示：将自然语言查询转换为 SQL 指令的提示。
  - 将自然语言查询转换为 Python 的提示：已转换为 Python 指令的自然语言查询。
6. 可选：添加从自然语言查询转换为 SQL 查询的示例：
  - 查询：必须转换为 SQL 查询的自然语言查询示例。例如，“加利福尼亚州客户的姓名和邮箱是什么”
  - 预期 SQL：一个字符串，用于说明与自然语言查询对应的示例 SQL 查询。例如，假设您有一个名为 customers 的 BigQuery 表。然后，您预期的 SQL 查询可以是 SELECT customer_name, email FROM customers WHERE state = 'California'。
  - 预期回答：一个字符串，通过执行预期 SQL 查询来提供查询的预期答案。例如：
```
Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \
```
点击创建。

数据分析智能体实例会显示在智能体列表中。
如需开始使用智能体，请等待直到智能体状态列中显示您的实例处于已启用状态。

使用 REST API 设置智能体

本部分介绍了如何使用 REST API 授权、创建和部署数据分析智能体实例。

为智能体授权

以管理员身份在 Gemini Enterprise 中创建授权资源。这样一来，数据分析智能体就可以访问 BigQuery 数据。

创建授权资源。

REST

以下示例展示了如何使用 authorizations.create 方法创建授权资源。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \
 -d '{
   "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID",
   "serverSideOauth2": {
     "clientId": "CLIENT_ID",
     "clientSecret": "CLIENT_SECRET",
     "authorizationUri": "AUTHORIZATION_URI",
     "tokenUri": "https://oauth2.googleapis.com/token"
}
}'

替换以下内容：

PROJECT_NUMBER：您的 Google Cloud 项目编号。
LOCATION：您的 Google Cloud 项目所在的位置。
AUTHORIZATION_ID：您必须提供的用于标识授权资源的 ID。
CLIENT_ID：您在上一步中获得的客户端 ID。
CLIENT_SECRET：您在上一步中获得的客户端密钥。
AUTHORIZATION_URI：您在上一步中获得的授权 URI。

响应

您应该会收到类似如下所示的 JSON 响应。请注意 AUTHORIZATION_RESOURCE_NAME，您必须使用它来创建数据分析智能体。AUTHORIZATION_RESOURCE_NAME 末尾的唯一 ID 是 AUTHORIZATION_ID。

{
 "name": "AUTHORIZATION_RESOURCE_NAME",
 "serverSideOauth2": {
   "clientId": "CLIENT_ID",
   "clientSecret": "CLIENT_SECRET",
   "tokenUri": "https://oauth2.googleapis.com/token",
   "authorizationUri": "AUTHORIZATION_URI"
 }
}

创建智能体实例

作为 Google Cloud 项目管理员，您可以创建数据分析智能体实例。这需要您提供项目 ID 和数据集 ID，以便智能体查询您指定的 BigQuery 数据。

REST

以下示例展示了如何使用 agents.create 方法创建数据分析智能体实例。如需了解可添加到此示例中的高级字段，请参阅为智能体添加高级配置。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

替换以下内容：

PROJECT_NUMBER：您的 Google Cloud 项目编号。
LOCATION：Gemini Enterprise 应用所在的位置。
APP_ID：应用的 ID。
AGENT_DISPLAY_NAME：数据分析智能体实例的名称。
AGENT_ICON_URI：一个可选字段，用于提供智能体的图标 URI。
AGENT_DESCRIPTION：数据分析智能体实例的说明，用于指明智能体的用途或其 BigQuery 数据源详细信息。
BIGQUERY_PROJECT_ID：包含 BigQuery 数据集的Google Cloud 项目的项目 ID。
BIGQUERY_DATASET_ID：包含要查询的数据的 BigQuery 数据集 ID。
AUTHORIZATION_RESOURCE_NAME：您在上一部分中获得的授权资源名称。

响应

您应该会收到类似如下所示的 JSON 响应。请记下 AGENT_RESOURCE_NAME，您必须使用它来部署数据分析智能体。AGENT_RESOURCE_NAME 末尾的唯一 ID 是 AGENT_ID。

{
  "name": "AGENT_RESOURCE_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "icon": {
    "uri": "AGENT_ICON_URI"
  },
  "createTime": "CREATION_TIME",
  "managedAgentDefinition": {
    "toolSettings": {
      "toolDescription": "AGENT_DISPLAY_NAME"
    },
    "deploymentInfo": {},
    "dataScienceAgentConfig": {
      "bqProjectId": "BIGQUERY_PROJECT_ID",
      "bqDatasetId": "BIGQUERY_DATASET_ID"
    }
  },
  "authorization_config": {
    "tool_authorizations" : [
      "AUTHORIZATION_RESOURCE_NAME"
    ]
  },
  "state": "CONFIGURED"
}

为智能体添加高级配置

您可以选择定义 nlQueryConfig 字段，以提供针对“自然语言到 SQL 或 Python 代码”这一转换过程的特定自定义设置。您还可以提供一个 SQL 示例，其中包含自然语言查询、其预期的 SQL 输出及其预期的响应。这有助于提高智能体的输出质量。以下代码段展示了如何配置这些高级字段：

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2pyPrompt": "NL_TO_PYTHON_INSTRUCTIONS",
    "nl2sqlExample": {
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    },
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

替换以下内容：

NL_TO_SQL_INSTRUCTIONS：已转换为 SQL 指令的自然语言查询。
NL_TO_PYTHON_INSTRUCTIONS：已转换为 Python 指令的自然语言查询。
EXAMPLE_NL_QUERY：必须转换为 SQL 查询的自然语言查询示例。例如，“加利福尼亚州客户的姓名和邮箱是什么”
EXPECTED_SQL_QUERY：一个字符串，用于说明与自然语言查询对应的示例 SQL 查询。例如，假设您有一个名为 customers 的 BigQuery 表。然后，您期望的 SQL 查询可以是“SELECT customer_name, email FROM customers WHERE state = 'California'”。

EXPECTED_SQL_RESPONSE：一个字符串，用于提供查询的预期答案和预期 SQL 查询。例如：

Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

NL_DESCRIPTION_OF_BQ_DATASET：一个用于描述 BigQuery 数据集架构的自然语言字符串。

部署实例

创建数据分析智能体实例后，作为管理员，您可以部署该实例，以便最终用户可以使用它。

REST

部署智能体。以下示例展示了如何使用 agents.deploy 方法部署创建的智能体。部署智能体是一项长时间运行的操作 (LRO)。
```
curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
 -d '{
   "name":"AGENT_RESOURCE_NAME"
 }'
```
替换以下内容：
- PROJECT_NUMBER：您的 Google Cloud 项目编号。
- AGENT_RESOURCE_NAME：您在上一部分中创建智能体时获得的智能体资源名称。
响应

您应该会收到类似如下所示的 JSON 响应。请记下 DEPLOY_OPERATION_NAME，您必须使用它来获取 LRO 的状态。
```
{
 "name": "DEPLOY_OPERATION_NAME",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.DeployAgentMetadata"
 }
}
```
获取部署操作的状态。以下示例展示了如何使用 operations.get 方法获取部署操作的状态。
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"
```
将 DEPLOY_OPERATION_NAME 替换为您在上一步中部署智能体时获得的 LRO 名称。

在响应中，如果 done 字段的值为 true，则表示部署已完成。如果 done 字段的值为 false，则表示部署正在进行中。

添加或修改用户及其权限

按照以下步骤，向数据分析智能体实例添加或修改主账号，并为其分配特定的 Identity and Access Management (IAM) 角色：

控制台

在 Google Cloud 控制台中，前往 Gemini Enterprise。

前往 Gemini Enterprise
选择包含数据分析智能体实例的应用。
在菜单中，点击智能体。

智能体页面会显示现有智能体。
点击要为其添加或修改用户的智能体。

默认情况下，新创建的智能体不包含任何用户。
在已获授权的用户表格中，点击添加用户。
从可用列表中选择会员类型。
根据成员类型输入其身份信息，并分配一个或多个角色。
- 对于用户、群组或服务账号，成员字符串是邮箱。
- 对于网域，成员字符串是有效的域名。
- 对于主账号，成员字符串是有效的主账号。例如 principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1。
- 对于主账号集，成员字符串是有效的主账号集。例如 principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1。
- 对于网域和主账号集，这些网域和主账号集内的所有用户身份和群组都会被分配相同的角色。如需安全访问智能体，请选择各个群组和受控网域或主账号集，并为其分配最低权限角色。
点击保存。

IAM 政策会随之更新，用户也将被添加到已获授权的用户列表中。
如需修改已分配的权限，请点击操作，选择修改，然后执行以下任一操作：
- 修改分配的角色。
- 添加其他角色。
- 点击删除以移除角色。您必须为用户分配至少一个角色。

更改实例的工作状态

创建数据分析智能体实例后，系统默认会启用该智能体。您可以按照以下步骤将其工作状态更改为已停用、已暂停、已启用或已删除：

控制台

在 Google Cloud 控制台中，前往 Gemini Enterprise。

前往 Gemini Enterprise
选择包含数据分析智能体实例的应用。
在菜单中，点击智能体。

智能体页面会显示现有智能体。
点击智能体的操作，然后选择以下选项之一：
- 暂停：使智能体暂时无法使用。不过，拥有任意程度的智能体访问权限的用户仍可看到该智能体。
- 停用：使智能体对所有用户（创建者除外）不可用。
- 启用：使智能体可供所有拥有任意程度的智能体访问权限的用户使用。
- 删除：用于删除智能体实例。

使用智能体

按照以下步骤操作，即可使用智能体获取数据分析：

应用

在应用导航菜单中，点击智能体。
点击查看所有智能体。
选择您的数据分析智能体实例。
如果您的智能体需要额外授权，请点击授权，然后提供授权详细信息。
点击 添加文件，以将文件作为智能体可处理的其他数据源。
点击来源，选择智能体必须包含的来源，以便提供最相关的数据分析。
输入问题或提示，然后按 Enter 键或点击提交。

使用数据分析智能体获取数据洞见 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

您可以向数据分析智能体提出的查询示例

准备工作

授予对 BigQuery 数据的访问权限

工作流

获取授权详细信息

使用 Google Cloud 控制台设置智能体

授权并创建智能体实例

使用 REST API 设置智能体

为智能体授权

REST

响应

创建智能体实例

REST

响应

为智能体添加高级配置

部署实例

REST

响应

添加或修改用户及其权限

控制台

更改实例的工作状态

控制台

使用智能体

应用

使用数据分析智能体获取数据洞见