設定自動完成功能

本頁面說明 Gemini Enterprise 的基本自動完成功能。自動完成功能會根據查詢的前幾個字元生成查詢建議。

注意： 這個版本的自動完成功能不支援第三方資料儲存庫，也不支援附加多個資料儲存庫的應用程式。Google 建議改用進階自動完成。

對於結構化和非結構化資料，自動完成功能預設會根據資料儲存庫中的文件內容生成建議。匯入文件後，自動完成功能預設要等到有足夠的優質資料 (通常需要幾天)，才會開始產生建議。如果您透過 API 提出自動完成要求，自動完成功能可以根據 Google 搜尋記錄或使用者事件產生建議。

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

• 文件。文件模型會根據使用者匯入的文件生成建議。

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

• Google 搜尋記錄。Google 搜尋記錄模型會根據 SearchService.search API 呼叫記錄生成建議。如果 servingConfigs.search 方法沒有可用流量，請勿使用這個模型。

• 使用者事件。使用者事件模型會根據使用者匯入的搜尋事件產生建議。

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

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

查詢建議模型	資料來源	網站資料	結構化資料	非結構化資料
文件	由使用者匯入		✔* (預設)	✔ (預設)
可完成的欄位	由使用者匯入		✔
搜尋記錄	自動收集	✔ (預設)	✔	✔
使用者事件	由使用者匯入或由小工具自動收集	✔ <0x0	✔	✔

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

如果不想使用資料類型的預設模型，可以在傳送自動完成要求時指定其他模型。自動完成要求是透過 dataStores.completeQuery 方法傳送。詳情請參閱「API 操作說明：傳送自動完成要求以選擇其他模型」。

自動完成功能

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

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

尾部比對建議

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

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

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

只有在符合下列條件時，系統才會傳回結尾相符建議：

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

2. 沒有與查詢完全相符的前置字元建議。

防止 PII 外洩

PII 的定義廣泛，且可能難以偵測。因此，Gemini Enterprise 無法保證自動完成建議不會傳回 PII。

Gemini Enterprise 會套用Sensitive Data Protection檢查服務，尋找並封鎖常見的 PII 類型，避免這些資訊顯示為建議。不過，如果資料儲存庫含有 PII，或您使用 Google 搜尋記錄或使用者事件查詢建議模型，請詳閱下列內容並採取適當行動：

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

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

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

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

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

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

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

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

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

控制台

1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

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

3. 按一下「Configurations」。

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

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

更新自動完成設定

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

控制台

1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

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

3. 按一下「Configurations」。

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

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

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

   • 啟用自動完成：根據預設，自動完成功能必須先收集足夠的優質資料 (通常需要幾天)，才會開始提供建議。如要覆寫這項預設值，並提早開始取得自動完成建議，請選取「立即」。

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

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

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

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

預覽

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

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

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

• queryFrequencyThreshold：查詢必須輸入達這個次數，才能做為自動完成建議傳回。

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

用途範例

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

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

為降低這類外洩事件發生的可能性，Gemini Enterprise 管理員決定：

• 將 queryFrequencyThreshold 參數的值提高至 30。在這種情況下，一個帳號不太可能被輸入這麼多次。不過，熱門搜尋查詢的輸入頻率至少會達到這個次數。

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

程序

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

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

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

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 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

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

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

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

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

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

傳送自動完成要求

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

REST

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

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

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

      前往「資料儲存庫」頁面

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

   3. 在資料儲存庫的「Data」(資料) 頁面，取得資料儲存庫 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 控制台的「Gemini Enterprise」頁面，然後點按導覽選單中的「Data Stores」(資料儲存庫)。

      前往「資料儲存庫」頁面

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

   3. 在資料儲存庫的「Data」(資料) 頁面，取得資料儲存庫 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：用於擷取建議的自動完成輸入內容。

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

C#

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 C# 設定說明操作。詳情請參閱「Gemini Enterprise C# API 參考文件」。

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

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Gemini Enterprise Go API 參考文件。

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

//go:build examples

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Gemini Enterprise Java API 參考文件。

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

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱「Gemini Enterprise Node.js API 參考文件」。

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

/**
 * 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Gemini Enterprise Python API 參考文件。

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

# 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Ruby 設定說明操作。詳情請參閱「Gemini Enterprise Ruby API 參考文件」。

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

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 核准，但資料儲存庫中的文件仍有提及，他們可能不希望該藥物出現在建議查詢中。公司可以將該藥物名稱加入拒絕清單，避免系統建議該藥物。

適用的限制如下：

• 每個資料儲存庫只能有一個拒絕清單
• 上傳拒絕清單後，系統會覆寫該資料儲存庫現有的拒絕清單
• 每個拒絕清單最多 1,000 個字詞
• 字詞不區分大小寫
• 匯入拒絕清單後，需要 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 bucket。請確認每個拒絕清單項目都位於新的一行，且沒有換行符。

   { "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。

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

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

注意： 系統不會對匯入的建議進行拼字校正。不過，系統會在提供前套用下列處理程序：

• 文字正規化。建議文字會轉換為小寫、經過 Unicode 正規化、摺疊內部空白字元、將彎引號 (U+2018、U+2019) 摺疊為 ASCII 引號 (U+0027)，並移除內嵌的雙引號字元和結尾的句號。
• 篩選長度。系統會捨棄少於 3 個半形字元或超過 125 個半形字元的建議。
• 依分數匯總簡化。如果兩個以上的匯入建議正規化為相同文字 (例如 "Pixel 10 Pro Moonstone" 和 "Pixel 10 Pro moonstone"，或使用捲曲撇號的 "jobseeker’s allowance" 和使用 ASCII 撇號的 "jobseeker's allowance")，系統會將這些建議合併為單一建議，分數為輸入分數的總和。如要保留建議的原始分數，請只提交一次。
• PII 篩選。系統會篩除含有個人識別資訊的建議。
• 拒絕清單篩選。如果建議與資料儲存庫建議項目拒絕清單中的詞組相符，就會遭到篩除。

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。如果結構定義不正確，系統就無法匯入建議。

事前準備

如要匯入自動完成建議，您必須具備 Discovery Engine 管理員 IAM 角色，其中包含 discoveryengine.completionSuggestions.import 權限。

詳情請參閱「IAM 角色和權限」。

設定及匯入自動完成建議

如要設定及匯入 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：資料儲存庫的 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. 按照這項程序，將自動完成要求傳送至其他模型，並將 QUERY_SUGGESTIONS_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"
     }
   }
   

2. (選用) 記下傳回的 name 值，並按照「取得長時間執行的作業詳細資料」中的操作說明，查看清除作業何時完成。

進階文件資料模型

實驗版

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

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

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

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