Define el contexto del agente de datos para las fuentes de datos de BigQuery

El contexto creado es una guía que los propietarios de agentes de datos pueden proporcionar para definir el comportamiento de un agente de datos y refinar las respuestas de la API. El contexto creado eficaz proporciona a tus agentes de datos de la API de Conversational Analytics un contexto útil para responder preguntas sobre tus fuentes de datos.

En esta página, se describe cómo proporcionar contexto creado para las fuentes de datos de BigQuery. En el caso de las fuentes de datos de BigQuery, puedes proporcionar contexto creado a través de una combinación de contexto estructurado y de instrucciones del sistema. Siempre que sea posible, proporciona contexto a través de campos de contexto estructurados. Luego, puedes usar el parámetro system_instruction para obtener orientación complementaria que no se incluye en los campos estructurados.

Si bien los campos de contexto estructurado y las instrucciones del sistema son opcionales, proporcionar un contexto sólido permite que el agente brinde respuestas más precisas y pertinentes.

Después de definir los campos estructurados y las instrucciones del sistema que componen el contexto creado, puedes proporcionar ese contexto a la API en una de las siguientes llamadas:

Cómo definir campos de contexto estructurados

En esta sección, se describe cómo proporcionar contexto a un agente de datos con campos de contexto estructurados. Puedes proporcionar la siguiente información a un agente como contexto estructurado:

Contexto estructurado a nivel de la tabla

Usa la clave tableReferences para proporcionar a un agente detalles sobre las tablas específicas que están disponibles para responder preguntas. Para cada referencia de tabla, puedes usar los siguientes campos de contexto estructurado para definir el esquema de una tabla:

  • description: Es un resumen del contenido y el propósito de la tabla.
  • synonyms: Lista de términos alternativos que se pueden usar para hacer referencia a la tabla
  • tags: Es una lista de palabras clave o etiquetas asociadas con la tabla.

En los siguientes ejemplos, se muestra cómo proporcionar estas propiedades como contexto estructurado dentro de solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, proporcionas estas propiedades a nivel de la tabla dentro del objeto schema para la referencia de tabla pertinente. Para ver un ejemplo completo de cómo estructurar la carga útil de la solicitud completa, consulta Conéctate a los datos de 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

Cuando usas el SDK de Python, puedes definir estas propiedades a nivel de la tabla en la propiedad schema de un objeto BigQueryTableReference. En el siguiente ejemplo, se muestra cómo crear objetos de referencia de tabla que proporcionan contexto para las tablas orders y users. Para ver un ejemplo completo de cómo compilar y usar objetos de referencia de tablas, consulta Conéctate a los datos de 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"]

Contexto estructurado a nivel de la columna

La clave fields, que está anidada dentro del objeto schema de una referencia de tabla, toma una lista de objetos field para describir columnas individuales. No todos los campos necesitan contexto adicional. Sin embargo, para los campos que se usan con frecuencia, incluir detalles adicionales puede ayudar a mejorar el rendimiento del agente.

Para cada objeto field, puedes usar los siguientes campos de contexto estructurado para definir las propiedades fundamentales de una columna:

  • description: Una breve descripción del contenido y el propósito de la columna
  • synonyms: Es una lista de términos alternativos que se pueden usar para referirse a la columna.
  • tags: Es una lista de palabras clave o etiquetas asociadas a la columna.

En los siguientes ejemplos, se muestra cómo puedes proporcionar estas propiedades como contexto estructurado para el campo status dentro de la tabla orders y para el campo first_name dentro de la tabla users con solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, puedes definir estas propiedades a nivel de la columna proporcionando una lista de objetos fields dentro del objeto schema de una referencia de tabla.

"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

Cuando usas el SDK de Python, puedes definir estas propiedades a nivel de la columna asignando una lista de objetos Field a la propiedad fields de la propiedad schema de una tabla.

# 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"],
    )
]

Consultas de ejemplo

La clave example_queries toma una lista de objetos example_query para definir consultas en lenguaje natural que ayudan al agente a proporcionar respuestas más precisas y pertinentes a preguntas comunes o importantes. Si le proporcionas al agente tanto una pregunta en lenguaje natural como su consulta en SQL correspondiente, puedes guiarlo para que proporcione resultados de mayor calidad y más coherentes.

Para cada objeto example_query, puedes proporcionar los siguientes campos para definir una pregunta en lenguaje natural y su consulta en SQL correspondiente:

  • natural_language_question: Pregunta en lenguaje natural que podría hacer un usuario
  • sql_query: La consulta en SQL que corresponde a la pregunta en lenguaje natural

En los siguientes ejemplos, se muestra cómo proporcionar consultas de ejemplo para la tabla orders con solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, proporciona una lista de objetos example_query en el campo example_queries. Cada objeto debe contener una clave naturalLanguageQuestion y una clave sqlQuery correspondiente.

"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'"
  }
]

Python SDK

Cuando usas el SDK de Python, puedes proporcionar una lista de objetos ExampleQuery. Para cada objeto, proporciona valores para los parámetros natural_language_question y sql_query.

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'",
    )
]

Define contexto adicional en las instrucciones del sistema

Puedes usar el parámetro system_instruction para proporcionar orientación complementaria sobre el contexto que no admiten los campos de contexto estructurado. Si proporcionas esta orientación adicional, puedes ayudar al agente a comprender mejor el contexto de tus datos y tu caso de uso.

Las instrucciones del sistema constan de una serie de componentes y objetos clave que proporcionan al agente de datos detalles sobre la fuente de datos y orientación sobre el rol del agente cuando responde preguntas. Puedes proporcionar instrucciones del sistema al agente de datos en el parámetro system_instruction como una cadena con formato YAML.

La siguiente plantilla muestra una estructura YAML sugerida para la cadena, que puedes proporcionar al parámetro system_instruction para una fuente de datos de BigQuery, incluidas las claves disponibles y los tipos de datos esperados. Si bien esta plantilla proporciona una estructura sugerida con componentes importantes para definir instrucciones del sistema, no incluye todos los formatos posibles de instrucciones del sistema.

- 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.

En las siguientes secciones, se incluyen ejemplos de componentes clave de las instrucciones del sistema:

system_instruction

Usa la clave system_instruction para definir el rol y el arquetipo del agente. Esta instrucción inicial establece el tono y el estilo de las respuestas de la API, y ayuda al agente a comprender su propósito principal.

Por ejemplo, puedes definir un agente como analista de ventas de una tienda de comercio electrónico ficticia de la siguiente manera:

- 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

Si bien defines las propiedades fundamentales de una tabla (como su descripción y sus sinónimos) como contexto estructurado, también puedes usar la clave tables en las instrucciones del sistema para proporcionar lógica empresarial complementaria. En el caso de las fuentes de datos de BigQuery, esto incluye el uso de la clave fields para definir el valor predeterminado de aggregations para columnas específicas.

En el siguiente bloque de código YAML de ejemplo, se muestra cómo puedes usar la clave tables en tus instrucciones del sistema para anidar campos que proporcionan orientación complementaria para la tabla 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

La clave relationships en tus instrucciones del sistema contiene una lista de relaciones de unión entre tablas. Si defines relaciones de unión, puedes ayudar al agente a comprender cómo unir datos de varias tablas cuando responda preguntas.

Por ejemplo, puedes definir una relación orders_to_user entre la tabla bigquery-public-data.thelook_ecommerce.orders y la tabla bigquery-public-data.thelook_ecommerce.users de la siguiente manera:

- 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

La clave glossaries en tus instrucciones del sistema enumera las definiciones de términos comerciales, jerga y abreviaturas que son relevantes para tus datos y tu caso de uso. Si proporcionas definiciones de glosario, puedes ayudar al agente a interpretar y responder con precisión las preguntas que usan un lenguaje comercial específico.

Por ejemplo, puedes definir términos como "estados comerciales comunes" y "OMPF" según el contexto específico de tu empresa de la siguiente manera:

- 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

Usa la clave additional_descriptions para proporcionar instrucciones generales o contexto que no se ajusten a otros campos de instrucciones del sistema o contexto estructurado. Si proporcionas descripciones adicionales en las instrucciones del sistema, puedes ayudar al agente a comprender mejor el contexto de tus datos y tu caso de uso.

Por ejemplo, puedes usar la clave additional_descriptions para proporcionar información sobre tu organización de la siguiente manera:

- 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.'

Ejemplo: Contexto creado para un agente de ventas

En el siguiente ejemplo de un agente analista de ventas ficticio, se muestra cómo proporcionar contexto creado con una combinación de contexto estructurado y de instrucciones del sistema.

Ejemplo: Contexto estructurado

Puedes proporcionar contexto estructurado con detalles sobre tablas, columnas y consultas de ejemplo para guiar al agente, como se muestra en los siguientes ejemplos de HTTP y del SDK de Python.

HTTP

En el siguiente ejemplo, se muestra cómo definir el contexto estructurado en una solicitud 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

En el siguiente ejemplo, se muestra cómo definir un contexto estructurado con el SDK de Python:

# 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'",
  )
]

Ejemplo: Instrucciones del sistema

Las siguientes instrucciones del sistema complementan el contexto estructurado definiendo el arquetipo del agente y proporcionando orientación que no admiten los campos estructurados, como las definiciones de relaciones, los términos del glosario, las descripciones adicionales y los detalles complementarios de la tabla orders. En este ejemplo, como la tabla users está completamente definida con contexto estructurado, no es necesario volver a definirla en las instrucciones del sistema.

- 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.