Hinzufügen von AutoVervollständigen und Suchvorschlägen in Client-Apps

„Suche während der Eingabe“ ist ein gängiges Verfahren für mehr Produktivität bei den Abfragen. In Azure KI-Suche wird dieses Verfahren durch die Funktion AutoVervollständigen unterstützt, die einen Begriff oder einen Ausdruck auf der Grundlage von partiellen Eingaben vervollständigt (aus Mikro wird z. B. Mikrochip oder Mikroskop, aus „Micro“ wird z. B. Microsoft, oder es werden andere Treffer mit „Mikro“ oder „Micro“ gefunden). Eine weitere Benutzerfunktion sind Vorschläge, wodurch eine engere Auswahlliste übereinstimmender Dokumente erzeugt wird (z. B. Buchtitel werden mit einer ID zurückgegeben, sodass Sie einen Link zu einer Detailseite für ein Buch erstellen können). Sowohl AutoVervollständigen als auch Vorschläge basieren auf einer Entsprechung im Index. Der Dienst bietet keine automatisch vervollständigten Abfragen oder Vorschläge, die keine Ergebnisse zurückgeben.

So implementieren Sie diese Erfahrungen in Azure AI Search:

• Fügen Sie suggester zu einem Indexschema hinzu.
• Erstellen Sie eine Abfrage, die die AutoVervollständigen-API oder Vorschläge-API für die Anforderung aufruft.
• Fügen Sie ein UI-Steuerelement hinzu, um Interaktionen bei der Suche während der Eingabe in Ihrer Client-App zu verarbeiten. Wir empfehlen für diesen Zweck eine vorhandene JavaScript-Bibliothek.

In Azure KI-Suche werden automatisch vervollständigte Abfragen und vorgeschlagene Ergebnisse aus dem Suchindex abgerufen, und zwar aus ausgewählten Feldern, die Sie mit einer Vorschlagsfunktion registrieren. Eine Vorschlagsfunktion ist Bestandteil des Index und gibt an, welche Felder Inhalte zum Vervollständigen einer Abfrage und/oder zum Vorschlagen eines Ergebnisses bereitstellen. Wenn der Index erstellt und geladen wird, wird intern eine Vorschlagsdatenstruktur zum Speichern von Präfixen erstellt, die für die Übereinstimmung bei partiellen Abfragen verwendet werden. Bei Vorschlägen ist es für die Sucherfahrung äußerst wichtig, geeignete Felder auszuwählen, die einmalig sind oder sich zumindest nicht wiederholen. Weitere Informationen finden Sie unter Konfigurieren einer Vorschlagsfunktion.

Im weiteren Verlauf dieses Artikels geht es um Abfragen und Clientcode. Zum Veranschaulichen der wichtigsten Punkte werden JavaScript und C# verwendet. Anhand von REST-API-Beispielen wird jeder Vorgang knapp und präzise dargestellt. End-to-End-Codebeispiele finden Sie unter Hinzufügen von Suchfunktionen zu einer Website mit .NET.

Einrichten einer Anforderung

Die Elemente einer Anforderung beinhalten eine der APIs für die Suche während der Eingabe, eine partielle Abfrage und eine Vorschlagsfunktion. Im folgenden Skript werden die Komponenten einer Anforderung veranschaulicht, wobei die AutoVervollständigen-REST-API als Beispiel verwendet wird.

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

Der suggesterName-Parameter gibt die Felder der Vorschlagsfunktion aus, die zum Vervollständigen von Begriffen oder Vorschlägen verwendet werden. Speziell bei Vorschlägen sollte die Feldliste aus Vorschlägen bestehen, die bei übereinstimmenden Ergebnissen klare Auswahlmöglichkeiten bieten. Auf einer Website zum Vertrieb von Computerspielen ist das Feld möglicherweise der Titel des Spiels.

Der search-Parameter stellt die partielle Abfrage bereit, bei der Zeichen über das jQuery AutoVervollständigen-Steuerelement an die Abfrageanforderung übergeben werden. Im obigen Beispiel ist minecraf eine statische Abbildung dessen, was das Steuerelement möglicherweise übergibt.

Die APIs erzwingen keine Mindestanforderungen für die Länge der partiellen Abfrage. Sie kann auch aus nur einem Zeichen bestehen. „jQuery Autocomplete“ stellt jedoch eine Mindestlänge bereit. In der Regel sind es mindestens zwei oder drei Zeichen.

Übereinstimmungen finden sich am Anfang eines Begriffs an beliebiger Stelle in der Eingabezeichenfolge. Bei der Suche nach the quick brown fox findet sowohl die Funktion „AutoVervollständigen“ als auch die Vorschlagsfunktion die partiellen Versionen von the, quick, brown oder fox, aber keine partiellen Infixe wie rown oder ox. Außerdem legt jede Übereinstimmung den Bereich für nachfolgende Erweiterungen fest. Die partielle Abfrage von quick br findet quick brown oder quick bread. Sie findet aber weder brown noch bread alleine, solange nicht „quick“ davorsteht.

APIs für die Suche während der Eingabe

Folgen Sie diesen Links zu den REST- und .NET SDK-Referenzseiten:

• Vorschläge-REST-API
• AutoVervollständigen-REST-API
• SuggestAsync-Methode
• AutocompleteAsync-Methode

Struktur einer Antwort

Antworten auf AutoVervollständigen und Vorschläge sind das, was Sie als Muster erwarten können: AutoVervollständigen gibt eine Liste von Ausdrücken zurück, Vorschläge gibt Ausdrücke plus eine Dokument-ID zurück, sodass Sie das Dokument abrufen können (verwenden Sie die Nachschlagedokument-API, um das bestimmte Dokument für eine Detailseite abzurufen).

Antworten werden durch die Parameter in der Anforderung gebildet:

• Legen Sie für AutoVervollständigen den autocompleteMode fest, um zu bestimmen, ob die Textvervollständigung für einen Begriff oder zwei Begriffe erfolgen soll.

• Legen Sie für Vorschläge $select fest, um Felder zurückzugeben, die eindeutige oder differenzierende Werte enthalten, z. B. Namen und Beschreibung. Vermeiden Sie Felder, die doppelte Werte (z. B. eine Kategorie oder Stadt) enthalten.

Die folgenden Parameter gelten sowohl für AutoVervollständigen als auch für Vorschläge, gelten aber eher für Vorschläge, besonders wenn eine Vorschlagsfunktion mehrere Felder enthält.

Parameter	Verwendung
searchFields	Beschränken Sie die Abfrage auf spezielle Felder.
$filter	Wenden Sie Übereinstimmungskriterien auf den Ergebnissatz an ($filter=Category eq 'ActionAdventure').
$top	Beschränken Sie die Ergebnisse auf eine bestimmte Zahl ($top=5).

Hinzufügen von Benutzerinteraktionscode

Das automatische Ausfüllen eines Abfragebegriffs oder die Dropdownauswahl in einer Liste übereinstimmender Links setzt einen Benutzerinteraktionscode (in der Regel JavaScript) voraus, der Anforderungen von externen Quellen (z. B. AutoVervollständigen- oder Vorschlagsabfragen bei einem Azure Search Cognitive-Index) verarbeiten kann.

Auch wenn Sie diesen Code nativ schreiben könnten, ist es einfacher, Funktionen aus einer vorhandenen JavaScript-Bibliothek zu verwenden, z. B. eine der folgenden.

• Das AutoVervollständigen-Widget (jQuery UI) wird im Codeschnipsel für den Vorschlag angezeigt. Sie können ein Suchfeld erstellen und dann in einer JavaScript-Funktion, die das AutoVervollständigen-Widget verwendet, darauf verweisen. Mit den Eigenschaften des Widgets werden die Quelle (eine AutoVervollständigen- oder Vorschlagsfunktion), die Mindestlänge der eingegebenen Zeichen, bevor eine Aktion erfolgt, und die Positionierung festgelegt.

• Das XDSoft-AutoVervollständigen-Plug-In wird im Codeschnipsel für AutoVervollständigen angezeigt.

• Suggestions erscheint im Tutorial zum Hinzufügen von Suchfunktionen zu einer Website und im Codebeispiel.

Verwenden Sie diese Bibliotheken im Client, um ein Suchfeld zu erstellen, das sowohl Vorschläge als auch AutoVervollständigen unterstützt. Eingaben, die im Suchfeld gesammelt werden, können dann mit Vorschlägen und AutoVervollständigen-Aktionen für den Suchdienst gekoppelt werden.

Vorschläge

In diesem Abschnitt wird die Implementierung der vorgeschlagenen Ergebnisse Schritt für Schritt beschrieben, beginnend mit der Definition des Suchfelds. Es wird auch gezeigt, wie ein Skript die erste JavaScript-Bibliothek zum AutoVervollständigen aufruft, auf die in diesem Artikel verwiesen wird.

Erstellen eines Suchfelds

Unter der Annahme, dass die jQuery UI Autocomplete-Bibliothek und ein MVC-Projekt in C# verwendet werden, könnten Sie das Suchfeld mithilfe von JavaScript in der Datei Index.cshtml definieren. Die Bibliothek fügt dem Suchfeld durch asynchrone Aufrufe an den MVC-Controller zum Abrufen von Vorschlägen die Interaktion „Suche während der Eingabe“ hinzu.

In der Datei Index.cshtml im Ordner \Views\Home könnte eine Zeile zum Erstellen eines Suchfelds wie folgt aussehen:

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

Dieses Beispiel umfasst ein einfaches Feld für die Texteingabe mit einer Klasse für das Format, einer von JavaScript referenzierten ID und Platzhaltertext.

Betten Sie in derselben Datei JavaScript-Code ein, der auf das Suchfeld verweist. Die folgende Funktion ruft die Vorschlags-API auf, die anhand der partiellen Begriffseingabe vorgeschlagene übereinstimmende Dokumente anfordert:

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

source teilt der Funktion „jQuery UI Autocomplete“ mit, wo die Liste der unter dem Suchfeld anzuzeigenden Elemente abgerufen werden soll. Da es sich um ein MVC-Projekt handelt, ruft es die Suggest-Funktion in der Datei HomeController.cs auf, die die Logik für die Rückgabe der Abfragevorschläge enthält. Diese Funktion übergibt auch einige Parameter zur Steuerung von Hervorhebungen, für die Fuzzyübereinstimmung und für Benennungen. Die JavaScript-API zur automatischen Vervollständigung fügt den Parameter für Begriffe hinzu.

minLength: 3 stellt sicher, dass Empfehlungen nur angezeigt werden, wenn mindestens drei Zeichen in das Suchfeld eingegeben wurden.

Aktivieren der Fuzzyübereinstimmung

Mit der Fuzzysuche können Sie Ergebnisse basierend auf nahen Übereinstimmungen abrufen, auch wenn der Benutzer ein Wort im Suchfeld falsch schreibt. Die Edit-Distanz beträgt 1. Das heißt, dass es zwischen der Eingabe des Benutzers und einer Übereinstimmung eine maximale Abweichung von einem Zeichen geben darf.

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

Aktivieren der Hervorhebung

Durch die Hervorhebung wird auf die Zeichen im Ergebnis, die der Eingabe entsprechen, ein Schriftschnitt angewendet. Wenn beispielsweise die partielle Eingabe Micro lautet, würde das Ergebnis als Microsoft, bei „Mikro“ als Mikroskop usw. angezeigt werden. Die Markierung basiert auf den Parametern HighlightPreTag und HighlightPostTag, die inline mit der Funktion Suggest definiert sind.

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

Vorschlagsfunktion

Wenn Sie C# und eine MVC-Anwendung verwenden, können Sie in der Datei HomeController.cs im Verzeichnis Controller eine Klasse für vorgeschlagene Ergebnisse erstellen. In .NET basiert eine Suggest-Funktion auf der SuggestAsync-Methode. Weitere Informationen zum .NET SDK finden Sie unter Verwenden von Azure AI Search aus einer .NET-Anwendung.

Mit der InitSearch-Methode wird für den Azure AI Search-Dienst ein authentifizierter Client für den HTTP-Index erstellt. Eigenschaften in der Klasse SuggestOptions bestimmen, welche Felder durchsucht und in den Ergebnissen zurückgegeben werden. Die Eigenschaften legen auch fest, wie viele Übereinstimmungen gesucht werden und ob die Fuzzyübereinstimmung verwendet wird.

Für AutoVervollständigen ist die Fuzzyübereinstimmung auf einen Bearbeitungsabstand (ein ausgelassenes oder falsch platziertes Zeichen) beschränkt. Fuzzyübereinstimmung bei Abfragen mit AutoVervollständigen liefern je nach Größe des Index und der Art und Weise, wie er partitioniert ist, manchmal unerwartete Ergebnisse.

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);
}

Die SuggestAsync-Funktion verwendet zwei Parameter, die bestimmen, ob Treffermarkierungen zurückgegeben werden sollen oder ob zusätzlich zur Eingabe des Suchbegriffs die Fuzzyübereinstimmung verwendet werden soll. Die vorgeschlagenen Ergebnisse können bis zu acht Übereinstimmungen enthalten. Die Methode erstellt ein SuggestOptions-Objekt, das an die Vorschlags-API übergeben wird. Das Ergebnis wird anschließend in JSON konvertiert, damit es im Client angezeigt werden kann.

AutoVervollständigen

Bisher war der UX-Suchcode auf Vorschläge ausgerichtet. Der nächste Codeblock zeigt das AutoVervollständigen mit der XDSoft-Funktion „jQuery UI Autocomplete“, die eine Anforderung zum AutoVervollständigen an Azure AI Search übergibt. Wie bei den Vorschlägen in einer C#-Anwendung befindet sich der Code, der die Interaktion von Benutzern unterstützt, in der Datei 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("");
        }
    });
});

Funktion „AutoVervollständigen“

AutoVervollständigen basiert auf der AutocompleteAsync-Methode. Wie bei den Vorschlägen gehört dieser Codeblock in die Datei 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);
}

Die Funktion „AutoVervollständigen“ übernimmt die Eingabe des Suchbegriffs. Die Methode erstellt ein AutoCompleteParameters-Objekt. Das Ergebnis wird anschließend in JSON konvertiert, damit es im Client angezeigt werden kann.

Nächster Schritt

Das folgende Tutorial veranschaulicht die Sucherfahrung während der Eingabe.

Hinzufügen der Suche zu einer Website (C#)