Menulis petunjuk sistem yang efektif dapat memberikan konteks yang berguna bagi agen data Conversational Analytics API Anda untuk menjawab pertanyaan tentang sumber data Anda. Petunjuk sistem adalah jenis konteks yang dibuat yang dapat diberikan oleh pemilik agen data untuk membentuk perilaku agen data dan menyempurnakan respons API.
Halaman ini menjelaskan struktur yang direkomendasikan untuk menulis perintah yang efektif bagi agen data Conversational Analytics API yang terhubung ke data BigQuery. Perintah ini adalah konteks yang dibuat yang Anda tentukan sebagai string menggunakan parameter system_instruction.
Halaman ini menjelaskan cara menulis petunjuk sistem untuk sumber data BigQuery, yang didasarkan pada database BigQuery.
Menentukan konteks dalam petunjuk sistem
Petunjuk sistem terdiri dari serangkaian komponen dan objek utama yang memberikan detail tentang sumber data dan panduan tentang peran agen saat menjawab pertanyaan kepada agen data. Anda dapat memberikan petunjuk sistem ke agen data dalam parameter system_instruction sebagai string berformat YAML.
Template berikut menunjukkan struktur YAML yang disarankan untuk string yang Anda berikan ke parameter system_instruction, termasuk kunci yang tersedia dan jenis data yang diharapkan.
Template YAML berikut menunjukkan contoh cara menyusun petunjuk sistem untuk sumber data 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.
Contoh komponen utama petunjuk sistem menggunakan sumber data BigQuery
Bagian berikut berisi contoh komponen utama petunjuk sistem di BigQuery. Kunci ini mencakup:
system_instructiontablesfieldsmeasuresgolden_queriesgolden_action_plansrelationshipsglossariesadditional_descriptions
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 e-commerce 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
Kunci tables berisi daftar deskripsi tabel untuk agen dan memberikan detail tentang data spesifik yang tersedia bagi agen untuk menjawab pertanyaan. Setiap objek table dalam daftar ini berisi metadata untuk tabel tertentu, termasuk nama, deskripsi, sinonim, tag, kolom, ukuran, kueri emas, dan rencana tindakan emas tabel tersebut. Blok kode YAML berikut menunjukkan struktur dasar untuk kunci tables untuk tabel bigquery-public-data.thelook_ecommerce.orders:
- 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
Kunci fields, yang bertingkat dalam objek table, mengambil daftar objek kolom untuk mendeskripsikan setiap kolom. Tidak semua kolom memerlukan konteks tambahan; namun, untuk kolom yang umum digunakan, menyertakan detail tambahan dapat membantu meningkatkan performa agen.
Contoh kode YAML berikut menjelaskan kolom utama seperti order_id, status, created_at, num_of_items, dan earnings untuk tabel orders:
- 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
Kunci measures, yang berada di dalam objek table, menentukan metrik atau penghitungan bisnis kustom yang tidak secara langsung ada sebagai kolom dalam tabel Anda. Memberikan konteks untuk ukuran membantu agen menjawab pertanyaan tentang indikator performa utama (KPI) atau nilai terhitung lainnya.
Sebagai contoh, Anda dapat menentukan ukuran profit sebagai penghitungan penghasilan dikurangi biaya sebagai berikut:
- 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
Kunci golden_queries, yang berada dalam objek table, mengambil daftar objek golden_query. Kueri emas membantu agen memberikan respons yang lebih akurat dan relevan terhadap pertanyaan umum atau penting yang dapat Anda tentukan.
Misalnya, Anda dapat menentukan kueri utama untuk analisis umum data dalam tabel orders sebagai berikut:
- 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
Kunci golden_action_plans, yang berada dalam objek table, mengambil daftar objek golden_action_plan. Anda dapat menggunakan rencana tindakan terbaik untuk memberikan contoh kepada agen tentang cara menangani permintaan multi-langkah, seperti mengambil data lalu membuat visualisasi.
Sebagai contoh, Anda dapat menentukan rencana tindakan untuk menampilkan perincian pesanan menurut kelompok usia dan menyertakan detail tentang kueri SQL dan langkah-langkah terkait visualisasi:
- 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
Kunci relationships 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
Kamus glossaries 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
Kunci additional_descriptions mencantumkan petunjuk atau konteks umum tambahan yang tidak tercakup di bagian lain dalam petunjuk sistem. Dengan memberikan deskripsi tambahan, Anda dapat membantu agen lebih memahami konteks data dan kasus penggunaan Anda.
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: Petunjuk sistem di BigQuery
Contoh berikut menunjukkan contoh petunjuk sistem untuk agen analis penjualan fiktif:
- 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.'