上下文集概览

上下文集包含特定数据库的信息，可帮助 QueryData 等工具生成高精确度的查询。上下文集可以包含模板、分面和值搜索，这些内容可帮助 QueryData 了解数据库架构和应用的业务逻辑。

支持以下数据库：

  • AlloyDB for PostgreSQL
  • Cloud SQL for MySQL
  • Cloud SQL for PostgreSQL
  • Spanner
  • 与 MongoDB 兼容的 Firestore
  • Bigtable

什么是上下文集

为了构建有效的智能体应用，QueryData 等工具必须了解您的数据组织和业务逻辑。您以上下文集的形式提供此信息。

您可以在包含每种上下文类型的 JSON 对象的文件中定义上下文。您可以借助上下文工程智能体编写这些上下文文件。 然后，您需要将上下文文件上传到您在 Google Cloud控制台中创建的上下文集。此过程使 QueryData 等工具能够了解数据库的特定架构和应用的业务逻辑。

上下文文件类似于以下内容：

{
  "templates": [
    {
      "nl_query": "List all luxury hotels",
      "sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = 'Luxury' ORDER BY _key ASC",
      "intent": "hotels in Luxury tier",
      "manifest": "hotels in a given product tier",
      "parameterized": {
        "parameterized_intent": "hotels in ? tier",
        "parameterized_sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = ? ORDER BY _key ASC"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= 4.5",
      "intent": "hotels with rating at least 4.5",
      "manifest": "hotels with rating at least a given number",
      "parameterized": {
        "parameterized_intent": "hotels with rating at least ?",
        "parameterized_sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= ?"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT CAST(T.cf['location'] AS STRING) AS value, 'hotels.location' AS `columns`, 'City' AS concept_type, 0 AS distance, '' AS context FROM `hotels` AS T WHERE CAST(T.cf['location'] AS STRING) = CAST($value AS STRING)",
      "concept_type": "City",
      "description": "Exact match for hotel city in hotels table"
    }
  ]
}

上下文集文件格式

上下文集文件包含一组精选的 JSON 格式模板、分面和值搜索，可指导 QueryData 等工具将自然语言问题转换为针对特定数据库的查询。定义上下文可确保针对常见查询句式生成高准确率的 SQL。

为了最大限度地提高准确率，请确保上下文集准确无误，并全面涵盖预期的应用查询。

可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 区域中创建上下文集。在项目中创建第一个上下文集时，您必须选择一个区域。 后续上下文集使用同一区域。

查询模板

查询模板是一组精选的代表性自然语言问题，其中包含相应的 SQL 查询。它们还包含说明，以便为自然语言到 SQL 生成提供声明性依据。

查询模板对象类似于以下内容：

{
  "templates": [
    {
      "nl_query": "List all luxury hotels",
      "sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = 'Luxury' ORDER BY _key ASC",
      "intent": "hotels in Luxury tier",
      "manifest": "hotels in a given product tier",
      "parameterized": {
        "parameterized_intent": "hotels in ? tier",
        "parameterized_sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = ? ORDER BY _key ASC"
      }
    }
  ],
  ...
}

查询模板 JSON 对象的主要组成部分如下：

  • nl_query：QueryData 等工具处理的自然语言查询示例。
  • sql：自然语言查询对应的 SQL 查询。
  • intent：自然语言查询的目标或目的。如果未设置，此值默认为自然语言查询。
  • manifest：自动生成的泛化形式的 intent。
  • parameterized_intent：意图的模板化自动生成形式，其中实体值替换为参数。
  • parameterized_sql：与参数化 intent 对应的 SQL 查询的模板化自动生成形式。

查询分面

查询 Facet 是一组精选的代表性自然语言条件，其中包含相应的 SQL 谓词。分面用于管理过滤和条件，使查询模板能够执行分面搜索。

查询分面对象类似于以下内容：

{
  ...
  "facets": [
    {
      "sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= 4.5",
      "intent": "hotels with rating at least 4.5",
      "manifest": "hotels with rating at least a given number",
      "parameterized": {
        "parameterized_intent": "hotels with rating at least ?",
        "parameterized_sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= ?"
      }
    }
  ]
}

分面 JSON 对象的主要组成部分如下：

  • sql_snippet：SQL 代码段。 为避免歧义，请使用表名称限定列名称（例如 table_name.column_name）。
  • intent：SQL 谓词的说明。
  • manifest：自动生成的泛化形式的 intent。
  • parameterized_intent：意图的模板化自动生成形式，其中实体值替换为参数。
  • parameterized_sql_snippet：与参数化 intent 对应的 sql_snippet 的模板化自动生成形式。

值搜索查询

值搜索查询 是开发者定义的查询，使用匹配函数在数据库中查找值及其上下文。值关联功能会使用这些查询的结果来识别哪些表和列包含匹配的值、了解值的概念类型，并更正拼写错误。

QueryData API 使用值关联来更准确地将自然语言转换为 SQL。通过使用值搜索查询，API 可以更正拼写错误并根据数据库值解析值类型，从而提高转换准确率。

值关联可提高自然语言到 SQL 的转换准确率。例如，如果用户询问“是否有从希思罗机场起飞的航班？”，数据库可能会将机场名称存储为“伦敦希思罗机场”。如果没有值关联，生成的 SQL 可能会按 WHERE name = 'Heathrow' 进行过滤，并且不返回任何结果。值搜索查询会引导代理将“Heathrow”映射到正确的数据库值“London Heathrow”及其架构位置 (airports.name)，从而确保生成的 SQL 准确无误。

值搜索查询示例如下：

{
  ...
  "value_searches": [
    {
      "query": "SELECT CAST(T.cf['location'] AS STRING) AS value, 'hotels.location' AS `columns`, 'City' AS concept_type, 0 AS distance, '' AS context FROM `hotels` AS T WHERE CAST(T.cf['location'] AS STRING) = CAST($value AS STRING)",
      "concept_type": "City",
      "description": "Exact match for hotel city in hotels table"
    }
  ]
}

值搜索 JSON 对象的主要组成部分如下：

  • query：一个参数化 SQL 语句，用于定义将值短语与数据库中存储的值进行匹配的逻辑。结果集通常会投影匹配的值、架构位置、概念类型和归一化距离指标（介于 0 和 1 之间）。
  • concept_type：分配给该值的语义标签，例如 district 或 loan_status。此标签有助于进行值关联，并最终帮助 QueryData API 等工具了解值短语在架构中的作用。它还有助于生成一条 SQL 语句，该语句以该值对应的概念以及该值短语所在的表和列为目标。
  • description：搜索逻辑的说明。

限制

上下文集具有以下限制：

  • 数据库的上下文集仅支持模板、分面和值搜索。
  • GoogleSQL for Bigtable 不支持集合操作 (UNION ALL)，因此不支持跨多个值搜索查询的值关联。此类请求会成功，但对于具有多个值搜索的上下文集，这些值不会关联。
  • 数据库的上下文集仅由 Conversational Analytics API 中的 QueryData 端点使用。

后续步骤