Menentukan konteks agen data untuk sumber data BigQuery

Halaman ini menjelaskan cara memberikan konteks yang dibuat untuk agen data yang menggunakan sumber data BigQuery.

Konteks yang dibuat adalah panduan yang dapat diberikan oleh pemilik agen data untuk membentuk perilaku agen data dan menyempurnakan respons API. Konteks yang dibuat secara efektif memberikan konteks yang berguna kepada agen data Conversational Analytics API Anda untuk menjawab pertanyaan tentang sumber data Anda.

Halaman ini menjelaskan cara memberikan konteks yang dibuat untuk sumber data BigQuery. Untuk sumber data BigQuery, Anda dapat memberikan konteks yang dibuat melalui kombinasi konteks terstruktur dan petunjuk sistem. Jika memungkinkan, berikan konteks melalui kolom konteks terstruktur. Kemudian, gunakan parameter system_instruction untuk panduan tambahan yang tidak tercakup dalam kolom terstruktur. Petunjuk sistem adalah jenis konteks yang dibuat yang dapat diberikan oleh pemilik agen data kepada agen untuk memberi tahu agen tentang peran, nada, dan perilaku keseluruhannya. Petunjuk sistem sering kali dapat lebih bebas daripada konteks terstruktur.

Meskipun kolom konteks terstruktur dan petunjuk sistem bersifat opsional, memberikan konteks yang kuat memungkinkan agen memberikan respons yang lebih akurat dan relevan. Agen data Anda menggabungkan konteks yang dibuat selama pembuatan dan runtime untuk memastikan tindakan, kueri, dan responsnya akurat, sesuai, dan memahami bisnis. Konteks ini di-ingest, diindeks, dan digunakan untuk membentuk perilaku agen melalui kombinasi petunjuk sistem dan konteks terstruktur.

Meskipun kolom konteks terstruktur dan petunjuk sistem bersifat opsional, memberikan konteks yang kuat memungkinkan agen memberikan respons yang lebih akurat dan relevan.

Setelah menentukan kolom terstruktur dan petunjuk sistem yang membentuk konteks yang dibuat, Anda dapat memberikan konteks tersebut ke API dalam salah satu panggilan berikut:

Menentukan kolom konteks terstruktur

Bagian ini menjelaskan cara memberikan konteks ke agen data menggunakan kolom konteks terstruktur. Anda dapat memberikan informasi berikut kepada agen sebagai konteks terstruktur:

Konteks terstruktur tingkat tabel

Gunakan kunci tableReferences untuk memberikan detail kepada agen tentang tabel tertentu yang tersedia untuk menjawab pertanyaan. Untuk setiap referensi tabel, Anda dapat menggunakan kolom konteks terstruktur berikut untuk menentukan skema tabel:

  • description: Ringkasan konten dan tujuan tabel
  • synonyms: Daftar istilah alternatif yang dapat digunakan untuk merujuk ke tabel
  • tags: Daftar kata kunci atau tag yang terkait dengan tabel

Contoh berikut menunjukkan cara memberikan properti ini sebagai konteks terstruktur dalam permintaan HTTP langsung dan dengan Python SDK.

HTTP

Dalam permintaan HTTP langsung, Anda memberikan properti tingkat tabel ini dalam objek schema untuk referensi tabel yang relevan. Untuk contoh lengkap cara menyusun payload permintaan lengkap, lihat Menghubungkan ke data 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

Saat menggunakan Python SDK, Anda dapat menentukan properti tingkat tabel ini pada properti schema dari objek BigQueryTableReference. Contoh berikut menunjukkan cara membuat objek referensi tabel yang memberikan konteks untuk tabel orders dan users. Untuk contoh lengkap cara membuat dan menggunakan objek referensi tabel, lihat Menghubungkan ke data BigQuery data.

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

Konteks terstruktur tingkat kolom

Kunci fields, yang disusun bertingkat dalam objek schema referensi tabel, menggunakan daftar objek field untuk mendeskripsikan setiap kolom. Tidak semua kolom memerlukan konteks tambahan; namun, untuk kolom yang umum digunakan, menyertakan detail tambahan dapat membantu meningkatkan performa agen.

Untuk setiap objek field, Anda dapat menggunakan kolom konteks terstruktur berikut untuk menentukan properti dasar kolom:

  • description: Deskripsi singkat tentang konten dan tujuan kolom
  • synonyms: Daftar istilah alternatif yang dapat digunakan untuk merujuk ke kolom
  • tags: Daftar kata kunci atau tag yang terkait dengan kolom

Contoh berikut menunjukkan cara memberikan properti ini sebagai konteks terstruktur untuk kolom status dalam tabel orders dan untuk kolom first_name dalam tabel users dengan permintaan HTTP langsung dan dengan Python SDK.

HTTP

Dalam permintaan HTTP langsung, Anda dapat menentukan properti tingkat kolom ini dengan memberikan daftar objek fields dalam objek schema referensi tabel.

"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

Saat menggunakan Python SDK, Anda dapat menentukan properti tingkat kolom ini dengan menetapkan daftar objek Field ke properti fields dari properti schema tabel.

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

Contoh kueri

Kunci example_queries menggunakan daftar objek example_query untuk menentukan kueri natural language yang membantu agen memberikan respons yang lebih akurat dan relevan terhadap pertanyaan umum atau penting. Dengan memberikan pertanyaan natural language dan kueri SQL yang sesuai kepada agen, Anda dapat memandu agen untuk memberikan hasil yang lebih berkualitas dan lebih konsisten.

Untuk setiap objek example_query, Anda dapat memberikan kolom berikut untuk menentukan pertanyaan natural language dan kueri SQL yang sesuai:

  • natural_language_question: Pertanyaan natural language yang mungkin diajukan pengguna
  • sql_query: Kueri SQL yang sesuai dengan pertanyaan natural language

Contoh berikut menunjukkan cara memberikan contoh kueri untuk tabel orders dengan permintaan HTTP langsung dan dengan Python SDK.

HTTP

Dalam permintaan HTTP langsung, berikan daftar objek example_query di kolom example_queries. Setiap objek harus berisi kunci naturalLanguageQuestion dan kunci sqlQuery yang sesuai.

"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

Saat menggunakan Python SDK, Anda dapat memberikan daftar objek ExampleQuery. Untuk setiap objek, berikan nilai untuk parameter natural_language_question dan 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'",
    )
]

Menentukan konteks tambahan dalam petunjuk sistem

Anda dapat menggunakan parameter system_instruction untuk memberikan panduan tambahan untuk konteks yang tidak didukung oleh kolom konteks terstruktur. Dengan memberikan panduan tambahan ini, Anda dapat membantu agen memahami konteks data dan kasus penggunaan Anda dengan lebih baik.

Petunjuk sistem terdiri dari serangkaian komponen dan objek utama yang memberikan detail kepada agen data tentang sumber data dan panduan tentang peran agen saat menjawab pertanyaan. Anda dapat memberikan petunjuk sistem kepada agen data dalam parameter system_instruction sebagai string berformat YAML.

Template berikut menunjukkan struktur YAML yang disarankan untuk string, yang dapat Anda berikan ke parameter system_instruction untuk sumber data BigQuery, termasuk kunci yang tersedia dan jenis data yang diharapkan. Meskipun template ini memberikan struktur yang disarankan dengan komponen penting untuk menentukan petunjuk sistem, template ini tidak menyertakan semua format petunjuk sistem yang mungkin.

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

Bagian berikut berisi contoh komponen utama petunjuk sistem:

system_instruction

Gunakan kunci system_instruction untuk menentukan peran dan persona agen. Petunjuk awal ini menetapkan nada dan gaya untuk respons API serta membantu agen memahami tujuan utamanya.

Misalnya, Anda dapat menentukan agen sebagai analis penjualan untuk toko ecommerce fiktif sebagai berikut:

-   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

Meskipun Anda menentukan properti dasar tabel (seperti deskripsi dan sinonimnya) sebagai konteks terstruktur, Anda juga dapat menggunakan kunci tables dalam petunjuk sistem untuk memberikan logika bisnis tambahan. Untuk sumber data BigQuery, hal ini mencakup penggunaan kunci fields untuk menentukan aggregations default untuk kolom tertentu.

Blok kode YAML contoh berikut menunjukkan cara menggunakan kunci tables dalam petunjuk sistem untuk menyusun kolom yang memberikan panduan tambahan untuk tabel 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

Kunci relationships dalam petunjuk sistem Anda berisi daftar hubungan gabungan antar-tabel. Dengan menentukan hubungan gabungan, Anda dapat membantu agen memahami cara menggabungkan data dari beberapa tabel saat menjawab pertanyaan.

Sebagai contoh, Anda dapat menentukan hubungan orders_to_user antara tabel bigquery-public-data.thelook_ecommerce.orders dan tabel bigquery-public-data.thelook_ecommerce.users sebagai berikut:

-   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

Kunci glossaries dalam petunjuk sistem Anda mencantumkan definisi untuk istilah bisnis, jargon, dan singkatan yang relevan dengan data dan kasus penggunaan Anda. Dengan memberikan definisi glosarium, Anda dapat membantu agen menafsirkan dan menjawab pertanyaan yang menggunakan bahasa bisnis tertentu secara akurat.

Sebagai contoh, Anda dapat menentukan istilah seperti status bisnis umum dan "OMPF" sesuai dengan konteks bisnis spesifik Anda sebagai berikut:

- 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

Gunakan kunci additional_descriptions untuk memberikan petunjuk atau konteks umum yang tidak sesuai dengan kolom konteks terstruktur atau petunjuk sistem lainnya. Dengan memberikan deskripsi tambahan dalam petunjuk sistem, Anda dapat membantu agen memahami konteks data dan kasus penggunaan Anda dengan lebih baik.

Sebagai contoh, Anda dapat menggunakan kunci additional_descriptions untuk memberikan informasi tentang organisasi Anda sebagai berikut:

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

Contoh: Konteks yang dibuat untuk agen penjualan

Contoh berikut untuk agen analis penjualan fiktif menunjukkan cara memberikan konteks yang dibuat menggunakan kombinasi konteks terstruktur dan petunjuk sistem.

Contoh: Konteks terstruktur

Anda dapat memberikan konteks terstruktur dengan detail tentang tabel, kolom, dan contoh kueri untuk memandu agen, seperti yang ditunjukkan dalam contoh HTTP dan Python SDK berikut.

HTTP

Contoh berikut menunjukkan cara menentukan konteks terstruktur dalam permintaan 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

Contoh berikut menunjukkan cara menentukan konteks terstruktur dengan 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'",
)
]

Contoh: Petunjuk sistem

Petunjuk sistem berikut melengkapi konteks terstruktur dengan menentukan persona agen dan memberikan panduan yang tidak didukung oleh kolom terstruktur, seperti definisi hubungan, istilah glosarium, deskripsi tambahan, dan detail tabel orders tambahan. Dalam contoh ini, karena tabel users sepenuhnya ditentukan dengan konteks terstruktur, tabel tersebut tidak perlu ditentukan ulang dalam petunjuk sistem.

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