Definir o contexto do agente de dados para fontes de dados do Looker

Nesta página, descrevemos como escrever instruções do sistema para agentes de dados que usam fontes de dados do Looker, baseadas em Análises do Looker.

O contexto criado é uma orientação 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. Um contexto criado eficaz fornece aos agentes de dados da API Conversational Analytics um contexto útil para responder a perguntas sobre suas fontes de dados.

Para fontes de dados do Looker, é possível fornecer contexto criado usando uma combinação de contexto estruturado e instruções do sistema. Sempre que possível, forneça contexto usando campos estruturados. Em seguida, use o parâmetro system_instruction para orientações complementares que não são cobertas pelos campos estruturados. As instruções do sistema são um tipo de contexto criado que os proprietários de agentes de dados podem fornecer para informar ao agente sobre sua função, tom e comportamento geral. Muitas vezes, as instruções do sistema podem ser mais livres do que o contexto estruturado.

Embora os campos de contexto estruturado e as instruções do sistema sejam opcionais, fornecer um contexto robusto permite que o agente dê respostas mais precisas e relevantes. Durante a criação do seu agente de dados, todas as informações de contexto estruturado fornecidas serão adicionadas automaticamente às instruções do sistema.

Definir contexto estruturado

Você pode fornecer perguntas e respostas de ouro em um contexto estruturado para seu agente de dados. Depois de definir o contexto estruturado, é possível fornecê-lo ao agente de dados usando solicitações HTTP diretas ou com o SDK do Python.

Para fontes de dados do Looker, as consultas de ouro são capturadas na chave looker_golden_queries, que define pares de perguntas em linguagem natural e as consultas correspondentes do Looker. Ao fornecer ao agente um par de perguntas em linguagem natural e os metadados correspondentes do recurso Detalhar, você pode orientar o agente a fornecer resultados de maior qualidade e mais consistentes. Exemplos de consultas de ouro do Looker estão incluídos nesta página.

Para definir cada consulta de ouro do Looker, forneça valores para os dois campos a seguir:

  • natural_language_questions: a pergunta em linguagem natural que um usuário pode fazer
  • looker_query: a consulta de ouro do Looker que corresponde à pergunta em linguagem natural

Confira um exemplo de um par natural_language_questions e looker_query de uma análise detalhada chamada "Aeroportos":

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

Definir uma consulta de ouro do Looker

Defina uma consulta de ouro do Looker para uma determinada Análise fornecendo valores para os campos natural_language_questions e looker_query. Para o campo natural_language_questions, considere as perguntas que um usuário pode fazer sobre essa análise detalhada e escreva essas perguntas em linguagem natural. É possível incluir mais de uma pergunta no valor desse campo. É possível obter o valor do campo looker_query nos metadados da consulta do recurso Detalhar.

O objeto de consulta do Looker é compatível com os seguintes campos:

  • model (string): o modelo do LookML usado para gerar a consulta. Este é um campo obrigatório.
  • explore (string): a Análise usada para gerar a consulta. Este é um campo obrigatório.
  • fields[] (string): os campos a serem recuperados da Análise, incluindo dimensões e métricas. Esse campo é opcional.
  • filters[] (objeto (Filter)): Os filtros a serem aplicados à Análise. Esse campo é opcional.
  • sorts[] (string): a classificação a ser aplicada à Análise. Esse campo é opcional.
  • limit (string): o limite de linhas de dados a ser aplicado à Análise. Esse campo é opcional.

É possível recuperar os metadados de consulta do recurso Detalhar das seguintes maneiras:

Recuperar os metadados da consulta na interface do usuário do recurso Detalhar

  1. Na Análise, selecione o menu Abrir ações e clique em Receber LookML.
  2. Selecione a guia Painel.
  3. Copie os detalhes da consulta do LookML. Por exemplo, a imagem a seguir mostra a LookML de uma Análise chamada "Itens do pedido":

Copie os metadados selecionados para usar na sua consulta de ouro do Looker:

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

Recuperar o objeto de consulta do Looker usando a API do Looker

Para recuperar informações sobre sua análise detalhada usando a API Looker, siga estas etapas:

  1. Na Análise, selecione o menu de ações da Análise e clique em Compartilhar. O Looker mostra URLs que você pode copiar para compartilhar a Análise. Os URLs de compartilhamento geralmente são assim: https://looker.yourcompany/x/vwGSbfc. O vwGSbfc final no URL de compartilhamento é o slug de compartilhamento.
  2. Copie o slug de compartilhamento.
  3. Faça uma solicitação à API Looker: GET /queries/slug/Explore_slug transmitindo o slug do URL da análise detalhada como uma string em Explore_slug. Na solicitação, inclua os campos dos metadados da consulta do Explorar que você quer retornar. Consulte a página de referência da API Get Query for Slug para mais informações.
  4. Copie os metadados da consulta da resposta da API.

Exemplo de consultas de ouro do Looker

Os exemplos a seguir mostram como fornecer consultas de ouro para a airports Análise detalhada com solicitações HTTP diretas e com o SDK do Python.

HTTP

Em uma solicitação HTTP direta, forneça uma lista de objetos de consulta do Looker para a chave looker_golden_queries. Cada objeto precisa conter uma chave natural_Language_questions e uma chave looker_query correspondente.

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

SDK do Python

Ao usar o SDK do Python, é possível fornecer uma lista de objetos LookerGoldenQuery. Para cada objeto, forneça valores para os parâmetros natural_language_questions e 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"
              ),
          ],
      ),
  ),
]

Definir mais contexto nas instruções do sistema

As instruções do sistema consistem em uma série de componentes e objetos principais que fornecem ao agente de dados detalhes sobre a fonte de dados e orientações sobre a função do agente ao responder a perguntas. É possível fornecer instruções do sistema ao agente de dados no parâmetro system_instruction como uma string formatada em YAML.

O modelo YAML a seguir mostra um exemplo de como estruturar instruções do sistema para uma fonte de dados do 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

Descrições dos principais componentes das instruções do sistema

As seções a seguir contêm exemplos dos componentes principais das instruções do sistema no Looker. Essas chaves incluem:

system_instruction

Use a chave system_instruction para definir a função e o perfil do agente. Essa instrução inicial define o tom e o estilo das respostas da API e ajuda o agente a entender o objetivo principal dele.

Por exemplo, você pode definir um agente como analista de vendas de uma loja de e-commerce fictícia da seguinte maneira:

-   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

A chave glossaries lista definições de termos comerciais, jargões e abreviações relevantes para seus dados e caso de uso, mas que ainda não aparecem nos dados. Por exemplo, você pode definir termos como status da empresa comuns e "Cliente fiel" de acordo com seu contexto comercial específico 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 outras instruções gerais ou contextos não abordados em outras partes das instruções do sistema. Por exemplo, é possível usar a chave additional_descriptions para fornecer informações sobre 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

O exemplo a seguir mostra instruções de sistema de amostra 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)."
-   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.

A seguir

Depois de definir os campos estruturados e as instruções do sistema que compõem seu contexto criado, você pode fornecer esse contexto à API Conversational Analytics em uma das seguintes chamadas: