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

在 Azure AI 搜尋中，typeahead 或 “search-as-you-type” 是使用 建議工具啟用。 建議工具是索引中的組態，指定應該使用哪些欄位來填入自動完成和建議的相符專案。 這些欄位會額外進行 Token 化，產生前置詞序列以支援部分字詞比對功能。 例如，包含city值為 Seattle 之字段的建議工具具有支援 typeahead 的前置詞組合，包括 sea、seatt 和 seattl。

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

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

Typeahead 可以使用 自動完成，以完成整個字詞查詢的部分輸入，或 邀請點擊到特定相符項目的建議 。 自動完成會產生查詢。 建議會產生相符文件。

以下螢幕擷取畫面說明這兩者。 自動完成預期有一個潛在的字詞，完成 tw 與 in。 建議是迷你搜尋結果，其中類似的 hotel name 欄位代表索引中的相符旅館搜尋檔。 若使用建議功能，您可以呈現任何提供描述性資訊的欄位。

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

• 將建議工具新增至搜尋索引定義。 本文的其餘部分著重於建立建議工具。

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

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

如何建立建議工具

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

• 僅限使用字串欄位。

• 如果字串欄位是複雜類型的一部分（例如 Address 中的 City 欄位），請在欄位路徑中包含父代： "Address/City" （REST、C#和 Python），或 ["Address"]["City"] （JavaScript）。

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

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

選擇欄位

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

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

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

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

選擇分析器

您選擇的分析器會決定欄位如何權杖化和加上前置詞。 例如，對於上下文相關等連字元字串，使用語言分析器會導致這些令牌組合：內容、敏感性、上下文相關。 如果您使用標準 Lucene 分析器，連字號字串就不會存在。

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

使用自定義分析器或內建分析器的欄位，明確不允許使用標準 Lucene，以防止結果不佳。

注意

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

使用 Azure 入口網站 建立

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

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。 如果在欄位中指定分析器，它必須是列在 LexicalAnalyzerName 結構上之具名語彙分析器（而非自定義分析器）。 最佳做法是只指定將內容提供給預期且適當回應的欄位，無論是搜尋列或下拉式清單中的已完成字串。 旅館名稱是很好的候選項目，因為相當精確。 描述和註解等詳細資訊欄位則太過密集。 同樣地，重複的欄位效果較差，例如類別和標籤。 在範例中，我們無論如何都包含 類別 ，以示範您可以包含多個字段。
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=2024-07-01
{
  "search": "minecraf",
  "suggesterName": "sg"
}

範例指令碼

若要瞭解如何在用戶端應用程式中使用 開放原始碼 建議套件進行部分字詞完成，請參閱探索 .NET 搜尋程序代碼。

後續步驟

深入瞭解要求制定。

在用戶端應用程式中新增自動完成和搜尋建議