Definisci il contesto dell'agente dati per le origini dati di Looker

Il contesto creato è una guida che i proprietari degli agenti di dati possono fornire per modellare il comportamento di un agente di dati e perfezionare le risposte dell'API. Un contesto creato in modo efficace fornisce 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 come scrivere istruzioni di sistema per le origini dati di Looker, che si basano sulle esplorazioni di Looker. Quando ti connetti alle esplorazioni di Looker, fornisci il contesto creato agli agenti di dati esclusivamente tramite le istruzioni di sistema.

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.

Dopo aver definito le istruzioni di sistema che compongono il contesto creato, puoi fornire questo contesto all'API in una delle seguenti chiamate:

Il seguente modello YAML mostra un esempio di come potresti strutturare le istruzioni di sistema per un'origine dati di Looker:

- system_instruction: str # Describe the expected behavior of the agent
  - golden_queries: # Define queries for common analyses of your Explore data
    - golden_query:
      - natural_language_query: str
      - looker_query: str
        - model: string
        - view: string
        - fields: list[str]
        - filters: list[str]
        - sorts: list[str]
        - limit: str
        - query_timezone: str
- 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

Descrizioni dei componenti chiave delle istruzioni di sistema

Le seguenti sezioni contengono esempi di componenti chiave delle istruzioni di sistema in Looker. Queste chiavi includono:

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.

golden_queries

La chiave golden_queries 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. Fornendo all'agente sia una query in linguaggio naturale sia la query Looker e le informazioni LookML corrispondenti per ogni query di riferimento, puoi guidarlo a fornire risultati di qualità superiore e più coerenti. Ad esempio, puoi definire query di riferimento per analisi comuni per i dati nella tabella order_items nel seguente modo:

- golden_queries:
  - natural_language_query: what were total sales over the last year
  - looker_query:
      - model: thelook
      - view: order_items
      - fields: order_items.total_sale_price
      - filters: order_items.created_date: last year
      - sorts: order_items.total_sale_price desc 0
      - limit: null
      - query_timezone: America/Los_Angeles

glossaries

L'glossarieselenco delle chiavi contiene le definizioni di termini aziendali, gergo e abbreviazioni pertinenti ai tuoi dati e al tuo caso d'uso, ma che non sono ancora presenti nei tuoi dati. Ad esempio, puoi definire termini come stati aziendali comuni e "Cliente fedele" in base al contesto aziendale specifico nel seguente modo:

- 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

Il tasto additional_descriptions elenca eventuali istruzioni generali o contesto aggiuntivi non trattati altrove nelle istruzioni di sistema. Ad esempio, puoi utilizzare il tasto additional_descriptions per fornire informazioni sul tuo agente nel seguente modo:

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

Esempio: istruzioni di sistema in Looker utilizzando YAML

Il seguente esempio mostra istruzioni di sistema di esempio per un agente analista delle vendite fittizio.

- 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)."
  - golden_queries:
    - golden_query:
      - question: what were total sales over the last year
      - looker_query:
        - model: thelook
        - view: order_items
        - fields: order_items.total_sale_price
          - filters: order_items.created_date: last year
        - sorts: []
        - limit: null
        - query_timezone: America/Los_Angeles
      - question: Show monthly profit for the last year, pivoted on product category for Jeans and Accessories.
      - looker_query:
        - model: thelook
        - view: order_items
        - fields:
          - name: products.category
          - name: order_items.total_gross_margin
          - name: order_items.created_month_name
        - filters:
          - products.category: Jeans,Accessories
          - order_items.created_date: last year
        - pivots: products.category
        - sorts:
          - order_items.created_month_name asc
          - order_items.total_gross_margin desc 0
        - limit: null
        - query_timezone: America/Los_Angeles
      - question: what were total sales over the last year break it down by brand only include
    brands with over 50000 in revenue
      - looker_query:
        - model: thelook
        - view: order_items
        - fields:
          - order_items.total_sale_price
          - products.brand
        - filters:
          - order_items.created_date: last year
          - order_items.total_sale_price: '>50000'
        - sorts: order_items.total_sale_price desc 0
        - limit: null
        - query_timezone: America/Los_Angeles
      - question: What is the buying propensity by Brand?
      - looker_query:
          - model: thelook
          - view: order_items
          - fields:
            - order_items.30_day_repeat_purchase_rate
            - products.brand
          - filters: {}
          - sorts: order_items.30_day_repeat_purchase_rate desc 0
          - limit: '10'
          - query_timezone: America/Los_Angeles
      - question: How many items are still in 'Processing' status for more than 3 days,
    by Distribution Center?
      - looker_query:
        - model: thelook
        - view: order_items
        - fields:
          - distribution_centers.name
          - order_items.count
        - filters:
            - order_items.created_date: before 3 days ago
            - order_items.status: Processing
        - sorts: order_items.count desc
        - limit: null
        - query_timezone: America/Los_Angeles
      - question: Show me total cost of unsold inventory for the 'Outerwear' category
      - looker_query:
        - model: thelook
        - view: inventory_items
        - fields: inventory_items.total_cost
        - filters:
          - inventory_items.is_sold: No
          - products.category: Outerwear
        - sorts: []
        - limit: null
        - query_timezone: America/Los_Angeles
      - question: let's build an audience list of customers with a lifetime value over $1,000,
    including their email and state, who came from Facebook or Search and live in
    the United States.
      - looker_query:
        - model: thelook
        - view: users
        - fields:
          - users.email
          - users.state
          - user_order_facts.lifetime_revenue
        - filters:
          - user_order_facts.lifetime_revenue: '>1000'
          - users.country: United States
          - users.traffic_source: Facebook,Search
        - sorts: user_order_facts.lifetime_revenue desc 0
        - limit: null
        - query_timezone: America/Los_Angeles
      - question: Show me a list of my most loyal customers and when their last order was.
      - looker_query:
        - model: thelook
        - view: users
        - fields:
          - users.id
          - users.email
          - user_order_facts.lifetime_revenue
          - user_order_facts.lifetime_orders
          - user_order_facts.latest_order_date
        - filters: user_order_facts.repeat_customer: Yes
        - sorts: user_order_facts.lifetime_revenue desc
        - limit: '50'
        - query_timezone: America/Los_Angeles
      - question: What's the breakdown of customers by age tier?
      - looker_query:
        - model: thelook
        - view: users
        - fields:
          - users.age_tier
          - users.count
        - filters: {}
        - sorts: users.count desc
        - limit: null
        - query_timezone: America/Los_Angeles
      - question: What is the total revenue from new customers acquired this year?
      - looker_query:
        - model: thelook
        - view: order_items
        - fields: order_items.total_sale_price
        - filters: user_order_facts.first_order_year: this year
        - sorts: []
        - limit: null
        - query_timezone: America/Los_Angeles
- 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.