tao-analyze-changenet-rca

TAO ChangeNet 分類 RCA スキル

NVIDIA TAO Visual ChangeNet の分類実験を調査するエキスパートです。実際の画像から得られた視覚的な証拠に基づいて、モデルが失敗する理由を突き止めます。

ユーザーから実験結果ディレクトリとトレーニングコードディレクトリが提供されたら、詳細な根本原因分析を実施します。調査は画像の証拠を重視して進めてください。主な結論はすべて、実際に確認した特定の画像に基づく必要があります。

---

入力

1. 実験結果ディレクトリ — train/ と inference/ を含みます
2. トレーニングコードディレクトリ — visual_changenet/ ソースツリー
3. データセットディレクトリ — CSV ファイルと画像が格納されている場所（多くの場合、experiment.yaml に記載されています）
4. 目標 KPI — 指定がない場合は、デフォルトで再現率優先にします。選択肢：再現率優先（再現率 100% 時の FAR）、FAR 優先（目標 FAR 時の再現率）、バランス（F1）、カスタム。

---

目視検査の基本

ChangeNet モデルは、テスト画像とゴールデン画像（正常な参照画像）を比較して差異を検出します。画像を確認する際は、次の 3 点を確認してください。

1. 画像品質：両方の画像が適切な露出で、内容を確認できる必要があります。異常に暗い画像に注意してください。ただし、固定の輝度しきい値は使用しないでください。SolderLight など一部の照明条件では、平均輝度が 30 未満になるのが通常です。必ず PASS のゴールデン画像を基準として確立し、それに対する外れ値を特定してください。
2. フレーミングの一致：テスト画像とゴールデン画像は、同じ領域を同じズーム倍率と向きで表示している必要があります。フレーミングが一致しない場合（例：広視野とクローズアップ）は、ゴールデン画像パイプラインのエラーを示しています。
3. 欠陥の視認性：テスト画像とゴールデン画像の違いを視認できますか？解像度に関係なく明らかな欠陥もあれば、モデルの入力サイズに縮小すると見えなくなる欠陥もあります。元画像の寸法とモデルの入力サイズを比較し、情報の損失を評価してください。

---

調査の流れ

調査は 5 つのフェーズで進めます。フェーズ 1（数値）で仮説を立てます。フェーズ 2（画像）で仮説を検証または否定します。フェーズ 3（多次元分析）で隠れたパターンを見つけます。フェーズ 4（設定）で原因の仕組みを説明します。フェーズ 5（反実仮想）で修正の効果を定量化します。中核となるのはフェーズ 2 です。ここに最も多くの労力をかけてください。最も実行に移しやすいのはフェーズ 5 です。決して省略しないでください。

• フェーズ 1 — スコア分析：スコア統計と層別分類、200 ポイントのしきい値スイープ、欠陥タイプ別の表、KPI 判定、および drop-N によるしきい値クリティカル分析。仮説を確立します。
• フェーズ 2 — 画像の詳細調査（中核）：しきい値クリティカルなサンプルの詳細調査（2A）、ゴールデン画像の体系的な監査と失敗モードのクラスタリング（2B）、偽陽性の詳細調査（2C）、比較視覚分析（2D）、ラベルの意味と視覚パターンの整合性監査（2E）。画像パスの構築ルールも含みます。
• フェーズ 3 — 多次元分析：コンポーネントタイプのクラスタリング（3A）、ボード単位および位置分析（3B）、トレーニング画像の詳細調査（3C）、複数照明条件の分析（3D）。
• フェーズ 4 — データとトレーニング設定の分析：データの十分性（4A）、トレーニング設定の監査（4B）、トレーニングメトリクス（4C）、損失関数と決定境界の分析（4D）。
• フェーズ 5 — 反実仮想と実行可能性の分析：what-if シミュレーション（5A）と、実行可能な最小修正パス（5B）。

すべてのフェーズおよびサブフェーズの詳細な手順については、references/phases.md を参照してください。そこにはすべてのコマンド、スクリプト、しきい値、数値、画像パスの構築ルール、重大度のガイダンス、必須のレポート出力が記載されています。そこに記載されたすべての手順を、指定どおりに実行してください。

並列化戦略（サブエージェントを使用）

Agent ツールを使って、独立した調査トラックを並行して実行する必要があります。 メインスレッドでフェーズ 1 を実行してから、フェーズ 2～4 のトラック用にサブエージェントを 6 つ（A～F）同時に起動し、調査結果を収集して統合してください（特に、探索を行うエージェント E と F の結果を重視してください）。フェーズ 5 は自分で実行し、レポートを作成してください。レポート作成時には必須の画像埋め込みプロトコルが適用されます。すべての視覚的証拠の表の行にインラインサムネイル列を含めないと、フックによってレポートが拒否されます。

完全な実行計画については、references/parallelization.md を参照してください。フェーズ 1 で保存する正確な出力、エージェント A～F のチェックリストと入力、統合時の相互確認、セクションごとのルールと表の形式を含む必須の画像埋め込みプロトコル全文、探索結果のセクション、および必須のサムネイルマップ返却形式を含むサブエージェントのプロンプトテンプレートが記載されています。内容に正確に従ってください。

---

アーキテクチャのリファレンス

• Learnable モジュール：softmax(model(img1, img2), dim=1)[:, 1] → スコア = P(欠陥)。値が大きいほど欠陥の可能性が高くなります。
• ユークリッド距離モジュール：F.pairwise_distance(embed1, embed2) → スコア = 距離。値が大きいほど、違いが大きくなります。
• WeightedRandomSampler：fail_wt = (num_pass / num_fail) * fpratio_sampling。欠陥は fail_wt:1 の比率でサンプリングされます。
• 画像パス：{images_dir}/{input_path}/{object_name}_{light_condition}.{ext}
• LR 線形：lr * (1.0 - epoch / (num_epochs + 1))
• データ読み込み：num_golden=1 の場合は SiameseNetworkTRIDataset、num_golden>1 の場合は MultiGoldenDataset

---

レポートの構成

最上位セクションが 9 つある RCA_Report.md を作成します：（1）判定、（2）スコア分析、（3）視覚的証拠（全体を通してインラインサムネイルを含める）、（4）次元横断分析、（5）データの問題、（6）トレーニング設定の問題、（7）探索結果、（8）反実仮想の影響分析、（9）推奨する修正（影響度 × 実現可能性の順）。視覚的証拠の表には、rca_images/ に生成したサムネイルを埋め込む必要があります。

すべてのセクション、サブセクション、表の列構成、インラインサムネイルの要件を含むレポートの完全なひな形については、references/report-structure.md を参照してください。ひな形に正確に合わせてください。

---

出力先

出力は必ず、<experiment_result_dir>/rca_results/YYYY-MM-DD_HHMMSS/ の下にあるタイムスタンプ付きフォルダーに保存してください。このフォルダーには、RCA_Report.md、サムネイル用の rca_images/ フォルダー、フックによってデータが入力される rca_config/、および claude_session.jsonl を含めます。実際のタイムスタンプは、Bash で date +%Y-%m-%d_%H%M%S を実行して取得してください。ハードコードしたり推測したりしてはいけません。

完全なディレクトリツリー、およびフォルダーの作成、サムネイルの書き込み、レポートの書き込み（これによりパッケージングフックが実行されます）の正確な順序については、references/output-and-deliverable.md を参照してください。ユーザーがカスタムパスを指定した場合は、同じ構成を維持したうえで、そのパスを使用してください。