Si escribes instrucciones del sistema eficaces, tus agentes de datos de la API Conversational Analytics podrán obtener contexto útil para responder a preguntas sobre tus fuentes de datos. Las instrucciones del sistema son un tipo de contexto creado 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.
En esta página se describe la estructura recomendada para escribir peticiones eficaces para tus agentes de datos de la API Conversational Analytics que se conectan a datos de BigQuery. Estas peticiones son contextos creados que se definen como cadenas mediante el parámetro system_instruction.
En esta página se describe cómo escribir instrucciones del sistema para fuentes de datos de BigQuery, que se basan en bases de datos de BigQuery.
Definir el contexto en las instrucciones del sistema
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 proporcione al parámetro system_instruction, incluidas las claves disponibles y los tipos de datos esperados.
La siguiente plantilla YAML muestra un ejemplo de cómo puede estructurar las instrucciones del sistema para una fuente de datos de BigQuery.
- 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.
- description: str # A description of the table.
- synonyms: list[str] # Alternative terms for referring to the table.
- tags: list[str] # Keywords or tags that are associated with 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.
- description: str # A description of the column.
- synonyms: list[str] # Alternative terms for referring to the column.
- tags: list[str] # Keywords or tags that are associated with the column.
- sample_values: list[str] # Sample values that are present within the column.
- aggregations: list[str] # Commonly used or default aggregations for the column.
- measures: # A list of calculated metrics (measures) for the table.
- measure: # Details about a single measure within the table.
- name: str # The name of the measure.
- description: str # A description of the measure.
- exp: str # The expression that is used to construct the measure.
- synonyms: list[str] # Alternative terms for referring to the measure.
- golden_queries: # A list of important or popular ("golden") queries for the table.
- golden_query: # Details about a single golden query.
- natural_language_query: str # The natural language query.
- sql_query: str # The SQL query that corresponds to the natural language query.
- golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
- golden_action_plan: # Details about a single action plan.
- natural_language_query: str # The natural language query.
- action_plan: # A list of the steps for this action plan.
- step: str # A single step within the action plan.
- 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.
Ejemplos de componentes clave de instrucciones del sistema con fuentes de datos de BigQuery
En las siguientes secciones se incluyen ejemplos de componentes clave de las instrucciones del sistema en BigQuery. Estas claves incluyen las siguientes:
system_instructiontablesfieldsmeasuresgolden_queriesgolden_action_plansrelationshipsglossariesadditional_descriptions
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
La clave tables contiene una lista de descripciones de tablas para el agente y proporciona detalles sobre los datos específicos que tiene a su disposición para responder preguntas. Cada objeto table de esta lista contiene los metadatos de una tabla específica, incluidos el nombre, la descripción, los sinónimos, las etiquetas, los campos, las medidas, las consultas de oro y los planes de acción de oro de esa tabla. El siguiente bloque de código YAML muestra la estructura básica de la clave tables de la tabla bigquery-public-data.thelook_ecommerce.orders:
- tables:
- table:
- name: bigquery-public-data.thelook_ecommerce.orders
- description: Data for customer orders in The Look fictitious e-commerce store.
- synonyms:
- sales
- orders_data
- tags:
- ecommerce
- transaction
fields
La clave fields, que está anidada en un objeto table, toma una lista de objetos de campo 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.
El siguiente código YAML de ejemplo describe los campos clave, como order_id, status, created_at, num_of_items y earnings, de la tabla orders:
- tables:
- table:
- name: bigquery-public-data.thelook_ecommerce.orders
- fields:
- field:
- name: order_id
- description: The unique identifier for each customer order.
- field:
- name: user_id
- description: The unique identifier for each customer.
- field:
- name: status
- description: The current status of the order.
- sample_values:
- complete
- shipped
- returned
- field:
- name: created_at
- description: The timestamp when the order was created.
- field:
- name: num_of_items
- description: The total number of items in the order.
- aggregations:
- sum
- avg
- field:
- name: earnings
- description: The sales amount for the order.
- aggregations:
- sum
- avg
measures
La clave measures, que está anidada en un objeto table, define métricas o cálculos empresariales personalizados que no están presentes directamente como columnas en sus tablas. Proporcionar contexto para las métricas ayuda al agente a responder preguntas sobre los indicadores clave de rendimiento u otros valores calculados.
Por ejemplo, puedes definir una medida profit como el resultado de restar los ingresos a los costes, de la siguiente manera:
- tables:
- table:
- name: bigquery-public-data.thelook_ecommerce.orders
- measures:
- measure:
- name: profit
- description: Raw profit (earnings minus cost).
- exp: earnings - cost
- synonyms: gains
golden_queries
La clave golden_queries, que está anidada en un objeto table, toma una lista de objetos golden_query. Las consultas de oro ayudan al agente a proporcionar respuestas más precisas y relevantes a las preguntas habituales o importantes que puedes definir.
Por ejemplo, puede definir consultas de referencia para análisis habituales de los datos de la tabla orders de la siguiente manera:
- tables:
- table:
- golden_queries:
- golden_query:
- natural_language_query: How many orders are there?
- sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
- golden_query:
- natural_language_query: How many orders were shipped?
- sql_query: >-
SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
WHERE status = 'shipped'
golden_action_plans
La clave golden_action_plans, que está anidada en un objeto table, toma una lista de objetos golden_action_plan. Puedes usar planes de acción óptimos para proporcionar al agente ejemplos de cómo gestionar solicitudes de varios pasos, como obtener datos y, a continuación, crear una visualización.
Por ejemplo, puedes definir un plan de acción para mostrar los desgloses de pedidos por grupo de edad e incluir detalles sobre la consulta SQL y los pasos relacionados con la visualización:
- tables:
- table:
- golden_action_plans:
- golden_action_plan:
- natural_language_query: Show me the number of orders broken down by age group.
- action_plan:
- step: >-
Run a SQL query that joins the table
sqlgen-testing.thelook_ecommerce.orders and
sqlgen-testing.thelook_ecommerce.users to get a
breakdown of order count by age group.
- step: >-
Create a vertical bar plot using the retrieved data,
with one bar per age group.
relationships
La clave relationships 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 clave 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 utilicen 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
La clave additional_descriptions incluye cualquier instrucción general o contexto adicional que no se haya tratado en otras partes de las instrucciones del sistema. Si proporciona descripciones adicionales, puede ayudar al agente a entender mejor el contexto de sus datos y su 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: instrucciones del sistema en BigQuery
En el siguiente ejemplo se muestran instrucciones del sistema de muestra para un agente analista de ventas ficticio:
- 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
- description: Data for orders in The Look, a fictitious ecommerce store.
- synonyms: sales
- tags: 'sale, order, sales_order'
- fields:
- field:
- name: order_id
- description: The unique identifier for each customer order.
- field:
- name: user_id
- description: The unique identifier for each customer.
- field:
- name: status
- description: The current status of the order.
- sample_values:
- complete
- shipped
- returned
- field:
- name: created_at
- description: >-
The date and time at which the order was created in timestamp
format.
- field:
- name: returned_at
- description: >-
The date and time at which the order was returned in timestamp
format.
- field:
- name: num_of_items
- description: The total number of items in the order.
- aggregations: 'sum, avg'
- field:
- name: earnings
- description: The sales revenue for the order.
- aggregations: 'sum, avg'
- field:
- name: cost
- description: The cost for the items in the order.
- aggregations: 'sum, avg'
- measures:
- measure:
- name: profit
- description: Raw profit (earnings minus cost).
- exp: earnings - cost
- synonyms: gains
- golden_queries:
- golden_query:
- natural_language_query: How many orders are there?
- sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
- golden_query:
- natural_language_query: How many orders were shipped?
- sql_query: >-
SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
WHERE status = 'shipped'
- golden_action_plans:
- golden_action_plan:
- natural_language_query: Show me the number of orders broken down by age group.
- action_plan:
- step: >-
Run a SQL query that joins the table
sqlgen-testing.thelook_ecommerce.orders and
sqlgen-testing.thelook_ecommerce.users to get a
breakdown of order count by age group.
- step: >-
Create a vertical bar plot using the retrieved data,
with one bar per age group.
- table:
- name: bigquery-public-data.thelook_ecommerce.users
- description: Data for users in The Look, a fictitious ecommerce store.
- synonyms: customers
- tags: 'user, customer, buyer'
- fields:
- field:
- name: id
- description: The unique identifier for each user.
- field:
- name: first_name
- description: The first name of the user.
- tag: person
- sample_values: 'alex, izumi, nur'
- field:
- name: last_name
- description: The first name of the user.
- tag: person
- sample_values: 'warmer, stilles, smith'
- field:
- name: age_group
- description: The age demographic group of the user.
- sample_values:
- 18-24
- 25-34
- 35-49
- 50+
- field:
- name: email
- description: The email address of the user.
- tag: contact
- sample_values: '222larabrown@gmail.com, cloudysanfrancisco@gmail.com'
- golden_queries:
- golden_query:
- natural_language_query: How many unique customers are there?
- sql_query: >-
SELECT COUNT(DISTINCT id) FROM
bigquery-public-data.thelook_ecommerce.users
- golden_query:
- natural_language_query: 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';
- 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:
- 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:
- text: All the sales data pertains to The Look, a fictitious ecommerce store.
- text: 'Orders can be of three categories: food, clothes, and electronics.'