設定自動完成功能

本頁說明 Vertex AI Search 的基本自動完成功能。自動完成功能會根據查詢的前幾個字元，生成查詢建議。

注意：

如要瞭解媒體搜尋應用程式的即時搜尋功能，請參閱「 取得媒體應用程式的即時搜尋結果」。

如要搭配連結至多個資料儲存庫的搜尋應用程式使用自動完成功能(混合搜尋)，或使用設有存取權控管的文件，或在自動完成功能中提升特定語言的優先順序，請參閱「設定進階自動完成功能」。

自動完成功能產生的建議會因搜尋應用程式使用的資料類型而異：

• 結構化和非結構化資料。根據預設，自動完成功能會根據資料儲存庫中的文件內容生成建議。匯入文件後，自動完成功能預設不會立即生成建議，通常要過幾天，系統才會收集到足夠的優質資料。如果您透過 API 提出自動完成要求，自動完成功能會根據搜尋記錄或使用者事件產生建議。

• 網站資料。根據預設，自動完成功能會根據搜尋記錄生成建議。自動完成功能需要實際搜尋流量。搜尋流量開始後，自動完成功能需要一到兩天才能產生建議。使用實驗性的進階文件資料模型，即可從公開網站的網頁檢索資料產生建議。

• 醫療照護資料。根據預設，系統會使用標準醫療資料來源，為醫療照護資料儲存庫產生自動完成建議。

查詢建議模型會決定自動完成功能用來產生建議的資料類型。查詢建議模型有四種：

• 文件。文件模型會根據使用者匯入的文件生成建議。這個模型不適用於網站資料或醫療保健資料。

• 可完成的欄位。可填寫欄位模型會建議直接從結構化資料欄位擷取的文字。只有以 completable 註解的欄位會用於自動完成建議。這個模型僅適用於結構化資料。

• 搜尋記錄。搜尋記錄模型會根據 SearchService.search API 呼叫記錄生成建議。如果 servingConfigs.search 方法沒有可用流量，請勿使用這個模型。這個模型不適用於醫療保健資料。

• 使用者事件。使用者事件模型會根據使用者匯入的 search 類型事件產生建議。這個模型不適用於醫療保健資料。

系統會使用 dataStores.completeQuery 方法傳送 Autocomplete 要求。

或者，如果不想使用查詢建議模型，可以改用「匯入的建議」，根據匯入的建議清單提供自動完成建議。詳情請參閱「使用匯入的自動完成建議清單」。

根據資料類型提供的模型類型

下表列出各資料類型適用的查詢建議模型類型。

查詢建議模型	資料來源	網站 資料	結構化資料	非結構化資料
文件	已匯入		✔* (預設)	✔ (預設)
可完成的欄位	已匯入		✔
搜尋記錄	自動收集	✔ (預設)	✔	✔
User events	匯入或由小工具自動收集	✔ <0x0	✔ <0x0	✔ <0x0
網路檢索內容	從您指定的公開網站內容檢索	✔^†

*：文件結構定義必須包含 title 或 description 欄位，或必須有指定為 title 或 description 鍵屬性的欄位。請參閱「更新結構化資料的結構定義」。

^†：只有在啟用自動完成功能的實驗性進階文件資料模型時，才能將網路檢索內容做為資料來源。請參閱進階文件資料模型。

如果不想使用資料類型的預設模型，可以在傳送自動完成要求時指定其他模型。系統會使用 dataStores.completeQuery 方法傳送自動完成要求。詳情請參閱API 指示：傳送自動完成要求來選擇其他模型。

自動完成功能

Vertex AI Search 支援下列自動完成功能，可在搜尋期間顯示最實用的預測結果：

功能	說明	範例或詳細資訊
修正錯字	修正錯別字。	Milc → Milk。
移除不安全的字詞	採用 Google 安全搜尋技術。 移除不當查詢。 支援英文 (en)、法文 (fr)、德文 (de)、義大利文 (it)、波蘭文 (pl)、葡萄牙文 (pt)、俄文 (ru)、西班牙文 (es) 和烏克蘭文 (uk)。	令人反感的文字，例如色情、煽情、粗俗、暴力。
禁止顯示基本個人識別資訊 (PII)	Vertex AI Search 採用 Sensitive Data Protection 技術，盡可能避免顯示電話號碼和電子郵件地址等基本類型的 PII。	如果資料儲存庫中有電子郵件地址 [e-mail]，使用者在搜尋列中輸入 jef 時，Vertex AI Search 不會將電子郵件地址做為自動完成建議傳回。 為更徹底防範 PII 外洩，Google 建議您除了 Vertex AI Search 提供的偵測器外，也套用自己的資料遺失防護 (DLP) 解決方案。詳情請參閱「防範 PII 外洩」。
拒絕清單	移除拒絕清單中的字詞。	詳情請參閱「使用自動完成拒絕清單」。
簡化字詞	採用 AI 驅動的語意理解技術。 如果兩個字詞幾乎相同，系統會比對任一字詞，但只會建議較熱門的字詞。	Shoes for Women、Womens Shoes 和 Womans Shoes 會經過重複資料刪除程序，並只建議最熱門的項目。
尾碼比對建議	不適用於美國和歐盟多區域。 選用設定。 如果整個查詢沒有自動完成相符項目，請只針對查詢的尾字建議相符項目。 不適用於醫療保健搜尋。	詳情請參閱「尾部比對建議」。

尾碼比對建議

系統會根據查詢字串中最後一個字詞的完全前置字串比對結果，提供尾部比對建議。

舉例來說，假設在自動完成要求中傳送了「songs with he」查詢。啟用尾碼比對後，自動完成功能可能會發現完整前置字串「songs with he」沒有任何相符項目。不過，查詢中的最後一個字詞「he」與「hello world」和「hello kitty」完全相符。在這種情況下，系統會傳回「含有 hello world 的歌曲」和「含有 hello kitty 的歌曲」建議，因為沒有完全相符的建議。

這項功能可減少空白建議結果，並增加建議的多樣性，因此在資料來源 (使用者事件計數、搜尋記錄和文件主題涵蓋範圍) 有限的情況下特別實用。不過，啟用尾部比對建議可能會降低建議的整體品質。由於尾碼相符只會比對前置字串的尾字，因此系統傳回的部分建議可能不合理。舉例來說，如果查詢「有 he 的歌曲」，系統可能會建議「有 helpers guides 的歌曲」這類尾部相符的項目。

只有在下列情況下，系統才會傳回尾部相符建議：

1. include_tail_suggestions 會在 dataStores.completeQuery 要求中設為 true。

2. 找不到與查詢相符的完整前置字元建議。

防範個人識別資訊外洩

PII 的定義很廣泛，而且難以偵測。因此，Vertex AI Search 無法保證自動完成建議不會傳回 PII。

Vertex AI Search 會套用私密/機密資料防護檢查服務，尋找並封鎖常見的 PII 類型，避免顯示為建議。不過，如果資料存放區含有 PII，或是您使用搜尋記錄或使用者事件查詢建議模型，請查看下列內容並採取適當行動：

1. 如果您想保護的 PII 類型相當標準，例如電話號碼和電子郵件地址，請先廣泛測試應用程式的自動完成建議。Vertex AI Search 無法保證自動完成建議不會傳回 PII。

2. 如果在自動完成測試期間發現 PII 外洩，或您已知道有非標準 PII 需要保護 (例如專屬使用者 ID)，請嘗試調整自動完成門檻和內容放送參數。詳情請參閱「降低傳回含有 PII 的建議的風險」。

3. 如果調整參數仍無法有效防止 PII 外洩，請自行導入 DLP 解決方案。針對資料儲存庫、使用者事件或使用者搜尋查詢中最有可能出現的 PII 類型，自訂資料遺失防護解決方案。您可以使用 Sensitive Data Protection 或第三方 DLP 服務。採取下列任何一種做法：

   • 在資料儲存庫中匯入文件和使用者事件前，請先篩除 PII。

   • 在放送時向使用者顯示建議前，請先檢查自動完成建議，並封鎖含有任何 PII 的建議。

4. 如果您使用搜尋記錄或使用者事件模型，請在搜尋列中加入一些資訊文字，提醒使用者不要在搜尋查詢中輸入 PII。

5. 如果您對封鎖 PII 有任何疑問或遇到特定問題，請與客戶工程師 (CE) 或 Google 帳戶團隊聯絡。

為小工具開啟或關閉自動完成功能

如要開啟或關閉小工具的自動完成功能，請按照下列步驟操作：

控制台

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

   AI 應用程式

2. 按一下要編輯的應用程式名稱。

3. 按一下「Configurations」。

4. 按一下「UI」分頁標籤。

5. 切換「顯示自動完成建議」選項，即可啟用或停用小工具的自動完成建議。啟用自動完成功能後，請等待一兩天，系統才會開始顯示建議。

更新自動完成設定

如要在 UI 中設定自動完成功能，請按照下列步驟操作：

控制台

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

   AI 應用程式

2. 按一下要編輯的應用程式名稱。

3. 按一下「Configurations」。

4. 按一下「自動完成」分頁標籤。

5. 輸入或選取要更新的自動完成設定新值：

   • 建議數量上限：系統可針對查詢提供的自動完成建議數量上限。
   • 觸發的最低長度：系統提供自動完成建議前，可輸入的最低字元數。
   • 比對順序：查詢字串中的位置，自動完成功能可從該位置開始比對建議。
   • 查詢建議模型：用於產生擷取建議的查詢建議模型。您可以在 dataStores.completeQuery 中使用 queryModel 參數覆寫這項設定。

   • 啟用自動完成功能：根據預設，自動完成功能不會立即開始提供建議，而是會等到有足夠的優質資料 (通常需要幾天時間) 才會開始。如要覆寫這項預設設定，並提早開始取得自動完成建議，請選取「立即」。

     即使選取「立即」，系統也可能需要一天才能產生建議，而且在有足夠的優質資料之前，部分自動完成建議仍會缺漏或品質不佳。

   • 拒絕清單：以 JSON 檔案形式，從 Cloud Storage bucket 匯入拒絕清單。如要進一步瞭解拒絕清單的限制和規格，請參閱「使用自動完成拒絕清單」。

6. 按一下「儲存並發布」。如果引擎已啟用自動完成功能，變更會在幾分鐘內生效。

降低傳回含有 PII 的建議的風險

預先發布版

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

使用者擁有各種 PII 資訊，例如駕照和電話號碼，這些資訊應妥善保管。但使用者可能會在搜尋列中輸入任何這類 PII 資訊，以尋找與自己相關的結果。

如果您使用搜尋記錄或使用者事件模型，且使用者很可能會在搜尋列中輸入 PII，則可調整下列參數，減少 PII 外洩的風險：

• queryFrequencyThreshold：查詢必須輸入這麼多次，才會以自動完成建議的形式傳回。

• numUniqueUsersThreshold：查詢必須由這麼多不重複使用者輸入，才能做為自動完成建議傳回。搜尋使用者事件中 userPseudoId 欄位的值，會決定使用者是否為不重複。

應用實例

舉例來說，假設使用者有應保密的帳號。

如果使用搜尋記錄或使用者事件建議模型，系統會將這些帳號號碼連同使用者搜尋的所有其他字詞，用於產生建議。因此，如果使用者 A 的帳號 YZ-46789A 曾多次輸入搜尋列，而使用者 B 的帳號為 YZ-42345B，當使用者 B 在搜尋列中輸入 YZ-4 時，系統傳回的自動完成建議可能就是使用者 A 的帳號。

為降低這類外洩事件發生的機率，AI 應用程式管理員可決定：

• 將 queryFrequencyThreshold 參數的值增加至 30。 在這種情況下，不太可能經常輸入同一個帳號。不過，熱門搜尋查詢至少會以該頻率輸入。

• 將 numUniqueUsersThreshold 參數的值增加至 6。 管理員認為，在六個與不同 userPseudoId 相關聯的搜尋事件中，不太可能在搜尋列中輸入相同的帳號。

程序

自動完成功能有兩個門檻參數。 這些參數無法在 Google Cloud 控制台中使用，但可以透過 REST API 呼叫 updateCompletionConfig 方法來設定。

注意： 這些參數僅適用於搜尋記錄和使用者事件模型。

如要設定自動完成門檻，請按照下列步驟操作。視要變更的參數而定，每個步驟都是選用。

REST

1. 更新 CompletionConfig.queryFrequencyThreshold 欄位：

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: PROJECT_ID" \
     https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig?updateMask=queryFrequencyThreshold \
     -d '{
       "name": "projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig",
       "queryFrequencyThreshold": QUERY_FREQUENCY_THRESHOLD
     }'
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。

   • DATA_STORE_ID：與應用程式相關聯的資料儲存空間 ID。

   • QUERY_FREQUENCY_THRESHOLD：整數值，表示搜尋查詢必須輸入的最低次數，才能做為自動完成建議傳回。這項計數是在為期數月的滾動時間範圍內加總。預設值為 8。

   指令與結果範例

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \$ curl -X PATCH \
     -H "X-Goog-User-Project: my-project-123" \t-access-token)" \
     https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig?updateMask=queryFrequencyThreshold \
     -d '{
     "name": "projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
     "queryFrequencyThreshold": 30
     }'
     
   
   {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
     "matchingOrder": "exact-prefix",
     "maxSuggestions": 20,
     "minPrefixLength": 1,
     "queryModel": "automatic",
     "enableMode": "AUTOMATIC",
     "queryFrequencyThreshold": 30
   }
   

2. 更新 CompletionConfig.numUniqueUsersThreshold 欄位：

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: PROJECT_ID" \
     https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig?updateMask=numUniqueUsersThreshold \
     -d '{
       "name": "projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig",
       "numUniqueUsersThreshold": UNIQUE_USERS
     }'
   

   將 UNIQUE_USERS 換成整數值，代表必須輸入特定搜尋查詢的不重複使用者人數下限，該查詢才能做為自動完成建議傳回。系統會加總數月內滾動時間範圍的計數。 預設值為 3。

   指令與結果範例

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: my-project-123" \
     https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig?updateMask=numUniqueUsersThreshold \
     -d '{
     "name": "projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
       "numUniqueUsersThreshold": 6
     }'
     
   
   {
   "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
     "matchingOrder": "exact-prefix",
     "maxSuggestions": 20,
     "minPrefixLength": 1,
     "queryModel": "automatic",
     "enableMode": "AUTOMATIC",
     "numUniqueUsersThreshold": 6,
     "queryFrequencyThreshold": 30
   }
   

更新結構定義中可完成欄位的註解

如要為結構化資料結構定義中的欄位開啟自動完成功能，請按照下列步驟操作：

控制台

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

   AI 應用程式

2. 按一下要編輯的應用程式名稱。必須使用結構化資料。

3. 按一下 [Data] (資料)。

4. 按一下「結構定義」分頁標籤。

5. 按一下「編輯」，選取要標示為 completable 的結構定義欄位。

6. 按一下「儲存」，儲存更新後的欄位設定。系統大約需要一天才能生成並傳回這些建議。

傳送自動完成要求

下列範例說明如何傳送自動完成要求。

REST

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

1. 找出資料儲存庫 ID。如果已有資料商店 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面，然後點按導覽選單中的「Data Stores」(資料儲存庫)。

      前往「資料儲存庫」頁面

   2. 點按資料儲存庫的名稱。

   3. 在資料儲存庫的「資料」頁面中，取得資料儲存庫 ID。

2. 呼叫 dataStores.completeQuery 方法。

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID:completeQuery?query=QUERY_STRING"
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。

   • DATA_STORE_ID：與應用程式相關聯的資料儲存空間 ID。

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

將自動完成要求傳送至其他模型

如要使用其他查詢建議模型傳送自動完成要求，請按照下列步驟操作：

1. 找出資料儲存庫 ID。如果已有資料商店 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面，然後點按導覽選單中的「Data Stores」(資料儲存庫)。

      前往「資料儲存庫」頁面

   2. 點按資料儲存庫的名稱。

   3. 在資料儲存庫的「資料」頁面中，取得資料儲存庫 ID。

2. 呼叫 dataStores.completeQuery 方法。

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID:completeQuery?query=QUERY_STRING&query_model=QUERY_SUGGESTIONS_MODEL"
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。

   • DATA_STORE_ID：與應用程式相關聯的資料商店專屬 ID。

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

   • AUTOCOMPLETE_MODEL：自動完成資料

   • QUERY_SUGGESTIONS_MODEL：用於要求的查詢建議模型：document、document-completable、search-history 或 user-event。如為健康照護資料，請使用 healthcare-default。

C#

詳情請參閱 AI Applications C# API 參考說明文件。

如要向 AI Applications 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

using Google.Cloud.DiscoveryEngine.V1;

public sealed partial class GeneratedCompletionServiceClientSnippets
{
    /// <summary>Snippet for CompleteQuery</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void CompleteQueryRequestObject()
    {
        // Create client
        CompletionServiceClient completionServiceClient = CompletionServiceClient.Create();
        // Initialize request argument(s)
        CompleteQueryRequest request = new CompleteQueryRequest
        {
            DataStoreAsDataStoreName = DataStoreName.FromProjectLocationDataStore("[PROJECT]", "[LOCATION]", "[DATA_STORE]"),
            Query = "",
            QueryModel = "",
            UserPseudoId = "",
            IncludeTailSuggestions = false,
        };
        // Make the request
        CompleteQueryResponse response = completionServiceClient.CompleteQuery(request);
    }
}

Go

詳情請參閱 AI Applications Go API 參考說明文件。

如要向 AI Applications 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewCompletionClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.CompleteQueryRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#CompleteQueryRequest.
	}
	resp, err := c.CompleteQuery(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳情請參閱 AI Applications Java API 參考說明文件。

如要向 AI Applications 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

import com.google.cloud.discoveryengine.v1.CompleteQueryRequest;
import com.google.cloud.discoveryengine.v1.CompleteQueryResponse;
import com.google.cloud.discoveryengine.v1.CompletionServiceClient;
import com.google.cloud.discoveryengine.v1.DataStoreName;

public class SyncCompleteQuery {

  public static void main(String[] args) throws Exception {
    syncCompleteQuery();
  }

  public static void syncCompleteQuery() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (CompletionServiceClient completionServiceClient = CompletionServiceClient.create()) {
      CompleteQueryRequest request =
          CompleteQueryRequest.newBuilder()
              .setDataStore(
                  DataStoreName.ofProjectLocationDataStoreName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]")
                      .toString())
              .setQuery("query107944136")
              .setQueryModel("queryModel-184930495")
              .setUserPseudoId("userPseudoId-1155274652")
              .setIncludeTailSuggestions(true)
              .build();
      CompleteQueryResponse response = completionServiceClient.completeQuery(request);
    }
  }
}

Node.js

詳情請參閱 AI Applications Node.js API 參考說明文件。

如要向 AI Applications 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. The parent data store resource name for which the completion is
 *  performed, such as
 *  `projects/* /locations/global/collections/default_collection/dataStores/default_data_store`.
 */
// const dataStore = 'abc123'
/**
 *  Required. The typeahead input used to fetch suggestions. Maximum length is
 *  128 characters.
 */
// const query = 'abc123'
/**
 *  Specifies the autocomplete data model. This overrides any model specified
 *  in the Configuration > Autocomplete section of the Cloud console. Currently
 *  supported values:
 *  * `document` - Using suggestions generated from user-imported documents.
 *  * `search-history` - Using suggestions generated from the past history of
 *  SearchService.Search google.cloud.discoveryengine.v1.SearchService.Search 
 *  API calls. Do not use it when there is no traffic for Search API.
 *  * `user-event` - Using suggestions generated from user-imported search
 *  events.
 *  * `document-completable` - Using suggestions taken directly from
 *  user-imported document fields marked as completable.
 *  Default values:
 *  * `document` is the default model for regular dataStores.
 *  * `search-history` is the default model for site search dataStores.
 */
// const queryModel = 'abc123'
/**
 *  A unique identifier for tracking visitors. For example, this could be
 *  implemented with an HTTP cookie, which should be able to uniquely identify
 *  a visitor on a single device. This unique identifier should not change if
 *  the visitor logs in or out of the website.
 *  This field should NOT have a fixed value such as `unknown_visitor`.
 *  This should be the same identifier as
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1.UserEvent.user_pseudo_id 
 *  and
 *  SearchRequest.user_pseudo_id google.cloud.discoveryengine.v1.SearchRequest.user_pseudo_id.
 *  The field must be a UTF-8 encoded string with a length limit of 128
 *  characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 */
// const userPseudoId = 'abc123'
/**
 *  Indicates if tail suggestions should be returned if there are no
 *  suggestions that match the full query. Even if set to true, if there are
 *  suggestions that match the full query, those are returned and no
 *  tail suggestions are returned.
 */
// const includeTailSuggestions = true

// Imports the Discoveryengine library
const {CompletionServiceClient} = require('@google-cloud/discoveryengine').v1;

// Instantiates a client
const discoveryengineClient = new CompletionServiceClient();

async function callCompleteQuery() {
  // Construct request
  const request = {
    dataStore,
    query,
  };

  // Run request
  const response = await discoveryengineClient.completeQuery(request);
  console.log(response);
}

callCompleteQuery();

Python

詳情請參閱 AI Applications Python API 參考說明文件。

如要向 AI Applications 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_complete_query():
    # Create a client
    client = discoveryengine_v1.CompletionServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.CompleteQueryRequest(
        data_store="data_store_value",
        query="query_value",
    )

    # Make the request
    response = client.complete_query(request=request)

    # Handle the response
    print(response)

Ruby

詳情請參閱 AI Applications Ruby API 參考說明文件。

如要向 AI Applications 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

require "google/cloud/discovery_engine/v1"

##
# Snippet for the complete_query call in the CompletionService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::CompletionService::Client#complete_query.
#
def complete_query
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::CompletionService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::CompleteQueryRequest.new

  # Call the complete_query method.
  result = client.complete_query request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1::CompleteQueryResponse.
  p result
end

使用自動完成拒絕清單

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

以製藥公司為例，如果某種藥物已不再獲得 FDA 核准，但資料商店中的文件仍提及該藥物，使用者可能希望避免系統將該藥物顯示為建議查詢。公司可以在拒絕清單中加入該藥物名稱，避免系統建議使用。

適用的限制如下：

• 每個資料儲存庫只能有一個拒絕清單
• 上傳拒絕清單會覆寫該資料儲存庫的任何現有拒絕清單
• 每個拒絕清單最多 1000 個字詞
• 字詞不區分大小寫
• 匯入拒絕清單後，需要 1 到 2 天才會生效

每個拒絕清單項目都包含 blockPhrase 和 matchOperator：

• blockPhrase：輸入字串做為拒絕清單字詞。搜尋字詞不區分大小寫。
• matchOperator：接受下列值：
  • EXACT_MATCH：禁止系統將拒絕清單中的字詞完全比對，並顯示為建議查詢。
  • CONTAINS：禁止顯示任何含有拒絕清單字詞的建議。

以下是包含四個項目的拒絕清單範例：

{
    "entries": [
        {"blockPhrase":"Oranges","matchOperator":"CONTAINS"},
        {"blockPhrase":"bAd apples","matchOperator":"EXACT_MATCH"},
        {"blockPhrase":"Cool as A Cucumber","matchOperator":"EXACT_MATCH"},
        {"blockPhrase":"cherry pick","matchOperator":"CONTAINS"}
    ]
}

匯入拒絕清單前，請先確認已為 Discovery Engine 編輯器存取權設定必要的存取權控管。

您可以從本機 JSON 資料或 Cloud Storage 匯入拒絕清單。如要從資料儲存庫移除拒絕清單，請清除拒絕清單。

從本機 JSON 資料匯入拒絕清單

如要從含有拒絕清單的本機 JSON 檔案匯入拒絕清單，請按照下列步驟操作：

1. 以本機 JSON 檔案建立拒絕清單，格式如下。請務必為每個拒絕清單項目換行，且不得換行。

   {
       "inlineSource": {
           "entries": [
               { "blockPhrase":"TERM_1","matchOperator":"MATCH_OPERATOR_1" },
               { "blockPhrase":"TERM_2","matchOperator":"MATCH_OPERATOR_2" }
           ]
       }
   }

2. 向 suggestionDenyListEntries:import 方法提出 POST 要求，並提供 JSON 檔案名稱。

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data @DENYLIST_FILE \
     "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/suggestionDenyListEntries:import"
   

   更改下列內容：

   • DENYLIST_FILE：包含拒絕清單字詞的 JSON 檔案本機路徑。

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。

   • DATA_STORE_ID：與應用程式相關聯的資料商店 ID。

匯入拒絕清單後，系統需要 1 到 2 天的時間，才會開始篩選建議。

從 Cloud Storage 匯入拒絕清單

如要從 Cloud Storage 中的 JSON 檔案匯入拒絕清單，請按照下列步驟操作：

1. 以 JSON 檔案建立拒絕清單，格式如下，然後匯入 Cloud Storage 值區。請務必將每個拒絕清單項目放在新的一行，且不得換行。

   { "blockPhrase":"TERM_1","matchOperator":"MATCH_OPERATOR_1" }
   { "blockPhrase":"TERM_2","matchOperator":"MATCH_OPERATOR_2" }

2. 建立包含 gcsSource 物件的本機 JSON 檔案。用來指向 Cloud Storage bucket 中拒絕清單檔案的位置。

   {
       "gcsSource": {
           "inputUris": [ "DENYLIST_STORAGE_LOCATION" ]
       }
   }

   請將 DENYLIST_STORAGE_LOCATION 改成 Cloud Storage 中拒絕清單的位置。您只能輸入一個 URI。URI 必須採用下列格式： gs://BUCKET/FILE_PATH。

3. 對 suggestionDenyListEntries:import 方法發出 POST 要求，並包含 gcsSource 物件。

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data @GCS_SOURCE_FILE \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/suggestionDenyListEntries:import"
   

   更改下列內容：

   • GCS_SOURCE_FILE：包含 gcsSource 物件的檔案本機路徑，該物件指向您的拒絕清單。

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。

   • DATA_STORE_ID：與應用程式相關聯的資料商店 ID。

匯入拒絕清單後，系統需要 1 到 2 天的時間，才會開始篩選建議。

清除拒絕清單

如要從資料儲存庫清除拒絕清單，請按照下列步驟操作：

1. 對 suggestionDenyListEntries:purge 方法發出 POST 要求。

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/suggestionDenyListEntries:purge"
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。

   • DATA_STORE_ID：與應用程式相關聯的資料商店 ID。

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

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

注意： 匯入的建議會完全按照清單中的文字顯示。 不會套用拼字檢查、SafeSearch篩選器或重複內容刪除功能。

對於大多數應用程式，使用其中一個自動完成資料模型產生的建議，可獲得較佳結果。不過，在少數情況下，模型建議可能不符合您的需求，因此提供不連續的建議清單，可為使用者帶來更優質的自動完成體驗。

舉例來說，小型線上書店會匯入書名清單做為自動完成建議。當顧客開始在搜尋列中輸入內容時，自動完成建議一律會是匯入清單中的書名。當書籍清單變更時，書店會清除目前的清單，並匯入新清單。清單節錄內容可能如下所示：

{"suggestion": "Wuthering Heights", "globalScore": "0.52" },
{"suggestion": "The Time Machine", "globalScore": "0.26" },
{"suggestion": "Nicholas Nickleby", "globalScore": "0.38" },
{"suggestion": "A Little Princess", "globalScore": "0.71" },
{"suggestion": "The Scarlet Letter", "globalScore": "0.32" }

globalScore 是介於 [0, 1] 之間的浮點數，用於建議排名。或者，您也可以使用 frequency 分數，也就是大於一的整數。如果 globalScore 無法使用 (設為空值)，系統會使用 frequency 分數對建議排序。

注意： 即使在資料中，您只能提供一個分數 (globalScore 或 frequency)，在下列建立 BigQuery 資料表的步驟中，結構定義必須同時包含 globalScore 和 frequency。如果結構定義不正確，建議匯入作業就會失敗。

設定及匯入自動完成建議

如要設定及匯入 BigQuery 的自動完成建議清單，請按照下列步驟操作：

1. 建立建議清單，並載入 BigQuery 資料表。

   您至少需要以字串形式提供每項建議，以及全域分數或頻率。

   建議清單的資料表結構定義如下：

   [
     {
       "description": "The suggestion text",
       "mode": "REQUIRED",
       "name": "suggestion",
       "type": "STRING"
     },
     {
       "description": "Global score of this suggestion. Control how this suggestion would be scored and ranked. Set global score or frequency; not both.",
       "mode": "NULLABLE",
       "name": "globalScore",
       "type": "FLOAT"
     },
     {
       "description": "Frequency of this suggestion. Used to rank suggestions when the global score is not available.",
       "mode": "NULLABLE",
       "name": "frequency",
       "type": "INTEGER"
     }
   ]
   

   如需如何建立 BigQuery 資料表，以及如何將自動完成建議清單載入資料表的說明，請參閱 BigQuery 說明文件。

2. 從 BigQuery 匯入清單。

   對 completionSuggestions:import 方法發出 POST 要求，並包含 bigquerySource 物件。

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/completionSuggestions:import" \
    -d '{
         "bigquery_source": {"project_id": "PROJECT_ID_SOURCE", "dataset_id": "DATASET_ID", "table_id": "TABLE_ID"}
    }'
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。
   • DATA_STORE_ID：Vertex AI Search 資料儲存庫的 ID。
   • PROJECT_ID_SOURCE：包含要匯入資料集的專案。
   • DATASET_ID：要匯入的建議清單資料集 ID
   • TABLE_ID：要匯入的建議清單資料表 ID

   指令與結果範例

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/dataStores/my-data-store/completionSuggestions:import" \
    -d '{
   "bigquery_source": {"project_id": "my-project-123", "dataset_id": "autocomplete", "table_id": "import_suggestion2"}
   }'
       
   
   {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/operations/import-completion-suggestion-7659310803143180509",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportCompletionSuggestionsMetadata"
     }
   }
   

3. 選用：記下傳回的 name 值，並按照「取得長時間運行的作業詳細資料」中的操作說明，查看匯入作業何時完成。

4. 如果尚未為應用程式啟用自動完成功能，請按照「更新自動完成設定」程序操作。請務必將「Enable autocomplete」(啟用自動完成功能) 設為「Now」(立即啟用)。

5. 請等待幾天，讓系統完成索引作業，並提供匯入的建議。

傳送自動完成要求

如要傳送自動完成要求，並傳回匯入的建議，而非自動完成模型提供的建議，請按照下列步驟操作：

1. 按照程序將自動完成要求傳送至其他模型，並將 AUTOCOMPLETE_MODEL 設為 imported-suggestion。

   指令與結果範例

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "X-Goog-User-Project: my-project-123" \
       "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store:completeQuery?query=t&query_model=imported-suggestion"
       
   
   Response:
   {
     "querySuggestions": [
       {
         "suggestion": "The Time Machine"
       },
       {
         "suggestion": "The Scarlet Letter"
       }
     ]
   }
   

清除匯入的自動完成建議清單

匯入新的自動完成建議清單前，請先移除現有清單。

如要清除現有的自動完成建議清單，請按照下列步驟操作：

1. 對 completionSuggestions:purge 方法發出 POST 要求。

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/completionSuggestions:purge"
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案編號或 ID。

   • DATA_STORE_ID：與應用程式相關聯的資料商店 ID。

   指令與結果範例

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/dataStores/my-data-store/completionSuggestions:purge"
       
   
   {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/operations/purge-customer-imported_suggestions-3197526711414652502",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.PurgeCompletionSuggestionsMetadata",
       "createTime": "2024-06-27T17:07:09.551726728Z",
       "updateTime": "2024-06-27T17:07:09.551726728Z"
     },
     "done": true,
     "response": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.PurgeCompletionSuggestionsResponse",
       "purgeSucceeded": true
     }
   }
   

進階文件資料模型

實驗版

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

AI 應用程式提供進階的自動完成資料模型。這個資料模型會根據您匯入的文件，運用 Google 大型語言模型 (LLM) 生成高品質的自動完成建議。

這個功能為實驗性質。如要使用這項功能，請與 Google Cloud 帳戶團隊聯絡，要求將您加入許可清單。

進階文件資料模型不適用於醫療保健搜尋，也不適用於美國和歐盟多區域。