הגדרת הקשר של סוכן נתונים למקורות נתונים של Looker

בדף הזה מוסבר איך לכתוב הוראות מערכת לסוכנים לאינטראקציה עם נתונים שמשתמשים במקורות נתונים של Looker, שמבוססים על חקירות ב-Looker.

הקשר מנוסח הוא הנחיה שבעלי סוכנים לאינטראקציה עם נתונים יכולים לספק כדי לעצב את ההתנהגות של סוכן לאינטראקציה עם נתונים ולשפר את התשובות של ה-API. הקשר יעיל שנוצר על ידי המשתמש מספק לסוכנים לאינטראקציה עם נתונים של Conversational Analytics API הקשר שימושי למענה על שאלות לגבי מקורות הנתונים שלכם.

במקורות נתונים של Looker, אתם יכולים לספק הקשר שנוצר על ידי שילוב של הקשר מובנה והוראות מערכת. בכל פעם שאפשר, כדאי לספק הקשר באמצעות שדות הקשר מובְנים. אחרי זה, אתם יכולים להשתמש בפרמטר system_instruction כדי להוסיף הנחיות שלא נכללות בשדות המובְנים. הוראות מערכת הן סוג של הקשר שנוצר על ידי הבעלים של סוכן הנתונים, והן מספקות לסוכן מידע על התפקיד, הטון וההתנהגות הכללית שלו. בדרך כלל, הוראות המערכת יכולות להיות יותר פריסה גמישה מהקשר מובנה.

שדות ההקשר המובנים והוראות המערכת הם אופציונליים, אבל אם תספקו הקשר מפורט, הסוכן יוכל לתת תשובות מדויקות ורלוונטיות יותר. כשיוצרים את סוכן לאינטראקציה עם נתונים, כל מידע הקשרי מובנה שסיפקתם מתווסף להוראות המערכת באופן אוטומטי.

הגדרת הקשר מובנה

אתם יכולים לספק שאלות ותשובות מושלמות בהקשר מובנה לסוכן הנתונים. אחרי שמגדירים את ההקשר המובנה, אפשר לספק אותו לסוכן לאינטראקציה עם נתונים באמצעות בקשות HTTP ישירות או באמצעות Python SDK.

במקורות נתונים של Looker, השאילתות לדוגמה מתועדות במפתח looker_golden_queries, שמגדיר זוגות של שאלות בשפה טבעית והשאילתות התואמות להן ב-Looker. אם תספקו לסוכן זוגות של שאלות בשפה טבעית והמטא-נתונים התואמים שלהן ב-Explore, תוכלו להנחות את הסוכן לספק תוצאות איכותיות ועקביות יותר. בדף הזה מופיעות דוגמאות לשאילתות לדוגמה ב-Looker.

כדי להגדיר כל שאילתה לדוגמה ב-Looker, צריך להזין ערכים בשני השדות הבאים:

  • ‫natural_language_questions: השאלה בשפה טבעית שהמשתמש עשוי לשאול
  • ‫looker_query: השאילתה לדוגמה ב-Looker שתואמת לשאלה בשפה טבעית

הנה דוגמה לצמד natural_language_questions — looker_query מניתוח שנקרא "שדות תעופה":

  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

כדי להגדיר שאילתה לדוגמה ב-Looker ל-Explore מסוים, צריך לספק ערכים לשדות natural_language_questions ו-looker_query. בשדה natural_language_questions, כדאי לחשוב על השאלות שמשתמשים עשויים לשאול לגבי הניתוח הזה, ולכתוב את השאלות האלה בשפה טבעית. אפשר לכלול יותר משאלה אחת בערך של השדה הזה. אתם יכולים לקבל את הערך של השדה looker_query מהמטא-נתונים של השאילתה ב-Explore.

האובייקט LookerQuery תומך בשדות הבאים:

  • ‫model (מחרוזת): מודל LookML שמשמש ליצירת השאילתה. זהו שדה חובה.
  • explore (מחרוזת): ה-Explore ששימש ליצירת השאילתה. זהו שדה חובה.
  • ‫fields[] (מחרוזת): השדות שרוצים לאחזר מה-Explore, כולל מאפיינים ומדדים. השדה הזה אופציונלי.
  • ‫filters[] (אובייקט (Filter)): המסננים שצריך להחיל על הניתוח. השדה הזה אופציונלי.
  • sorts[] (מחרוזת): המיון שרוצים להחיל על הניתוח. השדה הזה הוא אופציונלי.
  • ‫limit (מחרוזת): מגבלת שורות הנתונים שחלה על הניתוח. השדה הזה אופציונלי.

אפשר לאחזר את המטא-נתונים של השאילתה ב-Explore בדרכים הבאות:

אחזור המטא-נתונים של השאילתה מממשק המשתמש של Explore

  1. ב-Explore, לוחצים על תפריט Explore actions ואז על Get LookML.
  2. לוחצים על הכרטיסייה מרכז הבקרה.
  3. מעתיקים את פרטי השאילתה מ-LookML. לדוגמה, בתמונה הבאה מוצג קוד LookML של Explore שנקרא Order Items:

מעתיקים את המטא-נתונים שנבחרו כדי להשתמש בהם בשאילתה לדוגמה ב-Looker:

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

אחזור של אובייקט השאילתה של Looker באמצעות Looker API

כדי לאחזר מידע על ה-Explore באמצעות Looker API:

  1. ב-Explore, בוחרים את התפריט Explore actions ולוחצים על Share. ב-Looker יוצגו כתובות URL שאפשר להעתיק כדי לשתף את ה-Explore. כתובות URL לשיתוף נראות בדרך כלל בערך כך: https://looker.yourcompany/x/vwGSbfc. החלק vwGSbfc בסוף כתובת ה-URL לשיתוף הוא ה-slug של השיתוף.
  2. מעתיקים את הקישור לשיתוף.
  3. שולחים בקשה ל-Looker API: GET /queries/slug/Explore_slug ומעבירים את ה-slug של כתובת ה-URL של ה-Explore כמחרוזת ב-Explore_slug. בבקשה, צריך לכלול את השדות מהמטא-נתונים של שאילתת Explore שרוצים להחזיר. מידע נוסף זמין בדף מאמרי העזרה של ה-API בנושא Get Query for Slug.
  4. מעתיקים את המטא-נתונים של השאילתה מהתגובה מה-API.

שאילתות לדוגמה ב-Looker

בדוגמאות הבאות מוסבר איך לספק שאילתות לדוגמה ל-airports Explore באמצעות בקשות HTTP ישירות ובאמצעות Python SDK.

HTTP

בבקשת HTTP ישירה, מספקים רשימה של אובייקטים של שאילתות לדוגמה ב-Looker למפתח looker_golden_queries. כל אובייקט חייב להכיל מפתח natural_Language_questions ומפתח looker_query תואם.

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

כשמשתמשים ב-Python SDK, אפשר לספק רשימה של אובייקטים מסוג LookerGoldenQuery. לכל אובייקט, צריך לציין ערכים לפרמטרים natural_language_questions ו-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"
              ),
          ],
      ),
  ),
]

הגדרת הקשר נוסף בהוראות המערכת

הוראות המערכת מורכבות מסדרה של רכיבים ואובייקטים מרכזיים שמספקים לסוכן לאינטראקציה עם נתונים פרטים על מקור הנתונים והנחיות לגבי התפקיד של הסוכן במתן תשובות לשאלות. אתם יכולים לתת לסוכן לאינטראקציה עם נתונים הוראות מערכת בפרמטר system_instruction כמחרוזת בפורמט YAML.

תבנית ה-YAML הבאה מראה דוגמה לאופן שבו אפשר לבנות הוראות מערכת למקור נתונים של 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

תיאור של הרכיבים העיקריים בהוראות למערכת

בקטעים הבאים מופיעות דוגמאות לרכיבים העיקריים של הוראות המערכת ב-Looker. המפתחות האלה כוללים:

system_instruction

משתמשים במפתח system_instruction כדי להגדיר את התפקיד והפרסונה של הסוכן. ההוראה הראשונית הזו קובעת את הטון והסגנון של התשובות מה-API, ועוזרת לנציג להבין את המטרה העיקרית שלו.

לדוגמה, אתם יכולים להגדיר נציג כמנתח מכירות של חנות פיקטיבית למסחר אלקטרוני באופן הבא:

-   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

המפתח glossaries מפרט הגדרות של מונחים עסקיים, ז'רגון וקיצורים שרלוונטיים לנתונים ולתרחיש לדוגמה שלכם, אבל לא מופיעים בנתונים. לדוגמה, אתם יכולים להגדיר מונחים כמו סטטוסים עסקיים נפוצים ו "לקוח נאמן" בהתאם להקשר העסקי הספציפי שלכם, באופן הבא:

-   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

המפתח additional_descriptions מפרט הוראות כלליות נוספות או הקשר שלא נכלל במקום אחר בהוראות המערכת. לדוגמה, אתם יכולים להשתמש במפתח additional_descriptions כדי לספק מידע על הנציג באופן הבא:

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

דוגמה: הוראות מערכת ב-Looker

בדוגמה הבאה מוצגות הוראות מערכת לדוגמה לסוכן פיקטיבי לניתוח מכירות:

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

המאמרים הבאים

אחרי שמגדירים את השדות המובְנים ואת ההוראות למערכת שמרכיבים את ההקשר שנוצר, אפשר לספק את ההקשר הזה ל-Conversational Analytics API באחת מהקריאות הבאות: