建立資料代理程式

本文說明如何在 BigQuery 中建立、編輯、管理及刪除資料代理程式。

在 BigQuery 中，您可以與資料代理進行對話，以自然語言詢問有關 BigQuery 資料的問題。資料代理包含資料表的中繼資料，以及用例專屬的查詢處理指令，可定義回答使用者問題的最佳方式，問題內容與您選取的一組知識來源相關，例如資料表、檢視畫面或使用者定義函式 (UDF)。

事前準備

Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, Gemini Data Analytics, and Gemini for Google Cloud APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

必要的角色

如要使用資料代理程式，您必須具備下列任一對話式 Analytics API Identity and Access Management 角色：

在專案中建立、編輯、共用及刪除所有資料代理程式：專案的 Gemini Data Analytics 資料代理擁有者 (roles/geminidataanalytics.dataAgentOwner)。
在專案中建立、編輯、共用及刪除自己的資料代理：Gemini Data Analytics 資料代理建立者 (roles/geminidataanalytics.dataAgentCreator) 位於專案中。這個角色會自動授予您所建立資料代理的 Gemini Data Analytics 資料代理擁有者角色。
查看及編輯專案中的所有資料代理：專案層級的 Gemini Data Analytics 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)。
查看專案中的所有資料代理：Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)。

此外，您必須具備下列角色，才能建立或編輯資料代理程式：

Gemini Data Analytics 資料代理無狀態使用者 (roles/geminidataanalytics.dataAgentStatelessUser)。
資料代理程式做為知識來源的任何資料表，都必須具備 BigQuery 資料檢視者 (roles/bigquery.dataViewer) 權限。
專案的 Dataplex Catalog 檢視者 ( roles/datacatalog.catalogViewer)
如果資料表使用資料欄層級存取控管機制，請在適當的政策標記上選取「精細讀取者」圖示 roles/datacatalog.categoryFineGrainedReader。詳情請參閱「搭配欄層級存取權控管使用的角色」。
如果資料表使用資料列層級存取權控管，您必須擁有該資料表的資料列層級存取權政策。詳情請參閱「建立或更新資料列層級存取權政策」。
如果資料表使用資料遮蓋，請在適當的資料政策中，將 Masked Reader (roles/bigquerydatapolicy.maskedReader) 設為適當的資料政策。詳情請參閱「查詢遮蓋資料的角色」。

如要使用 BigQuery 資源 (例如查看資料表或執行查詢)，請參閱 BigQuery 角色。

最佳做法

使用對話式數據分析時，系統會自動執行查詢來回答問題。在下列情況下，您可能會產生預料之外的費用：

如果表格很大
如果查詢使用資料聯結
如果查詢會大量呼叫 AI 函式

為避免發生這個問題，請在選取知識來源時考慮大小，並在對話時考慮使用聯結。

產生深入分析資訊

您可以選擇在 Dataplex Universal Catalog 中產生資料洞察，以做為知識來源。

生成的洞察資訊會提供資料表的中繼資料，資料代理程式可使用這些資料生成問題回覆。

如果您未事先產生洞察資料，在建立資料代理程式時選取資料表做為知識來源，系統就會自動產生洞察資料。

使用範例資料代理程式

如果您不熟悉如何設定對話式數據分析的代理程式，可以選擇查看為每個Google Cloud 專案產生的預先定義範例代理程式。你可以與其對話，並查看參數瞭解建立方式，但無法修改。

如要查看範例代理程式，請按照下列步驟操作：

前往 Google Cloud 控制台的 BigQuery Agents 頁面。

前往「代理程式」頁面
選取「代理程式目錄」分頁標籤。
在「Google 的代理範例」部分下方，按一下代理範例資訊卡。

建立資料代理程式

下列各節說明如何建立資料代理程式。

建立代理程式後，您可以編輯其設定。

進行基本設定

前往 Google Cloud 控制台的 BigQuery Agents 頁面。

前往「代理程式」頁面
選取「代理程式目錄」分頁標籤。
按一下「新增代理程式」。「新增代理程式」頁面隨即開啟。
在「編輯器」部分的「代理程式名稱」欄位中，輸入資料代理程式的描述性名稱，例如 Q4 sales data 或 User activity logs。
在「代理程式說明」欄位中，輸入資料代理程式的說明。好的說明會解釋代理程式的功能、使用的資料，以及協助您判斷是否要與這個資料代理程式對話，例如 Ask questions about customer orders and revenue。
在「知識來源」部分中，按一下「新增來源」。「新增知識來源」頁面隨即開啟。
在「最近」部分，選取要用做知識來源的資料表、檢視區塊或 UDF。在Google Cloud 控制台中，UDF 會加上「fx」指標前置字串。
如要查看其他知識來源，請選取「顯示更多」。
選用：新增「最近」部分未列出的知識來源：
1. 在「搜尋」部分中，於「搜尋表格」欄位輸入來源名稱，然後按下 Enter 鍵。來源名稱不必完全相符。
2. 在「搜尋結果」部分中，選取一或多個來源。
按一下「Add」(新增)。系統會重新開啟新的代理程式頁面。

自訂資料表和欄位說明

如要提高資料代理程式的準確度，您可以選擇提供額外的表格中繼資料。只有資料代理程式會使用這項中繼資料，且不會影響來源資料表。

建立表格和欄位說明時，請遵循下列最佳做法：

請參考這些說明，瞭解資料代理程式如何解讀結構定義。如果代理商建議的說明正確無誤，你可以接受。
如果您設定這些說明後，資料代理程式仍無法瞭解結構定義，請手動調整說明，提供正確資訊。

請按照下列步驟設定表格和欄位說明：

在「知識來源」部分中，按一下表格的「自訂」連結。
建立資料表說明。您可以在「表格說明」欄位中輸入說明，或接受 Gemini 的建議。
在「欄位」部分，查看 Gemini 建議的欄位說明。
選取要接受的欄位說明，然後按一下「接受建議」。選取要拒絕的說明，然後按一下「拒絕建議」。
如要手動編輯任何欄位說明，請按一下欄位旁的「編輯」。「編輯欄位」窗格隨即開啟。
1. 在「Description」(說明) 欄位中輸入欄位說明。
2. 如要儲存欄位說明，請按一下「更新」。
如要儲存說明和欄位更新，請按一下「更新」。新的代理程式頁面會重新開啟。
針對需要自訂的每個表格重複執行這些步驟。

設定進階功能

設定選用的進階功能，例如代理商指令、已驗證的查詢 (舊稱「黃金查詢」) 和設定。

建立代理程式指令

服務專員應瞭解使用者問題的背景資訊，不必使用任何自訂指令。只有在需要變更代理程式行為或改善其他情境功能 (例如自訂表格和欄位中繼資料，或已驗證的查詢) 不支援的情境時，才需要為代理程式建立自訂指令。

在「Instructions」(操作說明) 部分，於「Agent instructions」(代理程式操作說明) 欄位中輸入資料代理程式的操作說明。資料代理程式會使用這些指令瞭解使用者問題的脈絡並提供答案，因此請盡可能清楚地撰寫指令。

如果服務專員無法提供令人滿意的答案，請加入描述或範例等結構化背景資訊。如果仍未獲得滿意的答案，請新增自訂指令，如以下表格中的範例所示。如需更多指令範例，請按一下「顯示範例」。

資訊類型	說明	範例
重要欄位	分析作業中最重要的欄位。	「這個資料表最重要的欄位為客戶 ID、產品 ID 和訂單日期。」
篩選及分組	代理在篩選及分類資料時應使用的欄位。	「如果問題與時間軸或『一段時間內』有關，請一律使用 order_created_date 欄。」「如果有人說『依產品』，請依 product_category 資料欄分組。」
預設篩選	預設要篩選的欄位。	「除非另有說明，否則請一律依 order_status = 'Complete' 篩選資料。」
同義詞和企業字詞	關鍵欄位的替代字詞。	「如果有人詢問『收益』或『銷售』，請使用 total_sale_amount 欄。」「我們認為 purchase_count 大於 5 的顧客是『忠實』顧客。」
排除欄位	資料代理應避免使用的欄位。	「切勿使用下列欄位：衍生交易日期、衍生城市。」
彙整關係	兩個以上的資料表如何彼此關聯，以及用於彙整資料表的資料欄。代理程式必須對資料欄組合使用標準 SQL JOIN，才能合併資料。請參閱「範例」欄。	顧客活動 `order_items.user_id` = `users.id` (將銷售量與顧客連結) `events.user_id` = `users.id` (將網站活動連結至已登入的顧客)

建立通過驗證的查詢

代理程式會透過兩種方式使用已驗證的查詢：

如果代理程式可以使用經過驗證的查詢來回答您提出的問題，為確保答案可信，代理程式會完全按照查詢內容執行。
如果服務專員無法使用已驗證的查詢來回答問題，仍會將查詢做為參考，瞭解資料和查詢資料的最佳做法。

您可以從系統生成的清單中選取已驗證的查詢，也可以自行建立查詢。

如要為資料代理程式建立已驗證的查詢 (舊稱黃金查詢)，請按照下列步驟操作：

選取一或多個 Gemini 建議的已驗證查詢：
1. 在「已驗證的查詢」部分，按一下「查看建議」。「查看建議的已驗證查詢」頁面隨即開啟。
2. 查看建議的已驗證查詢。請選取所有適用於您用途的選項。
3. 按一下「Add」(新增)。系統會重新開啟新的代理程式頁面。
如要建立自己的已驗證查詢，請按一下「新增查詢」。「新增已驗證的查詢」頁面隨即開啟。
1. 在「問題」欄位中，輸入經過驗證的查詢會回答的使用者問題。
2. 按一下「生成 SQL」，讓 Gemini 生成與您指定使用者問題相符的已驗證查詢。
3. 視需要修改通過驗證的查詢。
4. 點選「執行」，確認查詢傳回的結果符合預期。
5. 按一下「Add」(新增)。系統會重新開啟新的代理程式頁面。
視需要重複上述步驟，建立其他已驗證的查詢。

調整設定

在「設定」部分，您可以設定下列選用設定：

建立標籤，協助您整理Google Cloud 資源。標籤是鍵/值組合，可用來將相關物件分組，或與其他 Google Cloud 資源組合。
1. 在「設定」部分，按一下「管理標籤」。
2. 按一下「新增標籤」。
3. 在「key」和「value」欄位中，輸入標籤的鍵/值組合。
4. 如要新增其他標籤，請再次按一下「新增標籤」。
5. 如要刪除標籤，請按一下「刪除」。
6. 完成後，按一下「新增」。系統會重新開啟新的代理程式頁面。
選用：為資料代理程式處理的查詢設定大小限制。在「設定」部分中，於「帳單計算的位元組數上限」欄位輸入值。您必須將這項限制設為 10485760 以上，否則會收到下列錯誤訊息：

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

如未指定值，maximum bytes billed 預設為專案的每日查詢用量配額。除非您指定自訂配額，否則每日用量配額沒有上限。

請前往下一節，將代理程式設為草稿模式或發布代理程式。

預覽及發布代理程式

在「預覽」部分，於「提出問題」欄位中輸入範例使用者問題，然後按 Enter 鍵。如要確認資料代理程式是否傳回預期資料，請查看代理程式的回應。如果回覆內容不符合預期，請在「編輯器」部分變更設定，調整資料代理程式設定，直到獲得滿意的回覆為止。您可以繼續測試及修改代理，以改善代理的結果。
按一下 [儲存]。
如要將資料代理程式設為草稿模式，以便稍後重新編輯，請按一下「Go back」(返回)，返回「Agent Catalog」(代理程式目錄) 頁面。由於代理程式目前處於草稿模式，因此會顯示在「代理程式目錄」分頁的「我的草稿代理程式」部分。

如要發布代理程式，請留在代理程式建立頁面，然後繼續執行下一個步驟。
按一下「發布」，發布資料代理程式，即可在專案中使用。您可以使用 BigQuery Studio 與資料代理建立對話，如果訂閱了 Looker Studio，也可以使用 Looker Studio Pro。您也可以使用 Conversational Analytics API，建構自己的介面與資料代理對話。
選用：在「您的代理已發布」對話方塊中，按一下「分享」，即可與其他使用者共用資料代理。
1. 在「共用權限」窗格中，按一下「新增主體」。
2. 在「New principals」(新增主體) 欄位中，輸入一或多個主體。
3. 按一下「選取角色」清單。
4. 在「Role」(角色) 清單中，選取下列其中一個角色：
  - Gemini Data Analytics 資料代理使用者 (roles/geminidataanalytics.dataAgentUser)：授予與資料代理對話的權限。
  - Gemini Data Analytics 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)：可授予編輯資料代理的權限。
  - Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)：授予檢視資料代理的權限。
按一下 [儲存]。
如要返回新代理程式頁面，請按一下「關閉」。儲存或發布虛擬服務專員後，您會立即在虛擬服務專員目錄中看到該專員。

管理資料代理程式

您可以在「代理程式目錄」分頁中找到現有代理程式，該分頁包含三個部分：

我的代理：列出你建立及發布的所有代理。您可以修改已發布的代理，並與他人共用。
代理草稿：尚未發布的代理。您無法共用草稿代理程式。
組織中其他成員分享的代理：其他使用者建立並與您共用的代理。如果其他人授予您權限，您就可以編輯這些共用代理程式。

編輯資料代理程式

如要編輯資料代理人，請按照下列步驟操作：

前往 BigQuery Agents 頁面。

前往「代理程式」頁面
選取「代理程式目錄」分頁標籤。
找出要修改的資料代理人代理人資訊卡。
如要在代理程式編輯器中開啟資料代理程式，請依序點選「開啟動作」代理程式資訊卡上的「編輯」。
視需要編輯資料代理程式的設定。
如要儲存變更但不發布，請按一下「儲存」。
如要發布變更，請按一下「發布」。在「共用」對話方塊中，您可以與他人共用代理程式，或按一下「取消」。
如要返回「代理」窗格，請按一下「返回」。

如要分享已發布的資料代理程式，請按照下列步驟操作。您無法共用草稿代理程式。

前往 BigQuery Agents 頁面。

前往「代理程式」頁面
選取「代理程式目錄」分頁標籤。
找出要修改的資料代理人代理人資訊卡。
如要在代理程式編輯器中開啟資料代理程式，請依序點選「開啟動作」代理程式資訊卡上的「編輯」。
如要與其他使用者共用資料代理人，請按一下「共用」。
在「共用權限」窗格中，按一下「新增主體」。
在「New principals」(新增主體) 欄位中，輸入一或多個主體。
按一下「選取角色」清單。
在「Role」(角色) 清單中，選取下列其中一個角色：
- Gemini Data Analytics 資料代理使用者 (roles/geminidataanalytics.dataAgentUser)：可與資料代理對話。
- Gemini Data Analytics 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)：可編輯資料代理。
- Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)：可檢視資料代理。
按一下 [儲存]。
如要返回代理程式編輯頁面，請按一下「關閉」。
如要返回「代理程式」窗格，請按一下「返回」。

刪除資料代理程式

前往 BigQuery Agents 頁面。

前往「代理程式」頁面
選取「代理程式目錄」分頁標籤。
在「代理程式目錄」分頁的「我的代理程式」或「草稿代理程式」部分，找到要刪除資料代理程式的代理程式資訊卡。
依序點選「開啟動作」「刪除」。
在「Delete agent?」(刪除代理程式？) 對話方塊中，按一下「Delete」(刪除)。

位置

對話式分析功能適用於全球，無法選擇要使用的區域。

後續步驟

進一步瞭解 BigQuery 中的對話式數據分析。
進一步瞭解對話式數據分析 API。
透過對話分析資料。
進一步瞭解 Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer) 角色如何授予檢視資料代理的權限。

建立資料代理程式

事前準備

必要的角色

最佳做法

產生深入分析資訊

使用範例資料代理程式

建立資料代理程式

進行基本設定

自訂資料表和欄位說明

設定進階功能

建立代理程式指令

建立通過驗證的查詢

調整設定

預覽及發布代理程式

管理資料代理程式

編輯資料代理程式

共用資料代理

刪除資料代理程式

位置

後續步驟