エンリッチメント キャッシュの管理 (プレビュー)

エンリッチメント キャッシュ (プレビュー) は、スキルセットの実行中に作成されたエンリッチメントされたコンテンツを格納するオプションの機能です。 これは、変更されたスキルとドキュメントのみが再処理を必要とするように、実行間のコンテンツを保持します。 スキルセットの出力、インデクサーの状態、またはインデックス付きドキュメントのバックアップではありません。

Azure Storageでエンリッチメント キャッシュを作成します。 キャッシュには、 ドキュメントクラッキングからの出力と、すべてのドキュメントの各スキルの出力が含まれます。 キャッシュは課金対象ですが (Azure Storageを使用します)、ストレージのコストが画像抽出や AI 処理よりも少ないため、エンリッチメントの全体的なコストが削減されます。

エンリッチメント キャッシュを構成する場合、この記事では、キャッシュされたエンリッチメントから最大限のユーティリティを取得できるように、スキルとデータ ソースの更新を管理する方法について説明します。

前提 条件

• インデクサーとスキルセット

• エンリッチメント キャッシュ

制限

大規模なデータ ソースには、追加のキャッシュ制限があります。

キャッシュの構成

物理的には、キャッシュは BLOB コンテナーに格納され、Azure Storage アカウントのテーブルはインデクサーごとに 1 つずつ格納されます。 各インデクサーには、使用しているコンテナーに対応する一意の不変キャッシュ識別子が割り当てられます。

キャッシュは、 cache プロパティを指定し、インデクサーを実行するときに作成されます。 エンリッチされたコンテンツのみをキャッシュできます。 インデクサーにスキルセットがアタッチされていない場合、キャッシュは適用されません。

次の例は、キャッシュが有効になっているインデクサーを示しています。 詳しい手順については、「 エンリッチメント キャッシュの構成」 を参照してください。

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-08-01-preview
    {
        "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 に設定します。 ほとんどの場合、これを正しく保つことで、新しいドキュメントと既存のドキュメントの両方が現在のスキルセット定義に対して有効なままになります。

スキルセットの評価をバイパスする

通常、スキルを変更すると、そのスキルを再処理する必要があります。 ただし、スキルに対する一部の変更では、再処理はトリガーされません。 たとえば、カスタム スキルを新しい場所にデプロイしたり、新しいアクセス キーを使用したりします。 通常、これらの変更は、スキルの出力の内容に影響を与えない周辺機器の変更です。

スキルの変更が表面的であることがわかっている場合は、 disableCacheReprocessingChangeDetection パラメーターを true に設定してスキルの評価をオーバーライドします。

1. Update スキルセットを呼び出し、スキルセットの定義を変更します。
2. 要求に disableCacheReprocessingChangeDetection=true パラメーターを追加します。
3. 変更を送信します。

このパラメーターを設定すると、スキルセット定義の更新のみがコミットされます。 変更は、既存のキャッシュへの影響については評価されません。 プレビュー API バージョン (2020-06-30-Preview 以降) を使用します。 最新のプレビュー API を使用します。

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2026-08-01-preview&disableCacheReprocessingChangeDetection
  

データ ソースの検証チェックをバイパスする

データ ソース定義に対するほとんどの変更により、キャッシュが無効になります。 ただし、接続文字列の変更やストレージ アカウントのキーのローテーションなど、キャッシュを無効にしてはならないことがわかっているシナリオでは、ignoreResetRequirementに パラメーターを追加します。 このパラメーターを true に設定すると、すべてのオブジェクトが最初から再構築および設定されるリセット条件をトリガーせずにコミットを実行できます。

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-08-01-preview&ignoreResetRequirement
 

スキルセットの評価を強制する

キャッシュの目的は、不要な処理を回避することです。 ただし、インデクサーが検出しないスキルに変更を加えたとします (たとえば、カスタム スキルなどの外部コードの変更)。

この場合は、 Reset Skills API を使用して、そのスキルの出力に依存するダウンストリーム スキルを含め、特定のスキルの再処理を強制します。 この API は、無効にして再処理用にマークする必要があるスキルの一覧を含む POST 要求を受け入れます。 スキルのリセット後、 インデクサーの実行 要求に従ってパイプライン処理を呼び出します。

特定のドキュメントを再キャッシュする

インデクサーをリセットすると、検索コーパス内のすべてのドキュメントが再処理されます。

再処理が必要なドキュメントが少数しかないシナリオでは、ドキュメントの リセット (プレビュー) を使用して、特定のドキュメントの再処理を強制します。 ドキュメントをリセットすると、インデクサーはそのドキュメントのキャッシュを無効にします。 その後、インデクサーは、データ ソースからドキュメントを読み取ってドキュメントを再処理します。 詳細については、「 インデクサー、スキル、ドキュメントの実行またはリセット」を参照してください。

特定のドキュメントをリセットするには、検索インデックスから読み取られたドキュメント キーの一覧を要求に含めます。 キーが外部データ ソースのフィールドにマップされる場合は、検索インデックスの値を使用します。

API の呼び出し方法に応じて、要求はキー リストを追加、上書き、またはキューに追加します。

• 異なるキーを使用して API を複数回呼び出すと、リセットするドキュメント キーの一覧に新しいキーが追加されます。

• overwriteクエリ文字列パラメーターを true に設定して API を呼び出すと、リセットするドキュメント キーの現在の一覧が要求のペイロードで上書きされます。

• API を呼び出すと、インデクサーが実行する作業のキューにドキュメント キーが追加されます。 インデクサーが次に呼び出されると、スケジュールされた状態またはオンデマンドで呼び出されると、データ ソースから他の変更が加わる前に、ドキュメント キーのリセット処理が優先されます。

次の例は、ドキュメントのリセット要求を示しています。

POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2026-08-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

キャッシュを無効にする変更

キャッシュを有効にすると、インデクサーはパイプラインコンポジションの変更をチェックして、再利用できるコンテンツと再処理が必要なコンテンツを決定します。 このセクションでは、キャッシュを無効にする変更と、増分処理をトリガーする変更の一覧を示します。

無効な変更とは、キャッシュ全体が無効になる変更です。 たとえば、データ ソースの更新は無効な変更です。 キャッシュを無効にするインデクサー パイプラインの任意の部分に対する変更の完全な一覧を次に示します。

• データ ソースの種類の変更
• データ ソース コンテナーの変更
• データ ソース資格情報の変更
• データソースの変更検出ポリシーを変更する
• データ ソース削除検出ポリシーの変更
• インデクサー フィールド マッピングの変更
• インデクサー パラメーターの変更:
  • 解析モード
  • 除外されたファイル名拡張子
  • インデックス付きファイル名拡張子
  • サイズの大きいドキュメントに対してのみストレージ メタデータのインデックスを作成する
  • 区切りテキスト ヘッダー
  • 区切られたテキストの区切り記号
  • ドキュメント ルート
  • Image Action (イメージの抽出方法に対する変更)

増分処理をトリガーする変更

増分処理は、スキルセットの定義を評価し、再実行するスキルを決定します。 ドキュメント ツリーの影響を受ける部分を選択的に更新します。 以下は、増分エンリッチメントにつながる変更点の完全なリストです:

• スキルの種類の変更 (スキルの OData 型の更新)
• URL、既定値、その他のパラメーターなど、スキル固有のパラメーターの更新
• スキルの出力を変更する (スキルが追加または異なる出力を返す場合など)
• 異なる先祖またはスキルチェーンをもたらすスキル入力を変更する
• このスキルへの入力を提供するスキルを更新した場合の上流スキルの無効化
• ナレッジ ストアのプロジェクションの場所を更新すると、ドキュメントが再投影されます
• ナレッジ ストアプロジェクションを変更すると、ドキュメントが再投影されます
• インデクサーの出力フィールド マッピングを変更すると、ドキュメントがインデックスに再投影されます

キャッシュに使用される API

プレビュー API は、インデクサーに追加のプロパティを提供します。 最新のプレビュー API を使用します。

スキルセットとデータ ソースには、一般公開されているバージョンを使用します。 操作の順序の詳細については、リファレンス ドキュメントに加えて、 インクリメンタル エンリッチメントのキャッシュの構成 に関するページを参照してください。

• インデクサーの作成または更新 (api-version=2026-08-01-preview)

• スキルをリセット (api-version=2026-08-01-preview)

• スキルセットの作成または更新 (api-version=2026-08-01-preview) (要求の新しい URI パラメーター)

• データ ソースの作成または更新 (api-version=2026-08-01-preview) プレビュー API バージョンでこの API を呼び出すと、 ignoreResetRequirementという名前の新しいパラメーターが提供されます。 このパラメーターは、更新アクションでキャッシュを無効にしない場合に true に設定します。 ignoreResetRequirementは、簡単に検出されないデータに意図しない不整合が生じる可能性があるため、控えめに使用してください。