收集遥测数据以用于分析搜索流量

项目
09/09/2024

搜索流量分析是一种模式，用于收集有关用户与 Azure AI 搜索应用程序之间的交互（例如用户发起的单击事件和键盘输入）的遥测数据。使用此信息，你可以确定搜索解决方案的有效性，包括热门搜索词、点击率以及哪些查询输入产生了零个结果。

此模式依赖于 Application Insights（Azure Monitor 的一项功能）来收集用户数据。你还需要向客户端代码中添加检测机制，如本文中所述。最后，需要使用报告机制分析数据。建议使用 Power BI，但你可以使用连接到 Application Insights 的任何可视化工具。

注意

本文中所述的模式适用于你添加到客户端的代码生成的高级方案和点击流数据。相比之下，服务日志易于设置，提供各种指标，且无需编写任何代码即可在门户中操作。建议对所有方案启用日志记录。有关详细信息，请参阅收集和分析日志数据。

标识相关的搜索数据

若要为搜索流量分析提供有用的指标，必须记录搜索应用程序用户发出的一些信号。这些信号表示用户感兴趣的内容以及他们认为相关的内容。对于搜索流量分析，这些信号包括：

用户生成的搜索事件：只有用户发起的搜索查询才是需要关注的。其他搜索请求（例如用于填充方面或检索内部信息的搜索请求）并不重要。请确保只检测用户启动的事件，以避免结果中出现扭曲或偏差。
用户生成的单击事件：在搜索结果页上，单击事件通常意味着某个文档是特定搜索查询的相关结果。

将搜索和单击事件链接到相关 ID，可以更深入地了解应用程序搜索功能的表现。

添加搜索流量分析

在 Azure AI 搜索服务的门户页中，打开“搜索流量分析”页，以访问用于遵循此遥测模式的速查表。在此页中，可以选择或创建一个 Application Insights 资源，获取检测密钥，复制可以根据你的解决方案改编的代码片段，并下载基于模式中反映的架构生成的 Power BI 报表。

步骤 1：设置 Application Insights

选择现有的 Application Insights 资源，如果没有 Application Insights 资源，则创建一个资源。

以下步骤反映了适用于某些 Visual Studio 项目类型的快捷方式。

例如，这些步骤从将搜索添加到静态 Web 应用使用客户端。

在 Visual Studio 中打开解决方案。
在“项目”菜单上，选择“连接服务”“添加”“Azure Application Insights”>>。
在“连接到依赖项”中，依次选择“Azure Application Insights”、“下一步”。
依次选择 Azure 订阅、Application Insights 资源、“完成”。

此时，已经为应用程序监视设置了应用程序，这意味着，会使用默认指标跟踪客户端应用中的所有页面加载。

如果此快捷方式不起作用，请参阅启用 Application Insights 服务器端遥测。

步骤 2：添加检测

将检测代码添加到客户端应用程序。 Azure 门户中的搜索流量分析页提供了可粘贴到应用程序代码中的代码片段。

创建遥测客户端

创建一个用于将事件发送到 Application Insights 的对象。可以将检测机制添加到服务器端应用程序代码中或在浏览器中运行的客户端代码中，此处的代码以 C# 和 JavaScript 变体表示。有关其他语言，请参阅受支持的平台和框架。

服务器端遥测将捕获应用程序层（例如，在 Azure 上作为 Web 服务运行的应用程序，或者在企业网络中作为本地应用运行的应用程序）的指标。服务器端遥测捕获搜索和单击事件、结果中文档的位置以及查询信息，但数据收集范围将限定为该层上可用的任何信息。

在客户端上，可以使用附加的代码来操作查询输入、添加导航或包含上下文（例如，从主页或产品页发起的查询）。如果这种描述符合你的解决方案，可以选择启用客户端检测，使遥测数据反映额外的详细信息。如何收集这些额外的详细信息超出了此模式的范围，但你可以查看适用于网页的 Application Insights以获取有关该决定的帮助。

可以从 Azure 门户中获取检测密钥，无论是在 Application Insights 的页面中，还是在 Azure AI 搜索的搜索流量分析页中。

// Application Insights SDK: https://www.nuget.org/packages/Microsoft.ApplicationInsights.Web 

var telemetryClient = new TelemetryClient();
telemetryClient.InstrumentationKey = "0000000000000000000000000000";

请求用于关联的搜索 ID

重要

在 Azure 门户中，请求头的片段是使用过时版本的 Azure SDK 生成的。更新处于挂起状态。

为了将搜索请求与单击相关联，必须具有一个将这两个不同事件关联起来的相关性 ID。使用 HTTP 标头请求搜索 ID 时，Azure AI 搜索将提供该 ID。

使用搜索 ID 可将 Azure AI 搜索为请求本身发出的指标关联到在 Application Insights 中记录的自定义指标。

var client = new SearchClient(<SEARCH SERVICE NAME>, <INDEX NAME>, new AzureDefaultCredentials())
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);
IEnumerable<string> headerValues;
string searchId = string.Empty;
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
	 searchId = headerValues.FirstOrDefault();
}

记录搜索事件

每当用户发出搜索请求时，应在 Application Insights 自定义事件上使用以下架构，将该请求记录为一个搜索事件。请记得仅记录用户生成的搜索查询。

SearchServiceName：（字符串）搜索服务名称
SearchId：(GUID) 搜索查询的唯一标识符（位于搜索响应中）
IndexName：（字符串）要查询的搜索服务索引
QueryTerms：（字符串）用户输入的搜索字词
ResultCount：（整数）返回的文档数（位于搜索响应中）
ScoringProfile：（字符串）使用的评分配置文件的名称（如果有）

注意

通过向搜索查询添加 $count=true 来请求用户生成的查询的计数。有关详细信息，请参阅搜索文档 (REST)。

var properties = new Dictionary <string, string> {
	{"SearchServiceName", <SEARCH SERVICE NAME>},
	{"SearchId", <SEARCH ID>},
	{"IndexName", <INDEX NAME>},
	{"QueryTerms", <SEARCH TERMS>},
	{"ResultCount", <RESULTS COUNT>},
	{"ScoringProfile", <SCORING PROFILE USED>}
};

telemetryClient.TrackEvent("Search", properties);

记录单击事件

每次用户单击文档，都是一个必须记录以用于搜索分析的信号。使用 Application Insights 自定义事件可利用下面的架构来记录这些事件：

ServiceName：（字符串）搜索服务名称
SearchId：(GUID) 相关搜索查询的唯一标识符
DocId：（字符串）文档标识符
Position：（整数）文档在搜索结果页中的排名

注意

Position 指的是应用程序中的基数顺序。可以随意设置此数字以用于比较，只要它始终相同。

var properties = new Dictionary <string, string> {
	{"SearchServiceName", <SEARCH SERVICE NAME>},
	{"SearchId", <SEARCH ID>},
	{"ClickedDocId", <CLICKED DOCUMENT ID>},
	{"Rank", <CLICKED DOCUMENT POSITION>}
};

telemetryClient.TrackEvent("Click", properties);

步骤 3：在 Power BI 中分析

检测到应用并确认应用程序已正确连接到 Application Insights 后，下载一个预定义的报表模板以在 Power BI Desktop 中分析数据。报表包含预定义的图表和表，它们可用于分析为搜索流量分析捕获的额外数据。

在搜索服务页的 Azure 门户的“设置”下，选择“搜索流量分析”。
选择“获取 Power BI Desktop”以安装 Power BI。
选择“下载 Power BI 报表”以获取报表。
该报表将在 Power BI Desktop 中打开，且会提示你连接到 Application Insights 并提供凭据。可以在你的 Application Insights 资源的 Azure 门户页面中找到连接信息。对于凭据，请提供用于门户登录的相同用户名和密码。
选择“加载”。

该报表包含图表和表，可帮助你做出更明智的决策来提高搜索性能和相关性。

指标包括以下各项：

搜索量和最常用术语-文档对：导致同一文档被单击的词，按单击次数排序。
无单击的搜索：查询次数最多但未记录任何单击的词

以下屏幕截图显示了报表可能包含的数据元素。

后续步骤

检测搜索应用程序，以获取提供深入见解的有关搜索服务的强大数据。

你可以查找有关 Application Insights 的更多信息并访问定价页面来详细了解其各种服务层级。

详细了解如何创建报表。有关详细信息，请参阅 Power BI Desktop 入门。

通过