設定進階自動完成功能

本頁面說明 Agent Search 的進階自動完成功能。

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

閱讀本頁內容前，請先熟悉 Agent Search 的基本自動完成功能。請參閱「設定自動完成功能」。

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

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

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

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

  • 語言提升：進階自動完成功能可設定為提升一或多種語言的建議。舉例來說，如果瀏覽器語言是荷蘭文，系統可能會優先顯示該語言的自動完成建議。詳情請參閱「傳送自動完成要求並提升語言」。
  • 近期查詢：使用進階自動完成功能時，使用者輸入的字母會與近期查詢內容的前置字元相符，系統會顯示這些查詢內容，而非一般的自動完成查詢建議。詳情請參閱「傳送自動完成要求並傳回最近的查詢」。

事前準備

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

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

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

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

  • 如果您打算使用近期搜尋建議 (RECENT_SEARCH)，請務必記錄搜尋使用者事件。使用 SearchService.Search 方法執行搜尋時，Agent Search 不會自動填入最近的搜尋索引。如要傳回近期查詢，您必須使用 userEvents.write 方法記錄搜尋使用者事件。請參閱「事前準備 - 近期查詢」。

傳送自動完成要求

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

REST

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

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

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

      前往「應用程式」

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

  2. 呼叫 completionConfig.completeQuery 方法。

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

    更改下列內容：

    • PROJECT_ID：專案的 ID。 Google Cloud

    • APP_ID：Agent Search 應用程式的 ID。

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

傳送自動完成要求並提升語言

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

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

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

REST

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

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

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

      前往「應用程式」

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

  2. 呼叫 completionConfig.completeQuery 方法。

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/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：專案的 ID。 Google Cloud

    • APP_ID：Agent Search 應用程式的 ID。

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

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

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

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

傳回使用者最近查詢的內容清單，做為建議。這些內容必須與要求中的查詢字首相符。

系統會依時間順序 (由新到舊) 列出相符的查詢建議。如要使用近期搜尋功能，必須提供使用者虛擬 ID。

事前準備

如要使用自動完成功能擷取最近的查詢，請先呼叫 userEvents.write 方法，將使用者搜尋記錄為搜尋使用者事件。

如果未寫入搜尋使用者事件，對 completionConfig.completeQuery 發出的 suggestionTypes: ["RECENT_SEARCH"] 要求會傳回空白的建議清單 ({})。

如要記錄搜尋使用者事件，請使用下列值，將 POST 要求傳送至 userEvents.write 方法：

  • eventType：設為 "search"
  • userPseudoId：設為使用者的專屬匿名 ID
  • engine：設為引擎的資源名稱
  • searchInfo.searchQuery：設為使用者輸入的搜尋查詢字串
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/userEvents:write" \
  -d '{
        "eventType": "search",
        "userPseudoId": "USER_PSEUDO_ID",
        "engine": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID",
        "searchInfo": {
          "searchQuery": "SEARCH_QUERY"
        }
      }'

更改下列內容：

  • PROJECT_ID：專案的 ID。 Google Cloud
  • LOCATION：應用程式或資料儲存庫的位置 (例如 global 或 us)。
  • APP_ID：Agent Search 應用程式的 ID。
  • USER_PSEUDO_ID：使用者的假名 ID。這必須與後續要求中傳遞的 userPseudoIdcompletionConfig.completeQuery 相符。
  • SEARCH_QUERY：使用者搜尋的查詢字串。

詳情請參閱「使用 userEvents.write 方法記錄即時使用者事件」。

範例

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

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。

  2. 呼叫 completionConfig.completeQuery 方法。

    
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/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：專案的 ID。 Google Cloud

    • APP_ID：Agent Search 應用程式的 ID。

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

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

使用自動完成拒絕清單

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

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

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

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

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

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