對話式數據分析 API 常見問題

Conversational Analytics API 是否可以變更或刪除我的資料？

對話式數據分析 API 設有安全防護機制，可防止資料遭到變更或刪除。

以下說明如何處理不同資料來源的資料安全性：

  • BigQuery：API 會封鎖資料定義語言 (DDL) 和資料操縱語言 (DML) 陳述式。具體來說，系統會對產生的 SQL 執行測試，且只允許 SELECT 類型的查詢。
  • Looker：API 會使用 run_inline_query 等方法與 Looker 互動，這些方法僅限於選取、篩選和限制等讀取作業。這些方法不支援 DDL 或 DML 作業，也不包含刪除或捨棄作業。
  • Looker Studio (適用於 CSV 和 Google 試算表)：Looker Studio 會使用結構化格式定義及擷取資料，以製作視覺化內容和報表。以這個方法執行的任何查詢都是唯讀，且不支援資料變異。

對話式數據分析 API 的設計宗旨，是讓使用者只能讀取這些資料來源的資料。如要進一步瞭解對話式數據分析 API 的安全性，請參閱「Chat with confidence: Unpacking security in Looker Conversational Analytics」網誌文章。

如何處理驗證和權限錯誤？

使用對話式數據分析 API 時，可能會遇到一些常見的驗證和權限錯誤，如下所示：

  1. 錯誤：PERMISSION_DENIED 或 403 Write access to project ... was denied

    • 可能原因：這則訊息通常表示 Google Cloud IAM 角色有問題。嘗試使用 API 的使用者或服務帳戶在 Google Cloud 專案中缺少必要權限。
    • 疑難排解：
      • Google Cloud 專案擁有者必須確保使用者或服務帳戶在 Google Cloud 專案中已獲派正確的 IAM 角色。您可能需要 Project Editor 等角色，才能執行特定作業，例如啟用 API 或測試其功能。
      • 如果切換區域時發生 403 錯誤 (例如 Write access to project 'us-gcp-project-name' was denied)，請檢查專案的 IAM 設定。

  2. 錯誤：500 Internal Server Error當具有「使用者」角色的 Looker 使用者嘗試與資料代理程式對話時。

使用 Conversational Analytics API 時，Looker 有哪些規定？

如要使用 Conversational Analytics API，您必須在 Google Cloud IAM 和 Looker 中具備適當權限，具體視資料來源和要執行的動作而定：

  1. Google Cloud IAM 角色：

    • 您必須在 Google Cloud 專案中具備足夠的 IAM 角色，才能與 geminidataanalytics.googleapis.com API 互動。IAM 角色設定錯誤通常會導致 PERMISSION_DENIED 錯誤。
    • 視動作而定，可能需要特定角色，但某些作業可能需要「專案編輯者」等一般角色。

  2. Looker 權限和角色：

    • 模型層級權限：如要使用對話式數據分析和對話式數據分析 API，Looker 使用者必須獲派角色，其中包含與模型互動的 gemini_in_looker 權限。

如要進一步瞭解使用 Conversational Analytics API 時所需的權限和角色，請參閱「授予 Conversational Analytics API 身分與存取權管理角色和權限」說明文件頁面。

此外，Looker 執行個體也必須符合特定需求：

如要在 Looker Studio Pro 中使用 Conversational Analytics API，Pro 訂閱方案必須位於 VPC-SC 周邊以外。

如何從 Data QnA API 遷移至 Conversational Analytics API？

如果您使用的是舊版實驗性 Data QnA API (dataqna.googleapis.com)，請參閱遷移指南，瞭解如何遷移至 Conversational Analytics API 的新正式端點 (geminidataanalytics.googleapis.com)。

資料代理人的名稱和 ID 有何不同？

資料代理人的 ID (定義為 data_agent_id 的值) 是資料代理人的專屬 ID。資料代理程式的名稱 data_agent.name 會自動從 data_agent_id 衍生為完整名稱 (FQN)，格式為 projects/<project>/locations/<location>/dataAgents/<data_agent_id>。

建立資料代理程式時，系統會忽略您為 data_agent.name 輸入的任何值。執行 get、update 或 delete 作業時，系統會將完整 data_agent.name 視為資料代理程式的專屬 ID。

使用 Conversational Analytics API 建立資料代理程式時，適用下列情境：

  • 如果未定義 data_agent_id，系統會自動產生專屬 ID。
  • 如果您將 data_agent_id 定義為 TestID，則您為 data_agent.name 輸入的任何值都會遭到 projects/<project>/locations/<location>/dataAgents/TestID 覆寫。
  • 如果使用 FQN 定義 data_agent_id，就會收到「malformed name」錯誤。

在「建立代理程式」或「建立對話」中，可接受的身分證件格式為何？

資料代理：

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} 是資源 ID。長度不得超過 63 個字元，且必須符合 https://google.aip.dev/122#resource-id-segments 中說明的格式。

範例：projects/1234567890/locations/us-central1/dataAgents/my-agent

建議您在建立代理程式時略過設定這個欄位，因為系統會自動推斷，並以 {parent}/dataAgents/{data_agent_id} 覆寫。

對話：

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} 是資源 ID，長度應為 63 個半形字元以下，且格式必須符合 https://google.aip.dev/122#resource-id-segments 的說明。

範例：projects/1234567890/locations/us-central1/conversations/my-conversation。

建議您在建立對話時略過設定這個欄位，因為對話式數據分析會自動識別 {parent}/conversations/{conversation_id}，然後覆寫這個欄位。

如何使用更新遮罩？

在「Update Data Agent flow」(更新資料代理程式流程) 中，updateMask 參數會採用 FieldMask 格式字串，指定要更新 dataAgent 資源中的哪些 dataAgent 欄位。updateMask 參數為必填欄位，驗證方式如下：

  • 如果 updateMask 為空值，系統會擲回 BadRequestException，且不會更新任何欄位。
  • 如果 updateMask 中的所有欄位都是有效的 dataAgent 欄位，系統只會更新這些欄位。
  • 如果同時提供有效和無效的欄位，系統會忽略無效欄位，只更新有效欄位。

如何使用 getIAMPolicy 和 setIAMPolicy 為資料代理程式設定 IAM 政策？

您可以透過 getIamPolicy 方法和 setIamPolicy 方法，將 IAM 角色指派給特定代理程式的使用者。

下列程式碼範例示範如何擷取資料代理程式的 IAM 政策：

下列程式碼範例示範如何將 IAM 指派給資料代理程式：

對話式 Analytics API 資料代理程式的記憶體功能有哪些？

  • 單一工作階段內：對話式數據分析 API 支援多輪對話，也就是說，API 可以參照當前對話的先前部分。
  • 跨多個工作階段：Conversational Analytics API 包含管理對話記錄的功能，可讓使用者跨多個工作階段進行對話。此外，也支援有狀態的代理程式，以及 Google 管理的多輪對話。
  • 長期記憶：Conversational Analytics API 資料代理程式不支援明確的長期記憶功能。

如果我重複問同一個問題，對話式數據分析 API 資料服務專員每次都會給出相同答案嗎？

  • 對話式數據分析 API 資料代理程式的自然語言回覆並非決定性，因此即使是措辭完全相同的問題，代理程式提供的自然語言答案也可能不同。
  • 資料查詢回覆：不過，如果是尋找特定資料的問題，系統產生的基礎查詢 (SQL 或 Looker 查詢) 應為確定性。假設基礎資料未變更，擷取的資料應該相同。

如何提高對話式數據分析 API 資料代理程式回覆的準確度？

如要提升資料代理程式回覆的準確度，其中一個方法是提供豐富的背景資訊。您可以透過下列方式新增背景資訊：

  • 在 Looker 的語意層中，您可以在 LookML 定義中提供脈絡資訊。如需更多資訊和範例，請參閱「在 Looker 中使用撰寫的內容引導代理程式行為」說明文件頁面。
  • 建立資料代理程式時，您可以提供系統指令，也就是使用者定義的指引，可塑造資料代理程式的行為。這項指引包括特定業務邏輯、回覆格式或資料呈現方式。您也可以提供「黃金查詢」，也就是與正確 SQL 或 Looker 查詢配對的自然語言問題範例。如要進一步瞭解系統指令，請參閱「使用撰寫的內容引導代理程式行為」說明文件頁面。

如需提問訣竅，請參閱「運用有效的提問技巧」頁面，瞭解如何提出問題，以獲得更有效率且準確的回覆。

我可以將對話式數據分析 API 與第三方應用程式整合嗎？

將對話式數據分析 API 整合至第三方應用程式後，使用者就能直接在日常使用的工具中與資料互動。

與 geminidataanalytics.googleapis.com API 端點互動的任何第三方應用程式，都必須能夠將使用者訊息從應用程式傳送至代理程式，並顯示回覆。

如要建構整合功能，請參閱對話式數據分析快速入門存放區的範例或程式庫。您也可以造訪 Google 開發人員論壇，搜尋其他使用者的範例。

Conversational Analytics API 的費用為何？

Conversational Analytics API 處於預先發布階段，Google 不會對預先發布的產品收費。日後如有任何價格變動，我們會提前通知。

Conversational Analytics API 支援哪些資料來源？

Conversational Analytics API 支援下列資料來源：

  • BigQuery
  • Looker 探索
  • Looker Studio

您也可以透過 BigQuery 連線至 SAP 和 Salesforce 等來源，並透過 Looker Studio 連線至 CSV 檔案和 Google 試算表。

Conversational Analytics API 有哪些已知限制？

如要進一步瞭解 Conversational Analytics API 的已知限制，請參閱「Conversational Analytics API 已知限制」說明文件頁面。

專案有哪些配額限制？ Google Cloud

專案選取或位置沒有限制。 Google Cloud 您可以建立資料代理程式，查詢屬於任何專案或區域的支援資料來源。

Conversational Analytics API 是否支援資料區域規劃功能？

由於 Conversational Analytics API 尚未支援資料落地 (DRZ) 或服務控制範圍 (VPC-SC)，因此您還無法在特定地理區域中代管代理程式。不支援資料區域規劃功能。

Conversational Analytics API 是否支援英文以外的語言？

Conversational Analytics API 目前僅正式支援英文。雖然基礎 Gemini 模型支援多種語言，且部分使用者表示以非英文查詢時也能順利運作，但 Conversational Analytics API 官方僅支援英文。