创建数据代理

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

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

对于应用开发者，这些代理可带来以下好处：

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

准备工作

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

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

    启用 API 所需的角色

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

    启用 API

所需的角色

如需使用数据代理，您必须拥有以下 Conversational Analytics 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)。

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

在管理对 Cloud SQL for MySQL 数据库资源的访问权限时，请考虑以下权限层级：

  • Google Cloud IAM：控制对数据库实例（作为云资源）的访问权限。这包括连接、管理实例和执行 SQL 查询的权限，例如使用 executeSql 权限。
  • 数据库权限：控制对数据库中对象（如表、视图和架构）的访问权限。这些权限通过 GRANT 等 SQL 命令以及特定于数据库的用户和角色系统进行管理。

对于 Cloud SQL for MySQL，您需要具有适当的 Cloud SQL IAM 角色才能连接到实例并获得发送查询的授权。如需与表和视图等对象互动，连接的数据库用户必须具有使用 Cloud SQL for MySQL GRANT 系统授予的必要权限。如需了解详情，请参阅关于 Cloud SQL for MySQL 用户。如果代理使用服务账号，您可以为其分配数据库角色。例如，请参阅使用 IAM 数据库身份验证管理用户。

创建数据代理

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

配置基本信息

  1. 在 Google Cloud 控制台中，前往 Cloud SQL for MySQL 页面。

    前往 Cloud SQL

  2. 从列表中选择一个实例。

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

  4. 点击代理标签页。

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

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

  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 键。

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

  2. 点击保存。

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

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

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

    您可以使用 Google Cloud 控制台中的代理页面与数据代理创建对话。您还可以使用 Conversational Analytics 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 控制台中，前往 Cloud SQL for MySQL 页面。

    前往 Cloud SQL

  2. 从列表中选择一个实例。

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

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

  5. 点击智能体目录标签页。

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

  7. 如需在智能体编辑器中打开数据智能体，请点击 打开操作，然后点击智能体卡片上的修改。

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

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

  10. 如需发布更改，请点击发布。在分享对话框中，您可以选择与他人分享代理，也可以点击取消。

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

共享数据代理

请按照以下步骤分享已发布的数据智能体。您无法共享草稿代理。

  1. 在 Google Cloud 控制台中，前往 Cloud SQL for MySQL 页面。

    前往 Cloud SQL

  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 控制台中，前往 Cloud SQL for MySQL 页面。

    前往 Cloud SQL

  2. 从列表中选择一个实例。

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

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

  5. 选择智能体目录标签页。

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

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

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

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

位置

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

后续步骤