排解 Gemini Enterprise 資料儲存庫問題

您可以在這個頁面診斷及解決 Gemini Enterprise 資料儲存庫的問題。資料儲存庫無法擷取資訊時，您可以按照連貫的逐步觀測流程，獨立偵錯。

如要全面瞭解錯誤，請瞭解 Google Cloud的觀測能力工具如何搭配運作：

  • Cloud Monitoring：偵測問題何時發生。您可以使用這個頁面查看高層級趨勢、錯誤率，以及設定資料儲存庫的快訊。
  • Cloud Trace：找出問題發生的位置。您可以使用這項工具查看要求的生命週期、分析 span，並找出導致高延遲或失敗的確切步驟。
  • Cloud Logging：說明問題發生的原因。您可以透過這個頁面，查看失敗要求的確切錯誤訊息和酬載。
  • Cloud 稽核記錄：找出誰或哪項政策封鎖了動作。您可以使用這項工具追蹤安全性法規遵循、權限變更，以及可能導致存取遭拒的管理動作。

偵錯工作流程

調查資料儲存庫問題時，請按照下列工作流程依序找出並解決根本原因：

  1. 查看錯誤率趨勢
  2. 找出失敗的特定要求
  3. 查看錯誤酬載
  4. 交叉比對使用情況稽核記錄

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

    前往「Metrics Explorer」。

  2. 查看資訊主頁和資料儲存庫要求數量，並依「Tool ID」和「Engine ID」篩選。您可以判斷問題是單一錯誤，還是廣泛的系統性錯誤，需要立即處理。

找出失敗的特定要求

  1. 前往 Google Cloud 控制台的 「Trace Explorer」頁面：

    前往「Trace explorer」(Trace 探索工具)

    您也可以透過搜尋列找到這個頁面。

  2. 檢查散布圖，找出有錯誤圖示 (紅色驚嘆號) 或延遲時間異常長的追蹤記錄。
  3. 按一下追蹤記錄，即可查看其甘特圖。
  4. 查看 invoke_connector 跨度，瞭解程序停滯或失敗的位置。
  5. 此外，您也可以找到與特定要求相關聯的專屬協助權杖。如需將複雜問題提報給 Google Cloud 支援團隊，請提供這個協助權杖，加快調查速度。

查看錯誤酬載

  1. 在追蹤記錄探索工具中，按一下失敗的 Span。
  2. 在詳細資料窗格中，按一下「Show logs」(顯示記錄)。
  3. 系統會自動將您導向 Cloud Logging，並篩選出該要求。在這裡，您可以讀取原始記錄酬載，找出確切的錯誤簽章 (例如 RESOURCE_EXHAUSTED 或 PERMISSION_DENIED)。

交叉比對使用情況稽核記錄

如果記錄酬載指出 IAM 問題、缺少範圍或權限遭拒，請交叉比對 Cloud 稽核記錄：

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

    前往 Logs Explorer

  2. 查看管理記錄。確認管理員最近是否修改了動作篩選器，或撤銷必要權限。

範例：追蹤失敗的資料儲存庫要求

假設使用者提示 Gemini Enterprise 代理，要求取得 Jira 問題的狀態，但代理傳回一般失敗訊息。以下說明如何使用觀測能力工作流程找出根本原因：

  1. 查看錯誤趨勢：在尋找個別錯誤之前，請先瞭解問題的影響範圍。在 Cloud Monitoring 中開啟「Metrics Explorer」，並依 tool_id: get_issue 篩選資料儲存庫要求指標。您可能會看到 RESOURCE_EXHAUSTED 錯誤突然大幅增加。這表示問題出在系統，而非使用者一時輸入錯誤。
  2. 找出失敗的要求：開啟「Trace Explorer」，將時間篩選器設為過去一小時。在散布圖中，您會看到一組追蹤記錄，其中有紅色錯誤圖示，表示失敗。按一下其中一筆近期追蹤記錄，即可進行調查。
  3. 查看甘特圖：甘特圖會以視覺化方式呈現要求的歷程。您會看到初始代理路由的父項 Span 成功，但其下方巢狀結構中，專門指定 Jira Cloud 資料儲存庫的 invoke_connector Span 失敗。
  4. 切換至記錄：按一下失敗的 invoke_connector 追蹤記錄。在「Trace details」(Trace 詳細資料) 窗格中，按一下「Show logs」(顯示記錄)。

  5. 找出根本原因：Logs Explorer 隨即開啟，並預先篩選出確切的追蹤記錄 ID。現在，您可以檢查資料儲存庫產生的記錄酬載，找出確切錯誤：

    
"message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"

    在這則酬載錯誤訊息中，您可以看到失敗的特定工具 (get_issue)，以及明確指出執行要求的使用者無權存取目標系統中特定資源的訊息。

  6. 解決方法：請參閱「常見錯誤」一節，確認這是「缺少使用者資源存取權」錯誤。Gemini Enterprise 代理已成功連線至 Jira Cloud，但 Jira Cloud 因使用者權限不足而拒絕查詢。如要解決這個問題，請要求 Jira Cloud 管理員授予使用者特定資源的存取權。

常見錯誤

在 Cloud Logging 中查看錯誤酬載時，請著重於廣泛的錯誤特徵。大多數資料儲存庫錯誤都能自行解決。請在下方清單中找出您遇到的錯誤，判斷根本原因並加以修正。

驗證和存取錯誤

如果憑證、範圍或管理政策發生問題，導致無法存取必要資源，就會發生這些錯誤。如果遇到這些錯誤，Cloud 稽核記錄有助於偵錯近期的 IAM 變更、動作篩選器更新或撤銷的權限。

OAuth 權杖已過期或無效

  • 錯誤簽章： HTTP request failed with status code 401 / 401 Unauthorized
  • 根本原因：OAuth 權杖已過期或無效。
  • 解決方法：在 Gemini Enterprise 設定中重新授權資料儲存庫，產生新的權杖。

工具因動作篩選器而遭封鎖

  • 錯誤簽章： Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • 根本原因：管理員已使用動作篩選器封鎖該工具。
  • 解決方法：管理員必須更新動作或工具許可清單。

缺少 OAuth 範圍

  • 錯誤簽章： Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted 或 Cause: Insufficient Permission
  • 根本原因：第三方平台中的應用程式註冊缺少必要範圍。
  • 解決方法：管理員必須授予記錄中指定的確切範圍，並重新授權應用程式。

缺少 IAM 專案權限

  • 錯誤簽章： Access Denied: User does not have [permission] / mcp.tools.call permission
  • 根本原因：呼叫端或服務帳戶在目標專案中缺少必要的 Google Cloud IAM 權限。
  • 解決方法：將指定的 IAM 權限授予呼叫端。

效能和節流錯誤

當要求量超過目標 API 或服務設定的限制時，就會觸發這些錯誤。Cloud Trace 可協助您準確找出這些受限要求在失敗前停滯的時間。

第三方 API 429 節流

  • 錯誤簽章： Cause: Request has been rate limited
  • 根本原因：您傳送要求的速度超過第三方 API 允許的速度。
  • 解決方法：降低要求比率、實施輪詢策略，或向第三方供應商申請提高配額。

看不到「啟用動作」按鈕

  • 錯誤特徵：建立資料儲存庫後，控制台未顯示「啟用動作」按鈕，或該按鈕已停用。
  • 根本原因：資料儲存庫的功能有限 (例如僅限聯合搜尋、僅限擷取或僅限搜尋)，不支援動作。
  • 解決方法：這些資料儲存庫類型無法啟用動作。

顯示設定和資源錯誤

這類錯誤表示驗證可能成功，但使用者或應用程式沒有特定權限，無法查看要求的資料或與其互動。

第三方瀏覽權限限制

  • 錯誤簽章： 422 ... you do not have permission to view [Resource/Users]
  • 根本原因：第三方平台設有瀏覽權限限制或組織政策，導致無法擷取資料。
  • 解決方法：調整第三方組織成員資格，或縮小查詢範圍。

缺少使用者資源存取權

  • 錯誤簽章： permission denied: [user] does not have access to [Resource]
  • 根本原因：執行要求的使用者無權存取目標系統中的特定元件或資源。
  • 解決方法：直接在目標系統中授予使用者資源存取權。

系統和伺服器端錯誤

這類錯誤是由基礎架構問題、逾時或後端設定錯誤造成，通常無法自行解決。

第三方端點速度緩慢或超載

  • 錯誤簽章： context deadline exceeded
  • 根本原因：第三方端點速度緩慢或超載，導致 Google 端要求逾時。
  • 解決方法：重試要求。如果錯誤持續發生，請與 Google Cloud 支援團隊聯絡，要求調整逾時設定。

MCP 伺服器憑證繫結設定錯誤

  • 錯誤簽章： CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • 根本原因：伺服器端政策發生問題，MCP 伺服器憑證繫結設定有誤。客戶無法自行解決。
  • 解決方法：請與 Google Cloud 支援團隊聯絡。

取得支援

如果持續發生 context deadline exceeded 或 CredsPermissionException 錯誤，可能需要向 Google Cloud 支援團隊提交支援單。

為加快解決速度，請先從觀測工具收集下列構件，再提交支援單：

  • 從 Cloud Logging：錯誤的完整 JSON 記錄酬載。
  • Cloud Trace：與失敗要求相關聯的輔助權杖和特定 span 詳細資料 (包括追蹤記錄 ID)。
  • 使用情況稽核記錄：任何可能觸發問題的相關 IAM 修改時間戳記或政策變更。