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

효과적인 시스템 요청 사항을 작성하면 Conversational Analytics API 데이터 에이전트가 데이터 소스에 관한 질문에 답변하는 데 유용한 컨텍스트를 제공할 수 있습니다. 시스템 요청 사항은 데이터 에이전트 소유자가 데이터 에이전트의 동작을 형성하고 API의 응답을 개선하기 위해 제공할 수 있는 작성된 컨텍스트의 일종입니다.

이 페이지에서는 BigQuery 데이터에 연결되는 Conversational Analytics API 데이터 에이전트를 위해 효과적인 프롬프트를 작성하기 위한 권장 구조를 설명합니다. 이러한 프롬프트는 system_instruction 파라미터를 사용하여 문자열로 정의하는 작성된 컨텍스트입니다.

이 페이지에서는 BigQuery 데이터베이스를 기반으로 하는 BigQuery 데이터 소스에 대한 시스템 요청 사항을 작성하는 방법을 설명합니다.

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

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

다음 템플릿은 사용 가능한 키와 예상 데이터 유형을 포함하여 system_instruction 파라미터에 제공하는 문자열의 권장 YAML 구조를 보여줍니다.

다음 YAML 템플릿은 BigQuery 데이터 소스의 시스템 요청 사항을 구성하는 방법을 보여주는 예시입니다.

- 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.
        - description: str # A description of the table.
        - synonyms: list[str] # Alternative terms for referring to the table.
        - tags: list[str] # Keywords or tags that are associated with 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.
                - description: str # A description of the column.
                - synonyms: list[str] # Alternative terms for referring to the column.
                - tags: list[str] # Keywords or tags that are associated with the column.
                - sample_values: list[str] # Sample values that are present within the column.
                - aggregations: list[str] # Commonly used or default aggregations for the column.
        - measures: # A list of calculated metrics (measures) for the table.
            - measure: # Details about a single measure within the table.
                - name: str # The name of the measure.
                - description: str # A description of the measure.
                - exp: str # The expression that is used to construct the measure.
                - synonyms: list[str] # Alternative terms for referring to the measure.
        - golden_queries: # A list of important or popular ("golden") queries for the table.
            - golden_query: # Details about a single golden query.
                - natural_language_query: str # The natural language query.
                - sql_query: str # The SQL query that corresponds to the natural language query.
        - golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
            - golden_action_plan: # Details about a single action plan.
                - natural_language_query: str # The natural language query.
                - action_plan: # A list of the steps for this action plan.
                    - step: str # A single step within the action plan.
    - 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.

BigQuery 데이터 소스를 사용하는 시스템 요청 사항의 주요 구성요소 예시

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

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 키에는 에이전트의 테이블 설명 목록이 포함되어 있으며, 질문에 답변하기 위해 에이전트가 사용할 수 있는 특정 데이터에 관한 세부정보가 제공됩니다. 이 목록의 각 table 객체에는 테이블 이름, 설명, 동의어, 태그, 필드, 측정항목, 표준 쿼리, 표준 작업 계획 등 특정 테이블의 메타데이터가 포함됩니다. 다음 YAML 코드 블록은 테이블 bigquery-public-data.thelook_ecommerce.orders에 대한 tables 키의 기본 구조를 보여줍니다.

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - description: Data for customer orders in The Look fictitious e-commerce store.
        - synonyms:
            - sales
            - orders_data
        - tags:
            - ecommerce
            - transaction

fields

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

다음 샘플 YAML 코드는 orders 테이블의 order_id, status, created_at, num_of_items, earnings와 같은 주요 필드를 설명합니다.

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - fields:
            - field:
                - name: order_id
                - description: The unique identifier for each customer order.
            - field:
                - name: user_id
                - description: The unique identifier for each customer.
            - field:
                - name: status
                - description: The current status of the order.
                - sample_values:
                    - complete
                    - shipped
                    - returned
            - field:
                - name: created_at
                - description: The timestamp when the order was created.
            - field:
                - name: num_of_items
                - description: The total number of items in the order.
                - aggregations:
                    - sum
                    - avg
            - field:
                - name: earnings
                - description: The sales amount for the order.
                - aggregations:
                    - sum
                    - avg

measures

table 객체 내에 중첩된 measures 키는 테이블에 열로 직접 표시되지 않는 커스텀 비즈니스 측정항목 또는 계산을 정의합니다. 측정값에 대한 컨텍스트를 제공하면 에이전트가 핵심성과지표(KPI) 또는 기타 계산된 값에 관한 질문에 답변하는 데 도움이 됩니다.

예를 들어 profit 측정은 다음과 같이 순익에서 비용을 뺀 계산으로 정의할 수 있습니다.

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - measures:
            - measure:
                - name: profit
                - description: Raw profit (earnings minus cost).
                - exp: earnings - cost
                - synonyms: gains

golden_queries

table 객체 내에 중첩된 golden_queries 키는 golden_query 객체 목록을 사용합니다. 표준 쿼리를 사용하면 사용자가 정의할 수 있는 일반적이거나 중요한 질문에 에이전트가 더 정확하고 관련성 높은 답변을 제공할 수 있습니다.

예를 들어 orders 테이블의 데이터에 대한 일반적인 분석의 표준 쿼리를 다음과 같이 정의할 수 있습니다.

- tables:
    - table:
        - golden_queries:
            - golden_query:
                - natural_language_query: How many orders are there?
                - sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
            - golden_query:
                - natural_language_query: How many orders were shipped?
                - sql_query: >-
                    SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
                    WHERE status = 'shipped'

golden_action_plans

table 객체 내에 중첩된 golden_action_plans 키는 golden_action_plan 객체 목록을 사용합니다. 표준 작업 계획을 사용하여 데이터를 가져온 다음 시각화하는 것과 같은 다단계 요청을 처리하는 방법을 에이전트에게 예시로 제공할 수 있습니다.

예를 들어 연령대별 주문 분류를 표시하는 작업 계획을 정의하고 SQL 쿼리 및 시각화 관련 단계에 관한 세부정보를 포함할 수 있습니다.

- tables:
    - table:
        - golden_action_plans:
            - golden_action_plan:
                - natural_language_query: Show me the number of orders broken down by age group.
                - action_plan:
                    - step: >-
                        Run a SQL query that joins the table
                        sqlgen-testing.thelook_ecommerce.orders and
                        sqlgen-testing.thelook_ecommerce.users to get a
                        breakdown of order count by age group.
                    - step: >-
                        Create a vertical bar plot using the retrieved data,
                        with one bar per age group.

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

예: BigQuery의 시스템 요청 사항

다음 예시는 가상의 영업 분석가 에이전트의 샘플 시스템 요청 사항을 보여줍니다.

- 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
        - description: Data for orders in The Look, a fictitious ecommerce store.
        - synonyms: sales
        - tags: 'sale, order, sales_order'
        - fields:
            - field:
                - name: order_id
                - description: The unique identifier for each customer order.
            - field:
                - name: user_id
                - description: The unique identifier for each customer.
            - field:
                - name: status
                - description: The current status of the order.
                - sample_values:
                    - complete
                    - shipped
                    - returned
            - field:
                - name: created_at
                - description: >-
                    The date and time at which the order was created in timestamp
                    format.
            - field:
                - name: returned_at
                - description: >-
                    The date and time at which the order was returned in timestamp
                    format.
            - field:
                - name: num_of_items
                - description: The total number of items in the order.
                - aggregations: 'sum, avg'
            - field:
                - name: earnings
                - description: The sales revenue for the order.
                - aggregations: 'sum, avg'
            - field:
                - name: cost
                - description: The cost for the items in the order.
                - aggregations: 'sum, avg'
        - measures:
            - measure:
                - name: profit
                - description: Raw profit (earnings minus cost).
                - exp: earnings - cost
                - synonyms: gains
        - golden_queries:
            - golden_query:
                - natural_language_query: How many orders are there?
                - sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
            - golden_query:
                - natural_language_query: How many orders were shipped?
                - sql_query: >-
                    SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
                    WHERE status = 'shipped'
        - golden_action_plans:
            - golden_action_plan:
                - natural_language_query: Show me the number of orders broken down by age group.
                - action_plan:
                    - step: >-
                        Run a SQL query that joins the table
                        sqlgen-testing.thelook_ecommerce.orders and
                        sqlgen-testing.thelook_ecommerce.users to get a
                        breakdown of order count by age group.
                    - step: >-
                        Create a vertical bar plot using the retrieved data,
                        with one bar per age group.
    - table:
        - name: bigquery-public-data.thelook_ecommerce.users
        - description: Data for users in The Look, a fictitious ecommerce store.
        - synonyms: customers
        - tags: 'user, customer, buyer'
        - fields:
            - field:
                - name: id
                - description: The unique identifier for each user.
            - field:
                - name: first_name
                - description: The first name of the user.
                - tag: person
                - sample_values: 'alex, izumi, nur'
            - field:
                - name: last_name
                - description: The first name of the user.
                - tag: person
                - sample_values: 'warmer, stilles, smith'
            - field:
                - name: age_group
                - description: The age demographic group of the user.
                - sample_values:
                    - 18-24
                    - 25-34
                    - 35-49
                    - 50+
            - field:
                - name: email
                - description: The email address of the user.
                - tag: contact
                - sample_values: '222larabrown@gmail.com, cloudysanfrancisco@gmail.com'
        - golden_queries:
            - golden_query:
                - natural_language_query: How many unique customers are there?
                - sql_query: >-
                    SELECT COUNT(DISTINCT id) FROM
                    bigquery-public-data.thelook_ecommerce.users
            - golden_query:
                - natural_language_query: 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';
    - 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:
    - 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:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.
    - text: 'Orders can be of three categories: food, clothes, and electronics.'