Scrivere istruzioni di sistema efficaci può fornire agli agenti di dati dell'API Conversational Analytics un contesto utile per rispondere alle domande sulle origini dati. Le istruzioni di sistema sono un tipo di contesto creato che i proprietari degli agenti di dati possono fornire per modellare il comportamento di un agente di dati e perfezionare le risposte dell'API.
Questa pagina descrive la struttura consigliata per scrivere prompt efficaci per gli agenti di dati dell'API Conversational Analytics che si connettono ai dati BigQuery. Questi prompt sono contesti creati che definisci come stringhe utilizzando il parametro system_instruction.
Questa pagina descrive come scrivere istruzioni di sistema per le origini dati BigQuery, che si basano sui database BigQuery.
Definisci il contesto nelle istruzioni di sistema
Le istruzioni di sistema sono costituite da una serie di componenti e oggetti chiave che forniscono all'agente dati dettagli sull'origine dati e indicazioni sul ruolo dell'agente quando risponde alle domande. Puoi fornire istruzioni di sistema all'agente dati nel parametro system_instruction come stringa formattata in YAML.
Il seguente modello mostra una struttura YAML suggerita per la stringa che fornisci al parametro system_instruction, incluse le chiavi disponibili e i tipi di dati previsti.
Il seguente modello YAML mostra un esempio di come potresti strutturare le istruzioni di sistema per un'origine dati 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.
Esempi di componenti chiave delle istruzioni di sistema che utilizzano le origini dati BigQuery
Le sezioni seguenti contengono esempi di componenti chiave delle istruzioni di sistema in BigQuery. Queste chiavi includono:
system_instructiontablesfieldsmeasuresgolden_queriesgolden_action_plansrelationshipsglossariesadditional_descriptions
system_instruction
Utilizza la chiave system_instruction per definire il ruolo e la personalità dell'agente. Questa istruzione iniziale definisce il tono e lo stile delle risposte dell'API e aiuta l'agente a comprendere il suo scopo principale.
Ad esempio, puoi definire un agente come analista delle vendite per un negozio e-commerce fittizio nel seguente modo:
- 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 chiave tables contiene un elenco di descrizioni delle tabelle per l'agente e fornisce dettagli sui dati specifici disponibili per l'agente per rispondere alle domande. Ogni oggetto table di questo elenco contiene i metadati di una tabella specifica, inclusi nome, descrizione, sinonimi, tag, campi, misure, query di riferimento e piani d'azione di riferimento della tabella. Il seguente blocco di codice YAML mostra la struttura di base della chiave tables per la tabella 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 chiave fields, nidificata all'interno di un oggetto table, accetta un elenco di oggetti campo per descrivere le singole colonne. Non tutti i campi richiedono un contesto aggiuntivo, ma per i campi di uso comune, l'inclusione di dettagli aggiuntivi può contribuire a migliorare il rendimento dell'agente.
Il seguente codice YAML di esempio descrive i campi chiave come order_id, status, created_at, num_of_items e earnings per la tabella 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 chiave measures, nidificata all'interno di un oggetto table, definisce metriche o calcoli aziendali personalizzati che non sono direttamente presenti come colonne nelle tabelle. Fornire il contesto per le misure aiuta l'agente a rispondere a domande sugli indicatori chiave di prestazione (KPI) o su altri valori calcolati.
Ad esempio, puoi definire una misura profit come calcolo degli utili meno i costi nel seguente modo:
- 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 chiave golden_queries, nidificata all'interno di un oggetto table, accetta un elenco di oggetti golden_query. Le query d'oro aiutano l'agente a fornire risposte più accurate e pertinenti a domande comuni o importanti che puoi definire.
Ad esempio, puoi definire query di riferimento per analisi comuni per i dati nella tabella orders nel seguente modo:
- 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 chiave golden_action_plans, nidificata all'interno di un oggetto table, accetta un elenco di oggetti golden_action_plan. Puoi utilizzare i piani d'azione di riferimento per fornire all'agente esempi di come gestire le richieste in più passaggi, ad esempio per recuperare i dati e poi creare una visualizzazione.
Ad esempio, puoi definire un piano d'azione per mostrare le suddivisioni degli ordini per fascia d'età e includere dettagli sulla query SQL e sui passaggi relativi alla visualizzazione:
- 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 chiave relationships contiene un elenco di relazioni di unione tra le tabelle. Definendo le relazioni di join, puoi aiutare l'agente a capire come unire i dati di più tabelle quando risponde alle domande.
Ad esempio, puoi definire una relazione orders_to_user tra la tabella bigquery-public-data.thelook_ecommerce.orders e la tabella bigquery-public-data.thelook_ecommerce.users nel seguente modo:
- 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
L'elenco delle glossaries chiavi definisce i termini aziendali, il gergo e le abbreviazioni pertinenti ai tuoi dati e al tuo caso d'uso. Fornendo le definizioni del glossario, puoi aiutare l'agente a interpretare e rispondere con precisione alle domande che utilizzano un linguaggio aziendale specifico.
Ad esempio, puoi definire termini come stati aziendali comuni e "OMPF" in base al contesto aziendale specifico nel seguente modo:
- 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
Il tasto additional_descriptions elenca eventuali istruzioni generali o contesto aggiuntivi non trattati altrove nelle istruzioni di sistema. Fornendo descrizioni aggiuntive, puoi aiutare l'agente a comprendere meglio il contesto dei tuoi dati e il caso d'uso.
Ad esempio, puoi utilizzare il tasto additional_descriptions per fornire informazioni sulla tua organizzazione come segue:
- 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.'
Esempio: istruzioni di sistema in BigQuery
Il seguente esempio mostra istruzioni di sistema di esempio per un agente analista delle vendite fittizio:
- 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.'