O contexto criado são orientações que os proprietários de agentes de dados podem fornecer para moldar o comportamento de um agente de dados e refinar as respostas da API. O contexto criado eficazmente fornece aos agentes de dados da API Conversational Analytics contexto útil para responder a perguntas sobre as suas origens de dados. As instruções do sistema são um tipo de contexto criado que os proprietários de agentes de dados podem fornecer para moldar o comportamento de um agente de dados e refinar as respostas da API.
Esta página descreve como escrever instruções do sistema para origens de dados do Looker, que se baseiam em Explores do Looker. Quando se liga a explorações do Looker, fornece contexto criado a agentes de dados exclusivamente através de instruções do sistema.
Definir contexto nas instruções do sistema
As instruções do sistema consistem numa série de componentes e objetos essenciais que fornecem ao agente de dados detalhes sobre a origem de dados e orientações sobre a função do agente ao responder a perguntas. Pode fornecer instruções do sistema ao agente de dados no parâmetro system_instruction como uma string formatada em YAML.
Depois de definir as instruções do sistema que compõem o contexto criado, pode fornecer esse contexto à API numa das seguintes chamadas:
- Criar um agente de dados persistente: inclua o contexto criado no objeto
published_contextno corpo do pedido para configurar o comportamento do agente que persiste em várias conversas. Para mais informações, consulte os artigos Crie um agente de dados (HTTP) ou Configure o contexto para um chat com ou sem estado (SDK Python). - Enviar um pedido sem estado: forneça contexto criado no objeto
inline_contextnum pedido de chat para definir o comportamento do agente para essa chamada API específica. Para mais informações, consulte os artigos Crie uma conversa sem estado com várias interações (HTTP) ou Envie um pedido de chat sem estado com contexto inline (SDK Python).
O modelo YAML seguinte mostra um exemplo de como pode estruturar as instruções do sistema para uma origem de dados do 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
Descrições dos componentes principais das instruções do sistema
As secções seguintes contêm exemplos de componentes principais das instruções do sistema no Looker. Estas chaves incluem o seguinte:
system_instruction
Use a chave system_instruction para definir a função e a personalidade do agente. Esta instrução inicial define o tom e o estilo das respostas da API e ajuda o agente a compreender o seu objetivo principal.
Por exemplo, pode definir um agente como analista de vendas de uma loja de comércio eletrónico fictícia da seguinte forma:
- 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
A chave golden_queries recebe uma lista de objetos golden_query. As consultas de ouro ajudam o agente a fornecer respostas mais precisas e relevantes a perguntas comuns ou importantes que pode definir. Ao fornecer ao agente uma consulta em linguagem natural e a consulta do Looker correspondente, bem como informações do LookML para cada consulta de ouro, pode orientar o agente para fornecer resultados de maior qualidade e mais consistentes. Por exemplo, pode definir consultas de ouro para análises comuns dos dados na tabela order_items da seguinte forma:
- 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
A glossaries chave apresenta definições de termos empresariais, jargão e abreviaturas relevantes para os seus dados e exemplo de utilização, mas que ainda não aparecem nos seus dados. Por exemplo, pode definir termos como estados comuns da empresa e "Cliente fiel" de acordo com o contexto específico da sua empresa da seguinte forma:
- 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
A chave additional_descriptions lista quaisquer instruções gerais ou contexto adicionais que não sejam abordados noutras partes das instruções do sistema. Por exemplo, pode usar a tecla additional_descriptions para fornecer informações sobre o seu agente da seguinte forma:
- 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.
Exemplo: instruções do sistema no Looker com YAML
O exemplo seguinte mostra instruções do sistema de exemplo para um agente analista de vendas fictício.
- 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.