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 模型会将测试图像与黄金图像（已知良好的参考图像）进行比较，以检测差异。查看图像时，请检查以下三点：

1. 图像质量：两张图像都应曝光正常，且内容清晰可见。注意异常偏暗的图像，但不要使用固定的强度阈值。某些照明类型（例如 SolderLight）产生的图像整体偏暗，平均强度 < 30 也属正常。务必先建立 PASS 黄金基线，再根据该基线标记异常值。
2. 取景匹配：测试图像和黄金图像应展示相同区域，且缩放比例和方向一致。取景不匹配（例如，一个是广角视野，另一个是特写）说明黄金图像处理流程存在错误。
3. 缺陷可见性：能否看出测试图像与黄金图像之间的差异？某些缺陷在任何分辨率下都很明显；另一些缺陷经过缩小至模型输入尺寸后可能无法辨认。请比较原始图像尺寸与模型输入尺寸，以评估信息损失。

---

调查流程

调查分为 5 个阶段。阶段 1（数值）提供假设。阶段 2（图像）验证或推翻这些假设。阶段 3（跨维度）寻找隐藏模式。阶段 4（配置）解释其成因。阶段 5（反事实）量化修复效果。阶段 2 是核心——应在此投入最多精力。阶段 5 最具可操作性——绝不可跳过。

• 阶段 1 — 分数分析：分数统计与分层分类、200 点阈值扫描、按缺陷类型划分的表格、KPI 判断，以及删除 N 个样本的阈值关键分析。建立假设。
• 阶段 2 — 深入图像调查（核心）：阈值关键样本深入分析（2A）、系统性黄金图像审核与失效模式聚类（2B）、假阳性深入分析（2C）、对比视觉分析（2D），以及标签语义与视觉模式对齐审核（2E）。包括图像路径构建规则。
• 阶段 3 — 跨维度分析：组件类型聚类（3A）、板级与位置分析（3B）、训练图像深入分析（3C）、多光照条件分析（3D）。
• 阶段 4 — 数据与训练配置分析：数据充分性（4A）、训练配置审核（4B）、训练指标（4C）、损失函数与决策边界分析（4D）。
• 阶段 5 — 反事实与可操作性分析：假设场景模拟（5A）和最小可行修复路径（5B）。

有关每个阶段和子阶段的完整逐步流程，包括所有命令、脚本、阈值、数值、图像路径构建规则、严重性指导和必需的报告输出，请参阅 references/phases.md。请严格按其中的规定执行每个步骤。

---

并行化策略（使用子 Agent）

必须使用 Agent 工具并行开展独立调查。 在主线程中自行执行阶段 1，然后同时启动 6 个子 Agent（Agent A–F）执行阶段 2–4 的任务；收集并综合它们的调查结果（尤其留意探索型 Agent E 和 F），自行执行阶段 5，然后撰写报告。报告撰写步骤会强制执行必需的图像嵌入协议——每个视觉证据表格行都必须包含内联缩略图列，否则钩子会拒绝该报告。

完整执行计划见 references/parallelization.md：其中包含必须保存的阶段 1 输出、Agent A–F 各自的检查清单和输入、综合核查项、包含各章节规则和表格格式的完整必需图像嵌入协议、探索性调查结果章节，以及包含必需的缩略图映射返回格式的子 Agent 提示词模板。请严格遵循。

---

架构参考

• 可学习模块：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 * (1.0 - epoch / (num_epochs + 1))
• 数据加载：num_golden=1 时使用 SiameseNetworkTRIDataset，num_golden>1 时使用 MultiGoldenDataset

---

报告结构

生成 RCA_Report.md，包含 9 个顶级章节：（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。如果用户指定了自定义路径，则使用该路径，但保持相同的目录结构。