tao-analyze-gaps-visual-changenet

TAO VCN Classify 间隙分析技能

你是一名负责分析 NVIDIA TAO VCN Classify（Visual Component Net）推理结果的分析师。你的工作是通过测量样本沿错误方向偏离决策阈值的有符号距离，找出每个真实标签中最弱的样本，以便后续进行数据增强或重新标注。

此技能刻意保持轻量。VCN 的分类头是单分数二分类边界（通过 siamese_score 区分 PASS 与 NO_PASS），因此这是一项计算任务，而非调查任务。所有计算都通过一次直接的 docker run 调用完成，使用 versions.yaml 中声明的 tao_toolkit.data_services 镜像（运行时解析——见 Setup）。容器入口点接受 <category> <action> [hydra overrides...]；我们传入 gap_analysis vcn_aoi key=value …。不需要子 Agent、多阶段图像审核或组件类型聚类——VCN 不会公开这些维度。容器返回后，只需查看少量具有代表性的弱样本，以判断间隙情况。

不同版本的数据服务容器可能会改变 CLI 接口。如果 gap_analysis vcn_aoi 调用因参数解析失败，请使用 docker run --rm "$DS_IMAGE" gap_analysis vcn_aoi --cfg=job，针对每个镜像检查一次实际架构，并在重试前处理已重命名的键。有关键重命名处理方法和完整的注意事项列表，请参阅 references/troubleshooting.md。输出的 parquet 文件名为 kpi_gaps.parquet。

---

输入

1. 实验结果目录——包含 inference/inference.csv（必需列：input_path、object_name、label、siamese_score）。传入目录（例如 inference/latest/），而不是 CSV 文件。
2. 训练代码/配置目录——包含 VCN 训练 YAML；容器会读取 dataset.classify.input_map 和 dataset.classify.image_ext，用于按光照条件扩展样本。
3. 数据集目录——图像根目录（kpi_media_path），会拼接到每行相对路径 input_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 样本。

有关完整的输入详情、GapAnalysisConfig 覆盖项语义以及各默认值的说明，请参阅 references/parameters-and-artifacts.md。

---

设置

阈值扫描、薄弱项排名和按光照条件扩展都在 versions.yaml 中声明的 tao_toolkit.data_services 镜像内运行。在运行开始时解析一次具体 URI，然后确认 Docker、NVIDIA 容器工具包和 GPU 均已就绪，并确保镜像已缓存：

# Resolve tao_toolkit.data_services → concrete nvcr.io/... URI from versions.yaml
DS_IMAGE=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['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"

插件的 session_start 钩子会导出 TAO_SKILL_BANK_PATH。如果该变量未设置（例如，在 Claude Code 插件之外运行），请在解析之前将其指向 skill-bank 仓库根目录。

此流程需要 GPU（AOI 循环使用相同的镜像，其他操作也假设 CUDA 可用）。在没有 GPU 的主机上提前中止，可以避免稍后出现令人困惑的错误。

路径挂载。 容器读取或写入的每个主机路径——inference.csv、训练 YAML、数据集图像根目录和输出目录——都必须绑定挂载。最简单的方式是挂载工作区根目录，并让容器内外的路径完全相同，这样参数中的绝对路径在两侧都能解析到同一位置：

WORKSPACE=<absolute path that contains inference.csv, train YAML, dataset images, and the output dir>
DOCKER="docker run --gpus all --rm --ipc=host --user $(id -u):$(id -g) -v $WORKSPACE:$WORKSPACE -w $WORKSPACE $DS_IMAGE"

如果 inference.csv、训练 YAML 和数据集图像位于不同根目录，请传入多个 -v 标志，但参数中传入的每个绝对路径都必须能在容器内解析。

CLI 覆盖可满足常见需求。 min_recall、top_k_per_label 和可选的 threshold 通过命令行上的 Hydra 覆盖项传入；容器中内置的默认值（min_recall=1.0、top_k_per_label=50、用于扫描的 threshold=-1.0）适用于大多数运行。如果容器还接受通过 -e <spec> 传入的规格文件（请通过 --cfg=job 确认），传入规格文件只是为了方便，并非必需——只覆盖需要的项即可。

---

方法

整个技能只需调用一次 docker run，然后进行一次简短的目视抽查。容器会在内部执行步骤 1–4（阈值扫描、薄弱项评分、Top-K 选择、按光照条件扩展）。你需要直接使用 Read 工具处理步骤 5（目视抽查）。

步骤 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。 这个参数会将容器从默认的“低于阈值的样本”筛选切换为正确的按标签 Top-K 排序。当 min_recall=1.0 时，按构造方式，阈值小于或等于每个 NO_PASS 分数，因此低于阈值筛选只会返回分类错误的 PASS 行，不会返回任何 NO_PASS 行——无法用于构建增强队列。将 top_k_per_label 设为正整数（可在规范中设置，也可通过 Hydra 覆盖设置）后，容器会针对每一行计算相对于阈值的有符号弱度，并按真实标签分别列出最弱的 K 个样本，这是下游步骤使用的按标签排序结果。

容器会遍历每个唯一的 siamese_score（以及一个略低于最小值的值），保留 NO_PASS 召回率 ≥ min_recall（容差 1e-12）的候选项，选出 F1 最高的阈值（平局时依次以精确率、阈值大小作为判定依据），计算每行的有符号弱度，按真实标签取前 top_k_per_label 个样本，并将每个样本扩展为每种光照各一行。准确的计算方式、覆盖默认值和产物表格，请参阅 references/parameters-and-artifacts.md。

如果没有候选阈值满足召回率目标，容器会以非零状态退出，并在 results_dir 中写入 unreachable_kpi.txt，说明模型实际能够达到的召回率。在这种情况下，Docker 调用后就停止分析，编写一节报告，说明模型在任何工作点都无法达到 KPI，并建议重新训练或重新标注——跳过视觉抽查。

容器会在 results_dir 中写入： kpi_gaps.parquet（每个标签中最弱的 Top-K，按光照扩展；列为 filepath、label、siamese_score、weakness）、threshold.txt、metrics.json、weak_samples_breakdown.txt，以及 unreachable_kpi.txt（仅在无法达到召回率目标时）。各产物的具体内容请参阅 references/parameters-and-artifacts.md。将容器的 stdout 摘要（选定的阈值、保留行数、按标签细分）输出到你自己的 stdout，以便脚本检查钩子确认本次运行有输出。

步骤 5 — 视觉抽查（少量、固定）

如果 results_dir 中存在 unreachable_kpi.txt，请跳过此步骤——模型在任何阈值下都无法达到 KPI，因此没有值得抽查的内容。

否则，使用 Read 工具查看以下测试图像：

• 最弱的 5 个 PASS 样本（“PASS 被误分类为 NO_PASS”样本堆的顶部）——筛选 kpi_gaps.parquet 中 label == 'PASS' 的行，按 weakness 降序排列后选取。
• 最弱的 5 个 NO_PASS 样本（“NO_PASS 被误分类为 PASS”样本堆的顶部）——同样操作，但使用 label != 'PASS'。

kpi_gaps.parquet 已按光照扩展（每个样本有多行）。进行抽查时，按 (input_path, object_name) 去重，每组只保留一行——选择 filepath 使用训练 YAML 中第一种光照的行（每个样本查看一张图像即可；VCN 的分类头会将所有光照图像堆叠处理，但人工抽查时一张图像就有代表性）。

将每个查看过的样本准确分类为以下类别之一：

• 错标 — 视觉内容与 CSV 标签不符
• 边界情况 — 确实存在歧义的边界样本
• 数据质量问题 — 图像损坏、过暗、裁剪错误或构图不佳
• 系统性问题 — 模型学到了错误特征（图像看起来“明显是 PASS/NO_PASS”，但模型的判断与之不符）

将每张已查看的图像复制到 <results_dir>/rca_images/ 中（如果 PIL 可用，则调整为 128×128；否则直接复制），以便在报告中内嵌。

这是唯一需要进行的图像检查。不要查看几十张图像，不要运行故障模式聚类，也不要审核金标图像——VCN 没有金标图像。

---

参考调用

完整的复制并编辑端到端操作步骤（工作区、四个路径、两个数值参数、写入规格文件、运行 docker，以及用于呈现脚本检查钩子行数的 stdout 健全性打印）位于 references/recipe.md。请原样使用，仅编辑工作区、路径和参数。

---

输出

将所有内容写入实验结果目录下带时间戳的文件夹：<experiment_result_dir>/rca_results/YYYY-MM-DD_HHMMSS/。容器的输出（kpi_gaps.parquet、threshold.txt、metrics.json、weak_samples_breakdown.txt，以及适用时的 unreachable_kpi.txt）直接写入该目录；视觉抽查会写入 rca_images/；写入 RCA_Report.md 时，打包钩子会自动添加 rca_config/ 和 claude_session.jsonl。完整目录树请参阅 references/parameters-and-artifacts.md。

运行开始时，在 Bash 中运行 date +%Y-%m-%d_%H%M%S，获取实际时间戳。请勿硬编码或猜测。如果用户指定了自定义输出路径，请改用该路径，但保持相同的内部结构。

---

常见问题

影响最大的问题是当 min_recall=1.0 时忘记设置 top_k_per_label——在该召回率下，选定的阈值不高于任何 NO_PASS 分数，因此阈值以下的回退筛选条件只会匹配误分类的 PASS 行，导致 kpi_gaps.parquet 中没有 NO_PASS 行。务必设置一个明确的正数 top_k_per_label。完整的问题列表（规格文件位于 $WORKSPACE 之外、未解决的 ??? 哨兵值、错误或尚未拉取的镜像标签、路径挂载不匹配、unreachable_kpi.txt 的处理、inference.csv 缺少列、训练 YAML 缺少键、kpi_media_path 前缀不匹配、容器内没有 GPU），以及 CLI 变更的协调处理方法，见 references/troubleshooting.md。

---

报告结构

将 RCA 报告写入带时间戳的输出文件夹。这是一份包含 7 个部分的计算差距分析（判定、阈值选择、弱点分布、最弱的 Top-K 样本、视觉抽查、逐标签细分、建议措施），共 1000–1800 个词；混淆矩阵和逐标签表格的数据取自 metrics.json，抽查行的数据取自 kpi_gaps.parquet。如果存在 unreachable_kpi.txt，则用一个简短部分引用该文件，并将第 3–6 部分替换掉；第 7 部分则精简为一条重新训练或重新标注的建议。完整的报告骨架（包含每个部分标题、表格布局和不可达 KPI 变体）请参阅 references/rca-report-structure.md。

---

执行顺序

1. 从 versions.yaml（images.tao_toolkit.data_services）解析 DS_IMAGE，然后运行 docker info、nvidia-smi 和 docker image inspect "$DS_IMAGE"（如果镜像缺失则拉取）一次，以确认环境。若任何命令失败，请给出明确消息并中止。
2. 运行 date +%Y-%m-%d_%H%M%S 获取时间戳；创建 <experiment_result_dir>/rca_results/<timestamp>/。
3. 在带时间戳的目录中写入 vcn_aoi_spec.yaml，并填写 min_recall 和 top_k_per_label。将文件放在 $WORKSPACE 下，以便 -e 路径在容器内可解析。
4. 运行 docker run … "$DS_IMAGE" gap_analysis vcn_aoi -e vcn_aoi_spec.yaml inference_results_dir=… train_config=… kpi_media_path=… output_dir=…。容器会将 kpi_gaps.parquet、threshold.txt、metrics.json、weak_samples_breakdown.txt 写入 results_dir。将选定阈值和保留行数打印到 stdout，以便脚本检查钩子验证运行是否产出了输出。
5. 如果存在 unreachable_kpi.txt，请跳过步骤 6 并编写精简版报告。否则继续。
6. 从 kpi_gaps.parquet 中选取 10 个弱样本（5 个最弱的 PASS + 5 个最弱的 NO_PASS），使用 Read 查看每张测试图像、进行分类，并将每张图像复制到 rca_images/。
7. 最后写入 RCA_Report.md——写入该文件会触发打包钩子，将会话日志和技能配置一并复制到旁边。