Defina o contexto do agente de dados para origens de dados do BigQuery

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.

Esta página descreve como fornecer contexto criado para origens de dados do BigQuery. Para origens de dados do BigQuery, pode fornecer contexto criado através de uma combinação de contexto estruturado e instruções do sistema. Sempre que possível, forneça contexto através de campos de contexto estruturados. Em seguida, pode usar o parâmetro system_instruction para orientações suplementares que não são abrangidas pelos campos estruturados.

Embora os campos de contexto estruturado e as instruções do sistema sejam opcionais, o fornecimento de um contexto robusto permite ao agente dar respostas mais precisas e relevantes.

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

Defina campos de contexto estruturados

Esta secção descreve como fornecer contexto a um agente de dados através de campos de contexto estruturados. Pode fornecer as seguintes informações a um agente como contexto estruturado:

Contexto estruturado ao nível da tabela

Use a chave tableReferences para fornecer a um agente detalhes sobre as tabelas específicas que estão disponíveis para responder a perguntas. Para cada referência de tabela, 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 etiquetas associadas à tabela

Os exemplos seguintes mostram como fornecer estas propriedades como contexto estruturado em pedidos HTTP diretos e com o SDK Python.

HTTP

Num pedido HTTP direto, fornece estas propriedades ao nível da tabela no objeto schema para a referência da tabela relevante. Para ver um exemplo completo de como estruturar a carga útil do pedido completo, consulte o artigo Estabeleça ligação 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 Python

Quando usa o SDK Python, pode definir estas propriedades ao nível da tabela na propriedade schema de um objeto BigQueryTableReference. O exemplo seguinte mostra como criar objetos de referência de tabelas que fornecem contexto para as tabelas orders e users. Para ver um exemplo completo de como criar e usar objetos de referência de tabelas, consulte o artigo Efetue a associação 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 ao nível da coluna

A chave fields, que está aninhada no objeto schema de uma referência de tabela, recebe uma lista de objetos field para descrever colunas individuais. Nem todos os campos precisam de contexto adicional. No entanto, incluir detalhes adicionais nos campos usados com frequência pode ajudar a melhorar o desempenho do agente.

Para cada objeto field, pode 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 etiquetas associadas à coluna

Os exemplos seguintes mostram como pode fornecer estas propriedades como contexto estruturado para o campo status na tabela orders e para o campo first_name na tabela users com pedidos HTTP diretos e com o SDK Python.

HTTP

Num pedido HTTP direto, pode definir estas propriedades ao 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 Python

Quando usa o SDK Python, pode definir estas propriedades ao 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"],
    )
]

Consultas de exemplo

A chave example_queries recebe uma lista de objetos example_query para definir consultas de linguagem natural que ajudam o agente a fornecer respostas mais precisas e relevantes a perguntas comuns ou importantes. Ao fornecer ao agente uma pergunta em linguagem natural e a respetiva consulta SQL, pode orientá-lo para fornecer resultados de maior qualidade e mais consistentes.

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

  • natural_language_question: a pergunta em linguagem natural que um utilizador pode fazer
  • sql_query: A consulta SQL que corresponde à pergunta em linguagem natural

Os exemplos seguintes mostram como fornecer consultas de exemplo para a tabela orders com pedidos HTTP diretos e com o SDK Python.

HTTP

Num pedido HTTP direto, forneça uma lista de objetos example_query no campo example_queries. Cada objeto tem de 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 Python

Quando usa o SDK Python, pode 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'",
    )
]

Defina contexto adicional nas instruções do sistema

Pode usar o parâmetro system_instruction para fornecer orientações suplementares para contexto que não é suportado por campos de contexto estruturados. Com estas orientações adicionais, pode ajudar o agente a compreender melhor o contexto dos seus dados e exemplo de utilização.

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.

O modelo seguinte mostra uma estrutura YAML sugerida para a string, que pode fornecer ao parâmetro system_instruction para uma origem de dados do BigQuery, incluindo as chaves disponíveis e os tipos de dados esperados. Embora este modelo forneça uma estrutura sugerida com componentes importantes para definir instruções do sistema, não inclui todos os formatos possíveis de instruções do sistema.

- 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 secções seguintes contêm exemplos de componentes principais das instruções do sistema:

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.

tables

Embora defina as propriedades fundamentais de uma tabela (como a respetiva descrição e sinónimos) como contexto estruturado, também pode usar a chave tables nas instruções do sistema para fornecer lógica empresarial suplementar. Para origens de dados do BigQuery, isto inclui a utilização da chave fields para definir o valor aggregations predefinido para colunas específicas.

O seguinte bloco de código YAML de exemplo mostra como pode usar a chave tables nas instruções do sistema para aninhar campos que fornecem orientações suplementares 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, pode ajudar o agente a compreender como juntar dados de várias tabelas quando responde a perguntas.

Por exemplo, pode definir uma relação orders_to_user entre a tabela bigquery-public-data.thelook_ecommerce.orders e a tabela bigquery-public-data.thelook_ecommerce.users da seguinte forma:

- 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 apresenta definições de termos empresariais, jargão e abreviaturas relevantes para os seus dados e exemplo de utilização. Ao fornecer definições de glossário, pode ajudar o agente a interpretar e responder com precisão a perguntas que usam linguagem empresarial específica.

Por exemplo, pode definir termos como estados comuns da empresa e "OMPF" de acordo com o contexto específico da sua empresa 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 enquadrem noutros campos de contexto estruturado ou de instruções do sistema. Ao fornecer descrições adicionais nas instruções do sistema, pode ajudar o agente a compreender melhor o contexto dos seus dados e exemplo de utilização.

Por exemplo, pode usar a tecla additional_descriptions para fornecer informações sobre a 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 seguinte 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

Pode fornecer contexto estruturado com detalhes sobre tabelas, colunas e exemplos de consultas para orientar o agente, conforme mostrado nos seguintes exemplos de HTTP e SDK Python.

HTTP

O exemplo seguinte mostra como definir o contexto estruturado num pedido 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 Python

O exemplo seguinte 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 seguintes instruções do sistema complementam o contexto estruturado definindo a personalidade do agente e fornecendo orientações que não são suportadas por campos estruturados, como definições de relações, termos do glossário, descrições adicionais e detalhes suplementares da orders tabela. Neste exemplo, como a tabela users está totalmente definida com contexto estruturado, não precisa de 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.