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

Questa pagina descrive come scrivere istruzioni di sistema per gli agenti di dati che utilizzano origini dati di Looker, basate su esplorazioni 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.

Per le origini dati Looker, puoi fornire un contesto creato tramite una combinazione di contesto strutturato e istruzioni di sistema. Se possibile, fornisci il contesto tramite i campi di contesto strutturato. Puoi quindi utilizzare il parametro system_instruction per indicazioni supplementari non coperte dai campi strutturati. Le istruzioni di sistema sono un tipo di contesto creato che i proprietari degli agenti di dati possono fornire a un agente per informarlo del suo ruolo, del tono e del comportamento generale. Spesso le istruzioni di sistema possono essere più libere rispetto al contesto strutturato.

Sebbene sia i campi di contesto strutturato sia le istruzioni di sistema siano facoltativi, fornire un contesto solido consente all'agente di fornire risposte più accurate e pertinenti. Durante la creazione dell'agente dati, tutte le informazioni di contesto strutturate che hai fornito verranno aggiunte automaticamente alle istruzioni di sistema.

Definisci il contesto strutturato

Puoi fornire domande e risposte di riferimento in un contesto strutturato per l'agente dei dati. Una volta definito il contesto strutturato, puoi fornirlo all'agente dati utilizzando richieste HTTP dirette o con l'SDK Python.

Per le origini dati Looker, le query dorate vengono acquisite nella chiave looker_golden_queries, che definisce coppie di domande in linguaggio naturale e le query Looker corrispondenti. Fornendo all'agente una coppia di domande in linguaggio naturale e i relativi metadati di Explore, puoi guidarlo a fornire risultati di qualità superiore e più coerenti. In questa pagina sono inclusi esempi di query dorate di Looker.

Per definire ogni query di riferimento di Looker, fornisci i valori per entrambi i seguenti campi:

  • natural_language_questions: La domanda in linguaggio naturale che un utente potrebbe porre
  • looker_query: la query di riferimento di Looker che corrisponde alla domanda in linguaggio naturale

Ecco un esempio di coppia natural_language_questions - looker_query di un'esplorazione chiamata "Aeroporti":

  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"
          }
        ]
  }

Definisci una query di riferimento di Looker

Definisci una query di riferimento di Looker per una determinata esplorazione fornendo valori per i campi natural_language_questions e looker_query. Per il campo natural_language_questions, considera le domande che un utente potrebbe porre su questa esplorazione e scrivile in linguaggio naturale. Puoi includere più di una domanda nel valore di questo campo. Puoi ottenere il valore per il campo looker_query dai metadati della query di Esplora.

L'oggetto query di Looker supporta i seguenti campi:

  • model (stringa): il modello LookML utilizzato per generare la query. Questo è un campo obbligatorio.
  • explore (stringa): l'esplorazione utilizzata per generare la query. Questo è un campo obbligatorio.
  • fields[] (stringa): i campi da recuperare da Explore, incluse dimensioni e metriche. Questo è un campo facoltativo.
  • filters[] (object (Filter)): I filtri da applicare all'esplorazione. Questo è un campo facoltativo.
  • sorts[] (stringa): l'ordinamento da applicare all'esplorazione. Questo è un campo facoltativo.
  • limit (stringa): il limite di righe di dati da applicare all'esplorazione. Questo è un campo facoltativo.

Puoi recuperare i metadati della query di Esplora nei seguenti modi:

Recupera i metadati della query dall'interfaccia utente di Esplora

  1. In Esplora, seleziona il menu Azioni di Esplora e poi seleziona Ottieni LookML.
  2. Seleziona la scheda Dashboard.
  3. Copia i dettagli della query da LookML. Ad esempio, l'immagine seguente mostra il codice LookML per un'esplorazione chiamata Articoli dell'ordine:

Copia i metadati selezionati da utilizzare nella query dorata di Looker:

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

Recuperare l'oggetto query di Looker utilizzando l'API Looker

Per recuperare informazioni sull'esplorazione utilizzando l'API Looker, segui questi passaggi:

  1. In Esplora, seleziona il menu Azioni di Esplora e poi seleziona Condividi. Looker mostra gli URL che puoi copiare per condividere l'esplorazione. Gli URL di condivisione in genere hanno un aspetto simile a https://looker.yourcompany/x/vwGSbfc. Il vwGSbfc finale nell'URL di condivisione è lo slug di condivisione.
  2. Copia lo slug di condivisione.
  3. Invia una richiesta all'API Looker: GET /queries/slug/Explore_slug passando lo slug dell'URL dell'esplorazione come stringa in Explore_slug. Nella richiesta, includi i campi dei metadati della query Esplora che vuoi che vengano restituiti. Per saperne di più, consulta la pagina di riferimento dell'API Get Query for Slug.
  4. Copia i metadati della query dalla risposta dell'API.

Esempi di query di riferimento di Looker

Gli esempi seguenti mostrano come fornire query di riferimento per airports Esplora con richieste HTTP dirette e con l'SDK Python.

HTTP

In una richiesta HTTP diretta, fornisci un elenco di oggetti query golden di Looker per la chiave looker_golden_queries. Ogni oggetto deve contenere una chiave natural_Language_questions e una chiave looker_query corrispondente.

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

Quando utilizzi l'SDK Python, puoi fornire un elenco di oggetti LookerGoldenQuery. Per ogni oggetto, fornisci i valori per i parametri natural_language_questions e 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"
              ),
          ],
      ),
  ),
]

Definisci un contesto aggiuntivo 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.

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

glossaries

L'elenco delle chiavi glossaries 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 comuni dell'attività" e "Cliente fedele" in base al contesto specifico della tua attività come segue:

-   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 aggiuntive o contesto 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

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

Passaggi successivi

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