创建数据代理

借助对话式数据代理，您可以使用自然语言界面与数据库数据进行交互。通过构建这些代理，您可以帮助用户“与数据对话”，从而从运营数据库中获取洞见，而无需编写复杂的 SQL 查询。

从宏观层面来看，数据代理是角色、一组数据源的组合，并且可以访问一组对其用途至关重要的业务知识。

对于应用开发者，这些代理具有以下优势：

  • 准确率高：通过使用编写的上下文，您可以针对特定的业务问题实现高 准确率。编写的上下文是主要的 关键因素，代理创建者可以使用它来提高准确率。它包括架构说明、系统指令和结构化上下文，可提供有关预期数据库查询的额外信息。
  • 降低复杂性：代理会将自然语言转换为 SQL 查询、执行，甚至数据汇总或可视化。
  • 灵活性：您可以为个人测试起草代理，也可以发布代理，以便项目中的其他用户或通过 API 以编程方式使用这些代理。

准备工作

  1. 验证是否已为您的 Google Cloud 项目启用结算功能。

  2. 启用 Spanner、Data Analytics API with Gemini 和 Gemini for Google Cloud APIs。

    启用 API 所需的角色

    如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予 角色。

    启用 API

所需角色

如需使用数据代理，您必须拥有以下 对话式分析 API Identity and Access Management (IAM) 角色之一：

  • 使用 QueryData 方法从受支持的数据库来源查询数据：项目级 Gemini Data Analytics Data Query User (roles/geminidataanalytics.queryDataUser)。
  • 在项目中创建、修改、共享和删除所有数据代理：项目级 Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner)。
  • 在项目中创建自己的数据代理：项目级 Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator)。此角色会自动授予您对所创建数据代理的 Gemini Data Analytics Data Agent Owner 角色。
  • 查看和修改项目中的所有数据代理：项目级 Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)。
  • 查看项目中的所有数据代理：项目级 Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer)。

此外，您还必须拥有以下角色才能创建或修改数据代理：

  • 已添加到集群的 IAM 用户或服务帐号。如需了解详情， 请参阅 应用 IAM 角色。
  • 在项目级授予 IAM 用户的 spanner.databaseReader 角色。如需了解详情，请参阅 为项目添加 IAM 政策绑定。
  • 在项目级授予 IAM 用户所需数据库的角色和权限。如需了解详情，请参阅 授予角色和权限。

如需使用 Spanner 资源，请参阅 Spanner 角色和权限。

创建数据代理

以下部分介绍了如何创建数据代理。 创建代理后，您可以修改其设置。

配置基本信息

  1. 在 Google Cloud 控制台中，前往 Spanner 页面。

    转到 Spanner

  2. 从列表中选择一个实例，然后选择一个数据库。

  3. 在导航菜单中，点击代理 。

  4. 点击代理 标签页。

  5. 选择一个数据库，然后使用您的 IAM 账号登录。

  6. 点击新建代理 。系统会打开新建代理 页面。

  7. 在编辑器 部分的代理名称 字段中，输入数据代理的 描述性名称，例如 Q4 sales data 或 User activity logs。

  8. 在代理说明 字段中，输入数据代理的说明。好的说明应解释代理的作用、使用的数据，并帮助您确定这是否是适合用于对话的数据代理，例如 What are the top 10 selling products in Q2?。

  9. 在知识来源 部分，点击添加来源 。系统会打开添加数据 页面。

  10. 选择代理在回答问题时将重点关注的表。如需查看其他 知识来源，请依次选择 显示更多。

  11. 点击添加 。系统会重新打开“新建代理”页面。

自定义表和字段说明

为了提高对话式数据代理的准确性，您可以选择性地提供额外的表元数据。只有数据代理会使用此元数据，它不会影响源表。您可以添加以下元数据：

  • 架构说明： 为表和列添加说明，以帮助代理了解您的数据。如果您不添加说明，代理将使用数据定义中的架构说明。

添加表和字段说明时，请遵循以下最佳实践：

  • 将说明添加到数据定义，而不仅仅是添加到数据代理定义。这样可确保其他代理也能受益于这些说明。
  • 如需为数据代理添加合适的说明以帮助其了解您的数据，请为特定代理添加说明。验证说明是否具有预期效果后，您可以决定是否在数据定义中添加该说明。

如需配置表和字段说明，请按以下步骤操作：

  1. 在代理目录 标签页中，打开要自定义的代理。
  2. 点击修改代理 。
  3. 在知识来源 中，找到要自定义的表，然后点击自定义 。
  4. 输入表说明。
  5. 如需修改任何字段说明，请点击相应字段旁边的 修改 。系统会打开修改字段 窗格。
    1. 在 ID 字段中，输入字段说明。
    2. 如需保存字段说明，请点击更新 。
  6. 如需保存说明和字段更新，请点击更新 。系统会重新打开“新建代理”页面。
  7. 针对要自定义的每个表重复上述步骤。

为数据代理添加标签

在代理设置 部分，您可以 创建标签来整理资源。 Google Cloud 标签是键值对 ，可用于将相关对象组合在一起或者与其他 Google Cloud 资源组合在一起。

  1. 在代理目录 标签页中，打开要添加标签的代理。
  2. 点击修改代理 。
  3. 在代理设置 部分，点击添加标签 。系统会打开管理标签 窗格。
  4. 点击添加标签 。
  5. 在键 和值 字段中，输入标签的键值对。
  6. 如果您想添加更多标签，请再次点击添加标签 。
  7. 如需删除标签，请点击“删除”。
  8. 完成后，点击添加 。系统会重新打开“新建代理”页面。

请继续阅读下一部分，了解如何将代理置于草稿模式或发布代理。

预览并发布代理

  1. 在预览 部分的提问 字段中，输入一个示例问题，然后按 Enter 。

    如需验证数据代理是否返回了您预期的数据，请检查代理的回答。如果回答不是您预期的内容，请在编辑器 部分中更改设置，以优化数据代理配置，直到获得令人满意的回答。您可以继续测试和修改代理，以优化代理的结果。

  2. 点击保存 。

  3. 如需将数据代理置于草稿模式（您可以稍后重新修改）， 请点击 返回 ，返回到 代理目录 页面。由于您的代理现在处于草稿模式，因此它会显示在代理目录 标签页的我的草稿代理 部分中。

    如需发布代理，请停留在代理创建页面，然后继续执行下一步。

  4. 如需发布数据代理并使其可在项目中供使用，请点击发布 。发布代理后，有权访问同一数据库表的其他用户可以查看您的代理并与之对话，从而受益于您创建的指令和上下文。

    您可以使用 数据代理通过控制台中的代理页面创建对话。 Google Cloud 您还可以使用对话式分析 API 构建自己的界面，与数据代理对话。

  5. 可选：在您的代理已发布 对话框中，点击共享 以与其他用户共享数据代理。

    1. 在共享权限 窗格中，点击添加主账号 。
    2. 在新的主账号 字段中，输入一个或多个主账号。
    3. 点击选择角色 列表。
    4. 在角色 列表中，选择以下角色之一：
      • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser)：授予与数据代理对话的权限。
      • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)：授予修改数据代理的权限。
      • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer)：授予查看数据代理的权限。

  6. 点击保存 。

  7. 如需返回“新建代理”页面，请点击关闭 。保存或发布代理后，您可以在代理目录 中看到该代理。

管理数据代理

您可以在代理目录 标签页中找到现有代理，该标签页包含三个部分：

  • 我的代理：您创建和发布的所有代理的列表。您可以修改已发布的代理并与他人共享。
  • 我的草稿代理：您尚未发布的代理。您无法共享草稿代理。
  • 您组织中的其他人分享的代理：其他人创建并与您 共享的代理。如果其他人授予您权限，您可以修改这些共享的代理。

修改数据代理

如需修改数据代理，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，前往 Spanner 页面。

    转到 Spanner

  2. 从列表中选择一个实例，然后选择一个数据库。

  3. 在导航菜单中，点击代理 。

  4. 使用 Identity and Access Management (IAM) 身份验证登录代理 。

  5. 点击代理目录 标签页。

  6. 找到要修改的数据代理的代理卡片。

  7. 如需在代理编辑器中打开数据代理，请依次点击 打开操作 和代理卡片上的修改 。

  8. 根据需要修改数据代理的配置。

  9. 如需保存更改但不发布，请点击保存 。

  10. 如需发布更改，请点击发布 。在共享 对话框中，您可以与其他用户共享代理，也可以点击取消 。

  11. 如需返回代理 窗格，请点击 返回 。

共享数据代理

如需共享已发布的数据代理，请按以下步骤操作。您无法共享草稿代理。

  1. 在 Google Cloud 控制台中，前往 Spanner 页面。

    转到 Spanner

  2. 从列表中选择一个实例，然后选择一个数据库。

  3. 在导航菜单中，点击代理 。

  4. 使用 Identity and Access Management (IAM) 身份验证登录代理 。

  5. 点击代理目录 标签页。

  6. 找到要修改的数据代理的代理卡片。

  7. 如需在代理编辑器中打开数据代理，请依次点击 打开 操作 > 代理卡片上的修改 。

  8. 如需与其他用户共享数据代理，请点击共享 。

  9. 在共享权限 窗格中，点击添加主账号 。

  10. 在添加主账号 字段中，输入一个或多个主账号。

  11. 点击选择角色 。

  12. 在角色 列表中，选择以下角色之一：

    • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser)：授予与数据代理对话的权限。
    • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)：授予修改数据代理的权限。
    • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer)：授予查看数据代理的权限。

  13. 点击保存 。

  14. 如需返回代理修改页面，请点击关闭。

  15. 如需返回代理 窗格，请点击 返回 。

删除数据代理

  1. 在 Google Cloud 控制台中，前往 Spanner 页面。

    转到 Spanner

  2. 从列表中选择一个实例，然后选择一个数据库。

  3. 在导航菜单中，点击代理 。

  4. 使用 Identity and Access Management (IAM) 身份验证登录代理 。

  5. 选择代理目录 标签页。

  6. 在代理目录 标签页的代理 部分中，找到要删除的数据代理的代理卡片。

  7. 依次点击 打开操作 > 删除。

  8. 在删除代理？ 对话框中，点击删除 。删除代理会从项目中永久移除该代理。

    删除代理后，现有对话将以“只能查看”模式显示。您无法向已删除的代理提出新问题。

位置

对话式分析在全球范围内运行，因此您无法选择要使用的区域。

后续步骤