Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

對話式數據分析 API 可以變更或刪除我的資料嗎？

對話式數據分析 API 內建防護措施，可防止資料遭到竄改或刪除。

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

BigQuery：API 會封鎖資料定義語言 (DDL) 和資料操縱語言 (DML) 陳述式。具體來說，系統會對產生的 SQL 執行測試，且只允許 SELECT 類型的查詢。
Looker：API 會使用 run_inline_query 等方法與 Looker 互動，但這些方法僅限於選取、篩選和限制等讀取作業。這些方法不支援 DDL 或 DML 作業，也不包含刪除或捨棄作業。
Data Studio (適用於 CSV 和 Google 試算表)：Data Studio 會使用結構化格式定義及擷取資料，以製作視覺化內容和報表。以這種方法執行的任何查詢都是唯讀，且不支援資料突變。
資料庫：系統只允許 SELECT 類型的查詢。為避免資料遭到變更或刪除，請確保與「對話式數據分析」API 互動的服務帳戶或使用者，對資料庫擁有唯讀權限。

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

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

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

錯誤：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 設定。
錯誤：500 Internal Server Error當具有「使用者」角色的 Looker 使用者嘗試與資料代理程式對話時。
- 可能原因：Looker 使用者可能沒有足夠的權限。
- 疑難排解：請確認使用者在 IAM 和 Looker 中都已獲派適當角色，才能與資料代理程式對話。詳情請參閱本常見問題中的「使用對話式數據分析 API 的 Looker 需求為何？」一節。

為什麼串流回應時會看到 503 或 500 錯誤？

如果您使用基本的 HTTP 或 REST 用戶端 (例如 Python requests 程式庫) 呼叫串流 :chat 端點，API 可能會傳回一般錯誤訊息，例如 503 Connection reset by peer 或 500 Internal error。

發生這類一般錯誤的原因是，串流 API 會在串流開啟後立即傳送 HTTP 200 OK 標頭。如果資料代理程式在串流期間發生嚴重錯誤 (例如長時間執行的查詢逾時或權限突然遭拒)，就會終止串流，並在 HTTP/2 預告片中加入特定錯誤代碼。標準 HTTP 或 REST 用戶端無法剖析這些尾隨標頭，反而會將突然終止視為通訊端異常終止。

如要處理串流期間發生的錯誤，強烈建議使用官方 Google Cloud 用戶端程式庫 (SDK)，例如 Python SDK。這些以 gRPC 為基礎的 SDK 會剖析 HTTP/2 尾部，並傳回特定錯誤代碼 (例如 DEADLINE_EXCEEDED 或 PERMISSION_DENIED)，而非一般網路錯誤。

使用對話式數據分析 API 時，Looker 有哪些需求？

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

Google Cloud IAM 角色：
- 您必須在 Google Cloud 專案中具備足夠的 IAM 角色，才能與 geminidataanalytics.googleapis.com API 互動。IAM 角色設定錯誤通常會導致 PERMISSION_DENIED 錯誤。
- 視動作而定，可能需要特定角色，但某些作業可能需要「專案編輯者」等一般角色。
Looker 權限和角色：
- 模型層級權限：如要使用對話式數據分析和對話式數據分析 API，Looker 使用者必須獲派包含 gemini_in_looker 權限的Looker 角色，才能與模型互動。

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

此外，您的 Looker 執行個體必須符合特定條件：

如要在 Data Studio Pro 中使用對話式數據分析 API，Pro 訂閱方案必須位於 VPC-SC 範圍外。

使用對話式數據分析 API 時，資料庫有哪些要求？

如要搭配使用對話式數據分析 API 與 AlloyDB for PostgreSQL、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 等資料庫，請務必確保已啟用適當的 IAM 驗證機制：

Google Cloud IAM 角色：
- 服務帳戶或使用者必須具備必要的 IAM 角色，才能連線至特定資料庫並查詢。這通常是指具有資料庫讀取權的角色。
啟用 API：
- 確認專案已啟用 Cloud AI Companion API。 Google Cloud

如要進一步瞭解如何啟用 IAM 驗證，請參閱各資料庫的說明文件：

AlloyDB：管理 IAM 驗證。
Spanner：向 Spanner 進行驗證。
MySQL 適用的 Cloud SQL：IAM 驗證。
PostgreSQL 適用的 Cloud SQL：IAM 驗證。

如何從 Data QnA API 遷移至對話式數據分析 API？

如果您使用舊版實驗性 Data QnA API (dataqna.googleapis.com)，請參閱遷移指南，瞭解如何遷移至對話式數據分析 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。

使用對話式數據分析 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 指派給資料代理程式：

對話式數據分析 API 資料代理的記憶功能有哪些？

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

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

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

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

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

在 Looker 的語意層中，您可以在 LookML 定義中提供脈絡資訊。如需詳細資訊和範例，請參閱「在 Looker 中使用撰寫的內容引導代理程式行為」說明文件頁面。
在 AlloyDB for PostgreSQL、MySQL 適用的 Cloud SQL、PostgreSQL 適用的 Cloud SQL 和 Spanner 資料來源中，您可以新增資料表、資料欄、結構描述說明和限制，為資料和資料解讀方式提供指引，藉此提供背景資訊。
建立資料代理時，您可以提供系統指令、經過驗證的查詢和進階脈絡：
- 系統指令：使用者定義的指引，可決定資料代理程式的行為。這類指引包括業務專屬邏輯、回覆格式或資料呈現方式。
- 您可以提供已驗證的查詢 (視資料來源而定，也稱為黃金查詢)，也就是與正確 SQL 或 Looker 查詢配對的自然語言問題範例。
- 對於 AlloyDB、MySQL 適用的 Cloud SQL、PostgreSQL 適用的 Cloud SQL 和 Spanner 資料來源，您可以提供進階脈絡，協助最佳化代理程式的資料理解和準確度。
詳情請參閱「使用撰寫的內容引導代理程式行為」。

如要瞭解如何提問，才能獲得更有效率且準確的回覆，請參閱「運用有效的提問技巧」頁面。

如何安全檢查及處理代理生成的 Python 程式碼？

如果已啟用 Python 進階分析功能，資料代理程式可能會傳回 Python 程式碼。資料代理傳回的 Python 程式碼，會在 Google 管理的安全沙箱中執行。在本地或其他未經驗證的環境中執行這段程式碼，會規避沙箱的安全性防護措施，並可能導致系統面臨安全性風險，例如執行惡意程式碼。

如要安全檢查及處理代理程式生成的 Python 程式碼，請遵守下列規範：

請先手動檢查產生的程式碼，再執行。找出可疑模式，例如非預期的網路要求 (例如 socket、requests 或 urllib)、系統層級指令 (例如 os.system 或 subprocess)，或是經過大量模糊處理的字串常值和變數。
請勿直接在本機或正式環境中執行未經驗證的程式碼。使用安全且獨立的沙箱 (例如 Colaboratory 筆記本、暫時性 Docker 容器或虛擬機器)，這類沙箱無法存取機密憑證、內部網路或本機檔案系統。
盡可能在執行程式碼前，先對程式碼執行靜態分析工具或 Linter，標記潛在不安全的操作或已知的惡意模式。

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

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

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

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

對話式數據分析 API 的費用是多少？

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

對話式數據分析 API 支援哪些資料來源？

對話式數據分析 API 支援下列資料來源：

BigQuery
Looker 探索
數據分析
AlloyDB for PostgreSQL
Spanner 適用的 GoogleSQL
Cloud SQL 和 PostgreSQL 適用的 Cloud SQL

您也可以透過 BigQuery 連結 SAP 和 Salesforce 等來源，以及透過數據分析連結 CSV 和 Google 試算表。

對話式數據分析 API 有哪些已知限制？

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

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

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

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

由於 Conversational Analytics API 尚不支援資料落地 (DRZ)，因此您目前無法在特定地理區域中代管代理程式。不支援資料區域規劃功能。

對話式數據分析 API 是否支援英文以外的語言？

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