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

Auf dieser Seite wird beschrieben, wie Sie Systemanweisungen für Datenagenten schreiben, die Looker-Datenquellen verwenden, die auf Looker-Explores basieren.

Der selbst erstellte Kontext ist eine Anleitung, die Daten-KI-Agent-Inhaber bereitstellen können, um das Verhalten eines Daten-KI-Agenten zu beeinflussen und die Antworten der API zu optimieren. Ein effektiver selbst erstellter Kontext liefert Ihren Daten-KI-Agenten der Conversational Analytics API nützliche Informationen, um Fragen zu Ihren Datenquellen zu beantworten.

Für Looker-Datenquellen können Sie selbst erstellten Kontext über eine Kombination aus strukturiertem Kontext und Systemanweisungen bereitstellen. Stellen Sie nach Möglichkeit Kontext über strukturierte Kontextfelder bereit. Sie können dann den Parameter system_instruction für zusätzliche Anleitungen verwenden, die nicht von den strukturierten Feldern abgedeckt werden. Systemanweisungen sind eine Art von selbst erstelltem Kontext, den Daten-KI-Agent-Inhaber einem Agenten zur Verfügung stellen können, um ihn über seine Rolle, seinen Ton und sein allgemeines Verhalten zu informieren. Systemanweisungen können oft kostenloser formuliert werden als strukturierter Kontext.

Sowohl strukturierte Kontextfelder als auch Systemanweisungen sind optional. Wenn Sie jedoch einen aussagekräftigen Kontext angeben, kann der KI-Agent genauere und relevantere Antworten liefern. Beim Erstellen Ihres KI-Datenagenten werden alle von Ihnen angegebenen strukturierten Kontextinformationen automatisch den Systemanweisungen hinzugefügt.

Strukturierten Kontext definieren

Sie können Ihrem Daten-Agenten optimale Fragen und Antworten in strukturiertem Kontext zur Verfügung stellen. Nachdem Sie den strukturierten Kontext definiert haben, können Sie ihn Ihrem Daten-KI-Agenten mit direkten HTTP-Anfragen oder mit dem Python SDK zur Verfügung stellen.

Für Looker-Datenquellen werden Golden Queries im Schlüssel looker_golden_queries erfasst. Dieser definiert Paare aus Fragen in natürlicher Sprache und den entsprechenden Looker-Abfragen. Wenn Sie dem Agenten sowohl eine Frage in natürlicher Sprache als auch die entsprechenden Explore-Metadaten zur Verfügung stellen, können Sie ihn anleiten, qualitativ hochwertige und konsistente Ergebnisse zu liefern. Auf dieser Seite finden Sie Beispiele für Looker-Gold-Abfragen.

Geben Sie zum Definieren jeder Looker-Golden-Query Werte für die folgenden beiden Felder an:

  • natural_language_questions: Die Frage in natürlicher Sprache, die ein Nutzer stellen könnte
  • looker_query: Die Looker-Golden-Query, die der Frage in natürlicher Sprache entspricht

Hier ist ein Beispiel für ein natural_language_questions-looker_query-Paar aus einem Explore namens „Airports“ (Flughäfen):

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

Looker Golden Query definieren

Definieren Sie eine Looker-Golden-Query für ein bestimmtes Explore, indem Sie Werte für die Felder natural_language_questions und looker_query angeben. Berücksichtigen Sie für das Feld natural_language_questions die Fragen, die ein Nutzer zu diesem Explore stellen könnte, und formulieren Sie diese Fragen in natürlicher Sprache. Sie können in den Wert dieses Felds mehr als eine Frage einfügen. Sie können den Wert für das Feld looker_query aus den Abfragemetadaten des Explorers abrufen.

Das Looker Query Object unterstützt die folgenden Felder:

  • model (String): Das LookML-Modell, das zum Generieren der Anfrage verwendet wurde. Dies ist ein Pflichtfeld.
  • explore (String): Das Explore, das zum Generieren der Abfrage verwendet wurde. Dies ist ein Pflichtfeld.
  • fields[] (String): Die Felder, die aus dem Explore abgerufen werden sollen, einschließlich Dimensionen und Messwerten. Dieses Feld ist optional.
  • filters[] (object(Filter)): Die Filter, die auf das Explore angewendet werden sollen. Dieses Feld ist optional.
  • sorts[] (String): Die Sortierung, die auf den Explore angewendet werden soll. Dieses Feld ist optional.
  • limit (String): Das Datenzeilenlimit, das auf den Explore angewendet werden soll. Dieses Feld ist optional.

Sie können die Metadaten der Abfrage eines Explorationsberichts auf folgende Arten abrufen:

Abfragemetadaten über die Explorer-Benutzeroberfläche abrufen

  1. Wählen Sie im Explore das Menü Explore-Aktionen und dann LookML abrufen aus.
  2. Wählen Sie den Tab Dashboard aus.
  3. Kopieren Sie die Abfragedetails aus dem LookML-Code. Das folgende Bild zeigt beispielsweise das LookML für ein Explore namens „Order Items“:

Kopieren Sie die ausgewählten Metadaten, um sie in Ihrer Looker-Gold-Abfrage zu verwenden:

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

Looker-Abfrageobjekt mit der Looker API abrufen

So rufen Sie Informationen zu Ihrem Explore mit der Looker API ab:

  1. Wählen Sie im Explore-Bereich das Menü Explore-Aktionen und dann Freigeben aus. In Looker werden URLs angezeigt, die Sie kopieren können, um das Explore zu teilen. Freigabe-URLs sehen in der Regel so aus: https://looker.yourcompany/x/vwGSbfc. Das nachgestellte vwGSbfc in der Freigabe-URL ist der Freigabe-Slug.
  2. Kopieren Sie den Freigabe-Slug.
  3. Stellen Sie eine Anfrage an die Looker API: GET /queries/slug/Explore_slug und übergeben Sie den Explore-URL-Slug als String in Explore_slug. Nehmen Sie in Ihre Anfrage die Felder aus den Metadaten Ihrer Explore-Abfrage auf, die zurückgegeben werden sollen. Weitere Informationen finden Sie auf der API-Referenzseite Get Query for Slug.
  4. Kopieren Sie die Metadaten der Abfrage aus der API-Antwort.

Beispiele für Looker-Golden Queries

Die folgenden Beispiele zeigen, wie Sie Golden Queries für den Explore airports sowohl mit direkten HTTP-Anfragen als auch mit dem Python SDK bereitstellen.

HTTP

Geben Sie bei einer direkten HTTP-Anfrage eine Liste von Looker-Golden-Query-Objekten für den Schlüssel looker_golden_queries an. Jedes Objekt muss einen natural_Language_questions-Schlüssel und einen entsprechenden looker_query-Schlüssel enthalten.

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

Python SDK

Wenn Sie das Python SDK verwenden, können Sie eine Liste von LookerGoldenQuery-Objekten angeben. Geben Sie für jedes Objekt Werte für die Parameter natural_language_questions und looker_query an.

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"
              ),
          ],
      ),
  ),
]

Zusätzlichen Kontext in Systemanweisungen definieren

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

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
-   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 wichtiger 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 KI-Agenten zu definieren. Mit dieser ersten Anweisung werden Ton und Stil für die Antworten der API festgelegt und dem KI-Agenten wird sein Hauptzweck verdeutlicht.

Sie können einen KI-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.

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. So können Sie 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 Kundenservicemitarbeiter 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

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

Nächste Schritte

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