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 の回答のトーンとスタイルを設定し、エージェントがその主な目的を理解するのに役立ちます。

たとえば、次のように、架空の e コマースストアのセールス アナリストとしてエージェントを定義できます。

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