Definir 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 dar forma al comportamiento de un agente de datos y para refinar las respuestas de la API. El contexto creado eficaz proporciona a tus agentes de datos de la API Conversational Analytics información útil para responder a 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, puede proporcionar contexto creado mediante una combinación de contexto estructurado e instrucciones del sistema. Siempre que sea posible, proporciona contexto a través de campos de contexto estructurados. Después, puede usar el parámetro system_instruction para proporcionar información adicional que no se incluya en los campos estructurados.

Aunque tanto los campos de contexto estructurado como las instrucciones del sistema son opcionales, si proporcionas un contexto sólido, el agente podrá dar respuestas más precisas y relevantes.

Una vez que hayas definido 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:

Definir campos de contexto estructurados

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

Contexto estructurado a nivel de tabla

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

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

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

HTTP

En una solicitud HTTP directa, debe proporcionar estas propiedades a nivel de tabla en el objeto schema de la referencia de tabla correspondiente. Para ver un ejemplo completo de cómo estructurar la carga útil de la solicitud completa, consulta Conectarse a 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"]
    }
  }
]

SDK de Python

Cuando usas el SDK de Python, puedes definir estas propiedades a nivel de 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 crear y usar objetos de referencia de tabla, consulta Conectar con 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 columna

La clave fields, que está anidada en el objeto schema de una referencia de tabla, toma una lista de objetos field para describir columnas concretas. No todos los campos necesitan contexto adicional, pero, en el caso de los campos que se usan con frecuencia, incluir más detalles puede ayudar a mejorar el rendimiento del agente.

En 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: lista de términos alternativos que se pueden usar para referirse a la columna.
  • tags: 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 de la tabla orders y para el campo first_name de la tabla users con solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, puede definir estas propiedades a nivel de 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",
      }]
    }
  }
]

SDK de Python

Cuando usas el SDK de Python, puedes definir estas propiedades a nivel de 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 relevantes a preguntas habituales o importantes. Si proporcionas al agente tanto una pregunta en lenguaje natural como la consulta de SQL correspondiente, puedes guiarlo para que ofrezca resultados de mayor calidad y más coherentes.

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

  • natural_language_question: la pregunta en lenguaje natural que puede hacer un usuario
  • sql_query: la consulta de 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 tanto con solicitudes HTTP directas como con el SDK de Python.

HTTP

En una solicitud HTTP directa, proporcione 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'"
  }
]

SDK de Python

Cuando se usa el SDK de Python, se puede proporcionar una lista de objetos ExampleQuery. En cada objeto, proporcione 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'",
    )
]

Definir contexto adicional en las instrucciones del sistema

Puedes usar el parámetro system_instruction para proporcionar información complementaria sobre el contexto que no admiten los campos de contexto estructurado. Al proporcionar estas directrices adicionales, puedes ayudar al agente a comprender mejor el contexto de tus datos y tu caso práctico.

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 directrices sobre el rol del agente a la hora de responder preguntas. Puede 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 puede proporcionar al parámetro system_instruction de una fuente de datos de BigQuery, incluidas las claves disponibles y los tipos de datos esperados. Aunque 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 perfil del agente. Esta instrucción inicial marca el tono y el estilo de las respuestas de la API y ayuda al agente a entender su objetivo 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

Aunque definas 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 aggregations predeterminados para columnas específicas.

El siguiente bloque de código YAML de ejemplo muestra cómo puedes usar la clave tables en tus instrucciones del sistema para anidar campos que proporcionen informació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 de tus instrucciones del sistema contiene una lista de relaciones de unión entre tablas. Al definir relaciones de unión, puedes ayudar al agente a entender cómo unir datos de varias tablas al responder preguntas.

Por ejemplo, puede definir una relación orders_to_user entre las tablas bigquery-public-data.thelook_ecommerce.orders y 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 glossaries de las instrucciones del sistema incluye definiciones de términos empresariales, jerga y abreviaturas relevantes para tus datos y tu caso práctico. Si proporcionas definiciones de glosario, puedes ayudar al agente a interpretar y responder con precisión a preguntas que usen un lenguaje empresarial específico.

Por ejemplo, puedes definir términos como los estados habituales de las empresas 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 encajen en otros campos de contexto estructurado o de instrucciones del sistema. Si proporcionas descripciones adicionales en las instrucciones del sistema, puedes ayudar al agente a entender mejor el contexto de tus datos y tu caso práctico.

Por ejemplo, puedes usar la tecla 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 por el usuario mediante una combinación de contexto estructurado e instrucciones del sistema.

Ejemplo: Contexto estructurado

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

HTTP

En el ejemplo siguiente se muestra cómo definir un 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'"
    }
  ]
}

SDK de Python

En el ejemplo siguiente 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 perfil del agente y proporcionando directrices que no admiten los campos estructurados, como definiciones de relaciones, términos de glosario, descripciones adicionales y detalles complementarios de la tabla orders. En este ejemplo, como la tabla users está totalmente 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.