在 Firestore Studio 中测试 QueryData

本文档介绍了如何测试 QueryData 并更新上下文集文件。您可以测试 QueryData 从自然语言问题生成与 MongoDB 兼容的查询语言 (MQL) 查询的能力。如果生成的查询不准确，您可以更新上下文集文件。

如需了解上下文集，请参阅上下文集概览。

准备工作

确保已创建上下文集，并且上下文集文件已上传到 QueryData 代理。如需了解详情，请参阅在 Firestore Studio 中管理上下文集。

如需下载、更新和上传上下文集文件，请确保 IAM 用户对项目拥有 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色。如需了解详情，请参阅上下文集权限。

测试 QueryData

如需测试 QueryData，请执行以下步骤：

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

    转到 Firestore

  2. 选择您向其添加了上下文集的数据库。仅支持与 MongoDB 兼容的 Firestore。

  3. 在导航菜单中，点击 Firestore Studio 。

  4. 在探索器窗格中，点击您正在使用的上下文集旁边的查看操作。

  5. 点击测试上下文集 。

  6. 在查询编辑器中，点击生成查询 以打开帮我编码 面板。

  7. 在编辑器中输入自然语言问题以生成 MQL 查询，然后点击生成 。

  8. 查看 MQL 查询的准确性。

下载和更新上下文集

如果您对为自然语言问题生成的 MQL 查询不满意，请下载现有的上下文集文件。然后，您可以查看和更新查询模板，并将更新后的上下文文件重新上传到代理。

如需下载和更新上下文集，请执行以下步骤：

  1. 在探索器窗格 中，点击查看操作 。
  2. 点击下载上下文文件 。
  3. 按照使用上下文工程智能体构建上下文集中的步骤，使用其他查询对更新上下文。
  4. 在探索器窗格中，点击您正在使用的上下文集旁边的查看操作。
  5. 点击修改上下文集 。
  6. 在上传上下文集文件 部分中，点击浏览 ，然后选择更新后的上下文集文件。
  7. 点击保存 以更新上下文集。

如果您对回答的准确性感到满意，可以使用 QueryData 端点将应用连接到上下文集。

查找上下文集 ID

如需将数据应用连接到 QueryData 代理，您需要上下文集的 ID。

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

    转到 Firestore

  2. 选择您向其添加了上下文集的数据库。

  3. 在导航菜单中，点击 Firestore Studio 。

  4. 在探索器窗格中，点击您正在使用的上下文集旁边的查看操作。

  5. 点击修改上下文集 。

  6. 记下上下文集 ID 中的上下文 ID。上下文集 ID 的格式类似于 projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates。

将 QueryData 连接到应用

在 QueryData 方法调用中设置上下文集 ID，以便为数据库数据源（例如 AlloyDB、Spanner、Cloud SQL、Cloud SQL for PostgreSQL 和 Firestore）提供编写的上下文。如需了解详情，请参阅为数据库数据源定义数据代理上下文。

测试上下文集后，您可以在 QueryData 调用中引用数据库数据源。

包含编写的上下文的 QueryData 请求示例

以下示例展示了使用 firestore_reference（与 MongoDB 兼容的 Firestore）数据源的 QueryData 请求。agent_context_reference.context_set_id 字段用于链接到存储在数据库中的预先编写的上下文。

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans?",
  "context": {
    "datasource_references": [
      {
        "firestore_reference": {
          "database_reference": {
            "project_id": "context-set-project",
            "region": "us-central1",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-central1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

请求正文包含以下字段：

  • prompt：最终用户的自然语言问题。
  • context：包含有关数据源的信息。
    • datasource_references：指定数据源类型。
      • firestore_reference：查询数据库时是必需的。此字段会根据您查询的数据库而变化。
        • database_reference：指定与数据库实例相关的信息。
          • project_id：数据库的项目 ID。
          • region：数据库的区域。
          • database_id：数据库的 ID。
        • agent_context_reference：链接到数据库中编写的上下文。
          • context_set_id：存储在数据库中的上下文的完整上下文集 ID。例如，projects/context-set-project/locations/us-central1/contextSets/bdf_gsql_gemini_all_templates。
  • generationOptions：配置要生成的输出类型。
    • generate_query_result：设置为 true 可生成并返回查询结果。
    • generate_natural_language_answer：可选。如果设置为 true，则生成自然语言回答。
    • generate_explanation：可选。如果设置为 true，则生成 MQL 查询的说明。
    • generate_disambiguation_question：可选。如果设置为 true，则在查询不明确时生成消除歧义问题。

QueryData 响应示例

以下是 QueryData 调用的成功响应示例：

{
  "generated_query": "// Count the number of accounts in Prague that are eligible for loans\ndb.loans.aggregate([\n  // 1. Filter loans in the Prague region\n  { \n    $match: { \"district.name\": \"Prague\" } \n  },\n  // 2. Group by account_id to get distinct values, and count them\n  { \n    $group: { \n      _id: null, \n      uniqueAccounts: { $addToSet: \"$account_id\" } \n    } \n  },\n  // 3. Project the size of the unique accounts array\n  { \n    $project: { \n      _id: 0,\n      distinct_account_count: { $size: \"$uniqueAccounts\" } \n    } \n  }\n]);",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to filter the documents in the loans collection to only give me those in the Prague region. Then I need to group the loans by account ID to get distinct values and count them. Finally, I need to project the size of the array of unique accounts.",
  "query_result": {
    "columns": [
      {
        "name": "distinct_account_count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

后续步骤