Halaman ini menjelaskan cara menulis petunjuk sistem untuk agen data yang menggunakan sumber data Looker, yang didasarkan pada Eksplorasi Looker.
Konteks yang ditulis adalah panduan yang dapat diberikan oleh pemilik agen data untuk membentuk perilaku agen data dan menyempurnakan respons API. Konteks buatan yang efektif memberikan konteks yang berguna kepada agen data Analisis Percakapan API Anda untuk menjawab pertanyaan tentang sumber data Anda.
Untuk sumber data Looker, Anda dapat memberikan konteks yang ditulis 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 dalam kolom terstruktur. Petunjuk sistem adalah jenis konteks yang dibuat oleh pemilik agen data untuk memberi tahu agen tentang peran, gaya bahasa, dan perilaku keseluruhannya. Sering kali, petunjuk sistem dapat lebih berbentuk bebas daripada
konteks terstruktur.
Meskipun kolom konteks terstruktur dan petunjuk sistem bersifat opsional, menyediakan konteks yang kuat memungkinkan agen memberikan respons yang lebih akurat dan relevan. Selama pembuatan agen data, informasi konteks terstruktur yang Anda berikan akan otomatis ditambahkan ke petunjuk sistem.
Menentukan konteks terstruktur
Anda dapat memberikan pertanyaan dan jawaban emas 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, golden query dicatat dalam kunci looker_golden_queries, yang menentukan pasangan pertanyaan bahasa alami dan kueri Looker yang sesuai. Dengan memberikan pasangan pertanyaan natural language dan metadata Explore yang sesuai kepada agen, Anda dapat memandu agen untuk memberikan hasil yang lebih berkualitas dan konsisten. Contoh golden query Looker disertakan di halaman ini.
Untuk menentukan setiap golden query Looker, berikan nilai untuk kedua kolom berikut:
natural_language_questions: Pertanyaan dalam bahasa alami yang mungkin diajukan penggunalooker_query: Golden query Looker yang sesuai dengan pertanyaan natural language
Berikut adalah contoh pasangan natural_language_questions — looker_query
dari Explore yang disebut "Airports":
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 golden query Looker
Tentukan golden query 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 bisa mendapatkan nilai
untuk kolom looker_query dari metadata kueri Explore.
Objek
LookerQuery
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 Explore, termasuk dimensi dan ukuran. Kolom ini bersifat opsional.filters[](objek (Filter)): Filter yang akan diterapkan ke Explore. 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 Explore. Kolom ini bersifat opsional.
Anda dapat mengambil metadata kueri Explore dengan cara berikut:
- Mengambil metadata kueri dari halaman Explore
- Mengambil objek kueri Looker dari endpoint API
GetQueryForSlug
Mengambil metadata kueri dari antarmuka pengguna Explore
- Di Explore, pilih menu Explore actions, lalu pilih Get LookML.
- Pilih tab Dasbor.
- Salin detail kueri dari LookML. Misalnya, gambar berikut menunjukkan LookML untuk Eksplorasi bernama Order Items:

Salin metadata yang dipilih untuk digunakan dalam golden query 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 Explore menggunakan Looker API, ikuti langkah-langkah berikut:
- Di Explore, pilih menu Explore actions,
lalu pilih Share. Looker menampilkan URL yang dapat Anda salin untuk membagikan Eksplorasi. URL berbagi umumnya terlihat seperti
https://looker.yourcompany/x/vwGSbfc.vwGSbfcdi akhir URL berbagi adalah slug berbagi. - Salin slug berbagi.
- Buat permintaan ke Looker API:
GET /queries/slug/Explore_slugdengan meneruskan slug URL Explore sebagai string diExplore_slug. Dalam permintaan Anda, sertakan kolom dari metadata kueri Explore yang ingin Anda tampilkan. Lihat halaman referensi API Get Query for Slug untuk mengetahui informasi selengkapnya. - Salin metadata kueri dari respons API.
Contoh golden query Looker
Contoh berikut menunjukkan cara memberikan golden query untuk airports
Explore dengan permintaan HTTP langsung dan dengan Python SDK.
HTTP
Dalam permintaan HTTP langsung, berikan daftar objek golden query 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 kepada 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 nuansa dan gaya untuk 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 bagian 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 API Analisis Percakapan dalam salah satu panggilan berikut:
- Membuat agen data persisten: Sertakan konteks yang ditulis dalam objek
published_contextdi isi permintaan untuk mengonfigurasi perilaku agen yang tetap ada di beberapa percakapan. Untuk mengetahui informasi selengkapnya, lihat Membuat agen data (HTTP) atau Menyiapkan konteks untuk chat stateful atau stateless (Python SDK). - Mengirim permintaan stateless: Berikan konteks yang ditulis dalam objek
inline_contextdalam permintaan chat untuk menentukan perilaku agen untuk panggilan API tertentu tersebut. Untuk mengetahui informasi selengkapnya, lihat Membuat percakapan multi-turn stateless (HTTP) atau Menggunakan API untuk mengajukan pertanyaan (Python SDK). - Mengirim permintaan data kueri: Untuk sumber data database, berikan ID set konteks dari konteks yang dibuat dalam objek
agent_context_referencedalam permintaan data kueri. Untuk mengetahui informasi selengkapnya, lihat Menentukan konteks agen data untuk sumber data database.