Azure AI Search でのインデクサーの一般的なエラーと警告のトラブルシューティング

この記事では、Azure AI Search でのインデックス作成と AI エンリッチメント中に発生する可能性がある一般的なエラーと警告に関する情報と解決策について説明します。

エラー数が 'maxFailedItems' を超えると、インデックス作成が停止します。

インデクサーでこれらのエラーを無視する (および "失敗したドキュメント" をスキップする) 場合は、ここで説明するようにmaxFailedItemsとmaxFailedItemsPerBatchを更新することを検討してください。

この記事のエラー情報は、エラーの解決に役立ち、インデックス作成を続行できます。

警告はインデックス作成を停止しませんが、予期しない結果になる可能性のある条件を示します。 アクションを実行するかどうかは、データとシナリオによって異なります。

特定のインデクサー エラーはどこにありますか?

Azure portal でインデクサーの状態を確認し、エラーを特定するには、次の手順に従います。

1. Azure portal にサインインし、ご利用の検索サービスを探します。

2. 左側で、[Search Management]\(検索管理\)>Indexers を展開し、インデクサーを選択します。

3. [ 実行履歴] で、状態を選択します。 成功を含むすべての状態には、実行に関する詳細が表示されます。

4. エラーが発生した場合は、エラー メッセージにカーソルを合わせます。 画面の右側にウィンドウが表示され、エラーに関する詳細情報が表示されます。

一時的なエラー

一時的なネットワーク通信の中断、実行時間の長いプロセスからのタイムアウト、特定のドキュメントの微妙な違いなど、さまざまな理由から、インデクサーの実行中に一時的なエラーや警告が発生するのが一般的です。 ただし、これらのエラーは一時的なものであり、後続のインデクサーの実行で解決する必要があります。

これらのエラーを効果的に管理するには、 たとえば、インデクサーをスケジュールに従って 5 分ごとに実行することをお勧めします。次の実行は、サービスの 最大ランタイム制限 に従って、最初の実行が完了してから 5 分後に開始されます。 定期的にスケジュールされた実行は、一時的なエラーや警告を修正するのに役立ちます。

複数のインデクサー実行でエラーが解決しない場合は、一時的な問題ではない可能性があります。 このような場合は、次の一覧を参照して、考えられる解決策を確認してください。

エラーのプロパティ

Error: Could not read document

インデクサーがデータ ソースからドキュメントを読み取れませんでした。 これは、次の理由で発生する可能性があります。

Error: Could not extract content or metadata from your document

BLOB データ ソースを持つインデクサーは、ドキュメント (PDF ファイルなど) からコンテンツまたはメタデータを抽出できませんでした。 これは、次の理由で発生する可能性があります。

Error: Could not parse document

インデクサーはデータ ソースからドキュメントを読み取りますが、ドキュメントの内容を指定されたフィールド マッピング スキーマに変換する際に問題が発生しました。 これは、次の理由で発生する可能性があります。

Error: Could not map output field 'xyz' to search index due to deserialization problem while applying mapping function 'abc'

出力データが使用しているマッピング関数の形式が間違っているため、出力マッピングが失敗した可能性があります。 たとえば、バイナリ データ Base64Encode マッピング関数を適用すると、このエラーが生成されます。 この問題を解決するには、マッピング関数を指定せずにインデクサーを再実行するか、マッピング関数が出力フィールドのデータ型と互換性があることを確認します。 詳細については 、出力フィールドのマッピング を参照してください。

Error: Could not execute skill

インデクサーはスキルセットでスキルを実行できませんでした。

Error: Could not execute skill because the Web API request failed

Web API の呼び出しが失敗したため、スキルの実行に失敗しました。 通常、このクラスのエラーは、カスタム スキルが使用されるときに発生します。その場合は、問題を解決するためにカスタム コードをデバッグする必要があります。 代わりに、組み込みのスキルからのエラーの場合は、エラー メッセージを参照して問題の修正に関するヘルプを参照してください。

この問題をデバッグする際は、この スキルのスキル入力 に関する警告に注意してください。 インデクサーが予期しない入力を渡しているため、Web API エンドポイントが失敗する可能性があります。

Error: Could not execute skill because Web API skill response is invalid

Web API の呼び出しから無効な応答が返されたため、スキルの実行に失敗しました。 通常、このクラスのエラーは、カスタム スキルが使用されるときに発生します。その場合は、問題を解決するためにカスタム コードをデバッグする必要があります。 代わりに、組み込みのスキルからエラーが発生した場合は、 サポート チケット を提出して支援を受けてください。

Error: Type of value has a mismatch with column type. Couldn't store in 'xyz' column. Expected type is 'abc'

データ ソースに、インデックスにマップしようとしているフィールドとは異なるデータ型のフィールドがある場合、このエラーが発生する可能性があります。 データ ソース フィールドのデータ型を確認し、それらが インデックス データ型に正しくマップされていることを確認します。

Error: Skill did not execute within the time limit

このエラー メッセージが表示される場合は 2 つのケースがあり、それぞれ異なる方法で処理する必要があります。 このエラーを返したスキルに応じて、次の手順に従います。

組み込みの Azure AI サービス スキル

言語検出、エンティティ認識、OCR など、組み込みのコグニティブ スキルの多くは、Azure AI サービス API エンドポイントによってサポートされています。 これらのエンドポイントに一時的な問題があり、要求がタイムアウトすることがあります。一時的な問題の場合は、待ってからやり直す以外に解決策はありません。 軽減策として、スケジュールに従って実行するようにインデクサー を設定することを検討してください。 スケジュールされたインデックス作成は、中断したところから再開されます。 一時的な問題が解決されると仮定すると、インデックス作成とコグニティブ スキルの処理は、次回のスケジュールされた実行で続行できる必要があります。

組み込みのコグニティブ スキルの同じドキュメントでこのエラーが引き続き表示される場合は、 サポート チケット を提出してサポートを受けてください。これは想定されていないためです。

カスタム スキル

カスタム スキルでタイムアウト エラーが発生した場合は、いくつかのことを試すことができます。 まず、カスタム スキルを確認し、無限ループでスタックしていないことを確認し、結果を一貫して返していることを確認します。 結果が返されることを確認したら、実行時間を確認します。 カスタム スキル定義に timeout 値を明示的に設定しなかった場合、既定の timeout は 30 秒です。 スキルが実行できる時間が 30 秒ほど長くない場合は、カスタム スキル定義に高い timeout 値を指定できます。 タイムアウトが 90 秒に設定されているカスタム スキル定義の例を次に示します。

  {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "uri": "<your custom skill uri>",
        "batchSize": 1,
        "timeout": "PT90S",
        "context": "/document",
        "inputs": [
          {
            "name": "input",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "output",
            "targetName": "output"
          }
        ]
      }

timeout パラメーターに設定できる最大値は 230 秒です。 カスタム スキルが 230 秒以内に一貫して実行できない場合は、1 回の実行で処理するドキュメントが少なくなるため、カスタム スキルの batchSize を減らすことを検討してください。 batchSizeを既に 1 に設定している場合は、230 秒以内に実行できるようにスキルを書き直すか、1 つのカスタム スキルの実行時間が最大 230 秒になるように複数のカスタム スキルに分割する必要があります。 詳細については、 カスタム スキルのドキュメント を参照してください。

Error: Could not 'MergeOrUpload' | 'Delete' document to the search index

ドキュメントが読み取られ、処理されましたが、インデクサーが検索インデックスに追加できませんでした。 これは、次の理由で発生する可能性があります。

Error: Could not index document because some of the document's data was not valid

ドキュメントはインデクサーによって読み取られ、処理されましたが、インデックス フィールドの構成と、インデクサーによって抽出および処理されたデータの構成が一致しないため、検索インデックスに追加できませんでした。 これは、次の理由で発生する可能性があります。

いずれの場合も、インデクサーのサポートされているデータ型とデータ型マップを参照して、インデックス スキーマを正しく構築し、適切なインデクサー フィールド マッピングを設定していることを確認してください。 エラー メッセージには、不一致の原因を追跡するのに役立つ詳細が含まれています。

Error: Integrated change tracking policy cannot be used because table has a composite primary key

これは SQL テーブルに適用されます。通常、キーが複合キーとして定義されている場合、またはテーブルで (Azure Search インデックスではなく SQL インデックスのように) 一意のクラスター化インデックスが定義されている場合に発生します。 主な理由は、キー属性が 一意のクラスター化インデックスの複合主キーに変更されることです。 その場合は、SQL テーブルに一意のクラスター化インデックスがないことを確認するか、キー フィールドを、重複する値が含まれていないことが保証されているフィールドにマップします。

Error: Could not process document within indexer max run time

このエラーは、インデクサーが、許可された実行時間内にデータ ソースから 1 つのドキュメントの処理を完了できない場合に発生します。 スキルセットを使用すると、最大実行時間が短くなります。 このエラーが発生すると、maxFailedItems が 0 以外の値に設定されている場合、インデクサーは今後の実行時にドキュメントをバイパスして、インデックス作成を進行できるようにします。 ドキュメントをスキップする余裕がない場合、またはこのエラーが一貫して表示される場合は、1 つのインデクサーの実行内で部分的な進行状況を行えるように、ドキュメントをより小さなドキュメントに分割することを検討してください。

Error: Could not project document

このエラーは、インデクサーが ナレッジ ストアにデータを投影 しようとしたときに、試行でエラーが発生した場合に発生します。 このエラーは一貫性があり、修正可能な場合もあれば、プロジェクション出力シンクの一時的な障害である可能性があり、解決するには待機して再試行する必要があります。 既知のエラー状態と考えられる解決策のセットを次に示します。

Error: The cognitive service for skill '<skill-name>' has been throttled

Azure AI サービスの呼び出しが制限されたため、スキルの実行に失敗しました。 通常、このクラスのエラーは、多数のスキルが並列で実行されている場合に発生します。 Microsoft.Search.Documents クライアント ライブラリを使用してインデクサーを実行している場合は、 SearchIndexingBufferedSender を 使用して、失敗した手順で自動再試行を取得できます。 それ以外の場合は、 インデクサーをリセットして再実行できます。

Error: Expected IndexAction metadata

"予期される IndexAction メタデータ" エラーは、インデクサーが実行する必要があるアクションを特定するためにドキュメントを読み取ろうとしたときに、ドキュメントに対応するメタデータが見つからなかったことを意味します。 通常、このエラーは、インデクサーをリセットせずにインデクサーに注釈キャッシュが追加または削除された場合に発生します。 これに対処するには、 インデクサーをリセットして再実行する必要があります。

Warning: Skill input was invalid

スキルへの入力が見つからない、型が間違っている、または無効です。 次の情報が表示される場合があります。

• Could not execute skill

• Skill executed but may have unexpected results

コグニティブ スキルには、必要な入力とオプションの入力があります。 たとえば、キー フレーズ抽出スキルには、languageCodetext必要な 2 つの入力があり、省略可能な入力はありません。 カスタム スキル入力はすべて省略可能な入力と見なされます。

必要な入力がない場合、または入力が適切な型でない場合、スキルはスキップされ、警告が生成されます。 スキップされたスキルは出力を生成しません。 スキップされたスキルの出力をダウンストリームスキルが使用する場合、他の警告が生成される可能性があります。

省略可能な入力がない場合、スキルは引き続き実行されますが、入力がないために予期しない出力が生成される可能性があります。

どちらの場合も、この警告はデータの形状が原因です。 たとえば、 firstName、 middleName、および lastNameのフィールドを持つユーザーに関する情報を含むドキュメントがある場合、 middleNameのエントリがないドキュメントが存在する可能性があります。 パイプライン内のスキルに入力として middleName を渡すと、このスキル入力に時間が不足することが予想されます。 この警告の結果としてアクションが必要かどうかを判断するには、データとシナリオを評価する必要があります。

不足している入力の既定値を指定する場合は、 条件付きスキル を使用して既定値を生成し、スキル入力として 条件付きスキル の出力を使用できます。

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == null" },
        { "name": "whenTrue", "source": "= 'en'" },
        { "name": "whenFalse", "source": "= $(/document/language)" }
    ],
    "outputs": [ { "name": "output", "targetName": "languageWithDefault" } ]
}

Warning: Skill input 'languageCode' has the following language codes 'X,Y,Z', at least one of which is invalid.

ダウンストリーム スキルのオプションの languageCode 入力に渡される 1 つ以上の値はサポートされていません。 これは、 LanguageDetectionSkill の出力を後続のスキルに渡し、出力がそれらのダウンストリーム スキルでサポートされている言語よりも多くの言語で構成されている場合に発生する可能性があります。

無効な countryHint 入力が LanguageDetectionSkill に渡された場合は、次のような警告を受け取ることもできます。 その場合は、その入力にデータ ソースから使用しているフィールドに、有効な ISO 3166-1 alpha-2 の 2 文字の国コードが含まれていることを検証します。 一部が有効で無効な場合は、次のガイダンスに進みますが、ユース ケースに合わせて languageCode を countryHint に置き換え、 defaultLanguageCode を defaultCountryHint に置き換えます。

データ セットがすべて 1 つの言語であることがわかっている場合は、 LanguageDetectionSkill と languageCode スキルの入力を削除し、代わりにそのスキルの defaultLanguageCode スキル パラメーターを使用する必要があります(そのスキルの言語がサポートされていると仮定します)。

データ セットに複数の言語が含まれていることがわかっているため、 LanguageDetectionSkill と languageCode 入力が必要な場合は、ダウンストリーム スキルにテキストを渡す前に、サポートされていない言語でテキストを除外するために ConditionalSkill を追加することを検討してください。 EntityRecognitionSkill の例を次に示します。

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == 'de' || $(/document/language) == 'en' || $(/document/language) == 'es' || $(/document/language) == 'fr' || $(/document/language) == 'it'" },
        { "name": "whenTrue", "source": "/document/content" },
        { "name": "whenFalse", "source": "= null" }
    ],
    "outputs": [ { "name": "output", "targetName": "supportedByEntityRecognitionSkill" } ]
}

このエラー メッセージを生成できるスキルごとに、現在サポートされている言語のリファレンスをいくつか次に示します。

• EntityRecognitionSkill でサポートされている言語
• EntityLinkingSkill でサポートされている言語
• KeyPhraseExtractionSkill でサポートされている言語
• LanguageDetectionSkill でサポートされている言語
• PIIDetectionSkill でサポートされている言語
• SentimentSkill でサポートされている言語
• Translator でサポートされている言語
• Text SplitSkill でサポートされている言語: da, de, en, es, fi, fr, it, ko, pt

Warning: Skill input was truncated

コグニティブ スキルは、一度に分析できるテキストの長さを制限します。 テキスト入力が制限を超えた場合、テキストはエンリッチされる前に切り捨てられます。 スキルは実行されますが、すべてのデータに対して実行されるわけではありません。

次の LanguageDetectionSkill 例では、入力が文字制限を超えている場合、 'text' 入力フィールドによってこの警告がトリガーされることがあります。 入力制限については、 スキルリファレンスドキュメントを参照してください。

 {
    "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
    "inputs": [
      {
        "name": "text",
        "source": "/document/text"
      }
    ],
    "outputs": [...]
  }

すべてのテキストが確実に分析されるようにする場合は、 分割スキルの使用を検討してください。

Warning: Web API skill response contains warnings

インデクサーはスキルセットでスキルを実行しましたが、Web API 要求からの応答は警告があることを示します。 警告を確認して、データがどのように影響を受けるか、さらにアクションが必要かどうかを理解します。

Warning: The current indexer configuration does not support incremental progress

この警告は、Azure Cosmos DB データ ソースに対してのみ発生します。

インデックス作成中の増分的な進行状況により、インデクサーの実行が一時的なエラーまたは実行時間制限によって中断された場合、インデクサーは、コレクション全体のインデックスを最初から再作成する必要なく、次回の実行時に中断した場所を選択できます。 これは、大規模なコレクションのインデックスを作成する場合に特に重要です。

未完了のインデックス作成ジョブを再開する機能は、 _ts 列によって並べ替えられたドキュメントを持つことに基づきます。 インデクサーはタイムスタンプを使用して、次に取得するドキュメントを決定します。 _ts列がない場合、またはカスタム クエリが順序付けされているかどうかをインデクサーが判断できない場合、インデクサーは最初から開始され、この警告が表示されます。

この動作をオーバーライドし、増分進行状況を有効にし、 assumeOrderByHighWaterMarkColumn 構成プロパティを使用してこの警告を抑制することができます。

詳細については、「 増分進行状況とカスタム クエリ」を参照してください。

Warning: Some data was lost during projection. Row 'X' in table 'Y' has string property 'Z' which was too long.

Table Storage サービスには、エンティティプロパティの大きさに制限があります。 文字列の文字数は 32,000 文字以下です。 文字列プロパティが 32,000 文字を超える行が投影されている場合、最初の 32,000 文字のみが保持されます。 この問題を回避するには、文字列プロパティが 32,000 文字を超える行を投影しないようにします。

Warning: Truncated extracted text to X characters

インデクサーは、任意の 1 つのドキュメントから抽出できるテキストの量を制限します。 この制限は、価格レベルによって異なります。Free レベルでは 32,000 文字、Basic では 64,000 文字、Standard では 400 万文字、Standard S2 では 800 万文字、Standard S3 の場合は 1,600 万文字です。 切り捨てられたテキストはインデックス付けされません。 この警告を回避するには、大量のテキストを含むドキュメントを複数の小さなドキュメントに分割してみてください。

詳細については、「 インデクサーの制限」を参照してください。

Warning: Could not map output field 'X' to search index

存在しないデータまたは null データを参照する出力フィールド マッピングでは、ドキュメントごとに警告が生成され、空のインデックス フィールドが生成されます。 この問題を回避するには、入力ミスの可能性がないか出力フィールド マッピングのソース パスを再確認するか、 条件付きスキルを使用して既定値を設定します。 詳細については 、出力フィールドのマッピング を参照してください。

Warning: The data change detection policy is configured to use key column 'X'

データ変更検出ポリシーには、変更 の検出に使用する列に固有の要件があります。 これらの要件の 1 つは、ソース項目が変更されるたびにこの列が更新される点です。 もう 1 つの要件は、この列の新しい値が前の値より大きいということです。 キー列は更新ごとに変更されないため、この要件を満たしていません。 この問題を回避するには、変更検出ポリシーに別の列を選択します。

Warning: Document text appears to be UTF-16 encoded, but is missing a byte order mark

インデクサー解析モードでは、テキストを解析する前にエンコード方法を把握しておく必要があります。 テキストをエンコードする最も一般的な 2 つの方法は、UTF-16 と UTF-8 です。 UTF-8 は可変長エンコードで、各文字の長さは 1 バイトから 4 バイトです。 UTF-16 は固定長エンコードで、各文字の長さは 2 バイトです。 UTF-16 には、 big endian と little endianという 2 つの異なるバリエーションがあります。 テキスト エンコードは、テキストの前の一連のバイト byte order markによって決定されます。

バイトオーダーマークが存在しない場合、テキストは UTF-8 としてエンコードされていると見なされます。

この警告を回避するには、この BLOB のテキスト エンコードを特定し、適切なバイトオーダー マークを追加します。

Warning: Azure Cosmos DB collection 'X' has a Lazy indexing policy. Some data may be lost

Lazy インデックス作成ポリシーを持つコレクションを一貫して照会できないため、インデクサーにデータが不足しています。 この警告を回避するには、インデックス作成ポリシーを [整合性] に変更します。

Warning: The document contains very long words (longer than 64 characters). These words may result in truncated and/or unreliable model predictions.

この警告は、Azure AI サービスの言語サービスから渡されます。 場合によっては、長い文字列が長い URL だけの場合など、この警告は無視しても安全です。 単語が 64 文字より長い場合は、"64 文字に切り捨てられ、モデルの予測に影響する可能性があります" ことに注意してください。

Error: Cannot write more bytes to the buffer than the configured maximum buffer size

インデクサーには ドキュメント サイズの制限があります。 データ ソース内のドキュメントが、サービス レベルに関して説明されているように、サポートされているサイズ制限よりも小さいことを確認します。

Error: Failed to compare value 'X' of type M to value 'Y' of type N.

このエラーは、通常、 dataChangeDetectionPolicy に使用されるソース列の種類がインデクサーで想定されているものと一致しない場合 (特に convertHighWaterMarkToRowVersion が有効になっている場合)、Azure SQL インデクサーで発生します。

たとえば、変更検出に使用される列が datetime 型であるのに、convertHighWaterMarkToRowVersion が有効になっているためにインデクサーで rowversion 型が必要な場合、不一致によってエラーが発生します。

ソースの [High Water Mark] 列のデータ型を確認し、それに応じてインデクサーの構成を更新します。 検証と更新が完了したら、インデクサーをリセットして再実行し、列の値を処理します。