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

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.

Nesta página, descrevemos como fornecer contexto criado para fontes de dados do BigQuery. Para fontes de dados do BigQuery, é possível fornecer contexto criado usando uma combinação de contexto estruturado e instruções do sistema. Sempre que possível, ofereç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.

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.

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

Definir campos de contexto estruturado

Nesta seção, descrevemos como fornecer contexto a um agente de dados usando campos de contexto estruturados. Você pode fornecer as seguintes informações a um agente como contexto estruturado:

Contexto estruturado no nível da tabela

Use a chave tableReferences para fornecer a um agente detalhes sobre as tabelas específicas disponíveis para responder a perguntas. Para cada referência de tabela, você pode usar os seguintes campos de contexto estruturado para definir o esquema de uma tabela:

  • description: um resumo do conteúdo e da finalidade da tabela.
  • synonyms: uma lista de termos alternativos que podem ser usados para se referir à tabela.
  • tags: uma lista de palavras-chave ou tags associadas à tabela.

Os exemplos a seguir mostram como fornecer essas propriedades como contexto estruturado em solicitações HTTP diretas e com o SDK do Python.

HTTP

Em uma solicitação HTTP direta, você fornece essas propriedades no nível da tabela dentro do objeto schema para a referência de tabela relevante. Para ver um exemplo completo de como estruturar o payload da solicitação completa, consulte Conectar-se aos dados do BigQuery.

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
        "description": "Data for orders in The Look, a fictitious ecommerce store.",
        "synonyms": ["sales"],
        "tags": ["sale", "order", "sales_order"]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
        "description": "Data for users in The Look, a fictitious ecommerce store.",
        "synonyms": ["customers"],
        "tags": ["user", "customer", "buyer"]
    }
  }
]

SDK do Python

Ao usar o SDK do Python, você pode definir essas propriedades no nível da tabela na propriedade schema de um objeto BigQueryTableReference. O exemplo a seguir mostra como criar objetos de referência de tabela que fornecem contexto para as tabelas orders e users. Para um exemplo completo de como criar e usar objetos de referência de tabela, consulte Conectar-se a dados do BigQuery.

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]

Contexto estruturado no nível da coluna

A chave fields, que está aninhada no objeto schema de uma referência de tabela, usa uma lista de objetos field para descrever colunas individuais. Nem todos os campos precisam de contexto adicional, mas, para os usados com frequência, incluir mais detalhes pode ajudar a melhorar a performance do agente.

Para cada objeto field, é possível usar os seguintes campos de contexto estruturado para definir as propriedades fundamentais de uma coluna:

  • description: uma breve descrição do conteúdo e da finalidade da coluna
  • synonyms: uma lista de termos alternativos que podem ser usados para se referir à coluna
  • tags: uma lista de palavras-chave ou tags associadas à coluna.

Os exemplos a seguir mostram como fornecer essas propriedades como contexto estruturado para o campo status na tabela orders e para o campo first_name na tabela users com solicitações HTTP diretas e com o SDK do Python.

HTTP

Em uma solicitação HTTP direta, é possível definir essas propriedades no nível da coluna fornecendo uma lista de objetos fields no objeto schema de uma referência de tabela.

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
      "fields": [{
          "name": "status",
          "description": "The current status of the order.",
      }]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
      "fields": [{
          "name": "first_name",
          "description": "The first name of the user.",
          "tags": "person",
      }]
    }
  }
]

SDK do Python

Ao usar o SDK do Python, é possível definir essas propriedades no nível da coluna atribuindo uma lista de objetos Field à propriedade fields da propriedade schema de uma tabela.

# Define column context for the 'orders' table
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    )
]

# Define column context for the 'users' table
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    )
]

Exemplo de consultas

A chave example_queries usa uma lista de objetos example_query para definir consultas de linguagem natural que ajudam o agente a dar respostas mais precisas e relevantes a perguntas comuns ou importantes. Ao fornecer ao agente uma pergunta em linguagem natural e a consulta SQL correspondente, você pode orientar o agente a fornecer resultados de maior qualidade e mais consistentes.

Para cada objeto example_query, você pode fornecer os seguintes campos para definir uma pergunta em linguagem natural e a consulta SQL correspondente:

  • natural_language_question: a pergunta em linguagem natural que um usuário pode fazer
  • sql_query: a consulta SQL que corresponde à pergunta em linguagem natural

Os exemplos a seguir mostram como fornecer consultas de exemplo para a tabela orders com solicitações HTTP diretas e com o SDK do Python.

HTTP

Em uma solicitação HTTP direta, forneça uma lista de objetos example_query no campo example_queries. Cada objeto precisa conter uma chave naturalLanguageQuestion e uma chave sqlQuery correspondente.

"example_queries": [
  {
    "naturalLanguageQuestion": "How many orders are there?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`"
  },
  {
    "naturalLanguageQuestion": "How many orders were shipped?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'"
  }
]

SDK do Python

Ao usar o SDK do Python, é possível fornecer uma lista de objetos ExampleQuery. Para cada objeto, forneça valores para os parâmetros natural_language_question e sql_query.

example_queries = [
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many orders are there?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`",
    ),
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many orders were shipped?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'",
    )
]

Definir mais contexto nas instruções do sistema

Use o parâmetro system_instruction para fornecer orientação complementar sobre contextos que não são compatíveis com campos de contexto estruturado. Ao fornecer mais orientações, você ajuda o agente a entender melhor o contexto dos seus dados e caso de uso.

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 a seguir mostra uma estrutura YAML sugerida para a string, que você pode fornecer ao parâmetro system_instruction de uma fonte de dados do BigQuery, incluindo chaves disponíveis e tipos de dados esperados. Embora esse modelo forneça uma estrutura sugerida com componentes importantes para definir instruções do sistema, ele não inclui todos os formatos possíveis.

- system_instruction: str # A description of the expected behavior of the agent. For example: You are a sales agent.
- tables: # A list of tables to describe for the agent.
  - table: # Details about a single table that is relevant for the agent.
    - name: str # The name of the table.
    - fields: # Details about columns (fields) within the table.
      - field: # Details about a single column within the current table.
        - name: str # The name of the column.
        - aggregations: list[str] # Commonly used or default aggregations for the column.
  - relationships: # A list of join relationships between tables.
    - relationship: # Details about a single join relationship.
      - name: str # The name of this join relationship.
      - description: str # A description of the relationship.
      - relationship_type: str # The join relationship type: one-to-one, one-to-many, many-to-one, or many-to-many.
      - join_type: str # The join type: inner, outer, left, right, or full.
      - left_table: str # The name of the left table in the join.
      - right_table: str # The name of the right table in the join.
      - relationship_columns: # A list of columns that are used for the join.
        - left_column: str # The join column from the left table.
        - right_column: str # The join column from the right table.
- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
  - glossary: # The definition for a single glossary item.
    - term: str # The term, phrase, or abbreviation to define.
    - description: str # A description or definition of the term.
    - synonyms: list[str] # Alternative terms for the glossary entry.
- additional_descriptions: # A list of any other general instructions or content.
  - text: str # Any additional general instructions or context not covered elsewhere.

As seções a seguir contêm exemplos dos componentes principais das instruções do sistema:

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.

tables

Ao definir as propriedades fundamentais de uma tabela (como descrição e sinônimos) como contexto estruturado, você também pode usar a chave tables nas instruções do sistema para fornecer lógica de negócios complementar. Para fontes de dados do BigQuery, isso inclui o uso da chave fields para definir aggregations padrão para colunas específicas.

O bloco de código YAML de exemplo a seguir mostra como usar a chave tables nas instruções do sistema para aninhar campos que fornecem orientação complementar para a tabela bigquery-public-data.thelook_ecommerce.orders:

- tables:
  - table:
    - name: bigquery-public-data.thelook_ecommerce.orders
    - fields:
      - field:
        - name: num_of_items
        - aggregations: 'sum, avg'

relationships

A chave relationships nas instruções do sistema contém uma lista de relações de junção entre tabelas. Ao definir relações de junção, você ajuda o agente a entender como combinar dados de várias tabelas ao responder a perguntas.

Por exemplo, é possível definir uma relação orders_to_user entre as tabelas bigquery-public-data.thelook_ecommerce.orders e bigquery-public-data.thelook_ecommerce.users da seguinte maneira:

- relationships:
  - relationship:
    - name: orders_to_user
    - description: >-
        Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
    - relationship_type: many-to-one
    - join_type: left
    - left_table: bigquery-public-data.thelook_ecommerce.orders
    - right_table: bigquery-public-data.thelook_ecommerce.users
    - relationship_columns:
      - left_column: user_id
      - right_column: id

glossaries

A chave glossaries nas instruções do sistema lista definições de termos comerciais, jargões e abreviações relevantes para seus dados e caso de uso. Ao fornecer definições de glossário, você ajuda o agente a interpretar e responder com precisão a perguntas que usam uma linguagem comercial específica.

Por exemplo, você pode definir termos como status da empresa comuns e "OMPF" de acordo com seu contexto comercial específico da seguinte forma:

- glossaries:
  - glossary:
    - term: complete
    - description: Represents an order status where the order has been completed.
    - synonyms: 'finish, done, fulfilled'
  - glossary:
    - term: shipped
    - description: Represents an order status where the order has been shipped to the customer.
  - glossary:
    - term: returned
    - description: Represents an order status where the customer has returned the order.
  - glossary:
    - term: OMPF
    - description: Order Management and Product Fulfillment

additional_descriptions

Use a chave additional_descriptions para fornecer instruções gerais ou contexto que não se encaixam em outros campos de contexto estruturado ou instruções do sistema. Ao fornecer mais descrições nas instruções do sistema, você ajuda o agente a entender melhor o contexto dos seus dados e caso de uso.

Por exemplo, é possível usar a chave additional_descriptions para fornecer informações sobre sua organização da seguinte forma:

- additional_descriptions:
  - text: All the sales data pertains to The Look, a fictitious ecommerce store.
  - text: 'Orders can be of three categories: food, clothes, and electronics.'

Exemplo: contexto criado para um agente de vendas

O exemplo a seguir para um agente analista de vendas fictício demonstra como fornecer contexto criado usando uma combinação de contexto estruturado e instruções do sistema.

Exemplo: contexto estruturado

Você pode fornecer contexto estruturado com detalhes sobre tabelas, colunas e exemplos de consultas para orientar o agente, conforme mostrado nos exemplos a seguir de HTTP e SDK do Python.

HTTP

O exemplo a seguir mostra como definir um contexto estruturado em uma solicitação HTTP:

{
  "bq": {
    "tableReferences": [
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "orders",
        "schema": {
          "description": "Data for orders in The Look, a fictitious ecommerce store.",
          "synonyms": ["sales"],
          "tags": ["sale", "order", "sales_order"],
          "fields": [
            {
              "name": "status",
              "description": "The current status of the order."
            },
            {
              "name": "num_of_items",
              "description": "The number of items in the order."
            }
          ]
        }
      },
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "users",
        "schema": {
          "description": "Data for users in The Look, a fictitious ecommerce store.",
          "synonyms": ["customers"],
          "tags": ["user", "customer", "buyer"],
          "fields": [
            {
              "name": "first_name",
              "description": "The first name of the user.",
              "tags": ["person"]
            },
            {
              "name": "last_name",
              "description": "The last name of the user.",
              "tags": ["person"]
            },
            {
              "name": "age_group",
              "description": "The age demographic group of the user."
            },
            {
              "name": "email",
              "description": "The email address of the user.",
              "tags": ["contact"]
            }
          ]
        }
      }
    ]
  },
  "example_queries": [
    {
      "naturalLanguageQuestion": "How many orders are there?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`"
    },
    {
      "naturalLanguageQuestion": "How many orders were shipped?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'"
    },
    {
      "naturalLanguageQuestion": "How many unique customers are there?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`"
    },
    {
      "naturalLanguageQuestion": "How many users in the 25-34 age group have a cymbalgroup email address?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'"
    }
  ]
}

SDK do Python

O exemplo a seguir mostra como definir o contexto estruturado com o SDK Python:

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    ),
    geminidataanalytics.Field(
        name="num_of_items",
        description="The number of items in the order."
    )
]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="last_name",
        description="The last name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="age_group",
        description="The age demographic group of the user.",
    ),
    geminidataanalytics.Field(
        name="email",
        description="The email address of the user.",
        tags=["contact"],
    )
]

# Define example queries
example_queries = [
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders are there?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders were shipped?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many unique customers are there?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many users in the 25-34 age group have a cymbalgroup email address?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'",
  )
]

Exemplo: instruções do sistema

As instruções do sistema a seguir complementam o contexto estruturado definindo a personalidade do agente e fornecendo orientações que não são compatíveis com campos estruturados, como definições de relacionamento, termos do glossário, descrições adicionais e detalhes complementares da tabela orders. Neste exemplo, como a tabela users está totalmente definida com contexto estruturado, ela não precisa ser redefinida nas instruções do sistema.

- 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.
- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - fields:
            - field:
                - name: num_of_items
                - aggregations: 'sum, avg'
- relationships:
    - relationship:
        - name: orders_to_user
        - description: >-
            Connects customer order data to user information with the user_id and id fields.
        - relationship_type: many-to-one
        - join_type: left
        - left_table: bigquery-public-data.thelook_ecommerce.orders
        - right_table: bigquery-public-data.thelook_ecommerce.users
        - relationship_columns:
            - left_column: user_id
            - right_column: id
- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment
- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.