在查詢中設定自動完成和建議相符項目的建議工具

在 Azure AI 搜尋服務中，透過建議工具啟用預先輸入 (自動完成) 或「在輸入期間進行搜尋」功能。 建議工具是索引中的設定，其會指定應該使用哪些欄位來填入自動完成和建議。 這些欄位會額外進行 Token 化，產生前置詞序列以支援部分字詞比對功能。 例如，建議工具若包含值為「Seattle」的城市欄位，會設有前置詞組合「sea」、「seatt」、「seatt」和「seattl」以支援預先輸入功能。

部分字詞比對可以是自動完成的查詢或建議的相符項目。 一個建議工具同時支援這兩種體驗。

Azure AI 搜尋服務中的預先輸入體驗

預先輸入可以自動完成，會完成整個字詞查詢的部分輸入，或是提供建議以邀請點選特定相符項目。 自動完成會產生查詢。 建議會產生相符文件。

以下螢幕擷取畫面說明這兩者。 自動完成會預期潛在的字詞，在「tw」後加上「in」來完成字詞。 建議是迷你搜尋結果，例如旅館名稱欄位代表索引中相符的旅館搜尋文件。 若使用建議功能，您可以呈現任何提供描述性資訊的欄位。

您可以單獨或一起使用這些功能。 為了在 Azure AI 搜尋服務中實作這些行為，需有索引和查詢元件。

• 將建議工具新增至搜尋索引定義。 本文的其餘內容著重說明建立建議工具。

• 使用其中一個後面章節所列的 API，以建議要求或自動完成要求的形式呼叫啟用建議工具的查詢。

針對字串欄位，根據每個欄位啟用在輸入期間進行搜尋。 如果您想要類似螢幕擷取畫面中所指出的體驗，可以在同一個搜尋解決方案內實作這兩種預先輸入行為。 這兩種要求都會以特定索引的文件集合為目標，並在使用者至少提供三個字元的輸入字串之後傳回回應。

如何建立建議工具

若要建立建議工具，請將建議工具新增至索引定義。 建議工具會採用一個名稱和一個欄位集合，以此為基礎啟用預先輸入體驗。 當您也定義了使用建議工具的欄位時，是建立建議工具的最佳時機。

• 僅限使用字串欄位。

• 例如，如果字串欄位屬於複雜類型的一部分 (例如地址中的城市欄位)，請在欄位路徑中包含父欄位："Address/City" (REST 和 C# 和 Python)，或 ["Address"]["City"] (JavaScript)。

• 對欄位使用預設標準 Lucene 分析器 ("analyzer": null) 或語言分析器 (例如 "analyzer": "en.Microsoft")。

如果您嘗試使用預先存在的欄位建立建議工具，API 會不允許使用此建議工具。 前置詞會在編製索引期間產生，兩個或多個字元組合中的部分字詞會與整個詞彙一起 Token 化。 假設現有的欄位已經 Token 化，如果您想將這些欄位新增至建議工具，則必須重建索引。 如需詳細資訊，請參閱如何重建 Azure AI 搜尋服務索引。

選擇欄位

雖然建議工具有多項屬性，但主要是您啟用在輸入期間進行搜尋體驗的字串欄位集合。 每個索引都有一個建議工具，因此建議工具清單必須包含組成建議和自動完成內容的所有欄位。

若有較大欄位集區可提取內容，自動完成的成效會提高，因為額外的內容會帶來較高的字詞完成可能性。

另一方面，若您的欄位可供選擇，建議會產生更好的結果。 請記得，建議是搜尋文件的 Proxy，因此挑選最能代表單一結果的欄位。 能區分多個相符項目的名稱、標題或其他唯一欄位最為適合。 如果欄位是由重複的值所組成，建議便會包含相同的結果，讓使用者不知道要選擇哪一個結果。

若要滿足這兩種在輸入期間進行搜尋的體驗，請新增自動完成功能所需的所有欄位，然後使用 select、top、filter 和 searchFields 來控制建議的結果。

選擇分析器

您選擇的分析器會決定欄位如何權杖化和加上前置詞。 例如，針對類似 "context-sensitive" 的連字號字串，使用語言分析器會產生以下權杖組合："context"、"sensitive"、"context-sensitive"。 如果您使用標準 Lucene 分析器，連字號字串就不會存在。

評估分析器時，可考慮使用分析文字 API 來深入瞭解字詞的處理方式。 建置索引之後，您可以對字串嘗試各種分析器來檢視 Token 輸出。

系統明確不允許使用自訂分析器或內建分析器的欄位 (標準 Lucene 除外)，以避免產生不良結果。

注意

如果您需要分析器條件約束的因應措施 (例如若您需要特定查詢案例的關鍵字或 ngram 分析器)，您應針對相同的內容使用兩個不同的欄位。 這樣可讓其中一個欄位使用建議工具，另一個則以自訂分析器設定加以設置。

使用入口網站建立

使用 [新增索引] 或 [匯入資料] 精靈建立索引時，您可以選擇啟用建議工具：

1. 在索引定義中，輸入建議工具的名稱。

2. 在新欄位的每個欄位定義中，選取 [建議工具] 資料行中的核取方塊。 只有字串欄位提供核取方塊。

如先前所述，選擇的分析器會影響 Token 化和前置詞。 啟用建議工具時，請考慮整個欄位定義。

使用 REST 建立

在 REST API 中，透過 [建立索引] 或 [更新索引] 新增建議工具。

{
  "name": "hotels-sample-index",
  "fields": [
    . . .
        {
            "name": "HotelName",
            "type": "Edm.String",
            "facetable": false,
            "filterable": false,
            "key": false,
            "retrievable": true,
            "searchable": true,
            "sortable": false,
            "analyzer": "en.microsoft",
            "indexAnalyzer": null,
            "searchAnalyzer": null,
            "synonymMaps": [],
            "fields": []
        },
  ],
  "suggesters": [
    {
      "name": "sg",
      "searchMode": "analyzingInfixMatching",
      "sourceFields": ["HotelName"]
    }
  ],
  "scoringProfiles": [
    . . .
  ]
}

使用 .NET 建立

使用 C# 定義 SearchSuggester 物件。 Suggesters 是 SearchIndex 物件的集合，但只能接受一個項目。 將建議工具新增至索引定義。

private static void CreateIndex(string indexName, SearchIndexClient indexClient)
{
    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);

    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);

    indexClient.CreateOrUpdateIndex(definition);
}

屬性參考

屬性	描述
NAME	在建議工具定義中指定，但也會對自動完成或建議要求呼叫。
sourceFields	在建議工具定義中指定。 索引 (建議內容的來源) 中一或多個欄位的清單。 欄位的類型必須是 Edm.String。 如果對欄位指定分析器，必須是此清單中的具名語彙分析器 (而非自訂分析器)。 最佳做法是只指定將內容提供給預期且適當回應的欄位，無論是搜尋列或下拉式清單中的已完成字串。 旅館名稱是很好的候選項目，因為相當精確。 描述和註解等詳細資訊欄位則太過密集。 同樣地，重複的欄位效果較差，例如類別和標籤。 在範例中，為了示範您可以包含多個欄位，我們仍納入「類別」。
searchMode	僅限 REST 參數，但也會顯示在入口網站上。 此參數無法用於 .NET SDK。 指出用來搜尋候選片語的策略。 目前唯一支援的模式是 analyzingInfixMatching，目前會比對字詞的開頭內容。

使用建議工具

建議工具用於查詢中。 建立建議工具之後，請呼叫下列其中一個 API，以獲得在輸入期間進行搜尋體驗：

• 建議 REST API
• 自動完成 REST API
• SuggestAsync 方法
• AutocompleteAsync 方法

在搜尋應用程式中，用戶端程式碼應使用 jQuery UI Autocomplete 之類的程式庫來收集部分查詢並提供相符項目。 如需這項工作的詳細資訊，請參閱將自動完成或建議結果新增至用戶端程式碼。

下列對自動完成 REST API 發出的呼叫說明了 API 使用方式。 此範例有兩個重點。 首先，如同所有查詢，這項作業是針對索引的文件集合執行，且查詢中包含 search 參數，在此情況下會提供部分查詢。 其次，您必須將 suggesterName 新增至要求中。 如果沒有在索引中定義建議工具，對自動完成或建議的呼叫會失敗。

POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2023-11-01
{
  "search": "minecraf",
  "suggesterName": "sg"
}

範例指令碼

• 將搜尋新增至網站 (JavaScript) 會在用戶端應用程式中使用開放原始碼建議套件，以提供部分字詞功能。

下一步

深入瞭解 requests\ 公式。

將自動完成和建議新增至用戶端程式碼