使用撰寫的背景資訊引導代理程式行為

本頁面說明如何編寫有效的提示，供 Conversational Analytics API 資料代理程式使用。這些提示是您使用 system_instruction 參數定義為字串的撰寫內容。結構良好的系統指令可提高 API 回覆的準確度和關聯性。

什麼是系統指示？

系統指令是開發人員定義的指引，可提供給資料代理程式，藉此調整代理程式的行為，並改善 API 的回應。系統指令是 API 用來回答問題的脈絡資訊之一。這個脈絡也包括已連結的資料來源 (BigQuery 資料表、Looker 探索、Looker Studio 資料來源) 和對話記錄 (適用於多輪對話)。

透過系統指令提供清楚的結構化指引，有助於提升服務專員解讀使用者問題的能力，並生成實用且準確的回覆。如果您要連結至 BigQuery 資料表等資料，系統指令定義完善就特別實用，因為這類資料可能沒有預先定義的語意層 (如 Looker 探索)。

舉例來說，您可以使用系統指令，為代理程式提供下列類型的指引：

  • 特定商家的邏輯：將「忠實」顧客定義為在特定時間範圍內購買超過五次的顧客。
  • 回覆格式：將資料代理程式的所有回覆總結成 20 字以內，節省使用者時間。
  • 資料呈現：所有數字的格式都必須符合公司的樣式指南。

提供系統指示

您可以使用 system_instruction 參數，以 YAML 格式的字串向 Conversational Analytics API 提供系統指令。雖然 system_instruction 參數為選用，但建議提供結構良好的系統指令，以獲得準確且相關的回覆。

您可以在初始設定期間，於程式碼中定義 YAML 格式的字串，如「設定初始設定和驗證」(HTTP) 或「指定帳單專案和系統指令」(Python SDK) 所示。然後在下列 API 呼叫中加入 system_instruction 參數：

系統指令的 YAML 範本

下列範本顯示提供給 system_instruction 參數的字串建議 YAML 結構，包括可用鍵和預期資料類型。如需填入值的系統指令範例，請參閱「範例：系統指令」。

您可以使用下列 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.
        - 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.

系統指令的主要元件

以下各節說明系統指令的主要元件，以及如何使用這些元件提升代理程式回覆的品質。

使用 system_instruction 定義代理的角色和人物角色

使用 system_instruction 鍵定義代理程式的角色和人物角色。這項初始指令會為 API 回覆設定語氣和風格，並協助代理程式瞭解核心目的。

下列 YAML 程式碼區塊顯示 system_instrucction 鍵的基本結構：

- system_instruction: str

舉例來說，您可以為虛構的電子商務商店定義代理程式，如下所示：

- 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 程式碼區塊顯示 tables 鍵的基本結構：

- tables:
    - table:
      - 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: # A list of the fields in the table.
      - measures: # A list of the measures in the table.
      - golden_queries: # A list of golden queries for the table.
      - golden_action_plans: # A list of golden action plans for the 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 說明常用欄位

fields 鍵會巢狀內嵌在 table 物件中，並採用欄位物件清單來描述個別資料欄。並非所有欄位都需要額外背景資訊，但如果提供常用欄位的詳細資料，有助於提升服務專員的成效。

下列 YAML 程式碼區塊顯示 fields 鍵的基本結構：

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

舉例來說，下列 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 定義業務指標

measures 鍵 (位於 table 物件中) 會定義自訂商家指標或計算，這些指標或計算不會直接顯示為表格中的資料欄。提供指標的背景資訊，有助於代理商回答有關主要成效指標 (KPI) 或其他計算值的問題。

下列 YAML 程式碼區塊顯示 measures 鍵的基本結構：

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

舉例來說，您可以將 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 提高準確度

golden_queries 鍵 (巢狀結構位於 table 物件中) 會採用 golden_query 物件清單。服務專員可根據黃金查詢，針對常見或重要問題提供更準確且相關的回覆。為每個黃金查詢提供自然語言查詢和對應的 SQL 查詢，引導代理程式提供更高品質且更一致的結果。

下列 YAML 程式碼區塊顯示 golden_queries 鍵的基本結構：

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

舉例來說，您可以為 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 規劃多步驟工作

golden_action_plans 鍵 (巢狀結構位於 table 物件中) 會採用 golden_action_plan 物件清單。你可以使用黃金行動計畫，向代理提供如何處理多步驟要求的範例，例如擷取資料，然後建立視覺化內容。

下列 YAML 程式碼區塊顯示 golden_action_plans 鍵的基本結構：

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

舉例來說，您可以定義動作計畫，依年齡層顯示訂單明細，並納入 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 鍵包含資料表之間的彙整關係清單。定義聯結關係後，虛擬服務專員就能瞭解如何聯結多個資料表的資料，以便回答問題。

下列 YAML 程式碼區塊顯示 relationships 鍵的基本結構：

- relationships: # A list of join relationships between tables.
    - relationship: # Details for a single join relationship.
        - name: str # A unique name for this join relationship.
        - description: str # A description of the relationship.
        - relationship_type: str # The join relationship type (e.g., "one-to-one", "one-to-many", "many-to-one", "many-to-many").
        - join_type: str # The join type (e.g., "inner", "outer", "left", "right", "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.

舉例來說，您可以定義 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重要清單定義：列出與資料和用途相關的商業用語、術語和縮寫。提供詞彙定義後，虛擬服務專員就能準確解讀並回答使用特定業務用語的問題。

下列 YAML 程式碼區塊顯示 glossaries 鍵的基本結構：

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

舉例來說，您可以根據特定業務情境定義常見的業務狀態和「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 鍵會列出系統指令中其他位置未涵蓋的任何額外一般指令或背景資訊。提供額外說明有助於服務專員進一步瞭解資料和用途的背景資訊。

下列 YAML 程式碼區塊顯示 additional_descriptions 鍵的基本結構：

- additional_descriptions: # A list of any other general instructions or content.
    - text: str # Any additional general instructions or context not covered elsewhere.

舉例來說，您可以使用 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.'

範例：系統指示

以下範例顯示虛構銷售分析師代理程式的系統指令範例。

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