Compartir por

Incorporación de sugerencias de búsqueda y de la función de autocompletar a aplicaciones cliente

  • Artigo

La búsqueda mientras se escribe es una técnica común para mejorar la productividad de las consultas. En Búsqueda de Azure AI, esta experiencia se admite a través de autocompletar, que finaliza un término o frase según la entrada parcial (por ejemplo, completa micro con microchip, microscopio, microsoft y muchas más combinaciones). Una segunda experiencia de usuario son las sugerencias, que generan una breve lista de documentos coincidentes (por ejemplo, se devuelven títulos de libros con un identificador que son vínculos a una página de detalles sobre ese libro). Tanto la función de autocompletar como las sugerencias se declaran en una coincidencia en el índice. El servicio no ofrece consultas o sugerencias autocompletadas que devuelvan cero resultados.

Para implementar estas experiencias en Azure AI Search:

  • Agrega un suggester a un esquema de índice.
  • Compile una consulta que llame a la API de Autocompletar o a la API de Sugerencias en la solicitud.
  • Agregue un control de la interfaz de usuario para controlar las interacciones de la búsqueda mientras se escribe en la aplicación cliente. Se recomienda usar una biblioteca de JavaScript existente para este fin.

En Azure AI Search, las consultas autocompletadas y los resultados sugeridos se recuperan desde el índice de búsqueda, a partir de los campos seleccionados que se registran con un proveedor de sugerencias. Un proveedor de sugerencias forma parte del índice y especifica los campos que proporcionan contenido que completa una consulta, sugiere un resultado o ambos. Cuando se crea y carga el índice, se crea internamente una estructura de datos del proveedor de sugerencias para almacenar los prefijos usados para encontrar coincidencias en consultas parciales. Para obtener sugerencias, la elección de los campos adecuados que sean únicos o, al menos, no repetitivos, es esencial para la experiencia. Para obtener más información, consulte Configuración de un proveedor de sugerencias.

El resto de este artículo se centra en las consultas y el código de cliente. Usa JavaScript y C# para ilustrar los puntos clave. Se usan ejemplos de API de REST para presentar cada operación de manera concisa. Para obtener ejemplos de código de un extremo a otro, consulte Agregar búsqueda a un sitio web con .NET.

Configuración de una solicitud

Los elementos de una solicitud incluyen una de las API de buscar mientras se escribe, una consulta parcial y un proveedor de sugerencias. En el siguiente script se ilustran los componentes de una solicitud, y se usa la API de REST de autocompletar como ejemplo.

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

El parámetro suggesterName proporciona los campos con reconocimiento del proveedor de sugerencias para completar los términos o las sugerencias. En el caso concreto de las sugerencias, la lista de campos debe estar compuesta por las que ofrecen opciones claras entre los resultados coincidentes. En un sitio que vende juegos de equipo, el campo puede ser el título del juego.

El parámetro search proporciona la consulta parcial, donde los caracteres se insertan en la solicitud de consulta a través del control de jQuery Autocomplete. En el ejemplo anterior, minecraf es una ilustración estática de lo que podría pasar el control.

Las API no imponen requisitos de longitud mínima en la consulta parcial; podría tener un solo carácter. Sin embargo, la función de autocompletar de jQuery proporciona una longitud mínima. Un mínimo de dos o tres caracteres es lo más habitual.

Las coincidencias son del principio de un término, en cualquier parte de la cadena de entrada. Dado the quick brown fox, tanto la función de autocompletar como las sugerencias coinciden en las versiones parciales de the, quick, brown, o fox, pero no en los términos parciales infijos como rown o ox. Además, cada coincidencia establece el ámbito de las expansiones de bajada. Una consulta parcial de quick br coincidirá con quick brown o quick bread, pero ni brown ni bread por sí mismos coincidirán, a menos que quick* les preceda.

API para buscar mientras se escribe

Siga estos vínculos para las páginas de referencia del SDK de REST y .NET:

Estructuración de una respuesta

Las respuestas de la función de autocompletar y de las sugerencias son lo que cabría esperar para el patrón: Autocompletar devuelve una lista de términos, mientras que Sugerencias devuelve no solo términos, sino también un identificador de documento que le permite capturar el documento (use la API Buscar documento para capturar el documento específico de una página de detalles).

Las respuestas están formadas por los parámetros de la solicitud:

  • Para la función de autocompletar, establezca autocompleteMode para determinar si la finalización del texto se produce en uno o dos términos.

  • Para la función de sugerencias, establezca $Select para devolver campos que contengan valores únicos o diferenciales, como nombres y descripciones. Evite los campos que contienen valores duplicados (como una categoría o una ciudad).

Los parámetros siguientes se aplican tanto a las sugerencias como a la función de autocompletar, pero son más aplicables a las sugerencias, especialmente cuando un proveedor de sugerencias incluya varios campos.

Parámetro Uso
searchFields Restringe la consulta a campos específicos.
$filter Aplica criterios de coincidencia en el conjunto de resultados ($filter=Category eq 'ActionAdventure').
$top Limita los resultados a un número específico ($top=5).

Adición de código de interacción del usuario

El rellenado automático de un término de consulta o la eliminación de una lista de vínculos coincidentes requiere código de interacción del usuario, normalmente JavaScript, que puede consumir solicitudes de orígenes externos, como consultas con autocompletar o sugerencias en un índice de Azure Search Cognitive.

Aunque podrías escribir este código de forma nativa, es más fácil usar funciones de la biblioteca de JavaScript existente, como la que se muestra a continuación.

  • El widget de autocompletar (jQuery UI) aparece en el fragmento de código de sugerencias. Puede crear un cuadro de búsqueda y luego hacer referencia a él en una función de JavaScript que use el widget de autocompletar. Las propiedades del widget establecen la longitud mínima de los caracteres de entrada de origen (una función de autocompletar o sugerencias) para que se realice la acción y el posicionamiento.

  • El complemento de autocompletar XDSoft aparece en el fragmento de código de autocompletar.

  • Sugerencias aparece en el tutorial Agregar búsqueda a sitios web y en el código de ejemplo.

Use estas bibliotecas en el cliente para crear un cuadro de búsqueda que admita sugerencias y autocompletar. Las entradas recopiladas en el cuadro de búsqueda se pueden emparejar con sugerencias y acciones de autocompletar en el servicio de búsqueda.

Sugerencias

En esta sección se guía a través de una implementación de resultados sugeridos, empezando por la definición del cuadro de búsqueda. También se muestra cómo y el script que invoca la primera biblioteca de autocompletar de JavaScript a la que se hace referencia en este artículo.

Suponiendo que dispone de la biblioteca de autocompletar de la interfaz de usuario de jQuery y un proyecto de MVC en C#, podría definir el cuadro de búsqueda mediante JavaScript en el archivo index.cshtml. Esta biblioteca agrega la interacción de buscar mientras se escribe al cuadro de búsqueda; para ello realiza llamadas asincrónicas al controlador de MVC para recuperar sugerencias.

En Index.cshtml dentro de la carpeta \Views\Home, una línea para crear un cuadro de búsqueda podría ser la siguiente:

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

Este ejemplo es un cuadro de texto de entrada simple con una clase para establecer el estilo y un identificador al que JavaScript hará referencia, además de un texto de marcador de posición.

En el mismo archivo, inserte JavaScript que haga referencia al cuadro de búsqueda. La siguiente función llama a la API de sugerencias, que solicita los documentos coincidentes sugeridos en función de las entradas de términos parciales:

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

En source se indica a la función de autocompletar de la interfaz de usuario de jQuery dónde obtener la lista de elementos para mostrar debajo del cuadro de búsqueda. Puesto que este es un proyecto de MVC, llama a la función Suggest en HomeController.cs, que contiene la lógica para devolver las sugerencias de consulta. Esta función también pasa algunos parámetros para controlar aspectos destacados, una coincidencia aproximada o un término. La API de JavaScript de la función Autocompletar agrega el parámetro de término.

minLength: 3 garantiza que las recomendaciones solo se muestran cuando hay al menos tres caracteres en el cuadro de búsqueda.

Habilitación de la coincidencia aproximada

La búsqueda aproximada permite obtener resultados basados en coincidencias cercanas incluso si el usuario escribe incorrectamente una palabra en el cuadro de búsqueda. La distancia de edición es 1, lo que significa que puede haber una discrepancia máxima de un carácter entre la entrada del usuario y una coincidencia.

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

Habilitación del resaltado

El resaltado aplica el estilo de fuente a los caracteres del resultado que corresponden a la entrada. Por ejemplo, si la entrada parcial es micro, el resultado aparecería como microsoft, microscopio, etc. El resaltado se basa en los parámetros HighlightPreTag y HighlightPostTag, definidos en línea con la función Suggest.

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

Función de sugerencias

Si usas C# y una aplicación MVC, el archivo HomeController.cs del directorio Controladores es el lugar donde puede crear una clase para los resultados sugeridos. En .NET, una función Suggest se basa en el método SuggestAsync. Para más información sobre el SDK de .NET, consulte Uso de Azure AI Search desde una aplicación .NET.

El método InitSearch crea un cliente del índice HTTP autenticado en el servicio Azure AI Search. Las propiedades de la clase SuggestOptions determinan en qué campos se busca y cuáles se devuelven en los resultados, el número de coincidencias y si se usa la coincidencia aproximada.

En la funcionalidad de autocompletar, la coincidencia aproximada se limita a la distancia de una edición (un carácter omitido o mal colocado). La coincidencia aproximada en consultas de autocompletar puede producir a veces resultados inesperados en función del tamaño del índice y de cómo se particiona.

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 función SuggestAsync toma dos parámetros que determinar si se devuelven resaltados de aciertos o si se usa la coincidencia aproximada además de la entrada del término de búsqueda. Los resultados sugeridos pueden incluir hasta ocho coincidencias. El método crea un objeto SuggestOptions que luego se pasa a la API de Suggest. Luego el resultado se convierte en JSON para poder mostrarlo en el cliente.

Autocompletar

Hasta ahora, el código de experiencia de usuario de la búsqueda se ha centrado en las sugerencias. El siguiente bloque de código muestra la función de autocompletar de la interfaz de usuario de jQuery de XDSoft que pasa una solicitud de autocompletar de Azure AI Search. Igual que con las sugerencias, en una aplicación C#, el código que admite la interacción del usuario se encuentra en 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("");
        }
    });
});

Función de autocompletar

La función Autocomplete se basa en el método AutocompleteAsync. Igual que con las sugerencias, este bloque de código se incluye en el archivo 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 función Autocomplete toma la entrada del término de búsqueda. El método crea un objeto AutoCompleteParameters. Luego el resultado se convierte en JSON para poder mostrarlo en el cliente.

Paso siguiente

En el siguiente tutorial se muestra un ejemplo de como se realiza la búsqueda a medida que se escribe.

Agregar búsqueda a un sitio web (C#)