此页面由 Cloud Translation API 翻译。

通过数据分析智能体获取数据分析

数据洞见代理是 Made by Google 的代理。它可让您从 BigQuery 数据中获取数据洞见。借助“数据洞见”代理，您无需预先了解 SQL。这样，您就可以根据数据做出明智的业务决策，并让数据分析师腾出时间专注于更复杂的任务。

本页面介绍了 Google Cloud 项目管理员如何使用 Google Cloud 控制台和 REST API 授权、创建和部署 Data Insights 代理。此页面还介绍了最终用户如何使用代理。

概览

数据洞见代理旨在执行以下操作：

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

您可以向数据分析代理提出的查询示例

以下是一些您可以向数据洞见代理提出的查询示例：

数据汇总和可视化：
- “今年第 2 季度拉美区域的销售额与去年第 2 季度相比如何？”
- “绘制一个条形图，显示该区域排名前 5 的每个国家/地区的比较情况。”
趋势分析：
- “过去 6 个月内，按位置划分的出站通话量有何变化？”
- “分析里斯本 3 星级以上酒店的预订模式”
数据挖掘：
- “客户购买商品时，哪些因素与总销售价值相关？给我一张显示相关性的热图。”
分析和报告：
- “总结‘业务机会’表和‘客户’表，并创建一份简短的报告，突出显示所有关键趋势。”

准备工作

如需开始在 Gemini Enterprise 中使用“数据分析”代理，请按以下步骤操作：

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

授予对 BigQuery 数据的访问权限

如需允许数据洞见代理查看和查询 BigQuery 数据，请向代理的用户授予 Identity and Access Management (IAM) 角色：

工作流

设置和使用“数据洞见”代理的总体工作流程如下：

获取授权详细信息

请按照以下步骤设置授权。您获取的详细信息用于授权数据洞察代理连接到 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：TOKEN_URI
客户端密钥：CLIENT_SECRET

使用 Google Cloud 控制台设置代理

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

授权并创建代理实例

按照以下步骤授权并创建 Data Insights 代理实例：

在 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 \
```
点击创建。

Data Insights 代理实例会显示在代理列表中。
如需开始使用代理，请等待直到代理状态列中显示您的实例处于已启用状态。

使用 REST API 设置代理

本部分介绍了如何使用 REST API 授权、创建和部署 Data Insights 代理实例。

为代理授权

以管理员身份在 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": "TOKEN_URI"
}
}'

替换以下内容：

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

响应

您应该会收到类似以下内容的 JSON 响应。请记下 AUTHORIZATION_RESOURCE_NAME，您必须使用该值来创建数据洞见代理。AUTHORIZATION_RESOURCE_NAME 末尾的唯一 ID 是 AUTHORIZATION_ID。

{
 "name": "AUTHORIZATION_RESOURCE_NAME",
 "serverSideOauth2": {
   "clientId": "CLIENT_ID",
   "clientSecret": "CLIENT_SECRET",
   "tokenUri": "TOKEN_URI",
   "authorizationUri": "AUTHORIZATION_URI"
 }
}

创建代理实例

作为 Google Cloud 项目管理员，您可以创建数据洞见代理实例。这需要您提供项目 ID 和数据集 ID，以便代理查询您所需的 BigQuery 数据。

REST

以下示例展示了如何使用 agents.create 方法创建 Data Insights 代理实例。如需了解可添加到此示例中的高级字段，请参阅为代理添加高级配置。

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：Data Insights 代理实例的名称。
AGENT_ICON_URI：一个可选字段，用于提供代理的图标 URI。
AGENT_DESCRIPTION：Data Insights 代理实例的说明，用于指明代理的用途或其 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，则表示部署正在进行中。

添加或修改用户及其权限

按照以下步骤，向 Data Insights 代理实例添加或修改主账号，并为其分配特定的 Identity and Access Management (IAM) 角色：

控制台

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

前往 Gemini Enterprise
选择包含 Data Insights 代理实例的应用。
在菜单中，点击代理。

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

默认情况下，新创建的代理不包含任何用户。
在获得许可的用户表格中，点击添加用户。
从可用列表中选择会员类型。
根据成员的身份类型输入相应信息，并分配一个或多个角色。
- 对于用户、群组或服务账号，成员字符串是电子邮件地址。
- 对于网域，成员字符串是有效的域名。
- 对于主账号，成员字符串是有效的主账号。例如 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
选择包含 Data Insights 代理实例的应用。
在菜单中，点击代理。

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

使用代理

按照以下步骤操作，即可使用代理获取数据洞见：

应用

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