Menentukan konteks agen data untuk sumber data Looker

Halaman ini menjelaskan cara menulis petunjuk sistem untuk agen data yang menggunakan sumber data Looker, yang didasarkan pada Eksplorasi Looker.

Konteks yang dibuat adalah panduan yang dapat diberikan oleh pemilik agen data untuk membentuk perilaku agen data dan menyempurnakan respons API. Konteks yang ditulis secara efektif memberikan konteks yang berguna kepada agen data Conversational Analytics API Anda untuk menjawab pertanyaan tentang sumber data Anda.

Untuk sumber data Looker, Anda dapat memberikan konteks yang dibuat melalui kombinasi konteks terstruktur dan petunjuk sistem. Jika memungkinkan, berikan konteks melalui kolom konteks terstruktur. Kemudian, Anda dapat menggunakan parameter system_instruction untuk panduan tambahan yang tidak tercakup oleh kolom terstruktur. Petunjuk sistem adalah jenis konteks yang dibuat yang dapat diberikan pemilik agen data kepada agen untuk memberi tahu agen tentang peran, nuansa, dan perilaku keseluruhannya. Petunjuk sistem sering kali lebih bebas daripada konteks terstruktur.

Meskipun kolom konteks terstruktur dan petunjuk sistem bersifat opsional, pemberian konteks yang kuat memungkinkan agen memberikan respons yang lebih akurat dan relevan. Selama pembuatan agen data, semua informasi konteks terstruktur yang telah Anda berikan akan otomatis ditambahkan ke petunjuk sistem.

Menentukan konteks terstruktur

Anda dapat memberikan pertanyaan dan jawaban penting dalam konteks terstruktur untuk agen data Anda. Setelah menentukan konteks terstruktur, Anda dapat memberikannya ke agen data menggunakan permintaan HTTP langsung atau dengan Python SDK.

Untuk sumber data Looker, kueri unggulan dicatat dalam kunci looker_golden_queries, yang menentukan pasangan pertanyaan bahasa alami dan kueri Looker yang sesuai. Dengan memberikan sepasang pertanyaan dalam bahasa alami dan metadata Eksplorasi yang sesuai kepada agen, Anda dapat memandu agen untuk memberikan hasil yang lebih berkualitas dan lebih konsisten. Contoh kueri keemasan Looker disertakan di halaman ini.

Untuk menentukan setiap kueri utama Looker, berikan nilai untuk kedua kolom berikut:

  • natural_language_questions: Pertanyaan natural language yang mungkin diajukan pengguna
  • looker_query: Kueri emas Looker yang sesuai dengan pertanyaan bahasa alami

Berikut adalah contoh pasangan natural_language_questions — looker_query dari Eksplorasi yang disebut "Bandara":

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

Menentukan kueri unggulan Looker

Tentukan kueri terbaik Looker untuk Eksplorasi tertentu dengan memberikan nilai untuk kolom natural_language_questions dan looker_query. Untuk kolom natural_language_questions, pertimbangkan pertanyaan yang mungkin diajukan pengguna tentang Eksplorasi tersebut, dan tulis pertanyaan tersebut dalam bahasa alami. Anda dapat menyertakan lebih dari satu pertanyaan dalam nilai kolom ini. Anda dapat memperoleh nilai untuk kolom looker_query dari metadata kueri Explore.

Objek Kueri Looker mendukung kolom berikut:

  • model (string): Model LookML yang digunakan untuk membuat kueri. Kolom ini wajib diisi.
  • explore (string): Eksplorasi yang digunakan untuk membuat kueri. Kolom ini wajib diisi.
  • fields[] (string): Kolom yang akan diambil dari Eksplorasi, termasuk dimensi dan ukuran. Kolom ini bersifat opsional.
  • filters[] (object (Filter)): Filter yang akan diterapkan ke Eksplorasi. Kolom ini bersifat opsional.
  • sorts[] (string): Pengurutan yang akan diterapkan ke Eksplorasi. Kolom ini bersifat opsional.
  • limit (string): Batas baris data yang akan diterapkan ke Eksplorasi. Kolom ini bersifat opsional.

Anda dapat mengambil metadata kueri Eksplorasi dengan cara berikut:

Mengambil metadata kueri dari antarmuka pengguna Jelajahi

  1. Di Eksplorasi, pilih menu Explore actions, lalu pilih Get LookML.
  2. Pilih tab Dasbor.
  3. Salin detail kueri dari LookML. Misalnya, gambar berikut menampilkan LookML untuk Eksplorasi yang disebut Item Pesanan:

Salin metadata yang dipilih untuk digunakan dalam kueri utama Looker Anda:

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

Mengambil objek kueri Looker menggunakan Looker API

Untuk mengambil informasi tentang Eksplorasi menggunakan Looker API, ikuti langkah-langkah berikut:

  1. Di Eksplorasi, pilih menu Tindakan eksplorasi, lalu pilih Bagikan. Looker menampilkan URL yang dapat Anda salin untuk membagikan Jelajah. URL berbagi umumnya terlihat seperti https://looker.yourcompany/x/vwGSbfc. vwGSbfc di akhir URL berbagi adalah slug berbagi.
  2. Salin slug berbagi.
  3. Buat permintaan ke Looker API: GET /queries/slug/Explore_slug dengan meneruskan slug URL Eksplorasi sebagai string di Explore_slug. Dalam permintaan Anda, sertakan kolom dari metadata kueri Eksplorasi yang ingin Anda tampilkan. Lihat halaman referensi API Get Query for Slug untuk mengetahui informasi selengkapnya.
  4. Salin metadata kueri dari respons API.

Contoh kueri unggulan Looker

Contoh berikut menunjukkan cara memberikan kueri standar untuk airports Jelajahi dengan permintaan HTTP langsung dan dengan Python SDK.

HTTP

Dalam permintaan HTTP langsung, berikan daftar objek kueri emas Looker untuk kunci looker_golden_queries. Setiap objek harus berisi kunci natural_Language_questions dan kunci looker_query yang sesuai.

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

Saat menggunakan Python SDK, Anda dapat memberikan daftar objek LookerGoldenQuery. Untuk setiap objek, berikan nilai untuk parameter natural_language_questions dan 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"
              ),
          ],
      ),
  ),
]

Menentukan konteks tambahan dalam petunjuk sistem

Petunjuk sistem terdiri dari serangkaian komponen dan objek utama yang memberikan detail tentang sumber data kepada agen data dan panduan tentang peran agen saat menjawab pertanyaan. Anda dapat memberikan petunjuk sistem ke agen data dalam parameter system_instruction sebagai string berformat YAML.

Template YAML berikut menunjukkan contoh cara menyusun petunjuk sistem untuk sumber data 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

Deskripsi komponen utama petunjuk sistem

Bagian berikut berisi contoh komponen utama petunjuk sistem di Looker. Kunci ini mencakup:

system_instruction

Gunakan kunci system_instruction untuk menentukan peran dan persona agen. Petunjuk awal ini menetapkan nada dan gaya respons API serta membantu agen memahami tujuan utamanya.

Misalnya, Anda dapat menentukan agen sebagai analis penjualan untuk toko e-commerce fiktif sebagai berikut:

-   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

Kunci glossaries mencantumkan definisi untuk istilah bisnis, jargon, dan singkatan yang relevan dengan data dan kasus penggunaan Anda, tetapi belum muncul dalam data Anda. Sebagai contoh, Anda dapat menentukan istilah seperti status bisnis umum dan "Pelanggan Setia" sesuai dengan konteks bisnis spesifik Anda sebagai berikut:

-   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

Kunci additional_descriptions mencantumkan petunjuk umum atau konteks tambahan yang tidak tercakup di tempat lain dalam petunjuk sistem. Sebagai contoh, Anda dapat menggunakan kunci additional_descriptions untuk memberikan informasi tentang agen Anda sebagai berikut:

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

Contoh: Petunjuk sistem di Looker

Contoh berikut menunjukkan contoh petunjuk sistem untuk agen analis penjualan fiktif:

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

Langkah berikutnya

Setelah menentukan kolom terstruktur dan petunjuk sistem yang membentuk konteks yang Anda buat, Anda dapat memberikan konteks tersebut ke Conversational Analytics API dalam salah satu panggilan berikut: