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

發行項
10/24/2024

「輸入即搜尋」是改善查詢生產力的常見技術。在 Azure AI 搜尋中，這項體驗可透過自動完成來支援，其會根據部分輸入完成字詞或片語（例如，使用微晶片、顯微鏡、microsoft 完成 microchip、顯微鏡、microsoft 及其他任何微相符專案）。第二個使用者體驗是建議，其會產生一份相符文件的簡短清單（例如，傳回具有標識符的書名，以便連結至該書的詳細數據頁面）。自動完成和建議都取決於索引中的相符項目。服務不提供傳回零結果的自動完成查詢或建議。

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

將 suggester 新增至索引架構。
建置查詢，以在要求上呼叫自動完成 API 或建議 API 。
新增了用來處理用戶端應用程式中「輸入即搜尋」互動的 UI 控制項。建議您針對此目的使用現有的 JavaScript 程式庫。

在 Azure AI 搜尋服務中，自動完成的查詢和建議結果是從搜尋索引以及從您已向建議工具註冊的選取欄位擷取。建議工具是索引的一部分，它會指定哪些欄位會提供完成查詢、建議結果，或是兩者皆執行。建立和載入索引時，系統會在內部建立建議工具資料結構，以儲存用於比對部分查詢的前置詞。針對建議，選擇適合唯一或至少不重複的欄位對於體驗而言非常重要。如需詳細資訊，請參閱設定建議工具。

本文的其餘部分著重於查詢和用戶端程式碼。它會使用 JavaScript 和 C# 來說明重點。 REST API 範例可用來精簡轉譯每個作業。如需端對端程式代碼範例，請參閱使用 .NET 將搜尋新增至網站。

設定要求

要求的元素包括其中一個「輸入即搜尋」API、部分查詢，以及建議工具。下列指令碼說明使用自動完成 REST API 作為範例的要求元件。

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

參數 suggesterName 會提供用來完成字詞或建議的建議工具感知欄位。特別是針對建議，欄位清單應該由提供比對結果之間清楚選擇的建議所組成。在銷售電腦遊戲的網站上，此欄位可能是遊戲標題。

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

API 不會對部分查詢強制加上長度下限需求；查詢可以只是一個字元。不過，jQuery 自動完成會提供長度下限。通常至少為兩個或三個字元。

相符項目位於輸入字串中任何位置的字詞開頭。鑒於快速棕色狐狸，自動完成和建議都與部分版本的，快速，棕色或狐狸，而不是在部分虛線術語，如羅恩或牛。此外，每個相符項目都會設定下游擴充的範圍。快速棕色或快速麵包上快速 br 相符專案的部分查詢，但除非快速* 在快*之前，否則棕色或麵包本身都不是相符專案。

輸入即搜尋 API

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

建構回應

自動完成和建議的回應會是您可能預期得到的以下模式：自動完成會傳回字詞清單、建議會傳回字詞和文件識別碼，讓您擷取文件 (使用查閱文件 API 來擷取詳細資料頁面的特定文件)。

回應則由要求上的參數組成：

若為自動完成，請設定 autocompleteMode 來判斷文字完成是否以一或兩個字詞進行。
如需建議，請將$select設定為傳回包含唯一或區分值的欄位，例如名稱和描述。請避免包含重複值的欄位 (例如類別或城市)。

下列參數同時適用於自動完成和建議，但也許對於建議而言更加適用，特別是在建議工具包含多個欄位時。

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

新增使用者互動程式碼

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

雖然您可以原生撰寫此程式碼，但從現有的 JavaScript 程式庫使用函式要容易得多，例如下列之一。

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

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

建議

本節會從搜尋方塊定義開始，逐步引導您完成建議的結果實作。也會示範操作方法以及叫用本文參照的第一個 JavaScript 自動完成程式庫的指令碼。

假設使用 jQuery UI 自動完成程式庫和 C# 中的 MVC 專案，您可以在 Index.cshtml 檔案中使用 JavaScript 來定義搜尋方塊。此程式庫會對 MVC 控制器發出非同步呼叫以擷取建議，藉以在搜尋方塊中新增「輸入即搜尋」互動。

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

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

此範例是簡單的輸入文字方塊，並附有用來設定樣式的類別、JavaScript 所要參考的識別碼，和預留位置文字。

在相同的檔案中，內嵌參考搜尋方塊的 JavaScript。下列函式會呼叫建議 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 等等。醒目提示是以和 HighlightPostTag 參數為基礎HighlightPreTag，以函Suggest式內嵌定義。

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

建議函式

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

InitSearch 方法會建立已對 Azure AI 搜尋服務服務進行驗證的 HTTP 索引用戶端。 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 物件，然後傳遞到建議 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，以供在用戶端中顯示。

後續步驟

下列教學課程示範輸入即搜尋體驗。

將搜尋新增至網站 (C#)

共用方式為