Recopilación de datos de telemetría para análisis del tráfico de búsqueda
El análisis del tráfico de búsqueda es un patrón para recopilar datos de telemetría sobre las interacciones de los usuarios con su aplicación de Azure AI Search, como eventos de clic y entradas de teclado iniciados por el usuario. Con esta información, puede determinar la eficacia de la solución de búsqueda, incluidos los términos de búsqueda más populares, la tasa de clics y las entradas de consulta que producen cero resultados.
Este patrón depende de Application Insights (una característica de Azure monitor) para recopilar datos de usuario. Requiere que agregue la instrumentación a su código de cliente, tal como se describe en este artículo. Por último, necesitará una herramienta de informes para analizar los datos. Se recomienda Power BI, pero puede utilizar el panel de la aplicación o cualquier herramienta que se conecte a Application Insights.
Nota:
El patrón que se describe en este artículo es para escenarios avanzados y datos de la secuencia de clics generados por el código que agrega al cliente. Por el contrario, los registros de servicio son fáciles de configurar, proporcionan una gama de métricas y se pueden realizar en el portal sin necesidad de código. Se recomienda habilitar el registro para todos los escenarios. Para obtener más información, consulte Recopilación y análisis de datos de registro.
Identificación de los datos de búsqueda pertinentes
Para contar con métricas útiles para el análisis del tráfico de búsqueda, es necesario registrar algunas de las señales de los usuarios de la aplicación de búsqueda. Estas señales indican el contenido en el que los usuarios están interesados y que consideran relevantes. Para el análisis del tráfico de búsqueda, se incluyen:
Eventos de búsqueda generados por el usuario: solo son interesantes las consultas de búsqueda iniciadas por un usuario. Otras solicitudes de búsqueda, como las que se usan para rellenar las facetas o recuperar información interna, no son importantes. Asegúrese de instrumentar solo eventos iniciados por el usuario para evitar la distorsión o el sesgo en los resultados.
Eventos de clic generados por el usuario: en una página de resultados de la búsqueda, un evento de clic habitualmente significa que un documento es un resultado pertinente para una consulta de búsqueda específica.
Al vincular los eventos de búsqueda y clic con un id. de correlación, comprenderá mejor el rendimiento de la funcionalidad de búsqueda de su aplicación.
Incorporación de los análisis del tráfico de búsqueda
En la página del portal del servicio Azure AI Search, abra la página de análisis de tráfico de búsqueda para acceder a una hoja de referencia con la que podrá seguir este patrón de telemetría. Desde esta página, puede seleccionar o crear un recurso de Application Insights, obtener la clave de instrumentación, copiar fragmentos de código que se puedan adaptar a la solución y descargar un informe de Power BI que se base en el esquema que se refleja en el patrón.
1. Configuración de Application Insights
Seleccione un recurso existente de Application Insights o cree uno si aún no lo tiene. Si usa la página Análisis de tráfico de búsqueda, puede copiar la clave de instrumentación que necesita la aplicación para conectarse a Application Insights.
Una vez que tenga un recurso de Application Insights, puede seguir las instrucciones para los lenguajes y las plataformas admitidos para registrar la aplicación. El registro consiste simplemente en agregar la clave de instrumentación de Application Insights al código, con lo que se configura la asociación. Puede encontrar la clave en el portal o en la página Análisis de tráfico de búsqueda al seleccionar un recurso existente.
En los pasos siguientes se refleja un acceso directo que funciona en algunos tipos de proyecto de Visual Studio. Crea un recurso y registra la aplicación en unos pocos clics.
Para el desarrollo en Visual Studio y ASP.NET, abra la solución y seleccione Proyecto>Agregar telemetría de Application Insights.
Haga clic en Introducción.
Registre su aplicación proporcionando un cuenta de Microsoft, una suscripción a Azure y un recurso de Application Insights (el valor predeterminado es un nuevo recurso). Haga clic en Registrar.
En este punto, la aplicación está configurada para la supervisión de aplicaciones, lo que significa que se realiza un seguimiento de todas las cargas de páginas con las métricas predeterminadas. Para obtener más información sobre los pasos anteriores, consulte Habilitación de la telemetría de Application Insights del lado servidor.
2- Incorporación de la instrumentación
En este paso se instrumenta su propia aplicación de búsqueda con el recurso de Application Insights creado en el paso anterior. Este proceso tiene cuatro pasos, empezando por la creación de un cliente de telemetría.
Paso 1: Creación de un cliente de telemetría
Cree un objeto que envíe eventos a Application Insights. Puede agregar instrumentación al código de aplicación del lado servidor o al código del lado cliente que se ejecuta en un explorador, expresado aquí como variantes de C# y JavaScript (para otros lenguajes, consulte la lista completa de plataformas y marcos compatibles. Elija el enfoque que le proporcione la profundidad deseada de información.
Los datos de telemetría del lado servidor capturan métricas en la capa de aplicación, por ejemplo, en aplicaciones que se ejecutan como servicio web en la nube o como aplicación local en una red corporativa. Los datos de telemetría del lado servidor capturan los eventos de búsqueda y de clics, la posición de un documento en los resultados y la información de consulta, pero el ámbito de la colección de datos se limitará a la información que haya disponible en esa capa.
En el cliente, es posible que tenga código adicional que manipule las entradas de consulta, agregue navegación o incluya el contexto (por ejemplo, las consultas iniciadas desde una página principal en lugar de la página de un producto). Si esto describe su solución, puede optar por la instrumentación del lado cliente para que la telemetría refleje los detalles adicionales. La forma en que se recopilan estos detalles adicionales va más allá del ámbito de este patrón, pero puede revisar Application Insights para páginas web para obtener más instrucciones.
Uso de C#
En C#, InstrumentationKey debe definirse en la configuración de la aplicación, como appsettings.json si el proyecto es ASP.NET. Consulte las instrucciones de registro si no está seguro de la ubicación de la clave.
private static TelemetryClient _telemetryClient;
// Add a constructor that accepts a telemetry client:
public HomeController(TelemetryClient telemetry)
{
_telemetryClient = telemetry;
}
Uso de JavaScript
Para crear un objeto que envíe eventos a Application Insights mediante el script del cargador del SDK JavaScript (Web), consulte SDK de JavaScript de Microsoft Azure Monitor Application Insights.
Paso 2: Solicitud de un identificador de búsqueda para la correlación
Para correlacionar las solicitudes de búsqueda con clics, es necesario tener un identificador de correlación que relacione estos dos eventos distintos. Azure AI Search proporciona un identificador de búsqueda cuando se solicita con un encabezado HTTP.
Tener el identificador de búsqueda permite la correlación de las métricas emitidas por Azure AI Search para la solicitud en sí, con las métricas personalizadas que está registrando en Application Insights.
Uso de C# (SDK de V11 más reciente)
El SDK más reciente requiere el uso de una canalización http para establecer el encabezado, tal y como se detalla en este ejemplo.
// Create a custom policy to add the correct headers
public class SearchIdPipelinePolicy : HttpPipelineSynchronousPolicy
{
public override void OnSendingRequest(HttpMessage message)
{
message.Request.Headers.SetValue("x-ms-azs-return-searchid", "true");
}
}
// This sample uses the .NET SDK https://www.nuget.org/packages/Azure.Search.Documents
SearchClientOptions clientOptions = new SearchClientOptions();
clientOptions.AddPolicy(new SearchIdPipelinePolicy(), HttpPipelinePosition.PerCall);
var client = new SearchClient("<SearchServiceName>", "<IndexName>", new AzureKeyCredential("<QueryKey>"), options: clientOptions);
Response<SearchResults<SearchDocument>> response = await client.SearchAsync<SearchDocument>(searchText: searchText, searchOptions: options);
string searchId = string.Empty;
if (response.GetRawResponse().Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string> headerValues))
{
searchId = headerValues.FirstOrDefault();
}
Uso de C# (SDK de V10 anterior)
// This sample uses the .NET SDK https://www.nuget.org/packages/Microsoft.Azure.Search
var client = new SearchIndexClient(<SearchServiceName>, <IndexName>, new SearchCredentials(<QueryKey>));
// Use HTTP headers so that you can get the search ID from the response
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
string searchId = string.Empty;
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string> headerValues))
{
searchId = headerValues.FirstOrDefault();
}
Uso de JavaScript (llamando a las API de REST)
request.setRequestHeader("x-ms-azs-return-searchid", "true");
request.setRequestHeader("Access-Control-Expose-Headers", "x-ms-azs-searchid");
var searchId = request.getResponseHeader('x-ms-azs-searchid');
Paso 3: Registro de eventos de búsqueda
Cada vez que un usuario emite una solicitud de búsqueda, debe registrarla como un evento de búsqueda con el esquema siguiente en un evento personalizado de Application Insights. Recuerde registrar solo las consultas de búsqueda generadas por el usuario.
- SearchServiceName: (cadena) nombre del servicio de búsqueda
- SearchId: (guid) identificador único de la consulta de búsqueda (se incluye en la respuesta de la búsqueda)
- IndexName: (cadena) índice del servicio de búsqueda que se va a consultar
- QueryTerms: (cadena) términos de búsqueda especificados por el usuario
- ResultCount: (int) número de documentos devueltos (se incluye en la respuesta de la búsqueda)
- ScoringProfile: (cadena) nombre del perfil de puntuación usado, si existe
Nota:
Solicite el recuento de consultas generadas por el usuario agregando $count=true a la consulta de búsqueda. Para más información, consulte Búsqueda de documentos (REST).
Uso de C#
var properties = new Dictionary <string, string>
{
{"SearchServiceName", <service name>},
{"SearchId", <search Id>},
{"IndexName", <index name>},
{"QueryTerms", <search terms>},
{"ResultCount", <results count>},
{"ScoringProfile", <scoring profile used>}
};
_telemetryClient.TrackEvent("Search", properties);
Uso de JavaScript
appInsights.trackEvent("Search", {
SearchServiceName: <service name>,
SearchId: <search id>,
IndexName: <index name>,
QueryTerms: <search terms>,
ResultCount: <results count>,
ScoringProfile: <scoring profile used>
});
Paso 4: Registro de eventos de clic
Cada vez que un usuario hace clic en un documento, es una señal de que debe registrarse para fines de análisis de búsqueda. Utilice eventos personalizados de Application Insights para registrar estos eventos con el siguiente esquema:
- ServiceName: (cadena) nombre del servicio de búsqueda
- SearchId: (guid) identificador único de la consulta de búsqueda relacionada
- DocId: (cadena) identificador del documento
- Position: (int) clasificación del documento en la página de resultados de la búsqueda
Nota:
La posición hace referencia al orden cardinal en la aplicación. Puede establecer este número, siempre que en todo momento sea el mismo, para permitir la comparación.
Uso de C#
var properties = new Dictionary <string, string>
{
{"SearchServiceName", <service name>},
{"SearchId", <search id>},
{"ClickedDocId", <clicked document id>},
{"Rank", <clicked document position>}
};
_telemetryClient.TrackEvent("Click", properties);
Uso de JavaScript
appInsights.trackEvent("Click", {
SearchServiceName: <service name>,
SearchId: <search id>,
ClickedDocId: <clicked document id>,
Rank: <clicked document position>
});
3- Análisis en Power BI
Una vez que haya instrumentado la aplicación y comprobado que esta se ha conectado correctamente a Application Insights, debe descargar una plantilla de informe predefinida para analizar los datos en Power BI Desktop. El informe contiene tablas y gráficos predefinidos útiles para analizar los datos adicionales que se capturaron para los análisis de tráfico de búsqueda.
En el panel de navegación izquierdo de Azure AI Search, en Configuración, haga clic en Análisis de tráfico de búsqueda.
En la página Análisis de tráfico de búsqueda, en el paso 3, haga clic en Obtener Power BI Desktop para instalar Power BI.
En la misma página, haga clic en Descargar informe de Power BI.
El informe se abrirá en Power BI Desktop y se le pedirá que se conecte a Application Insights y proporcione las credenciales. Puede encontrar la información de conexión en las páginas de Azure Portal para el recurso de Application Insights. Para obtener las credenciales, proporcione el mismo nombre de usuario y la misma contraseña que usa para iniciar sesión en el portal.
Haga clic en Cargar.
El informe contiene gráficos y tablas que le ayudarán a tomar decisiones más informadas para mejorar la relevancia y el rendimiento de las búsquedas.
Las métricas incluyen los siguientes elementos:
- Busque los pares de términos y documentos más populares: términos resultantes en el mismo documento en el que se hizo clic, ordenados por clics.
- Búsquedas sin clics: términos de las consultas principales que no registran ningún clic
En la captura de pantalla siguiente se muestra el aspecto que podría tener un informe integrado si hubiese usado todos los elementos del esquema.
Pasos siguientes
Instrumente la aplicación de búsqueda para obtener datos eficaces y reveladores sobre el servicio de búsqueda.
Puede encontrar más información en Application Insights y visitar la página de precios para conocer más sobre los distintos niveles de servicio.
Obtenga más información sobre cómo crear informes increíbles. Consulte Introducción a Power BI Desktop para más información.