在 Azure AI 搜索中添加同义词

项目
12/18/2024

在搜索服务中，同义词映射对等效字词进行关联，从而在无需用户实际提供字词的情况下扩展查询范围。例如，假设“狗”、“狗狗”和“小狗”为映射同义词，则对“狗狗”的查询会匹配包含“狗”的文档。如果你的内容包含行话、俚语或模糊术语，则你可以为不同的语言（例如英语和法语版本）或词典创建多个同义词映射。

下面是有关同义词映射的一些要点：

同义词映射是一种顶级资源，可以创建一次，然后供许多索引使用。
同义词映射适用于字符串字段。
你可以随时创建和分配同义词映射，且不会中断索引或查询。
你的服务层级设定了你可以创建的同义词映射数上限。
你的搜索服务可以有多个同义词映射，但在一个索引中，一个字段定义只能有一个同义词映射分配。

创建同义词映射

同义词映射由名称、格式和充当同义词映射条目的规则组成。唯一受支持的格式是 solr，solr 格式决定了规则构造。

若要创建同义词映射，请以编程方式进行。门户不支持同义词映射定义。

使用创建同义词映射 (REST API) 创建同义词映射。

POST /synonymmaps?api-version=2024-07-01
{
    "name": "geo-synonyms",
    "format": "solr",
    "synonyms": "
        USA, United States, United States of America\n
        Washington, Wash., WA => WA\n"
}

定义规则

映射规则遵循 Apache Solr 的开源同义词筛选器规则，详情请参阅此文档：SynonymGraphFilter。 solr 格式支持两种类型的规则：

等效（例如，字词在查询中是等效替代项）
显式映射（多个字词映射到一个显式字词）

每个规则由换行符 (\n) 分隔。在免费服务中可为每个同义词映射定义最多 5,000 条规则，在其他层级中可为每个映射定义最多 20,000 条规则。每条规则可包含最多 20 个扩展或规则中的项。有关详细信息，请参阅同义词限制。

查询分析程序会将任何大写或混合大小写的字词转换为小写。要想保留字符串中的特殊字符（例如逗号或短划线），请在创建同义词映射时添加合适的转义字符。

等效规则

等效字词的规则在同一规则中用逗号分隔。在第一个示例中，对“USA”的查询扩展为“USA”OR“United States”OR“United States of America”。请注意，如果想要匹配某个短语，则查询本身必须是带引号的短语查询。

在等效情况下，对 dog 的查询在扩展查询范围后还会包含 puppy 和 canine。

{
"format": "solr",
"synonyms": "
    USA, United States, United States of America\n
    dog, puppy, canine\n
    coffee, latte, cup of joe, java\n"
}

显式映射

显式映射的规则由箭头 => 表示。在指定它的情况下，与 => 左侧内容匹配的一系列搜索查询字词在查询时会被替换为右侧的替代项。

在显式情况下，对 Washington、Wash. 或 WA 的查询会被重写为 WA，查询引擎仅查找与“WA”一词匹配的内容。显式映射只会按指定方向应用，在此示例中，不会将查询“WA”重写为“Washington”。

{
"format": "solr",
"synonyms": "
    Washington, Wash., WA => WA\n
    California, Calif., CA => CA\n"
}

转义特殊字符

与任何其他查询字词一样，同义词在查询处理过程中会被分析，这意味着保留字符和特殊字符的规则适用于同义词映射中的字词。需要转义的字符列表在简单语法和完整语法中有所不同：

简单语法 + | " ( ) ' \
完整语法 + - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

若要保留默认分析器会丢弃的字符，请改用会保留它们的分析器。可供选择的一些项包括 Azure 自然语言分析器（它会保留带连字符的单词）和自定义分析器（用于更复杂的模式）。有关详细信息，请参阅部分词语、模式和特殊字符。

以下示例演示如何转义带反斜杠的字符：

{
    "format": "solr",
    "synonyms": "WA\, USA, WA, Washington\n"
}

由于反斜杠本身是其他语言（例如 JSON 和 C#）中的特殊字符，因此你可能需要对其进行双重转义。下面是一个使用 JSON 的示例：

{
    "format":"solr",
    "synonyms": "WA\\, USA, WA, Washington"
}

管理同义词映射

你无需中断查询，也无需为工作负载编制索引，便可更新同义词映射。但是，一旦你将同义词映射添加到字段，则在删除同义词映射后，包含相关字段的任何查询都会失败并出现 404 错误。

创建、更新和删除同义词映射始终是一个整文档操作。不能以增量方式更新或删除同义词映射的各个部分。甚至更新单个规则也需要重新加载。

向字段分配同义词

创建同义词映射后，请将其分配给索引中的一个字段。若要分配同义词映射，请以编程方式进行。门户不支持同义词映射字段关联。

字段类型必须为 Edm.String 或 Collection(Edm.String)
字段必须具有 "searchable":true
一个字段只能有一个同义词映射

如果同义词映射存在于搜索服务中，则它将在下一次查询中使用，无需重新编制索引或重新生成。

使用创建或更新索引 (REST API) 来修改字段定义。

PUT /indexes?api-version=2024-07-01
{
    "name":"hotels-sample-index",
    "fields":[
        {
            "name":"description",
            "type":"Edm.String",
            "searchable":true,
            "synonymMaps":[
            "en-synonyms"
            ]
        },
        {
            "name":"description_fr",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"fr.microsoft",
            "synonymMaps":[
            "fr-synonyms"
            ]
        }
    ]
}

使用 SearchIndexClient 来更新索引。提供整个索引定义，并包括用于同义词映射分配的新参数。

在此示例中，country 字段具有 synonymMapName 属性。

// Update an index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene }
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

有关更多示例，请参阅 GitHub 上的 quickstart/v11。

可以使用任何受支持的 SDK 来更新搜索索引。所有 SDK 都提供了 SearchIndexClient，其中包含用于更新索引的方法。

Azure SDK	客户端	示例
Java	SearchIndexClient	CreateIndexExample.java
Javascript	SearchIndexClient	索引
Python	SearchIndexClient	sample_index_crud_operations.py

对等效或映射的字段进行查询

同义词字段分配不会更改编写查询的方式。在分配同义词映射后，唯一的区别是，如果同义词映射中存在查询字词，则搜索引擎会根据规则扩展或重写该字词或短语。

在查询执行过程中如何使用同义词

同义词是一种查询扩展技术，它对具有等效词条的索引内容进行补充，但仅适用于具有同义词赋值的字段。如果字段范围内的查询不包括已启用同义词的字段，则看不到同义词映射中的匹配项。

对于支持同义词的字段，同义词与关联的字段具有相同的文本分析。例如，如果使用标准 Lucene 分析器分析某个字段，则在查询时，同义词词条也将受限于标准 Lucene 分析器。如果希望保留标点符号（如句点或短划线），请在“同义词词条”中对该字段应用内容保留分析器。

在内部，同义词功能将使用 OR 操作符重写具有同义词的原始查询。出于这个原因，突出显示和计分配置文件会将原始术语和同义词视为等效项。

同义词仅适用于自由格式文本查询，不支持筛选器、Facet、自动完成或建议。自动完成和建议仅基于原始字词；同义词匹配项不会在响应中显示。

通配符搜索

同义词扩展不适用于通配符搜索术语；也不会扩展前缀、模糊和正则表达式术语。

如果需要执行应用同义词扩展和通配符、正则表达式或模糊搜索的单个查询，则可以使用 OR 语法组合查询。例如，若要将同义词与通配符组合用于简单查询语法，则术语将为 <query> | <query>*。

下一步

创建同义词映射 (REST API)

通过