Azure portal で Azure AI Search スキルセットをデバッグする

ポータル ベースのデバッグ セッションを開始して、エラーの特定と解決、変更の検証を行い、Azure AI Search サービスの公開済みスキルセットに変更をプッシュします。

デバッグ セッションは、キャッシュされたインデクサーとスキルセットの実行であり、スコープは 1 つのドキュメントです。これを使用して、変更を対話形式で編集してテストできます。 デバッグが完了したら、スキルセットへの変更を保存できます。

デバッグ セッションのしくみの背景情報については、「Azure AI Search のデバッグ セッション」を参照してください。 サンプル ドキュメントを使ってデバッグ ワークフローを練習するには、「チュートリアル: デバッグ セッションを使用してスキルセットをデバッグする」を参照してください。

前提条件

• データ ソース、スキルセット、インデクサー、インデックスを含む、既存のエンリッチメント パイプライン。

• 検索サービスでの 共同作成者 ロールの割り当て。

• セッション状態の保存に使われる Azure Storage アカウント。

• Azure Storage でのストレージ BLOB データ共同作成者ロールの割り当て (システム マネージド ID を使用する場合)。 それ以外の場合は、Azure Storage へのデバッグ セッション接続にフル アクセス接続文字列を使用することを計画します。

• Azure Storage アカウントがファイアウォールの内側にある場合は、検索サービスのアクセスを許可するようにそれを構成します。

制限事項

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

• Azure Cosmos DB for MongoDB は現在サポートされていません。

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

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

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

ポータルではカスタマー マネージド キー暗号化 (CMK) がサポートされていません。つまり、デバッグ セッションなどのポータル エクスペリエンスには、CMK で暗号化された接続文字列やその他の暗号化されたメタデータを含めることはできません。 検索サービスが CMK 強制用に構成されている場合、デバッグ セッションは機能しません。

デバッグ セッションを作成する

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

2. 左側のナビゲーション ウィンドウで、[デバッグ セッション] を選択します。

3. 上部のアクション バーで、[デバッグ セッションを追加] を選択します。

   

4. [デバッグセッション名] に、デバッグセッションに関連するスキルセット、インデクサー、およびデータソースを思い出すのに役立つ名前を入力します。

5. [ストレージ接続] で、デバッグセッションをキャッシュするための汎用ストレージアカウントを見つけます。 Blob Storage または Azure Data Lake Storage Gen2 の blob コンテナーを選択し、必要に応じて作成するよう求められます。 同じコンテナーを、それ以降に作成するすべてのデバッグ セッションで再利用できます。 "cognitive-search-debug-sessions" などは、コンテナー名として役立ちます。

6. マネージド ID 認証で、Azure Storage への接続でマネージド ID を使用しない場合は、[なし] を選択します。 それ以外の場合は、ストレージ BLOB データ共同作成者アクセス許可を付与したマネージド ID 選択します。

7. [Indexer template](インデクサー テンプレート) で、デバッグするスキルセットを駆動するインデクサーを選択します。 セッションを開始するために、インデクサーとスキルセットの両方のコピーが使われます。

8. [Document to debug](デバッグするドキュメント) で、インデックスの最初のドキュメントを選択するか、特定のドキュメントを選択します。 データ ソースに応じて特定のドキュメントを選択すると、URI または行 ID を指定するように求められます。

   特定のドキュメントが BLOB の場合は、BLOB URI を指定します。 URI は、ポータルの BLOB プロパティ ページで見つけることができます。

   

9. 必要に応じて、[インデクサーの設定] で、セッションの作成に使用されるインデクサーの実行設定を指定します。 この設定は、実際のインデクサーで使用される設定を模倣する必要があります。 デバッグ セッションでインデクサー オプションを指定した場合でも、インデクサー自体には影響しません。

10. 構成は、次のスクリーンショットのようになります。 まず [セッションの保存] を選びます。

    

デバッグ セッションは、選んだドキュメントに対してインデクサーとスキルセットを実行することから始まります。 作成されたドキュメントのコンテンツとメタデータは、そのセッション内で表示、使用できるようになります。

デバッグ セッションは、実行中に [キャンセル] ボタンを使用して取り消すことができます。 [キャンセル] ボタンをクリックすると、結果の一部を分析できるようになります。

デバッグ セッションは、追加の処理を通過するため、インデクサーよりも実行に時間がかかることが予想されます。

エラーと警告から始める

ポータルのインデクサーの実行履歴では、すべてのドキュメントに関するすべてのエラーと警告の一覧を確認できます。 デバッグ セッションでは、エラーと警告は 1 つのドキュメントに限定されます。 この一覧を見て対応し、変更を加え、一覧に戻って問題が解決したかどうかを確認します。

メッセージを表示するには、[AI エンリッチメント] > [Skill Graph]\(スキル グラフ\) でスキルを選び、詳細ウィンドウで [エラー/警告] を選びます。

ベスト プラクティスとして、出力に移る前に入力に関する問題を解決してください。

変更によってエラーが解決したかどうかを確認するには、次の手順を実行します。

1. [スキルの詳細] ウィンドウの [保存] を選び、変更内容を保存します。

2. セッション ウィンドウで [実行] を選び、変更した定義を使ってスキルセットの実行を呼び出します。

3. [エラー/警告] に戻り、数が減ったかどうかを確認します。 タブを開くまで、リストは更新されません。

エンリッチメント ノードのコンテンツを確認する

AI エンリッチメント パイプラインを使うと、ソース ドキュメントから情報と構造を抽出または推論し、そのプロセスでエンリッチ ド ドキュメントを作成することができます。 エンリッチされたドキュメントは、まずドキュメント解析時に作成され、ルート ノード (/document) に加えて、メタデータやドキュメント キーから直接解除されたデータ ソースなどのコンテンツのノードが設定されます。 その他のノードはスキルの実行時にスキルによって作成され、スキルの出力ごとにエンリッチメント ツリーに新しいノードが追加されます。

エンリッチされたドキュメントは内部のものですが、スキルの実行時に生成されたコンテンツには、デバッグ セッションからアクセスできます。 各スキルのコンテンツまたは出力を確認するには、次の手順を実行します。

1. 既定のビュー ([AI エンリッチメント] > [Skill Graph]\(スキル グラフ\)) から始めます。グラフの種類は [依存関係グラフ] に設定します。

2. スキルを選びます。

3. 右側の詳細ウィンドウで [実行] を選び、[出力] を選び、[式エバリュエーター] (</>) を開いて式とその結果を確認します。

   

4. または、[AI Enrichments] (AI エンリッチメント) > [Enriched Data Structure] (エンリッチ処理されたデータ構造) を開き、ノードの一覧を下にスクロールします。 一覧には、潜在的なノードと実際のノードが含まれています。また、出力の列と、出力の生成に使われたアップストリーム オブジェクトを示す別の列があります。

   

スキル定義を編集する

フィールドのマッピングが正しい場合は、個々のスキルの構成とコンテンツを確認します。 スキルによる出力の生成に失敗する場合は、プロパティまたはパラメーターが不足している可能性があります。これは、エラーと検証メッセージで判断できます。

コンテキストや入力式が無効な場合など、他の問題は解決が難しいことがあります。エラーによって何が問題かはわかりますが、修正方法はわからないからです。 コンテキストと入力構文については、Azure AI Search スキルセットでのエンリッチメントの参照に関する記事を参照してください。 個々のメッセージについては、インデクサーの一般的なエラーと警告のトラブルシューティングに関するページを参照してください。

スキルに関する情報を取得するには、次の手順を実行します。

1. [AI エンリッチメント] > [Skill Graph]\(スキル グラフ\) でスキルを選びます。 右側に [Skill Details]\(スキルの詳細\) ペインが開きます。

2. いずれかの方法を使ってスキル定義を編集します。

   • ビジュアル エディターを使う場合は [Skill Settings]\(スキルの設定\)
   • JSON ドキュメントを直接編集する場合は [Skill JSON Editor]\(スキル JSON エディター\)

3. エンリッチメント ツリーのノードを参照するためのパス構文を確認します。 最も一般的な入力パスの一部を次に示します。

   • テキストのチャンクの場合は /document/content。 このノードは、BLOB のコンテンツ プロパティから設定されます。
   • テキスト マージ スキルを含むスキルセット内のテキストのチャンクの場合は /document/merged_content。
   • 画像から認識または推論されたテキストの場合は /document/normalized_images/*。

フィールドのマッピングを確認する

スキルが出力を生成しても、検索インデックスが空の場合は、フィールドマッピングを確認します。 フィールドマッピングは、パイプラインから検索インデックスにコンテンツを移動する方法を指定します。

1. 既定のビュー ([AI エンリッチメント] > [Skill Graph]\(スキル グラフ\)) から始めます。グラフの種類は [依存関係グラフ] に設定します。

2. 上部にある [フィールドのマッピング] を選びます。 少なくともドキュメント キーが表示されます。これは、検索インデックス内の各検索ドキュメントを一意に識別し、データ ソース内のソース ドキュメントと関連付けるものです。

   エンリッチメントをバイパスしてデータ ソースから生のコンテンツを直接インポートしている場合は、[フィールドのマッピング] にそれらのフィールドが表示されます。

3. グラフの下部にある [出力フィールドのマッピング] を選びます。 ここには、スキルの出力から検索インデックス内の対象フィールドへのマッピングが表示されます。 [データのインポート] ウィザードを使っていない場合、出力フィールドのマッピングは手動で定義されるため、不完全な場合や誤入力が生じる場合があります。

   [出力フィールドのマッピング] のフィールドが指定したとおりに検索インデックスに存在することを確認し、スペルとエンリッチメント ノード パスの構文を確認します。

   

カスタム スキルをローカルでデバッグする

カスタム スキルは、コードが外部で実行されるため、デバッグ セッションを使用してデバッグできません。このため、カスタム スキルは、デバッグが難しい場合があります。 このセクションでは、カスタム Web API スキルをローカルでデバッグする方法、デバッグ セッション、Visual Studio Code と ngrok または Tunnelmole について説明します。 この手法は、Azure Functions で実行されるカスタム スキルや、ローカルで実行される他の Web フレームワーク (FastAPI など) で動作します。

パブリック URL の取得

Tunnelmole を使用する

Tunnelmole は、トンネルを介してローカル コンピューターに要求を転送するパブリック URL を作成できるオープン ソースのトンネリング ツールです。

1. Tunnelmole をインストールします。

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: npm を使用してインストールします。 または、NodeJS がインストールされていない場合は、Windows 用プリコンパイル済み.exe ファイルをダウンロードし、PATH 内のどこかに配置します。

2. 次のコマンドを実行して、新しいトンネルを作成します。

   tmole 7071
   

   応答は次のようになります。

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   前の例では、https://m5hdpb-ip-49-183-170-144.tunnelmole.net はローカル コンピューター上のポート 7071 に転送されます。これは、Azure 関数が公開されている既定のポートです。

ngrok を使用する

ngrok は、トンネリングまたは転送 URL を作成できる一般的なクローズド ソースのクロスプラットフォーム アプリケーションであり、インターネット要求をローカル コンピューターに到達できるようにします。 ngrok を使用して、検索サービスのエンリッチメント パイプラインからの要求をご自分のコンピューターに転送し、ローカル デバッグを許可します。

1. ngrok をインストールします。

2. ターミナルを開き、ngrok 実行可能ファイルを含むフォルダーに移動します。

3. 次のコマンドを使用して ngrok を実行して、新しいトンネルを作成します。

   ngrok http 7071 
   

   Note

   既定では、Azure 関数は 7071 で公開されます。 その他のツールや構成では、別のポートを指定する必要がある場合があります。

4. ngrok が起動したら、次の手順のためにパブリック転送 URL をコピーして保存します。 転送 URL はランダムに生成されます。

   

Azure Portal での構成

デバッグ セッション内で、カスタム Web API スキル URI を変更して、Tunnelmole または ngrok 転送 URL を呼び出します。 Azure Function を使用してスキルセット コードを実行する場合は、"/api/FunctionName" を確実に追加してください。

ポータルでスキル定義を編集できます。

コードのテスト

この時点で、デバッグ セッションからの新しい要求は、ローカルの Azure 関数に送信されるようになります。 Visual Studio Code のブレークポイントを使用して、コードをデバッグしたり、ステップバイステップで実行したりすることができます。

次のステップ

デバッグ セッション ビジュアル エディターのレイアウトと機能を理解したら、次はチュートリアルで実践してみましょう。