tao-analyze-gaps-visual-changenet

TAO VCN Classify ギャップ分析スキル

NVIDIA TAO VCN Classify（Visual Component Net）の推論結果を分析します。目的は、判定しきい値から誤った方向への符号付き距離を測定し、正解ラベルごとに最も弱いサンプルを特定して、後続のデータ拡張や再ラベル付けに活用できるようにすることです。

このスキルは意図的に軽量化されています。VCN の分類ヘッドは、siamese_score による PASS 対 NO_PASS の単一スコアの二値境界であるため、分析は調査ではなく計算中心です。処理全体は、versions.yaml で宣言された tao_toolkit.data_services イメージに対する単一の直接的な docker run 呼び出しで実行します（実行時に解決されます。Setup を参照）。コンテナのエントリーポイントは <category> <action> [hydra overrides...] を受け取るため、gap_analysis vcn_aoi key=value … を渡します。サブエージェントや複数フェーズの画像監査、コンポーネントタイプのクラスタリングは不要です。VCN ではこれらの属性は公開されていません。コンテナの実行後、ギャップを評価するために、代表的な弱いサンプルを少数だけ確認してください。

CLI の仕様は、データサービスコンテナのビルドによって変わる場合があります。gap_analysis vcn_aoi の呼び出しで引数解析に失敗した場合は、docker run --rm "$DS_IMAGE" gap_analysis vcn_aoi --cfg=job を使って、各イメージにつき一度だけ実際のスキーマを調べてから、名前が変更されたキーを修正して再試行してください。キー名変更の照合方法と、落とし穴の完全な一覧については、references/troubleshooting.md を参照してください。出力 parquet ファイル名は kpi_gaps.parquet です。

---

入力

1. 実験結果ディレクトリ — inference/inference.csv（必須列：input_path、object_name、label、siamese_score）を含みます。CSV ファイルではなく、ディレクトリ（例：inference/latest/）を渡してください。
2. 学習コード／設定ディレクトリ — VCN の学習 YAML を含みます。コンテナは、ライティングごとの展開に dataset.classify.input_map と dataset.classify.image_ext を読み取ります。
3. データセットディレクトリ — 各行の相対 input_path の先頭に付加する画像ルート（kpi_media_path）です。
4. スキーマのオーバーライド — min_recall、top_k_per_label、および任意の固定 threshold を Hydra オーバーライドとして渡します（デフォルト：min_recall=1.0、top_k_per_label=50、threshold=-1.0 はスイープを意味します）。top_k_per_label は正の整数でなければなりません。省略すると、コンテナは「しきい値未満のフィルター」モードに切り替わります。このモードでは、min_recall=1.0 のとき PASS の誤分類のみが返され、NO_PASS の行は返されません。

入力の詳細、GapAnalysisConfig のオーバーライドの意味、および各デフォルトの説明については、references/parameters-and-artifacts.md を参照してください。

---

セットアップ

閾値のスイープ、弱点の順位付け、照明条件ごとの展開はすべて、versions.yaml で指定されている tao_toolkit.data_services イメージ内で実行されます。実行の冒頭で具体的な URI を一度解決し、Docker、NVIDIA Container Toolkit、GPU が利用可能であることを確認して、イメージがキャッシュされていることを確認します。

# Resolve tao_toolkit.data_services → concrete nvcr.io/... URI from versions.yaml
DS_IMAGE=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['images']['tao_toolkit']['data_services'])")
echo "DS_IMAGE=$DS_IMAGE"

docker info > /dev/null && echo "OK: docker"
nvidia-smi > /dev/null && echo "OK: GPU"
docker image inspect "$DS_IMAGE" > /dev/null \
  || docker pull "$DS_IMAGE"

TAO_SKILL_BANK_PATH はプラグインの session_start フックによってエクスポートされます。未設定の場合（たとえば Claude Code プラグインの外部で実行する場合）は、解決の前にスキルバンクのリポジトリルートを指定してください。

GPU が必要です（AOI ループ全体で同じイメージが使われ、ほかの処理でも CUDA が存在することを前提としているためです）。GPU のないホストで早めに中断すれば、後から分かりにくいエラーが発生するのを防げます。

パスのマウント。 コンテナが読み書きするすべてのホストパス（inference.csv、train YAML、データセットの画像ルート、出力ディレクトリ）は、バインドマウントする必要があります。最も簡単な方法は、ワークスペースのルートをコンテナの内外で同じパスにマウントすることです。これにより、引数内の絶対パスを両方の環境で同じように解決できます。

WORKSPACE=<absolute path that contains inference.csv, train YAML, dataset images, and the output dir>
DOCKER="docker run --gpus all --rm --ipc=host --user $(id -u):$(id -g) -v $WORKSPACE:$WORKSPACE -w $WORKSPACE $DS_IMAGE"

inference.csv、train YAML、データセットの画像がそれぞれ異なるルートにある場合は、複数の -v フラグを渡してください。ただし、引数に渡すすべての絶対パスがコンテナ内で解決できる必要があります。

CLI オーバーライドで一般的なケースに対応できます。 min_recall、top_k_per_label、および任意の threshold は、コマンドラインで Hydra オーバーライドとして渡します。コンテナに組み込まれているデフォルト値（min_recall=1.0、top_k_per_label=50、スイープする場合は threshold=-1.0）で、ほとんどの実行に対応できます。コンテナが -e <spec> で spec ファイルも受け付ける場合（--cfg=job で確認してください）、指定するのは便利ですが必須ではありません。必要な項目だけをオーバーライドしてください。

---

手順

このスキル全体は、単一の docker run 呼び出しと、それに続く簡単な目視確認で構成されます。コンテナ内でステップ 1〜4（閾値のスイープ、弱点のスコアリング、トップ K の選択、照明条件ごとの展開）が実行されます。ステップ 5（目視確認）は、Read ツールを使って直接実行します。

ステップ 1–4 — コンテナを実行する

$DOCKER gap_analysis vcn_aoi \
    inference_results_dir=<exp_dir>/inference/<label>/ \
    train_config=<exp_dir>/train.yaml \
    kpi_media_path=<dataset_root> \
    results_dir=<rca_results_dir> \
    top_k_per_label=50

必ず top_k_per_label を指定してください。 これは、コンテナのフィルターをデフォルトの「しきい値未満のサンプル」から、適切なラベルごとのトップ K ランキングに切り替える引数です。min_recall=1.0 の場合、しきい値は構造上すべての NO_PASS スコア以下になるため、しきい値未満のフィルターでは、誤分類された PASS の行だけが返され、NO_PASS の行は 1 行も返されません。これではデータ拡張用のキューとして役に立ちません。top_k_per_label に正の整数を設定すると（仕様ファイルまたは Hydra オーバーライドで設定できます）、コンテナは各行についてしきい値に対する符号付き弱さを計算し、正解ラベルごとに弱さが最も大きい K 件を表示します。後続のステップでは、このラベルごとのランキング出力を使用します。

コンテナは、すべての一意な siamese_score（および最小値よりわずかに小さい値を 1 つ）を走査し、NO_PASS の再現率が min_recall 以上（許容誤差 1e-12）となる候補を残します。その中から F1 が最も高いしきい値を選びます（同点の場合は、適合率、次にしきい値の値で決定します）。各行の符号付き弱さをスコア化し、正解ラベルごとに top_k_per_label 件を選び、それぞれを照明条件ごとに 1 行へ展開します。正確な計算方法、オーバーライドのデフォルト値、アーティファクトの表については、references/parameters-and-artifacts.md を参照してください。

再現率の目標を満たすしきい値候補がない場合、コンテナはゼロ以外の終了コードで終了し、モデルが実際に達成できる再現率を説明する unreachable_kpi.txt を results_dir に書き込みます。その場合は、Docker 呼び出し後に分析を終了し、モデルがどの動作点でも KPI を根本的に達成できないことを説明する 1 セクションのレポートを作成して、再トレーニングまたは再ラベル付けを推奨してください。目視確認は省略してください。

コンテナが results_dir に書き込むファイル： kpi_gaps.parquet（ラベルごとに弱さが最も大きいトップ K 件を照明条件ごとに展開。列は filepath、label、siamese_score、weakness）、threshold.txt、metrics.json、weak_samples_breakdown.txt、および unreachable_kpi.txt（再現率の目標を達成できない場合のみ）。各アーティファクトの内容については、references/parameters-and-artifacts.md を参照してください。選択されたしきい値、残った行数、ラベルごとの内訳を含むコンテナの標準出力の概要を、自身の標準出力に表示してください。これにより、スクリプト確認フックで実行結果を検証できます。

ステップ 5 — 目視でのスポットチェック（少数、固定）

results_dir に unreachable_kpi.txt が存在する場合は、このステップを省略してください。どのしきい値でもモデルが KPI を達成できない場合、スポットチェックを行っても意味がありません。

それ以外の場合は、Read ツールを使って、次のテスト画像を表示してください。

• 最も弱い PASS サンプル 5 件（「PASS を NO_PASS と誤分類」したサンプルの山の先頭）。kpi_gaps.parquet の行から label == 'PASS' のものを選び、weakness の降順で並べます。
• 最も弱い NO_PASS サンプル 5 件（「NO_PASS を PASS と誤分類」したサンプルの山の先頭）。同様に、label != 'PASS' のものを選びます。

kpi_gaps.parquet はすでに照明条件ごとに展開されているため、サンプルごとに複数の行があります。スポットチェックでは、(input_path, object_name) ごとに 1 行に重複排除してください。train YAML で最初に指定されている照明条件を使う filepath の行を選びます（サンプルごとに画像は 1 枚で十分です。VCN の分類ヘッドはすべての照明条件を積み重ねて処理しますが、人によるスポットチェックには 1 枚で代表できます）。

表示した各サンプルを、次のいずれか 1 つに分類してください。

• ラベル誤り — 画像の内容が CSV のラベルと一致しない
• 境界ケース — 実際に判断が曖昧な境界事例
• データ品質 — 画像の破損、暗さ、切り抜きの誤り、フレーミングの不備
• 系統的な問題 — モデルが誤った特徴を学習している（画像は「明らかに PASS／NO_PASS」に見えるのに、モデルは異なる判定をしている）

表示した画像を <results_dir>/rca_images/ にコピーしてください。PIL が利用可能な場合は 128×128 にサイズ変更し、利用できない場合はそのままコピーします。画像はレポートにインラインで埋め込めるようにします。

画像の確認は、これが唯一必要な作業です。数十枚の画像を表示したり、失敗モードのクラスタリングを実行したり、ゴールデン画像を監査したりしないでください。VCN にはゴールデン画像がありません。

---

参照用の実行手順

ワークスペース、4つのパス、2つの数値パラメーター、仕様ファイルの書き込み、docker run、およびスクリプトチェックフック用に行数を表示する標準出力の確認用プリントを含む、貼り付けて編集するだけのエンドツーエンド手順は references/recipe.md にあります。ワークスペース、パス、パラメーターだけを編集し、そのまま使用してください。

---

出力

すべての出力を、実験結果ディレクトリ配下のタイムスタンプ付きフォルダー <experiment_result_dir>/rca_results/YYYY-MM-DD_HHMMSS/ に書き込みます。コンテナーの出力（kpi_gaps.parquet、threshold.txt、metrics.json、weak_samples_breakdown.txt、該当する場合は unreachable_kpi.txt）はそのフォルダーに直接保存されます。目視確認の画像は rca_images/ に保存されます。パッケージングフックは、RCA_Report.md の書き込み時に rca_config/ と claude_session.jsonl を自動的に追加します。フォルダー構成の全体については references/parameters-and-artifacts.md を参照してください。

実行の開始時に、Bash で date +%Y-%m-%d_%H%M%S を実行して実際のタイムスタンプを取得します。ハードコードしたり、推測したりしないでください。ユーザーがカスタム出力パスを指定した場合はそのパスを使用しますが、内部構成は同じにしてください。

---

よくある落とし穴

最も重大な失敗は、min_recall=1.0 のときに top_k_per_label を指定し忘れることです。この再現率では、選択されるしきい値がすべての NO_PASS スコア以下になるため、しきい値を下回る行を対象とするフォールバックフィルターには誤分類された PASS 行だけが一致し、kpi_gaps.parquet に NO_PASS 行が1つも残りません。必ず正の値の top_k_per_label を明示してください。落とし穴の一覧（$WORKSPACE の外にある仕様ファイル、未解決の ??? センチネル、誤った、またはプルされていないイメージタグ、パスマウントの不一致、unreachable_kpi.txt の処理、inference.csv の列不足、train-YAML のキー不足、kpi_media_path のプレフィックス不一致、コンテナー内に GPU がない場合）と CLI の差異の調整については references/troubleshooting.md を参照してください。

---

レポートの構成

RCA レポートをタイムスタンプ付き出力フォルダーに書き込みます。これは7セクションからなる計算的なギャップ分析（判定、しきい値の選択、弱点の分布、最も弱いサンプルの上位K件、目視確認、ラベルごとの内訳、推奨アクション）で、1000～1800語とします。混同行列とラベルごとの表には metrics.json の値を入力し、目視確認の行には kpi_gaps.parquet の値を入力します。unreachable_kpi.txt が存在する場合は、セクション3～6をそのファイルを引用する短い1セクションに置き換え、セクション7は再トレーニングまたは再ラベル付けの推奨事項1つにまとめます。すべてのセクション見出し、表のレイアウト、到達不能 KPI の場合の形式を含む完全なひな形については references/rca-report-structure.md を参照してください。

---

実行順序

1. versions.yaml（images.tao_toolkit.data_services）から DS_IMAGE を解決し、次に docker info、nvidia-smi、docker image inspect "$DS_IMAGE" を実行します。環境の確認のため、必要な場合はイメージをプルしてください。いずれかが失敗した場合は、明確なメッセージを表示して中止します。
2. date +%Y-%m-%d_%H%M%S を実行してタイムスタンプを取得し、<experiment_result_dir>/rca_results/<timestamp>/ を作成します。
3. タイムスタンプ付きディレクトリに vcn_aoi_spec.yaml を書き込み、min_recall と top_k_per_label を設定します。-e のパスがコンテナー内で解決できるよう、$WORKSPACE の配下に置いてください。
4. docker run … "$DS_IMAGE" gap_analysis vcn_aoi -e vcn_aoi_spec.yaml inference_results_dir=… train_config=… kpi_media_path=… output_dir=… を実行します。コンテナーは results_dir に kpi_gaps.parquet、threshold.txt、metrics.json、weak_samples_breakdown.txt を書き込みます。スクリプトチェックフックが実行による出力の生成を確認できるよう、選択したしきい値と保持された行数を標準出力に表示します。
5. unreachable_kpi.txt が存在する場合は、ステップ6を省略して短縮版のレポートを作成します。存在しない場合は続行します。
6. kpi_gaps.parquet から弱点のあるサンプルを10件（最も弱い PASS を5件、最も弱い NO_PASS を5件）選び、Read を使って各テスト画像を表示して分類し、それぞれを rca_images/ にコピーします。
7. 最後に RCA_Report.md を書き込みます。これによりパッケージングフックが起動し、セッションログとスキル設定が同じ場所にコピーされます。