physical-ai-defect-image-generation

Physical AI 缺陷图像生成

目录

• 支持的流程
• 消歧（完整表格见 references/disambiguation.md）
• 步骤 0：选择流程、Cookbook 并收集输入
• 通用前置条件（详细说明见 references/preconditions.md）
• 流程演练（每个流程各有一项；详情见 references/flows/）
• OSMO 监控
• 支持文件

用于端到端编排 AOI（自动光学检测）数据集的缺陷图像生成、增强和标注流水线。AnomalyGen = 针对每个用例微调的 Cosmos-Predict2-2B（Cosmos-AnomalyGen-PCB-2B、-Metal-2B、-Glass-2B）。每个流程在 assets/configs/ 中都有规范的 OSMO 工作流 YAML，可非交互式地串联所有步骤。assets/cookbooks/ 中的用例 Cookbook 提供 PCBA usd2roi/image-edit 配置，以及适用于 PCBA、金属表面和玻璃检测的 AnomalyGen 训练配置。本技能负责流程选择、数据交接和提交命令；组件内部细节请参阅各组件的 SKILL.md。

支持的流程

流程	入口	OSMO YAML	步骤	用例
第 0 天 — 纹理缺陷	CAD 场景 USD（Cookbook 中附带 pcba_target.yaml）	texture_defect_generation_day0.yaml	usd2roi（scan_grid + 按单元 ROI 裁剪）→ image-edit 增强（nvidia/Qwen-Image-Edit-NVPCB-OVSL2SL）→ 微调或直通 → 推理（内联 AnomalyGen 标签，包括缺失组件）	PCBA
第 0 天 — 良品图像 （usd2roi + Image-Edit）	CAD 场景 USD + 每块电路板对应的 pcba_target.yaml / day0_image.yaml / day0_crop.yaml	good_image_generation.yaml	usd2roi-render（scan_grid + 按单元 ROI 裁剪）→ Qwen Image-Edit（OVSL2SL 外观迁移）	PCBA 清洁图像集（ChangeNet 良品半图、微调正样本、真实照片配对）
第 0 天 — 结构缺陷	CAD 场景 USD + 每块电路板对应的 pcba_target.yaml	structural_defect_generation.yaml	isaac-render（姿态缺陷：偏移 / 立碑 / 侧翻）+ 按组件裁剪（单个 pod）→ Qwen Image-Edit（OVSL2SL 光照迁移；保留姿态几何）	PCBA 姿态缺陷集；ChangeNet 缺陷半图
第 1 天 — 推理 + 标注（真实照片对齐，默认）	CAD 派生的 USD + PCBA 真实照片（两者均附带于 datasets/pcb/assets）	texture_defect_generation_day1_real_alignment.yaml	usd2roi 第 1 天渲染 → MI 配准 → 按 ROI 裁剪 → yq-render 配置 → 微调或直通 → 推理（内联 AnomalyGen 标签）	PCBA 第 1 天默认流程。 任意受 usd2roi 支持的电路板的原始 AOI 截图
第 1 天 — 推理 + 标注（手动 ROI）	预先采集的良品图像 + ROI 掩码（NGC 工件或用户上传）	texture_defect_generation_day1_manual_roi.yaml	yq-render 配置 → 微调或直通 → 推理（内联 AnomalyGen 标签）	金属表面、玻璃（无 USD/真实照片流程）；仅在用户明确要求预采集 ROI 实验时用于 PCBA
仅微调	已标注的异常 URL 工件	finetune.yaml	yq-render 配置 → 微调（validate_dataset → prep_testcase → torchrun）	任意用例；生成适用于第 0 天或第 1 天的检查点。要求原始训练数据位于 <dig_url_root>/datasets/<usecase>/raw 下（参见 assets/configs/setup/setup_<usecase>.yaml）。

所有流程均在 OSMO 上运行。第 0 天流程需要 image_edit_endpoint（Qwen Image-Edit OVSL2SL——已有 URL 或通过 references/nim/ 在本地部署）；仅微调流程不需要外部端点。

根据用户缺陷类别选择合适的工作流

缺陷类别	工作流	机制
干净 / 良好 / 扫描网格 / normal_img + cad_mask 对	good_image_generation.yaml	usd2roi-render + Qwen Image-Edit
纹理缺陷（焊桥、划痕、变色）以及缺失组件（由 AnomalyGen 原生处理，不属于结构缺陷）	texture_defect_generation_day0.yaml	Qwen Image-Edit + AnomalyGen AMP/SDG
结构 / 姿态缺陷（墓碑效应、偏移、侧翻）	structural_defect_generation.yaml	IsaacSim 姿态扰动
在真实图像上进行 Day 1 推理 + 标注	texture_defect_generation_day1_real_alignment.yaml（PCBA 默认）或 texture_defect_generation_day1_manual_roi.yaml（金属 / 玻璃；仅当用户明确要求使用预先采集的 ROI / 跳过对齐时用于 PCBA）	usd2roi Day 1 配准（真实对齐）或直接推理（手动 ROI）

ChangeNet 标准 / 缺陷图像对：提交 good_image_generation.yaml + structural_defect_generation.yaml，并使用相同的 --set name=（成对提交约定）。

Day 0 和 Day 1 的下游结构相同：由 Jinja 控制的 finetune-job（当 use_pretrained_checkpoint=true 时省略）连接到 anomaly-infer。Day 0 前置 usd2roi-render + augment-image-edit；Day 1 从 <dig_url_root>/datasets/<usecase>/raw 开始。各阶段详情：参见每个流程的操作指南。

用户意图 → 参数映射

每个 OV 流程都分为两个阶段：crop_max_emit=N 限制最终每个单元格的裁剪图数量（阶段 2）；render_patches=N 限制原始扫描网格图块数量（阶段 1，每个图块会生成多个裁剪图）。不要自动将“生成 N 张图”映射为 render_patches=N（阶段不对）。structural_defect_generation.yaml 不存在 crop_max_emit（每个组件裁剪一张图 — 使用 render_patches）；texture_defect_generation_day1_real_alignment.yaml 也不存在该参数（通过操作手册中的 crop.classes 白名单缩小范围）。完整参数表、冒烟测试方案、默认值和注意事项：references/knob_mapping.md。

结构缺陷的数量设置（不存在 crop_max_emit 参数）

结构缺陷的输出量与 render_patches 并非线性关系：帧数翻倍，裁剪图数量约增加 1.6–1.7 倍，而不是 2 倍。不要使用 crop_max_emit（无效）或 render_patches=0（会失败）。经验证的产出表 + 目标数量公式：references/flows/structural_defect_generation.md §“输出数量设置”。对于“生成 N 张图”这类含糊请求，通过 AskUserQuestion 展示校准表。

---

消除歧义：确认含糊请求后再执行

对未充分说明的提示（“给我生成一些图”“运行 PCBA 流程”“给我一些缺陷”），不得通过默默假定工作流 / 用例 / 参数映射来决定如何处理。意图不明确时，暂停并通过 AskUserQuestion 提供候选解释（2–4 个互斥选项），再提交。需要明确影响执行的选择：使用哪个流程、哪个用例、数量指哪个阶段、微调还是直通。

已确定的默认值无需再次询问：PCBA Day 1 → 真实对齐；板卡 → 0603_H100；图像编辑端点 → 本地集群服务（references/nim/）；use_pretrained_checkpoint=true；Day 1 真实对齐 default_spatial_dependency=cad（仅在 CAD 掩码不可用时回退到 free，参见 references/flows/texture_defect_generation_day1_real_alignment.md）。

dig_url_root 是唯一例外 — 不得默默使用默认值。 首次使用（无记忆条目）时，必须先通过 AskUserQuestion 询问，再进行任何提交 / osmo data upload / preflight_urls.sh。s3://osmo-workflows/dig 是供确认的建议值，绝不能自动选用（上传量约 80 GB 或更大）。后续运行可静默复用记忆中的值。参见步骤 0 + 记忆规则（§4）。

完整的触发条件表、提示词构建方式及无需询问的例外情况：references/disambiguation.md — 为任何含糊请求整理 AskUserQuestion 选项前，先阅读该文件。

---

步骤 0：选择流程、操作手册并收集输入

在此步骤之前，如果请求含糊不清（例如“给我生成图片”“运行 PCBA 流程”“给我一些缺陷”），请暂停并运行上方的消歧速查表——通过 AskUserQuestion 列出可能的解释，并让用户选择。不要擅自选用用户并未实际选择、且会产生重大影响的默认选项。

首次使用门槛

如果内存中没有该用户的记录，请在任何预检 / osmo / kubectl / osmo data upload 操作之前，通过一次 AskUserQuestion 调用询问所有前置偏好问题，并将答案保存到内存（§4），然后继续。问题应包括：

• dig_url_root — 必须询问，不能擅自选择。提供 s3://osmo-workflows/dig 作为可供确认的建议；否则由用户提供其 OSMO 支持的存储前缀。约 80 GB 及以上的数据存放在此处。除从内存中读取此前已确认的值外，没有其他跳过此项的方式。
• 默认 OSMO --pool — 候选项来自 osmo profile list → pool.accessible。
• Pod 模板确认 — 仅当 osmo config show POD_TEMPLATE 返回 403 时询问（§2 中有确切的问题）。
• 图像编辑端点 — 仅限第 0 天：选项 A（现有 URL）与选项 B（部署本地 NIM）二选一。

后续对话应从内存中静默读取这些偏好。每次都要询问各流程的选项（用例、checkpoint 或 finetune、板卡、参数）——见下文。

预检顺序（首次使用门槛之后）

依次运行 §1 preflight_credentials.sh → §2 preflight_pod_template.sh → §3 preflight_urls.sh <flow> <usecase> → §4 生成运行戳。执行频率：§1 和 §2 是每次对话仅需执行一次的门槛，并会跨对话缓存记忆（参见 references/preconditions.md 中的 §4a）——如果记忆记录显示已验证／用户已确认，则跳过。每次提交前都运行 §3（因流程而异）。§4 由 Agent 执行——每次提交都使用新的 $STAMP。

Pod 模板的强制检查分为两层：提交前的 preflight_pod_template.sh 门槛（§2），以及每个 OV + 训练任务在 Pod 内执行的运行时预检（如果缺少 /usr/share/nvidia/nvoptix.bin 或 /dev/shm < 16 GiB，则快速失败）。如果 §2 通过，但运行时检查失败 → 模板曾被移除补丁 → 转到 physical-ai-infrastructure-setup-and-resilient-scaling。如果缺少凭据／URL 配置文件 → 先提议提交 setup/setup_<case>.yaml + setup/setup_pretrained.yaml。

然后在一条消息中询问用户——只询问与流程相关的选项（上面的首次使用门槛已涵盖 dig_url_root、资源池、Pod 模板和端点偏好；从记忆中获取这些信息）：

1. 用例 — PCBA（使用 Day 0 + pcb cookbook）、金属表面（Day 1 + metal_surface cookbook）、玻璃（Day 1 + glass cookbook），还是自定义？
2. 是否有可用的检查点？ — 如果有（use_pretrained_checkpoint=true），使用 <dig_url_root>/models/<usecase> 并提供 checkpoint_step。如果没有，则从 <dig_url_root>/datasets/<usecase>/raw 微调。
3. Local-NIM 资源池容量检查（仅限 Day 0 Option B）— 在 kubectl apply 之前，通过 physical-ai-infrastructure-setup-and-resilient-scaling 检查 Total Capacity。Total Capacity < 2 时无法同时运行 NIM + DIG → 请用户添加 GPU 或切换到 Option A。image_edit_model 始终为 nvidia/Qwen-Image-Edit-NVPCB-OVSL2SL，绝不能使用通用的 qwen-image-edit。
4. 将用户偏好保存到记忆中 — 首次使用门槛之后（以及任何提交偏离文档默认值之后），保存影响后续操作的选项（dig_url_root、OSMO 资源池、默认电路板、图像编辑端点、Pod 模板状态、osmo-admin 角色）。绝不保存 image_edit_model（它是常量——保存后可能导致值发生偏移），也不保存临时状态（STAMP、一次性的 anomaly_types_json）。完整列表：references/preconditions.md §4a「记忆规则」。每次新对话开始时读取相关记忆，并静默应用。

提问前先查看相关流程参考——大多数值都有合理的默认值。Day 1 路由：PCBA 默认为 real_alignment；金属／玻璃没有 USD 流程，因此始终使用 manual_roi；除非用户明确要求跳过对齐，否则不要询问 PCBA 用户要选“手动”还是“真实对齐”。

通用前置条件（适用于所有流程）

快速参考。详细说明：references/preconditions.md。

1. OSMO 凭据 + 令牌 — 每次对话执行一次。如果工作区中存在 .env，请先加载它（set -a; . ./.env; set +a），以便导出 HF_TOKEN。运行 scripts/preflight_credentials.sh；权威检查项是 OSMO 凭据 hf-token 已配置（镜像在 nvcr.io/nvidia/ 上公开，无需注册表凭据）。在受限出站网络的 shell 中传入 --no-probe。参见 references/preconditions.md §1。

2. Pod 模板 — 每次对话执行一次，并跨对话缓存记忆（参见 Step 0 §6）。如果记忆记录了集群已验证／用户已确认／因 409 而跳过，则跳过。否则运行 scripts/preflight_pod_template.sh 并根据退出码分支处理（0=已验证／1=通过 infra skill 修补／2=询问用户（HTTP 403）／3=跳过（HTTP 409）／4=修复环境）。完整的分支说明和提示词见 references/preconditions.md §2。

3. 必需的 URL 资源 — 每次提交前执行。运行 DIG_URL_ROOT=<dig_url_root> scripts/preflight_urls.sh <flow> <usecase> [variant]。如果缺少任何资源，请停止并先提交相关的 setup/setup_<case>.yaml + setup/setup_pretrained.yaml（OSMO 设置工作流）— 参见 references/setup.md。**切勿为了绕过问题而在本地下载资源；如果设置因凭据失败，请让用户修正凭据并在 OSMO 上重新提交。**各流程的检查清单：

   流程	用例	<dig_url_root> 下必需的 URL 资源
   Day 0 — 纹理缺陷	PCBA	models/pretrained、models/pcb、datasets/pcb/raw、datasets/pcb/assets
   Day 0 — 良品图像	PCBA	仅 datasets/pcb/assets
   Day 0 — 结构缺陷	PCBA	仅 datasets/pcb/assets
   Day 1	金属表面	models/pretrained、models/metal_surface、datasets/metal_surface/raw
   Day 1	玻璃	models/pretrained、models/glass、datasets/glass/raw
   Day 1 真实照片对齐	PCBA	Day 1 PCBA，以及 datasets/pcb/assets
   仅微调	任意	models/pretrained、datasets/<usecase>/raw

   内置的 usecase 值为 pcb、metal_surface、glass。参见 references/preconditions.md §3。

4. 名称标记 — 每次提交前重新生成 $STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)，并传入 --set name=<flow>-$STAMP。生产 YAML 不提供默认 name。参见 references/preconditions.md §4。

5. 玻璃用例（UC3）— Roboflow zip — 仅适用于 setup_glass.yaml。先将 mobile_screen.zip 上传到 OSMO URL 前缀；传入 --set uc3_zip_url_root=<prefix>。完整流程：references/setup.md §"玻璃用例（UC3）"。

---

流程演练

各流程的完整演练——包括组图、前置条件、提交命令变体、数据交接和各阶段故障排查——位于 references/flows/ 下。对于当前对话中尚未运行过的流程，Agent 应在提交前阅读对应文件。

流程	工作流 YAML	演练
Day 0 — 纹理缺陷（PCBA）	assets/configs/texture_defect_generation_day0.yaml	references/flows/texture_defect_generation_day0.md
Day 0 — 良品图像（PCBA）	assets/configs/good_image_generation.yaml	references/flows/good_image_generation.md
Day 0 — 结构缺陷（PCBA）	assets/configs/structural_defect_generation.yaml	references/flows/structural_defect_generation.md
Day 1 — 推理 + 标注（真实照片对齐，默认 PCBA）	assets/configs/texture_defect_generation_day1_real_alignment.yaml	references/flows/texture_defect_generation_day1_real_alignment.md
Day 1 — 推理 + 标注（手动 ROI，金属／玻璃 + PCBA 实验）	assets/configs/texture_defect_generation_day1_manual_roi.yaml	references/flows/texture_defect_generation_day1_manual_roi.md
仅微调	assets/configs/finetune.yaml	references/flows/finetune.md

跨流程不变量

• use_pretrained_checkpoint=true（默认值）→ 对 models/<usecase> 进行透传。设为 false 可插入一个 pod 内的 finetune-job 组（cookbook 在 pod 内通过 yq 打补丁，不执行预提交渲染步骤）。
• Day 0 会生成按单元划分的 crop/<MATERIAL>/<cell>/... 目录树；Day 1 会生成针对每个 ROI 的裁剪图，并注册到 USD；结构化流程会生成扁平的按组件划分的裁剪图。
• 各用例随附的 checkpoint_step 和 anomaly_types_json 默认值：参见 references/preconditions.md §“随附的 checkpoint 和 anomaly_types_json 默认值”。

---

OSMO 监控

在此技能中执行任何 osmo workflow submit、osmo workflow query 或 osmo workflow logs 操作之前，请先加载 references/monitoring.md。 该文件定义了轮询频率、任务状态解读、日志拉取升级阈值、故障分类路由，以及哪些内容应告知用户、哪些内容应静默重试。请勿凭记忆编写提交后的监控循环或状态摘要——每次对话中首次执行此类操作时，都要重新读取该文件。

osmo workflow query <workflow_id> --format-type json | jq '{status, tasks: [.groups[].tasks[] | {name, status, exit_code}]}'
osmo workflow logs <workflow_id> -t <task_name> -n 200
osmo data download <dig_url_root>/runs/<name>/anomaly ./output/anomaly-<name>/

监控规范：references/monitoring.md。结果检索：references/output_retrieval.md。结果展示：references/output_rendering.md。注意事项：references/troubleshooting.md。

---

回复模板

对于“给我看看计划 / 配方”之类的请求，请在最终回复中使用以下带标签的部分（避免内容在配方中途被截断）：

工作流： <flow name> → assets/configs/<yaml>

预检： scripts/preflight_credentials.sh；scripts/preflight_urls.sh <0|1|finetune> <usecase> [variant]

<dig_url_root> 下所需的 URL 产物： 根据所选工作流，按 Common Preconditions §3 逐项列出。

提交命令：

STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
osmo workflow submit assets/configs/<yaml> --pool <pool> \
  --set name=<flow>-$STAMP dig_url_root=<root> usecase=<usecase> \
        image_edit_endpoint=<endpoint> image_edit_model=nvidia/Qwen-Image-Edit-NVPCB-OVSL2SL \
        checkpoint_step=<step> 'anomaly_types_json=<types>'

监控： 运行提交命令前加载 references/monitoring.md；osmo workflow submit 返回工作流 ID 后，按照其中的轮询频率和日志拉取阈值执行。

输出位置： <dig_url_root>/runs/<flow>-$STAMP/anomaly/（各工作流的覆盖设置：参见工作流说明）。

---

支持文件

完整清单——工作流 YAML、cookbook、脚本表、参考资料、评估项和组件技能——请参见 references/contents.md。顶层目录：assets/configs/、assets/cookbooks/、scripts/、references/、evals/。