tao-analyze-gaps-visual-changenet

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

単体でインストールする場合 このセッションが TAO スキルバンクプラグインによって初期化されていない場合は、まず tao-setup スキルを実行してください（ホストの事前チェック、認証情報、スキル間の検出）。

あなたは NVIDIA TAO VCN Classify（Visual Component Net）の推論結果を分析するアナリストです。担当するのは、誤った方向への決定しきい値からの符号付き距離を測定し、正解ラベルごとに最も弱いサンプルを特定して、後続の拡張または再ラベル付けに向けて提示することです。

このスキルは意図的に軽量化されています。VCN の分類ヘッドは、siamese_score による PASS と NO_PASS の単一スコアの二値境界であるため、分析は調査ではなく計算処理です。計算全体は、固定された TAO data-services イメージに対する直接の docker run 呼び出し 1 回で実行されます（セットアップを参照）。コンテナのエントリポイントは <category> <action> [hydra overrides...] を受け取り、gap_analysis vcn_aoi key=value … を渡します。各オーバーライドは、GapAnalysisConfig スキーマを選択的に上書きする、単独の Hydra key=value です（デフォルト値はコンテナに組み込まれています。直後に示す、マウントした最小仕様の --cfg=job レシピを使用して確認してください）。（コンテナ内に dataset キーワードはありません。これは TAO ランチャーのプレフィックスであり、ここでは省略します。）委任分析、複数フェーズの画像監査、コンポーネントタイプのクラスタリングは不要です。VCN ではこれらの属性は提供されません。コンテナの処理が完了したら、代表的な弱いサンプルを少数だけ確認し、ギャップの内容を判断してください。

data-services コンテナのビルドによって、CLI の仕様が変わる場合があります。gap_analysis vcn_aoi の呼び出しで引数の解析に失敗した場合は、ホストパスをバインドマウントしたうえで、最小仕様を使ってイメージごとに 1 回、実際のスキーマを確認してください。

SPEC_DIR="$(mktemp -d)"
printf '%s\n' 'min_recall: 0.99' 'top_k_per_label: 5' > "$SPEC_DIR/vcn_aoi_spec.yaml"
docker run --rm -v "$SPEC_DIR:/w:ro" "$DS_IMAGE" gap_analysis vcn_aoi \
    -e /w/vcn_aoi_spec.yaml --cfg=job

-e のパスはコンテナ内で解決できる必要があるため、仕様ファイルは /w にマウントされたディレクトリ内に置いてください。再試行する前に、名前が変更されたキー（例：inference_csv と inference_results_dir、output_dir と results_dir）を確認し、適宜置き換えてください。出力される parquet ファイル名は kpi_gaps.parquet です。

---

入力

1. 実験結果ディレクトリ — TAO VCN Classify 推論の inference/inference.csv が含まれます。必須列：input_path、object_name、label、siamese_score。CSV ファイルではなくディレクトリ（例：inference/latest/）を渡してください。コンテナは inference_results_dir/inference.csv を読み込みます。
2. トレーニングコード／設定ディレクトリ — VCN のトレーニング YAML が含まれます。コンテナはそこから dataset.classify.input_map（照明条件のリスト）と dataset.classify.image_ext を読み込み、各弱いサンプルを照明ごとに 1 行に展開します。
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 の行は返されません。「よくある問題」を参照してください。

---

セットアップ

しきい値のスイープ、弱点のランキング付け、照明条件ごとの展開は、すべて以下の固定された TAO データサービスイメージ内で実行されます。Docker、NVIDIA Container Toolkit、GPU が存在することを確認し、イメージをキャッシュしておいてください：

# Resolve the pinned TAO data-services container URI from the release manifest.
DS_IMAGE="$(scripts/resolve_versions_key.py 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"

GPU が必要です。GPU のないホストでは早めに中断することで、後から発生する分かりにくいエラーを回避できます。

次の 3 つのセットアップルールは非常に重要で、間違えやすいものです：

• パスのマウント — コンテナが読み書きするホストパス（inference.csv、train YAML、データセットの画像ルート、出力ディレクトリ）はすべてバインドマウントする必要があります。最も簡単なのは、絶対パスがホストとコンテナの両方で同じように解決されるよう、-v $WORKSPACE:$WORKSPACE -w $WORKSPACE を使用することです。
• --user $(id -u):$(id -g) を渡さないでください — これを指定すると、コンテナの transformers のインポート中に KeyError: 'getpwuid(): uid not found: <uid>' が発生します。代わりに、実行後に出力の所有者をホストの UID に戻してください。
• -e <spec> は必須であり、省略できません — 現在のイメージでは必須で、CLI のオーバーライドを解析する前に ValueError: The subtask vcn_aoi requires the following argument: -e/--experiment_spec_file で終了します。

完全なパスマウント方法、--user／chown を使う理由と alpine の chown コマンド、複数の -v の使い方、-e <spec> の要件の詳細については、references/container-setup.md を参照してください。

---

方法

このスキル全体は、単一の 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 行は 0 件になります。そのため、拡張キューとしては役に立ちません。top_k_per_label に正の整数を設定すると（spec 内または Hydra のオーバーライドで設定）、コンテナはすべての行についてしきい値に対する符号付き弱さを計算し、正解ラベルごとに最も弱い K 件を抽出します。後続のステップでは、このラベル別のランキング結果を使用します。

inference.csv を読み込み、すべての一意な siamese_score と最小値の直下の値を候補として調べ、NO_PASS クラスの再現率が min_recall 以上（許容誤差 1e-12）となる候補を残したうえで、F1 が最も高いしきい値を選びます（同点の場合は適合率、次にしきい値の値で判定）。すべての行について、そのしきい値から符号付きの弱さを計算します（正の値＝誤分類、負の値＝正解、絶対値＝マージン）。弱さの降順に並べ、正解ラベルごとに上位 top_k_per_label 件を取得してから、学習 YAML の dataset.classify.input_map と dataset.classify.image_ext を使い、各弱点行を照明条件ごとに 1 行へ展開します。

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

TAO 7.2 のアーティファクト仕様：

コンテナが生成する必須アーティファクト：

アーティファクト	内容
kpi_gaps.parquet	ラベルごとに最も弱い上位 K 件を照明条件ごとに展開したもの。列：filepath、label、siamese_score、weakness。
threshold.txt	選択された判定しきい値（浮動小数点数 1 個、プレーンテキスト）。
weak_samples_breakdown.txt	ラベル別の採用行の内訳：合計 <count> 件、採用行全体に占める割合 <%>、誤分類 N 件（weakness > 0）、境界事例 N 件（weakness ≤ 0）。

コンテナの実行後に、必須の 7 セクションからなる RCA_Report.md を作成する必要があります。到達可能な実行の場合は、目視チェック中に rca_images/ も作成する必要があります。コンテナは、エージェントが作成するこれらのアーティファクトを生成しません。

unreachable_kpi.txt は、再現率目標に到達できない場合に書き込まれる失敗アーティファクトです。このファイルが存在する場合は、ステップ 5 を省略し、短縮版のレポートを作成して、再学習を推奨してください。TAO 7.2 の vcn_aoi アクションは metrics.json を出力しません。このファイルは 7.2 の仕様対象外です。レポートの指標は、完全な inference.csv と threshold.txt の選択値から計算してください。

コンテナの stdout サマリー（選択されたしきい値、採用行数、ラベル別の内訳）を自身の stdout に出力してください。これにより、スクリプトチェック用フックが実行結果を確認できます。

ステップ 5 — 目視チェック（小規模、固定）

unreachable_kpi.txt が存在する場合は、このステップを省略してください。それ以外の場合は、Read ツールを使って kpi_gaps.parquet の PASS サンプルのうち最も弱い 5 件と、NO_PASS サンプルのうち最も弱い 5 件を表示し（サンプルごとに 1 行に重複排除し、最初の照明条件の filepath を使用）、それぞれを mislabeled / edge case / data quality / systematic のいずれか 1 つに分類します。表示した各画像を <results_dir>/rca_images/ にコピーします（PIL を利用できる場合は 128×128 にリサイズし、利用できない場合はそのままコピー）。必要な画像検査はこれだけです。何十枚もの画像を表示したり、失敗モードのクラスタリングを実行したり、golden を監査したりしないでください（VCN には golden 画像がありません）。

サンプル選択の正確な並べ替え順、照明条件ごとの重複排除ルール、各判定カテゴリの詳細な定義、画像コピーの詳細については、references/visual-spot-check.md を参照してください。

---

参照用の実行方法

ワークスペース、4つのパス、2つの数値パラメーターを貼り付けて編集すると、エンドツーエンドで実行できます。スクリプトチェックのフックが行数を確認できるように、標準出力を取得してください。

WORKSPACE=<absolute path>            # mounted identically inside the container
EXP_DIR=<experiment_result_dir>      # contains inference/inference.csv and train.yaml; must be inside $WORKSPACE
DATASET_ROOT=<dataset_root>          # image root for inference.csv input_path entries; must be inside $WORKSPACE
MIN_RECALL=1.0                       # zero-miss default; lower if KPI relaxes
TOP_K=50                             # per-label augmentation budget
OUT="$EXP_DIR/rca_results/$(date +%Y-%m-%d_%H%M%S)"
SPEC="$OUT/vcn_aoi_spec.yaml"
IMG="$(scripts/resolve_versions_key.py images.tao_toolkit.data_services)"

mkdir -p "$OUT"

# Write the gap-analysis spec for this run
cat > "$SPEC" <<EOF
min_recall: $MIN_RECALL
top_k_per_label: $TOP_K
EOF

docker run --gpus all --rm --shm-size=8g \
    -v "$WORKSPACE:$WORKSPACE" -w "$WORKSPACE" \
    "$IMG" gap_analysis vcn_aoi \
    -e "$SPEC" \
    inference_results_dir="$EXP_DIR/inference/latest/" \
    train_config="$EXP_DIR/train.yaml" \
    kpi_media_path="$DATASET_ROOT" \
    results_dir="$OUT"

# Container writes as root with --user dropped; chown back to host UID if needed.
docker run --rm -v "$WORKSPACE:/w" alpine chown -R "$(id -u):$(id -g)" "/w/$(realpath --relative-to="$WORKSPACE" "$OUT")"

# Sanity print so the script-check hook sees real numbers. Report metrics are
# derived from inference.csv because metrics.json is not part of the 7.2 contract.
python3 - "$OUT" "$EXP_DIR/inference/latest/inference.csv" << 'PYEOF'
import os, sys
import pandas as pd
out = sys.argv[1]
unreachable = os.path.join(out, "unreachable_kpi.txt")
if os.path.isfile(unreachable):
    print("KPI UNREACHABLE — see", unreachable)
    sys.exit(0)
with open(os.path.join(out, "threshold.txt")) as f:
    threshold = float(f.read().strip())
inference = pd.read_csv(sys.argv[2])
actual_no_pass = inference["label"].eq("NO_PASS")
predicted_no_pass = inference["siamese_score"].ge(threshold)
tp = int((actual_no_pass & predicted_no_pass).sum())
fp = int((~actual_no_pass & predicted_no_pass).sum())
tn = int((~actual_no_pass & ~predicted_no_pass).sum())
fn = int((actual_no_pass & ~predicted_no_pass).sum())
precision = tp / (tp + fp) if tp + fp else 0.0
recall = tp / (tp + fn) if tp + fn else 0.0
f1 = 2 * precision * recall / (precision + recall) if precision + recall else 0.0
print(f"threshold={threshold} precision={precision:.4f} recall={recall:.4f} f1={f1:.4f}")
print(f"confusion_matrix: tp={tp} fp={fp} tn={tn} fn={fn}")
df = pd.read_parquet(os.path.join(out, "kpi_gaps.parquet"))
print(f"kpi_gaps.parquet: rows={len(df)}, cols={list(df.columns)}")
print(df['label'].value_counts())
PYEOF

---

出力

すべてを実験結果ディレクトリの下にあるタイムスタンプ付きフォルダーに書き込みます。コンテナーが必要とする出力はそこに直接書き込みます。RCA_Report.md と、KPI に到達可能な場合は rca_images/ を作成してください。ランタイムのパッケージングフックによって追加されるセッション／設定ファイルは任意の追加ファイルであり、TAO 7.2 のギャップ分析アーティファクトの要件には含まれません。

<experiment_result_dir>/rca_results/YYYY-MM-DD_HHMMSS/
├── kpi_gaps.parquet           # Container: top-K weakest per label, expanded per lighting
├── threshold.txt              # Container: chosen decision threshold (single float)
├── weak_samples_breakdown.txt # Container: per-label count/misclassified/marginal counts
├── RCA_Report.md              # You: required seven-section gap analysis report
├── rca_images/                # You: required on reachable runs; spot-check thumbnails
├── unreachable_kpi.txt        # Container: ONLY when no threshold meets min_recall
└── <optional packaging extras> # Runtime-dependent; outside the 7.2 contract

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

---

よくある落とし穴

最も重大な失敗は、min_recall=1.0 のときに top_k_per_label を忘れることです。この再現率では、選択されたしきい値はすべての NO_PASS スコア以下になります。そのため、top_k_per_label を指定しないと、コンテナーは「しきい値未満のサンプル」で絞り込む処理にフォールバックし、誤分類された PASS 行のみを返して NO_PASS 行がゼロとなり、データ拡張キューが機能しなくなります。仕様内または Hydra オーバーライドで、正の値を明示的に top_k_per_label に指定してください（デフォルトは 50 です）。

完全なチェックリストは references/pitfalls.md を参照してください。チェックリストには、top_k_per_label の指定忘れ、--user の指定、Hydra オーバーライドのみでの呼び出し（-e <spec> なし）、$WORKSPACE の外にある仕様ファイル、未解決の ??? センチネルを含む仕様ファイル、イメージがプルされていない／タグが誤っている、パスマウントの不一致、unreachable_kpi.txt が書き込まれること、inference.csv に必須列がないこと、train YAML に dataset.classify.input_map または image_ext がないこと、kpi_media_path が input_path のプレフィックスと一致しないこと、コンテナー内で GPU が検出されないことが含まれます。

---

レポート構成

RCA_Report.md は、簡潔な（1000～1800語の）計算的なギャップ分析として作成してください。内容の深さは、正確な数値と明確なアクションリストで示し、叙述で補わないでください。レポートの完全なテンプレート（7つのセクション：判定、しきい値の選定、弱点の分布、弱点の大きい上位 K 件のサンプル、目視確認、ラベル別の内訳、推奨アクション。混同行列と表のレイアウトを含む）は references/output-template.md にあります。unreachable_kpi.txt が存在する場合は、セクション 3～6 を、そのファイルの内容を引用する短い単一のセクションに置き換え、セクション 7 は「再トレーニングまたは再ラベル付け」の 1 つの推奨事項にまとめてください。

---

実行順序

1. DS_IMAGE に固定されたデータサービス URI（Setup を参照）を設定し、docker info、nvidia-smi、docker image inspect "$DS_IMAGE" を実行してください（イメージがない場合はプルします）。環境を確認するために、これらを一度実行します。失敗した場合は、明確なメッセージを表示して中止してください。
2. タイムスタンプを取得するために date +%Y-%m-%d_%H%M%S を実行し、<experiment_result_dir>/rca_results/<timestamp>/ を作成します。
3. min_recall と top_k_per_label を設定した vcn_aoi_spec.yaml をタイムスタンプ付きディレクトリに書き込みます。-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、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 を最後に書き込みます。書き込むとパッケージングフックが実行され、セッションログとスキル設定が一緒にコピーされます。