撰寫的背景資訊是資料代理擁有者提供的指引，可塑造資料代理的行為，並改善 API 的回應。撰寫得當的內容可為對話式數據分析 API 資料代理程式提供實用背景資訊，協助回答資料來源相關問題。系統指令是資料代理擁有者提供的一種撰寫背景資訊，可塑造資料代理的行為，並改善 API 的回覆。
本頁面說明如何為 Looker 資料來源編寫系統指令，這些指令是以 Looker 探索為基礎。連線至 Looker 探索時，您只能透過系統指令，向資料代理程式提供撰寫的內容。
在系統指令中定義情境
系統指令包含一系列重要元件和物件，可向資料代理程式提供資料來源的詳細資料，以及代理程式在回答問題時的角色指引。您可以在 system_instruction 參數中以 YAML 格式的字串，向資料代理程式提供系統指令。
定義組成撰寫脈絡的系統指令後，您可以在下列其中一個呼叫中向 API 提供該脈絡：
- 建立持續性資料代理：在要求主體的
published_context物件中加入撰寫的內容，設定代理行為，讓代理在多個對話中保持一致。詳情請參閱「建立資料代理程式」(HTTP) 或「為有狀態或無狀態的對話設定環境」(Python SDK)。 - 傳送無狀態要求：在聊天要求中，於
inline_context物件內提供撰寫的內容，為該特定 API 呼叫定義代理程式的行為。詳情請參閱「建立無狀態多輪對話」(HTTP) 或「傳送含內嵌情境的無狀態即時通訊要求」(Python SDK)。
以下 YAML 範本提供範例，說明如何為 Looker 資料來源設定系統指令：
- system_instruction: str # Describe the expected behavior of the agent
- golden_queries: # Define queries for common analyses of your Explore data
- golden_query:
- natural_language_query: str
- looker_query: str
- model: string
- view: string
- fields: list[str]
- filters: list[str]
- sorts: list[str]
- limit: str
- query_timezone: str
- 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.
golden_queries
golden_queries 鍵會採用 golden_query 物件清單。黃金查詢可協助服務專員針對您定義的常見或重要問題，提供更準確且相關的回覆。為每個黃金查詢提供自然語言查詢，以及對應的 Looker 查詢和 LookML 資訊，即可引導代理程式提供更高品質且更一致的結果。舉例來說，您可以為 order_items 資料表中的資料定義常見分析的金鑰查詢，如下所示：
- golden_queries:
- natural_language_query: what were total sales over the last year
- looker_query:
- model: thelook
- view: order_items
- fields: order_items.total_sale_price
- filters: order_items.created_date: last year
- sorts: order_items.total_sale_price desc 0
- limit: null
- query_timezone: America/Los_Angeles
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 中使用 YAML 的系統指令
以下範例顯示虛構銷售分析師代理程式的系統指令。
- 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)."
- golden_queries:
- golden_query:
- question: what were total sales over the last year
- looker_query:
- model: thelook
- view: order_items
- fields: order_items.total_sale_price
- filters: order_items.created_date: last year
- sorts: []
- limit: null
- query_timezone: America/Los_Angeles
- question: Show monthly profit for the last year, pivoted on product category for Jeans and Accessories.
- looker_query:
- model: thelook
- view: order_items
- fields:
- name: products.category
- name: order_items.total_gross_margin
- name: order_items.created_month_name
- filters:
- products.category: Jeans,Accessories
- order_items.created_date: last year
- pivots: products.category
- sorts:
- order_items.created_month_name asc
- order_items.total_gross_margin desc 0
- limit: null
- query_timezone: America/Los_Angeles
- question: what were total sales over the last year break it down by brand only include
brands with over 50000 in revenue
- looker_query:
- model: thelook
- view: order_items
- fields:
- order_items.total_sale_price
- products.brand
- filters:
- order_items.created_date: last year
- order_items.total_sale_price: '>50000'
- sorts: order_items.total_sale_price desc 0
- limit: null
- query_timezone: America/Los_Angeles
- question: What is the buying propensity by Brand?
- looker_query:
- model: thelook
- view: order_items
- fields:
- order_items.30_day_repeat_purchase_rate
- products.brand
- filters: {}
- sorts: order_items.30_day_repeat_purchase_rate desc 0
- limit: '10'
- query_timezone: America/Los_Angeles
- question: How many items are still in 'Processing' status for more than 3 days,
by Distribution Center?
- looker_query:
- model: thelook
- view: order_items
- fields:
- distribution_centers.name
- order_items.count
- filters:
- order_items.created_date: before 3 days ago
- order_items.status: Processing
- sorts: order_items.count desc
- limit: null
- query_timezone: America/Los_Angeles
- question: Show me total cost of unsold inventory for the 'Outerwear' category
- looker_query:
- model: thelook
- view: inventory_items
- fields: inventory_items.total_cost
- filters:
- inventory_items.is_sold: No
- products.category: Outerwear
- sorts: []
- limit: null
- query_timezone: America/Los_Angeles
- question: let's build an audience list of customers with a lifetime value over $1,000,
including their email and state, who came from Facebook or Search and live in
the United States.
- looker_query:
- model: thelook
- view: users
- fields:
- users.email
- users.state
- user_order_facts.lifetime_revenue
- filters:
- user_order_facts.lifetime_revenue: '>1000'
- users.country: United States
- users.traffic_source: Facebook,Search
- sorts: user_order_facts.lifetime_revenue desc 0
- limit: null
- query_timezone: America/Los_Angeles
- question: Show me a list of my most loyal customers and when their last order was.
- looker_query:
- model: thelook
- view: users
- fields:
- users.id
- users.email
- user_order_facts.lifetime_revenue
- user_order_facts.lifetime_orders
- user_order_facts.latest_order_date
- filters: user_order_facts.repeat_customer: Yes
- sorts: user_order_facts.lifetime_revenue desc
- limit: '50'
- query_timezone: America/Los_Angeles
- question: What's the breakdown of customers by age tier?
- looker_query:
- model: thelook
- view: users
- fields:
- users.age_tier
- users.count
- filters: {}
- sorts: users.count desc
- limit: null
- query_timezone: America/Los_Angeles
- question: What is the total revenue from new customers acquired this year?
- looker_query:
- model: thelook
- view: order_items
- fields: order_items.total_sale_price
- filters: user_order_facts.first_order_year: this year
- sorts: []
- limit: null
- query_timezone: America/Los_Angeles
- 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.