例: C#で Azure AI Search の同意語を追加する

[アーティクル]
11/15/2023

シノニムは、意味的に入力用語と同等と見なされる用語を一致させることにより、クエリを拡張します。たとえば、"car" を "automobile" または "vehicle" という用語が含まれているドキュメントと一致させたい場合があります。

Azure AI Search では、同意語は、同等の用語を関連付けるマッピングルール通じて、 同意語マップ で定義されます。この例では、既にインデックスがある状態で同意語を追加して使用する最も重要な手順について取り上げます。

この例では、次のことについて説明します。

SynonymMap クラスを使用して、シノニムマップを作成する。
シノニムを介してクエリ拡張をサポートする必要があるフィールドに対して SynonymMapsName プロパティを設定する。

シノニム対応フィールドに対するクエリは、通常と同じ方法で実行できます。クエリ構文を追加しなくてもシノニムにアクセスできます。

複数のシノニムマップを作成し、サービス全体の任意のインデックスで使用できるリソースとしてポストして、フィールドレベルでどのマップを使用するかを参照することができます。クエリ時に、インデックスの検索に加えて、Azure AI Search は、クエリで使用されるフィールドで同意語マップが指定されている場合に、同意語マップで検索を実行します。

Note

シノニムは、プログラムで作成できますが、ポータルでは作成できません。

前提条件

チュートリアルには、次のような要件があります。

.NET クライアントライブラリに慣れていない場合は、「 .NETで Azure AI Search を使用する方法」を参照してください。

サンプルコード

この例で使用したサンプルアプリケーションの完全なソースコードは GitHub にあります。

概要

前と後のクエリは、シノニムの値を示すために使用されます。この例では、サンプルアプリケーションによってクエリが実行され、2 つのドキュメントが設定されたサンプルの "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);

これらの用語は 2 つのインデックス付きドキュメントのどちらにも含まれていないため、最初の RunQueriesWithNonExistentTermsInIndex からは no document matched (一致するドキュメントがありませんでした) という出力が返されます。

シノニムの有効化

"前" のクエリが実行されると、サンプルコードによってシノニムが有効になります。シノニムの有効化は、2 段階のプロセスです。最初に、シノニム規則を定義してアップロードします。次に、それらを使用するようにフィールドを構成します。プロセスの概要は、UploadSynonyms および EnableSynonymsInHotelsIndex で示されています。

シノニムマップを検索サービスに追加します。 UploadSynonyms で、シノニムマップ 'desc-synonymmap' に 4 つの規則を定義し、サービスにアップロードします。

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 の 2 つのフィールド 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");
```

"後" のクエリ

シノニムマップがアップロードされ、インデックスがシノニムマップを使用するように更新された後、2 回目の 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 からドキュメントを見つけます。 2 番目のクエリは internet,wifi を使用して検索を拡張し、3 番目のクエリは hotel, motel と economy,inexpensive=>budget の両方を使用してそれらと一致するドキュメントを見つけます。

シノニムを追加することで、検索エクスペリエンスがまったく違うものになります。この例で元のクエリは、インデックス内のドキュメントが関連性を持っているにもかかわらず、意味のある結果を返すことができませんでした。シノニムを有効にすると、インデックス内の基になるデータは変更せずに、よく使用される用語が含まれるようにインデックスを拡張できます。

リソースをクリーンアップする

例の後で最も簡単にクリーンアップする方法は、Azure AI Search Serviceを含むリソースグループを削除することです。リソースグループを削除することで、そのすべての内容を完全に削除することができます。ポータルのリソースグループ名は、Azure AI Search Serviceの [概要] ページにあります。

次のステップ

この例では、マッピング規則を作成、ポストしてからクエリでシノニムマップを呼び出す C# コードのシノニム機能を示します。さらに詳しい情報については、.NET SDK と REST API のリファレンスドキュメントをご覧ください。

Azure AI Searchで同意語を使用する方法

例: C#で Azure AI Search の同意語を追加する

前提条件

サンプルコード

概要

"前" のクエリ

シノニムの有効化

"後" のクエリ

リソースをクリーンアップする

次のステップ

その他のリソース

その他のリソース

例: C#で Azure AI Search の同意語を追加する

前提条件

サンプル コード

概要

"前" のクエリ

シノニムの有効化

"後" のクエリ

リソースをクリーンアップする

次のステップ

その他のリソース

その他のリソース

サンプルコード