設定進階自動完成功能

預先發布版

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本頁面說明 AI 應用程式的進階自動完成功能。

與基本自動完成功能相同，進階自動完成功能會根據查詢的前幾個字元，產生查詢建議。

閱讀本頁面之前，請先熟悉 AI 應用程式的基本自動完成功能。請參閱「設定自動完成功能」。

進階自動完成功能的主要特色

進階自動完成功能與基本自動完成功能的主要差異如下：

• 混合搜尋：進階自動完成功能可與混合搜尋應用程式搭配使用，這類應用程式會連結至多個資料儲存庫。

• 存取權控管：進階自動完成功能會遵守存取權控管規定。(存取控制也稱為 ACL，即存取控制清單)。進階自動完成功能只會建議與搜尋者可存取文件相關的搜尋查詢。如要瞭解存取控管機制，請參閱「使用資料來源存取控管機制」。

• 語言提升：進階自動完成功能可設定為提升一或多種語言的建議。舉例來說，如果瀏覽器語言是荷蘭文，系統可能會優先顯示該語言的自動完成建議。詳情請參閱「傳送自動完成要求並提升語言」。

• 近期查詢：透過進階自動完成功能，使用者可以根據輸入的字首，取得與其相符的近期查詢內容，而非一般的自動完成查詢建議。詳情請參閱「傳送自動完成要求並傳回最近的查詢」。

事前準備

開始使用進階自動完成功能前，請先完成下列步驟：

• 查看並視需要編輯應用程式的自動完成設定。請參閱「更新自動完成設定」。

• 如果資料儲存庫較小，請將「啟用自動完成功能」設為「立即」。建議您這麼做，是因為小型資料存放區可能沒有足夠的資料，無法提供準確的建議。

• 如果資料儲存空間含有任何個人識別資訊 (PII)，或是使用搜尋記錄或使用者事件查詢建議模型，請參閱「防範 PII 外洩」，並設定可能需要的資料遺失防護 (DLP) 安全措施，防止 PII 外洩。

傳送自動完成要求

以下說明如何使用 completionConfig.completeQuery 方法傳送進階自動完成要求。

REST

如要使用 API 傳送自動完成要求，請按照下列步驟操作：

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中，找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

1. 呼叫 completionConfig.completeQuery 方法。

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
   -d '{
         "query":"QUERY_STRING"
       }'
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案 ID。

   • APP_ID：Vertex AI Search 應用程式的 ID。

   • QUERY_STRING：用於擷取建議的自動完成輸入內容。

傳送附帶語言提升功能的自動完成要求

您可以根據語言代碼提升或隱藏自動完成建議，例如提高或降低某些語言的自動完成建議顯示機率。

增強值必須介於 -1 和 1 之間。設定負數會「埋藏」該語言的自動完成建議，正數則會提升該語言。

使用 BCP 47 定義的雙字母語言標記，例如 en、fr、hi 和 zh。

REST

如要傳送包含語言提升值的自動完成要求，請按照下列步驟操作：

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中，找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

1. 呼叫 completionConfig.completeQuery 方法。

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
   -d '{
         "query":"QUERY_STRING",
         "boostSpec": {
            "conditionBoostSpecs": [{
              "condition": "(langCode: ANY(LANG_CODE))",
              "boost": BOOST_VALUE
            }]
         }
       }'
   
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案 ID。

   • APP_ID：Vertex AI Search 應用程式的 ID。

   • QUERY_STRING：用於擷取建議的預先輸入文字。

   • LANG_CODE：一或多種語言的雙字母代碼，以逸出引號括住。例如，\"fr\", \"es\" 可將加成值套用至西班牙文和法文。

   • BOOST_VALUE：介於 -1 和 1 之間的浮點數。如果值為負數，系統會降低該語言的自動建議優先順序 (建議會顯示在建議清單的較下方)。如果值為正數，系統會優先顯示建議 (在清單中顯示在較上方的位置)。

   範例指令

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/completionConfig:completeQuery" \
   -d '{
        "query": { "text": "Co"}
        "boostSpec": {
           "conditionBoostSpecs": [{
             "condition": "(langCode: ANY(\"es\", \"fr\"))",
             "boost": 0.75 }, {
             "condition": "(langCode: ANY(\"en\"))",
             "boost": -1
           }]
         }
       }'
    

   在這個範例中，如果查詢 Co 的自動完成建議是法文或西班牙文，就會獲得提升 (在自動建議清單中排名較高)，如果是英文，就會遭到埋沒 (在自動建議清單中排名較低)。

傳送自動完成要求並傳回近期查詢

傳回使用者最近查詢的清單，做為建議，這些查詢會與要求中的查詢前置字元相符。

系統會列出相符的查詢建議，並依時間排序，最近的查詢會先顯示。如要使用近期搜尋記錄，必須提供使用者虛擬 ID。

範例

員工正在查詢公司內部網路網站，瞭解休假相關資訊。員工執行了下列查詢 (依時間排序，從最近到最舊)：

PTO、Vacation blackout periods、How much vacation time do I have?、Time off、Vacation policy、covering a vacant position during absences 和 Can I take unpaid time off?。

現在，員工在搜尋框中輸入 vac 時，自動完成建議如下：

• Vacation blackout periods
• How much vacation time do I have?
• Vacation policy
• Covering a vacant position during absences

程序

如要傳送自動完成要求，並傳回使用者最近的查詢，請按照下列步驟操作：

REST

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中，找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

1. 呼叫 completionConfig.completeQuery 方法。

   
   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
   -d '{
         "query":"QUERY_STRING",
         "suggestionTypes": ["RECENT_SEARCH"],
         "userPseudoId": "USER_PSEUDO_ID"
       }'
   
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案 ID。

   • APP_ID：Vertex AI Search 應用程式的 ID。

   • QUERY_STRING：用於擷取建議的預先輸入文字。

   • USER_PSEUDO_ID：使用者的假名 ID。您可以在這個欄位中使用 HTTP Cookie，這類 Cookie 會在單一裝置上識別訪客。請勿為多位使用者將這個欄位設為相同 ID。這樣一來，系統就會合併兩者的查詢記錄。請勿在這個欄位中輸入個人識別資訊 (PII)。

   指令和結果範例

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/completionConfig:completeQuery" \
   -d '{
         "query": "hol",
         "suggestionTypes": ["RECENT_SEARCH"],
         "userPseudoId": "test_user"
       }'
   
   {
     "recentSearchSuggestions": [
       {
         "suggestion": "holiday readiness",
         "recentSearchTime": "2024-11-19T18:27:07.261698Z"
       },
       {
         "suggestion": "holiday freeze",
         "recentSearchTime": "2024-11-19T18:25:45.744021Z"
       },
       {
         "suggestion": "holiday",
         "recentSearchTime": "2024-11-19T18:20:08.916884Z"
       }
     ]
   }
   

注意： 如果將 suggestionTypes 指定為 RECENT_SEARCH，系統會忽略 curl 指令中的任何 boostSpec、queryModel 或 includeTailSuggestions 參數。

使用自動完成拒絕清單

拒絕清單可避免自動完成建議顯示特定字詞。

雖然進階自動完成功能是在應用程式層級，但拒絕清單是在資料儲存庫層級。如果您的應用程式是混合式搜尋應用程式，這點就非常重要。請為連結至應用程式的每個資料儲存庫建立拒絕清單。

如要瞭解如何建立及使用拒絕清單，請參閱「使用自動完成拒絕清單」。

使用匯入的自動完成建議清單

您可以選擇提供自己的自動完成建議清單，而非使用自動完成資料模型產生的自動完成建議。

如要瞭解如何匯入清單，請參閱「使用匯入的自動完成建議清單」。