tao-run-deft-aoi

技能：tao-run-deft-aoi

何时使用此技能

当用户希望 Agent 为 NVIDIA TAO VisualChangeNet / ChangeNet PCB 检测模型运行完整的 DEFT AOI 改进循环时，使用此技能：基线评估、RCA、摄取预生成的合成缺陷、数据挖掘、重新训练，以及持续进行部署准入检查，直至达到 KPI 目标。在此 EA 变体中，不会内联运行 AnomalyGen——客户会在其他流程中预生成 NG/OK 图像对，并将其放在 <workspace>/augmentation/anomalygen/ 下。

• “运行 DEFT 循环”
• “微调，直到 FAR < 0.1%，且 recall=100%”
• “使用 RCA 和合成缺陷改进我的 AOI ChangeNet 模型”
• “迭代训练，直到误接受率达到目标”

单独运行 TAO 训练、一次性推理、通用异常生成或仅进行 RCA 分析时，不要使用此技能。如果用户只要求其中某个步骤，请直接使用相应的 Agent。

基础模型

此循环使用 NVIDIA TAO Visual ChangeNet classify 和 NVIDIA C-RADIOv2-B 主干网络，并进行端到端微调。架构定义在 specs/baseline_spec.yaml 中——该文件是权威依据。所有预训练权重均来自 HuggingFace（需要 HF_TOKEN）；NGC_API_KEY_* 仅用于控制容器拉取权限。ChangeNet 主干网络的解析以及 model.backbone.pretrained_backbone_path 的暂存文件 / HF URL 回退逻辑由 references/visual-changenet.md 负责。用于 k-NN 挖掘的 SigLIP 由 references/tao-mine-aoi-images.md 负责。此 EA 变体不需要 AnomalyGen 侧的检查点——预生成的合成图像对会直接从 <workspace>/augmentation/anomalygen/{reconstructed_image,original_image}/ 摄取；请参阅 references/pipeline.md 中的 Pipeline 第 3 步。

训练 AutoML 策略

DEFT AOI 负责迭代式数据改进循环、重新训练节奏和 KPI 检查点选择。仅对此工作流而言，即使底层 Visual ChangeNet 模型元数据设置了 automl_enabled: true，也要绕过模型级 AutoML。调用每个 Visual ChangeNet 训练阶段（包括基线训练和迭代重新训练）时，都要使用运行覆盖项 automl_policy: off / 普通训练。此覆盖仅适用于工作流级别；不要更改模型元数据，也不要将此策略应用于其他工作流。

启动信息收集

用户确认要运行此工作流后，询问他们打算在哪个受支持的平台上运行。使用以下命令生成平台选项：

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} --format text

选择平台后，运行：

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --platform <platform> --format text

只询问与该平台相关的凭证，以及所选工作流所需的模型专属凭证。

Agent 行为

**用户只需在一个环节确认：运行前确认。打印运行前摘要（请参阅 references/pre-flight.md 中的 运行前摘要），然后停止并等待用户输入“go”、“yes”、“looks good”或类似的明确批准。在获得批准之前，不得启动任何会产生副作用的步骤（docker run、训练、SDG、修改 ${RESULTS_DIR}/ 下的内容）——读取规格、列出文件、运行 docker image inspect 和填写摘要表格均可。“自主”指的是通过此确认后，而不是确认之前的行为。**即使用户最初的请求听起来很紧急（“直接运行”、“继续”），也不要跳过此环节——摘要本身就是用户批准前需要查看的内容。

**通过确认后，此技能将完全自主运行。**无需再次征求确认，即可运行完整循环。步骤之间不要暂停，也不要询问“要我继续吗？”——直接继续。只有在某一步因不可恢复的错误而失败，或触发硬性停止条件时，才停止。在每个步骤里程碑处打印一行状态更新，让用户了解进度。

工作流

按以下顺序执行循环。各步骤的完整详情见对应引用文件。

1. 预检。 执行 references/pre-flight.md 中的所有检查。解析工作区、规格文件、CSV、检查点和容器镜像，仅暂存一次预生成池，并打印预检摘要。缺少任何输入时立即停止。
2. 基线。 如果 deft_state.json 中已有 iterations.baseline.stage_completed == "train"，且 best_ckpt_path 指向一个现存文件（上游 tao-run-automl-deft-pipeline 会在其第 1 阶段 AutoML 获胜者的第 1 阶段 → 第 2 阶段交接中预先写入这些内容），则跳过 train 子步骤，从 inference -> evaluate 开始，使用预先写入的检查点继续执行。否则，调用 tao-skill-bank:tao-train-visual-changenet 技能，执行 train -> inference -> evaluate。无论哪种情况，之后都调用 tao-skill-bank:tao-analyze-gaps-visual-changenet 执行 rca。首先阅读 references/visual-changenet.md 和 references/tao-analyze-gaps-visual-changenet.md，了解 DEFT 循环专用参数（挂载、输出目录、deft_state.json 更新）。
3. 迭代。 对每次迭代（最多 max_iterations 次），执行 references/pipeline.md 中的流水线步骤 1–7。每个步骤之间都要从磁盘重新读取 results/loop_log.jsonl 尾部内容和 results/deft_state.json——磁盘数据是权威来源。
4. 停止。 KPI 目标达成、达到 max_iterations 或触发硬停止条件（静默丢弃、AMP 分配不匹配、训练集/验证集泄漏）时停止。绝不自动重试硬停止情况。
5. 渲染。 每次迭代完成后（并在循环结束时再渲染一次），通过启动 reporter 子 Agent（agents/reporter.md）生成 results/DEFT_Loop_Report.html。不进行分阶段渲染——每个阶段都会向 loop_log.jsonl 追加一行，足以让监视日志尾部的用户了解进度；HTML 渲染包含一次迭代的状态，每次迭代渲染一次可使每个循环的令牌成本大致随迭代次数线性增长，而非随阶段数增长。不要内联渲染。

所有流水线阶段都在父上下文中内联运行——父上下文通过 Skill 工具直接调用底层 tao-skill-bank:* 技能，并通过对应的 references/*.md 文件叠加 DEFT 循环约定。唯一委派的工作是 HTML 报告渲染，由 reporter 子 Agent 在全新上下文中处理，确保循环结束时即使父上下文已饱和，也不会悄然遗漏最终渲染。

默认值

仅当用户未提供时才设置；不要询问有默认值的参数。完整列表见 references/pre-flight.md。

• max_iterations：3 — top_k_per_target：5 — min_similarity：0.9（余弦截断值）
• training_epochs：specs/baseline_spec.yaml 中的 num_epochs，否则为 20
• 工作区根目录：用户提示词指定的目录，否则为 ~/workspace

参考文档索引

参考文档	负责内容
references/pre-flight.md	Pre-Flight 检查 1-11、完整默认值列表、Pre-Flight Summary 模板和唯一的用户确认关卡。工作区/spec/CSV/checkpoint/image 解析、.env + versions.yaml 凭据解析、GPU 内存检查（48GB 时 batch_size ≤ 16 / 24GB 时 ≤ 8）、一次性预生成暂存、数据泄漏检查。
references/pipeline.md	Pipeline 步骤 1-7 + Augmentation Pool。RCA → 路由（预生成单一分桶、提升所有缺失项，filter_by_label: false，不进行 AG 扇出）→ 读取缓存清单 → k-NN 挖掘（top_k_per_target、min_similarity 0.9、不绕过 SDG）→ 组装 CSV → 验证 → 微调（automl_policy: off）。源池组装、每轮挖掘边界、14 列 / 4 个必需列的 CSV 架构、基线跳过训练逻辑。
references/stage-execution.md	可用脚本表、阶段参考模块（阶段→技能映射）、路径规则不变量、SKILL/INLINE/AGENT 阶段类型、阶段后检查、报告产物、agents/reporter.md 启动约定。
references/state-logging.md	deft_state.json + loop_log.jsonl 约定、每个阶段一条记录、从磁盘读取 seq = last_seq + 1（磁盘是规范来源，绝不使用 echo/内联 jq）、每轮 + 循环结束时的渲染时机、循环结束时的顺序（log_stage → align_token_usage → 渲染 → prepare_inference_spec）、停止条件。
references/prepare-for-inference.md	best_model.json + best_model_inference_spec.yaml 约定和使用方工作流。
references/REPORT_RENDERING.md	agents/reporter.md 遵循的模板填充规则。
references/SCRIPT_USAGE.md	run_script() 与直接调用 python 的区别、绝对路径解析。

每个阶段开始时阅读相关参考文档，然后执行。如果参考文件缺失，请停止并要求用户重新安装插件——不要使用通用 shell 命令替代。

数据约定

输入（除绝对路径外，所有路径均位于 <workspace> 下）：

<workspace>/
├── .env                                     # NGC_API_KEY (nvcr.io/* image pulls), HF_TOKEN (HuggingFace pre-flight pulls). No AnomalyGen credentials required — this EA variant ingests pre-generated pairs.
├── specs/baseline_spec.yaml                 # ChangeNet train/eval spec
├── train/base/
│   ├── training_set.csv                     # seed training rows; ChangeNet 14-column siamese schema
│   └── validation_set.csv                   # held-out rows; checked for leakage against every train CSV
├── kpi/
│   ├── images/                              # KPI test images (real data only — no generated images here)
│   └── testing_set.csv                      # labels live in the CSV
├── augmentation/
│   ├── mining_pool/
│   │   ├── mining_pool.csv                  # append-only production-line samples; paths relative to this dir
│   │   └── images/                          # source images referenced by mining_pool.csv (e.g. *_SolderLight.jpg)
│   └── anomalygen/                          # customer-supplied pre-generated synthetic pairs (this EA variant does not run AnomalyGen)
│       ├── reconstructed_image/             # NG images (will become ChangeNet input_path); flat dir of *.jpg or *.png
│       ├── original_image/                  # OK partner images, same stems as reconstructed_image/ (will become ChangeNet golden_path)
│       └── defect_spec.jsonl                # OPTIONAL — one entry per defect_type if defect-type accounting is wanted in deft_state.json
│                                            # Stems in reconstructed_image/ and original_image/ must match 1-to-1; extensions may differ.
└── results/run_<YYYYMMDD_HHMMSS>/           # created/resumed by this workflow (= ${RESULTS_DIR})

ChangeNet CSV 架构（VCN）。 必需列：input_path、golden_path、label、object_name（孪生变化检测器——没有 golden_path 的行不可用）。存在时保留 boardname、分数和来源字段。TAO 按 {images_dir}/{input_path}/{object_name}_{light}{image_ext} 构建完整图像路径——input_path 是目录，不是文件。

输出布局

相对于 <workspace>：

results/run_<YYYYMMDD_HHMMSS>/               # = ${RESULTS_DIR}
├── deft_state.json                          # current resume snapshot (schema: references/deft_state.json)
├── loop_log.jsonl                           # append-only stage log; single source of truth
├── DEFT_Loop_Report.html                    # re-rendered after every stage by agents/reporter.md
├── best_model.json                          # inference handoff metadata (see references/prepare-for-inference.md)
├── best_model_inference_spec.yaml           # ready-to-run TAO inference spec built from training config
├── iter${ITER}_summary.md                   # ≤300-word per-iteration summary
├── synth_pool/                              # built ONCE at Pre-Flight step 10 via scripts/prestage_pregen.py
│   ├── manifest.json                        # paths + counts for the loop to reference
│   ├── images/synth_{ng,ok}/                # ChangeNet-staged pre-gen pairs (single copy, shared across iters)
│   ├── sdg_rows.csv                         # 14-col + provenance + filepath; the SDG half of source_pool
│   ├── source_pool.{csv,parquet}            # real (mining_pool) + sdg unified pool with provenance
│   ├── source_embeddings.parquet            # written only when --embed-with-siglip was passed to prestage_pregen.py
│   └── source_embed.log                     # data-services log for the source embedding (if run)
├── baseline/
│   ├── train/                               # TAO train output: model_epoch_<EEE>_step_<SSS>.pth × N, status.json, experiment.yaml, train.log
│   ├── inference/{best_val,latest}/         # per-checkpoint inference.csv + KPI plots from scripts/analyze_kpi.py
│   └── rca_results/<TS>/                    # kpi_gaps.parquet, threshold.txt, weak_samples_breakdown.txt
└── iter${ITER}/
    ├── routing_results/<TS>/                # mining_gaps.parquet, anomalygen_gaps.parquet, routing_summary.txt
    ├── anomalygen/                          # per-iter bookkeeping (just records the synth_pool/manifest.json path)
    │   └── ingest_summary.json              # per-iter audit: which synth_pool manifest was reused, counts at iter start
    ├── mining_filter/
    │   ├── mining_pool.csv                  # top-K-per-target k-NN survivors from synth_pool/source_pool (synth + real subject to same filter)
    │   ├── knn_summary.csv                  # candidate_count, kept_count, rejected_count, similarity_threshold=0.9
    │   ├── target_embeddings.parquet        # embeddings of weak-target images (per-iter — targets change each iter)
    │   └── mining_summary.txt               # per-label breakdown emitted by mining container
    ├── dataset/
    │   ├── train_combined_iter${ITER}.csv
    │   └── train_combined_iter${ITER}_provenance.csv  # source ∈ {base_train, previous_iter_train, mining_pool}
    ├── train/                               # TAO train output for iter${ITER}
    ├── inference/{best_val,latest}/
    └── rca_results/<TS>/                    # next iteration's RCA reads inference/{best_val|latest}/inference.csv

之前的合并 CSV 中已经包含所有先前贡献的行——组装第 N+1 轮时，应使用 train_combined_iter${N}.csv 加上新的 mining_filter/mining_pool.csv，而不是再次使用 train/base/training_set.csv。

安全与确认关卡

• 唯一的用户确认关卡。 references/pre-flight.md 中的 Pre-Flight Summary 是唯一的确认点。在执行任何有副作用的步骤前停止并等待用户明确批准；批准后自主执行。
• 路径规则。 每个阶段都将绝对主机路径写入 ${RESULTS_DIR}/iter${ITER}/ 下；拒绝任何包含 output: /results/... 或指向 <workspace> 之外路径的配置。参见 references/stage-execution.md 中的 Invariants。
• 磁盘是规范来源。 每个阶段开始前重新读取 loop_log.jsonl 末尾内容 + deft_state.json；每个阶段通过 scripts/log_stage.py 恰好追加一条 loop_log.jsonl 记录（绝不使用 echo/内联 jq）。参见 references/state-logging.md。
• 硬性停止，不得自动重试： 预生成目录缺失/为空/不成对、mining_pool.csv 缺失或行数为零、运行期间预生成数据发生变动、训练/验证数据泄漏（轮次中及组装后检查）、静默丢弃、AMP 分配不匹配、CSV 验证失败、参考文件缺失。
• 不得绕过 SDG。 合成行与真实行使用相同的 k-NN 流程；此 EA 变体中的循环绝不会启动 SDG/AnomalyGen 容器。