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

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

项目
12/10/2024

重要

根据补充使用条款，此功能以公共预览版提供。预览版 REST API 支持此功能。

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

通过应用规范化程序，可以实现简单文本转换，从而改善结果：

一致的大小写（例如全部小写或大写）
将 ö 或 ê 等重音和音调符号规范化为 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”属性设置为以下值之一：预定义的规范化程序（例如“lowercase”），或自定义规范化程序（在同一索引架构中定义）。
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "filterable": true,
   "analyzer": "en.microsoft",
   "normalizer": "lowercase"
   ...
 }
]
```
先在索引的“normalizers”部分中定义自定义规范化器，然后将它们分配给字段定义，如前一步中所示。有关详细信息，请参阅创建索引和添加自定义规范化器。
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "analyzer": null,
   "normalizer": "my_custom_normalizer"
 },
```

注意

若要更改现有字段的规范化程序，请重新生成整个索引（不能重新生成单个字段）。

生成索引（其中重新生成索引成本高昂）的一种好办法是，创建一个与旧字段相同的新字段，但使用新的规范化器，用它代替旧字段。使用 Update Index 合并新字段，使用 mergeOrUpload 填充该字段。之后在计划索引服务中，可清除索引以删除过时字段。

预定义的和自定义规范化器

Azure AI 搜索提供内置的规范化器用于常见用例，同时还可以根据需要进行自定义。

类别	说明
预定义的规范化器	开箱即用，无需任何配置即可使用。
自定义规范化程序 ¹	用于高级方案。要求对现有元素组合进行用户定义的配置，包括字符和标记筛选器。

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

规范化器引用

预定义的规范化器

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

支持的字符筛选器

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

支持的标记筛选器

以下列表显示了规范化器支持的标记筛选器，它是自定义分析器中所用的整体标记筛选器的子集。

添加自定义规范化器

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

token_filter_name_1 是标记筛选器的名称，char_filter_name_1 和 char_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”是在索引定义的“normalizers”部分中定义的。
规范化器由两个字符筛选器和三个标记筛选器组成：省略、小写和自定义的 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
        }
     ]
  }

通过