Azure AI Search でインクリメンタル エンリッチメントのキャッシュを有効にする

この記事では、エンリッチメント パイプラインにキャッシュを追加して、毎回完全にリビルドしなくてもダウンストリーム エンリッチメントの手順を変更できるようにする方法について説明します。 既定では、スキルセットはステートレスであり、その構成の任意の部分を変更するには、インデクサーを完全に再実行する必要があります。 エンリッチメント キャッシュを使用すると、スキルセットまたはインデクサーの定義で検出された変更に基づいて、ドキュメント ツリーのどの部分を更新する必要があるかをインデクサーで判断できます。 既存の処理済みの出力は保持され、可能な限り再利用されます。

キャッシュされたコンテンツは、指定したアカウント情報を使用して Azure Storage に配置されます。 ms-az-search-indexercache-<alpha-numerc-string> という名前のコンテナーは、インデクサーの実行時に作成されます。 これは検索サービスによって管理される内部コンポーネントと見なされ、変更することはできません。

前提条件

• キャッシュされたエンリッチメントを格納するための Azure Storage。 ストレージ アカウントは、汎用 v2 にする必要があります。

• BLOB のインデックスの作成のみを行う場合で、データ ソースから BLOB が削除されたときにキャッシュとインデックスの両方からドキュメントの削除を同期する必要がある場合は、インデクサーで削除ポリシーを有効化します。 このポリシーがないと、ドキュメントのキャッシュからの削除はサポートされません。

インデックスの設定に慣れている必要があります。 インデクサーの概要のページから開始し、スキルセットのページに進んで、エンリッチメント パイプラインについて学習してください。 主要な概念の背景の詳細については、インクリメンタル エンリッチメントに関するページを参照してください。

新しいインデクサーで有効にする

インデクサーでエンリッチメント キャッシュを有効化するには、Azure portal、プレビュー API、またはベータ版の Azure SDK が必要です。

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
    "fieldMappings" : [],
    "outputFieldMappings": [],
    "parameters": []
    }

既存のインデクサーで有効にする

既にスキルセットのある既存のインデクサーの場合、次の手順を使用してキャッシュを追加します。 1 回限りの操作として、インデクサーを完全にリセットして再実行し、キャッシュを読み込みます。

ステップ 1: インデクサーの定義を取得する

コンポーネント (データソース、スキルセット、インデックス) を含む有効な作業インデクサーを使用して開始します。 API クライアントを使用して、GET インデクサー要求を送信し、インデクサーを取得します。 プレビュー API バージョンを使用してインデクサーを取得すると、null に設定された "cache" プロパティが自動的に定義に追加されます。

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

手順 2: cache プロパティを設定する

インデックス定義で、次の必須プロパティと省略可能なプロパティを含めるように "cache" を変更します。

• (必須) storageConnectionString は Azure Storage 接続文字列を設定する必要があります。
• (省略可能) enableReprocessing のブール型プロパティ (既定では true) は、インクリメンタル エンリッチメントが有効になっていることを示します。 新しいドキュメントのインデックス作成など、リソースを大量に消費する他の操作の実行中に増分処理を一時停止させ、後で true に切り替える場合は、false に設定します。

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

ステップ 3: インデクサーをリセットする

すべてのドキュメントが一貫した状態になるように、既存のインデクサーにインクリメンタル エンリッチメントを設定するときは、インデクサーのリセットが必要です。 このタスクには、ポータルまたは API クライアントを使用することができます。

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

手順 4: インデクサーを保存する

要求の本文に "cache" が含まれる PUT 要求を使用してインデクサーを更新します。

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

ここでインデクサーに別の GET 要求を発行した場合、サービスからの応答には、キャッシュ オブジェクトの ID プロパティが含まれます。 このインデクサーによって処理される各ドキュメントのキャッシュされたすべての結果と中間状態が格納されているコンテナーの名前に、英数字文字列が追加されます。 ID は、BLOB ストレージでキャッシュの名前を一意に指定するために使用されます。

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

ステップ 5: インデクサーを実行する

インデクサーを実行するには、ポータルまたは API を使用します。 ポータルでは、インデクサーの一覧からインデクサーを選択し、[実行] を選択します。 ポータルを使用する利点の 1 つは、インデクサーの状態を監視し、ジョブの実行時間と処理されるドキュメントの数を確認できることです。 ポータルのページは、数分ごとに更新されます。

別の方法として、REST を使用してインデクサーを実行することもできます。

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

キャッシュされた出力の確認

[BLOB コンテナー] の下の Azure Storage でキャッシュを検索します。 コンテナーの名前は ms-az-search-indexercache-<some-alphanumeric-string> です。

キャッシュはインデクサーによって作成および使用されます。 そのコンテンツは人間が判読できるものではありません。

キャッシュが動作するかどうかを確認するには、スキルセットを変更してインデクサーを実行し、実行時間とドキュメント数の前後のメトリックを比較します。

スキャンされたドキュメントの画像分析と光学式文字認識 (OCR) を含むスキルセットは、テスト ケースとして最適です。 ダウンストリーム テキストのスキルまたは画像に関連しないスキルを変更すると、インデクサーは、以前に処理されたすべての画像と OCR のコンテンツをキャッシュから取得できるため、編集によって示されたテキスト関連の変更だけを更新および処理できます。 インデクサー実行ドキュメント数に含まれるドキュメントの数が少なくなり、実行時間が短縮され、請求書の料金が少なくなることが期待できます。

cog-search-demo チュートリアルで使用されるファイル セットは、JPG、PNG、HTML、DOCX、PPTX などのさまざまな形式のファイルが 14 個含まれているため、便利なテスト ケースです。 インクリメンタル エンリッチメントの概念実証テストのために、テキスト翻訳スキルの en を es、または別の言語に変更します。

一般的なエラー

要求でプレビュー API バージョンを指定し忘れた場合、次のエラーが発生します。

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

インデクサーの要件が不足している場合は、400 Bad Request エラーも発生します。 エラー メッセージには、不足している依存関係が示されます。

次のステップ

インクリメンタル エンリッチメントは、スキルセットを含むインデクサーに適用され、インデックスとナレッジ ストアの両方に再利用可能なコンテンツを提供します。 キャッシュとスキルセットの詳細については、次のリンクを参照してください。

• インクリメンタル エンリッチメント (ライフサイクルと管理)
• スキルセットの概念と構成
• スキルセットを作成する
• チュートリアル: REST と AI を使用して Azure Blob から検索可能なコンテンツを生成する