你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将拼写检查添加到Azure AI 搜索中的查询（预览版）

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

重要

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

在查询到达搜索引擎之前，可以通过对查询中的单词进行拼写更正来改善召回率。 参数speller（预览版）适用于所有文本（非向量）查询类型，可通过Azure门户、预览 REST API 和Azure SDK库的 beta 版本获得。

先决条件

  • 基本层或更高层的搜索服务（任何区域中）。

  • 具有 支持语言的内容的现有搜索索引。

  • 将 和 speller=lexicon 设置为queryLanguage的查询请求。 拼写检查适用于参数中传递的 search 字符串。 筛选器、模糊搜索、通配符搜索、正则表达式或矢量查询不支持它。

使用支持查询请求上的预览 API 的搜索客户端。 可以使用 Azure SDK 的 REST 客户端或 beta 版本。

客户端库 版本
REST API 版本 2020-06-30-Preview 及更高版本。 建议使用最新的预览版 API： 2026-08-01-preview
.NET的Azure SDK 版本 11.7.0-beta.4
Java的Azure SDK 版本 11.8.0-beta.7
适用于 JavaScript 的Azure SDK 版本 11.3.0-beta.8
Python的Azure SDK 版本 11.6.0b12

以下示例使用 hotels-sample 索引 来演示简单文本查询的拼写更正。 如果没有拼写更正，查询将返回零结果。 更正后，该查询返回一条结果（Johnson 家庭度假村）。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "famly acitvites",
    "speller": "lexicon",
    "queryLanguage": "en-us",
    "queryType": "simple",
    "select": "HotelId,HotelName,Description,Category,Tags",
    "count": true
}

使用完整 Lucene 进行拼写更正

拼写更正发生在进行文本分析的单个查询词上，这就是为什么可以将拼写检查器参数用于某些 Lucene 查询，而不是其他查询。

  • 绕过文本分析的不兼容查询表单包括：通配符、正则表达式、模糊查询
  • 兼容的查询表单包括：字段搜索、邻近查询、词项权重提升

此示例对采用完整 Lucene 语法并包含一个拼错的查询字词的“类别”字段使用字段搜索。 通过包含拼写检查器，“Suiite”中的拼写错误已得到更正，查询将会成功。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "Category:(Resort and Spa) OR Category:Suiite",
    "queryType": "full",
    "speller": "lexicon",
    "queryLanguage": "en-us",
    "select": "Category",
    "count": true
}

使用语义排名进行拼写更正

此查询在每个字词中出现拼写错误，但除一个字词外，都会进行拼写更正以返回相关结果。 若要了解详细信息，请参阅 “配置语义排名器”。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "hisotoric hotell wiht great restrant nad wiifi",
    "queryType": "semantic",
    "speller": "lexicon",
    "queryLanguage": "en-us",
    "searchFields": "HotelName,Tags,Description",
    "select": "HotelId,HotelName,Description,Category,Tags",
    "count": true
}

支持的语言

可以在下表中找到queryLanguage的有效值，这些值从支持的语言列表（REST API 参考）中复制而来。

语言 查询语言
英语 [EN] EN、EN-US（默认值）
西班牙语 [ES] ES、ES-ES（默认值）
法语 [FR] FR、FR-FR （默认值）
德语 [DE] DE、DE-DE（默认值）
荷兰语 [NL] NL、NL-BE、NL-NL（默认值）

注意

以前，虽然语义排名器处于预览状态，但 queryLanguage 参数也用于语义排名。 语义排名器现在与语言无关。

语言分析器注意事项

包含非英语内容的索引通常对非英语字段使用 语言分析器 来应用本机语言的语言规则。

向同时进行语言分析的内容添加拼写检查时，可以对每个索引和查询处理步骤使用相同的语言获得更好的结果。 例如，如果使用“fr.microsoft”语言分析器为字段的内容编制索引，则查询和拼写检查应全部使用某种形式的法语词典或语言库。

回顾Azure AI 搜索中使用语言库的方式：

  • 可以在索引编制和查询执行期间调用语言分析器，并且是 Apache Lucene（例如“de.lucene”）或Microsoft（“de.microsoft）。

  • 在拼写检查期间调用的语言词典是使用 受支持语言 表中的语言代码之一指定的。

在查询请求中，分配给 queryLanguage 的值将应用于 speller。

注意

仅当使用语言分析器时，各种属性值之间的语言一致性才值得关注。 如果使用与语言无关的分析器（例如关键字、简单、标准、停止、空格或 standardasciifolding.lucene），则 queryLanguage 值可以是所需的任意值。

虽然搜索索引中的内容可以由多种语言组成，但查询输入很可能在一种中。 搜索引擎不会检查语言分析器的兼容性 queryLanguage以及内容撰写的语言，因此请务必相应地限定查询范围，以避免产生不正确的结果。

后续步骤

  • Last updated on