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

用于不区分大小写的筛选、分面和排序的文本规范化

注意

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

在 Azure AI 搜索中，“规范化器”是一个组件，用于预处理标记为“可筛选”、“可分面”或“可排序”的字段的关键字匹配文本。与与文本分析器配对的全文“可搜索”字段相比，为筛选分面排序操作创建的内容不会进行分析或标记化。当出现大小写和字符差异时，文本分析的遗漏可能会产生意外的结果，这就是为什么你需要规范化器来使内容中的变体同质化。

通过应用规范化器，可以实现可改善结果的浅文本转换：

一致的大小写（如所有小写或大写）
规范化重音符号和附加符号，如 ö 或 ê 至 ASCII 等效字符“o”和“e”
将字符（如 - 和空格）映射到用户指定的字符

规范化器的优点

从搜索索引中搜索和检索文档需要将查询输入与文档的内容匹配。匹配是通过标记化的内容进行，就像调用“搜索”时一样，或者在请求是筛选器、 Facet 或 orderby 操作时对非标记化内容进行匹配。

由于不分析非标记化内容，因此内容中的小差异会评估为明显不同的值。请考虑以下示例：

$filter=City eq 'Las Vegas' 将仅返回包含确切文本“"Las Vegas"”的文档，并排除包含“"LAS VEGAS"”和“"las vegas"”的文档，在用例需要所有文档而不考虑大小写时，这并不充分。
search=*&facet=City,count:5 将返回 "Las Vegas"， "LAS VEGAS" 并且 "las vegas" 作为非重复值，尽管是相同的城市。
search=usa&$orderby=City 将按字典顺序返回城市：“"Las Vegas"”、“"Seattle"”、“"las vegas"”，即使意图是不分大小写地将相同城市排在一起也是如此。

规范化程序在编制索引和查询执行期间调用，它添加了一些简单的转换，可以消除筛选器、facet 和排序场景中的文本差异。在前面的示例中，"Las Vegas" 的不同形式将根据您选择的规范化器（例如，所有文本都转为小写）进行处理，以获得更为统一的结果。

如何指定规范化器

在索引定义中，按字段对文本字段（Edm.String 和 Collection(Edm.String)）指定规范化器，“filterable”、“sortable”或“facetable”属性中至少有一个设置为 true。设置规范化器是可选的，默认情况下为 null。建议在配置自定义规范化程序之前评估预定义规范化程序。

规范化程序只能在向索引添加新字段时指定，因此，如果可能，请尝试在删除和重新创建索引时提前评估规范化需求，并在开发的初始阶段分配规范化器。

在索引中创建字段定义时，将“normalizer”属性设置为以下值之一：预定义规范化程序（如“小写”）或自定义规范化程序（在同一索引架构中定义）。

"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "filterable": true,
   "analyzer": "en.microsoft",
   "normalizer": "lowercase"
   ...
 }
]

自定义规范器首先在索引的“规范器”部分中定义，然后分配给字段定义，如上一步所示。有关详细信息，请参阅 “创建索引 ”，并添加自定义规范化程序。
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "analyzer": null,
   "normalizer": "my_custom_normalizer"
 },
```

注意

若要更改现有字段的规范化程序，请完全重新生成索引（无法重新生成单个字段）。

对于生产索引来说，重建索引成本高昂的一个好解决方法是创建一个与旧索引相同的新字段，但使用新的规范化器，并将其用于代替旧字段。使用更新索引来合并新字段，并使用 mergeOrUpload 来填充该字段。稍后，作为计划索引服务的一部分，可以清理索引以删除过时的字段。

预定义和自定义规范化程序

Azure AI 搜索为常见用例提供内置规范化程序，并提供按需自定义的功能。

类别	描述
预定义规范化器	提供现装现用，无需任何配置即可使用。
自定义规范化器¹	用于高级方案。需要用户自定义配置，将现有元素组合在一起，包括字符和令牌过滤器。

⁽¹⁾ 自定义规范化器不指定 tokenizer，因为规范化器始终生成单个标记。

测试规范化器

可以使用测试分析器（REST）查看规范化器如何处理输入。

请求

  POST https://[search service name].search.windows.net/indexes/[index name]/analyze?api-version=[api-version]
    Content-Type: application/json
    api-key: [admin key]

  {
     "normalizer":"asciifolding",
     "text": "Vis-à-vis means Opposite"
  }

响应

HTTP/1.1 200 OK

{
  "tokens": [
    {
      "token": "Vis-a-vis means Opposite",
      "startOffset": 0,
      "endOffset": 24,
      "position": 0
    }
  ]
}

规范化器参考

预定义规范化器

名字	说明和选项
标准	先确定文本的大小写，再进行 asciifolding。
小写的	将字符转换为小写。
大写	将字符转换为大写。
asciifolding	将不在基本拉丁文 Unicode 块中的字符转换为其 ASCII 等效字符（如果存在）。例如，将 `à` 更改为 `a`。
elision	从标记开头删除省略。

支持的字符筛选器

规范化器支持两个字符筛选器，这些筛选器与自定义分析器字符筛选器中的对应筛选器相同：

支持的令牌筛选器

下面的列表显示了规范化器支持的令牌筛选器，是自定义分析器中使用的整体令牌筛选器的子集。

添加自定义规范化程序

自定义规范化程序在索引架构中定义。定义包括名称、类型、一个或多个字符筛选器和令牌筛选器。字符筛选器和标记筛选器是自定义规范化器的构建基块，负责处理文本。这些筛选器从左到右应用。

这是token_filter_name_1令牌筛选器的名称，也是char_filter_name_1char_filter_name_2字符筛选器的名称（有关有效值，请参阅下面的受支持令牌筛选器和支持的字符筛选器表）。

"normalizers":(optional)[
   {
      "name":"name of normalizer",
      "@odata.type":"#Microsoft.Azure.Search.CustomNormalizer",
      "charFilters":[
         "char_filter_name_1",
         "char_filter_name_2"
      ],
      "tokenFilters":[
         "token_filter_name_1"
      ]
   }
],
"charFilters":(optional)[
   {
      "name":"char_filter_name_1",
      "@odata.type":"#char_filter_type",
      "option1": "value1",
      "option2": "value2",
      ...
   }
],
"tokenFilters":(optional)[
   {
      "name":"token_filter_name_1",
      "@odata.type":"#token_filter_type",
      "option1": "value1",
      "option2": "value2",
      ...
   }
]

自定义规范化程序可以在创建索引期间添加，也可以通过更新现有的规范化程序在以后添加。将自定义规范化程序添加到现有索引需要更新索引中指定“allowIndexDowntime”标志，并将导致索引在几秒钟内不可用。

自定义规范化器示例

下面的示例演示了具有相应字符筛选器和标记筛选器的自定义规范化器定义。字符筛选器和标记筛选器的自定义选项分别指定为命名构造，然后在规范化器定义中引用，如下所示。

名为“my_custom_normalizer”的自定义规范化程序在索引定义的“规范化器”部分中定义。
规范化器由两个字符筛选器和三个标记筛选器组成：省略、小写和自定义的 asciifolding 筛选器“my_asciifolding”。
第一个字符筛选器“map_dash”将所有短划线替换为下划线，而第二个“remove_whitespace”将删除所有空格。

  {
     "name":"myindex",
     "fields":[
        {
           "name":"id",
           "type":"Edm.String",
           "key":true,
           "searchable":false,
        },
        {
           "name":"city",
           "type":"Edm.String",
           "filterable": true,
           "facetable": true,
           "normalizer": "my_custom_normalizer"
        }
     ],
     "normalizers":[
        {
           "name":"my_custom_normalizer",
           "@odata.type":"#Microsoft.Azure.Search.CustomNormalizer",
           "charFilters":[
              "map_dash",
              "remove_whitespace"
           ],
           "tokenFilters":[              
              "my_asciifolding",
              "elision",
              "lowercase",
           ]
        }
     ],
     "charFilters":[
        {
           "name":"map_dash",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["-=>_"]
        },
        {
           "name":"remove_whitespace",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["\\u0020=>"]
        }
     ],
     "tokenFilters":[
        {
           "name":"my_asciifolding",
           "@odata.type":"#Microsoft.Azure.Search.AsciiFoldingTokenFilter",
           "preserveOriginal":true
        }
     ]
  }

另请参阅

反馈

此页面是否有帮助？

Last updated on 2026-07-03