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

發行項
10/16/2024

「輸入即搜尋」是改善查詢生產力的常見技術。在 Azure AI 搜尋服務中，透過 [自動完成] 來支援此體驗，此體驗會根據部分輸入 (如以「microchip」、「microscope」、「microsoft」以及 micro 的任何其他匹配項來完成「micro」) 來完成字詞或片語。第二個使用者體驗是「建議」，或簡短相符檔案清單 (傳回具識別碼的書籍標題，以便您連至該書籍的詳細資料頁面)。自動完成和建議都取決於索引中的相符項目。如果自動完成的查詢或建議不會返回任何結果，則此服務不會提供這樣的查詢和建議。

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

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

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

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

設定要求

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

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

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

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

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

相符項目位於輸入字串中任何位置的字詞開頭。假設有「the quick brown fox」，而自動完成和建議都會與部分版本的「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 自動完成程式庫的指令碼。

假設使用 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 中的建議函式，其中包含傳回查詢建議的邏輯。此函式也會傳遞幾個參數來控制醒目提示、模糊比對和字詞。自動完成 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 應用程式，則控制器目錄下的 HomeController.cs 檔案是您可能會為建議結果建立類別的位置。在 .NET 中，建議函式是以 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#)

共用方式為