Azure AI Search での増分 エンリッチメントとキャッシュ
重要
この機能はパブリック プレビュー段階にあり、追加使用条件の下で提供されます。 この機能は、プレビュー REST API でサポートされます。
"インクリメンタル エンリッチメント" とは、スキルセットの実行中にキャッシュされたエンリッチメントを使うことを指します。こうすることで、新規および変更されたスキルとドキュメントにのみ、Azure AI サービスへの API 呼び出しの従量課金処理料金が発生します。 キャッシュには、ドキュメント解析の出力に加え、ドキュメントごとの各スキルの出力が格納されます。 キャッシュは課金対象 (Azure Storage を使用) です。ただし、ストレージのコストは画像抽出や AI 処理よりも低いため、強化全体コストは削減されます。
データ ソース データとインデックスの間の同期を確保するには、独自のデータ ソースの変更と削除の追跡の前提条件を理解することが重要です。 このガイドでは、スキル処理の観点から増分変更を管理する方法と、この目的のためにキャッシュを利用する方法について具体的に説明します。
キャッシュを有効にすると、インデクサーによって更新内容が評価され、既にあるエンリッチメントをキャッシュから取得できるかどうかが判断されます。 ドキュメント解析フェーズから出力される画像やテキスト コンテンツに加え、編集の上流のスキル出力や、編集に対して直交するスキル出力は再利用できる可能性が高くなります。
スキルセットの処理が完了した後、更新された結果は、キャッシュだけでなく、検索インデックスまたはナレッジ ストアにも書き戻されます。
制限事項
注意事項
SharePoint Online インデクサー (プレビュー) を使用している場合は、増分エンリッチメントを避ける必要があります。 特定の状況では、キャッシュが無効になり、キャッシュを再ロードする場合は、インデクサーをリセットして実行する必要があります。
キャッシュの構成
物理的には、ご使用の Azure ストレージ アカウントの BLOB コンテナーに、インデクサーごとに 1 つキャッシュが格納されます。 それぞれのインデクサーには、使っているコンテナーに対応する一意で不変のキャッシュ識別子が割り当てられます。
キャッシュは、"cache" プロパティを指定してインデクサーを実行すると作成されます。 キャッシュできるのは、エンリッチされたコンテンツのみです。 インデクサーにスキルセットがアタッチされていない場合、キャッシュは適用されません。
次の例は、キャッシュが有効になっているインデクサーを示しています。 詳細な手順については、エンリッチメント キャッシュの有効化に関するページを参照してください。
キャッシュ プロパティを使うには、インデクサーを作成または更新するときに 2020-06-30-preview 以降を使用できます。 最新のプレビュー API をお勧めします。
POST https://[search service name].search.windows.net/indexers?api-version=2024-05-01-rreview
{
"name": "myIndexerName",
"targetIndexName": "myIndex",
"dataSourceName": "myDatasource",
"skillsetName": "mySkillset",
"cache" : {
"storageConnectionString" : "<Your storage account connection string>",
"enableReprocessing": true
},
"fieldMappings" : [],
"outputFieldMappings": [],
"parameters": []
}
キャッシュ管理
キャッシュのライフサイクルは、インデクサーによって管理されます。 インデクサーが削除されると、そのキャッシュも削除されます。 インデクサーの cache プロパティが null に設定されるか、接続文字列が変更された場合、既存のキャッシュはインデクサーの次回の実行時に削除されます。
インクリメンタル エンリッチメントはユーザーの介入なしに変更を検出して対応するように設計されています。その一方で、特定の動作を呼び出すために使用できるパラメーターが用意されています。
新しいドキュメントを優先する
cache プロパティには、enableReprocessing パラメータが含まれます。 キャッシュ内で既に表現されている受信ドキュメントの処理を制御する目的で使用されます。 true (既定値) の場合、インデクサーを再実行すると、キャッシュ内に既にあるドキュメントが再処理されます。これは、スキルの更新によってそのドキュメントが影響を受けると仮定されるためです。
false の場合、既存のドキュメントは再処理されず、実質的に新しい受信コンテンツが既存のコンテンツより優先されます。 enableReprocessing を false に設定するのは、あくまで一時的な措置としてください。 ほとんどの場合は enableReprocessing を true に設定しておくと、新規と既存両方のすべてのドキュメントが、最新のスキルセット定義に従って確実に有効になります。
スキルセットの評価をバイパスする
通常、スキルの変更とそのスキルの再処理は連動します。 ただし、スキルを変更しても再処理が行われてはならない場合がいくつかあります (たとえば、新しい場所に、または新しいアクセス キーを使って、カスタム スキルをデプロイする場合)。 ほとんどの場合、これらは、スキル出力の実体そのものに実際の影響を与えない末梢的な変更です。
スキルに対する変更が実際は表面的なものであることがわかっている場合は、disableCacheReprocessingChangeDetection パラメータを true に設定して、スキルの評価をオーバーライドする必要があります。
- スキルセットの更新を呼び出し、スキルセット定義を変更します。
- 要求に "disableCacheReprocessingChangeDetection=true" パラメーターを追加します。
- 変更を送信します。
このパラメーターを設定すると、スキルセット定義に対する更新だけがコミットされ、変更が既存のキャッシュに及ぼす影響は評価されません。 プレビューの API バージョンである 2020-06-30-Preview 以降を使用してください。 最新のプレビュー API をお勧めします。
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2024-05-01-preview&disableCacheReprocessingChangeDetection
データ ソースの検証チェックをバイパスする
ほとんどの場合、データ ソース定義を変更すると、キャッシュが無効になります。 ただし、接続文字列の変更やストレージ アカウントのキーのローテーションなど、変更によってキャッシュが無効になってはならないことがわかっているシナリオでは、データ ソースの更新で ignoreResetRequirement パラメータを追加します。 このパラメーターを true に設定すると、リセット条件 (結果的にすべてのオブジェクトが最初から再構築されて設定される条件) をトリガーすることなく、コミットを実行できます。
PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2024-05-01-preview&ignoreResetRequirement
スキルセットの評価を強制的に実行する
キャッシュの目的は不必要な処理を回避することにあります。ここで、インデクサーによって検出されない変更 (たとえば、カスタム スキルなどの外部コード内の変更) をスキルに加えるケースを考えてみましょう。
この場合は、スキルのリセットを使用して、特定のスキル (そのスキルの出力に依存するダウンストリームのスキルも含まれます) を強制的に再処理することができます。 この API は、無効にして再処理用にマークする必要があるスキルのリストが含まれた POST 要求を受け取ります。 スキルのリセット後、インデクサー実行要求を行ってパイプライン処理を呼び出します。
特定のドキュメントを再キャッシュする
インデクサーのリセットを使用すると、検索コーパス内のすべてのドキュメントが再処理されます。
再処理を必要とするドキュメントがごく少数のシナリオでは、ドキュメントのリセット (プレビュー) を使用して、特定のドキュメントを強制的に再処理します。 ドキュメントがリセットされると、インデクサーによってそのドキュメントのキャッシュが無効にされ、ドキュメントはその後データ ソースから読み取ることによって再処理されます。 詳細については、インデクサー、スキル、ドキュメントの実行またはリセットに関するページを参照してください。
特定のドキュメントをリセットする場合は、検索インデックスから読み取るドキュメント キーのリストを要求で指定します。 キーが外部データソースのフィールドにマップされている場合、指定する値は検索インデックスで使用されているものであることが必要です。
API の呼び出し方法に応じて、要求ではキー リストを追加、上書き、またはキューに登録します。
異なるキーを使用して API を複数回呼び出すと、ドキュメント キーのリセットの一覧に新しいキーが追加されます。
"overwrite" クエリ文字列パラメーターを true に設定して API を呼び出すと、リセットされるドキュメント キーの現在のリストが要求のペイロードで上書きされます。
API を呼び出しても、ドキュメント キーはインデクサーによって実行される処理のキューに追加されるだけです。 スケジュールに従ってまたはオンデマンドでインデクサーが次に呼び出されると、データ ソースからの他の変更よりも、リセットされたドキュメント キーの処理が優先されます。
次の例は、ドキュメントのリセット要求を示しています。
POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2024-05-01-preview
{
"documentKeys" : [
"key1",
"key2",
"key3"
]
}
キャッシュが無効になる変更
キャッシュを有効にすると、インデクサーによってパイプライン構成の変更が評価され、再利用できるコンテンツと再処理が必要なコンテンツが特定されます。 このセクションでは、キャッシュが完全に無効になる変更を示した後、増分処理がトリガーされる変更を示します。
無効化につながる変更とは、キャッシュ全体の有効性が失われる変更をいいます。 たとえばデータ ソースの更新は、無効化につながる変更です。 次に示すのは、インデクサー パイプラインのいずれかの部分に対する変更で、キャッシュが無効になるすべてのものの一覧です。
- データ ソースの種類の変更
- データ ソース コンテナーの変更
- データ ソースの資格情報の変更
- データ ソースの変更検出ポリシーの変更
- データ ソースの削除検出ポリシーの変更
- インデクサーのフィールドのマッピングの変更
- インデクサーのパラメーターの変更:
- 解析モード
- ファイル名拡張子を除外
- ファイル名拡張子のインデックスを作成
- サイズの大きいドキュメントのストレージ メタデータのみのインデックスを作成
- 区切りテキストのヘッダー
- 区切りテキストの区切り記号
- ドキュメントのルート
- 画像操作 (画像の抽出方法に対する変更)
増分処理がトリガーされる変更
増分処理では、対象のスキルセット定義が評価された後、再実行する必要があるスキルが特定され、ドキュメント ツリーの影響を受ける部分が選択的に更新されます。 結果的にインクリメンタル エンリッチメントが発生する変更の完全な一覧を次に示します。
- スキルの種類を変更する (スキルの OData 型が更新された)。
- スキルに固有のパラメーター (URL、defaults など) が更新された。
- スキルの出力が変更 (スキルから返される出力が追加または変更) された。
- 先祖の変更を伴うスキルの入力の変更があった (スキルのチェーンが変更された)。
- アップストリームのスキルが無効化された (このスキルへの入力となっているスキルが更新された場合)。
- ドキュメントの再プロジェクションを伴う更新がナレッジ ストアのプロジェクション場所に生じた。
- ドキュメントの再プロジェクションを伴う変更がナレッジ ストアのプロジェクションに生じた。
- インデックスに対するドキュメントの再プロジェクションを伴う変更が、インデクサーの出力フィールドのマッピングに生じた。
キャッシュに使用される API
REST API バージョン 2020-06-30-Preview 以降では、インデクサーの追加のプロパティによって増分エンリッチメントが提供されます。 最新のプレビュー API をお勧めします。
スキルセットとデータ ソースは、一般公開されているバージョンを使用できます。 操作の順序について詳しくは、リファレンス ドキュメントに加えて、インクリメンタル エンリッチメント用のキャッシュの構成に関するページを参照してください。
スキルセットを作成または更新する (api-version=2024-07-01) (要求での新しい URI パラメーター)
データ ソースを作成または更新する (api-version=2024-07-01): プレビュー API バージョンで呼び出されるときは、"ignoreResetRequirement" という名前の新しいパラメーターを指定し、更新アクションでキャッシュを無効にしてはならないときはそれを true に設定する必要があります。 "ignoreResetRequirement" は、簡単に検出できない不整合が意図せずデータに発生する可能性があるため、慎重に使ってください。
次のステップ
インクリメンタル エンリッチメントは、変更の追跡をスキルセットと AI エンリッチメントに拡張する強力な機能です。 インクリメンタル エンリッチメントを使用すると、スキルセットの設計を反復処理する際に、既存の処理済みコンテンツを再利用できます。 次のステップで、インデクサーのキャッシュを有効にします。