上下文集概览

借助上下文集，您可以使用对话式语言与数据库中的数据互动，QueryData 等工具会使用上下文集来构建对话智能体。您可以通过为数据库中的一组表定义上下文来创建上下文集。借助此上下文，QueryData 可以将自然语言问题转换为准确的查询，以满足您的目标使用情形。

上下文集是特定于数据库的信息集合，可让 QueryData 生成高准确度的查询。上下文集包括模板、方面和值搜索，可帮助 QueryData 了解您的数据库架构和应用的业务逻辑。

支持以下数据库：

  • AlloyDB for PostgreSQL
  • Cloud SQL for MySQL
  • Cloud SQL for PostgreSQL
  • Spanner

何时使用上下文集

您可以使用上下文集来构建对话数据应用，非常适合以下用例：

  • 客户服务自动化：处理大量咨询，例如“我的订单在哪里？”或“我的当前余额是多少？”。
  • 电子商务购物助理：帮助用户通过自然语言查询（例如“显示价格低于 100 美元的跑鞋”）浏览大型产品目录。
  • 现场作业工具：让移动员工能够实时查询库存水平、零件供应情况或服务工单详细信息。

情境集的工作原理

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

您可以在包含每种上下文类型的 JSON 对象的文件中定义上下文。您可以在 Gemini CLI 的帮助下创建这些上下文文件。然后，您将上下文的描述文件上传到在 Cloud de Confiance by S3NS控制台中创建的上下文集中。此过程可让 QueryData 了解数据库的特定架构和应用的业务逻辑。

上下文的描述文件类似于以下内容：

代理上下文的描述文件类似于以下内容：

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

当最终用户提出自然语言问题时，QueryData 会优先将问题与经过开发者审核的模板和分面进行匹配，以整理上下文。QueryData 识别出匹配项后，会使用所选的查询模板和分面来合成数据库查询。然后，上下文设置逻辑针对数据库执行该查询，以返回准确的结果。

建议您在上下文中定义值搜索。值搜索功能可让代理将值短语映射到数据库列中存储的特定值。这可让 LLM 以您的实际数据为依据，帮助其解决歧义，例如某个术语是指District还是City。

如果代理未能找到匹配的模板，则会使用值搜索功能将自然语言短语映射到数据库列中存储的特定值。这样，LLM 就可以根据您的实际数据进行推理，从而帮助其解决歧义问题，例如某个术语是指 District、Name 还是 City。

对话式分析 API 中的 QueryData 端点是一种智能体工具，可与您的应用进行程序化集成，从而能够根据自然语言问题生成 SQL 查询。在对话式应用中，QueryData 端点必须在管理对话历史记录和上下文的框架内使用。如需在保持严格的行级安全性的同时强制执行实体解析，您可以使用参数化安全视图 (PSV)。如需了解详情，请参阅使用参数化安全视图保护应用数据安全并控制对应用数据的访问权限

上下文集文件

上下文集文件包含一组精心挑选的 JSON 格式的模板和分面，用于指导 QueryData 将自然语言问题转换为针对特定数据库的查询。定义上下文可确保针对常见查询模式生成高准确度的 SQL。

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

可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 区域中创建上下文集。

查询模板

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

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

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

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

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

查询分面

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

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

{
...
"facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

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

  • sql_snippet：SQL 代码段。
  • intent：SQL 谓词的说明。
  • manifest：一种泛化的自动生成意图形式。
  • parameterized_intent：一种自动生成的模板化意图，实体值已替换为参数。
  • parameterized_sql_snippet：与参数化 intent 对应的 sql_snippet 的模板化自动生成形式。

值搜索查询

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

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

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

以下是一个值搜索查询示例：

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

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

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

限制

上下文集具有以下限制：

  • Cloud SQL for SQL Server 不受支持。
  • 数据库的上下文集仅支持模板、分面和值搜索。
  • 数据库的上下文集仅由 Conversational Analytics API 中的 QueryData 端点使用。

后续步骤