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

發行項
11/15/2023

搜尋即用類型是改善查詢生產力的常見技術。在 Azure AI 搜尋中，透過自動完成來支援此體驗，其會根據部分輸入完成字詞或片語（使用 “microsoft 完成 ”micro“ ）。第二個用戶體驗是建議，或簡短的相符檔清單（傳回具有標識符的書名，以便連結至該書的詳細數據頁面）。自動完成和建議都是在索引中的相符專案上述詞。服務不會提供傳回零結果的查詢。

若要在 Azure AI 搜尋中實作這些體驗：

suggester將加入至索引架構
建置查詢，以在要求上呼叫自動完成或建議 API。
新增UI控制件，以處理用戶端應用程式中的搜尋即用類型互動。基於此目的，建議您使用現有的 JavaScript 連結庫。

在 Azure AI 搜尋中，自動完成的查詢和建議結果會從搜尋索引擷取，從您已向建議工具註冊的選取字段擷取。建議程式是索引的一部分，並指定哪些欄位會提供完成查詢、建議結果或兩者的內容。建立和載入索引時，會在內部建立建議項數據結構，以儲存用於比對部分查詢的前置詞。如需建議，選擇適合唯一或至少不重複的欄位，對於體驗至關重要。如需詳細資訊，請參閱建立建議工具。

本文的其餘部分著重於查詢和客戶端程序代碼。它會使用 JavaScript 和 C# 來說明重點。 REST API 範例可用來精簡呈現每個作業。如需端對端程式代碼範例，請參閱後續步驟。

設定要求

要求的元素包括其中一個搜尋即用型 API、部分查詢和建議工具。下列腳本說明使用自動完成 REST API 作為範例的要求元件。

POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2020-06-30
{
  "search": "minecraf",
  "suggesterName": "sg"
}

“suggesterName” 提供您用來完成字詞或建議的建議器感知字段。特別是針對建議，欄位清單應包含那些在比對結果之間提供清楚選擇的欄位清單。在銷售計算機遊戲的網站上，該領域可能是遊戲標題。

“search” 參數會提供部分查詢，其中字元會透過 jQuery 自動完成控件將字元饋送至查詢要求。在上述範例中，“minecraf” 是控件可能傳入的靜態圖例。

API 不會對部分查詢施加最小長度需求;它可以是一個字元。不過，jQuery 自動完成提供最小長度。至少兩或三個字元是典型的。

相符項目位於輸入字串中任何位置的字詞開頭。鑒於“快速棕色狐狸”，自動完成和建議將符合部分版本的“the”、“quick”、“brown”或“fox”，但不適用於“rown”或“ox”等部分內涵詞彙。此外，每個比對都會設定下游擴充的範圍。 “quick br” 的部分查詢會比對 “quick brown” 或 “quick bread”，但除非 “quick” 在它們之前，否則 “brown” 或 “bread” 本身都不會相符。

搜尋即用類型 API

請遵循 REST 和 .NET SDK 參考頁面的下列連結：

建構回應

自動完成和建議的回應是您對於模式的預期：自動完成會傳回字詞清單、建議會傳回字詞加上文件標識符，以便擷取檔（使用查閱檔 API 來擷取詳細數據頁面的特定檔）。

回應是由要求上的參數所塑造：

針對 [自動完成]，設定 autocompleteMode 以判斷文字完成是否發生在一或兩個字詞上。
針對 [建議]，將 $select 設定為傳回包含唯一或區分值的欄位，例如名稱和描述。避免包含重複值的欄位（例如類別或城市）。

下列其他參數同時適用於自動完成和建議，但對於建議來說可能更必要，尤其是在建議工具包含多個字段時。

參數	使用方式
searchFields	將查詢限制為特定欄位。
$filter	在結果集（`$filter=Category eq 'ActionAdventure'`）上套用比對準則。
$top	將結果限製為特定數位（`$top=5`）。

新增用戶互動程序代碼

自動填入查詢字詞或卸除相符連結清單需要使用者互動程序代碼，通常是 JavaScript，以取用來自外部來源的要求，例如自動完成或針對 Azure 搜尋服務認知索引的建議查詢。

雖然您可以原生撰寫此程序代碼，但從現有的 JavaScript 連結庫使用函式會更容易，例如下列其中一項。

自動完成小工具（jQuery UI）會出現在建議代碼段中。您可以建立搜尋方塊，然後在使用自動完成小工具的 JavaScript 函式中參考它。小工具上的屬性會設定來源（自動完成或建議函式）、採取動作之前輸入字元的最小長度，以及定位。
XDSoft 自動完成外掛程式會出現在自動完成代碼段中。
建議會出現在 JavaScript 教學課程和程式代碼範例中。

在用戶端使用這些連結庫來建立支持建議和自動完成的搜尋方塊。接著，在搜尋方塊中收集的輸入可以與搜尋服務上的建議和自動完成動作配對。

建議

本節會逐步引導您完成建議結果的實作，從搜尋方塊定義開始。它也會示範如何和腳本來叫用本文所參考的第一個 JavaScript 自動完成連結庫。

假設 jQuery UI 自動完成連結庫和 C# 中的 MVC 專案，您可以在 Index.cshtml 檔案中使用 JavaScript 來定義搜尋方塊。連結庫會透過對MVC控制器進行異步呼叫以擷取建議，將搜尋即用類型互動新增至搜尋方塊。

在 \Views\Home 資料夾下的 Index.cshtml 中，建立搜尋方塊的行可能如下所示：

<input class="searchBox" type="text" id="searchbox1" placeholder="search">

此範例是具有類別的簡單輸入文字框，用於設定樣式、JavaScript 所要參考的標識碼，以及佔位元文字。

在相同的檔案中，內嵌參考搜尋方塊的 JavaScript。下列函式會呼叫 Suggest API，此 API 會根據部分字詞輸入要求建議的相符檔：

$(function () {
    $("#searchbox1").autocomplete({
        source: "/home/suggest?highlights=false&fuzzy=false&",
        minLength: 3,
        position: {
            my: "left top",
            at: "left-23 bottom+10"
        }
    });
});

source會告知 jQuery UI 自動完成函式，以取得搜尋方塊下要顯示的專案清單。由於此專案是MVC專案，因此它會呼叫HomeController.cs中的Suggest函式，其中包含傳回查詢建議的邏輯。此函式也會傳遞一些參數來控制醒目提示、模糊比對和詞彙。自動完成 JavaScript API 會新增字詞參數。

可確保 minLength: 3 只有在搜尋方塊中至少有三個字元時，才會顯示建議。

啟用模糊比對

模糊搜尋可讓您根據接近相符專案取得結果，即使使用者拼錯搜尋方塊中的單字也一樣。編輯距離為 1，這表示使用者輸入與比對之間可能會有一個字元的最大差異。

source: "/home/suggest?highlights=false&fuzzy=true&",

啟用醒目提示

醒目提示會將字型樣式套用至對應至輸入之結果中的字元。例如，如果部分輸入為「micro」，結果會顯示為 microsoft、 microscope 等等。醒目提示是以 HighlightPreTag 和 HighlightPostTag 參數為基礎，以建議函式內嵌定義。

source: "/home/suggest?highlights=true&fuzzy=true&",

建議函式

如果您使用 C# 和 MVC 應用程式， 則 Controllers 目錄下的 HomeController.cs 檔案是您可以針對建議的結果建立類別的位置。在 .NET 中，Suggest 函式是以 SuggestAsync 方法為基礎。如需 .NET SDK 的詳細資訊，請參閱如何從 .NET 應用程式使用 Azure AI 搜尋。

方法InitSearch會將已驗證的 HTTP 索引用戶端建立至 Azure AI 搜尋服務。 SuggestOptions 類別上的屬性會決定在結果中搜尋和傳回哪些欄位、相符項目數目，以及是否使用模糊比對。

針對自動完成，模糊比對僅限於一個編輯距離（一個省略或錯放的字元）。請注意，自動完成查詢中的模糊比對有時會根據索引大小及其分區化方式產生非預期的結果。如需詳細資訊，請參閱數據分割和分區化概念。

public async Task<ActionResult> SuggestAsync(bool highlights, bool fuzzy, string term)
{
    InitSearch();

    var options = new SuggestOptions()
    {
        UseFuzzyMatching = fuzzy,
        Size = 8,
    };

    if (highlights)
    {
        options.HighlightPreTag = "<b>";
        options.HighlightPostTag = "</b>";
    }

    // Only one suggester can be specified per index.
    // The suggester for the Hotels index enables autocomplete/suggestions on the HotelName field only.
    // During indexing, HotelNames are indexed in patterns that support autocomplete and suggested results.
    var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", options).ConfigureAwait(false);

    // Convert the suggest query results to a list that can be displayed in the client.
    List<string> suggestions = suggestResult.Value.Results.Select(x => x.Text).ToList();

    // Return the list of suggestions.
    return new JsonResult(suggestions);
}

SuggestAsync 函式會採用兩個參數，以判斷叫用醒目提示是否傳回或模糊比對除了搜尋字詞輸入之外。建議的結果最多可包含八個相符專案。方法會建立 SuggestOptions 對象，然後傳遞給 Suggest API。結果接著會轉換成 JSON，以便在用戶端中顯示。

自動完成

到目前為止，搜尋 UX 程式代碼已集中在建議上。下一個程式碼區塊會使用 XDSoft jQuery UI 自動完成函式來顯示自動完成，並傳入 Azure AI 搜尋自動完成的要求。如同建議，在 C# 應用程式中，支援使用者互動的程式碼會進入 index.cshtml 。

$(function () {
    // using modified jQuery Autocomplete plugin v1.2.8 https://xdsoft.net/jqplugins/autocomplete/
    // $.autocomplete -> $.autocompleteInline
    $("#searchbox1").autocompleteInline({
        appendMethod: "replace",
        source: [
            function (text, add) {
                if (!text) {
                    return;
                }

                $.getJSON("/home/autocomplete?term=" + text, function (data) {
                    if (data && data.length > 0) {
                        currentSuggestion2 = data[0];
                        add(data);
                    }
                });
            }
        ]
    });

    // complete on TAB and clear on ESC
    $("#searchbox1").keydown(function (evt) {
        if (evt.keyCode === 9 /* TAB */ && currentSuggestion2) {
            $("#searchbox1").val(currentSuggestion2);
            return false;
        } else if (evt.keyCode === 27 /* ESC */) {
            currentSuggestion2 = "";
            $("#searchbox1").val("");
        }
    });
});

自動完成函式

自動完成是以 AutocompleteAsync 方法為基礎。如同建議，此程式碼區塊會移至 HomeController.cs 檔案中。

public async Task<ActionResult> AutoCompleteAsync(string term)
{
    InitSearch();

    // Setup the autocomplete parameters.
    var ap = new AutocompleteOptions()
    {
        Mode = AutocompleteMode.OneTermWithContext,
        Size = 6
    };
    var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap).ConfigureAwait(false);

    // Convert the autocompleteResult results to a list that can be displayed in the client.
    List<string> autocomplete = autocompleteResult.Value.Results.Select(x => x.Text).ToList();

    return new JsonResult(autocomplete);
}

自動完成函式會採用搜尋字詞輸入。方法會建立 AutoCompleteParameters 物件。結果接著會轉換成 JSON，以便在用戶端中顯示。

下一步

下列教學課程示範搜尋即用類型體驗。

將搜尋新增至網站（JavaScript）