Aggiungere il completamento automatico e i suggerimenti di ricerca nelle app client

  • Articolo

La ricerca contestualmente all'atto della digitazione è una tecnica comune per migliorare la produttività delle query. In Ricerca di intelligenza artificiale di Azure questa esperienza è supportata tramite il completamento automatico, che termina un termine o una frase in base all'input parziale (ad esempio, il completamento di micro con microprocessore, microscopio, microsoft e qualsiasi altra micro-corrispondenza). Una seconda esperienza utente è costituita da suggerimenti, che genera un breve elenco di documenti corrispondenti (ad esempio, restituendo titoli di libri con un ID in modo che sia possibile collegarsi a una pagina di dettaglio relativa a tale libro). Sia il completamento automatico che i suggerimenti sono predicati su una corrispondenza nell'indice. Il servizio non offre query completate automaticamente o suggerimenti che restituiscono zero risultati.

Per implementare tali esperienze in Azure AI Search:

  • Aggiungere un suggester a uno schema di indice.
  • Compilare una query che chiama l'API completamento automatico o l'API Suggestions nella richiesta.
  • Aggiungere un controllo dell'interfaccia utente per gestire le interazioni di ricerca contestualmente all'atto della digitazione nell'app client. A questo scopo, è consigliabile utilizzare una libreria JavaScript esistente.

In Azure AI Search, le query completate automaticamente e i risultati suggeriti vengono recuperati dall'indice di ricerca, dai campi selezionati registrati con un suggerimento. Un suggerimento fa parte dell'indice e specifica quali campi forniscono contenuto che completa una query, suggerisce un risultato o esegue entrambe le operazioni. Quando l'indice viene creato e caricato, viene creata internamente una struttura di dati del suggerimento per archiviare i prefissi utilizzati per la corrispondenza nelle query parziali. Per i suggerimenti, la scelta di campi adatti unici o almeno non ripetitivi è essenziale per l'esperienza. Per altre informazioni, vedere Configurare un suggerimento.

La parte restante di questo articolo è incentrata sulle query e sul codice client. Utilizza JavaScript e C# per illustrare i punti chiave. Gli esempi di API REST vengono utilizzati per presentare in modo conciso ogni operazione. Per esempi di codice end-to-end, vedere Aggiungere la ricerca a un sito Web con .NET.

Configurare una richiesta

Gli elementi di una richiesta includono una delle API di ricerca contestualmente alla digitazione, una query parziale e uno strumento suggerimenti. Lo script seguente illustra i componenti di una richiesta, usando l'API REST di completamento automatico come esempio.

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

Il suggesterName parametro fornisce i campi con riconoscimento del suggerimento usati per completare termini o suggerimenti. Per i suggerimenti in particolare, l'elenco dei campi deve essere costituito da suggerimenti che offrono scelte chiare tra i risultati corrispondenti. Per un sito che vende giochi per computer, il campo potrebbe essere il titolo del gioco.

Il search parametro fornisce la query parziale, in cui i caratteri vengono inseriti nella richiesta di query tramite il controllo di completamento automatico jQuery. Nell'esempio precedente, minecraf è un'illustrazione statica di ciò che il controllo potrebbe passare.

Le API non impongono requisiti di lunghezza minima per la query parziale, che può avere le dimensioni di un singolo carattere. Tuttavia, il completamento automatico di jQuery fornisce una lunghezza minima. Un minimo di due o tre caratteri è il requisito tipico.

Le corrispondenze si trovano all'inizio di un termine, in qualsiasi punto della stringa di input. Dato che la volpe marrone veloce, sia il completamento automatico che i suggerimenti corrispondono a versioni parziali di , rapido, marrone o fox, ma non in termini parziali di prefisso come rown o ox. Inoltre, ogni corrispondenza imposta l'ambito per le espansioni downstream. Una query parziale delle corrispondenze br rapide su un pane rapido o marrone o veloce, ma nessuno dei due corrisponde a se stessi sarebbe una corrispondenza a meno che non li precede rapidamente* .

API relative alla ricerca contestualmente alla digitazione.

Seguire questi collegamenti per le pagine di riferimento di REST e SDK .NET:

Strutturare una risposta

Le risposte per il completamento automatico e i suggerimenti sono ciò che ci si potrebbe attendere per il modello: Completamento automatico restituisce un elenco di termini, Suggerimenti restituisce dei termini più un ID documento in modo da poter recuperare il documento (usare l'API Documento di ricerca per recuperare il documento specifico con a pagina che ne riporta i dettagli).

Le risposte sono modellate dai parametri della richiesta:

  • Per il completamento automatico, impostare autocompleteMode per determinare se il completamento del testo si verifica in uno o due termini.

  • Per suggerimenti, impostare $select per restituire campi contenenti valori univoci o differenzianti, ad esempio nomi e descrizione. Evitare campi che contengono valori duplicati, ad esempio una categoria o una città.

I parametri seguenti si applicano sia al completamento automatico che ai suggerimenti, ma sono più applicabili ai suggerimenti, soprattutto quando un suggerimento include più campi.

Parametro Utilizzo
searchFields Vincolare la query a campi specifici.
$filter Applicare criteri di corrispondenza al set di risultati ($filter=Category eq 'ActionAdventure').
$top Limitare i risultati a un numero specifico ($top=5).

Aggiungere codice per l'interazione utente

Il riempimento automatico di un termine di query o l'eliminazione di un elenco di collegamenti corrispondenti richiede un codice di interazione utente, in genere JavaScript, che può utilizzare le richieste provenienti da origini esterne, ad esempio il completamento automatico o le query di suggerimento su un indice cognitivo di Ricerca di Azure.

Anche se è possibile scrivere questo codice in modo nativo, è più facile utilizzare funzioni della libreria JavaScript esistente, ad esempio una delle seguenti.

  • Il widget di completamento automatico (interfaccia utente jQuery) viene visualizzato nel frammento di codice di suggerimento. È possibile creare una casella di ricerca e quindi farvi riferimento in una funzione JavaScript che usa il widget di completamento automatico. Le proprietà nel widget impostano l'origine (una funzione di completamento automatico o di suggerimenti), la lunghezza minima dei caratteri di input prima dell'esecuzione dell'azione e il posizionamento.

  • Il plug-in di completamento automatico XDSoft viene visualizzato nel frammento di codice di completamento automatico.

  • I suggerimenti verranno visualizzati nell'esercitazione Aggiungi ricerca ai siti Web e nell'esempio di codice.

Usare queste librerie nel client per creare una casella di ricerca che supporti sia i suggerimenti che il completamento automatico. Gli input raccolti nella casella di ricerca possono quindi essere associati a suggerimenti e azioni di completamento automatico nel servizio di ricerca.

Suggerimenti

Questa sezione illustra un'implementazione dei risultati suggeriti, a partire dalla definizione della casella di ricerca. Viene inoltre illustrata la modalità e lo script che richiama la prima libreria di completamento automatico JavaScript a cui si fa riferimento in questo articolo.

Supponendo che la libreria di completamento automatico dell'interfaccia utente di jQuery e un progetto MVC siano presenti in C#, è possibile definire la casella di ricerca utilizzando JavaScript nel file Index.cshtml. Questa libreria aggiunge l'interazione con la ricerca contestualmente alla digitazione alla casella di ricerca effettuando chiamate asincrone al controller MVC per recuperare suggerimenti.

In Index.cshtml all'interno della cartella \Views\Home, una riga per creare una casella di ricerca potrebbe essere la seguente:

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

Questo esempio contiene una casella di testo di input semplice con una classe per definire lo stile, un ID a cui JavaScript farà riferimento e un testo segnaposto.

All'interno dello stesso file, incorporare JavaScript che fa riferimento alla casella di ricerca. La funzione seguente richiama l'API Suggest, che richiede documenti corrispondenti suggeriti in base agli input parziali dei termini:

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

source indica alla funzione di completamento automatico dell'interfaccia utente di jQuery dove recuperare l'elenco di voci da visualizzare sotto la casella di ricerca. Poiché questo progetto è un progetto MVC, chiama la Suggest funzione in HomeController.cs che contiene la logica per la restituzione di suggerimenti di query. Questa funzione passa anche alcuni parametri per controllare evidenziazioni, corrispondenze fuzzy e termini. L'API JavaScript di completamento automatico aggiunge il parametro per i termini.

minLength: 3 Garantisce che le raccomandazioni vengano visualizzate solo quando nella casella di ricerca sono presenti almeno tre caratteri.

Abilitare opzioni corrispondenza fuzzy

La ricerca fuzzy consente di ottenere risultati in base alle corrispondenze simili, anche se l'utente commette errori di digitazione di una parola nella casella di ricerca. La distanza di modifica è 1, il che significa che può esserci una discrepanza massima di un carattere tra l'input dell'utente e una corrispondenza.

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

Abilitare evidenziazione

L'evidenziazione applica lo stile del carattere ai caratteri nel risultato che corrispondono all'input. Ad esempio, se l'input parziale è micro, il risultato viene visualizzato come microsoft, microscope e così via. L'evidenziazione HighlightPreTag si basa sui parametri e HighlightPostTag definiti inline con la Suggest funzione .

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

Funzione Suggerimenti

Se si usa C# e un'applicazione MVC, il file HomeController.cs nella directory Controllers consente di creare una classe per i risultati suggeriti. In .NET una Suggest funzione si basa sul metodo SuggestAsync. Per altre informazioni, vedere Come utilizzare Azure AI Search da un'applicazione .NET.

Il metodo InitSearch genererà un client di indice HTTP autenticato nel servizio di Azure AI Search. Le proprietà nella classe SuggestOptions determinano quali campi vengono cercati e restituiti nei risultati, il numero di corrispondenze e se viene usata la corrispondenza fuzzy.

Per il completamento automatico, la corrispondenza fuzzy è limitata alla distanza di una modifica (un carattere omesso o fuori posto). La corrispondenza fuzzy nelle query di completamento automatico può talvolta produrre risultati imprevisti a seconda delle dimensioni dell'indice e della modalità di partizione.

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

La SuggestAsync funzione accetta due parametri che determinano se le evidenziazioni di hit vengono restituite o viene usata la corrispondenza fuzzy oltre all'input del termine di ricerca. È possibile includere fino a otto corrispondenze nei risultati suggeriti. Il metodo crea un oggetto SuggestOptions che viene quindi passato all'API Suggest. Il risultato viene quindi convertito in formato JSON in modo da essere visualizzato nel client.

Completamento automatico

Fino a questo momento, il codice dell'esperienza utente di ricerca è stato centrato sui suggerimenti. Il blocco di codice successivo mostra la funzione di completamento automatico, che utilizza la funzione dell'interfaccia utente di jQuery XDSoft, passando una richiesta per il completamento automatico di Azure AI Search. Come per i suggerimenti, in un'applicazione C#, il codice che supporta l'interazione dell'utente passa a 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("");
        }
    });
});

Funzione di completamento automatico

Il completamento automatico si basa sul metodo AutocompleteAsync. Come per i suggerimenti, questo blocco di codice verrà inserito nel file 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);
}

La funzione Autocomplete accetta l'input del termine di ricerca. Il metodo crea un oggetto AutoCompleteParameters. Il risultato viene quindi convertito in formato JSON in modo da essere visualizzato nel client.

Passaggio successivo

L'esercitazione seguente illustra un'esperienza di ricerca contestualmente alla digitazione.

Aggiungere la ricerca a un sito Web (C#)