Azure AI 検索 のデバッグ セッション

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

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

サポートされるシナリオ

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

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

• 組み込みのスキルは統合ベクトル化に使用され、テキスト分割によるデータのチャンク化と、埋め込みスキルを通じたベクトル化を行います。

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

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

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

2 番目の画像は、垂直統合の典型的なパターンを示しています。 垂直統合のスキルには通常、テキスト分割スキルと埋め込みスキルが含まれます。 テキスト分割スキルは、ドキュメントをチャンクに分割します。 埋め込みスキルは埋め込み API を呼び出して、それらのチャンクをベクター化します。 この特定のスキルセットは、コンテンツを "ページ" の配列にチャンク化します。 垂直統合の場合、プロジェクション マッピングは、チャンクをインデックス内のフィールドにマップする方法を制御します。

制限事項

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

• SharePoint インデクサー。

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

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

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

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

• カスタマー マネージド キー (CMK) を使用して暗号化が有効になっているデータ ソース。

• 共有プライベート リンクはサポートされていません。 検索サービスでプライベート エンドポイント接続を使用してデータ ソースまたはその他のリソースにアクセスする場合、デバッグ セッションはこれらのリソースにアクセスできません。 回避策については、「 デバッグ セッションとプライベート接続」を参照してください。

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

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

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

マネージド ID を使用してストレージ アカウント接続を構成する場合は、ストレージ アカウントの検索サービス ID にStorage Blob Data Contributorロールを割り当てます。 ストレージ アカウントで、信頼できるサービスを有効にして、Azure AI 検索からの書き込みアクセスを許可します。

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

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

デバッグ セッションは、データ、スキルの入力と出力、フィールド マッピングを分析することで、エラーまたは警告の根本原因を特定するのに役立ちます。 スキルの詳細ペインを使用して、各スキルが入力として受け取り、出力として生成するものを調べます。 この検査は、スキル定義、式、およびフィールド マッピングが正しく形成されていることを確認するのに役立ちます。 不正なネットワークセットアップやアクセス許可関連のアクセス エラーなど、インデクサーで構成の問題が発生した場合は、特定のエラー メッセージとリンクされたドキュメントを確認してください。 トラブルシューティングのガイダンスについては、「 インデクサーの一般的なエラーと警告」を参照してください。

デバッグ セッションとプライベート接続

デバッグ セッションでは、共有プライベート リンクはサポートされません。 運用検索サービスでプライベート エンドポイント接続を使用してデータ ソースやその他のリソースにアクセスする場合、そのサービスに対してデバッグ セッションを実行することはできません。

回避策: テスト検索サービスを使用する

スキルセットをデバッグするには、プライベート接続の制限なしで個別のAzure AI 検索 サービスを作成します。 運用データとスキーマの詳細をプライベート以外の環境から除外するには、合成ドキュメントを使用してテスト セットアップをビルドします。

• 実稼働データのフィールド型と構造に一致するテスト ドキュメントを作成しますが、実際のデータの代わりに汎用フィールド名 ( content、 title、 categoryなど) とプレースホルダー値を使用します。 スキルセット ロジックは、特定のフィールド名ではなく、コンテンツ タイプと構造に依存します。
• 運用サービスからスキルセット JSON をコピーします。 スキル入力が運用フィールド名を参照している場合は、それらの参照を一般的なテスト フィールド名と一致するように更新します。 テスト インデクサーの フィールド マッピング を使用して、テスト フィールド名をスキルセットの入力に合わせます。
• テスト データ ソースに対して実行するようにインデクサーを構成します。

テスト サービスでデバッグ セッションを実行して、スキルの入力と出力を検査し、スキルの式とフィールド マッピングを検証し、エラーを特定します。 変更が検証されたら、スキルセット JSON の元の運用フィールド名参照を復元し、運用サービスに適用し直します。

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

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

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

スキルの詳細ペインに情報のドリルダウン機能があることを示すスクリーンショット。

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

スキルの詳細ウィンドウ

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

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

拡張データ構造ウィンドウ

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

次のステップ

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