Cómo definir el contexto del agente de datos para las fuentes de datos de Looker

En esta página, se describe cómo escribir instrucciones del sistema para los agentes de datos que usan fuentes de datos de Looker, las cuales se basan en Explores de Looker.

El contexto creado es una guía que los propietarios de agentes de datos pueden proporcionar para definir el comportamiento de un agente de datos y refinar las respuestas de la API. El contexto creado eficaz proporciona a tus agentes de datos de la API de Conversational Analytics un contexto útil para responder preguntas sobre tus fuentes de datos.

En el caso de las fuentes de datos de Looker, puedes proporcionar contexto creado por el usuario a través de una combinación de contexto estructurado y instrucciones del sistema. Siempre que sea posible, proporciona contexto a través de campos de contexto estructurados. Luego, puedes usar el parámetro system_instruction para obtener orientación complementaria que no se incluye en los campos estructurados. Las instrucciones del sistema son un tipo de contexto creado que los propietarios de agentes de datos pueden proporcionar a un agente para informarle sobre su rol, tono y comportamiento general. A menudo, las instrucciones del sistema pueden ser más libres que el contexto estructurado.

Si bien tanto los campos de contexto estructurado como las instrucciones del sistema son opcionales, proporcionar un contexto sólido permite que el agente brinde respuestas más precisas y pertinentes. Durante la creación de tu agente de datos, cualquier información de contexto estructurada que hayas proporcionado se agregará automáticamente a las instrucciones del sistema.

Cómo definir el contexto estructurado

Puedes proporcionar preguntas y respuestas de referencia en un contexto estructurado para tu agente de datos. Una vez que hayas definido tu contexto estructurado, puedes proporcionárselo a tu agente de datos con solicitudes HTTP directas o con el SDK de Python.

En el caso de las fuentes de datos de Looker, las preguntas de referencia se capturan en la clave looker_golden_queries, que define pares de preguntas en lenguaje natural y sus correspondientes consultas de Looker. Si le proporcionas al agente un par de preguntas en lenguaje natural y sus metadatos de Explore correspondientes, puedes guiarlo para que proporcione resultados de mayor calidad y más coherentes. En esta página, se incluyen ejemplos de consultas de oro de Looker.

Para definir cada consulta de referencia de Looker, proporciona valores para los siguientes campos:

  • natural_language_questions: Pregunta en lenguaje natural que podría hacer un usuario
  • looker_query: Es la consulta de oro de Looker que corresponde a la pregunta en lenguaje natural.

Este es un ejemplo de un par natural_language_questions — looker_query de una Exploración llamada "Aeropuertos":

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

Cómo definir una consulta de referencia de Looker

Define una consulta de referencia de Looker para una exploración determinada proporcionando valores para los campos natural_language_questions y looker_query. Para el campo natural_language_questions, considera las preguntas que podría hacer un usuario sobre esa Exploración y escríbelas en lenguaje natural. Puedes incluir más de una pregunta en el valor de este campo. Puedes obtener el valor del campo looker_query de los metadatos de la búsqueda de Explorar.

El objeto de consulta de Looker admite los siguientes campos:

  • model (cadena): Es el modelo de LookML que se usó para generar la consulta. Este es un campo obligatorio.
  • explore (cadena): Es la exploración que se usó para generar la consulta. Este campo es obligatorio.
  • fields[] (cadena): Son los campos que se recuperarán de la exploración, incluidas las dimensiones y las métricas. Este paso es opcional,
  • filters[] (objeto (Filter)): Son los filtros que se aplicarán a la exploración. Este paso es opcional,
  • sorts[] (cadena): Es la clasificación que se aplicará a la función Explorar. Este es un campo opcional.
  • limit (cadena): Es el límite de filas de datos que se aplicará a la exploración. Este campo es opcional.

Puedes recuperar los metadatos de la consulta de Explorar de las siguientes maneras:

Cómo recuperar los metadatos de la consulta desde la interfaz de usuario de Explorar

  1. En el Explorador, selecciona el menú Acciones de Explore y, luego, Obtener LookML.
  2. Selecciona la pestaña Panel.
  3. Copia los detalles de la consulta desde LookML. Por ejemplo, en la siguiente imagen, se muestra el LookML de una exploración llamada Order Items:

Copia los metadatos seleccionados para usarlos en tu consulta de referencia de Looker:

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

Recupera el objeto de consulta de Looker con la API de Looker

Para recuperar información sobre tu Explorar con la API de Looker, sigue estos pasos:

  1. En la sección Explorar, selecciona el menú de acciones de Explorar y, luego, Compartir. Looker muestra URLs que puedes copiar para compartir la función Explorar. Por lo general, las URLs para compartir tienen un formato similar al siguiente: https://looker.yourcompany/x/vwGSbfc. El vwGSbfc final en la URL de uso compartido es el slug de uso compartido.
  2. Copia el slug para compartir.
  3. Realiza una solicitud a la API de Looker: GET /queries/slug/Explore_slug pasa el slug de la URL de Explore como una cadena en Explore_slug. En tu solicitud, incluye los campos de los metadatos de la consulta de Explorar que deseas que se muestren. Consulta la página de referencia de la API de Get Query for Slug para obtener más información.
  4. Copia los metadatos de la consulta de la respuesta de la API.

Ejemplo de consultas de referencia de Looker

En los siguientes ejemplos, se muestra cómo proporcionar búsquedas de referencia para airports Explore con solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, proporciona una lista de objetos de consulta dorada de Looker para la clave looker_golden_queries. Cada objeto debe contener una clave natural_Language_questions y una clave looker_query correspondiente.

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

Cuando usas el SDK de Python, puedes proporcionar una lista de objetos LookerGoldenQuery. Para cada objeto, proporciona valores para los parámetros natural_language_questions y 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"
              ),
          ],
      ),
  ),
]

Cómo definir contexto adicional en las instrucciones del sistema

Las instrucciones del sistema constan de una serie de componentes y objetos clave que proporcionan al agente de datos detalles sobre la fuente de datos y orientación sobre el rol del agente cuando responde preguntas. Puedes proporcionar instrucciones del sistema al agente de datos en el parámetro system_instruction como una cadena con formato YAML.

En la siguiente plantilla de YAML, se muestra un ejemplo de cómo podrías estructurar las instrucciones del sistema para una fuente de datos de 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

Descripciones de los componentes clave de las instrucciones del sistema

En las siguientes secciones, se incluyen ejemplos de componentes clave de las instrucciones del sistema en Looker. Estas claves incluyen lo siguiente:

system_instruction

Usa la clave system_instruction para definir el rol y el arquetipo del agente. Esta instrucción inicial establece el tono y el estilo de las respuestas de la API, y ayuda al agente a comprender su propósito principal.

Por ejemplo, puedes definir un agente como analista de ventas de una tienda de comercio electrónico ficticia de la siguiente manera:

-   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

La clave glossaries enumera las definiciones de términos comerciales, jerga y abreviaturas que son relevantes para tus datos y tu caso de uso, pero que aún no aparecen en tus datos. Por ejemplo, puedes definir términos como "estados comerciales comunes" y "cliente leal" según el contexto específico de tu empresa de la siguiente manera:

-   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

La clave additional_descriptions enumera cualquier instrucción general o contexto adicional que no se aborde en otras partes de las instrucciones del sistema. Por ejemplo, puedes usar la clave additional_descriptions para proporcionar información sobre tu agente de la siguiente manera:

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

Ejemplo: Instrucciones del sistema en Looker

En el siguiente ejemplo, se muestran instrucciones del sistema de muestra para un agente analista de ventas ficticio:

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

¿Qué sigue?

Después de definir los campos estructurados y las instrucciones del sistema que componen tu contexto creado, puedes proporcionar ese contexto a la API de Conversational Analytics en una de las siguientes llamadas: