Name: paidf-anomalygenSkill
Rating: 5 (1 reviews)
Author: paidf-anomalygen


名称	paidf-anomalygen
开源协议	Apache-2.0 compatibility: Requires docker + nvidia-container-toolkit and a CUDA GPU. Pulls the `metropolis_sdg.paidf_anomalygen` image declared in `versions.yaml` at the skill bank root. metadata:
作者	NVIDIA Corporation
版本	“0.1.0” allowed-tools: Read Bash
描述	>- 完整的 PAIDF AnomalyGen 流水线 —— 在新的异常数据集上进行微调，生成合成异常图像 (SDG)，评估质量 (nn_score)，并搜索每个样本的 (guidance, crop_ratio) 参数。三种模式：full（阶段 0→7：先微调再生成），finetune_only（阶段 0→1：仅训练），inference_only（阶段 0, 2→7：从已有检查点生成）。当用户要求“微调 AnomalyGen”、“生成异常图像”、“运行 PAIDF SDG”、“评估 SDG 输出质量”、“运行逐样本搜索”，或运行 AnomalyGen 流水线的任意部分（即使用户只提到一个阶段）时使用。 tags: - tao - data

PAIDF AnomalyGen

独立安装？ 如果本会话未经 TAO 技能银行插件初始化，请先运行 tao-setup 技能（主机预检、凭据、跨技能发现）。

多阶段流水线（0-7）；mode 标志选择要运行的阶段。

阶段	执行内容	模式
0	验证/下载预训练检查点	all
1	在 `dataset_dir` 上微调	`full`, `finetune_only`
2	准备推理 JSONL（AMP 路由）	`full`, `inference_only`
3	SDG — 生成合成异常图像 → `original/`	`full`, `inference_only`
4	评估 `original/` — 输出 `per_sample.csv` + `eval.log`，将 `nn_score` 合并到 `SDG_result.csv`	`full`, `inference_only`
5	逐样本 `(guidance, crop_ratio)` 搜索轮次 → `rounds/round_NN/`（每轮执行 SDG 和评估）	`full`, `inference_only`
6	将各轮最佳结果组装到 `searched/`（仅拼接），并生成 `rounds/search_summary.csv`	`full`, `inference_only`
7	按 `nn_threshold`（默认 `0.4`）过滤 `searched/`，重新生成被丢弃的样本，然后进行标准桶评估 → `searched/{per_sample.csv, eval.log}`	`full`, `inference_only`

所有阶段连续运行至完成，不要中途暂停。提前收集所有必需的参数，并从仓库根目录运行所有命令。

Shell 设置。 所有 ${ANOMALYGEN_SCRIPTS} 引用解析到打包的辅助脚本目录。在容器内该目录已预设（ENV ANOMALYGEN_SCRIPTS=<dir>/scripts/utilities）；在主机上，请为每个 shell 导出一次：

export ANOMALYGEN_SCRIPTS="$(git rev-parse --show-toplevel)/scripts/utilities"

python3 -m scripts.utilities.<name> 调用可在容器内的任何工作目录（PYTHONPATH 已预设）以及主机上的仓库根目录下运行。当处于产品容器内（ANOMALYGEN_PRODUCT_MODE=1）时，在 GPU 工作之前运行 anomalygen-guard；若报告 BLOCKED，修复所列问题后再继续。

快速开始

流水线在 metropolis_sdg.paidf_anomalygen 容器内运行（在 versions.yaml 中声明），或在激活了 cosmos-predict2 conda 环境的任意主机上运行。所有阶段命令都假定在仓库根目录、该环境中、并已导出 ANOMALYGEN_SCRIPTS。

最小端到端运行（mode=full）：

# 1. 设置共享变量（完整集合请参见“共享变量”）。
export ANOMALYGEN_SCRIPTS="$(git rev-parse --show-toplevel)/scripts/utilities"
MODE=full
NAME=my_exp
DATASET_DIR=/data/uc1
DEFECT_DESC=assets/defect_spec_template.jsonl
NUM_SDG=20
MODEL_SIZE=2b

# 2. 阶段 0 — 验证/下载检查点（约 140 GB；需要 HF_TOKEN）。
${ANOMALYGEN_SCRIPTS}/check.sh || ${ANOMALYGEN_SCRIPTS}/download_checkpoints.sh

# 3. 按顺序执行阶段 1→7（参见各阶段节）。

对于 mode=inference_only（复用检查点），还需要设置 CKPT/STEP 并跳过阶段 1。对于 mode=finetune_only，仅运行阶段 0–1。

在 Docker 中运行 — 容器启动、挂载与权限

paidf-anomalygen 镜像以非 root 内置用户（USER anomalygen，uid=10000）运行，这与你的主机 uid 无关。Docker 不会重新映射绑定挂载的 uid，因此主机上归属于你的 uid 的目录不能被 uid 10000 写入，容器在尝试创建文件时立即失败。请使用 --user "$(id -u):$(id -g)" 并附带必需的 /etc/passwd+/etc/group 和 HOME/缓存重定向伴侣，以你的主机 uid 运行，并在阶段 0 之前运行快速失败写入预检。完整的 docker run 命令、关键标志表、预检片段以及 uid-10000 chown/chmod 回退方法，请参阅 references/docker.md。

参考文件 — 执行阶段前阅读

在阶段 0/1 之前阅读 references/finetune.md，在阶段 2–7 的任何操作之前阅读 references/inference.md；对于 mode=full，开始前阅读两者。剩余参考文件按需阅读——当需要排查问题或特定阶段的完整细节时再阅读。

文件	何时阅读
`references/finetune.md`	阶段 0/1 之前：环境检查、检查点下载、数据集验证、配置生成、训练命令、最佳检查点选择
`references/finetune-commands.md`	阶段 1 步骤 1–4 的精确命令以及 `CKPT`/`STEP` 的推导
`references/inference-commands.md`	阶段 5 `run_round.sh` 和阶段 7 `filter_with_regen` 的精确命令
`references/inference.md`	阶段 2–7 之前：AMP 路由、JSONL 验证、SDG 标志、评估解释、搜索循环、过滤
`references/setup.md`	检查点下载失败；首次设置；HF_TOKEN / 磁盘问题
`references/datasets.md`	用户需要准备或获取 UC1 / UC2 / UC3 数据集；`dataset_dir` 尚不存在
`references/prep-testcase.md`	AMP 失败；需要完整参数表、辅助脚本描述、分配不变量
`references/sdg-inference.md`	NCCL 挂起；检查点验证错误；多 GPU 显存问题；完整步骤列表
`references/eval.md`	意外分数；FID 列顺序混淆；评估输出格式参考
`references/sdg-refine.md`	draws.json 对齐；重新 AMP 启发式；搜索输出布局
`references/guard-and-custom-counts.md`	完整 guard 预检命令；`--per-defect-counts` 示例
`references/docker.md`	容器启动命令、挂载权限标志、写入预检、uid-10000 回退
`references/output-layout.md`	`results/<name>/` 完整目录树及各文件注释；运行后验证清单
`references/error-handling.md`	流水线级故障模式：缺少掩码目录、AMP 输出过短/为空、轮次中途恢复、`step` 越界

必需参数

num_SDG 的分配取决于 prep_testcase.sh --mode：inference（默认，阶段 2）在各缺陷类型间均匀分配，可通过 --per-defect-counts 按缺陷覆盖；validation（阶段 1 的验证 JSONL）与训练掩码计数成比例（最大余数舍入），并强制每个缺陷至少 1 条。完整的模式表见 references/prep-testcase.md。

参数	描述
`mode`	`full`（阶段 0→7）、`inference_only`（跳过阶段 1）或 `finetune_only`（仅阶段 0→1）。
`name`	实验标签。
`dataset_dir`	训练/参考数据集根目录。驱动掩码计数分配、AMP 子掩码模板，并为 `cad` 缺陷保存 `semantic_segmentation_labels.json`。
`defect_spec`	JSONL，将每个缺陷的 `spatial_dependency` 标记为 `free`/`text`/`cad`。`text` 条目需要 `roi_prompt_defect_location`。模板：`assets/defect_spec_template.jsonl`。
`num_SDG`	每个桶的总输出样本数。（当 `mode=finetune_only` 时忽略。）

条件必需参数

参数	何时需要	描述
`checkpoint_dir` / `step`	`mode=inference_only`	预先存在的微调模型。在 `mode=full` 中，阶段 1 之后自动推导；传入它们会报错。在 `mode=finetune_only` 中静默忽略——阶段 1 总是从头训练（不支持从检查点恢复）。两者必须同时存在——只提供一个会报错。

可选参数

参数	默认值	描述
`clean_dir`	`dataset_dir`	干净图像。仅当它们位于训练数据集之外时设置。转发为 prep-testcase 的 `--clean-dir` 和 finetune 的 `--clean-image-path`。
`validation_jsonl`	自动生成	阶段 1 的预构建验证 JSONL。若提供，预检会验证每种 `defect_spec` 类型都出现且路径存在。
`num_search_run`	`3`	阶段 5 的逐样本搜索预算。`0` 跳过搜索（仅 `original/`）。（当 `mode=finetune_only` 时忽略。）
`nn_threshold`	`0.4`	阶段 7 的 `nn_score` 截止值（DINOv2 与真实缺陷的对应度——关键 KPI）。低于此值的样本会被重新生成；最终 `searched/` 总是包含 `num_SDG` 个样本。`0` 禁用过滤。
`max_iter`	`75000`	仅阶段 1。微调总迭代次数。
`save_iter`	`5000`	仅阶段 1。检查点保存间隔。
`validation_iter`	`5000`	仅阶段 1。验证（`nn_score`）日志间隔。
`num_gpus`	`1`	转发到阶段 1（微调）和阶段 3（SDG）。评估和搜索轮次保持单 GPU。
`model_size`	`2b`	`2b` 或 `14b`。用于微调和 SDG。磁盘上的检查点路径以大写编码（`2b`→`2B`，`14b`→`14B`）。
`lr`	`0.02`	仅阶段 1。学习率。
`batch_size`	`2`	仅阶段 1。每 GPU 批大小。
`image_size`	`512`	仅阶段 1。训练分辨率（正方形）。
`guidance_range`	`1.5 10.0`	阶段 5 的 guidance 搜索抽取范围。
`crop_ratio_range`	`1.5 10.0`	阶段 5 的 crop_ratio 搜索抽取范围。

模式验证（在任何阶段之前快速失败）

mode 未设置 → 停止：“mode 是必需的（full | inference_only | finetune_only）。”
mode=inference_only 缺少 checkpoint_dir 或 step 中的任意一个 → 停止：“inference_only 需要同时提供 checkpoint_dir 和 step。”
mode=full 但提供了 checkpoint_dir 或 step → 停止：“full 模式会运行微调；若要复用现有检查点请使用 mode=inference_only。”

共享变量

在阶段 0 之前设置一次：

MODE=<full|inference_only|finetune_only>
NAME=<exp>
DATASET_DIR=<dataset_dir>
CLEAN_DIR=${clean_dir:-${DATASET_DIR}}
CKPT=<checkpoint_dir>      # required iff MODE=inference_only; auto-derived after Phase 1 when MODE=full
STEP=<iter>                # required iff MODE=inference_only; auto-derived after Phase 1 when MODE=full
NUM_SDG=<N>
DEFECT_DESC=<defect_spec.jsonl>
DEFECTS=(T+A T+B)          # TEXTURE+TYPE names. For mode=inference_only, derive from ${CKPT}/ag_config.yaml → dataloader_train.dataset.anomaly_types (also printed by validate_checkpoint.py in Phase 0). For mode=full, take from DEFECT_DESC entries. See references/inference.md §Phase 0.
NUM_SEARCH_RUN=${num_search_run:-3}
NN_THRESHOLD=${nn_threshold:-0.4}
MODEL_SIZE=<2b|14b>
NUM_GPUS=${num_gpus:-1}
MAX_ITER=${max_iter:-75000}
SAVE_ITER=${save_iter:-5000}
VALIDATION_ITER=${validation_iter:-5000}
LR=${lr:-0.02}
BATCH_SIZE=${batch_size:-2}
IMAGE_SIZE=${image_size:-512}
VALIDATION_JSONL=${validation_jsonl:-}  # optional; set by Phase 1 Step 2 if not user-supplied

BASE=results/${NAME}
JSONL=ag_inference/${NAME}/testcase.jsonl
ORIGINAL=${BASE}/original
SEARCHED=${BASE}/searched
ROUNDS=${BASE}/rounds
REGENS=${BASE}/regens

Guard 预检（仅产品模式）

当 ANOMALYGEN_PRODUCT_MODE=1 时，在任何 GPU 工作前运行 .agents/skills/anomalygen-guard/scripts/preflight.py，修复所有 BLOCKED 问题。仅当用户提供了 --validation-jsonl 时才转发该参数；对于 MODE=finetune_only，如果未提供 --num-sdg 则省略。完整的预检命令及所有转发标志、验证 JSONL / allocate_samples.py 0 条目检查，请参阅 references/guard-and-custom-counts.md。

阶段 0 — 检查点

关于 HF_TOKEN 要求和下载内容（约 140 GB），请阅读 references/finetune.md §Phase 0。先验证；仅下载缺失内容。

${ANOMALYGEN_SCRIPTS}/check.sh \
    || ${ANOMALYGEN_SCRIPTS}/download_checkpoints.sh

阶段 1 — 微调（`MODE=inference_only` 时跳过）

关于数据集结构、配置模板细节和最佳检查点选择，请阅读 references/finetune.md §Phase 1。四个步骤：（1）验证数据集/推导异常类型，（2）生成验证 JSONL（如果用户提供了 VALIDATION_JSONL 则跳过），（3）生成训练配置——先展示给用户并确认后再写入——（4）在后台启动训练。然后推导 CKPT（路径编码为大写 MODEL_SIZE）和 STEP（来自验证日志中最高 nn_score 的步骤）。如果 MODE=finetune_only，训练后停止。精确的步骤 1–4 命令和 CKPT/STEP 推导片段，请参阅 references/finetune-commands.md。

阶段 2 — prep-testcase（`MODE=finetune_only` 时跳过）

关于 AMP 路由细节和 n_seeds 大小，请阅读 references/inference.md §Phase 2。不要传递 --seeds——它会自动计算，且不是可识别标志。prep_testcase.sh 默认使用 --mode inference（在各缺陷类型间均匀分配，无 KPI 下限），阶段 2 始终使用该模式。

${ANOMALYGEN_SCRIPTS}/prep_testcase.sh \
    --name ${NAME} --num-sdg ${NUM_SDG} \
    --dataset-dir ${DATASET_DIR} \
    --clean-dir ${CLEAN_DIR} \
    --defect-spec ${DEFECT_DESC} \
    --amp-output-dir ag_inference/${NAME}/amp \
    --output-jsonl ${JSONL}

自定义逐缺陷数量： 当用户指定每个缺陷类型的数量时，转换为 --num-sdg 加上 --per-defect-counts JSON 字典（字典中未出现的类型为 0；总和应等于 --num-sdg，否则脚本在 stderr 上警告并使用覆盖总和）。意图不明确时确认分配。完整的 --per-defect-counts 命令示例和歧义处理细节，请参阅 references/guard-and-custom-counts.md。

阶段 3 — SDG → `original/`

关于针对检查点的 JSONL 验证、多 GPU 注意事项和输出验证，请阅读 references/inference.md §Phase 3。

python3 -m scripts.utilities.validate_checkpoint ${CKPT} --step ${STEP}
python3 -m scripts.utilities.validate_jsonl ${CKPT} ${JSONL}

${ANOMALYGEN_SCRIPTS}/run_sdg.sh \
    --checkpoint_dir ${CKPT} --step ${STEP} \
    --input_jsonl ${JSONL} --output_dir ${ORIGINAL} \
    --model_size ${MODEL_SIZE} --num_gpus ${NUM_GPUS}

${ANOMALYGEN_SCRIPTS}/verify_output.sh ${JSONL} ${ORIGINAL}

阶段 4 — 评估 `original/`

关于评分解释和特征计数说明，请阅读 references/inference.md §Eval。run_eval.sh 在 original/ 内写入 per_sample.csv 和 eval.log，并将 nn_score 合并到 SDG_result.csv。

${ANOMALYGEN_SCRIPTS}/run_eval.sh \
    --real-path ${DATASET_DIR} --generated-path ${ORIGINAL} \
    --anomaly-types ${DEFECTS[@]}

阶段 5 — 逐样本搜索轮次

关于抽取策略、范围和重新 AMP 指导，请阅读 references/inference.md §Phase 5。对于 r 从 1 到 NUM_SEARCH_RUN：

读取上一轮的 per_sample.csv（r=1 时读取 ${ORIGINAL}/per_sample.csv）。
将选定的 (guidance, crop_ratio) 逐样本写入 ${ROUNDS}/round_${r}/draws.json。
通过 ${ANOMALYGEN_SCRIPTS}/run_round.sh 运行该轮（SDG + 评估；该轮目录获得自己的 sdg/{SDG_result.csv, per_sample.csv, eval.log}）。完整命令和标志见 references/inference-commands.md §Phase 5。

NUM_SEARCH_RUN=0 是合法的——完全跳过此阶段，让阶段 6 将 original/ 克隆到 searched/。

阶段 6 — 组装 `searched/`（仅拼接）

始终运行组装（0 轮也能工作——searched/ 克隆 original/，因此无论 num_search_run 如何，下游总是读取 searched/）。仅拼接：将每个样本索引的获胜图像复制到 searched/，并从各来源轮次的 per_sample.csv 中载入逐样本 nn_score / mnn_score。不执行评估——阶段 7 输出规范的 searched/eval.log。

mkdir -p ${ROUNDS}
python3 -m scripts.utilities.assemble_searched \
    --original-dir ${ORIGINAL} --original-csv ${ORIGINAL}/per_sample.csv \
    --rounds-dir ${ROUNDS} --searched-dir ${SEARCHED}

阶段 7 — 过滤 + 重新生成 + 评估（默认 `nn_threshold=0.4`）

阶段 7 默认执行（nn_threshold=0.4），在每次 mode=full 和 mode=inference_only 调用中都会运行；传入 nn_threshold=0 可跳过。它按 nn_threshold 过滤 searched/，通过重新 AMP（在同一缺陷类型中重新配对 (clean, submask)）重新生成被丢弃的样本，最多尝试 5 次，然后回退到未通过但得分最高的重新生成样本，最终回退到被丢弃的原始样本，因此最终桶总是等于 num_SDG。

运行 python3 -m scripts.utilities.filter_with_regen。它在内部执行最终的 run_eval.sh——这是唯一针对 searched/ 的评估。有关重新生成机制、源列追踪和 regens/regen_summary.csv 模式，请阅读 references/inference.md §Phase 7；完整命令和标志见 references/inference-commands.md §Phase 7。

输出布局

每个被评估的桶都携带相同的一套三个文件：SDG_result.csv（生成参数 + nn_score）、per_sample.csv（逐样本 nn + mnn）和 eval.log（聚合 FID / 每种缺陷的平均值）。桶位于 results/<name>/ 下，分别为 original/（阶段 3+4）、searched/（阶段 6 拼接 + 阶段 7 过滤+重新生成+评估）、rounds/round_NN/（阶段 5，外加 search_summary.csv）和 regens/regen_NN/（阶段 7，外加 regen_summary.csv）。

完整目录树及各文件注释和运行后验证清单（每桶图像计数、search_summary.csv / regen_summary.csv 行检查、每个 eval.log 中按类型的 nn_score / mnn_score / fid 字段）请参阅 references/output-layout.md。

错误处理

常见流水线故障模式（缺少掩码目录、AMP 输出过短/为空以及 0 entries written 停止、轮次中途 SDG 失败恢复、step 越界）见 references/error-handling.md；阶段特定的错误处理另见 references/finetune.md 和 references/inference.md。