建立資料代理程式

預覽

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

對話式資料代理可讓您透過自然語言介面與資料庫資料互動。建構這些代理程式後，使用者就能「與資料對話」，從作業資料庫取得洞察結果，不必編寫複雜的 SQL 查詢。

就整體而言，資料代理是角色、一組資料來源的組合，可存取一組對其用途至關重要的業務知識。

對應用程式開發人員而言，這些代理程式可帶來下列好處：

• 高精確度：使用撰寫的內容，可針對特定業務問題取得高精確度的答案。撰寫的脈絡是代理程式建立者可用來提高準確度的主要關鍵因素。包括結構定義說明、系統指令和結構化內容，可提供預期資料庫查詢的額外資訊。
• 降低複雜度：代理程式會將自然語言轉換為 SQL 查詢、執行查詢，甚至產生資料摘要或視覺化內容。
• 彈性：您可以草擬代理程式進行個人測試，也可以發布代理程式，供專案中的其他使用者使用，或透過 API 以程式輔助方式使用。

事前準備

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

2. 啟用 Spanner、Data Analytics API with Gemini 和 Gemini for Google Cloud APIs。

   啟用 API 時所需的角色

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

   啟用 API

必要的角色

如要使用資料代理程式，您必須具備符合用途的 IAM 權限。下表列出建立及發布代理程式、在 Gemini Enterprise 中佈建代理程式，或探索及使用代理程式時所需的角色。詳情請參閱「Conversational Analytics API Identity and Access Management 角色」。

用途	必要的角色
建立、編輯、發布、共用及刪除代理程式	如要在專案中建立資料代理，請在專案中具備 Gemini Data Analytics 資料代理建立者 (roles/geminidataanalytics.dataAgentCreator) 權限。這個角色會自動授予您所建立資料代理的 Gemini Data Analytics 資料代理擁有者角色。 如要編輯、共用或刪除資料代理，您必須是代理或專案的 Gemini Data Analytics 資料代理擁有者 (roles/geminidataanalytics.dataAgentOwner)。 如要在專案中編輯資料代理，您必須是專案的 Gemini Data Analytics 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)。 如要查看專案中的資料代理，請在專案中具備 Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer) 角色。 此外，您必須具備下列角色，才能建立或編輯資料代理程式： 新增至叢集的 IAM 使用者或服務帳戶。詳情請參閱「套用 IAM 角色」。 在專案層級授予 IAM 使用者的 spanner.databaseReader 角色。詳情請參閱「為專案新增 IAM 政策繫結」。 在專案層級授予 IAM 使用者必要資料庫的角色和權限。詳情請參閱「授予角色和權限」。
在 Gemini Enterprise 中佈建代理	如要讓 Gemini Enterprise 使用者存取已發布的代理程式，您必須在 Gemini Enterprise 管理控制台中，具備註冊及管理 A2A 代理程式的權限。
探索及使用代理	如要與資料代理交談，請使用 Gemini Data Analytics 資料代理使用者 (roles/geminidataanalytics.dataAgentUser)。 如要查看專案中的所有資料代理，請使用 Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)。

如要使用 Spanner 資源，請參閱「Spanner 角色和權限」。

建立資料代理

下列各節說明如何建立資料代理程式。建立代理程式後，您可以編輯其設定。

進行基本設定

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

   前往 Spanner

2. 從清單中選取執行個體，然後選取資料庫。

3. 在導覽選單中，按一下「代理商」。

4. 按一下「代理商」分頁標籤。

5. 選取資料庫，然後使用 IAM 帳戶登入。

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

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

8. 在「代理說明」欄位中，輸入資料代理的說明。好的說明會解釋代理的用途、使用的資料，並協助您判斷是否應將這個資料代理用於對話，例如 What are the top 10 selling products in Q2?

9. 在「知識來源」部分中，按一下「新增來源」。「新增資料」頁面隨即開啟。

10. 選取代理回答問題時要著重使用的資料表。如要查看其他知識來源，請選取「顯示更多」。

11. 按一下「Add」(新增)。系統會重新開啟新的代理程式頁面。

自訂表格和欄位說明

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

• 結構描述：為表格和資料欄新增說明，協助代理程式瞭解資料。如未新增說明，代理程式會使用資料定義中的結構定義說明。

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

• 請在資料定義中新增說明，而非僅在資料代理程式定義中新增。確保其他代理商也能從說明中獲益。
• 如要製作適當的說明原型，協助資料代理瞭解資料，請為特定代理新增說明。確認說明達到預期效果後，即可決定是否要在資料定義中新增說明。

如要設定表格和欄位說明，請按照下列步驟操作：

1. 在「代理程式目錄」分頁中，開啟要自訂的代理程式。
2. 按一下「編輯代理程式」。
3. 在「知識來源」中，找到要自訂的表格，然後按一下「自訂」。
4. 輸入表格說明。
5. 如要編輯任何欄位說明，請按一下欄位旁的「編輯」 。「編輯欄位」窗格隨即開啟。
   1. 在「ID」欄位中，輸入欄位說明。
   2. 如要儲存欄位說明，請按一下「更新」。
6. 如要儲存說明和欄位更新，請按一下「更新」。系統會重新開啟新的代理程式頁面。
7. 針對要自訂的每個表格重複執行上述步驟。

為資料代理程式新增標籤

在「代理程式設定」部分，您可以建立標籤來整理資源。 Google Cloud 標籤是鍵/值組合，可用來將相關的物件分組，或與其他 Google Cloud資源組合。

1. 在「代理程式目錄」分頁中，開啟要新增標籤的代理程式。
2. 按一下「編輯代理程式」。
3. 在「代理程式設定」部分中，按一下「新增標籤」。「管理標籤」窗格隨即開啟。
4. 按一下「新增標籤」。
5. 在「key」和「value」欄位中，輸入標籤的鍵/值組合。
6. 如要新增其他標籤，請再次按一下「新增標籤」。
7. 如要刪除標籤，請按一下「刪除」。
8. 完成後，按一下「新增」。系統會重新開啟新的代理程式頁面。

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

預覽及發布代理程式

1. 在「預覽」部分中，於「提出問題」欄位輸入範例問題，然後按 Enter 鍵。

   如要確認資料代理程式是否傳回您預期的資料，請檢查代理程式的回覆。如果回應不符預期，請在「編輯器」部分變更設定，微調資料代理程式設定，直到獲得滿意的回應為止。您可以繼續測試及修改代理程式，以改善代理程式的結果。

2. 按一下 [儲存]。

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

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

4. 如要發布資料代理程式，並在專案中啟用，請按一下「發布」。發布代理程式後，其他有權存取相同資料庫表格的使用者，就能查看代理程式並與之對話，從您建立的指令和情境獲益。

   您可以在 Google Cloud 控制台的「Agents」頁面中，與資料代理建立對話。您也可以使用 Conversational Analytics API，建構自己的介面與資料代理對話。

5. 選用：在「您的代理已發布」對話方塊中，按一下「共用」，即可與其他使用者共用資料代理。

   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)：授予檢視資料代理的權限。
   5. 按一下 [儲存]。

6. 選用：您可以將資料代理發布至 Gemini Enterprise。詳情請參閱「在 Gemini Enterprise 中發布資料代理程式」。

7. 如要返回新的代理程式頁面，請按一下「關閉」。儲存或發布代理後，您可以在代理目錄中查看。

管理資料代理程式

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

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

編輯資料代理程式

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

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

   前往 Spanner

2. 從清單中選取執行個體，然後選取資料庫。

3. 在導覽選單中，按一下「代理商」。

4. 使用 Identity and Access Management (IAM) 驗證登入 Agents。

5. 按一下「代理程式目錄」分頁標籤。

6. 找出要修改的資料代理人代理人資訊卡。

7. 如要在代理編輯器中開啟資料代理，請按一下「開啟動作」，然後點選代理資訊卡上的「編輯」。

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

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

10. 如要發布變更，請按一下「發布」。在「分享」對話方塊中，您可以與他人共用代理程式，也可以按一下「取消」。

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

共用資料代理

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

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

   前往 Spanner

2. 從清單中選取執行個體，然後選取資料庫。

3. 在導覽選單中，按一下「代理商」。

4. 使用 Identity and Access Management (IAM) 驗證登入 Agents。

5. 按一下「代理程式目錄」分頁標籤。

6. 找出要修改的資料代理人代理人資訊卡。

7. 如要在代理編輯器中開啟資料代理，請依序點按 「開啟動作」 > 代理資訊卡上的「編輯」。

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

9. 在「共用權限」窗格中，按一下「新增主體」。

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

11. 按一下「選擇角色」。

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

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

13. 按一下 [儲存]。

14. 如要返回代理程式編輯頁面，請按一下「關閉」。

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

刪除資料代理程式

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

   前往 Spanner

2. 從清單中選取執行個體，然後選取資料庫。

3. 在導覽選單中，按一下「代理商」。

4. 使用 Identity and Access Management (IAM) 驗證登入 Agents。

5. 選取「代理程式目錄」分頁。

6. 在「代理程式目錄」分頁的「代理程式」部分，找到要刪除的資料代理程式代理程式卡片。

7. 依序點按 「開啟動作」 >「刪除」。

8. 在「Delete agent?」(要刪除代理程式嗎？) 對話方塊中，按一下「Delete」(刪除)。永久刪除代理程式後，系統會將代理程式從專案中移除。

   刪除代理程式後，現有對話將僅供檢視。您無法再向已刪除的代理提出新問題。

在 Gemini Enterprise 中發布資料代理

發布資料代理程式時，需要資料分析師、Gemini Enterprise 管理員和商務使用者共同合作。如要瞭解這些使用者所需的角色，請參閱「必要的角色」。

建立及發布代理程式

如要建立、編輯及發布代理程式，請按照下列步驟操作：

1. 在 Spanner 中建立或編輯資料代理。
2. 發布代理程式。發布代理時，請選取「Gemini Enterprise」做為發布選項。
3. 如要複製 A2A 端點 JSON，請按一下「複製 JSON」。
4. 將 A2A 端點 JSON 和使用者清單提供給 Gemini Enterprise 管理員，讓他們在 Google Cloud 控制台中註冊自訂代理程式，並設定存取權。詳情請參閱「佈建代理程式」。
5. 共用代理程式，讓需要存取權的使用者和群組都能使用。

佈建代理程式

如要讓使用者在 Google Cloud 控制台中使用已發布的代理程式，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Gemini Enterprise」。

   Gemini Enterprise

2. 按一下要註冊代理程式的應用程式名稱。

3. 依序點選「代理」 >「新增代理」。

4. 在「選擇代理類型」部分，按一下「透過 A2A 新增自訂代理」的「新增」。

5. 在「代理商資訊卡 JSON」欄位中，輸入您先前從資料分析師收到的代理商資訊卡詳細資料 (JSON 格式)。

6. 按一下「預覽代理程式詳細資料」>「下一步」。

7. 如要允許代理程式代表您存取 Google Cloud 資源，請按照下列步驟操作：

   1. 輸入您在「設定授權詳細資料」部分產生的「用戶端 ID」和「用戶端密鑰」。

   2. 在「Authorization URI」欄位中，輸入下列內容：

      https://accounts.google.com/o/oauth2/v2/auth?client_id=client_id&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      將 client_id 替換為您在「設定授權詳細資料」中產生的用戶端 ID。

   3. 在「權杖 URI」欄位中，輸入下列內容：

      https://oauth2.googleapis.com/token

   4. 在「範圍」欄位中輸入下列內容：

      https://www.googleapis.com/auth/cloud-platform

8. 按一下「完成」。

9. 與使用者或群組共用代理程式。

詳情請參閱「註冊及管理 A2A 代理程式」。

尋找及使用代理程式

您可以使用下列任一方法，在 Gemini Enterprise 中尋找及使用資料代理：

• 在代理庫中找到代理，然後開始專屬對話。
• 使用代理程式的專屬網址，直接在 Gemini Enterprise 中開啟與該特定 Spanner 資料代理程式的對話。
• 在 Gemini Enterprise 核心對話中輸入 @mention (例如 @sales_pipeline_agent)，即可叫用代理。
• 提出一般分析問題，例如「過去 3 個月內，我們的銷售漏斗趨勢如何？」，讓 Gemini Enterprise 自動將查詢轉送至相關資料代理程式。

找到代理程式後，您可以使用下列其中一種方法與其互動：

• 完成一次性 OAuth 登入，安全地向 Spanner 驗證。
• 以自然語言提問。對話式數據分析代理程式會處理您的要求，並以文字、Markdown、圖表或表格的形式，將回應串流回 Gemini Enterprise。
• 在記錄窗格中查看對話記錄，系統會自動儲存對話。

位置

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

後續步驟

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