向 Azure AI 搜索索引中的字符串字段添加自定义分析器

自定义分析器是一个 tokenizer、一个或多个令牌筛选器以及一个或多个字符筛选器的用户定义组合。 自定义分析器是在搜索索引中指定的，然后在需要自定义分析的字段定义中由名称引用。 将根据每个字段调用自定义分析器。 字段上的属性将确定其是用于索引和/或查询。

在自定义分析器中，字符筛选器先准备输入文本，然后由 tokenizer 对其进行处理（例如，删除标记）。 接下来，tokenizer 将文本分解为标记。 最后，标记筛选器修改由 tokenizer 发出的标记。 有关概念和示例，请参阅 Azure AI 搜索中的分析器。

为什么要使用自定义分析器？

自定义分析器可以使得允许通过选择要调用的分析或筛选类型以及它们出现的顺序来控制将文本转换为可索引和可搜索的标记的过程。

如果默认 (Standard Lucence)、内置或语言分析器都不能满足你需求，则创建并分配自定义分析器。 如果要将内置分析器与自定义选项一同使用，还可以创建自定义分析器。 例如，如果要更改 Standard 上的 maxTokenLength，可以使用用户定义的名称创建自定义分析器以设置该选项。

在下列情况下，自定义分析器可能很有用处：

• 在文本输入被标记之前使用字符筛选器删除 HTML 标记，或者替换特定字符或符号。

• 拼音搜索。 添加一个拼音筛选器，以便根据字词的发音方式而不是拼写方式进行搜索。

• 禁用词法分析。 使用关键字分析器创建未分析的可搜索字段。

• 快速前缀/后缀搜索。 添加 Edge N 元语法标记筛选器以对字词前缀编制索引，从而启用快速前缀匹配。 将其与反向标记筛选器组合使用，以执行后缀匹配。

• 自定义词汇切分。 例如，借助空格 tokenizer，通过将空格用作分隔符来将句子分解成标记

• ASCII 折叠。 添加标准 ASCII 折叠筛选器以规范化搜索词中的音调符号，如 ö 或 ê。

创建自定义分析器

若要创建自定义分析器，请设计时在索引的 analyzers 部分指定它，然后使用 analyzer 属性或者 indexAnalyzer 和 searchAnalyzer 对在可搜索的 Edm.String 字段上引用它。

分析器定义包括名称、类型、一个或多个字符筛选器、最多一个 tokenizer，以及一个或多个用于后期词汇切分处理的标记筛选器。 字符筛选器在词汇切分前应用。 标记筛选器和字符筛选器按从左到右的顺序应用。

• 自定义分析器中的名称必须是唯一的，并且不能与内置分析器、tokenizer、标记筛选器或字符筛选器中的任一者相同。 它必须仅包含字母、数字、空格、短划线或下划线，只能以字母数字字符开头和结尾，且最多包含 128 个字符。

• 类型必须是 #Microsoft.Azure.Search.CustomAnalyzer。

• charFilters 可以是字符筛选器中的一个或多个筛选器，这些筛选器按照提供的顺序在词汇切分之前进行处理。 某些字符筛选器包含选项，可在 charFilters 部分设置这些选项。 字符筛选器是可选的。

• tokenizer 正好是一个 Tokenizer。 值是必选的。 如果需要多个 tokenizer，则可以创建多个自定义分析器，并在索引架构中逐个字段地分配它们。

• tokenFilters 可以是标记筛选器中的一个或多个筛选器，这些筛选器按照提供的顺序在词汇切分之后进行处理。 对于具有选项的标记筛选器，添加 tokenFilter 部分以指定配置。 标记筛选器是可选的。

分析器不得生成超过300个字符的标记，否则索引将失败。 若要剪裁或排除长标记，请分别使用 “TruncateTokenFilter” 和 “LengthTokenFilter”。 请参阅标记筛选器进行参考。

"analyzers":(optional)[
   {
      "name":"name of analyzer",
      "@odata.type":"#Microsoft.Azure.Search.CustomAnalyzer",
      "charFilters":[
         "char_filter_name_1",
         "char_filter_name_2"
      ],
      "tokenizer":"tokenizer_name",
      "tokenFilters":[
         "token_filter_name_1",
         "token_filter_name_2"
      ]
   },
   {
      "name":"name of analyzer",
      "@odata.type":"#analyzer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"charFilters":(optional)[
   {
      "name":"char_filter_name",
      "@odata.type":"#char_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenizers":(optional)[
   {
      "name":"tokenizer_name",
      "@odata.type":"#tokenizer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenFilters":(optional)[
   {
      "name":"token_filter_name",
      "@odata.type":"#token_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
]

在索引定义中，可以将此节放在创建索引请求正文中的任意位置，但通常将它放在末尾：

{
  "name": "name_of_index",
  "fields": [ ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": (optional) "...",
  "corsOptions": (optional) { },
  "analyzers":(optional)[ ],
  "charFilters":(optional)[ ],
  "tokenizers":(optional)[ ],
  "tokenFilters":(optional)[ ]
}

分析器定义是较大索引的一部分。 只有在设置自定义选项时，才向索引添加字符筛选器、tokenizer 和标记筛选器的定义。 若要按原样使用现有筛选器或 tokenizer，请在分析器定义中按名称指定它。 有关详细信息，请参阅创建索引 (REST)。 有关更多示例，请参阅在 Azure AI 搜索中添加分析器。

测试自定义分析器

可以使用测试分析器 (REST) 来查看分析器如何将给定文本分解成多个标记。

请求

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

  {
     "analyzer":"my_analyzer",
     "text": "Vis-à-vis means Opposite"
  }

响应

  {
    "tokens": [
      {
        "token": "vis_a_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "vis_à_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "means",
        "startOffset": 10,
        "endOffset": 15,
        "position": 1
      },
      {
        "token": "opposite",
        "startOffset": 16,
        "endOffset": 24,
        "position": 2
      }
    ]
  }

更新自定义分析器

定义分析器、tokenizer、标记筛选器或字符筛选器后，便无法修改它。 仅当 allowIndexDowntime 标志在索引更新请求中设置为 true 时，才可向现有索引添加新的上述内容：

PUT https://[search service name].search.azure.cn/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

此操作将使索引离线至少几秒钟，从而导致索引和查询请求失败。 索引的性能和写入可用性可能会在更新索引后的几分钟内处于受损状态，对于非常大的索引，持续时间更长，但这些影响只是暂时的，最终将自行解除。

内置分析器

如果要使用具有自定义选项的内置分析器，则创建自定义分析器是用于指定这些选项的机制。 相反，若要按原样使用内置分析器，只需在字段定义中按名称引用即可。

¹ 分析器类型在代码中始终使用前缀 #Microsoft.Azure.Search，以使 PatternAnalyzer 实际指定为 #Microsoft.Azure.Search.PatternAnalyzer。 为简洁起见，我们删除了该前缀，但在代码中需要使用该前缀。

analyzer_type 仅适用于可自定义的分析器。 如果没有选项（比如关键字分析器），则没有关联的 #Microsoft.Azure.Search 类型。

字符筛选器

字符筛选器在字符串到达标记器之前添加处理。

Azure AI 搜索支持以下列表中的字符筛选器。 有关各自的详细信息，请参阅 Lucene API 参考。

¹ 字符筛选器类型在代码中始终使用前缀 #Microsoft.Azure.Search，以使 MappingCharFilter 实际指定为 #Microsoft.Azure.Search.MappingCharFilter。 为缩小表的宽度，我们删除了该前缀，但请记住在代码中包含该前缀。 请注意，char_filter_type 仅适用于可自定义的筛选器。 如果没有选项（比如 html_strip），则没有关联的 #Microsoft.Azure.Search 类型。

Tokenizer

Tokenizer 将连续文本划分为一系列标记，例如将一个句子分解成多个字词，或者将一个单词分解为字根形式。

Azure AI 搜索支持以下列表中的 tokenizer。 有关各自的详细信息，请参阅 Lucene API 参考。

¹ Tokenizer 类型在代码中始终使用前缀 #Microsoft.Azure.Search，以使 ClassicTokenizer 实际指定为 #Microsoft.Azure.Search.ClassicTokenizer。 为缩小表的宽度，我们删除了该前缀，但请记住在代码中包含该前缀。 请注意，tokenizer_type 仅适用于可自定义的 tokenizer。 如果没有选项（比如字母 tokenizer），则没有关联的 #Microsoft.Azure.Search 类型。

标记筛选器

标记筛选器用于筛选出或修改由 tokenizer 生成的标记。 例如，可以指定将所有字符转换为小写的小写筛选器。 可以在自定义分析器中使用多个标记筛选器。 标记筛选器按其列出的顺序运行。

在下表中，使用 Apache Lucene 实现的标记筛选器已链接到相应的 Lucene API 文档。

¹ 令牌筛选器类型在代码中始终使用前缀 #Microsoft.Azure.Search，以使 ArabicNormalizationTokenFilter 实际指定为 #Microsoft.Azure.Search.ArabicNormalizationTokenFilter。 为缩小表的宽度，我们删除了该前缀，但请记住在代码中包含该前缀。

另请参阅

• Azure AI 搜索 REST API
• Azure AI 搜索中的分析器（示例）
• 创建索引 (REST)