Kontext für KI-Datenagenten für Looker-Datenquellen definieren

Erstellter Kontext ist eine Anleitung, die Eigentümer von Daten-Agents bereitstellen können, um das Verhalten eines Daten-Agents zu beeinflussen und die Antworten der API zu optimieren. Ein effektiver Kontext, den Sie selbst erstellen, liefert Ihren Daten-KI-Agenten der Conversational Analytics API nützliche Informationen, um Fragen zu Ihren Datenquellen zu beantworten. Systemanweisungen sind eine Art von Kontext, den Inhaber von Daten-Agenten bereitstellen können, um das Verhalten eines Daten-Agenten zu beeinflussen und die Antworten der API zu optimieren.

Auf dieser Seite wird beschrieben, wie Sie Systemanweisungen für Looker-Datenquellen schreiben, die auf Looker-Explores basieren. Wenn Sie eine Verbindung zu Looker-Explores herstellen, stellen Sie Daten-Agents ausschließlich über Systemanweisungen selbst erstellten Kontext zur Verfügung.

Kontext in Systemanweisungen definieren

Systemanweisungen bestehen aus einer Reihe von Schlüsselkomponenten und ‑objekten, die dem KI-Datenagenten Details zur Datenquelle und Anleitungen zur Rolle des Agenten beim Beantworten von Fragen liefern. Sie können dem Daten-Agent Systemanweisungen als YAML-formatierte Zeichenfolge über den Parameter system_instruction bereitstellen.

Nachdem Sie die Systemanweisungen definiert haben, aus denen Ihr erstellter Kontext besteht, können Sie diesen Kontext in einem der folgenden Aufrufe an die API übergeben:

Die folgende YAML-Vorlage zeigt ein Beispiel dafür, wie Sie Systemanweisungen für eine Looker-Datenquelle strukturieren können:

- 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

Beschreibungen der wichtigsten Komponenten von Systemanweisungen

Die folgenden Abschnitte enthalten Beispiele für wichtige Komponenten von Systemanweisungen in Looker. Dazu gehören die folgenden Schlüssel:

system_instruction

Verwenden Sie den Schlüssel system_instruction, um die Rolle und Persona des Agenten zu definieren. Mit dieser ersten Anweisung werden Ton und Stil für die Antworten der API festgelegt und dem Agenten wird sein Hauptzweck verdeutlicht.

Sie können einen Agenten beispielsweise als Vertriebsanalyst für ein fiktives E-Commerce-Unternehmen definieren:

- 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

Der Schlüssel golden_queries akzeptiert eine Liste von golden_query-Objekten. Mithilfe von Golden Queries kann der Agent genauere und relevantere Antworten auf häufige oder wichtige Fragen geben, die Sie definieren können. Wenn Sie dem Agenten sowohl eine Anfrage in natürlicher Sprache als auch die entsprechende Looker-Abfrage und LookML-Informationen für jede Golden Query zur Verfügung stellen, können Sie ihn anleiten, qualitativ hochwertige und konsistente Ergebnisse zu liefern. Sie können beispielsweise Gold-Abfragen für häufige Analysen für die Daten in der Tabelle order_items so definieren:

- 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

Unter glossaries finden Sie Definitionen für geschäftliche Begriffe, Fachsprache und Abkürzungen, die für Ihre Daten und Ihren Anwendungsfall relevant sind, aber noch nicht in Ihren Daten enthalten sind. Sie können beispielsweise Begriffe wie allgemeine Unternehmensstatus und „treuer Kunde“ entsprechend Ihrem spezifischen geschäftlichen Kontext so definieren:

- 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

Unter dem Schlüssel additional_descriptions werden alle zusätzlichen allgemeinen Anweisungen oder der Kontext aufgeführt, die nicht an anderer Stelle in den Systemanweisungen behandelt werden. Mit dem Schlüssel additional_descriptions können Sie beispielsweise Informationen zu Ihrem Agenten angeben:

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

Beispiel: Systemanweisungen in Looker mit YAML

Das folgende Beispiel zeigt Beispielsystemanweisungen für einen fiktiven Agent für die Vertriebsanalyse.

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