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, lesquelles sont basées sur les explorations Looker.

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.

Pour les sources de données Looker, vous pouvez fournir un contexte créé en combinant le contexte structuré et les instructions système. Dans la mesure du possible, fournissez du contexte à l'aide 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 peuvent souvent être plus libres que le contexte structuré.

Bien que les champs de contexte structuré et les instructions système soient facultatifs, fournir un contexte solide permet à l'agent de fournir des réponses plus précises et pertinentes. Lorsque vous créez votre agent de données, toute information contextuelle structurée que vous avez fournie est automatiquement ajoutée aux instructions système.

Définir un contexte structuré

Vous pouvez fournir des questions et des 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 avec le 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 Explore correspondantes, vous pouvez l'aider à fournir des résultats de meilleure qualité et plus cohérents. Des exemples de requêtes parfaites Looker sont inclus sur cette page.

Pour définir chaque requête en or Looker, indiquez 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 correspondant à la question en langage naturel

Voici un exemple de paire natural_language_questions – looker_query provenant d'une exploration appelée "Aéroports" :

  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 en or 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 pourrait 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 la requête Explore.

L'objet de requête Looker accepte les champs suivants :

  • model (chaîne) : modèle LookML utilisé pour générer la requête. Ce champ est obligatoire.
  • explore (chaîne) : exploration utilisée pour générer la requête. Ce champ est 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(Filter)) : 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 Explore de plusieurs manières :

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

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

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 "Explorer", sélectionnez le menu Actions sur les explorations, puis Partager. Looker affiche des URL que vous pouvez copier pour partager l'exploration. Les URL de partage ressemblent généralement à ceci : https://looker.yourcompany/x/vwGSbfc. Le vwGSbfc de fin dans 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 votre requête Explorer que vous souhaitez renvoyer. Pour en savoir plus, consultez la page de documentation de référence de l'API Get Query for Slug.
  4. Copiez les métadonnées de la 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 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, indiquez les valeurs des 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 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 YAML suivant montre un exemple de structure d'instructions système pour 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

Description 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 "Client fidèle" 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.

Étapes suivantes

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 :