Azure AI Search のデバッグ セッション

デバッグ セッションは、Azure portal の既存のスキルセットと連携するビジュアル エディターです。セッションの間に、インデクサーとスキルセットによって生成された 1 つのエンリッチされたドキュメントの構造と内容が表示されます。 実際のドキュメントを使っているので、このセッションは対話形式です。エラーの特定、スキルの実行の変更と呼び出し、結果の検証をリアルタイムで行うことができます。 変更によって問題が解決した場合は、公開されているスキルセットにコミットして、修正をグローバルに適用することができます。

この記事では、サポートされているシナリオとエディターの構成について説明します。 エディターのタブとセクションでは、スキルセットのさまざまなレイヤーが展開され、スキルセットの構造、フロー、実行時に生成されるコンテンツを確認できます。

サポートされるシナリオ

デバッグ セッションを使用して、次によって問題を調査して解決します。

• OCR、画像分析、エンティティ認識、キーワード抽出などの、AI エンリッチメントに使用される組み込みのスキル。

• テキスト分割によるデータ チャンキング、および埋め込みスキルによるベクター化を使用する、垂直統合に使用される組み込みのスキル。

• 指定した外部処理を統合するために使用されるカスタム スキル。

最初の 2 つのシナリオを表している、以下のデバッグ セッションの画像を比較してみましょう。 どちらのシナリオでも、表示領域には、ソース ドキュメントから検索インデックスに至る過程で実行されるコンテンツの生成スキルや変換スキルのプログレッションが表示されています。 このフローにはインデックス マッピング オプションが含まれており、矢印をたどって処理の流れを追うことができます。 右側の詳細ペインは、状況に合わせて変化します。 ここには、エンリッチされたドキュメントの表現、またはスキルやマッピングの詳細が表示されます。

最初の画像は、AI エンリッチメントの応用パターンを示しています。 スキルは順番実行することも、依存関係がなければ並列で実行することもできます。 出力フィールド マッピングでは、エンリッチされたコンテンツまたは生成されたコンテンツを、インメモリ データ構造からインデックス内のフィールドに送信します。

2 番目の画像は、垂直統合の典型的なパターンを示しています。 垂直統合のスキルには通常、テキスト分割と埋め込みスキルが含まれます。 テキスト分割スキルは、ドキュメントをページ単位のチャンクに分割します。 埋め込みスキルはベクター化を行います。 プロジェクション マッピングは、コンテンツのチャンクのインデックスがどのように作成されるかを制御します。 この特定のスキルセットは、親インデックスをスキップし、メタデータを使用してチャンクのソースを識別して、チャンクされたコンテンツのみのインデックスを作成します。

制限事項

デバッグ セッションは、一般提供されているすべてのインデクサー データ ソースとほとんどのプレビュー データ ソースで機能しますが、次の例外があります。

• SharePoint Online インデクサー。

• Azure Cosmos DB for MongoDB インデクサー。

• Azure Cosmos DB for NoSQL では、インデックス中に行が失敗し、対応するメタデータがない場合、デバッグ セッションで正しい行が選択されない可能性があります。

• Azure Cosmos DB の SQL API の場合、パーティション分割されたコレクションが以前にパーティション分割されていなかった場合、デバッグ セッションではドキュメントが見つかりません。

• カスタム スキルの場合、Azure Storage へのデバッグ セッション接続では、ユーザー割り当てマネージド ID はサポートされていません。 前提条件に記載されているように、システム マネージド ID を使用するか、キーを含むフル アクセス接続文字列を指定することができます。 詳細については、「マネージド ID を使用して他の Azure リソースに検索サービスを接続する」を参照してください。

• 現在、デバッグするドキュメントを選択する機能は使用できません。 この制限は永続的ではなく、間もなく解除される予定です。 現時点では、デバッグ セッションはソース データ コンテナーまたはフォルダー内の最初のドキュメントを選択します。

デバッグ セッションのしくみ

セッションを開始すると、検索サービスによって、スキルセット、インデクサー、データ ソース (スキルセットのテストに使われる 1 つのドキュメントを含む) のコピーが作成されます。 すべてのセッション状態は、指定した Azure Storage アカウントの Azure AI Search Service よって作成された新しい BLOB コンテナーに保存されます。 生成されたコンテナーの名前には、プレフィックス ms-az-cognitive-search-debugsession が付きます。 プレフィックスを使用すると、セッション データを誤ってアカウント内の別のコンテナーにエクスポートする可能性を軽減できるため、これを使用することは必須です。

エンリッチされたドキュメントとスキルセットのキャッシュ コピーがビジュアル エディターに読み込まれるので、エンリッチされたドキュメントの内容とメタデータを調べることができます。また、各ドキュメント ノードを確認し、スキルセット定義のあらゆる側面を編集する機能があります。 セッション内で加えられた変更はすべてキャッシュされます。 これらの変更は、コミットしない限り、公開済みのスキルセットには影響しません。 変更をコミットすると、運用スキルセットが上書きされます。

エンリッチメント パイプラインにエラーがない場合は、デバッグ セッションを使用してドキュメントを段階的にエンリッチし、変更をコミットする前に各変更をテストして確認することができます。

デバッグ セッション レイアウト

ビジュアル エディターは、ドキュメント解析から始まり、スキル、マッピング、インデックスというように、操作のプログレッションを示す表示領域として構成されます。

任意のスキルまたはマッピングを選択すると、関連する情報を表示するペインが横に表示されます。

スキル処理をさらに詳しく見るには、リンクをたどります。 たとえば、次のスクリーンショットは、テキスト分割スキルの最初のイテレーションの出力を示しています。

スキルの詳細ウィンドウ

[スキルの詳細] ペインには、次のセクションがあります。

• イテレーション: スキルの実行回数が表示されます。 それぞれの入力と出力を確認できます。
• スキル設定: JSON スキルセット定義を表示または編集します。
• エラーと警告: このスキルに固有のエラーまたは警告を表示します。

[エンリッチされたデータ構造] ペイン

青い矢印記号の表示/非表示を切り替えると、[エンリッチされたデータ構造] ペインが横にスライドして表示されます。 これは、エンリッチされたドキュメントに含まれる内容を人間が判読できる表現にしたものです。 この記事の前のスクリーンショットは、エンリッチされたデータ構造の例を示しています。

次のステップ

デバッグ セッションの要素を理解したので、既存のスキルセットで最初のデバッグ セッションを開始します。