为 BigQuery 数据源定义数据代理上下文

本页面介绍了如何为使用 BigQuery 数据源的数据代理提供编写的上下文。

编写的上下文是数据代理所有者可以提供的指导，用于引导数据代理的行为并优化 API 的回答。有效的编写上下文可为 Conversational Analytics API 数据代理提供有用的上下文，以便回答有关数据源的问题。

虽然编写的上下文是可选的，但提供可靠的上下文可让代理给出更准确且相关的回答。您的数据代理会在创建和运行时融入此上下文，以确保其操作、查询和回答准确、合规且符合业务需求。系统会提取此上下文、为其编制索引，并使用它来引导代理的行为。

提供编写的上下文的选项

对于 BigQuery 数据源，您可以通过 结构化上下文 和 系统指令 的组合来提供编写的上下文。请尽可能通过结构化上下文字段提供上下文。然后，使用 system_instruction 参数提供结构化字段未涵盖的补充指导，例如定义代理的语气或整体行为。

定义构成编写的上下文的结构化字段和系统指令后，您可以通过以下任一调用将该上下文提供给 API：

定义结构化上下文字段

本部分介绍了如何使用结构化上下文字段向数据代理提供上下文。您可以向代理提供以下信息作为结构化上下文：

表级结构化上下文

使用 tableReferences 键向代理提供有关可用于回答问题的特定表的详细信息。对于每个表引用，您可以使用以下结构化上下文字段来定义表的架构：

  • description：表的内容和用途的摘要
  • synonyms：可用于引用表的替代术语列表
  • tags：与表关联的关键字或标记列表

以下示例展示了如何在直接 HTTP 请求中以及使用 Python SDK 提供这些属性作为结构化上下文。

HTTP

在直接 HTTP 请求中，您可以在相关表引用的 schema 对象中提供这些表级属性。如需查看如何构建完整请求载荷的完整示例 ，请参阅连接到 BigQuery 数据。

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
        "description": "Data for orders in The Look, a fictitious ecommerce store.",
        "synonyms": ["sales"],
        "tags": ["sale", "order", "sales_order"]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
        "description": "Data for users in The Look, a fictitious ecommerce store.",
        "synonyms": ["customers"],
        "tags": ["user", "customer", "buyer"]
    }
  }
]

Python SDK

使用 Python SDK 时，您可以在 BigQueryTableReference 对象的 schema 属性中定义这些表级属性。以下示例展示了如何创建为 orders 和 users 表提供上下文的表引用对象。如需查看如何构建和使用表引用对象的完整示例，请参阅连接到 BigQuery 数据。

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]

列级结构化上下文

嵌套在表引用的 schema 对象中的 fields 键接受 field 对象列表作为输入来描述各列。并非所有字段都需要提供额外的上下文信息；不过，对于常用字段，添加额外的详细信息有助于提升智能体的性能。

对于每个 field 对象，您可以使用以下结构化上下文字段来定义列的基本属性：

  • description：列的内容和用途的简要说明
  • synonyms：可用于引用列的替代术语列表
  • tags：与列关联的关键字或标记列表

以下示例展示了如何在直接 HTTP 请求中以及使用 Python SDK 为 orders 表中的 status 字段和 users 表中的 first_name 字段提供这些属性作为结构化上下文。

HTTP

在直接 HTTP 请求中，您可以通过在表引用的 schema 对象中提供 fields 对象列表来定义这些列级属性。

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
      "fields": [{
          "name": "status",
          "description": "The current status of the order.",
      }]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
      "fields": [{
          "name": "first_name",
          "description": "The first name of the user.",
          "tags": "person",
      }]
    }
  }
]

Python SDK

使用 Python SDK 时，您可以通过将 Field 对象列表分配给表的 schema 属性的 fields 属性来定义这些列级属性。

# Define column context for the 'orders' table
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    )
]

# Define column context for the 'users' table
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    )
]

示例查询

example_queries 键接受 example_query 对象列表作为输入，这些对象定义了自然语言查询，有助于代理提供更准确且相关的回答。通过为智能体提供自然语言问题及其相应的 SQL 查询，您可以引导智能体提供更高质量且更一致的结果。

如果用户的问题在语义上与定义的示例查询匹配，代理可能会直接执行该查询，而不是生成新查询。当代理执行现有查询时，API 响应会包含 matched_query 对象，以表明使用了 经过验证的查询。代理还可能会在其回答中引用该查询。

参数化示例查询

除了静态查询之外，您还可以定义参数化示例查询，让代理将动态值替换为经过验证的查询模板。通过在示例查询中添加参数，您可以创建灵活的模板，这些模板比静态示例涵盖更广泛的用户查询。当用户的问题与模板匹配时，代理会执行相应的查询以提供经过验证的回答。

您可以按如下方式定义参数化查询：

  1. 在 naturalLanguageQuestion 字段中，使用大括号作为占位符，例如 {state}。
  2. 在 sqlQuery 字段中，对同一变量使用 BigQuery 命名参数语法，例如 @state。
  3. 在 parameters 字段中，定义每个参数的名称、数据类型和说明。

示例

以下示例展示了如何为 FAA 机场数据集定义静态和参数化示例查询。

HTTP

在直接 HTTP 请求中，在 example_queries 字段中提供 example_query 对象列表。对于每个对象，提供 naturalLanguageQuestion 键（用户可能会提出的问题）及其对应的 sqlQuery 键。对于参数化查询，您还必须提供 parameters 列表，其中包含每个参数的名称、数据类型和说明。

"example_queries": [
  {
    "naturalLanguageQuestion": "How many airports are there?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports`"
  },
  {
    "naturalLanguageQuestion": "How many airports are in {state} with an elevation that is greater than {elevation}?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports` WHERE LOWER(state_abbreviation) = @state AND elevation > @elevation",
    "parameters": [
      {
        "name": "state",
        "dataType": "STRING",
        "description": "The state abbreviation in lowercase.",
      },
      {
        "name": "elevation",
        "dataType": "FLOAT64",
        "description": "The elevation in feet.",
      }
    ]
  }
]

Python SDK

使用 Python SDK 时，请提供 ExampleQuery 对象列表。对于每个对象，提供 natural_language_question 参数（用户可能会提出的问题）和 sql_query 参数的值。对于参数化查询，您还必须提供 QueryParameter 对象列表。

example_queries = [
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many airports are there?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports`"
    ),
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many airports are in {state} with an elevation that is greater than {elevation}?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports` WHERE LOWER(state_abbreviation) = @state AND elevation > @elevation",
        parameters=[
            geminidataanalytics.QueryParameter(
                name="state",
                data_type="STRING",
                description="The state abbreviation in lowercase.",
            ),
            geminidataanalytics.QueryParameter(
                name="elevation",
                data_type="FLOAT64",
                description="The elevation in feet.",
            ),
        ],
    )
]

用户定义的函数

您可以使用 用户定义的函数 (UDF) 在代理上下文中为 BigQuery 提供 user_functions 字段。当您提供自定义 BigQuery 例程时，如果需要回答问题，代理可以使用这些例程。

对于每个 UDF，您可以提供以下属性：

  • routineReference：对 BigQuery 例程的引用，包括项目 ID、数据集 ID 和例程 ID。如需在与 API 端点不同的区域中使用例程（例如，如果您从 us 多区域 API 端点访问 us-east4 区域中的表），请在 boundaryLocationId 字段中指定该区域。
  • description：函数行为的摘要，代理使用该摘要来确定函数何时适合作为回答。

以下示例展示了如何在直接 HTTP 请求中以及使用 Python SDK 提供用户定义的函数。

HTTP

在直接 HTTP 请求中，提供包含 bqRoutines 列表的 user_functions 对象。列表中的每个对象都必须包含 routineReference 属性和 description 字段。

"user_functions": {
  "bqRoutines": [
    {
      "routineReference": {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "routineId": "my_custom_function"
      },
      "description": "Calculates adjusted revenue by using custom logic."
    }
  ]
}

Python SDK

使用 Python SDK 时，您可以通过将 BigQueryRoutine 对象列表分配给添加到代理上下文的 UserFunctions 对象的 bq_routines 属性来定义这些例程。

# Define a BigQuery routine (UDF)
bq_routine = geminidataanalytics.BigQueryRoutine()
bq_routine.routine_reference.project_id = "bigquery-public-data"
bq_routine.routine_reference.dataset_id = "thelook_ecommerce"
bq_routine.routine_reference.routine_id = "my_custom_function"
bq_routine.description = "Calculates adjusted revenue by using custom logic."

# Add the routine to the agent's context
user_functions = geminidataanalytics.UserFunctions()
user_functions.bq_routines = [bq_routine]

# Assign to context
context.user_functions = user_functions

在系统指令中定义其他上下文

您可以使用 system_instruction 参数为结构化上下文字段不支持的上下文提供补充指导。通过提供此额外指导，有助于代理更好地理解您的数据及应用场景的上下文信息。

系统指令由一系列关键组件和对象组成，这些组件和对象为数据代理提供了有关数据源的详细信息，以及在回答问题时有关代理角色的指导。您可以使用 system_instruction 参数以 YAML 格式的字符串形式向数据代理提供系统指令。

以下模板展示了一种建议的 YAML 结构来为 BigQuery 数据源的 system_instruction 参数提供字符串，包括可用的键和预期的数据类型。虽然此模板提供了一种建议的结构，其中包含用于定义系统指令的重要组件，但它并不包含所有可能的系统指令格式。

- system_instruction: str # A description of the expected behavior of the agent. For example: You are a sales agent.
- tables: # A list of tables to describe for the agent.
  - table: # Details about a single table that is relevant for the agent.
    - name: str # The name of the table.
    - fields: # Details about columns (fields) within the table.
      - field: # Details about a single column within the current table.
        - name: str # The name of the column.
        - aggregations: list[str] # Commonly used or default aggregations for the column.
  - relationships: # A list of join relationships between tables.
    - relationship: # Details about a single join relationship.
      - name: str # The name of this join relationship.
      - description: str # A description of the relationship.
      - relationship_type: str # The join relationship type: one-to-one, one-to-many, many-to-one, or many-to-many.
      - join_type: str # The join type: inner, outer, left, right, or full.
      - left_table: str # The name of the left table in the join.
      - right_table: str # The name of the right table in the join.
      - relationship_columns: # A list of columns that are used for the join.
        - left_column: str # The join column from the left table.
        - right_column: str # The join column from the right table.
- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
  - glossary: # The definition for a single glossary item.
    - term: str # The term, phrase, or abbreviation to define.
    - description: str # A description or definition of the term.
    - synonyms: list[str] # Alternative terms for the glossary entry.
- additional_descriptions: # A list of any other general instructions or content.
  - text: str # Any additional general instructions or context not covered elsewhere.

以下部分包含系统指令的关键组成部分示例：

system_instruction

使用 system_instruction 键定义智能体的角色及角色设定。此初始指令可为 API 的回答设定基调和风格，并帮助智能体理解其核心目标。

例如，您可以将智能体定义成一个虚构网店的销售分析师，如下所示：

-   system_instruction: You are an expert sales analyst for a fictitious
    ecommerce store. You will answer questions about sales, orders, and customer
    data. Your responses should be concise and data-driven.

tables

虽然您将表的基本属性（例如说明和同义词）定义为 结构化上下文，但您也可以在系统指令中使用 tables 键来提供补充业务逻辑。对于 BigQuery 数据源，这包括使用 fields 键为特定列定义默认 aggregations。

以下示例 YAML 代码块展示了如何在系统指令中使用 tables 键来嵌套为表 bigquery-public-data.thelook_ecommerce.orders 提供补充指导的字段：

-   tables:
  -   table:
    -   name: bigquery-public-data.thelook_ecommerce.orders
    -   fields:
      -   field:
        -   name: num_of_items
        -   aggregations: 'sum, avg'

relationships

系统指令中的 relationships 键包含表之间联接关系的列表。通过定义联接关系，有助于智能体理解在回答问题时应如何联接来自多个表的数据。

例如，您可以按如下方式定义 bigquery-public-data.thelook_ecommerce.orders 表和 bigquery-public-data.thelook_ecommerce.users 表之间的 orders_to_user 关系：

-   relationships:
  -   relationship:
    -   name: orders_to_user
    -   description: >-
        Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
    -   relationship_type: many-to-one
    -   join_type: left
    -   left_table: bigquery-public-data.thelook_ecommerce.orders
    -   right_table: bigquery-public-data.thelook_ecommerce.users
    -   relationship_columns:
      -   left_column: user_id
      -   right_column: id

glossaries

系统指令中的 glossaries 键列出了与您的数据及应用场景相关的业务术语、行话和缩写的定义。通过提供词汇表定义，有助于智能体准确解读并回答使用特定业务语言的问题。如果智能体使用词汇表术语来回答问题，它可能会在其回答中引用该术语。

例如，您可以根据特定业务情境定义常见业务状态和“OMPF”等字词，如下所示：

- glossaries:
  - glossary:
    - term: complete
    - description: Represents an order status where the order has been completed.
    - synonyms: 'finish, done, fulfilled'
  - glossary:
    - term: shipped
    - description: Represents an order status where the order has been shipped to the customer.
  - glossary:
    - term: returned
    - description: Represents an order status where the customer has returned the order.
  - glossary:
    - term: OMPF
    - description: Order Management and Product Fulfillment

additional_descriptions

使用 additional_descriptions 键提供不适合其他结构化上下文或系统指令字段的任何一般性说明或上下文。通过在系统指令中提供更多说明，有助于智能体更好地理解您的数据及应用场景的上下文信息。

例如，您可以使用 additional_descriptions 键提供有关组织的信息，如下所示：

-   additional_descriptions:
  -   text: All the sales data pertains to The Look, a fictitious ecommerce store.
  -   text: 'Orders can be of three categories: food, clothes, and electronics.'

示例：销售代理的编写的上下文

以下虚构的销售分析师代理示例展示了如何通过结合使用结构化上下文和系统指令来提供编写的上下文。

示例：结构化上下文

您可以提供结构化上下文，其中包含有关表、列和示例查询的详细信息，以指导代理，如以下 HTTP 和 Python SDK 示例所示。

HTTP

以下示例展示了如何在 HTTP 请求中定义结构化上下文：

{
  "bq": {
    "tableReferences": [
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "orders",
        "schema": {
          "description": "Data for orders in The Look, a fictitious ecommerce store.",
          "synonyms": ["sales"],
          "tags": ["sale", "order", "sales_order"],
          "fields": [
            {
              "name": "status",
              "description": "The current status of the order."
            },
            {
              "name": "num_of_items",
              "description": "The number of items in the order."
            }
          ]
        }
      },
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "users",
        "schema": {
          "description": "Data for users in The Look, a fictitious ecommerce store.",
          "synonyms": ["customers"],
          "tags": ["user", "customer", "buyer"],
          "fields": [
            {
              "name": "first_name",
              "description": "The first name of the user.",
              "tags": ["person"]
            },
            {
              "name": "last_name",
              "description": "The last name of the user.",
              "tags": ["person"]
            },
            {
              "name": "age_group",
              "description": "The age demographic group of the user."
            },
            {
              "name": "email",
              "description": "The email address of the user.",
              "tags": ["contact"]
            }
          ]
        }
      }
    ]
  },
  "example_queries": [
    {
      "naturalLanguageQuestion": "How many orders are there?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`"
    },
    {
      "naturalLanguageQuestion": "How many orders were shipped?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'"
    },
    {
      "naturalLanguageQuestion": "How many unique customers are there?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`"
    },
    {
      "naturalLanguageQuestion": "How many users in the 25-34 age group have a cymbalgroup email address?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'"
    }
  ]
}

Python SDK

以下示例展示了如何使用 Python SDK 定义结构化上下文：

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    ),
    geminidataanalytics.Field(
        name="num_of_items",
        description="The number of items in the order."
    )
]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="last_name",
        description="The last name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="age_group",
        description="The age demographic group of the user.",
    ),
    geminidataanalytics.Field(
        name="email",
        description="The email address of the user.",
        tags=["contact"],
    )
]

# Define example queries
example_queries = [
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders are there?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders were shipped?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many unique customers are there?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many users in the 25-34 age group have a cymbalgroup email address?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'",
  )
]

示例：系统指令

以下系统指令通过定义代理的角色设定并提供结构化字段不支持的指导（例如关系定义、词汇表术语、其他说明和补充 orders 表详细信息）来补充结构化上下文。在此示例中，由于 users 表已通过结构化上下文完全定义，因此无需在系统指令中重新定义。

-   system_instruction: >-
    You are an expert sales analyst for a fictitious ecommerce store. You will answer questions about sales, orders, and customer data. Your responses should be concise and data-driven.
-   tables:
    -   table:
        -   name: bigquery-public-data.thelook_ecommerce.orders
        -   fields:
            -   field:
                -   name: num_of_items
                -   aggregations: 'sum, avg'
-   relationships:
    -   relationship:
        -   name: orders_to_user
        -   description: >-
            Connects customer order data to user information with the user_id and id fields.
        - relationship_type: many-to-one
        - join_type: left
        - left_table: bigquery-public-data.thelook_ecommerce.orders
        - right_table: bigquery-public-data.thelook_ecommerce.users
        - relationship_columns:
            - left_column: user_id
            - right_column: id
- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment
- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.