Troubleshooting of Google Vertex AI Search in Mandarin

解決 Google Vertex AI Search 及其 API 的問題

🌐 Switch language: EN, 漢字

問題

疑難排解：Vertex AI Search：資料儲存庫需啟用 Enterprise 版功能

錯誤： 建立應用程式時遇到錯誤訊息「這個應用程式目前無法使用 4 data stores are ...」 展開所有資料儲存庫清單，顯示「網站資料儲存庫只能連結至 Enterprise 版 Vertex AI Search 應用程式」

解決方式： 建立應用程式時，需啟用「Enterprise 版功能」

疑難排解：Discovery Engine 中的「SearchLite API 被封鎖」錯誤

問題描述：當嘗試使用 Google Vertex AI API 取得搜尋結果時，發生以下錯誤：

curl -X POST -H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:searchLite?key=API_KEY" \
-d '{
"servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search",
"query": "QUERY",
}'

遇到錯誤

{
  "code" : 403,
  "message" : "Requests to this API discoveryengine.googleapis.com method google.cloud.discoveryengine.v1.SearchService.SearchLite are blocked.",
  "status" : "PERMISSION_DENIED",
  "details" : [
    {
      "@type" : "type.googleapis.com/google.rpc.ErrorInfo",
      "reason" : "API_KEY_SERVICE_BLOCKED",
      "domain" : "googleapis.com",
      "metadata" : {
        "service" : "discoveryengine.googleapis.com",
        "methodName" : "google.cloud.discoveryengine.v1.SearchService.SearchLite",
        "apiName" : "discoveryengine.googleapis.com",
        "consumer" : "projects/xxx"
      }
    },
    {
      "@type" : "type.googleapis.com/google.rpc.LocalizedMessage",
      "locale" : "en-US",
      "message" : "Requests to this API discoveryengine.googleapis.com method google.cloud.discoveryengine.v1.SearchService.SearchLite are blocked."
    }
  ]
}

解決步驟：檢查 API 金鑰限制

• 確認金鑰是否限制特定 API：
  1. 前往 Google Cloud Console 的 API 金鑰管理頁面。
  2. 找到正在使用的 API 金鑰，並檢查是否限制特定 API。如果限制包含 discoveryengine.googleapis.com，請確保其設定正確。
  3. 移除不必要的限制：如果金鑰被限制在不相關的 IP 位址或應用程式，請移除這些限制。
• 啟用 Discovery Engine API
  1. 前往 Google Cloud Console 的 API 與服務頁面。
  2. 搜尋 Discovery Engine API 並確保其已啟用。

疑難排解：儲存 Data Stores 時出現「Requested Entity Already Exists」錯誤

錯誤訊息: 儲存網站規則時，出現以下錯誤訊息：

Failed to save sites
Requested entity already exists
Tracking number: <mix of English and numeric characters>

問題原因： 在「Specify URL patterns to index」中同時存在衝突的 URL 模式：

example.com

和

*.example.com/*

這兩種模式相互衝突，導致系統將它們視為重複的實體。詳細的連結規則在正式文件中有提及

你可以使用以下列出的操作
整個網站：www.mysite.com/*
網站的部分區域：www.mysite.com/faq/*
整個網域：*.mysite.com/*
引號表示精確匹配："www.mysite.com/faq"
沒有引號的網站將匹配指定地址後的任何路徑：
www.mysite.com/faq → www.mysite.com/faq*

解決方案： 只需移除其中一種模式即可解決此問題。建議保留較通用的模式 *.example.com/*，因為它已經包含了 example.com。

疑難排解：Discovery Engine 中的 "Search lite requests" 超出額度錯誤

問題描述： 當使用 Discovery Engine API 來取得搜尋結果時，發生以下錯誤：

{
  "error" : {
    "code" : 429,
    "message" : "Quota exceeded for quota metric 'Search lite requests' and limit 'Search lite requests per minute' of service 'discoveryengine.googleapis.com' for consumer 'project_number:XXX'.",
    "status" : "RESOURCE_EXHAUSTED",
    ...
  }
}

根本原因：

錯誤回應中的 metadata 已標示該額度為 100 請求／分鐘

解決步驟：解決 API 配額限制超出問題

選項一：增加請求 (request) 之間的延遲時間

1. 在程式碼中實作延遲時間，以避免 429 錯誤。60 秒 ÷ 100 個請求 = 每個請求 0.6 秒，例如：在每個請求之間添加 0.6 ~ 1 秒的暫停，以符合速率限制。
2. 根據配額和請求模式，動態調整延遲時間

選項二：提高額度限制

1. 前往 Google Cloud Console 的額度頁面並找到 "Search lite requests per minute"
2. 選擇相關配額，點擊 "EDIT QUOTAS"，並提交更高限制的申請
3. 等待 Google Cloud Support 審核批准

選項三：實作指數退避重試機制

1. 在應用程式中偵測 HTTP 429 錯誤並設置初始延遲（例如 1 秒）
2. 每次重試失敗後增加延遲時間（例如 2 秒、4 秒、8 秒等）
3. 持續重試直到請求成功或達到最大重試次數

疑難排解：Vertex AI Search: Engine 404 錯誤

錯誤: 使用 Vertex AI Search API 時，遇到 404 錯誤：

{
  "error": {
    "code": 404,
    "message": "Engine projects/<YOUR_PROJECT_ID>/locations/global/collections/default_collection/engines/<YOUR_APP_ID> not found.",
    "status": "NOT_FOUND"
  }
}

解決方案：

1. 確認正確的 APP ID (引擎 ID)： 開啟瀏覽器，將網址中的 <YOUR_APP_ID> 替換為實際的 APP ID：

https://console.cloud.google.com/gen-app-builder/locations/global/engines/<YOUR_APP_ID>/overview

2. 更新程式碼中的 app_id：

3. 驗證 API 端點：確保 curl 請求使用正確的引擎 ID：

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/<YOUR_PROJECT_ID>/locations/global/collections/default_collection/engines/<YOUR_APP_ID>/servingConfigs/default_search:search" \
-d '{"query":"<QUERY>","pageSize":10,"queryExpansionSpec":{"condition":"AUTO"},"spellCorrectionSpec":{"mode":"AUTO"},"languageCode":"zh-TW","userInfo":{"timeZone":"Asia/Taipei"}}'

疑難排解：Vertex AI Search：啟用 Grounding 遇到路徑格式錯誤

「利用 Vertex AI Search 建立基準」時遇到錯誤：

錯誤訊息：

路徑必須採用下列格式：
projects/{project_id}/locations/{location}/collections/{collection_name}/dataStores/{datastore_name}

解決方案： 如何找到正確的路徑參數：

1. 前往 https://console.cloud.google.com/gen-app-builder/engines
2. 選擇要套用的資料儲存庫
3. 點擊「整合」分頁
4. 查看「在 Cloud Shell 執行範例要求」下方的範例指令

範例 curl 指令：

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/987654321000/locations/global/collections/default_collection/engines/vertex-search_123/servingConfigs/default_search:search" \
-d '{"query":"<QUERY>","pageSize":10,"queryExpansionSpec":{"condition":"AUTO"},"spellCorrectionSpec":{"mode":"AUTO"},"languageCode":"zh-TW","userInfo":{"timeZone":"Asia/Taipei"}}'

從 URL 中擷取參數：

/projects/987654321000/locations/global/collections/default_collection/engines/vertex-search_123/

1. {project_id}：`987654321000`（`/projects/` 之後的數字）
2. {location}：`global`（`/locations/` 之後的字串） 注意：請勿輸入 GCP 伺服器的地理區域，將會遇到錯誤訊息「Invalid location in serving config: asia-east1」
3. {collection_name}：`default_collection`（`/collections/` 之後的字串）
4. {datastore_name}：在資料儲存庫總覽頁面顯示為「資料儲存庫 ID」（例如：`XXX_1234567890123`） 注意：datastore_name 在 engine URL 中找不到，需要到資料儲存庫總覽頁面查看「資料儲存庫 ID」。

相關頁面

• Customized Search Engine
• Troubleshooting of curl errors in Mandarin
• Troubleshooting of HTTP errors in Mandarin