tao-analyze-gaps-vlm-bcq

VLM 二値分類ギャップ分析

VLM の予測 JSON を読み込み、各モデルの応答を正解データと比較して、FP/FN の失敗ケースを JSONL ファイルに書き込み、サマリーレポートを作成します。

目的

VLM で二値の yes/no 評価タスクを実行した後、失敗ケースを特定するために予測を正解データと比較する必要があります。このスキルは、FP（偽陽性）と FN（偽陰性）のサンプルを構造化されたリストとして出力します。このリストは、後続の RCCA ステージ（例：cosmos の生成、根本原因分析）で使用され、DEFT の反復を推進します。

使い方

Hydra 形式の key=value オーバーライドを使い、TAO Toolkit データサービスコンテナ内で vlm_bcq アクションを呼び出します。

gap_analysis vlm_bcq \
  predictions_json=/path/to/results.json \
  results_dir=/path/to/output/gaps

予測内の video_id が相対パスの場合は、videos_dir を指定してください。

gap_analysis vlm_bcq \
  predictions_json=/path/to/results.json \
  results_dir=/path/to/output/gaps \
  videos_dir=/path/to/videos/root

実行後、kpi_gaps_report.txt の FP/FN 件数を確認し、後続ステージで kpi_gaps.jsonl を指定してください。

入力

• predictions_json：予測 JSON ファイルのパスです。各項目に video_id、response、gt フィールドが含まれる JSON 配列である必要があります。response と gt は単語境界に基づいて解析され、「yes」または「no」が文字列内のどこかにあれば認識されます。両方が含まれるサンプル、またはいずれも含まれないサンプルは警告とともにスキップされます。
• videos_dir（任意）：相対パスの video_id を解決するためのベースディレクトリです。省略した場合、video_id の値は絶対パスとして使用されます。

予測 JSON の形式：

[
  {
    "video_id": "/path/to/video.mp4",
    "response": "Yes, there is a collision.",
    "gt": "B. No",
    "question": "Is there a collision?"
  }
]

出力

• kpi_gaps.jsonl：FP/FN ケースごとに 1 行の JSON オブジェクトを出力します。フィールド：video_id（絶対パス）、error_type（FP または FN）、question、ground_truth、response。
• kpi_gaps_report.txt：FP/FN の合計件数を含む、人が読みやすい形式の表です。

ギャップが見つからない場合、ファイルは書き込まれず、メッセージがログに記録されます。

主なパラメーター

パラメーター	必須	説明
predictions_json	はい	予測 JSON ファイルのパス
results_dir	はい	出力ディレクトリ。存在しない場合は作成されます
videos_dir	いいえ	相対パスの video_id を解決するためのベースディレクトリ

エラーパターン

エラー	原因	修正方法
FileNotFoundError	predictions_json が存在しません	パスを確認してください
ValueError: must be a JSON array	予測ファイルがリストではありません	予測を [...] で囲んでください
ValueError: missing 'gt'/'response'/'video_id'	予測項目に必須フィールドがありません	予測 JSON を確認して修正してください
サンプルが通知なくスキップされる	response または gt に「yes」と「no」の両方、あるいはいずれも含まれていません	警告がないかログを確認し、該当するサンプルを調べてください