BigQuery 데이터 소스의 데이터 에이전트 컨텍스트 정의

작성된 컨텍스트는 데이터 에이전트 소유자가 데이터 에이전트의 동작을 형성하고 API의 응답을 미세 조정하기 위해 제공할 수 있는 안내입니다. 효과적으로 작성된 컨텍스트는 Conversational Analytics API 데이터 에이전트가 데이터 소스에 관한 질문에 답변하는 데 유용한 컨텍스트를 제공합니다.

이 페이지에서는 BigQuery 데이터 소스에 대해 작성된 컨텍스트를 제공하는 방법을 설명합니다. BigQuery 데이터 소스의 경우 구조화된 컨텍스트와 시스템 요청 사항을 조합하여 작성된 컨텍스트를 제공할 수 있습니다. 가능한 경우 구조화된 컨텍스트 필드를 통해 컨텍스트를 제공하세요. 그런 다음 구조화된 필드에서 다루지 않는 추가 안내에 system_instruction 매개변수를 사용할 수 있습니다.

구조화된 컨텍스트 필드와 시스템 요청 사항은 모두 선택사항이지만 강력한 컨텍스트를 제공하면 에이전트가 더 정확하고 관련성 높은 대답을 제공할 수 있습니다.

작성된 컨텍스트를 구성하는 구조화된 필드와 시스템 지침을 정의한 후 다음 호출 중 하나에서 해당 컨텍스트를 API에 제공할 수 있습니다.

구조화된 컨텍스트 필드 정의

이 섹션에서는 구조화된 컨텍스트 필드를 사용하여 데이터 에이전트에 컨텍스트를 제공하는 방법을 설명합니다. 다음 정보를 상담사에게 구조화된 컨텍스트로 제공할 수 있습니다.

표 수준 구조화된 컨텍스트

tableReferences 키를 사용하여 질문에 답변하는 데 사용할 수 있는 특정 테이블에 관한 세부정보를 에이전트에게 제공합니다. 각 테이블 참조에 대해 다음 구조화된 컨텍스트 필드를 사용하여 테이블의 스키마를 정의할 수 있습니다.

  • description: 테이블의 콘텐츠와 목적에 대한 요약
  • synonyms: 테이블을 참조하는 데 사용할 수 있는 대체 용어 목록
  • tags: 테이블과 연결된 키워드 또는 태그 목록

다음 예에서는 직접 HTTP 요청과 Python SDK를 사용하여 이러한 속성을 구조화된 컨텍스트로 제공하는 방법을 보여줍니다.

HTTP

직접 HTTP 요청에서는 관련 테이블 참조의 schema 객체 내에 이러한 테이블 수준 속성을 제공합니다. 전체 요청 페이로드를 구성하는 방법의 전체 예는 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"]
    }
  }
]

Python SDK

Python SDK를 사용하는 경우 BigQueryTableReference 객체의 schema 속성에서 이러한 테이블 수준 속성을 정의할 수 있습니다. 다음 예시는 orders 및 users 테이블의 컨텍스트를 제공하는 테이블 참조 객체를 만드는 방법을 보여줍니다. 테이블 참조 객체를 빌드하고 사용하는 방법의 전체 예는 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"]

열 수준 구조화된 컨텍스트

표 참조의 schema 객체 내에 중첩된 fields 키는 개별 열을 설명하는 field 객체 목록을 사용합니다. 모든 필드에 추가 컨텍스트가 필요한 것은 아니지만, 일반적으로 사용되는 필드의 경우 추가 세부정보를 포함하면 에이전트의 성능을 개선하는 데 도움이 될 수 있습니다.

각 field 객체에 대해 다음 구조화된 컨텍스트 필드를 사용하여 열의 기본 속성을 정의할 수 있습니다.

  • description: 열의 콘텐츠 및 용도에 대한 간단한 설명
  • synonyms: 열을 참조하는 데 사용할 수 있는 대체 용어 목록
  • tags: 열과 연결된 키워드 또는 태그 목록

다음 예에서는 직접 HTTP 요청과 Python SDK를 사용하여 orders 테이블 내의 status 필드와 users 테이블 내의 first_name 필드에 이러한 속성을 구조화된 컨텍스트로 제공하는 방법을 보여줍니다.

HTTP

직접 HTTP 요청에서는 표 참조의 schema 객체 내에 fields 객체 목록을 제공하여 이러한 열 수준 속성을 정의할 수 있습니다.

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

Python SDK

Python SDK를 사용하는 경우 테이블의 schema 속성의 fields 속성에 Field 객체 목록을 할당하여 이러한 열 수준 속성을 정의할 수 있습니다.

# 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"],
    )
]

쿼리 예

example_queries 키는 example_query 객체 목록을 사용하여 에이전트가 일반적이거나 중요한 질문에 더 정확하고 관련성 높은 답변을 제공하는 데 도움이 되는 자연어 질문을 정의합니다. 자연어 질문과 해당 SQL 쿼리를 에이전트에게 제공하면 에이전트가 더 높은 품질의 일관된 결과를 제공하도록 안내할 수 있습니다.

각 example_query 객체에 대해 다음 필드를 제공하여 자연어 질문과 해당 SQL 쿼리를 정의할 수 있습니다.

  • natural_language_question: 사용자가 질문할 수 있는 자연어 질문
  • sql_query: 자연어 질문에 해당하는 SQL 쿼리

다음 예시에서는 직접 HTTP 요청과 Python SDK를 모두 사용하여 orders 테이블에 대한 예시 쿼리를 제공하는 방법을 보여줍니다.

HTTP

직접 HTTP 요청에서 example_queries 필드에 example_query 객체 목록을 제공합니다. 각 객체에는 naturalLanguageQuestion 키와 해당 sqlQuery 키가 포함되어야 합니다.

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

Python SDK

Python SDK를 사용하는 경우 ExampleQuery 객체 목록을 제공할 수 있습니다. 각 객체에 대해 natural_language_question 및 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'",
    )
]

시스템 요청 사항에서 추가 컨텍스트 정의

system_instruction 파라미터를 사용하여 구조화된 컨텍스트 필드에서 지원하지 않는 컨텍스트에 대한 추가 안내를 제공할 수 있습니다. 추가 안내를 제공하면 에이전트가 데이터와 사용 사례의 컨텍스트를 더 잘 이해할 수 있습니다.

시스템 요청 사항은 데이터 소스에 관한 세부정보와 질문에 답할 때 에이전트의 역할에 관한 안내를 데이터 에이전트에 제공하는 일련의 주요 구성요소와 객체로 구성됩니다. system_instruction 파라미터에서 YAML 형식 문자열로 데이터 에이전트에 시스템 요청 사항을 제공할 수 있습니다.

다음 템플릿은 사용 가능한 키와 예상 데이터 유형을 포함하여 BigQuery 데이터 소스의 system_instruction 파라미터에 제공할 수 있는 문자열의 권장 YAML 구조를 보여줍니다. 이 템플릿은 시스템 명령어를 정의하는 데 중요한 구성요소를 포함한 권장 구조를 제공하지만, 가능한 모든 시스템 명령어 형식을 포함하지는 않습니다.

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

다음 섹션에는 시스템 요청 사항의 주요 구성요소 예시가 포함되어 있습니다.

system_instruction

system_instruction 키를 사용하여 에이전트의 역할과 페르소나를 정의합니다. 이 초기 명령은 API의 응답에 대한 어조와 스타일을 설정하고 에이전트가 핵심 목적을 이해하는 데 도움이 됩니다.

예를 들어 가상의 전자상거래 매장의 영업 분석가로 에이전트를 다음과 같이 정의할 수 있습니다.

- 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

테이블의 기본 속성 (예: 설명 및 동의어)을 구조화된 컨텍스트로 정의하는 동시에 시스템 안내 내에서 tables 키를 사용하여 보충 비즈니스 로직을 제공할 수도 있습니다. BigQuery 데이터 소스의 경우 fields 키를 사용하여 특정 열의 기본 aggregations를 정의하는 것이 포함됩니다.

다음 샘플 YAML 코드 블록은 시스템 요청 사항 내에서 tables 키를 사용하여 표 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

시스템 안내의 relationships 키에는 테이블 간의 조인 관계 목록이 포함되어 있습니다. 조인 관계를 정의하면 에이전트가 질문에 답변할 때 여러 테이블의 데이터를 조인하는 방법을 이해하는 데 도움이 됩니다.

예를 들어 bigquery-public-data.thelook_ecommerce.orders 테이블과 bigquery-public-data.thelook_ecommerce.users 테이블 간의 orders_to_user 관계를 다음과 같이 정의할 수 있습니다.

- 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

시스템 안내의 glossaries 키에는 데이터 및 사용 사례와 관련된 비즈니스 용어, 전문 용어, 약어의 정의가 나열됩니다. 용어집 정의를 제공하면 에이전트가 특정 비즈니스 언어를 사용하는 질문을 정확하게 해석하고 답변하는 데 도움이 됩니다.

예를 들어 다음과 같이 특정 비즈니스 컨텍스트에 따라 일반적인 비즈니스 상태 및 'OMPF'와 같은 용어를 정의할 수 있습니다.

- 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

additional_descriptions 키를 사용하여 다른 구조화된 컨텍스트나 시스템 요청 사항 필드에 맞지 않는 일반 요청 사항이나 컨텍스트를 제공하세요. 시스템 요청 사항에 추가 설명을 제공하면 에이전트가 데이터와 사용 사례의 컨텍스트를 더 잘 이해할 수 있습니다.

예를 들어 additional_descriptions 키를 사용하여 다음과 같이 조직에 관한 정보를 제공할 수 있습니다.

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

예: 영업 상담사를 위해 작성된 컨텍스트

가상의 영업 분석가 에이전트의 다음 예시에서는 구조화된 컨텍스트와 시스템 요청 사항을 조합하여 작성된 컨텍스트를 제공하는 방법을 보여줍니다.

예: 구조화된 컨텍스트

다음 HTTP 및 Python SDK 예와 같이 테이블, 열, 예시 쿼리에 관한 세부정보가 포함된 구조화된 컨텍스트를 제공하여 에이전트를 안내할 수 있습니다.

HTTP

다음 예는 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'"
    }
  ]
}

Python SDK

다음 예에서는 Python SDK를 사용하여 구조화된 컨텍스트를 정의하는 방법을 보여줍니다.

# 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'",
  )
]

예: 시스템 안내

다음 시스템 안내는 에이전트의 페르소나를 정의하고 관계 정의, 용어집, 추가 설명, 보충 orders 표 세부정보와 같이 구조화된 필드에서 지원되지 않는 안내를 제공하여 구조화된 컨텍스트를 보완합니다. 이 예에서는 users 테이블이 구조화된 컨텍스트로 완전히 정의되어 있으므로 시스템 안내에서 재정의할 필요가 없습니다.

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