Editing Troubleshooting of Google Vertex AI Search in Mandarin (section)

== 問題 ==

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

'''解決方式：'''
建立應用程式時，需啟用「[https://cloud.google.com/generative-ai-app-builder/docs/about-advanced-features?_gl=1*3htbzk*_ga*ODY1NjExNjI5LjE3MzUyMDY5NDM.*_ga_WH2QY8WWF5*MTczNTYyODg5MS40LjEuMTczNTYyOTQ5Ny4xMS4wLjA. Enterprise 版功能]」

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

'''問題描述'''：當嘗試使用 Google Vertex AI API 取得搜尋結果時<ref>[https://cloud.google.com/generative-ai-app-builder/docs/preview-search-results 取得搜尋結果 | Vertex AI Agent Builder | Google Cloud]</ref>，發生以下錯誤：

<pre>
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",
}'
</pre>

遇到錯誤
<pre>
{
  "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."
    }
  ]
}
</pre>

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

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


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

'''錯誤訊息:'''
儲存網站規則時，出現以下錯誤訊息：
<pre>
Failed to save sites
Requested entity already exists
Tracking number: <mix of English and numeric characters>
</pre>

'''問題原因：'''
在「Specify URL patterns to index」中同時存在衝突的 URL 模式：
<pre>
example.com
</pre>
和
<pre>
*.example.com/*
</pre>

這兩種模式相互衝突，導致系統將它們視為重複的實體。詳細的連結規則在正式文件中有提及
<pre>
你可以使用以下列出的操作
整個網站：www.mysite.com/*
網站的部分區域：www.mysite.com/faq/*
整個網域：*.mysite.com/*
引號表示精確匹配："www.mysite.com/faq"
沒有引號的網站將匹配指定地址後的任何路徑：
www.mysite.com/faq → www.mysite.com/faq*
</pre>


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

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

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

<pre>
{
  "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",
    ...
  }
}
</pre>

'''根本原因：'''

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

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

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

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

選項二：提高額度限制

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

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

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


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

'''錯誤:'''
使用 Vertex AI Search API 時，遇到 404 錯誤：
<pre>
{
  "error": {
    "code": 404,
    "message": "Engine projects/<YOUR_PROJECT_ID>/locations/global/collections/default_collection/engines/<YOUR_APP_ID> not found.",
    "status": "NOT_FOUND"
  }
}
</pre>

解決方案：

1. 確認正確的 APP ID (引擎 ID)：
開啟瀏覽器，將網址中的 {{kbd | key=<nowiki><YOUR_APP_ID></nowiki>}} 替換為實際的 APP ID：
<pre>
https://console.cloud.google.com/gen-app-builder/locations/global/engines/<YOUR_APP_ID>/overview
</pre>

2. 更新程式碼中的 app_id：

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

<pre>
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"}}'
</pre>

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

「[https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-vertex-ai-search?hl=zh-TW 利用 Vertex AI Search 建立基準]」時遇到錯誤：

'''錯誤訊息：'''
<pre>
路徑必須採用下列格式：
projects/{project_id}/locations/{location}/collections/{collection_name}/dataStores/{datastore_name}
</pre>

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

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

範例 curl 指令：
<pre>
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"}}'
</pre>

從 URL 中擷取參數：

{{kbd | key=<nowiki>/projects/987654321000/locations/global/collections/default_collection/engines/vertex-search_123/</nowiki>}}

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