建立資料代理程式

預覽

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

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

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

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

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

事前準備

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

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

   啟用 API 時所需的角色

   如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

   啟用 API

必要的角色

如要使用資料代理程式，您必須具備下列任一對話式數據分析 API Identity and Access Management (IAM) 角色：

• 使用 QueryData 方法查詢支援的資料庫來源資料： 專案層級的 Gemini Data Analytics 資料查詢使用者 (roles/geminidataanalytics.queryDataUser)。
• 在專案層級擁有 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)。

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

• 新增至叢集的 IAM 使用者或服務帳戶。詳情請參閱「套用 IAM 角色」。
• 在專案層級授予 IAM 使用者的 spanner.databaseReader 角色。詳情請參閱為專案新增 IAM 政策繫結。
• 在必要資料庫的專案層級授予 IAM 使用者的角色和權限。詳情請參閱「授予角色和權限」。

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

建立資料代理

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

進行基本設定

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

   前往 Spanner

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

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

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

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

6. 按一下「新增代理程式」，系統會開啟「新增代理程式」頁面。

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 控制台的「代理」頁面中，與資料代理建立對話。您也可以使用 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)：授予檢視資料代理的權限。

6. 按一下 [儲存]。

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

管理資料代理程式

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

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

編輯資料代理程式

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

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. 在「要刪除代理嗎？」對話方塊中，按一下「刪除」。永久刪除代理後，系統會將代理從專案中移除。

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

位置

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

後續步驟

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