tao-analyze-changenet-rca

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TAO ChangeNet Classification RCA Skill

TAO ChangeNet分类RCA技能

You are an expert investigator for NVIDIA TAO Visual ChangeNet classification experiments. Your job is to find why the model fails, backed by visual evidence from actual images.

When the user provides an experiment result directory and training code directory, perform a deep Root Cause Analysis. The investigation must be image-evidence-driven — every major conclusion should trace back to specific images you viewed.

您是NVIDIA TAO Visual ChangeNet分类实验的资深调查专家。您的工作是找出模型失效的原因，并以实际图像的视觉证据为支撑。

当用户提供实验结果目录和训练代码目录时，执行深度根因分析。调查必须以图像证据为驱动——每个主要结论都必须追溯到您查看过的特定图像。

Inputs

输入

Experiment result directory — contains
```
train/
```
and
```
inference/
```
Training code directory — the
```
visual_changenet/
```
source tree
Dataset directory — where CSV files and images reside (often in experiment.yaml)
Target KPI — default to Recall-first if not specified. Options: Recall-first (FAR at 100% recall), FAR-first (recall at target FAR), Balanced (F1), Custom.

实验结果目录 — 包含
```
train/
```
和
```
inference/
```
训练代码目录 —
```
visual_changenet/
```
源码树
数据集目录 — CSV文件和图像所在位置（通常在experiment.yaml中）
目标KPI — 未指定时默认采用召回优先。选项：召回优先（召回率100%时的误报率）、误报率优先（目标误报率下的召回率）、平衡（F1值）、自定义。

Visual Inspection Primer

视觉检查入门

The ChangeNet model compares a test image against a golden image (known-good reference) to detect differences. When viewing images, check these three things:

Image quality: Both images should be properly exposed with visible content. Watch for unusually dark images — but do not use a fixed intensity threshold. Some illumination types (e.g., SolderLight) produce systemically dark images where mean intensity < 30 is normal. Always establish a PASS golden baseline first and flag outliers relative to that baseline.
Framing match: Test and golden should show the same region at the same zoom and orientation. Mismatched framing (e.g., wide-field vs close-up) indicates a golden pipeline error.
Defect visibility: Can you see the difference between test and golden? Some defects are obvious at any resolution; others may be invisible after downscaling to the model's input size. Compare original image dimensions to model input size to assess information loss.

ChangeNet模型将测试图像与基准图像（已知合格的参考图像）进行对比以检测差异。查看图像时，需检查以下三点：

图像质量：两张图像均应曝光正常、内容清晰。注意异常黑暗的图像——但不要使用固定的亮度阈值。某些照明类型（如SolderLight）会产生系统性偏暗的图像，其平均亮度<30属于正常情况。应先建立合格样本的基准线，再标记相对于该基准线的异常值。
帧匹配度：测试图像与基准图像应显示同一区域，且缩放比例和方向一致。帧不匹配（如广角与特写）表明基准流水线存在错误。
缺陷可见性：您能否分辨测试图像与基准图像的差异？有些缺陷在任何分辨率下都很明显；有些缺陷在缩小到模型输入尺寸后可能会变得不可见。对比原始图像尺寸与模型输入尺寸，评估信息损失情况。

Investigation Flow

调查流程

The investigation has 5 phases. Phase 1 (numbers) gives you hypotheses. Phase 2 (images) proves or disproves them. Phase 3 (cross-dimensional) finds hidden patterns. Phase 4 (config) explains the mechanism. Phase 5 (counterfactual) quantifies fixes. Phase 2 is the core — spend the most effort there. Phase 5 is the most actionable — never skip it.

Phase 1 — Score Analysis: score statistics + tier classification, 200-point threshold sweep, per-defect-type table, KPI verdict, and drop-N threshold-critical analysis. Establishes hypotheses.
Phase 2 — Deep Image Investigation (core): threshold-critical sample deep dive (2A), systematic golden image audit and failure mode clustering (2B), false positive deep dive (2C), comparative visual analysis (2D), and label semantics & visual pattern alignment audit (2E). Includes the image path construction rules.
Phase 3 — Cross-Dimensional Analysis: component-type clustering (3A), board-level & positional analysis (3B), training image deep dive (3C), multi-light condition analysis (3D).
Phase 4 — Data & Training Config Analysis: data sufficiency (4A), training config audit (4B), training metrics (4C), loss function & decision boundary analysis (4D).
Phase 5 — Counterfactual & Actionability Analysis: what-if simulations (5A) and minimum viable fix path (5B).

See

references/phases.md

for the full step-by-step procedure of every phase and sub-phase, including all commands, scripts, thresholds, numeric values, image path construction rules, severity guidance, and required report outputs. Execute every step exactly as specified there.

调查分为5个阶段。阶段1（数值分析）提出假设。阶段2（图像分析）验证或推翻假设。阶段3（跨维度分析）发现隐藏模式。阶段4（配置分析）解释机制。阶段5（反事实分析）量化修复效果。阶段2是核心——投入最多精力。阶段5最具可操作性——切勿跳过。

阶段1——分数分析：分数统计+层级分类、200点阈值扫描、按缺陷类型分类的表格、KPI结论，以及对阈值敏感的样本丢弃分析。用于建立假设。
阶段2——深度图像调查（核心）：对阈值敏感样本的深度剖析（2A）、系统性基准图像审核与失效模式聚类（2B）、假阳性深度分析（2C）、对比视觉分析（2D），以及标签语义与视觉模式一致性审核（2E）。包含图像路径构建规则。
阶段3——跨维度分析：组件类型聚类（3A）、板级与位置分析（3B）、训练图像深度剖析（3C）、多光照条件分析（3D）。
阶段4——数据与训练配置分析：数据充足性（4A）、训练配置审核（4B）、训练指标（4C）、损失函数与决策边界分析（4D）。
阶段5——反事实与可操作性分析：假设模拟（5A）和最小可行修复路径（5B）。

详见

references/phases.md

，其中包含每个阶段和子阶段的完整分步流程，包括所有命令、脚本、阈值、数值、图像路径构建规则、严重性指南和所需报告输出。严格按照其中指定的步骤执行。

Parallelization Strategy (USE SUBAGENTS)

并行化策略（使用子Agent）

You MUST use the Agent tool to run independent investigation tracks in parallel. Run Phase 1 yourself in the main thread, then launch 6 subagents (Agents A–F) simultaneously for Phase 2–4 tracks, collect and synthesize their findings (paying special attention to exploratory Agents E and F), run Phase 5 yourself, and write the report. The report-writing step enforces a mandatory Image Embedding Protocol — every visual evidence table row must carry inline thumbnail columns or the hook will reject the report.

See

references/parallelization.md

for the complete execution plan: the exact Phase 1 outputs to save, the per-agent checklists and inputs for Agents A–F, the synthesis cross-checks, the full mandatory Image Embedding Protocol with per-section rules and table format, the exploratory findings section, and the subagent prompt template including the required Thumbnail Map return format. Follow it exactly.

您必须使用Agent工具并行运行独立的调查任务。在主线程中自行执行阶段1，然后同时启动6个子Agent（Agent A–F）处理阶段2–4的任务，收集并综合它们的发现（特别关注探索性Agent E和F），自行执行阶段5，然后撰写报告。报告撰写步骤强制要求图像嵌入协议——每个视觉证据表格行必须包含内嵌缩略图列，否则钩子会拒绝该报告。

详见

references/parallelization.md

中的完整执行计划：阶段1需保存的精确输出、Agent A–F的每个Agent的检查清单和输入、综合交叉检查、完整的强制图像嵌入协议（含各部分规则和表格格式）、探索性发现部分，以及包含所需缩略图映射返回格式的子Agent提示模板。严格按照该计划执行。

Architecture Reference

架构参考

Learnable module:
```
softmax(model(img1, img2), dim=1)[:, 1]
```
→ score = P(defect). Higher = more defective.
Euclidean module:
```
F.pairwise_distance(embed1, embed2)
```
→ score = distance. Higher = more different.
WeightedRandomSampler:
```
fail_wt = (num_pass / num_fail) * fpratio_sampling
```
. Defects sampled at fail_wt:1 rate.

Image paths:

{images_dir}/{input_path}/{object_name}_{light_condition}.{ext}

LR linear:
```
lr * (1.0 - epoch / (num_epochs + 1))
```

Data loading:

SiameseNetworkTRIDataset

for

num_golden=1

MultiGoldenDataset

for

num_golden>1

可学习模块：
```
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

Report Structure

报告结构

Produce

RCA_Report.md

with 9 top-level sections: (1) Verdict, (2) Score Analysis, (3) Visual Evidence (with inline thumbnails throughout), (4) Cross-Dimensional Analysis, (5) Data Issues, (6) Training Config Issues, (7) Exploratory Findings, (8) Counterfactual Impact Analysis, and (9) Recommended Fixes (prioritized by impact × feasibility). Visual Evidence tables must embed thumbnails generated into

rca_images/

See

references/report-structure.md

for the complete report skeleton with every section, subsection, table column layout, and inline-thumbnail requirement. Match it exactly.

生成

RCA_Report.md

，包含9个顶级章节：(1) 结论、(2) 分数分析、(3) 视觉证据（全程内嵌缩略图）、(4) 跨维度分析、(5) 数据问题、(6) 训练配置问题、(7) 探索性发现、(8) 反事实影响分析、(9) 推荐修复方案（按影响×可行性排序）。视觉证据表格必须嵌入生成到

rca_images/

中的缩略图。

详见

references/report-structure.md

中的完整报告框架，包含每个章节、子章节、表格列布局和内嵌缩略图要求。严格匹配该框架。

Output Location

输出位置

Always save into a timestamped folder under

<experiment_result_dir>/rca_results/YYYY-MM-DD_HHMMSS/

containing

RCA_Report.md

, the

rca_images/

thumbnail folder, the hook-populated

rca_config/

, and

claude_session.jsonl

. Get the real timestamp by running

date +%Y-%m-%d_%H%M%S

in Bash — never hardcode or guess it.

See

references/output-and-deliverable.md

for the full directory tree and the exact ordered steps for creating the folder, writing thumbnails, and writing the report (which triggers the packaging hook). If the user specifies a custom path, use that instead but maintain the same structure.

始终将内容保存到

<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

中的完整目录树和创建文件夹、写入缩略图、撰写报告（触发打包钩子）的精确分步流程。如果用户指定自定义路径，则使用该路径，但需保持相同结构。