在 Azure AI 搜索中创建全文查询

项目
12/18/2024

如果要为全文搜索生成查询，本文提供了设置请求的步骤。本文还介绍了查询结构，并说明了字段属性和语言分析器如何影响查询结果。

先决条件

搜索索引，字符串字段属性为“可搜索”。
对搜索索引的读取权限。若要进行读取访问，请在请求中包含查询 API 密钥，或者向调用方提供“搜索索引数据读者”权限。

全文查询请求的示例

在 Azure AI 搜索中，查询是针对单个搜索索引的文档集合发出的只读请求，其参数既用于通知查询执行又用于形成返回的响应。

全文查询在 search 参数中指定，由字词、带引号的短语和运算符组成。其他参数将更多定义添加到请求。

以下搜索 POST REST API 调用说明了使用上述参数的查询请求。

POST https://[service name].search.azure.cn/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": 10,
    "count": true
}

要点

search 提供匹配条件（通常是整个搜索词或短语，带或不带运算符）。在索引架构中设置了 searchable 属性的任何字段都适合指定此参数。
queryType 设置分析程序：简单、完整。默认的简单查询分析程序最适合全文搜索。完整的 Lucene 查询分析程序适用于高级查询构造，如正则表达式、邻近搜索、模糊和通配符搜索。
searchMode 指定是根据表达式中的“所有”条件（精准率优先）还是“任一”条件（召回率优先）进行匹配。默认为任意。如果你预计会大量使用布尔运算符（在包含大文本块（内容字段或长描述）的索引中较可能发生这种情况），请确保使用 searchMode=Any|All 参数测试查询，以评估该设置对布尔搜索的影响。
searchFields 将查询执行约束为特定的可搜索字段。在开发过程中，为选择和搜索使用同一字段列表会很有帮助。否则，匹配可能是基于你无法在结果中看到的字段值，从而导致不确定返回文档的原因。

用于形成响应的参数：

select 指定要在响应中返回哪些字段。仅可在 select 语句中使用索引内标记为“可检索”的字段。
top 返回指定数目的最匹配的文档。在本例中，仅返回 10 个命中项。你可使用 top 和 skip（未显示）分页显示结果。
count 指出整体上整个索引中多少文档匹配，该数目可能比返回的数目多。
如果你想要按值（例如排名或位置）对结果分类，则使用 orderby。否则，默认使用相关性分数对结果进行排名。字段的属性必须设置为“可排序”才能成为此参数的可能值。

选择客户端

要进行早期开发和概念证明测试，请使用 Azure 门户或 REST 客户端。这两种方法都是交互式的，可用于有针对性的测试，有助于评估不同属性的影响，而无需编写任何代码。

若要从应用内调用搜索，请在适用于 .NET、Java、JavaScript 和 Python 的 Azure SDK 中使用 Azure.Document.Search 客户端库。

在门户中，打开索引时，可以使用搜索资源管理器以及并排选项卡中的索引 JSON 定义，以便轻松访问字段属性。检查“字段”表以查看哪些字段在测试查询时可搜索、可排序、可筛选和可分面。

登录到 Azure 门户并查找你的搜索服务。
在服务中，选择“索引”，然后选择一个索引。
索引将打开“搜索资源管理器”选项卡，以便你可以立即查询。切换到 JSON 视图以指定查询语法。

下面是适用于 Hotels 示例索引的全文搜索查询表达式：
```
   {
       "search": "pool spa +airport",
       "queryType": "simple",
       "searchMode": "any",
       "searchFields": "Description, Tags",
       "select": "HotelName, Description, Tags",
       "top": 10,
       "count": true
   }
```
以下屏幕截图演示了查询和响应：

使用 REST 客户端设置请求。如需入门帮助信息，请参阅快速入门：使用 REST 进行文本搜索。

以下示例调用 REST API 进行全文搜索：

POST https://[service name].search.azure.cn/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

以下 Azure SDK 提供了一个 SearchClient，其中包含用于制定查询请求的方法。

Azure SDK	客户端	示例
.NET	SearchClient	DotNetHowTo
Java	SearchClient	SearchForDynamicDocumentsExample.java
Javascript	SearchClient	Pending。
Python	SearchClient	sample_simple_query.py

选择查询类型：简单 | 完整

如果查询是全文搜索，查询分析器将用于处理作为搜索词和短语传递的任何文本。 Azure AI 搜索提供了两个查询分析器。

简单分析程序理解简单查询语法。选择此分析程序作为默认分析程序是因为它在自由格式文本查询中的速度和有效性。该语法支持将常见搜索运算符（AND、OR、NOT）用于术语和短语搜索，以及前缀 (*) 搜索（例如，使用 sea* 搜索 Seattle 和 Seaside）。一般建议首先尝试使用简单版分析程序，如果应用程序需要更强大的查询，则可以改用完整版分析程序。
向请求添加 queryType=full 时启用的完整 Lucene 查询语法基于 Apache Lucene 分析程序。

虽然完整语法和简单语法存在重叠，都支持相同的前缀和布尔运算，但完整语法提供了更多的运算符。在完整语法中，布尔表达式有了更多运算符，高级查询（如模糊搜索、通配符搜索、邻近搜索和正则表达式）也有了更多运算符。

选择查询方法

搜索本质上是一个用户驱动的活动，该活动从搜索框或页面上的单击事件中收集术语或短语。下表总结了收集用户输入的机制以及预期的搜索体验。

输入	体验
搜索方法	用户在搜索框中键入术语或短语（不一定带运算符），然后选择“搜索”发送请求。搜索可与筛选器一起用于同一请求，但不能与自动完成或建议一起使用。
“自动完成”方法	用户键入几个字符，然后在键入每个新字符后启动查询。响应是索引中的已完成字符串。如果提供的字符串有效，则用户选择“搜索”将该查询发送到服务。
“建议”方法	与自动完成一样，用户键入几个字符并生成增量查询。响应是匹配文档的下拉列表，通常由几个唯一或描述性字段表示。如果任何一个选择有效，用户选择其中一个，就会返回匹配的文档。
多面导航	页面显示可单击的导航链接或导航痕迹，缩小了搜索范围。分面导航结构基于初始查询动态组合。例如，`search=*` 可用于填充由每个可能的类别组成的分面导航树。分面导航结构是从查询响应创建的，但它也是表示下一个查询的机制。在 REST API 引用中，`facets` 作为“搜索文档”操作的查询参数记录，但是它可以在没有 `search` 参数的情况下使用。
筛选器方法	筛选器与分面一起使用，以缩小结果范围。你还可以在页面后面实现一个筛选器，例如用特定于语言的字段初始化页面。在 REST API 引用中，`$filter` 作为“搜索文档”操作的查询参数记录，但是它可以在没有 `search` 参数的情况下使用。

字段属性对查询的影响

如果你熟悉查询类型和组合，可能还记得查询请求上的参数取决于字段在索引中的属性。例如，查询和搜索结果中只能使用标记为“可搜索”和“可检索”的字段。在请求中设置 search、filter 和 orderby 参数时，应检查属性以避免意外结果。

在下面的酒店示例索引屏幕截图中，只有最后两个字段“LastRenovationDate”和“Rating”是可排序的，这是在 "$orderby" only 子句中使用的要求。

有关字段属性定义，请参阅创建索引 (REST API)。

标记对查询的影响

在索引过程中，搜索引擎对字符串使用文本分析器，以最大程度地提高在查询时找到匹配项的可能性。字符串至少是小写的，但根据分析器的情况，也可能需要进行词形还原和停用词删除。较大的字符串或复合词通常由空格、连字符或短划线分隔，并作为单独的标记编制索引。

要点是，你认为索引包含的内容和索引实际包含的内容可能会有所不同。如果查询没有返回预期的结果，则可以通过分析文本 (REST API) 检查分析器创建的标记。有关词汇切分及其对查询的影响的详细信息，请参阅具有特殊字符的部分术语搜索和模式。

现在你已经更好地了解了查询请求的工作原理，可以尝试以下快速入门以获得实际操作经验。

通过