示例：使用 C# 为 Azure 认知搜索添加同义词

项目
08/07/2023

使用同义词进行搜索时，在语义上被视为与输入字词等效的字词也属于匹配项，从而扩展了查询的范围。例如，使用“car”进行搜索时，也可将包含“automobile”或“vehicle”字词的文档视为匹配项。

在 Azure 认知搜索中，同义词在“同义词映射”中通过可将等效字词关联在一起的“映射规则”进行定义。本示例介绍了用于添加同义词并将其与现有索引一起使用的基本步骤。

此示例介绍如何执行以下操作：

使用 SynonymMap 类创建同义词映射。
在应该支持通过同义词进行查询扩展的字段上设置 SynonymMapsName 属性。

可以照常查询启用了同义词的字段。访问同义词不需其他的查询语法。

可以创建多个同义词映射，将其发布为在服务范围内可供任何索引使用的资源，然后引用要在字段级别使用的资源。在查询时，除了搜索索引，Azure 认知搜索还会查看同义词映射（如果在查询所用的字段上指定了该映射）。

注意

可以通过编程方式创建同义词，但不能在门户中进行。

必备条件

教程要求如下：

如果不熟悉 .NET 客户端库，请参阅如何在 .NET 中使用 Azure 认知搜索。

代码示例

可以在 GitHub 上找到本示例中所用示例应用程序的完整源代码。

概述

前后比较查询用于演示同义词的值。在此示例中，示例应用程序会执行查询并返回针对示例“hotels”索引（使用两个文档填充）的结果。第一步，应用程序使用索引中没有出现的术语和短语执行搜索查询。第二步，代码启用同义词功能，然后重新发出相同的查询，这次根据同义词映射中的匹配项返回结果。

以下代码演示了整个流程。

static void Main(string[] args)
{
   SearchIndexClient indexClient = CreateSearchIndexClient();

   Console.WriteLine("Cleaning up resources...\n");
   CleanupResources(indexClient);

   Console.WriteLine("Creating index...\n");
   CreateHotelsIndex(indexClient);

   SearchClient searchClient = indexClient.GetSearchClient("hotels");

   Console.WriteLine("Uploading documents...\n");
   UploadDocuments(searchClient);

   SearchClient searchClientForQueries = CreateSearchClientForQueries();

   RunQueriesWithNonExistentTermsInIndex(searchClientForQueries);

   Console.WriteLine("Adding synonyms...\n");
   UploadSynonyms(indexClient);

   Console.WriteLine("Enabling synonyms in the test index...\n");
   EnableSynonymsInHotelsIndexSafely(indexClient);
   Thread.Sleep(10000); // Wait for the changes to propagate

   RunQueriesWithNonExistentTermsInIndex(searchClientForQueries);

   Console.WriteLine("Complete.  Press any key to end application...\n");

   Console.ReadKey();
}

“启用前”查询

在 RunQueriesWithNonExistentTermsInIndex 中，使用“five star”、“internet”和“economy AND hotel”发出搜索查询。

短语查询（如“five star”）必须用引号括起来，并且可能还需要转义字符，具体取决于客户端。

Console.WriteLine("Search the entire index for the phrase \"five star\":\n");
results = searchClient.Search<Hotel>("\"five star\"", searchOptions);
WriteDocuments(results);

Console.WriteLine("Search the entire index for the term 'internet':\n");
results = searchClient.Search<Hotel>("internet", searchOptions);
WriteDocuments(results);

Console.WriteLine("Search the entire index for the terms 'economy' AND 'hotel':\n");
results = searchClient.Search<Hotel>("economy AND hotel", searchOptions);
WriteDocuments(results);

两个已编入索引的文档都不包含这些术语，因此我们从第一个 RunQueriesWithNonExistentTermsInIndex 获得以下输出：没有匹配的文档。

启用同义词

运行“启用前”查询后，示例代码会启用同义词。启用同义词是一个两步过程。第一步，定义并上传同义词规则。第二步，配置字段以使用这些规则。 UploadSynonyms 和 EnableSynonymsInHotelsIndex 中概述了此过程。

将同义词映射添加到搜索服务。在 UploadSynonyms 中，我们在同义词映射“desc-synonymmap”中定义了四条规则，并将其上传到服务。

private static void UploadSynonyms(SearchIndexClient indexClient)
{
   var synonymMap = new SynonymMap("desc-synonymmap", "hotel, motel\ninternet,wifi\nfive star=>luxury\neconomy,inexpensive=>budget");

   indexClient.CreateOrUpdateSynonymMap(synonymMap);
}

将可搜索字段配置为允许在索引定义中使用同义词映射。在 AddSynonymMapsToFields 中，我们对category和tags这两个字段启用了同义词功能，方法是将 SynonymMapNames 属性设置为新上传的同义词映射的名称。
```
private static SearchIndex AddSynonymMapsToFields(SearchIndex index)
{
   index.Fields.First(f => f.Name == "category").SynonymMapNames.Add("desc-synonymmap");
   index.Fields.First(f => f.Name == "tags").SynonymMapNames.Add("desc-synonymmap");
   return index;
}
```
添加同义词映射时，索引重建不是必需的。可以向服务添加同义词映射，并对任意索引中的现有字段定义进行修正，使之使用新的同义词映射。添加新属性不影响索引可用性。这同样适用于禁用字段同义词功能的情况。可以直接将 SynonymMapNames 属性设置为空列表。
```
index.Fields.First(f => f.Name == "category").SynonymMapNames.Add("desc-synonymmap");
```

“启用后”查询

上传同义词映射并对索引进行更新，允许其使用同义词映射以后，再次调用 RunQueriesWithNonExistentTermsInIndex 会获得如下输出：

Search the entire index for the phrase "five star":

Name: Fancy Stay        Category: Luxury        Tags: [pool, view, wifi, concierge]

Search the entire index for the term 'internet':

Name: Fancy Stay        Category: Luxury        Tags: [pool, view, wifi, concierge]

Search the entire index for the terms 'economy' AND 'hotel':

Name: Roach Motel       Category: Budget        Tags: [motel, budget]

第一个查询根据规则 five star=>luxury 查找文档。第二个查询使用 internet,wifi 扩展了搜索，第三个查询在查找匹配的文档时同时使用 hotel, motel 和 economy,inexpensive=>budget。

添加同义词完全改观了搜索体验。在本示例中，初始查询并没有返回有意义的结果，虽然索引中的文档是相关的。启用同义词可以扩展索引，使之包括常用字词，但不更改索引中的基础数据。

清理资源

完成本示例后，最快的清理方式是删除包含 Azure 认知搜索服务的资源组。现在，可以删除资源组以永久删除其中的所有内容。在门户中，资源组名称显示在 Azure 认知搜索服务的“概述”页上。

后续步骤

本示例使用 C# 代码演示了同义词功能，创建并发布了映射规则，然后在查询中调用同义词映射。可以在 REST API 参考文档中找到更多信息。

如何在 Azure 认知搜索中使用同义词