建立資料代理程式

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

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

事前準備

1. 確認 Google Cloud 專案已啟用計費功能。

2. 如果尚未啟用 BigQuery、Gemini 資料分析、Gemini for Google Cloud和 Knowledge Catalog API，請啟用這些 API。

   啟用 API 所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

必要的角色

如要使用資料代理，您必須具備符合用途的身分與存取權管理 (IAM) 權限。下列各節會根據您是否要建立及發布代理、在 Gemini Enterprise 佈建代理，或在各種介面探索及使用代理，列出所需角色。詳情請參閱「Conversational Analytics API IAM 角色」。

• 建立、編輯、發布、共用及刪除代理程式：
  • 如要在專案中建立資料代理，請在專案中啟用 Gemini Data Analytics 資料代理建立者 (roles/geminidataanalytics.dataAgentCreator)。這個角色會自動授予您所建立資料代理的 Gemini 資料分析 資料代理擁有者角色。
  • 如要編輯、共用或刪除資料代理，請在代理或專案中，取得 Gemini Data Analytics 資料代理擁有者 (roles/geminidataanalytics.dataAgentOwner) 角色。
  • 如要編輯專案中的資料代理：專案的 Gemini Data Analytics 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)。
  • 如要在專案中查看資料代理，您必須具備專案的 Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer) 角色。
• 在 Gemini Enterprise 中佈建代理：
  • 如要讓 Gemini Enterprise 的使用者存取已發布的代理，您必須具備註冊及管理自訂代理的權限，並在 Gemini Enterprise 管理控制台中設定Agent Gateway。
• 探索及使用代理：
  • 與資料代理對話：Gemini 資料分析資料代理使用者 (roles/geminidataanalytics.dataAgentUser)。
  • 如要查看專案中的所有資料代理：Gemini 資料分析資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)。
  • 如要在數據分析中與 Gemini 輔助的對話介面互動，請使用 BigQuery Studio 使用者 (roles/bigquery.studioUser) 或 Gemini for Google Cloud 使用者 (roles/cloudaicompanion.user) 角色，這兩個角色都提供 cloudaicompanion.topics.create 權限。請在專案層級授予這些角色。使用者也必須具備「數據分析資產檢視者」角色 (roles/datastudio.viewer)。
• 將知識來源新增至代理：
  • 專案的 Data Catalog 檢視者 (roles/datacatalog.viewer)。

如要進行對話，請參閱對話所需的角色。

代理會代表你執行操作，並使用你的權限。代理只能存取您有權存取的資料和資源。

最佳做法

對話式數據分析會自動代您執行查詢，回答您的問題。請考量下列可能導致查詢費用增加的因素：

• 資料表過大
• 在查詢中使用資料彙整
• 在查詢中頻繁呼叫 AI 函式

生成深入分析

您也可以在 Knowledge Catalog 中，為要用做知識來源的任何資料表生成資料洞察。

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

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

使用樣本資料代理

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

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

1. 前往 Google Cloud 控制台的「BigQuery Agents」頁面。

   前往「Agents」

2. 選取「代理程式目錄」分頁標籤。

3. 在「Google 的代理範例」部分下方，點選範例代理資訊卡。

建立資料代理

以下各節說明如何建立資料代理。

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

注意： 如果您正在與資料來源對話，也可以從該對話建立代理。

初始步驟

1. 前往 Google Cloud 控制台的「BigQuery Agents」頁面。

   前往「Agents」

2. 選取「代理程式目錄」分頁標籤。

3. 按一下「New agent」(新增代理)。「New agent」(新增代理程式) 頁面隨即開啟。

4. 在「編輯器」部分的「代理程式名稱」欄位，輸入資料代理程式的描述性名稱，例如 Q4 sales data 或 User activity logs。

5. 在「Agent description」(代理程式說明) 欄位中，輸入資料代理程式的說明。好的說明會解釋代理的功能、使用的資料，並協助您判斷何時適合與這個資料代理對話，例如Ask questions about customer orders and revenue。

6. 在「知識來源」部分，點選「新增來源」。「新增知識來源」頁面隨即開啟。

7. 在「Recents」(近期) 部分，選取要用做知識來源的資料表、檢視表、圖表或 UDF。在 Google Cloud 控制台中，UDF 的前置字元為「fx」指標。

8. 如要查看其他知識來源，請選取 「Show more」(顯示更多)。

9. 選用：新增「Recents」(近期) 專區未列出的知識來源：

   1. 在「Search」(搜尋) 區段的「Search for tables」(搜尋資料表) 欄位中輸入來源名稱，然後按下 Enter 鍵。來源名稱不一定要完全相同。

   2. 在「搜尋結果」部分，選取一或多個來源。

10. 按一下「Add」(新增)。新代理頁面會重新開啟。

自訂資料表和欄位說明

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

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

• 請參考這些說明，瞭解資料代理如何解讀結構定義。如果代理建議的說明正確，您可以接受。

• 如果設定說明後，資料代理仍無法理解結構定義，請手動調整說明，提供正確資訊。

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

1. 在「知識來源」部分中，按一下表格的「自訂」連結。

2. 建立資料表說明。您可以在「Table Description」(資料表說明) 欄位中輸入說明，或接受 Gemini 的建議。

3. 在「欄位」部分，查看 Gemini 建議的欄位說明。

4. 選取要接受的欄位說明，然後按一下「接受建議」。選取要拒絕的說明，然後按一下「拒絕建議」。

5. 如要手動編輯任何欄位說明，請按一下欄位旁邊的「編輯」。「編輯欄位」窗格隨即開啟。

   1. 在「Description」(說明) 欄位中輸入欄位說明。
   2. 如要儲存欄位說明，請按一下「更新」。

6. 如要儲存說明和欄位更新，請按一下「更新」。新的代理頁面會重新開啟。

7. 針對每個需要自訂的表格重複上述步驟。

注意： 如果 Google Cloud 控制台未反映您對說明的變更，可以使用 list 方法驗證，或使用 patch 方法更新說明。

建立代理指令

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

在「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 (將網站活動連結至已登入的顧客)

建立通過驗證的查詢

服務專員可透過兩種方式使用已驗證的查詢：

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

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

注意： 如要建立參數化已驗證查詢，請參閱「建立參數化已驗證查詢」。

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

1. 選取一或多個 Gemini 建議的已驗證查詢：

   1. 在「已驗證的查詢」部分，按一下「查看建議」。「Review suggested verified queries」(查看建議的已驗證查詢) 頁面隨即開啟。
   2. 查看建議的已驗證查詢。請選取所有適用於您用途的選項。
   3. 按一下「Add」(新增)。新代理頁面會重新開啟。

2. 如要建立自己的已驗證查詢，請按一下「新增查詢」。「新增已驗證的查詢」頁面隨即開啟。

   1. 在「Question」(問題) 欄位中，輸入已驗證查詢回答的使用者問題。
   2. 點選「生成 SQL」，讓 Gemini 生成與您指定使用者問題相符的已驗證查詢。
   3. 視需要修改通過驗證的查詢。
   4. 點選「Run」(執行)，確認查詢傳回預期結果。
   5. 按一下「Add」(新增)。系統會重新開啟新的代理程式頁面。

3. 視需要重複上述步驟，建立其他已驗證的查詢。

建立參數化驗證查詢

參數化驗證查詢會從使用者問題中擷取值，提供給對話式數據分析代理，並提供量身打造的結果。

分析師和建構工具可以建立可重複使用的 SQL 範本，其中包含這些值的預留位置。範本會在執行階段動態替換參數，因此能回答更多使用者問題，比一般驗證查詢更靈活。

當使用者提出的問題符合範本模式時，對話式數據分析代理會從問題中擷取參數值，例如產品名稱、區域和日期。然後將這些值插入參數化查詢。查詢範本中相符的回覆會顯示為「已驗證」。

參數化已驗證查詢可大幅提升已驗證查詢的效力和彈性。確保各種輸入內容都能獲得一致且可信的答案，並減少需要維護的個別查詢數量。

運作方式

資料分析師等專家會使用範本問題定義已驗證的查詢，例如「@product在 @region的銷售額是多少？」。接著，專家會使用 SQL 參數建立或修改已驗證的查詢，如下例所示：

SELECT * FROM sales WHERE region = @region AND product = @product

儲存已驗證的查詢後，使用者可以自然語言向對話式數據分析代理程式提問，例如「北美地區的筆電銷售額是多少？」

為回答使用者的問題，代理會執行下列步驟：

1. 將問題與參數化驗證查詢相關聯的模式進行比對。代理程式會使用自然語言理解 (NLU)，從使用者的問題中找出並擷取 @region (北美) 和 @product (筆電) 的值。
2. 將擷取的值代入 SQL 範本中的 @region 和 @product 預留位置。
3. 執行完整的 SQL 查詢，例如 SELECT * FROM sales WHERE region = 'North America' AND product = 'Laptops'。
4. 將結果傳回給使用者。比對結果一律會標示為「已驗證」。

建立有效參數化查詢的訣竅

• 使用清楚的參數名稱。參數應使用描述性名稱，例如 @start_date，而非 @d1。
• 建立詳細的參數說明。對話式數據分析的大型語言模型 (LLM) 會使用參數說明，從使用者問題中找出參數及其值。舉例來說，num_enrollments 是有效的參數名稱，但 number of student enrollments from ages 5-14 是參數說明，可提供更多查詢相關背景資訊。
• 確保資料型別一致。確保 SQL 查詢預期的資料類型，與可能從使用者問題中擷取的資料類型相符。
• 提供明確的範圍。針對查詢結構複雜或邏輯不直觀的常見重要問題模式，建立範本。這樣 LLM 才能傳回最佳結果。
• 全面測試。請測試各種自然語言詞組，確保系統正確擷取參數。

建立參數化的已驗證查詢

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

建立或修改查詢前，請先草擬查詢，並考量自然語言模式和您的問題。舉例來說，如果詢問「美國東部倉庫的有機香蕉總庫存量是多少？」，您可以將問題改寫為參數化驗證查詢「@region 倉庫的 @product 總庫存量是多少？」。代理程式會將這個問題轉換為 SQL 查詢，您可以使用預設值更新查詢。

如要為資料代理建立參數化驗證查詢，您可以在建立新代理時建立新查詢，也可以為新代理或現有代理編輯現有的驗證查詢。

下列操作說明會使用經過驗證的範例查詢，設定參數。

選取 Gemini 建議的現有已驗證查詢

1. 在新的或現有代理的「Verified Queries」(已驗證查詢) 部分，按一下「Review suggestions」(查看建議)。「查看建議的已驗證查詢」頁面隨即開啟。
2. 選取建議驗證查詢旁的核取方塊。
3. 在查詢視窗中，按一下「顯示更多」，展開查詢說明。
4. 如要開啟現有查詢，請按一下「編輯」。
5. 如要完成查詢設定，請參閱「設定已驗證查詢的參數」。

建立代理程式，然後建立已驗證的查詢

1. 請參閱「初始步驟」， 並繼續完成其餘設定步驟，以驗證查詢。
2. 在 Google Cloud 控制台中，點選新代理程式「已驗證的查詢」部分中的「新增查詢」。「新增通過驗證的查詢」頁面隨即開啟。
3. 如要完成查詢設定，請參閱「設定已驗證查詢的參數」。

設定已驗證查詢的參數

1. 在「Question」(問題) 欄位中，輸入已驗證查詢回答的使用者問題。
2. 如要指定參數，請使用 @ 符號，後接參數名稱。這個語法會識別預留位置，從使用者問題中擷取值。使用自然語言問題，說明參數在使用者問題中的用途。例如：「@region 倉庫中 @product 的總庫存量是多少？」

3. 按一下「Generate SQL」(生成 SQL 查詢)。SQL 如下所示：

      SELECT
          SUM(stock) AS total_stock
      FROM
          inventory
      WHERE
          product_id = @product
          AND region = @region;
   

4. 如要為查詢中的預留位置新增預設值，請依序點選「Manage query parameters」(管理查詢參數) 和「Add query parameter」(新增查詢參數)。

5. 第一個參數會顯示四個欄位：「Name」、「Type」、「Value」和「Description」。

   • 在「Name」(名稱) 部分，複製問題中的 @product 並貼到這個欄位。
   • 在「Type」(類型) 部分選取「STRING」(字串)。
   • 在「值」部分輸入 organic bananas。
   • 在「Description」(說明) 部分，盡可能輸入具體說明。例如存放在區域倉庫的產品。

6. 針對第二個參數，按一下「新增查詢參數」。

   • 在「Name」中，複製問題中的 @region 並貼到這個欄位。
   • 在「Type」(類型) 部分選取「STRING」(字串)。
   • 在「Value」部分輸入 US-EAST。
   • 在「說明」中，盡可能輸入具體的說明，例如 a regional warehouse where products are located.

7. 填寫兩個參數的欄位後，按一下「儲存」。

測試參數化已驗證查詢

1. 點選「執行」，確認查詢傳回的結果符合預期。
2. 如要在後續畫面中測試使用者查詢，請複製整個問題欄位。
3. 按一下「儲存」，離開「新增查詢」畫面，然後返回代理程式「編輯」頁面。
4. 在代理程式的「Edit」(編輯) 頁面，將先前複製的問題欄位貼到「Preview」(預覽) 視窗。
   1. 將 @product 變數替換為 organic bananas。
   2. 將 @region 變數替換為 US-EAST。
5. 按下 Enter 鍵，請查看結果，在本例中，有效答案是美國東部地區的香蕉總庫存量，例如 1,000。
6. 如要建立或編輯其他已驗證查詢，請視需要重複這些步驟。

儲存查詢後，使用者可以詢問「我們是否知道美國東部倉庫的有機香蕉總庫存量？」對話式數據分析接著會執行下列操作：

1. 將這個問題與模式相符。
2. 從問題中擷取 @product 參數 (@product =「organic bananas」) 和 @region 參數 (@region =「US-EAST」)。
3. 執行查詢：SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST';
4. 傳回計算出的 total_stock。

建立或查看詞彙表字詞

您可以建立代理專屬的 BigQuery 自訂組織詞彙字詞，或查看從 Knowledge Catalog 匯入的組織詞彙字詞，這些字詞適用於您為代理選取的知識來源。

• 由於 Knowledge Catalog 中的組織詞彙會全域套用至 BigQuery 資源，因此如果您使用 Knowledge Catalog，請在 Knowledge Catalog 中建立及管理組織詞彙，而非個別代理程式。
• 如要修改從 Knowledge Catalog 匯入的組織詞彙，請在 Knowledge Catalog 中編輯，然後返回 BigQuery 查看。
• BigQuery 自訂詞彙表字詞會保留在 BigQuery 中。不會顯示在 Knowledge Catalog 中。
• 如果未使用 Knowledge Catalog，可以為特定代理建立 BigQuery 自訂詞彙表字詞。

請按照下列步驟，為代理建立自訂詞彙：

1. 在代理編輯器頁面的「Glossary」(詞彙表) 部分，按一下「Add term」(新增字詞)。
2. 在「Custom terms」(自訂字詞) 區段中，您可以編輯或刪除任何現有的自訂字詞。
3. 如要建立一或多個新字詞，請按一下「建立字詞」。
   1. 輸入「Term」(字詞)、「Definition」(定義)，以及一或多個「Synonyms」(同義詞)，並以半形逗號分隔。
   2. 按一下「新增」，建立字詞。
   3. 如要刪除新字詞，請按一下「刪除」。
4. 如要建立更多自訂字詞，請重複執行這些步驟。

請按照下列步驟，查看從 Knowledge Catalog 匯入的組織詞彙：

1. 在代理程式「編輯器」頁面的「字彙表」部分，按一下「新增字詞」。
2. 前往「Imported from Dataplex」(從 Dataplex 匯入) 網頁區塊。
3. 如要在 Knowledge Catalog 修改匯入的字詞，請按一下「Go to Dataplex glossaries」(前往 Dataplex 詞彙表)。
4. 在 Knowledge Catalog 修改字詞後，您可以返回代理的「Editor」(編輯器) 頁面查看修改後的字詞。

調整設定

在「Settings」(設定) 部分，您可以進行下列選用設定：

1. 在「Model」(模型) 部分，選擇使用者與代理對話時可用的模型類型。預先發布版和正式發布版模型預設皆可使用。處於預先發布版階段的模型可能會使用全域端點。

2. 建立標籤，協助您整理Google Cloud 資源。標籤是鍵/值組合，可用來將相關物件分組，或與其他 Google Cloud 資源組合。

   1. 在「設定」部分，按一下「管理標籤」。
   2. 按一下「新增標籤」。
   3. 在「key」(鍵) 和「value」(值) 欄位中，輸入標籤的鍵/值組合。
   4. 如要新增更多標籤，請再次按一下「新增標籤」。
   5. 如要刪除標籤，請按一下「刪除」。
   6. 完成後，按一下「新增」。新代理頁面會重新開啟。

3. 為資料代理處理的查詢設定大小限制。在「Settings」(設定) 區段的「Maximum bytes billed」(計費位元組數上限) 欄位中輸入值。您必須將這項限制設為 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 會預設為專案的每日查詢用量配額。除非您指定自訂配額，否則每日用量配額沒有限制。

請繼續閱讀下一節，瞭解如何將代理程式設為草稿模式或發布代理程式。

預覽及發布代理程式

1. 在「Preview」(預覽) 部分的「Ask a question」(提出問題) 欄位中，輸入使用者問題範例，然後按下 Enter 鍵。如要確認資料代理是否傳回預期資料，請查看代理的回覆。如果回覆不符合預期，請在「編輯器」部分變更設定，調整資料代理程式設定，直到獲得滿意的回覆為止。您可以繼續測試及修改代理，以改善代理的結果。

2. 按一下 [儲存]。

3. 如要將資料代理程式設為草稿模式，以便稍後重新編輯，請按一下「返回」，返回「代理程式目錄」頁面。由於代理現在處於草稿模式，因此會顯示在「代理目錄」分頁的「我的草稿代理」部分。

   如要發布代理，請留在代理建立頁面，並繼續執行下一個步驟。

4. 按一下「Publish」(發布)，開啟「Publishing channels」(發布管道) 窗格，然後發布資料代理，以便在專案中使用。

5. 選用：在「Your agent has been published」(代理已發布) 對話方塊中，按一下「Share」(共用)，與其他使用者共用資料代理。

   1. 在「Share permissions」(共用權限) 窗格中，按一下「Add principal」(新增主體)。

   2. 在「New principals」(新增主體) 欄位中，輸入一或多個主體。

   3. 按一下「Select a role」(選取角色) 清單。

   4. 在「Role」(角色) 清單中，選取下列任一角色：

      • Gemini 資料分析資料代理使用者 (roles/geminidataanalytics.dataAgentUser)：授予與資料代理對話的權限。
      • Gemini Data Analytics 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)：可授予編輯資料代理的權限。
      • Gemini 資料分析資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)：可查看資料代理。

6. 按一下 [儲存]。

7. 如要返回新代理頁面，請按一下「Close」(關閉)。儲存或發布代理後，代理會立即顯示在代理目錄中。

您可以使用 BigQuery Studio 或數據分析與資料代理對話。您也可以使用 Conversational Analytics API，建構自己的介面與資料代理對話。如要瞭解如何發布至數據分析，請參閱「在數據分析中發布資料代理」。如要瞭解如何發布至 Gemini Enterprise，請參閱「在 Gemini Enterprise 發布資料代理」。

管理資料代理程式

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

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

編輯資料代理

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

1. 前往 BigQuery 的「Agents」(代理程式) 頁面。

   前往「Agents」

2. 選取「代理程式目錄」分頁標籤。

3. 找出要修改的資料代理程式資訊卡。

4. 如要在代理編輯器中開啟資料代理，請依序點選 「Open actions」(開啟動作) > 代理資訊卡上的「Edit」(編輯)。

5. 視需要編輯資料代理程式的設定。

6. 如要儲存變更但不發布，請按一下「儲存」。

7. 如要發布變更，請按一下「發布」。在「Share」對話方塊中，您可以與他人共用代理，或按一下「Cancel」。

8. 如要返回「代理」窗格，請按一下「返回」。

   

共用資料代理

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

1. 前往 BigQuery Agents 頁面。

   前往「Agents」

2. 選取「Agent Catalog」分頁標籤。

3. 找出要修改的資料代理程式資訊卡。

4. 如要在代理程式編輯器中開啟資料代理程式，請按一下 「開啟動作」> 代理程式資訊卡上的「編輯」。

5. 如要與其他使用者共用資料代理，請按一下「共用」。

6. 在「Share permissions」(共用權限) 窗格中，按一下「Add principal」(新增主體)。

7. 在「New principals」(新增主體) 欄位中，輸入一或多個主體。

8. 按一下「Select a role」(選取角色) 清單。

9. 在「Role」(角色) 清單中，選取下列其中一個角色：

   • Gemini 資料分析資料代理使用者 (roles/geminidataanalytics.dataAgentUser)：可與資料代理對話。
   • Gemini 資料分析資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)：可編輯資料代理。
   • Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)：可查看資料代理。

10. 按一下 [儲存]。

11. 如要返回代理編輯頁面，請按一下「Close」(關閉)。

12. 如要返回「代理」窗格，請按一下 「返回」。

    

刪除資料代理

1. 前往 BigQuery 的「Agents」(代理程式) 頁面。

   前往「Agents」

2. 選取「Agent Catalog」分頁標籤。

3. 在「代理程式目錄」分頁的「我的代理程式」或「我的草稿代理程式」部分，找到要刪除的資料代理程式資訊卡。

4. 依序點選「開啟動作」>「刪除」。

5. 在「Delete agent?」對話方塊中，點選「Delete」。

在數據分析中發布資料代理

發布代理並分享給數據分析使用者後，代理會自動顯示在數據分析的「與資料對話」頁面，供使用者對話。

建立代理並發布至 Data Studio

資料分析師可以按照下列步驟，建立、編輯代理並發布至數據分析：

1. 在 BigQuery 中建立或編輯資料代理程式。
2. 發布代理程式。發布代理時，請選取「數據分析」做為發布選項。
3. 按照操作說明共用代理，並將適當的身分與存取權管理角色授予數據分析使用者。

與數據分析使用者分享代理

您可以複製連結，直接與數據分析工具使用者共用代理程式，對方點選連結後，即可在數據分析工具中與代理程式展開對話。您也可以傳送電子郵件，通知使用者他們有權存取代理程式。

如要分享專屬的客服專員連結，請按照下列步驟複製：

• 在代理程式目錄中，依序選取 「開啟動作」>「複製連結」>「數據分析」。
• 在代理程式詳細資料檢視畫面中，依序選取 「複製代理程式連結」>「數據分析」。
• 在「分享」溢位選單中，選取「複製數據分析工具中代理的連結」。
• 按一下「共用權限」面板中的「儲存」後，選取「複製連結」。

如要傳送電子郵件通知，告知收件者他們有權存取代理程式，請在「分享權限」面板中選取「傳送電子郵件」。系統只會向您在該編輯工作階段中，剛共用代理的使用者或群組傳送電子郵件通知。即使某位使用者已具備代理層級權限，群組的所有成員仍會收到電子郵件通知。電子郵件會列出分享代理的使用者名稱、代理名稱，以及在數據分析工具中開啟代理的連結。

注意： 如果 Google 群組的「誰可以張貼內容」設定設為「僅限群組成員」，群組擁有者或管理員必須將群組設定更新為「整個機構」，才能傳送郵件。

在 Gemini Enterprise 發布資料代理

您可以在 Gemini Enterprise 發布 BigQuery 資料代理，讓業務使用者直接在 Gemini Enterprise 中，以自然語言查詢及分析資料。這項程序通常需要資料分析師、Gemini Enterprise 管理員和商務使用者共同合作。如要進一步瞭解這些使用者所需的角色，請參閱「必要的角色」。

如要在 Gemini Enterprise 中發布資料代理，請完成下列步驟：

1. 查看必要條件。
2. 在 BigQuery 建立及發布資料代理。
3. 在 Gemini Enterprise 佈建代理。
4. 探索代理並與其對話。

審視必備條件

建議使用 Agent Registry 發布 BigQuery 對話式數據分析代理。請按照本節中的必要條件操作，確保 Gemini Enterprise 能找到代理。

或者，您也可以使用 A2A 資訊卡 JSON 發布代理。如果使用這個方法，請參閱「在 BigQuery 中建立及發布資料代理程式」。

如要使用 Agent Registry，您必須先設定 Agent Gateway，並對應適當的區域。BigQuery 資料代理和 Gemini Enterprise 中的 Agent Gateway 註冊繫結，必須位於相同的儲存空間區域。

您可以在 BigQuery 網頁版 UI 的代理編輯器中，透過「Region」(區域) 部分設定代理的儲存空間區域。儲存代理後，就無法變更區域。

下圖顯示 Agent Gateway 中可用的區域選項：

身為 Gemini Enterprise 管理員，請按照下列步驟，為 Gemini Enterprise 應用程式設定 Agent Gateway：

1. 設定 Agent Gateway，其中包含與資料代理程式區域相符的 Agent Registry 繫結。選項包括「US」(美國)、「EU」(歐盟) 或「Global」(全球)。
2. 在 Gemini Enterprise 中開啟應用程式，依序前往「Security」(安全性) >「Configuration」(設定)，然後在「Agent Gateway configuration」(代理閘道設定) 部分輸入閘道資源名稱。如需詳細操作說明，請參閱「透過 Agent Gateway 轉送 Gemini Enterprise 流量」。

在 BigQuery 建立及發布資料代理

身為資料分析師，您可以在 BigQuery 中建立、設定及發布代理，步驟如下：

1. 在 BigQuery 中建立或編輯資料代理。
2. 在「Region」(區域) 部分，確認儲存空間區域與資料來源和代理閘道設定相符。選項包括「US」(美國)、「EU」(歐盟)或「Global」(全球)。
3. 按一下「Publish」(發布)，如果代理先前已發布，則按一下「Publish updates」(發布更新)。
4. 在「Publishing channels」(發布管道) 窗格的「Additional channels」(其他管道) 下方，選擇發布方式：
   • 如果 BigQuery 和 Gemini Enterprise 位於同一個專案，請在「Agent Registry」部分，勾選「Register this agent」核取方塊。
     • 如要從登錄檔中移除代理，請按一下「Unregister」(取消註冊)。
   • 如果 BigQuery 和 Gemini Enterprise 位於不同專案，請在「Integrate via A2A (Agent2Agent)」(透過 A2A (Agent2Agent) 整合) 區段，按一下「Copy JSON」(複製 JSON) 複製 A2A 端點 JSON 資料，然後與 Gemini Enterprise 管理員分享 JSON 資料。您在「在 Gemini Enterprise 中佈建代理程式」一節中，會使用這個 JSON 資料。
5. 按一下「發布」或「發布更新」。
6. 將代理分享給需要存取權的使用者和群組，並授予 Gemini Data Analytics 資料代理使用者 (roles/geminidataanalytics.dataAgentUser) 角色。

在 Gemini Enterprise 中佈建代理

Gemini Enterprise 管理員可透過下列任一方式，在應用程式中開放使用者存取資料代理：

方法 1：從 Agent Registry 匯入

請按照下列步驟匯入已註冊的代理：

1. 如果 Gemini Enterprise 與 BigQuery 專案位於不同專案，請完成下列步驟，在 Agent Registry 中手動註冊代理。否則請略過這個步驟：
   1. 在 Google Cloud 控制台中，前往與 Gemini Enterprise 相同的專案，然後選取「Agent Registry」(代理程式登錄)，按一下「Agents」(代理程式) 分頁標籤，然後按一下「Add agent」(新增代理程式)。
   2. 在「Agent details」(代理程式詳細資料) 窗格中，「Type」(類型) 請選取「A2A」。
   3. 在「Region」(區域) 部分，選取與資料代理程式和 Agent Gateway 設定相符的區域。
   4. 選取「貼上 JSON」，貼上從 BigQuery 取得的 A2A 端點 JSON 資料，然後按一下「儲存」。
2. 在 Gemini Enterprise 中，按一下要新增代理程式的應用程式名稱。
3. 在導覽選單中，依序點選「Agents」(代理) > 「Add agent」(新增代理)。
4. 在「Choose an agent type」(選擇代理類型) 窗格中，找到「Agents from Agent Registry」(代理登錄檔中的代理)，然後按一下「Add」(新增)。
5. 在「Add agent」(新增代理) 窗格中，依據名稱、Agent Registry ID、類型、提供者或用途搜尋代理，或在清單中找出代理資訊卡。
6. 在代理程式資訊卡上，按一下「新增代理程式」。
7. 在「Review agent details」(查看代理詳細資料) 步驟中，查看從代理 A2A 資訊卡填入的代理中繼資料，包括名稱、說明、代理網址、功能和技能，然後按一下「Next」(下一步)。
8. 在「驗證代理程式」步驟中，選取 Gemini Enterprise 向代理程式供應商驗證的方式：
   • 預設的 Google 代管憑證：Google 會自動管理 OAuth 憑證。您不必手動設定或輸入用戶端憑證。
   • Custom OAuth (自訂 OAuth)：只有在貴機構需要自訂 OAuth 用戶端憑證時，才選取這個選項，並輸入用戶端 ID、用戶端密鑰、授權網址和權杖網址。
9. 按一下「完成」。
10. 代理會顯示在「代理」表格中，狀態為「已啟用」，代理類型為「A2A (自訂)」。
11. 與需要存取權的使用者或群組共用代理。

方法 2：使用 A2A 資訊卡 JSON 匯入

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

如果 BigQuery 和 Gemini Enterprise 位於不同專案，請按照下列步驟，使用 A2A 卡片 JSON 匯入代理：

1. 在 Gemini Enterprise 中，點選要新增代理的應用程式名稱。
2. 在導覽選單中，依序點選「Agents」(代理) > 「Add agent」(新增代理)。
3. 在「Choose an agent type」(選擇代理類型) 窗格中，找到「Custom agent via A2A」(透過 A2A 建立的自訂代理)，然後按一下「Add」(新增)。
4. 在「代理商資訊卡 JSON」欄位中，輸入從資料分析師收到的代理商資訊卡 JSON。
5. 依序點選「預覽代理程式詳細資料」>「下一步」。
6. 在「Agent authorization」(代理授權) 步驟中，選取驗證方式：
   • 預設 Google 代管憑證：Google 會自動管理 OAuth 憑證，您不必手動輸入或產生用戶端 ID 和用戶端密鑰。
   • 自訂 OAuth：如要手動提供自訂 OAuth 憑證，請選取這個選項，然後按照「註冊及管理 A2A 代理程式」一文中的步驟操作。
7. 在「Tool authorizations」(工具授權) 步驟中，按一下「Finish」(完成)。
8. 代理會顯示在「代理」表格中，狀態為「已啟用」，代理類型為「A2A (自訂)」。
9. 與需要存取權的使用者或群組共用代理。

探索及使用代理

您可以透過下列任一方式，在 Gemini Enterprise 中探索及使用資料代理：

• 手動探索：在代理庫中找到資料代理，並透過下列任一方式使用：
  • 瀏覽代理庫：選取代理並開始專屬對話。
  • 直接連結：使用代理的專屬網址，直接在 Gemini Enterprise 中與該 BigQuery 資料代理展開對話。
  • 導向意圖：在 Gemini Enterprise 核心聊天室中，使用 @mention 呼叫代理程式 (例如 @sales_pipeline_agent)。
  • 無縫自動化調度：提出一般分析問題 (例如「過去 3 個月，我們的銷售管道趨勢如何？」)，Gemini Enterprise 就會自動將查詢傳送至相關資料代理程式。

找到代理程式後，請按照下列步驟與其互動：

• 驗證：完成一次性 OAuth 登入，安全地向 BigQuery 驗證。
• 即時通訊：以自然語言向服務專員提問。要求會由代理程式處理，並以文字、Markdown、圖表或表格的形式，將回應串流回 Gemini Enterprise。
• 查看對話記錄：對話會自動儲存在記錄窗格中。

監控服務專員和對話

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

注意： 如要提供意見回饋或尋求這項功能的支援，請傳送電子郵件至 [e-mail]。

您可以在 BigQuery 中使用 Google Cloud Observability，監控資料代理及其對話的效能、採用率、延遲時間和成本。啟用代理觀測後，您可以查看下列指標：

• 對話中使用的代理數量
• 提問的使用者人數
• 建立的對話數量
• 回答最多問題的服務專員
• 最常用的知識來源
• 使用者參與
• 預估詞元用量
• 每小時回答延遲時間

事前準備

如果尚未啟用，請啟用 Cloud Trace、Cloud Monitoring 和 Cloud Logging API。

啟用 API 所需的角色

如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

所需角色和權限

如要啟用代理觀測功能，您必須具備下列專案權限：

• cloudaicompanion.gibqObservabilitySettings.create
• cloudaicompanion.gibqObservabilitySettings.list
• cloudaicompanion.gibqObservabilitySettings.update
• cloudaicompanion.settingBindings.gibqObservabilitySettingsCreate
• cloudaicompanion.settingBindings.gibqObservabilitySettingsList
• cloudaicompanion.settingBindings.gibqObservabilitySettingsUse
• geminidataanalytics.dataAgents.create
• geminidataanalytics.operations.get
• observability.traceScopes.create
• resourcemanager.projects.update
• serviceusage.services.enable
• serviceusage.values.test

如要取得透過指標、追蹤記錄和記錄檔監控代理所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 查看監控資料和設定：Monitoring 檢視者 (roles/monitoring.viewer)
• 查看追蹤記錄：Cloud Trace 使用者 (roles/cloudtrace.user)
• 查看記錄： 記錄檢視器 (roles/logging.viewer)
• 查看資料集及其內容：BigQuery 資料檢視者 (roles/bigquery.dataViewer)
• 查看管理員設定： Gemini 版 Google Cloud 使用者 (roles/cloudaicompanion.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

啟用觀測能力

代理觀測預設為停用。管理員可以為專案或組織啟用這項功能。如要啟用代理的可觀測性，請選取下列其中一個選項：

控制台

1. 前往 Google Cloud 控制台的「BigQuery Agents」頁面。

   前往「Agents」

2. 選取「監控」分頁標籤。

3. 如果可觀測性已停用，請按照提示啟用。

Google Cloud CLI

1. 建立觀測能力設定：

   gcloud gemini gibq-observability-settings create SETTING_NAME \
     --conversational-analytics-setting-metrics-enabled \
     --conversational-analytics-setting-traces-enabled \
     --project=PROJECT_ID \
     --location=global

   更改下列內容：

   • SETTING_NAME：觀測能力設定的名稱。
   • PROJECT_ID：專案 ID。

2. 將觀測能力設定繫結至專案：

   gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
     --gibq-observability-setting=SETTING_NAME \
     --target=projects/PROJECT_ID \
     --location=global \
     --project=PROJECT_ID

   將 BINDING_NAME 替換為設定繫結的名稱。建議您使用 binding-PROJECT_ID 做為繫結名稱。

API

1. 建立觀測能力設定：

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "conversational_analytics_setting": {
               "metrics_enabled": true
             }
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"

   更改下列內容：

   • SETTING_NAME：觀測能力設定的名稱。
   • PROJECT_ID：專案 ID。

2. 將觀測能力設定繫結至專案：

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "target": "projects/PROJECT_ID",
             "product": "GEMINI_IN_BIGQUERY"
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"

   將 BINDING_NAME 替換為設定繫結的名稱。建議您使用 binding-PROJECT_ID 做為繫結名稱。

查看指標

啟用觀測能力後，系統就會收集指標。系統不會回填資料。如要查看代理程式指標，請選取下列其中一個選項：

BigQuery

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

   前往「Agents」

2. 選取「監控」分頁標籤。

Cloud Monitoring

1. 前往 Google Cloud 控制台的 Cloud Monitoring「Dashboards」(資訊主頁) 頁面。

   前往「Dashboards」(資訊主頁)

2. 在「My Dashboards」(我的資訊主頁) 窗格，搜尋名為 BigQuery Conversational Analytics 的資訊主頁。

3. 按一下資訊主頁名稱即可開啟。

4. 選用：建立自訂資訊主頁。

5. 選用：如要個別查看指標，請前往「Metrics Explorer」頁面。

   前往「Metrics Explorer」頁面

   代理指標包括代理用量、模型呼叫、工具用量、健康狀態、延遲時間和權杖用量。

偵錯模型呼叫

您可以視覺化呈現對話回合中的作業序列，例如模型呼叫和工具呼叫，協助排解錯誤和延遲問題。

1. 前往 Google Cloud 控制台的 Cloud Monitoring「Trace explorer」(Trace 探索工具) 頁面。

   前往「Trace explorer」(Trace 探索工具)

2. 按一下要檢查的範圍。

3. 查看「詳細資料」窗格中的資訊。

4. 選用：建立自訂追蹤資訊主頁。

保留追蹤記錄

Cloud Trace 資料會儲存在可觀測性資料集中 30 天。如要延長追蹤記錄資料的儲存時間，請將資料移至 BigQuery 資料集。

必要的角色

如要取得建立連結資料集，將即時追蹤記錄公開至 BigQuery 所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• Cloud Trace 管理員 (roles/cloudtrace.admin)
• 觀測能力編輯者 (roles/observability.editor)
• BigQuery 使用者 (roles/bigquery.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

將追蹤記錄資料移至 BigQuery

如要保留追蹤記錄資料，請按照下列步驟操作：

1. 開啟 Cloud Shell。

2. 找出 _Trace bucket 的位置：

   gcloud beta observability buckets list --location=-

   記下 _Trace bucket 的位置，以便在下一個步驟中使用。

3. 在 BigQuery 專案中建立連結資料集，並指向 _Trace bucket：

   gcloud beta observability buckets datasets links create \
       projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
       --dataset=Spans \
       --bucket=_Trace \
       --location=LOCATION \
       --project=PROJECT_ID

   更改下列內容：

   • PROJECT_ID：專案 ID
   • LOCATION：上一個步驟中 _Trace bucket 的位置
   • LINK_NAME：連結資料集的名稱

4. 建立標準資料集，用於儲存歷來追蹤記錄。下列指令會將預設分區到期時間設為 90 天 (7,776,000 秒)：

   bq --location=LOCATION mk \
       --dataset \
       --default_partition_expiration=7776000 \
       --description="Archive storage for historical traces" \
       PROJECT_ID:STORAGE_DATASET

   將 STORAGE_DATASET 替換為資料集的名稱。

5. 在儲存空間資料集中建立空白的分區資料表，結構定義與連結的資料集相同。按日期分區有助於管理資料保留和查詢費用。如要建立資料表，請在 SQL 編輯器中執行下列查詢：

   CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   PARTITION BY DATE(start_time)
   AS
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE FALSE;

   將 TABLE_NAME 替換為資料表的名稱。

6. 建立排程查詢，將連結資料集中的每日追蹤資料複製到封存資料表。下列查詢會複製前一天的資料：

   INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE start_time >=
     TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
     AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);

詳情請參閱「尋找及探索追蹤記錄」。

關閉可觀測性

如要關閉資料代理的可觀測性，請更新可觀測性設定：

gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global

更改下列內容：

• SETTING_NAME：您建立的可觀測性設定名稱，用於啟用可觀測性。如果您是透過 Google Cloud 控制台啟用觀測能力，設定名稱會是default。
• PROJECT_ID：專案 ID。

後續步驟

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