建立資料代理程式

預覽

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

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

整體來說，資料代理是由角色、一組資料來源，以及一組對其用途至關重要的業務知識所組成。

對應用程式開發人員來說，這些代理程式有下列優點：

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

事前準備

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

2. 啟用 Cloud SQL、Data Analytics API with Gemini 和 Gemini for Google Cloud API (如有尚未啟用的 API)。

   啟用 API 所需的角色

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

   啟用 API

必要的角色

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

用途	必要的角色
建立、編輯、發布、共用及刪除代理	如要在專案中建立資料代理，請在專案中具備 Gemini Data Analytics 資料代理建立者 (roles/geminidataanalytics.dataAgentCreator) 角色。具備這個角色後，您建立的資料代理會自動授予您 Gemini 資料分析資料代理擁有者角色。 如要編輯、共用或刪除資料代理，請在代理或專案中，取得 Gemini 資料分析資料代理擁有者 (roles/geminidataanalytics.dataAgentOwner) 角色。 如要編輯專案中的資料代理：專案的 Gemini Data Analytics 資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)。 如要查看專案中的資料代理，請在專案中具備 Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer) 角色。 此外，您必須具備下列角色，才能建立或編輯資料代理： 新增至執行個體的 IAM 使用者或服務帳戶。詳情請參閱「使用 Cloud SQL 的 IAM 資料庫驗證功能管理使用者」。 在專案層級授予 IAM 使用者的 cloudsql.studioUser 和 cloudsql.instanceUser 角色。詳情請參閱「新增專案的 IAM 政策繫結」。 選用：如果資料庫資料代理使用情境集 (預先發布版)，則須在專案層級，將 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色授予 IAM 使用者，以便建立、上傳及管理情境集。詳情請參閱「情境組合權限」。 以 postgres 使用者身分登入，將資料庫權限授予 IAM 使用者或服務帳戶。 GRANT ALL ON SCHEMA public TO public; 詳情請參閱「將資料庫權限授予個別 IAM 使用者或服務帳戶」。
在 Gemini Enterprise 佈建代理	如要讓 Gemini Enterprise 使用者存取已發布的代理，您必須具備 Gemini Enterprise 管理控制台的註冊及管理 A2A 代理權限。
探索及使用代理	與資料代理對話：Gemini Data Analytics 資料代理使用者 (roles/geminidataanalytics.dataAgentUser)。 如要查看專案中的所有資料代理：Gemini Data Analytics 資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)。

管理 PostgreSQL 適用的 Cloud SQL 資料庫資源存取權時，請考量下列權限層級：

• Google Cloud IAM：控管資料庫執行個體做為雲端資源的存取權。包括連線、管理執行個體和執行 SQL 查詢的權限，例如使用 executeSql 權限。
• 資料庫權限：控管資料庫中物件 (例如資料表、檢視表和結構定義) 的存取權。這些權限是透過 GRANT 等 SQL 指令，以及資料庫專屬的使用者和角色系統管理。

如果是 PostgreSQL 適用的 Cloud SQL，您必須具備適當的 Cloud SQL IAM 角色，才能連線至執行個體，並取得傳送查詢的授權。如要與資料表和檢視表等物件互動，連線資料庫使用者必須具備使用 PostgreSQL 適用的 Cloud SQL GRANT 系統授予的必要權限。詳情請參閱「關於 PostgreSQL 使用者和角色」。如果代理程式使用服務帳戶，您可以指派資料庫角色。例如，請參閱「使用 IAM 資料庫驗證機制管理使用者」。

建立資料代理

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

進行基本設定

1. 前往 Google Cloud 控制台的「PostgreSQL 適用的 Cloud SQL」頁面。

   前往 Cloud SQL

2. 從清單中選取執行個體。

3. 在導覽選單中，按一下「對話」。

4. 按一下「Agents」分頁標籤。

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

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

7. 在「Editor」(編輯器) 區段的「Agent name」(代理程式名稱) 欄位中，輸入資料代理程式的描述性名稱，例如 Q4 sales data 或 User activity logs。

8. 在「Agent description」(代理說明) 欄位中，輸入資料代理的說明。好的說明會解釋代理的功用、使用的資料，並協助您判斷是否要使用這個資料代理進行對話，例如：What are the top 10 selling products in Q2?

9. 在「知識來源」部分，點選「新增來源」。「Add data」(新增資料) 頁面隨即開啟。

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

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

自訂資料表和欄位說明

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

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

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

• 請在資料定義中加入說明，而非僅在資料代理定義中加入。確保其他代理也能從說明中受益。
• 如要設計適當的說明，協助資料代理瞭解資料，請為特定代理新增說明。確認說明達到預期效果後，再決定是否要將說明新增至資料定義。

如要自訂代理的資料表和欄位說明，請按照下列步驟操作：

1. 在「Agent Catalog」(代理目錄) 分頁中，開啟要自訂的代理。
2. 按一下「編輯代理」。
3. 在「知識來源」中，找到要自訂的表格，然後按一下「自訂」。
4. 在「資料表說明」中新增說明，或接受 Gemini 的建議。
5. 在「Fields」(欄位) 中，查看 Gemini 建議的資料表欄說明。
6. 管理建議的欄位說明：
   • 如要接受建議，請選取所需說明，然後按一下「Accept suggestions」(接受建議)。
   • 如要拒絕建議，請選取所需說明，然後按一下「Reject suggestions」(拒絕建議)。
7. 如要編輯欄位說明，請按一下欄位旁的 「Edit」(編輯)。
   1. 在「Description」(說明) 中輸入欄位說明。
   2. 按一下「更新」儲存編輯內容。
8. 按一下「更新」，儲存表格的自訂設定。
9. 針對要自訂的每個資料表，重複執行上述步驟。

建立通過驗證的查詢

注意： 只有「引導」模式可以新增已驗證查詢

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

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

1. 在「Agent Catalog」(代理目錄) 分頁中，開啟要自訂的代理。
2. 按一下「編輯代理」。

3. 在「已驗證的查詢」中，按一下「查看 Gemini 生成的建議」。

   1. 在「Review suggested verified queries」(查看建議的已驗證查詢) 中，查看建議的已驗證查詢。
   2. 選取符合用途的查詢。
   3. 按一下「Add」，將查詢新增至內容。
   注意： 如要編輯建議查詢，請展開建議查詢，然後按一下「編輯」。

4. 選用。如要建立自己的已驗證查詢，請在「已驗證的查詢」中點選「新增查詢」。

   1. 在「Question」(問題) 中，輸入可透過已驗證查詢回答的問題。
   2. 點選「Generate SQL」(生成 SQL)，讓 Gemini 生成與您新增的問題相對應的已驗證查詢。
   3. 點選「Run」(執行)，確認查詢傳回預期結果。
   4. 查看回覆，並視需要修改通過驗證的查詢。
   5. 按一下「新增」。

5. 重複上述步驟，建立其他已驗證的查詢。

為資料代理新增標籤

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

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

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

預覽及發布代理

1. 在「Preview」(預覽) 區段的「Ask a question」(提出問題) 欄位中輸入範例問題，然後按下 Enter 鍵。

   如要確認資料代理是否傳回預期資料，請查看代理的回覆。如果回覆不符合預期，請在「Editor」(編輯器) 區段中變更設定，調整資料代理設定，直到獲得滿意的回覆。您可以繼續測試及修改代理，改善代理的結果。

2. 按一下 [儲存]。

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

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

4. 如要發布資料代理，並在專案中使用，請按一下「Publish」(發布)。發布代理後，其他有權存取相同資料庫資料表的使用者，就能查看代理並與其對話，並根據您建立的指示和背景資訊，獲得所需資訊。

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

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 資料分析資料代理編輯者 (roles/geminidataanalytics.dataAgentEditor)：可編輯資料代理。
      • Gemini 資料分析資料代理檢視者 (roles/geminidataanalytics.dataAgentViewer)：授予查看資料代理的權限。
   5. 按一下 [儲存]。

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

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

管理資料代理

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

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

編輯資料代理

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

1. 前往 Google Cloud 控制台的「PostgreSQL 適用的 Cloud SQL」頁面。

   前往 Cloud SQL

2. 從清單中選取執行個體。

3. 在導覽選單中，按一下「對話」。

4. 使用 Identity and Access Management (IAM) 驗證機制登入對話。

5. 按一下「Agent Catalog」分頁標籤。

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

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

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

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

10. 如要發布變更，請按一下「發布」。在「Share」(共用) 對話方塊中，您可以與他人共用代理，也可以點選「Cancel」(取消)。

11. 如要返回「Conversations」(對話) 窗格，請按一下 「Go back」(返回)。

共用資料代理

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

1. 前往 Google Cloud 控制台的「PostgreSQL 適用的 Cloud SQL」頁面。

   前往 Cloud SQL

2. 從清單中選取執行個體。

3. 在導覽選單中，按一下「對話」。

4. 使用 Identity and Access Management (IAM) 驗證機制登入對話。

5. 按一下「Agent Catalog」分頁標籤。

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

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

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

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

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

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

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

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

13. 按一下 [儲存]。

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

15. 如要返回「Conversations」(對話) 窗格，請按一下「Go back」(返回) 。

刪除資料代理

1. 前往 Google Cloud 控制台的「PostgreSQL 適用的 Cloud SQL」頁面。

   前往 Cloud SQL

2. 從清單中選取執行個體。

3. 在導覽選單中，按一下「對話」。

4. 使用 Identity and Access Management (IAM) 驗證機制登入對話。

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

6. 在「Agent Catalog」(代理程式目錄) 分頁的「Agents」(代理程式) 部分，找出要刪除的資料代理程式資訊卡。

7. 依序點選 「Open actions」(開啟動作) >「Delete」(刪除)。

8. 在「Delete agent?」對話方塊中，按一下「Delete」。刪除代理後，系統會從專案中永久移除該代理。

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

在 Gemini Enterprise 發布資料代理

發布資料代理需要資料分析師、Gemini Enterprise 管理員和業務使用者通力合作。如要瞭解這些使用者需要的角色，請參閱「必要的角色」。

建立及發布代理

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

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

佈建代理

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

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

   Gemini Enterprise

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

3. 依序點選「Agents」(代理) >「 Add Agents」(新增代理)。

4. 在「Choose an agent type」(選擇代理類型) 部分，按一下「Custom agent via A2A」(透過 A2A 自訂代理) 的「Add」(新增)。

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

6. 依序點選「預覽代理詳細資料」>「下一步」。

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

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

   2. 在「Authorization URI」(授權 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. 在「Token URI」欄位中輸入下列內容：

      https://oauth2.googleapis.com/token

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

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

8. 按一下「完成」。

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

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

尋找並使用代理

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

• 在代理庫中找到代理，然後開始專屬對話。
• 使用代理的專屬網址，直接在 Gemini Enterprise 中與該 PostgreSQL 適用的 Cloud SQL 資料代理對話。
• 在 Gemini Enterprise 核心對話中輸入 @mention (例如 @sales_pipeline_agent)，即可叫用代理。
• 提出一般分析問題，例如「過去 3 個月的銷售管道趨勢如何？」，Gemini Enterprise 就會自動將查詢轉送至相關的資料代理。

找到代理後，您可以透過下列任一方式與其互動：

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

位置

對話數據分析功能在全球運作，無法選擇要使用的區域。

後續步驟

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