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

La ricerca come tipo è 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 (completando "micro" con "microsoft"). Una seconda esperienza utente è costituita da suggerimenti o da un breve elenco di documenti corrispondenti (restituzione di titoli di libri con ID in modo che sia possibile collegarsi a una pagina di dettaglio su tale libro). Sia il completamento automatico che i suggerimenti sono predicati su una corrispondenza nell'indice. Il servizio non offrirà query che restituiscono zero risultati.

Per implementare queste esperienze in Ricerca di intelligenza artificiale di Azure:

• Aggiungere un oggetto suggester a uno schema di indice
• Compilare una query che chiama l'API Completamento automatico o Suggerimenti nella richiesta.
• Aggiungere un controllo dell'interfaccia utente per gestire le interazioni di ricerca come tipo nell'app client. A questo scopo, è consigliabile usare una libreria JavaScript esistente.

In Ricerca di intelligenza artificiale di Azure, 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 forniranno 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 usati per la corrispondenza nelle query parziali. Per suggerimenti, la scelta di campi adatti unici o almeno non ripetitivi è essenziale per l'esperienza. Per altre informazioni, vedere Creare un suggerimento.

La parte restante di questo articolo è incentrata sulle query e sul codice client. Usa JavaScript e C# per illustrare i punti chiave. Gli esempi di API REST vengono usati per presentare in modo conciso ogni operazione. Per esempi di codice end-to-end, vedere Passaggi successivi.

Configurare una richiesta

Gli elementi di una richiesta includono una delle API search-as-you-type, una query parziale e un suggerimento. 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=2020-06-30
{
  "search": "minecraf",
  "suggesterName": "sg"
}

Il valore "suggesterName" fornisce i campi in grado di fornire suggerimenti usati per completare termini o suggerimenti. Per i suggerimenti in particolare, l'elenco dei campi deve essere composto da quelli che offrono scelte chiare tra i risultati corrispondenti. In un sito che vende giochi per computer, il campo potrebbe essere il titolo del gioco.

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

Le API non impongono requisiti di lunghezza minima per la query parziale; può essere piccolo come un carattere. Tuttavia, il completamento automatico di jQuery fornisce una lunghezza minima. Un minimo di due o tre caratteri è tipico.

Le corrispondenze si trovano all'inizio di un termine in qualsiasi punto della stringa di input. Dato "the quick brown fox", sia autocomplete che suggestions will match on partial versions of "the", "quick", "brown" or "fox" but not on partial infix terms like "rown" or "ox". Inoltre, ogni corrispondenza imposta l'ambito per le espansioni downstream. Una query parziale di "br veloce" corrisponderà a "quick brown" o "quick bread", ma nessuno dei due "brown" o "bread" da solo sarebbe corrispondente a meno che "quick" li precede.

API per la ricerca come tipo

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

• API REST dei suggerimenti
• API REST di completamento automatico
• SuggestAsync, metodo
• Metodo AutocompleteAsync

Strutturare una risposta

Le risposte per il completamento automatico e i suggerimenti sono gli aspetti previsti per il modello: il completamento automatico restituisce un elenco di termini, i suggerimenti restituiscono i termini più un ID documento in modo da poter recuperare il documento (usare l'API Ricerca documento per recuperare il documento specifico per una pagina di dettaglio).

Le risposte sono modellate dai parametri della richiesta:

• Per 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 diversi, ad esempio nomi e descrizione. Evitare campi che contengono valori duplicati, ad esempio una categoria o una città.

I parametri aggiuntivi seguenti si applicano sia al completamento automatico che ai suggerimenti, ma sono forse più necessari per i 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 di interazione utente

La compilazione automatica di un termine di query o l'eliminazione di un elenco di collegamenti corrispondenti richiede codice di interazione dell'utente, in genere JavaScript, in grado di 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, è molto più semplice usare le funzioni della libreria JavaScript esistente, ad esempio una delle seguenti.

• Il widget completamento automatico (interfaccia utente jQuery) viene visualizzato nel frammento di codice suggerimento. È possibile creare una casella di ricerca e quindi farvi riferimento in una funzione JavaScript che usa il widget Completamento automatico. Le proprietà nel widget impostano l'origine (una funzione di completamento automatico o 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 sono visualizzati nell'esercitazione javaScript 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 illustrato come e script che richiama la prima libreria di completamento automatico JavaScript a cui si fa riferimento in questo articolo.

Creare una casella di ricerca

Supponendo che la libreria di completamento automatico dell'interfaccia utente jQuery e un progetto MVC in C#, è possibile definire la casella di ricerca usando JavaScript nel file Index.cshtml. La libreria aggiunge l'interazione di ricerca come tipo alla casella di ricerca effettuando chiamate asincrone al controller MVC per recuperare i suggerimenti.

In Index.cshtml nella 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 chiama 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 ottenere l'elenco di elementi da visualizzare nella casella di ricerca. Poiché questo progetto è un progetto MVC, chiama la funzione Suggest 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 la 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 l'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 si basa sui parametri HighlightPreTag e HighlightPostTag, definiti inline con la funzione Suggestion.

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

Funzione Suggest

Se si usa C# e un'applicazione MVC, il file HomeController.cs nella directory Controllers è il punto in cui è possibile creare una classe per i risultati suggeriti. In .NET una funzione Suggest si basa sul metodo SuggestAsync. Per altre informazioni su .NET SDK, vedere Come usare Ricerca di intelligenza artificiale di Azure da un'applicazione .NET.

Il InitSearch metodo crea un client di indice HTTP autenticato per l'servizio di ricerca di intelligenza artificiale di Azure. Le proprietà della classe SuggestOptions determinano quali campi vengono cercati e restituiti nei risultati, il numero di corrispondenze e se viene utilizzata la corrispondenza fuzzy.

Per il completamento automatico, la corrispondenza fuzzy è limitata a una distanza di modifica (un carattere omesso o smarrito). Si noti che la corrispondenza fuzzy nelle query di completamento automatico può talvolta produrre risultati imprevisti a seconda delle dimensioni dell'indice e della relativa partizionamento orizzontale. Per altre informazioni, vedere Concetti relativi alla partizione e al partizionamento orizzontale.

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 funzione SuggestAsync accetta due parametri che determinano se vengono restituite le evidenziazioni dei riscontri o se vengono usate corrispondenze 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

Finora, il codice dell'esperienza utente di ricerca è stato centrato sui suggerimenti. Il blocco di codice successivo mostra il completamento automatico, usando la funzione di completamento automatico dell'interfaccia utente XDSoft jQuery, passando una richiesta per il completamento automatico di Ricerca intelligenza artificiale di Azure. 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.

Passaggi successivi

L'esercitazione seguente illustra un'esperienza di ricerca come tipo.

Aggiungere la ricerca a un sito Web (JavaScript)