Cette page décrit la structure recommandée pour rédiger des prompts efficaces pour vos agents de données utilisant l'API Conversational Analytics. Ces prompts sont des contextes créés que vous définissez sous forme de chaînes à l'aide du paramètre system_instruction. Des instructions système bien structurées peuvent améliorer la justesse et la pertinence des réponses fournies par l'API.
Que sont les instructions système ?
Les instructions système sont des consignes définies par l'utilisateur, que les développeurs peuvent fournir pour façonner le comportement d'un agent de données et affiner les réponses de l'API. Les instructions système font partie du contexte utilisé par l'API pour répondre aux questions. Ce contexte inclut également les sources de données connectées (tables BigQuery, explorations Looker, sources de données Looker Studio) et l'historique des conversations (pour les conversations multitours).
En fournissant des instructions système claires et structurées, vous pouvez améliorer la capacité de l'agent à interpréter les questions des utilisateurs et à générer des réponses utiles et précises. Des instructions système bien définies sont particulièrement utiles si vous vous connectez à des données telles que des tables BigQuery, où il n'existe peut-être pas de couche sémantique prédéfinie comme on en trouve dans une exploration Looker.
Par exemple, vous pouvez utiliser des instructions système pour fournir les types de consignes suivants à un agent :
- Logique spécifique à l'entreprise : définis comme "fidèle" un client qui a effectué plus de cinq achats au cours d'une période donnée.
- Mise en forme des réponses : résume toutes les réponses de l'agent de données en 20 mots ou moins pour faire gagner du temps aux utilisateurs.
- Présentation des données : mets en forme tous les nombres pour qu'ils correspondent au guide de style de l'entreprise.
Fournir des instructions système
Vous pouvez fournir des instructions système à l'API Conversational Analytics sous la forme d'une chaîne au format YAML à l'aide du paramètre system_instruction. Bien que le paramètre system_instruction soit facultatif, il est recommandé de fournir des instructions système bien structurées pour obtenir des réponses précises et pertinentes.
Vous pouvez définir la chaîne au format YAML dans votre code lors de la configuration initiale, comme indiqué dans Configurer les paramètres initiaux et l'authentification (HTTP) ou Spécifier le projet de facturation et les instructions système (SDK Python). Vous pouvez ensuite inclure le paramètre system_instruction dans les appels d'API suivants :
- Créer un agent de données persistant : incluez la chaîne
system_instructiondans l'objetpublished_contextdu corps de la requête pour configurer un comportement d'agent qui persiste sur plusieurs conversations. Pour en savoir plus, consultez Créer un agent de données (HTTP) ou Configurer le contexte pour un chat avec ou sans état (SDK Python). - Envoyer une requête sans état : fournissez la chaîne
system_instructiondans l'objetinline_contextde la requête de chat pour définir le comportement de l'agent et le contexte pour la durée de cet appel d'API spécifique. Pour en savoir plus, consultez Créer une conversation multitours sans état (HTTP) ou Envoyer une requête de chat sans état avec un contexte intégré (SDK Python).
Modèle YAML pour les instructions système
Le modèle suivant montre la structure YAML recommandée pour la chaîne que vous fournissez au paramètre system_instruction, y compris les clés disponibles et les types de données attendus. Pour obtenir un exemple d'instruction système avec des valeurs renseignées, consultez Exemple : Instructions système.
Vous pouvez utiliser le modèle YAML suivant pour fournir vos propres instructions système :
- 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.
Composants clés des instructions système
Les sections suivantes décrivent les principaux composants des instructions système et expliquent comment les utiliser pour améliorer la qualité des réponses de votre agent.
Définir le rôle et le persona de l'agent avec system_instruction
Définissez le rôle et le persona de l'agent à l'aide de la clé system_instruction. Cette instruction initiale définit le ton et le style des réponses de l'API, et aide l'agent à comprendre son objectif principal.
Le bloc de code YAML suivant montre la structure de base de la clé system_instrucction :
- system_instruction: str
Par exemple, vous pouvez définir un agent en tant qu'analyste des ventes pour une boutique d'e-commerce fictive comme suit :
- 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.
Décrire vos données avec tables
La clé tables contient une liste de descriptions de tables pour l'agent et fournit des détails sur les données spécifiques dont l'agent dispose pour répondre aux questions. Chaque objet table de cette liste contient les métadonnées d'une table spécifique, y compris son nom, sa description, ses synonymes, ses tags, ses champs, ses mesures, ses requêtes de référence et ses plans d'action de référence.
Le bloc de code YAML suivant montre la structure de base de la clé tables :
- tables:
- table:
- 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: # A list of the fields in the table.
- measures: # A list of the measures in the table.
- golden_queries: # A list of golden queries for the table.
- golden_action_plans: # A list of golden action plans for the table.
Par exemple, le bloc de code YAML suivant montre la structure de base de la clé tables pour la table 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
Décrire les champs couramment utilisés avec fields
La clé fields, imbriquée dans un objet table, accepte une liste d'objets de champ pour décrire les colonnes individuelles. Tous les champs n'ont pas besoin de contexte supplémentaire. Toutefois, pour les champs couramment utilisés, l'ajout de détails supplémentaires peut aider à améliorer les performances de l'agent.
Le bloc de code YAML suivant montre la structure de base de la clé fields :
- 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.
L'exemple de code YAML suivant décrit les champs clés tels que order_id, status, created_at, num_of_items et earnings pour la table 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
Définir des métriques métier avec measures
La clé measures, imbriquée dans un objet table, définit des métriques ou des calculs métier personnalisés qui ne sont pas directement présents sous forme de colonnes dans vos tables. Fournir du contexte pour les mesures aide l'agent à répondre aux questions sur les indicateurs clés de performance (KPI) ou d'autres valeurs calculées.
Le bloc de code YAML suivant montre la structure de base de la clé measures :
- 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.
Par exemple, vous pouvez définir une mesure profit comme un calcul des revenus moins les coûts, comme suit :
- tables:
- table:
- name: bigquery-public-data.thelook_ecommerce.orders
- measures:
- measure:
- name: profit
- description: Raw profit (earnings minus cost).
- exp: earnings - cost
- synonyms:
- gains
Améliorer la précision avec golden_queries
La clé golden_queries, qui est imbriquée dans un objet table, accepte une liste d'objets golden_query. Les requêtes de référence aident l'agent à fournir des réponses plus précises et pertinentes aux questions courantes ou importantes. En fournissant à l'agent à la fois une requête en langage naturel et la requête SQL correspondante pour chaque requête de référence, vous pouvez l'aider à fournir des résultats de meilleure qualité et plus cohérents.
Le bloc de code YAML suivant montre la structure de base de la clé golden_queries :
- 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.
Par exemple, vous pouvez définir des requêtes de référence pour les analyses courantes des données de la table orders comme suit :
- 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'
Décrire des tâches en plusieurs étapes avec golden_action_plans
La clé golden_action_plans, qui est imbriquée dans un objet table, accepte une liste d'objets golden_action_plan. Vous pouvez utiliser des plans d'action de référence pour fournir à l'agent des exemples de gestion des requêtes en plusieurs étapes, comme l'extraction de données et la création d'une visualisation.
Le bloc de code YAML suivant montre la structure de base de la clé golden_action_plans :
- 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.
Par exemple, vous pouvez définir un plan d'action pour afficher la répartition des commandes par tranche d'âge et inclure des informations sur la requête SQL et les étapes liées à la visualisation :
- 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.
Définir des jointures de tables avec relationships
La clé relationships contient une liste des relations de jointure entre les tables. En définissant des relations de jointure, vous pouvez aider l'agent à comprendre comment joindre des données provenant de plusieurs tables lorsqu'il répond à des questions.
Le bloc de code YAML suivant montre la structure de base de la clé relationships :
- relationships: # A list of join relationships between tables.
- relationship: # Details for a single join relationship.
- name: str # A unique name for this join relationship.
- description: str # A description of the relationship.
- relationship_type: str # The join relationship type (e.g., "one-to-one", "one-to-many", "many-to-one", "many-to-many").
- join_type: str # The join type (e.g., "inner", "outer", "left", "right", "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.
Par exemple, vous pouvez définir une relation orders_to_user entre la table bigquery-public-data.thelook_ecommerce.orders et la table bigquery-public-data.thelook_ecommerce.users comme suit :
- 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
Expliquer les termes métier avec glossaries
La clé glossaries liste les définitions de termes métier, le jargon et les abréviations qui ont une pertinence pour vos données et votre cas d'utilisation. En fournissant des définitions de glossaire, vous pouvez aider l'agent à interpréter les questions qui utilisent un langage métier spécifique et à y répondre avec précision.
Le bloc de code YAML suivant montre la structure de base de la clé glossaries :
- 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.
Par exemple, vous pouvez définir des termes tels que les états d'activité courants et "OMPF" en fonction de votre contexte métier spécifique, comme suit :
- 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
Inclure des instructions supplémentaires avec additional_descriptions
La clé additional_descriptions liste toutes les instructions générales ou le contexte supplémentaires qui ne sont pas couverts ailleurs dans les instructions système. En fournissant des descriptions supplémentaires, vous pouvez aider l'agent à mieux comprendre le contexte de vos données et de votre cas d'utilisation.
Le bloc de code YAML suivant montre la structure de base de la clé additional_descriptions :
- additional_descriptions: # A list of any other general instructions or content.
- text: str # Any additional general instructions or context not covered elsewhere.
Par exemple, vous pouvez utiliser la clé additional_descriptions pour fournir des informations sur votre organisation comme suit :
- 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.'
Exemple : Instructions système
L'exemple suivant montre des instructions système pour un agent devant se comporter comme un analyste des ventes.
- 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.'