测试 QueryData

本文档介绍了如何通过调用 对话式分析 API 的 QueryData 方法来测试 Spanner Graph 的 QueryData,以及如何更新上下文集文件。您可以测试 QueryData 根据自然语言问题生成 Graph Query Language (GQL) 查询的能力。如果生成的 GQL 查询不准确,您可以更新上下文集文件。

如需了解 Spanner Graph 的上下文集,请参阅上下文集概览。

准备工作

查找现有上下文集 ID

如需使用上下文集测试 QueryData,或将数据应用连接到 QueryData,您需要上下文集 ID。

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

    转到 Spanner

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

  3. 在导航菜单中,点击 Spanner Studio。

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

  5. 点击修改上下文集。

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

使用 HTTP POST 测试 QueryData

如需测试 Spanner Graph 的 QueryData,请发送包含 graph_ids 字段和上下文集 ID 的 QueryData HTTP POST 请求:

  1. 创建一个名为 request.json 的文件,其中包含以下内容:

    {
      "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
      "context": {
        "datasource_references": {
          "spanner_reference": {
            "database_reference": {
              "engine": "GOOGLE_SQL",
              "project_id": "PROJECT_ID",
              "instance_id": "INSTANCE_ID",
              "database_id": "DATABASE_ID",
              "graph_ids": ["FinGraph"]
            },
            "agent_context_reference": {
              "context_set_id": "CONTEXT_SET_ID"
            }
          }
        }
      },
      "generation_options": {
        "generate_query_result": true,
        "generate_natural_language_answer": true,
        "generate_explanation": true
      }
    }

    替换以下内容:

    • PROJECT_ID:您的 Google Cloud 项目 ID。
    • INSTANCE_ID:您的 Spanner 实例 ID。
    • DATABASE_ID:您的 Spanner 数据库 ID。
    • CONTEXT_SET_ID:您在查找上下文集 ID 中记下的完整上下文集 ID。
  2. 发送请求:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "x-goog-user-project: PROJECT_ID" \
      "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \
      -d @request.json
    
  3. 在响应中,检查 generatedQuery 字段 (GRAPH FinGraph MATCH ...) 是否准确,并检查 queryResult 字段中返回的行。

如需测试其他问题,请更改 request.json 中的 prompt 值,然后再次发送请求。如需了解 QueryData 在没有编写上下文时的行为,请移除 agent_context_reference 对象。

如需检查 QueryData 是否使用了您的上下文集,请提出一个依赖于该上下文集的问题(例如“谁拥有 rainy day 账号?”),并比较使用和不使用 agent_context_reference 对象时的回答。如果未设置上下文,QueryData 可能会对 'rainy day' 进行过滤,并且不返回任何行。设置上下文后,它会过滤 'Rainy Day Fund' 并返回 Dana。

下载并更新现有上下文集

如果测试回答表明,针对自然语言问题生成的 GQL 查询需要改进,请下载现有的上下文集文件。然后,您可以查看和更新 GQL 查询模板、分面或值搜索,并将更新后的上下文集文件上传到上下文集。

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

  1. 在探索器窗格中,点击上下文集旁边的查看操作。
  2. 点击下载上下文文件。
  3. 按照使用上下文工程智能体构建上下文集中的步骤,使用更多自然语言到 GQL 查询对来更新上下文集。
  4. 在探索器窗格中,点击您正在使用的上下文集旁边的查看操作。
  5. 点击修改上下文集。
  6. 点击上传上下文集文件部分中的浏览,然后选择更新后的上下文集文件。
  7. 点击保存以更新上下文集。
  8. 再次测试 QueryData,以验证生成的 GQL 查询。

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

将 QueryData 连接到您的应用

在 QueryData 方法调用中设置上下文集 ID 和目标 graph_ids,以提供编写的上下文并为 Spanner Graph 启用 GQL 查询生成功能。如需详细了解如何将 QueryData 与数据库数据源搭配使用,请参阅为数据库数据源定义数据智能体上下文。如需查看通过调用 QueryData REST API 的自定义 HTTP 工具将智能体应用连接到 QueryData 的示例,请参阅将 QueryData 与应用集成。

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

以下示例展示了针对 FinGraph 属性图表使用 spanner_reference 数据库数据源的 QueryData 请求。您必须在 spanner_reference.database_reference 中提供 graph_ids,以便 QueryData 定位到您的属性图并生成 GQL 查询。agent_context_reference.context_set_id 字段会链接到存储在数据库中的预先编写的上下文:

{
  "parent": "projects/my-project/locations/global",
  "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
  "context": {
    "datasource_references": {
      "spanner_reference": {
        "database_reference": {
          "engine": "GOOGLE_SQL",
          "project_id": "my-project",
          "instance_id": "my-instance",
          "database_id": "fin-graph-db",
          "graph_ids": [
            "FinGraph"
          ]
        },
        "agent_context_reference": {
          "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

请求正文包含以下字段:

  • parent:可选。请求的项目和位置,格式为 projects/PROJECT_ID/locations/LOCATION。使用与请求网址中相同的项目和位置。
  • prompt:来自最终用户的自然语言问题。
  • context:包含数据源的相关信息。
    • datasource_references:指定数据源。此字段是一个对象,而不是列表。
      • spanner_reference:查询 Spanner 数据库时为必需。
        • database_reference:指定与 Spanner 数据库和属性图相关的信息。
          • engine:数据库的方言。对于 Spanner Graph 数据库,应设置为 GOOGLE_SQL。
          • project_id:Spanner 实例的项目 ID。
          • instance_id:Spanner 实例的实例 ID。
          • database_id:Spanner 数据库的 ID。
          • graph_ids:Spanner Graph 必需。要查询的数据库中的属性图表名称列表(例如 ["FinGraph"])。提供 graph_ids 会指示 QueryData 针对指定的属性图表生成 GQL 查询。如果您省略 graph_ids,QueryData 只会针对底层表生成关系型 SQL 查询。
        • agent_context_reference:链接到数据库中撰写的上下文。
          • context_set_id:存储在数据库中的上下文的完整上下文集 ID,例如 projects/my-project/locations/us-central1/contextSets/fingraph-assistant。
  • generation_options:配置要生成的输出类型。
    • generate_query_result:设置为 true,以执行生成的 GQL 查询并返回查询结果。
    • generate_natural_language_answer:可选。如果设置为 true,则会生成一个自然语言回答,用于总结查询结果。
    • generate_explanation:可选。如果设置为 true,则会生成 GQL 查询的说明。
    • generate_disambiguation_question:可选。如果设置为 true,则在自然语言提示不明确时生成消除歧义的问题。

QueryData 响应示例

以下示例展示了针对 FinGraph 属性图表执行 QueryData 调用后返回的成功响应。REST API 会以驼峰命名法返回字段名称,例如 generatedQuery 和 queryResult。由于 GQL 生成具有不确定性,因此生成的查询、列名称和答案文本在不同调用之间可能会有所不同。

{
  "generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
  "intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
  "queryResult": {
    "columns": [
      {
        "name": "recipient_name",
        "type": "STRING"
      },
      {
        "name": "recipient_account_id",
        "type": "INT64"
      },
      {
        "name": "transfer_amount",
        "type": "FLOAT64"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "Alex"
          },
          {
            "value": "7"
          },
          {
            "value": "500"
          }
        ]
      },
      {
        "values": [
          {
            "value": "Lee"
          },
          {
            "value": "16"
          },
          {
            "value": "200"
          }
        ]
      }
    ],
    "totalRowCount": "2"
  },
  "naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n*   **Alex**: Account ID **7**, with a transfer amount of **500**\n*   **Lee**: Account ID **16**, with a transfer amount of **200**"
}

后续步骤