Azure AI Search でインデックスを作成する

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

Azure AI Search では、クエリ要求のターゲットは検索インデックス内の検索可能なテキストです。

この記事では、検索インデックスを定義して発行する手順について説明します。インデックスを作成すると、検索サービスに物理的なデータ構造が確立されます。インデックス定義が存在すると、インデックスの読み込みが別のタスクとして続きます。

前提条件

書き込みアクセス許可。アクセス許可は、要求の管理 API キーを使用して付与できます。または、ロールベースのアクセス制御を使用している場合は、検索の共同作成者ロールのメンバーとして要求を送信します。
インデックスを作成するデータを理解していること。インデックスの作成はスキーマ定義の演習であるため、検索インデックス内で検索可能、取得可能、フィルター可能、ファセット可能、並べ替え可能にするソースフィールドを明確に把握する必要があります (詳細については、「スキーマのチェックリスト」を参照してください)。

インデックスのドキュメントキー (または ID) として使用できるソースデータ内の一意のフィールドも必要です。
安定したインデックスの場所。既存のインデックスを別の検索サービスに移動することは、簡単にはできません。アプリケーションの要件を見直し、既存の検索サービスとその容量と場所がニーズに十分に対応していることを確認してください。
最後に、すべてのサービスレベルには、作成できるオブジェクトの数に関するインデックス制限があります。たとえば、Free レベルを試している場合は、所定の期間内に 3 つのインデックスしか作成できません。インデックス自体に、複合フィールドとコレクションの数に制限があります。

ドキュメントキー

検索インデックスには、ドキュメントキーという 1 つの必須フィールドがあります。ドキュメントキーは、検索ドキュメントの一意識別子です。 Azure AI Search では、これは文字列である必要があります。また、インデックスを作成するコンテンツを提供するデータソース内の一意の値から取得する必要があります。検索サービスでは、キー値を生成しませんが、一部のシナリオ (Azure テーブルインデクサーなど) では、既存の値を合成して、インデックスを作成するドキュメントの一意のキーを作成します。

新しいコンテンツと更新されたコンテンツのインデックスだけが作成される増分インデックス作成では、新しいキーを持つ着信ドキュメントは追加されますが、既存のキーを持つ着信ドキュメントは、インデックスフィールドが null か値が設定されているかに応じて、マージまたは上書きされます。

スキーマのチェックリスト

このチェックリストは、検索インデックスの設計上の決定を行う際に役立ちます。

インデックス名とフィールド名が名前付けルールに準拠するように、名前付け規則を確認します。
サポートされていないデータ型を確認します。データ型は、フィールドの使用方法に影響します。たとえば、数値コンテンツはフィルター可能ですが、フルテキスト検索はできません。最も一般的なデータ型は、検索可能な Edm.String テキストです。これは、フルテキスト検索エンジンを使用してトークン化され、クエリが実行されます。
ドキュメントキーを確認します。ドキュメントキーはインデックス要件です。これは単一の文字列フィールドであり、一意の値を含むソースデータフィールドから設定されます。たとえば、Blob Storage からインデックスを作成する場合、メタデータストレージパスは、コンテナー内の各 BLOB を一意に識別するため、ドキュメントキーとしてよく使用されます。
インデックス内の検索可能なコンテンツに作用するデータソース内のフィールドを特定します。検索可能なコンテンツには、フルテキスト検索エンジンを使用してクエリを実行する短い文字列または長い文字列が含まれます。コンテンツが詳細である (小さなフレーズまたは大きなチャンク) 場合は、さまざまなアナライザーを試して、テキストがどのようにトークン化されるのか確認します。

フィールド属性の割り当てによって、検索動作と、検索サービスでのインデックスの物理的な表現の両方が決定されます。フィールドの指定方法の決定は、多くのお客様にとって反復的なプロセスになります。反復処理の速度を上げるには、簡単に削除して再構築できるサンプルデータから始めます。
フィルターとして使用できるソースフィールドを特定します。数値コンテンツと短いテキストフィールド (特に繰り返し値を持つフィールド) は、優れた選択肢です。フィルターを使用する場合は、次のことを覚えておいてください。
- フィルター可能なフィールドは、必要に応じてファセットナビゲーションで使用できます。
- フィルター可能なフィールドは任意の順序で返されます。そのため、並べ替え可能にすることも検討してください。
既定のアナライザー ("analyzer": null) と別のアナライザーのどちらを使用するかを決定します。アナライザーは、インデックス作成とクエリの実行中にテキストフィールドをトークン化するために使用されます。

多言語文字列の場合は、言語アナライザーのを検討してください。

ハイフンでつながれた文字列または特殊文字の場合は、特殊なアナライザーを検討してください。たとえば、フィールドの内容全体を 1 つのトークンとして扱う keyword です。この動作は、郵便番号、ID、製品名などのデータで役立ちます。詳細については、「部分的な用語検索と特殊文字を含むパターン」をご覧ください。

Note

インデックス作成中にトークン化された用語に対してフルテキスト検索が実行されます。クエリで期待した結果が返されない場合は、トークン化をテストして、文字列が実際に存在することを確認してください。文字列に対してさまざまなアナライザーを試して、各種アナライザーでトークンがどのように生成されるかを確認できます。

インデックスを作成する

インデックスを作成する準備ができたら、要求を送信できる検索クライアントを使用します。早期の開発と概念実証のテストには、Azure portal または REST API を使用できます。

開発時に、頻繁な再構築を計画します。物理構造はサービス内で作成されるため、変更のほとんどにおいてインデックスの削除と再作成が必要になります。リビルドを高速化するために、データのサブセットを使って作業することを検討してもよいでしょう。

ポータルを使用したインデックスの設計では、数値フィールドに対してフルテキスト検索機能を許可しないなど、特定のデータ型に対して要件とスキーマルールが適用されます。

Azure portal にサインインします。
検索サービスの [概要] ページで、検索インデックスの作成に関するオプションとして次のいずれかを選択します。
- [インデックスの追加] (インデックススキーマを指定するための埋め込みエディター)
- データのインポートウィザード
このウィザードは、インデクサー、データソース、完成したインデックスを作成するエンドツーエンドのワークフローです。また、データも読み込まれます。これだと目的よりも機能が多い場合は、代わりに [インデックスの追加] を使用してください。

次のスクリーンショットでは、コマンドバーの [インデックスの追加] と [データのインポート] が表示される場所を強調表示しています。インデックスが作成されたら、再度 [インデックス] タブで確認できます。

ヒント

ポータルでインデックスを作成した後、JSON 表現をコピーしてアプリケーションコードに追加できます。

[インデックスの作成 (REST API)] は、インデックスを作成するために使用されます。検索サービスに接続して要求を送信するには、REST クライアントが必要です。「クイックスタート: REST を使用したテキスト検索」を参照して開始してください。

REST API は、フィールド属性の既定値を提供します。たとえば、既定ではすべての Edm.String フィールドが検索可能です。属性は、説明を目的として以下のように完全に表示されますが、既定値が適用される場合は、属性を省略できます。

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

Azure SDK for .NET には、インデックスを作成および更新するためのメソッドを含む SearchIndexClient が用意されています。

// Create the 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);

詳細については、azure-search-dotnet-samples/quickstart/v11/ を参照してください。

Azure AI Search の場合、一般公開される機能は Azure SDK によって実装されています。そのため、いずれかの SDK を使用して検索インデックスを作成できます。これらのすべてに、インデックスを作成および更新するためのメソッドを含む SearchIndexClient が用意されています。

Azure SDK	クライアント	例
Java	SearchIndexClient	CreateIndexExample.java
JavaScript	SearchIndexClient	インデックス
Python	SearchIndexClient	sample_index_crud_operations.py

クロスオリジンクエリのために `corsOptions` を設定する

インデックススキーマには、corsOptions を設定するためのセクションが含まれます。既定では、ブラウザーではすべてのクロスオリジン要求が禁止されるので、クライアント側 JavaScript で API を呼び出すことはできません。インデックスに対するクロスオリジンクエリを許可するには、corsOptions 属性を設定することによって、CORS (クロスオリジンリソース共有) を有効にします。セキュリティ上の理由から、CORS がサポートされているのはクエリ API だけです。

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

CORS には次のプロパティを設定できます。

allowedOrigins (必須): インデックスへのアクセスが許可されるオリジンのリストです。これらのオリジンから提供される JavaScript コードは、インデックスのクエリを実行できます (呼び出し元が有効なキーを提示するか、アクセス許可を持っている場合)。各オリジンの標準的な形式は protocol://<fully-qualified-domain-name>:<port> ですが、多くの場合 <port> は省略されます。詳細については、「クロスオリジンリソース共有 (Wikipedia) 」を参照してください。

すべてのオリジンにアクセスを許可する場合は、allowedOrigins 配列の唯一の要素として * を指定します。 "運用環境の検索サービスに対してはこれは推奨されません" が、開発およびデバッグでは役に立つことがよくあります。
maxAgeInSeconds (省略可能): (省略可能): ブラウザーはこの値を使用して、CORS プレフライト応答をキャッシュする期間 (秒) を決定します。負ではない整数を指定する必要があります。キャッシュ期間が長いほどパフォーマンスは向上しますが、CORS ポリシーを有効にするために必要な時間が長くなります。この値が設定されていない場合は、既定の期間として 5 分が使用されます。

既存のインデックスに対して許可される更新

インデックスの作成では、検索サービスに物理データ構造 (ファイルと逆インデックス) を作成します。インデックスの作成後、[インデックスの更新] を使用して変更を有効にできるかどうかは、その変更によってこれらの物理構造が無効になるかどうかに応じて決まります。ほとんどのフィールド属性は、インデックスにフィールドが作成された後は変更できません。

または、アプリケーションコードで安定した参照として機能するインデックスエイリアスを作成することもできます。コードを更新する代わりに、新しいインデックスバージョンを指すようにインデックスエイリアスを更新できます。

設計プロセスのチャーンを最小限に抑えるために、次の表で、スキーマに固定される要素と、柔軟性のある要素を説明します。固定要素を変更するにはインデックスを再構築する必要がありますが、柔軟性のある要素は物理実装に影響を与えることなくいつでも変更できます。

要素	更新可能かどうか
名前	いいえ
キー	いいえ
フィールド名と型	いいえ
フィールド属性 (検索可能、フィルター可能、ファセット可能、並べ替え可能)	いいえ
フィールド属性 (取得可能)	はい
Analyzer	インデックス内のカスタムアナライザーを追加および変更できます。文字列フィールドでのアナライザーの割り当てについては、`searchAnalyzer` のみを変更できます。その他すべての割り当てと変更には、再構築が必要です。
スコアリングプロファイル	はい
Suggesters	いいえ
クロスオリジンリソース共有 (CORS)	はい
暗号化	はい

次のステップ

次のリンクを使用して、インデックスとデータの読み込みや、シノニムマップを使用したインデックスの拡張について理解を深めてください。