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

Cette page explique comment rédiger des instructions système pour les agents de données qui utilisent des sources de données Looker, basées sur les explorations Looker.

Le contexte créé est un ensemble de consignes 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.

Pour les sources de données Looker, vous pouvez fournir un contexte créé en combinant un contexte structuré et des instructions système. Dans la mesure du possible, fournissez le contexte via des 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. Les instructions système sont un type de contexte créé que les propriétaires d'agents de données peuvent fournir à un agent pour l'informer de son rôle, de son ton et de son comportement général. Les instructions système sont souvent plus libres que le contexte structuré.

Bien que les champs de contexte structurés et les instructions système soient facultatifs, fournir un contexte robuste permet à l'agent de fournir des réponses plus précises et pertinentes. Lors de la création de votre agent de données, toutes les informations de contexte structurées que vous avez fournies seront automatiquement ajoutées aux instructions système.

Définir un contexte structuré

Vous pouvez fournir des questions et réponses de référence dans un contexte structuré pour votre agent de données. Une fois que vous avez défini votre contexte structuré, vous pouvez le fournir à votre agent de données à l'aide de requêtes HTTP directes ou du SDK Python.

Pour les sources de données Looker, les requêtes de référence sont capturées dans la clé looker_golden_queries, qui définit des paires de questions en langage naturel et leurs requêtes Looker correspondantes. En fournissant à l'agent une paire de questions en langage naturel et les métadonnées d'exploration correspondantes, vous pouvez l'aider à fournir des résultats de meilleure qualité et plus cohérents. Exemples de requêtes de référence Looker sont inclus sur cette page.

Pour définir chaque requête de référence Looker, fournissez des valeurs pour les deux champs suivants :

  • natural_language_questions: question en langage naturel qu'un utilisateur peut poser
  • looker_query: requête de référence Looker qui correspond à la question en langage naturel

Voici un exemple de paire natural_language_questions — looker_query à partir d'une exploration appelée "Airports" :

  natural_language_questions: ["What are the major airport codes and cities in CA?"]
  looker_query": {
        "model": "airports",
        "explore": "airports",
        "fields": ["airports.city", "airports.code"],
        "filters": [
          {
            "field": "airports.major",
            "value": "Y"
          },
          {
            "field": "airports.state",
            "value": "CA"
          }
        ]
  }

Définir une requête de référence Looker

Définissez une requête de référence Looker pour une exploration donnée en fournissant des valeurs pour les champs natural_language_questions et looker_query. Pour le champ natural_language_questions, réfléchissez aux questions qu'un utilisateur peut poser sur cette exploration et rédigez-les en langage naturel. Vous pouvez inclure plusieurs questions dans la valeur de ce champ. Vous pouvez obtenir la valeur du champ looker_query à partir des métadonnées de requête de l'exploration.

L'objet Looker Query Object accepte les champs suivants :

  • model (chaîne) : modèle LookML utilisé pour générer la requête. Il s'agit d'un champ obligatoire.
  • explore (chaîne) : exploration utilisée pour générer la requête. Il s'agit d'un champ obligatoire.
  • fields[] (chaîne) : champs à récupérer à partir de l'exploration, y compris les dimensions et les mesures. Ce champ est facultatif.
  • filters[] (objet (Filtre)) : filtres à appliquer à l'exploration. Ce champ est facultatif.
  • sorts[] (chaîne) : tri à appliquer à l'exploration. Ce champ est facultatif.
  • limit (chaîne) : limite de lignes de données à appliquer à l'exploration. Ce champ est facultatif.

Vous pouvez récupérer les métadonnées de requête de l'exploration de différentes manières :

Récupérer les métadonnées de requête à partir de l'interface utilisateur "Explorer"

  1. Dans l'exploration, sélectionnez le menu Actions sur les explorations , puis Obtenir LookML.
  2. Sélectionnez l'onglet Tableau de bord.
  3. Copiez les détails de la requête à partir du code LookML. Par exemple, l'image suivante montre le code LookML d'une exploration appelée "Order Items" :

Copiez les métadonnées sélectionnées pour les utiliser dans votre requête de référence Looker :

  model: thelook
  explore: order_items
  fields: [order_items.order_id, orders.status]
  sorts: [orders.status, order_items.order_id]
  limit: 500

Récupérer l'objet de requête Looker à l'aide de l'API Looker

Pour récupérer des informations sur votre exploration à l'aide de l'API Looker, procédez comme suit :

  1. Dans l'exploration, sélectionnez le menu Actions sur les explorations , puis Partager. Looker affiche les URL que vous pouvez copier pour partager l'exploration. Les URL de partage se présentent généralement comme suit : https://looker.yourcompany/x/vwGSbfc. Le suffixe vwGSbfc de l'URL de partage est le slug de partage.
  2. Copiez le slug de partage.
  3. Envoyez une requête à l'API Looker : GET /queries/slug/Explore_slug en transmettant le slug de l'URL de l'exploration sous forme de chaîne dans Explore_slug. Dans votre requête, incluez les champs des métadonnées de requête de votre exploration que vous souhaitez renvoyer. Pour en savoir plus, consultez la page de référence de l'API Get Query for Slug.
  4. Copiez les métadonnées de requête à partir de la réponse de l'API.

Exemples de requêtes de référence Looker

Les exemples suivants montrent comment fournir des requêtes de référence pour l'exploration airports avec des requêtes HTTP directes et avec le SDK Python.

HTTP

Dans une requête HTTP directe, fournissez une liste d'objets de requête de référence Looker pour la clé looker_golden_queries. Chaque objet doit contenir une clé natural_Language_questions et une clé looker_query correspondante.

looker_golden_queries = [
  {
    "natural_language_questions": ["What is the highest observed positive longitude?"],
    "looker_query": {
      "model": "airports",
      "explore": "airports",
      "fields": ["airports.longitude"],
      "filters": [
        {
          "field": "airports.longitude",
          "value": ">0"
        }
      ],
      "sorts": ["airports.longitude desc"],
      "limit": "1"
    }
  },
 {
    "natural_language_questions": ["What are the major airport codes and cities in CA?", "Can you list the cities and airport codes of airports in CA?"],
    "looker_query": {
      "model": "airports",
      "explore": "airports",
      "fields": ["airports.city", "airports.code"],
      "filters": [
        {
          "field": "airports.major",
          "value": "Y"
        },
        {
          "field": "airports.state",
          "value": "CA"
        }
      ]
    }
  },
]

SDK Python

Lorsque vous utilisez le SDK Python, vous pouvez fournir une liste d'objets LookerGoldenQuery. Pour chaque objet, fournissez des valeurs pour les paramètres natural_language_questions et looker_query.

looker_golden_queries = [geminidataanalytics.LookerGoldenQuery(
      natural_language_questions=[
          "What is the highest observed positive longitude?"
      ],
      looker_query=geminidataanalytics.LookerQuery(
          model="airports",
          explore="airports",
          fields=["airports.longitude"],
          filters=[
              geminidataanalytics.LookerQuery.Filter(
                  field="airports.longitude", value=">0"
              )
          ],
          sorts=["airports.longitude desc"],
          limit="1",
      ),
  ),
  geminidataanalytics.LookerGoldenQuery(
      natural_language_questions=[
          "What are the major airport codes and cities in CA?",
          "Can you list the cities and airport codes of airports in CA?",
      ],
      looker_query=geminidataanalytics.LookerQuery(
          model="airports",
          explore="airports",
          fields=["airports.city", "airports.code"],
          filters=[
              geminidataanalytics.LookerQuery.Filter(
                  field="airports.major", value="Y"
              ),
              geminidataanalytics.LookerQuery.Filter(
                  field="airports.state", value="CA"
              ),
          ],
      ),
  ),
]

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

Les instructions système se composent d'une série de composants clés et d'objets qui fournissent à l'agent de données des informations sur la source de données et des conseils sur le rôle de l'agent 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 YAML suivant montre un exemple de structure possible pour les instructions système d'une source de données Looker :

-   system_instruction: str # Describe the expected behavior of the agent
-   glossaries: # Define business terms, jargon, and abbreviations that are relevant to your use case
    -   glossary:
            -   term: str
            -   description: str
            -   synonyms: list[str]
-   additional_descriptions: # List any additional general instructions
    -   text: str

Descriptions des composants clés des instructions système

Les sections suivantes présentent des exemples de composants de clés pour les instructions système dans Looker. Voici certaines de ces clés :

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.

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, mais qui n'apparaissent pas déjà dans vos données. Par exemple, vous pouvez définir des termes tels que les états d'activité courants et "Loyal Customer" en fonction de votre contexte métier spécifique comme suit :

-   glossaries:
    -   glossary:
            -   term: Loyal Customer
            -   description: A customer who has made more than one purchase.
                Maps to the dimension 'user_order_facts.repeat_customer' being
                'Yes'. High value loyal customers are those with high
                'user_order_facts.lifetime_revenue'.
            -   synonyms:
                -   repeat customer
                -   returning customer

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. Par exemple, vous pouvez utiliser la clé additional_descriptions pour fournir des informations sur votre agent comme suit :

-   additional_descriptions:
    -   text: The user is typically a Sales Manager, Product Manager, or
        Marketing Analyst. They need to understand performance trends, build
        customer lists for campaigns, and analyze product sales.

Exemple : Instructions système dans Looker

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, product, and operations
    analyst for our e-commerce store. Your primary function is to answer
    questions by querying the 'Order Items' Explore. Always be concise and
    data-driven. When asked about 'revenue' or 'sales', use
    'order_items.total_sale_price'. For 'profit' or 'margin', use
    'order_items.total_gross_margin'. For 'customers' or 'users', use
    'users.count'. The default date for analysis is 'order_items.created_date'
    unless specified otherwise. For advanced statistical questions, such as
    correlation or regression analysis, use the Python tool to fetch the
    necessary data, perform the calculation, and generate a plot (like a scatter
    plot or heatmap)."
-   glossaries:
    -   term: Revenue
    -   description: The total monetary value from items sold. Maps to the
        measure 'order_items.total_sale_price'.
    -   synonyms:
        -   sales
        -   total sales
        -   income
        -   turnover
    -   term: Profit
    -   description: Revenue minus the cost of goods sold. Maps to the measure
        'order_items.total_gross_margin'.
    -   synonyms:
        -   margin
        -   gross margin
        -   contribution
    -   term: Buying Propensity
    -   description: Measures the likelihood of a customer to purchase again
        soon. Primarily maps to the 'order_items.30_day_repeat_purchase_rate'
        measure.
    -   synonyms:
        -   repeat purchase rate
        -   repurchase likelihood
        -   customer velocity
    -   term: Customer Lifetime Value
    -   description: The total revenue a customer has generated over their
        entire history with us. Maps to 'user_order_facts.lifetime_revenue'.
    -   synonyms:
        -   CLV
        -   LTV
        -   lifetime spend
        -   lifetime value
    -   term: Loyal Customer
    -   description: "A customer who has made more than one purchase. Maps to
        the dimension 'user_order_facts.repeat_customer' being 'Yes'. High value
        loyal customers are those with high
        'user_order_facts.lifetime_revenue'."
    -   synonyms:
        -   repeat customer
        -   returning customer
    -   term: Active Customer
    -   description: "A customer who is currently considered active based on
        their recent purchase history. Mapped to
        'user_order_facts.currently_active_customer' being 'Yes'."
    -   synonyms:
        -   current customer
        -   engaged shopper
    -   term: Audience
    -   description: A list of customers, typically identified by their email
        address, for marketing or analysis purposes.
    -   synonyms:
        -   audience list
        -   customer list
        -   segment
    -   term: Return Rate
    -   description: The percentage of items that are returned by customers
        after purchase. Mapped to 'order_items.return_rate'.
    -   synonyms:
        -   returns percentage
        -   RMA rate
    -   term: Processing Time
    -   description: The time it takes to prepare an order for shipment from the
        moment it is created. Maps to 'order_items.average_days_to_process'.
    -   synonyms:
        -   fulfillment time
        -   handling time
    -   term: Inventory Turn
    -   description: "A concept related to how quickly stock is sold. This can
        be analyzed using 'inventory_items.days_in_inventory' (lower days means
        higher turn)."
    -   synonyms:
        -   stock turn
        -   inventory turnover
        -   sell-through
    -   term: New vs Returning Customer
    -   description: "A classification of whether a purchase was a customer's
        first ('order_facts.is_first_purchase' is Yes) or if they are a repeat
        buyer ('user_order_facts.repeat_customer' is Yes)."
    -   synonyms:
        -   customer type
        -   first-time buyer
-   additional_descriptions:
    -   text: The user is typically a Sales Manager, Product Manager, or
        Marketing Analyst. They need to understand performance trends, build
        customer lists for campaigns, and analyze product sales.
    -   text: This agent can answer complex questions by joining data about
        sales line items, products, users, inventory, and distribution centers.

Étape suivante

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 Conversational Analytics dans l'un des appels suivants :