Définir le contexte de l'agent de données pour les sources de données BigQuery

Le contexte créé est une guidance que les propriétaires d'agents de données peuvent fournir pour façonner le comportement d'un agent de données et affiner les réponses de l'API. Un contexte créé efficace fournit à vos agents de données de l'API Conversational Analytics un contexte utile pour répondre aux questions sur vos sources de données.

Cette page explique comment fournir un contexte créé pour les sources de données BigQuery. Pour les sources de données BigQuery, vous pouvez fournir un contexte créé en combinant un contexte structuré et des instructions système. Dans la mesure du possible, fournissez du contexte à l'aide de champs de contexte structurés. Vous pouvez ensuite utiliser le paramètre system_instruction pour obtenir des conseils supplémentaires qui ne sont pas couverts par les champs structurés.

Bien que les champs de contexte structuré et les instructions système soient facultatifs, fournir un contexte solide permet à l'agent de donner des réponses plus précises et pertinentes.

Une fois que vous avez défini les champs structurés et les instructions système qui composent votre contexte créé, vous pouvez fournir ce contexte à l'API dans l'un des appels suivants :

Définir des champs de contexte structurés

Cette section explique comment fournir du contexte à un agent de données à l'aide de champs de contexte structurés. Vous pouvez fournir les informations suivantes à un agent en tant que contexte structuré :

Contexte structuré au niveau du tableau

Utilisez la clé tableReferences pour fournir à un agent des informations sur les tables spécifiques disponibles pour répondre aux questions. Pour chaque référence de table, vous pouvez utiliser les champs de contexte structuré suivants pour définir le schéma d'une table :

  • description : résumé du contenu et de l'objectif de la table
  • synonyms : liste des termes alternatifs pouvant être utilisés pour désigner la table
  • tags : liste de mots clés ou de tags associés à la table.

Les exemples suivants montrent comment fournir ces propriétés en tant que contexte structuré dans des requêtes HTTP directes et avec le SDK Python.

HTTP

Dans une requête HTTP directe, vous fournissez ces propriétés au niveau de la table dans l'objet schema pour la référence de table concernée. Pour obtenir un exemple complet de la structure du corps de la requête, consultez Se connecter aux données 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 Python

Lorsque vous utilisez le SDK Python, vous pouvez définir ces propriétés au niveau du tableau sur la propriété schema d'un objet BigQueryTableReference. L'exemple suivant montre comment créer des objets de référence de table qui fournissent le contexte pour les tables orders et users. Pour obtenir un exemple complet de création et d'utilisation d'objets de référence de table, consultez Se connecter aux données 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"]

Contexte structuré au niveau des colonnes

La clé fields, imbriquée dans l'objet schema d'une référence de table, accepte une liste d'objets field 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.

Pour chaque objet field, vous pouvez utiliser les champs de contexte structuré suivants pour définir les propriétés fondamentales d'une colonne :

  • description : brève description du contenu et de l'objectif de la colonne
  • synonyms : liste des autres termes pouvant être utilisés pour désigner la colonne.
  • tags : liste de mots clés ou de tags associés à la colonne.

Les exemples suivants montrent comment fournir ces propriétés en tant que contexte structuré pour le champ status dans le tableau orders et pour le champ first_name dans le tableau users avec des requêtes HTTP directes et avec le SDK Python.

HTTP

Dans une requête HTTP directe, vous pouvez définir ces propriétés au niveau des colonnes en fournissant une liste d'objets fields dans l'objet schema d'une référence de table.

"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 Python

Lorsque vous utilisez le SDK Python, vous pouvez définir ces propriétés au niveau des colonnes en attribuant une liste d'objets Field à la propriété fields de la propriété schema d'une table.

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

Exemples de requêtes

La clé example_queries accepte une liste d'objets example_query pour définir des requêtes en langage naturel qui aident l'agent à fournir des réponses plus précises et pertinentes aux questions courantes ou importantes. En fournissant à l'agent à la fois une question en langage naturel et la requête SQL correspondante, vous pouvez l'aider à fournir des résultats de meilleure qualité et plus cohérents.

Pour chaque objet example_query, vous pouvez fournir les champs suivants pour définir une question en langage naturel et la requête SQL correspondante :

  • natural_language_question : question en langage naturel qu'un utilisateur peut poser
  • sql_query : requête SQL correspondant à la question en langage naturel

Les exemples suivants montrent comment fournir des exemples de requêtes pour la table orders à l'aide de requêtes HTTP directes et du SDK Python.

HTTP

Dans une requête HTTP directe, fournissez une liste d'objets example_query dans le champ example_queries. Chaque objet doit contenir une clé naturalLanguageQuestion et une clé sqlQuery correspondante.

"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 Python

Lorsque vous utilisez le SDK Python, vous pouvez fournir une liste d'objets ExampleQuery. Pour chaque objet, indiquez des valeurs pour les paramètres natural_language_question et 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'",
    )
]

Définir un contexte supplémentaire dans les instructions système

Vous pouvez utiliser le paramètre system_instruction pour fournir des conseils supplémentaires sur le contexte qui n'est pas pris en charge par les champs de contexte structurés. En fournissant ces conseils supplémentaires, vous pouvez aider l'agent à mieux comprendre le contexte de vos données et de votre cas d'utilisation.

Les instructions système se composent d'une série de composants et d'objets clés qui fournissent à l'agent de données des informations sur la source de données et des conseils sur son rôle lorsqu'il répond à des questions. Vous pouvez fournir des instructions système à l'agent de données dans le paramètre system_instruction sous la forme d'une chaîne au format YAML.

Le modèle suivant montre une structure YAML suggérée pour la chaîne que vous pouvez fournir au paramètre system_instruction pour une source de données BigQuery, y compris les clés disponibles et les types de données attendus. Bien que ce modèle propose une structure suggérée avec des composants importants pour définir les instructions système, il n'inclut pas tous les formats d'instructions système possibles.

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

Les sections suivantes présentent des exemples de composants clés pour les instructions système :

system_instruction

Utilisez la clé system_instruction pour définir le rôle et le persona de l'agent. Cette instruction initiale définit le ton et le style des réponses de l'API, et aide l'agent à comprendre son objectif principal.

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.

tables

Alors que vous définissez les propriétés fondamentales d'une table (comme sa description et ses synonymes) en tant que contexte structuré, vous pouvez également utiliser la clé tables dans les instructions système pour fournir une logique métier supplémentaire. Pour les sources de données BigQuery, cela inclut l'utilisation de la clé fields pour définir des aggregations par défaut pour des colonnes spécifiques.

L'exemple de bloc de code YAML suivant montre comment utiliser la clé tables dans vos instructions système pour imbriquer des champs qui fournissent des conseils supplémentaires pour le tableau 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 clé relationships de vos instructions système 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.

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

glossaries

La clé glossaries dans vos instructions système 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.

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

additional_descriptions

Utilisez la clé additional_descriptions pour fournir des instructions générales ou un contexte qui ne correspond pas aux autres champs de contexte structuré ou d'instructions système. En fournissant des descriptions supplémentaires dans vos instructions système, vous pouvez aider l'agent à mieux comprendre le contexte de vos données et de votre cas d'utilisation.

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 : Contexte créé pour un agent commercial

L'exemple suivant pour un agent devant se comporter comme un analyste des ventes montre comment fournir un contexte créé en combinant un contexte structuré et des instructions système.

Exemple : Contexte structuré

Vous pouvez fournir un contexte structuré avec des détails sur les tables, les colonnes et des exemples de requêtes pour guider l'agent, comme illustré dans les exemples HTTP et SDK Python suivants.

HTTP

L'exemple suivant montre comment définir un contexte structuré dans une requête 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 Python

L'exemple suivant montre comment définir un contexte structuré avec le SDK 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'",
  )
]

Exemple : Instructions système

Les instructions système suivantes complètent le contexte structuré en définissant le persona de l'agent et en fournissant des conseils qui ne sont pas pris en charge par les champs structurés, tels que les définitions de relations, les termes du glossaire, les descriptions supplémentaires et les détails supplémentaires du tableau orders. Dans cet exemple, comme la table users est entièrement définie avec un contexte structuré, il n'est pas nécessaire de la redéfinir dans les instructions système.

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