デバッグ セッションは、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 Storage アカウントの Azure AI Search Service よって作成された新しい BLOB コンテナーに保存されます。 生成されたコンテナーの名前には、プレフィックス ms-az-cognitive-search-debugsession が付きます。 プレフィックスを使用すると、セッション データを誤ってアカウント内の別のコンテナーにエクスポートする可能性を軽減できるため、これを使用することは必須です。
エンリッチされたドキュメントとスキルセットのキャッシュ コピーがビジュアル エディターに読み込まれるので、エンリッチされたドキュメントの内容とメタデータを調べることができます。また、各ドキュメント ノードを確認し、スキルセット定義のあらゆる側面を編集する機能があります。 セッション内で加えられた変更はすべてキャッシュされます。 これらの変更は、コミットしない限り、公開済みのスキルセットには影響しません。 変更をコミットすると、運用スキルセットが上書きされます。
エンリッチメント パイプラインにエラーがない場合は、デバッグ セッションを使用してドキュメントを段階的にエンリッチし、変更をコミットする前に各変更をテストして確認することができます。
デバッグ セッションは、データ、スキルの入力と出力、フィールド マッピングを分析することで、エラーまたは警告の根本原因を特定するのに役立ちます。 インデクサーで正しくないネットワークセットアップ、アクセス許可関連のアクセス エラーなどの構成の問題が発生した場合は、特定のエラー メッセージと、提供されているリンクされたドキュメントを確認してください。 トラブルシューティングのガイダンスについては、 インデクサーの一般的なエラーと警告を参照してください。
プライベート接続を使用してセッションをデバッグする
AI エンリッチメント パイプラインで共有プライベート リンクを使用して Azure リソースにアクセスする場合は、インデクサーセッションとデバッグ セッションが正しく動作するように追加の構成が必要です。 これには、アクセス許可、信頼されたアクセス、ネットワークのセットアップが含まれます。
-
マネージド ID を使用している場合は、
Storage Blob Data Contributorを含む検索サービス ID に必要なロールを割り当てて、デバッグ セッションがストレージ アカウントにセッション データを書き込むことができるようにします。 - 検索サービスが、デバッグ セッションで使用されるすべてのリソースを含め、 スキルセット定義で参照されているすべてのリソースにアクセスできることを確認します。
- ストレージ アカウントで、 信頼されたサービスを有効 にして、Azure AI Search からのアクセスを許可します。
- インデクサー定義
"executionEnvironment" = "private"プロパティを設定して、 インデクサーがプライベート コンテキストで実行されるようにします。 - 検索サービスによってアクセスされる各リソース (データ ソース、インデクサー AI エンリッチメント キャッシュとナレッジ ストアに構成されている場合)、スキルセットで構成されているその他のリソースなど、 共有プライベート リンク を作成します。
- その他のトラブルシューティング ガイダンスについては、 インデクサーの一般的なエラーと警告を参照してください。
デバッグ セッション レイアウト
ビジュアル エディターは、ドキュメント解析から始まり、スキル、マッピング、インデックスというように、操作のプログレッションを示す表示領域として構成されます。
任意のスキルまたはマッピングを選択すると、関連する情報を表示するペインが横に表示されます。
スキル処理をさらに詳しく見るには、リンクをたどります。 たとえば、次のスクリーンショットは、テキスト分割スキルの最初のイテレーションの出力を示しています。
スキルの詳細ウィンドウ
[スキルの詳細] ペインには、次のセクションがあります。
- イテレーション: スキルの実行回数が表示されます。 それぞれの入力と出力を確認できます。
- スキル設定: JSON スキルセット定義を表示または編集します。
- エラーと警告: このスキルに固有のエラーまたは警告を表示します。
[エンリッチされたデータ構造] ペイン
青い矢印記号の表示/非表示を切り替えると、[エンリッチされたデータ構造] ペインが横にスライドして表示されます。 これは、エンリッチされたドキュメントに含まれる内容を人間が判読できる表現にしたものです。 この記事の前のスクリーンショットは、エンリッチされたデータ構造の例を示しています。
次のステップ
デバッグ セッションの要素を理解したので、既存のスキルセットで最初のデバッグ セッションを開始します。