Azure AI Search のインデクサーのトラブルシューティングガイダンス

[アーティクル]
09/03/2024

場合によっては、認証中や接続時などに、インデクサーでエラーが発生しない問題や、他の Azure サービスの問題が発生することがあります。この記事では、ガイドとなるメッセージがない場合のインデクサーの問題のトラブルシューティングに焦点を当てます。また、インデックス作成中に使用される検索以外のリソースから発生するエラーのトラブルシューティングも提供します。

Note

調査する Azure AI 検索のエラーがある場合は、代わりに、「インデクサーの一般的なエラーと警告のトラブルシューティング」を参照してください。

制限されたリソースへの接続のトラブルシューティング

Azure ネットワークセキュリティが適用されているデータソースの場合、インデクサーの接続方法は制限されます。現在、インデクサーは、共有プライベートリンクを使用して、IP ファイアウォールの背後の、またはプライベートエンドポイントを介した仮想ネットワーク上の、制限されたデータソースにアクセスできます。

ファイアウォール規則

Azure Storage、Azure Cosmos DB、Azure SQL では、構成可能なファイアウォールが提供されます。ファイアウォールが要求をブロックする場合、特定のエラーメッセージはありません。通常、ファイアウォールのエラーは一般的です。一般的なエラーには次のようなものがあります。

The remote server returned an error: (403) Forbidden
This request is not authorized to perform this operation
Credentials provided in the connection string are invalid or have expired

こうした場合にインデクサーでこれらのリソースにアクセスできるようにするには、次の 2 つのオプションがあります。

検索サービスの IP アドレスと AzureCognitiveSearch サービスタグの IP アドレス範囲の受信規則を構成します。データソースの種類ごとに IP アドレス範囲の制限を構成する方法の詳細については、次のリンクを参照してください。
最後の手段として、または一時的な手段として、すべてのネットワークからのアクセスを許可してファイアウォールを無効にします。

制限: IP アドレス範囲の制限は、検索サービスとストレージアカウントが異なるリージョンにある場合にのみ機能します。

インデクサーは、データ取得に加えて、スキルセットとカスタムスキルを通じた送信要求の送信も行います。 Azure 関数に基づくカスタムスキルの場合は、Azure 関数にも IP アドレス制限があることに注意してください。カスタムスキルの実行に使用できる IP アドレスの一覧には、検索サービスの IP アドレスと AzureCognitiveSearch サービスタグの IP アドレス範囲が含まれます。

ネットワークセキュリティグループ (NSG) のルール

インデクサーが SQL マネージドインスタンス上のデータにアクセスするとき、またはカスタムスキルの Web サービス URI として Azure VM が使用されている場合、ネットワークセキュリティグループは要求が許可されるかどうかを判断します。

仮想ネットワーク上に存在する外部リソースの場合は、AzureCognitiveSearch サービスタグの受信 NSG 規則を構成します。

仮想マシンへの接続の詳細については、Azure VM での SQL Server への接続の構成に関する記事を参照してください。

ネットワークエラー

通常、ネットワークエラーは一般的です。一般的なエラーには次のようなものがあります。

A network-related or instance-specific error occurred while establishing a connection to the server
The server was not found or was not accessible
Verify that the instance name is correct and that the source is configured to allow remote connections

これらのエラーのいずれかが発生した場合は、次を行います。

ソースに直接接続してみたり、検索サービスを経由しないで接続してみたりして、ソースにアクセス可能であることを確認します
Azure portal 内のリソースに現在エラーや停止が発生していないかどうかを確認します
Azure の状態で、ネットワークの停止が発生していないかどうかを確認します
名前解決に対して、Azure プライベート DNS ではなく、パブリック DNS を使用していることを確認します

Azure SQL Database のサーバーレスインデックス作成 (エラーコード 40613)

SQL データベースがサーバーレスのコンピューティング層にある場合は、インデクサーが接続しているときに、データベースが実行中であり、一時停止されていないことを確認します。

データベースが一時停止されている場合、検索サービスからの最初のサインインによってデータベースが自動的に再開されることが期待されますが、代わりに、エラーコード 40613 でデータベースを使用できないことを示すエラーが返されます。データベースが実行されたら、サインインを再試行して接続を確立します。

Microsoft Entra 条件付きアクセスポリシー

SharePoint Online インデクサーを作成するときに、デバイスコードを指定した後に Microsoft Entra アプリへのサインインを求める手順があります。 "Your sign-in was successful but your admin requires the device requesting access to be managed" というメッセージが表示された場合、インデクサーは条件付きアクセスポリシーによって SharePoint ドキュメントライブラリからブロックされている可能性があります。

ポリシーを更新し、インデクサーによるドキュメントライブラリへのアクセスを許可するには:

Azure portal を開き、Microsoft Entra 条件付きアクセスを検索します。
左側のメニューの [ポリシー] を選択します。このページを表示するためのアクセス権がない場合は、アクセス権を持つ他のユーザーを見つけるか、アクセス権を取得する必要があります。
SharePoint Online インデクサーによるドキュメントライブラリへのアクセスをブロックしているポリシーを特定します。インデクサーをブロックしている可能性のあるポリシーには、[ユーザーとグループ] セクションでのインデクサーの作成手順で認証に使用したユーザーアカウントが含まれています。ポリシーには次の条件も含まれている場合があります。
- Windows プラットフォームを制限する。
- モバイルアプリとデスクトップクライアントを制限する。
- [デバイスの状態] が [はい] に構成されている。
インデクサーをブロックしているポリシーを確認したら、インデクサーを除外します。まず、検索サービスの IP アドレスを取得します。

最初に、お使いの検索サービスの完全修飾ドメイン名 (FQDN) を取得します。 FQDN は <your-search-service-name>.search.windows.net のようになります。 FQDN は Azure portal で確認できます。

FQDN を取得したら、FQDN の nslookup (または ping) を実行して検索サービスの IP アドレスを取得します。次の例では、Azure Storage ファイアウォールのインバウンド規則に "150.0.0.1" を追加します。検索サービスインデクサーが Azure Storage アカウントにアクセスできるようにするには、ファイアウォール設定が更新されてから最大 15 分かかることがあります。
```
nslookup contoso.search.windows.net
Server:  server.example.org
Address:  10.50.10.50

Non-authoritative answer:
Name:    <name>
Address:  150.0.0.1
Aliases:  contoso.search.windows.net
```
リージョンのインデクサー実行環境の IP アドレスの範囲を取得します。

追加の IP アドレスは、インデクサーのマルチテナント実行環境から発信される要求に使用されます。この IP アドレス範囲は、サービスタグから取得できます。

AzureCognitiveSearch サービスタグの IP アドレス範囲は、Discovery API またはダウンロード可能な JSON ファイル経由で取得できます。

この演習では、検索サービスが Azure パブリッククラウドであることを前提として、Azure パブリック JSON ファイルをダウンロードする必要があります。

JSON ファイルから、検索サービスが米国中西部にあることを前提として、マルチテナントインデクサー実行環境の IP アドレスの一覧が次のように表示されます。
```
    {
      "name": "AzureCognitiveSearch.WestCentralUS",
      "id": "AzureCognitiveSearch.WestCentralUS",
      "properties": {
        "changeNumber": 1,
        "region": "westcentralus",
        "platform": "Azure",
        "systemService": "AzureCognitiveSearch",
        "addressPrefixes": [
          "52.150.139.0/26",
          "52.253.133.74/32"
        ]
      }
    }
```
Azure portal の [条件付きアクセス] ページに戻り、左側のメニューで [ネームドロケーション] を選択し、[IP 範囲の場所] を選択します。新しいネームドロケーションに名前を付けて、最後の 2 つの手順で収集した検索サービスとインデクサーの実行環境の IP 範囲を追加します。 1
- 検索サービスの IP アドレスでは、有効な IP 範囲のみが受け入れられるため、IP アドレスの末尾に "/32" を追加する必要がある場合があります。
- インデクサーの実行環境の IP 範囲は、検索サービスが存在するリージョンの IP 範囲を追加する必要があるだけであることに注意してください。
新しいネームドロケーションをポリシーから除外します。
1. 左側のメニューの [ポリシー] を選択します。
2. インデクサーをブロックしているポリシーを選択します。
3. [条件] を選択します。
4. [場所] を選択します。
5. [除外] を選択し、新しいネームドロケーションを追加します。
6. 変更を [保存] します。
ポリシーが更新され、新しいポリシールールが適用されるまで数分待ちます。
インデクサーを再作成することを試みます。
1. 作成したデータソースオブジェクトに対する更新要求を送信します。
2. インデクサー作成要求を再送信します。新しいコードを使用してサインインした後、別のインデクサー作成要求を送信します。

サポートされていないドキュメントの種類のインデックス作成

Azure Blob Storage のコンテンツにインデックスを付けるときに、サポートされていないコンテンツの種類の BLOB がコンテナーに含まれている場合、インデクサーではそのドキュメントはスキップされます。それ以外の場合、個々のドキュメントに問題がある可能性があります。

このような状況では、個々のドキュメントに問題がある場合にインデクサーの処理を続行できるようにする構成オプションを設定できます。

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false, "failOnUnprocessableDocument" : false } }
}

ドキュメントの欠落

インデクサーでは、外部データソースからドキュメントまたは行が抽出され、検索サービスによってインデックス付けされる "検索ドキュメント" が作成されます。場合によっては、データソースに存在するドキュメントが検索インデックスに表示されません。この予想外の結果は、次の理由で発生する可能性があります。

インデクサーの実行後に、ドキュメントが更新された。インデクサーがスケジュール設定されている場合は、いずれ再実行されて、ドキュメントを処理します。
ドキュメントを取り込む前にインデクサーがタイムアウトした。最大処理時間の制限があり、これを超えるとドキュメントは処理されなくなります。インデクサーの状態は、ポータルで確認するか、Get Indexer Status (REST API) を呼び出すことで確認できます。
フィールドマッピングまたは AI エンリッチメントによってドキュメントが変更され、検索インデックス内のそのアーティキュレーションが予想とは異なっている。
変更の追跡の値が間違っている、または前提条件が満たされていない。高基準値の日付が将来の時刻に設定されている場合、これよりも前の日付になっているドキュメントはすべて、インデクサーによってスキップされます。インデクサーの状態の 'initialTrackingState' および 'finalTrackingState' フィールドを使用して、インデクサーの変更追跡の状態を判断できます。 Azure SQL と MySQL のインデクサーには、ソーステーブルの高いウォーターマーク列のインデックスが必要です。または、インデクサーによって使用されているクエリがタイムアウトしている可能性があります。

ヒント

ドキュメントが見つからない場合は、使用しているクエリを調べて、問題のドキュメントが除外されていないことを確認します。特定のドキュメントのクエリを実行するには、Lookup Document REST API を使用します。

Blob Storage のコンテンツが見つからない

BLOB インデクサーによって、コンテナー内の BLOB からテキストが検索されて抽出されます。テキストの抽出に関する問題には次のものがあります。

ドキュメントに、スキャンしたイメージしか含まれていません。スキャンしたイメージ (JPG) などテキスト以外のコンテンツを含む PDF BLOB では、標準 BLOB インデックスパイプラインで結果が生成されません。イメージコンテンツにテキスト要素が含まれる場合は、OCR または画像分析を使用して、テキストを検索して抽出できます。
BLOB インデクサーは、メタデータのインデックス付けのみを行うように構成されています。コンテンツを抽出するには、コンテンツとメタデータの両方を抽出するように BLOB インデクサーを構成する必要があります。

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "dataToExtract" : "contentAndMetadata" } }
}

Azure Cosmos DB のコンテンツが見つからない

Azure AI Search には、Azure Cosmos DB のインデックス作成に対する暗黙的な依存関係があります。 Azure Cosmos DB で自動インデックス作成を無効にすると、Azure AI Search は正常な状態を返しますが、コンテナーの内容のインデックス作成に失敗します。設定を確認してインデックス付けをオンにする手順については、Azure Cosmos DB でのインデックス付けの管理に関する記事をご覧ください。

データソースとインデックスのドキュメント数の不一致

インデクサーでは、データソース、インデックス自体、またはコード内のカウントとは異なるドキュメント数が表示される場合があります。この動作が発生する可能性がある理由を次に示します。

インデックスでは、実際のドキュメント数の表示に遅延が発生する可能性があります (特にポータル)。
インデクサーに、削除されたドキュメントポリシーがある。ドキュメントが削除される前にインデックスが作成されている場合、削除されたドキュメントがインデクサーによってカウントされます。
データソースの ID 列が一意ではない場合。これは、Azure Cosmos DB など、列の概念を持つデータソースに適用されます。
データソース定義に、レコード数の見積もりに使用しているものとは異なるクエリがある場合。たとえば、お使いのデータベースで、データベースレコード数のクエリを実行しているが、データソース定義クエリでは、インデックスを付けるレコードのサブセットのみを選択している場合があります。
カウントが、パイプラインのコンポーネント (データソース、インデクサー、インデックス) ごとに異なる間隔でチェックされています。
データソースに、多数のドキュメントにマップされたファイルがある。この条件は、BLOB にインデックスを作成しているときに、"parsingMode" が jsonArray および jsonLines に設定されていると発生する可能性があります。

ドキュメントが複数回処理される

インデクサーでは、インデックス付けを行うときにデータソース内の新規および変更されたすべてのドキュメントが確実に取得されるように、保守的なバッファリング戦略が使用されます。特定の状況で、これらのバッファーが重複することで、インデクサーによってドキュメントに 2 回以上インデックスが作成される結果、処理されるドキュメントの数がデータソース内のドキュメントの実際の数より多くなることがあります。この動作は、インデックスに格納されるデータ (ドキュメントの複製など) には影響しませんが、最終的に整合されるまで時間がかかる可能性があります。この条件は、次のいずれかの条件に該当する場合に特によく見られます。

オンデマンドインデクサー要求がすばやく連続して発行される
データソースのトポロジに、複数のレプリカとパーティションが含まれる (このような例の 1 つについては、こちらを参照)
データソースは Azure SQL データベースであり、"高基準値" として選択された列の型は datetime2 です

インデクサーは、すばやく連続して複数回呼び出されるようには意図されていません。すばやい更新が必要な場合、サポートされているアプローチでは、更新をインデックスにプッシュし、同時にデータソースを更新します。オンデマンド処理の場合は、5 分以上の間隔で要求のペースを調整し、スケジュールに従ってインデクサーを実行することをお勧めします。

30 秒のバッファーを使用したドキュメント重複処理の例

ドキュメントが 2 回処理される条件については、それぞれのアクションとカウンターアクションを示した以下のタイムラインで説明しています。次のタイムラインから、この問題を確認できます。

タイムライン (hh:mm:ss)	Event	インデクサーの高基準	Comment
00:01:00	`doc1` をデータソースへ書き込み、最終的に整合させる	`null`	ドキュメントのタイムスタンプは 00:01:00 です。
00:01:05	`doc2` をデータソースへ書き込み、最終的に整合させる	`null`	ドキュメントのタイムスタンプは 00:01:05 です。
00:01:10	インデクサーが開始する	`null`
00:01:11	インデクサーによって、00:01:10 より前のすべての変更のクエリが実行される。インデクサーによってクエリが実行されるレプリカが、たまたま `doc2` のみを認識し、`doc2` のみが取得される	`null`	インデクサーによって、タイムスタンプを開始する前にすべての変更が要求されますが、実際にはサブセットを受け取ります。この動作には、ルックバックバッファー期間が必要です。
00:01:12	インデクサーによって、`doc2` の 1 回目の処理が行われる	`null`
00:01:13	インデクサーが終了する	00:01:10	高基準が、現在のインデクサー実行のタイムスタンプを開始するように更新されます。
00:01:20	インデクサーが開始する	00:01:10
00:01:21	インデクサーによって、00:00:40 から 00:01:20 の間のすべての変更のクエリが実行される。インデクサーによってクエリが実行されるレプリカが、たまたま `doc1` と `doc2` の両方を認識し、`doc1` と `doc2` が取得される	00:01:10	インデクサーによって、現在の高基準から 30 秒のバッファーを差し引いた値と、現在のインデクサー実行の開始タイムスタンプの間のすべての変更に対して要求されます。
00:01:22	インデクサーによって、`doc1` の 1 回目の処理が行われる	00:01:10
00:01:23	インデクサーによって、`doc2` の 2 回目の処理が行われる	00:01:10
00:01:24	インデクサーが終了する	00:01:20	高基準が、現在のインデクサー実行のタイムスタンプを開始するように更新されます。
00:01:32	インデクサーが開始する	00:01:20
00:01:33	インデクサーによって、00:00:50 から 00:01:32 の間のすべての変更のクエリが実行され、`doc1` と `doc2` が取得される	00:01:20	インデクサーによって、現在の高基準から 30 秒のバッファーを差し引いた値と、現在のインデクサー実行の開始タイムスタンプの間のすべての変更に対して要求されます。
00:01:34	インデクサーによって、`doc1` の 2 回目の処理が行われる	00:01:20
00:01:35	インデクサーによって、`doc2` の 3 回目の処理が行われる	00:01:20
00:01:36	インデクサーが終了する	00:01:32	高基準が、現在のインデクサー実行のタイムスタンプを開始するように更新されます。
00:01:40	インデクサーが開始する	00:01:32
00:01:41	インデクサーによって、00:01:02 から 00:01:40 の間のすべての変更のクエリが実行され、`doc2` が取得される	00:01:32	インデクサーによって、現在の高基準から 30 秒のバッファーを差し引いた値と、現在のインデクサー実行の開始タイムスタンプの間のすべての変更に対して要求されます。
00:01:42	インデクサーによって、`doc2` の 4 回目の処理が行われる	00:01:32
00:01:43	インデクサーが終了する	00:01:40	このインデクサーの実行が、データソースへの最後の書き込みから 30 秒を超えて開始され、`doc2` も処理されていることに注意してください。これは、00:01:35 より前のすべてのインデクサー実行が削除された場合、`doc1` と `doc2` を処理する最初で唯一の実行になるため、予期される動作です。

実際には、このシナリオは、特定のデータソースに対して、オンデマンドインデクサーが相互に数分以内に手動で呼び出された場合にのみ発生します。同じドキュメントに対して同じスキルを複数回実行している場合、数が一致しない (インデクサーの実行統計によると合計 345 ドキュメントがインデクサーによって処理されたが、データソースとインデックスに 340 ドキュメントがあるような場合) か、請求が増える可能性があります。スケジュールを使用してインデクサーを実行することをお勧めします。

並列インデックス作成

複数のインデクサーが同時に動作している場合、一部がキューに入り、実行を開始するためにリソースが利用可能になるのを待機することが一般的です。同時に実行できるインデクサーの数は、いくつかの要因によって決まります。インデクサーがスキルセットにリンクされていない場合、並列実行用の容量は、AI Search サービス内で設定されたレプリカとパーティションの数によって決まります。

一方、インデクサーはスキルセットに関連付けられている場合、AI Search の内部クラスター内で動作します。この場合の同時実行の能力は、スキルセットの複雑さと他のスキルセットが同時に実行されているかどうかによって決まります。組み込みインデクサーはソースから確実にデータを抽出できるように設計されているため、スケジュール通りに実行されている限りはデータが取りこぼされることはありません。ただし、並列化とスケールアウトのインデクサープロセスにはある程度の時間がかかる場合があります。

秘密度ラベルを使用したドキュメントのインデックス作成

ドキュメントに秘密度ラベルが設定されている場合は、インデックスを付けることができない可能性があります。エラーが発生する場合は、インデックスを作成する前にラベルを削除してください。

次の方法で共有

Azure AI Search のインデクサーのトラブルシューティングガイダンス

制限されたリソースへの接続のトラブルシューティング

ファイアウォール規則

ネットワークセキュリティグループ (NSG) のルール

ネットワークエラー

Azure SQL Database のサーバーレスインデックス作成 (エラーコード 40613)

Microsoft Entra 条件付きアクセスポリシー

サポートされていないドキュメントの種類のインデックス作成

ドキュメントの欠落

Blob Storage のコンテンツが見つからない

Azure Cosmos DB のコンテンツが見つからない

データソースとインデックスのドキュメント数の不一致

ドキュメントが複数回処理される

30 秒のバッファーを使用したドキュメント重複処理の例

並列インデックス作成

秘密度ラベルを使用したドキュメントのインデックス作成

関連項目

フィードバック

その他のリソース

次の方法で共有

Azure AI Search のインデクサーのトラブルシューティング ガイダンス

制限されたリソースへの接続のトラブルシューティング

ファイアウォール規則

ネットワーク セキュリティ グループ (NSG) のルール

ネットワーク エラー

Azure SQL Database のサーバーレス インデックス作成 (エラー コード 40613)

Microsoft Entra 条件付きアクセス ポリシー

サポートされていないドキュメントの種類のインデックス作成

ドキュメントの欠落

Blob Storage のコンテンツが見つからない

Azure Cosmos DB のコンテンツが見つからない

データ ソースとインデックスのドキュメント数の不一致

ドキュメントが複数回処理される

30 秒のバッファーを使用したドキュメント重複処理の例

並列インデックス作成

秘密度ラベルを使用したドキュメントのインデックス作成

関連項目

フィードバック

その他のリソース

Azure AI Search のインデクサーのトラブルシューティングガイダンス

ネットワークセキュリティグループ (NSG) のルール

ネットワークエラー

Azure SQL Database のサーバーレスインデックス作成 (エラーコード 40613)

Microsoft Entra 条件付きアクセスポリシー

データソースとインデックスのドキュメント数の不一致