チュートリアル: デバッグ セッションを使用してスキルセットを修正する

  • [アーティクル]

Azure AI 検索のスキルセットを使用すると、検索可能なコンテンツを分析、変換、または作成するスキルのアクションを調整できます。 多くの場合、あるスキルの出力が別のスキルの入力になります。 入力が出力に依存している場合にスキルセットの定義およびフィールドの関連付けに誤りがあると、操作とデータが失われる可能性があります。

デバッグ セッションは、スキルセットの包括的な視覚化を提供する Azure portal ツールであり、Azure AI 検索で実行できます。 このツールを使用することで、特定の手順にドリルダウンし、アクションが失敗していると考えられる場所が簡単にわかります。

この記事では、デバッグ セッションを使って、不足している入力と出力を見つけて修正します。 必要なものはチュートリアルにすべて含まれています。 サンプル データ、オブジェクトを作成する REST ファイル、スキルセットの問題をデバッグするための手順が用意されています。

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

前提条件

  • Azure AI Search。 サービスを作成するか、現在のサブスクリプションから既存のサービスを検索します。 このチュートリアル用には、無料のサービスを使用できます。 Free レベルでは、Azure AI 検索サービスのマネージド ID サポートは提供されません。 Azure Storage への接続にはキーを使用する必要があります。

  • サンプル データのホスト、およびデバッグ セッション中に作成されるキャッシュ データの保持に使用する BLOB ストレージ付き Azure Storage アカウント。 無料の検索サービスを使用している場合は、ストレージ アカウントで共有アクセス キーを有効にし、公衆ネットワーク アクセスを許可している必要があります。

  • REST クライアントを使用する Visual Studio Code。

  • サンプル PDF (臨床試験)。

  • エンリッチメント パイプラインの作成に使用されるサンプル debug-sessions.rest ファイル。

Note

また、このチュートリアルでは、言語検出、エンティティ認識、キー フレーズ抽出に Azure Cognitive Services も使います。 ワークロードは非常に小さいので、最大 20 トランザクションの処理を無料で使用するために Azure AI サービスを内部で利用しています。 つまり、課金対象の Azure AI サービスリソースを作成しなくても、この演習を完了できるということです。

サンプル データを設定する

このセクションでは、Azure Blob Storage にサンプル データ セットを作成し、インデクサーとスキルセットに作業用コンテンツを用意します。

  1. 19 個のファイルから成るサンプル データ (clinical-trials-pdf-19) をダウンロードしてください。

  2. Azure Storage アカウントを作成するか、既存のアカウントを検索してください。

    • 帯域幅の料金を避けるため、リージョンは、Azure AI Search と同じものを選択してください。

    • [StorageV2 (汎用 v2)] のアカウントの種類を選択します。

  3. ポータルの Azure Storage サービス ページに移動して、BLOB コンテナーを作成します。 アクセス レベルとして "プライベート" を指定することをお勧めします。 コンテナーの名前は clinicaltrialdataset にします。

  4. コンテナーの [アップロード] を選択して、最初の手順でダウンロードして解凍したサンプル ファイルをアップロードします。

  5. ポータルで、Azure Storage の接続文字列をコピーします。 接続文字列は、ポータルの [設定]>[アクセス キー] から取得できます。

キーと URL をコピーする

このチュートリアルでは、認証と認可に API キーを使用します。 検索サービス エンドポイントと API キーが必要です。これらは Azure portal から取得できます。

  1. Azure portal にサインインし、[概要] ページに移動して URL をコピーします。 たとえば、エンドポイントは https://mydemo.search.windows.net のようになります。

  2. [設定]>[キー] で管理者キーをコピーします。 管理者キーは、オブジェクトの追加、変更、削除で使用します。 2 つの交換可能な管理者キーがあります。 どちらかをコピーします。

    Azure portal の URL キーと API キーのスクリーンショット。

有効な API キーにより、要求を送信するアプリケーションとそれを処理する検索サービスとの間で、要求ごとに信頼が確立されます。

データ ソース、スキルセット、インデックス、およびインデクサーを作成する

このセクションでは、このチュートリアルで修正できる "バグのある" ワークフローを作成します。

  1. Visual Studio Code を起動し、debug-sessions.rest ファイルを開きます。

  2. 次の変数を指定します。検索サービス URL、検索サービス管理 API キー、ストレージ接続文字列、PDF を格納する BLOB コンテナーの名前。

  3. 各要求を順番に送信します。 インデクサーの作成が完了するまでに数分かかります。

  4. ファイルを閉じます。

ポータルで結果を確認する

このサンプル コードでは意図的に、スキルセットの実行中に発生した問題の結果としてバグのあるインデックスが作成されます。 問題は、インデックスのデータの欠落することです。

  1. Azure portal の検索サービスの [概要] ページで、[インデックス] タブを選択します。

  2. clinical-trials を選びます。

  3. 検索エクスプローラーの JSON ビューに、この JSON クエリ文字列を入力します。 特定のドキュメントのフィールドを返します (一意の metadata_storage_path フィールドで識別されます)。

    "search": "*",
"select": "metadata_storage_path, organizations, locations",
"count": true

  4. クエリを実行します。 organizations と locationsの空の値が表示されます。

    これらのフィールドには、(BLOB のコンテンツ内のあらゆる組織と場所を検出するために使用される) スキルセットのエンティティ認識スキルを通じて値が設定されているはずでした。 次の演習では、スキルセットをデバッグして問題の原因を特定します。

エラーと警告を調査する別の方法は、Azure portal を使用することです。

  1. [インデクサー] タブを開き、clinical-trials-idxr を選びます。

    全体としてはインデクサー ジョブが成功したものの、警告が発生したことに注目してください。

  2. [成功] を選んで警告を表示します (大部分がエラーの場合、詳細リンクは [失敗] になります)。 インデックスによって出力されたすべての警告が記載された長いリストが表示されます。

    警告の表示のスクリーンショット。

デバッグ セッションを開始する

  1. 検索サービスの左側のナビゲーション ウィンドウの [検索管理] で、[セッションのデバッグ] を選択します。

  2. + デバッグ セッションの追加 を選択します。

  3. セッションに名前を指定します。

  4. インデクサー テンプレートで、インデクサー名を指定します。 インデクサーには、データ ソース、スキルセット、およびインデックスへの参照があります。

  5. ストレージ アカウントを選択します。

  6. セッションを保存します。

    [デバッグ セッションの定義] ページのスクリーンショット。

  7. デバッグ セッションが開き、設定ページが表示されます。 初期構成を変更し、既定値をオーバーライドすることができます。 デバッグ セッションは、1 つのドキュメントでのみ機能します。 既定では、コレクション内の最初のドキュメントをデバッグ セッションのベースとして受け入れます。 Azure Storage 内の URI を指定することで、デバッグ対象の特定のドキュメントを選択できます。

  8. デバッグ セッションの初期化が完了すると、マッピングと検索インデックスを含むスキル ワークフローが表示されます。 エンリッチされたドキュメント データ構造が横の詳細ウィンドウに表示されます。 ワークフローの詳細を確認できるように、次のスクリーンショットからは除外しました。

    デバッグ セッション ビジュアル エディターのスクリーンショット。

スキルセットに関する問題を検出する

インデクサーによって報告された問題がある場合は、"エラー" や "警告" と表示されます。

エラーと警告の数は先ほど表示された一覧よりも少ないことに注意してください。この一覧には、1 つのドキュメントのエラーの詳細のみが表示されるためです。 インデクサーによって表示される一覧と同様に、警告メッセージを選択して、その警告の詳細を確認できます。

[警告] を選択して通知を確認します。 次の 4 つが表示されます。

  • 「1 つ以上のスキルの入力が無効だったため、スキルを実行できませんでした。 Required skill input is missing. (必須のスキルの入力がありません。) 名前: 'text'、ソース: '/document/content'。"

  • "出力フィールド "locations" を検索インデックスにマップできませんでした。 インデクサーの "outputFieldMappings" プロパティを確認してください。 "/document/merged_content/locations" の値がありません。"

  • "出力フィールド "organizations" を検索インデックスにマップできませんでした。 インデクサーの "outputFieldMappings" プロパティを確認してください。 "/document/merged_content/organizations" の値がありません。"

  • 「スキルは実行されましたが、1 つ以上のスキルの入力が無効だったため、予期しない結果が生じる可能性があります。 省略可能なスキルの入力がありません。 名前: "languageCode"、ソース: "/document/languageCode"。 式言語が問題を解析中:"/document/languageCode" の値がありません。"

多くのスキルには "languageCode" パラメーターがあります。 操作を検査することで、EntityRecognitionSkill.#1 からこの言語コード入力が不足していることがわかります。これは、"locations" と "organizations" の出力に問題を抱える同じエンティティ認識スキルです。

4 つの通知はすべてこのスキルに関するものなので、次のステップでは、このスキルをデバッグします。 可能であれば、先に入力の問題を解決してから、出力の問題に進んでください。

不足しているスキル入力値を修正する

  1. 作業画面で、警告を報告しているスキルを選択します。 このチュートリアルでは、エンティティ認識スキルです。

  2. [スキルの詳細] ペインが右側に開き、イテレーションとそれぞれの入力と出力、スキルの JSON 定義のスキル設定、このスキルから出力されているエラーと警告のメッセージのセクションが表示されます。

    [スキルの詳細] ペインのスクリーンショット。

  3. 各入力にマウス ポインターを合わせると (または入力を選択すると)、式エバリュエーターに値が表示されます。 この入力に表示される結果は、テキスト入力のようには見えないことに注意してください。 テキストではなく、一連の改行文字 \n \n\n\n\n のように見えます。 テキストがないということは、エンティティが特定できないことを意味するので、このドキュメントはスキルの前提条件を満たしていないか、代わりに使う必要がある別の入力があります。

    null 値を示すスキル入力のスクリーンショット。

  4. [エンリッチされたデータ構造] に戻り、このドキュメントのエンリッチ ノードを確認します。 "content" の \n \n\n\n\n には送信元がありませんが、"merged_content" の別の値には OCR 出力があることに注目してください。 表示はありませんが、抽出され、処理されたテキストが "merged_content" にはあることから、この PDF のコンテンツは JPEG ファイルであると思われます。

    エンリッチ処理されたデータ構造のスクリーンショット。

  5. スキルに戻り、[スキルセットの設定] を選択して JSON 定義を開きます。

  6. 式を /document/content から /document/merged_content に変更し、[保存] を選択します。 警告が一覧に表示されなくなったことに注目してください。

    固定の merged_content 入力の式エバリュエーターのスクリーンショット。

  7. セッションのウィンドウ メニューで [実行] を選びます。 これにより、ドキュメントを使用してスキルセットの別の実行が開始されます。

  8. デバッグ セッションの実行が完了すると、警告数が 1 つ減っていることがわかります。 警告を見ると、テキスト入力のエラーはなくなりましたが、他の警告は残っています。 次の手順は、不足値または空の値 /document/languageCode に関する警告に対処することです。

    更新されたエラーと警告のスクリーンショット。

  9. スキルを選択し、/document/languageCode にマウス ポインターを合わせます。 この入力の値は null であり、有効な入力ではありません。

  10. 前の問題と同様に、まず、[エンリッチされたデータ構造] を確認して、そのノードの証拠を確認します。 "languageCode" ノードはありませんが、"language" にはあることに注目してください。 つまり、スキルの設定に入力ミスがあります。

  11. 式 /document/language をコピーします。

  12. [スキルの詳細] ペインで、1 つ目のスキルの [スキルの設定] を選択し、新しい値 /document/language を貼り付けます。

  13. [保存] を選択します。

  14. [実行] を選択します。

  15. デバッグ セッションの実行が完了したら、[スキルの詳細] ペインで結果を確認できます。 /document/language にマウス カーソルを合わせると、式エバリュエーターの値として en が表示されます。

入力の警告がなくなったことに注目してください。 ここでは、組織と場所の出力フィールドに関する 2 つの警告のみが残っています。

不足しているスキル出力値を修正する

メッセージには、インデクサーの 'outputFieldMappings' プロパティを確認するように指示されているので、そこから始めましょう。

  1. 作業画面で [出力フィールドのマッピング] を選択します。 [出力フィールドのマッピング] が欠落していることに注目してください。

    出力フィールド マッピングのスクリーンショット。

  2. 最初の手順として、想定するフィールドが検索インデックスにあることを確認します。 この場合、インデックスには "locations" と "organizations" のフィールドがあります。

  3. インデックスに問題がなければ、次の手順はスキルの出力を確認することです。 先ほどと同様に、[エンリッチされたデータ構造] を選択し、ノードをスクロールして "location" と "organization" を見つけます。 親が "merged_content" ではなく "content" であることに注意してください。 コンテキストが正しくありません。

  4. エンティティ認識スキルの [スキルの詳細] ペインに戻ります。

  5. [スキルの設定] で context を document/merged_content に変更します。 この時点で、スキル定義には合計 3 つの変更が加えられているはずです。

    すべての変更が示されたスキル定義のスクリーンショット。

  6. [保存] を選択します。

  7. [実行] を選択します。

すべてのエラーが解決されました。

スキルセットに変更をコミットする

デバッグ セッションが開始されたとき、検索サービスによってスキルセットのコピーが作成されました。 これは、自分の検索サービスで元のスキルセットを保護するために行われました。 スキルセットのデバッグが完了したので、修正をコミット (元のスキルセットを上書き) できるようになりました。

または、変更をコミットする準備ができていない場合は、デバッグ セッションを保存し、後でそれを開き直すことができます。

  1. メイン デバッグ セッション メニューの [Commit changes](変更のコミット) を選びます。

  2. [OK] を選んで、スキルセットの更新に同意します。

  3. デバッグ セッションを閉じ、左側のナビゲーション ウィンドウから [インデクサー] を開きます。

  4. 'clinical-trials-idxr' を選択します。

  5. [リセット] を選択します。

  6. [実行] を選択します。

  7. [更新] を選択して、リセットコマンドと実行コマンドの状態を表示します。

インデクサーの実行が完了すると、 [実行履歴] タブに緑色のチェックマークが表示され、最新の実行のタイム スタンプの横に "成功" という単語が表示されるはずです。変更が適用されたことを確認するには、次のようにします。

  1. 左側のナビゲーション ウィンドウで、[インデックス] を開きます。

  2. 'clinical-trials' インデックスを開き、[検索エクスプローラー] タブで、(一意の metadata_storage_path フィールドで識別される) 特定のドキュメントのフィールドを返すクエリ文字列: $select=metadata_storage_path, organizations, locations&$count=true を入力します。

  3. [Search] を選択します。

結果として、組織と場所に想定される値が設定されるようになったことがわかるはずです。

リソースをクリーンアップする

独自のサブスクリプションを使用している場合は、プロジェクトの最後に、作成したリソースがまだ必要かどうかを確認してください。 リソースを実行したままにすると、お金がかかる場合があります。 リソースは個別に削除することも、リソース グループを削除してリソースのセット全体を削除することもできます。

ポータルの左側のナビゲーション ウィンドウにある [All resources](すべてのリソース) または [Resource groups](リソース グループ) リンクを使って、リソースを検索および管理できます。

無料サービスでは、3 つのインデックス、インデクサー、データ ソースに制限されます。 ポータルで個別の項目を削除して、制限を超えないようにすることができます。

次のステップ

このチュートリアルでは、スキルセットの定義および処理のさまざまな側面について紹介しました。 概念とワークフローの詳細については、次の記事を参照してください。