用途
该技能为 AnomalyGenNext 准备标准化输入，核心目标是把目标检测中的框级假阴性（false negative，FN）缺口转化为可用的异常生成输入。整个流程分为三个动作：第一，冻结符合条件的假阴性身份，将每个 FN 掩码隔离到其边界框，选择确定性的同类型掩码，并输出干净图像与 FN 的嵌入规格；第二，消费这些嵌入结果，保留每个 FN 到干净图像的配对，并运行 AnomalyGenNext 容器原生的自动掩码放置（AMP）；第三，仅接受两个掩码分支均通过 AMP 的配对，然后冻结确切的生成输入及其哈希。
输入契约
从 assets/default_filtering.yaml 开始。gap parquet 必须包含以下字段：image_id、filepath、gap_type、bbox、class、split、dataset_id、texture_id、defect_class、anomaly_type、fn_mask_source。身份是显式的：anomaly_type 必须等于 texture_id+defect_class。准备过程刻意不做文件名或目录布局推断。调用方在适配不熟悉的数据集时，必须在此边界之前规范化这些字段。
干净参考图像按每个路由的 FN/类型独立解析。缺失目录或目录中没有受支持图像时，仅跳过受影响的 FN，原因为 no_clean_reference_images，不会禁用其他类型。
每个选中的数据集映射到一个已有的微调检查点和配方。配方必须声明确切的异常类型，defect_spec.jsonl 必须包含其放置定义。文本路由的定义要求非空的 roi_prompt_defect_location。池布局为：POOL/TEXTURE/clean_image/* 与 POOL/TEXTURE/mask/DEFECT/*。
使用方式
在完成通用启动审查后，通过所选平台运行：
scripts/prepare_anomalygennext_inputs.py
--config /path/to/filtering.yaml
--pool-dataset-root /path/to/anomalygen_pool
--output-dir /new/result/root
输出根目录必须不存在。该动作会输出 fn_queries.parquet、selected_fn_queries.parquet、mask_selection.parquet、clean_pool.parquet、两个 tao-generate-image-embeddings 规格、复制的过滤配置以及 input_contract.json。掩码资格按每个 FN 评估。契约列出符合条件的 FN ID 以及稳定的被跳过 FN ID 和机器可读原因；被跳过的 FN 不会出现在任何查询、嵌入、掩码和 AMP 输入中。供体掩码按确定性顺序尝试，直到找到有效的同类型供体。
如果没有 FN 存活，准备过程仅输出一个 SKIPPED 的 input_contract.json，原因为 no_eligible_false_negatives。详细的 skip_counts、逐 FN 记录和警告证据可区分缺失干净参考与掩码资格失败。对于这种类型化的空操作，不要运行嵌入或 AMP，也不要将其表示为生成成功。部分跳过会输出警告证据，同时规格中仅包含符合条件的 FN。
pool_dataset_root 是工作流的一个用户级文件夹输入。平台将其暂存一次，并保留其源与传递给准备过程的计算可见路径之间的绑定。准备过程将该计算路径冻结到 filtering_config.yaml、clean_pool.parquet 中的每个干净文件路径以及 input_contract.json 中。契约声明同一个类型化文件夹作为干净图像嵌入和 AMP 的只读下游输入。每个后续容器必须在那个确切的计算路径重新挂载原始源；生成的脚本参数是平台管道，不是新的用户选择。
通过 tao-generate-image-embeddings 运行两个输出的规格，保持相同的编码器。干净图像嵌入动作必须消费 input_contract.json.downstream_inputs.clean_embeddings，以便其 parquet 中的池路径能够解析。FN 嵌入动作同样需要为其输入 parquet 已携带的源图像路径提供挂载。将两个输出放在规格指定的 embeddings/ 下，然后提交 run_amp 动作：
scripts/run_anomalygennext_amp.py
--prepared-root /temporary/execution/root
--published-root /persistent/result/root
--pool-dataset-root /path/to/anomalygen_pool
--checkpoint-root /workspace/paidf-anomalygen/checkpoints
run_amp 始终加载 --prepared-root 下的冻结配置；它不接受第二个配置。其类型化池参数确认平台已将文件夹重新挂载到已冻结到配置和 parquet 中的路径。
这会写入 knn_candidates.parquet、原生 AMP 请求和 amp/testcase.jsonl。当执行使用临时存储时，--published-root 记录将包含保存结果的持久位置。完整检查点根是必需的输入，挂载在镜像的规范路径 /workspace/paidf-anomalygen/checkpoints。在 GPU 工作之前，run_amp 会验证固定的 Qwen 缓存、配置的 amp.model_id 作为完整的直接本地模型或 Hugging Face 快照，以及 facebook/sam2.1-hiera-large/sam2.1_hiera_large.pt；单独挂载的 SAM2 文件不满足原生运行时契约。所选平台必须遵守声明的 checkpoint_root.container_path；叶子节点拒绝不同的挂载点。在持久结果根中最终确定保存的输出：
scripts/finalize_anomalygennext_inputs.py --prepared-root /existing/result/root
最终化器写入配对状态、选中的配对、复制的对齐掩码、逐数据集 testcase 和溯源 JSONL，以及生成计划和完整性清单。干净图像仅在一个 FN 内唯一；不同的 FN 可以复用它。平台技能负责暂存和缓存放置。
门控条件
- 将每个框级 FN 保留为不同的 fn_id。
- 每个 FN 恰好生成两个掩码：隔离的 FN 和确定性的同类型掩码。
- 跳过一个无效 FN 而不中止其他符合条件的 FN。
- 对重复的源图像仅嵌入一次，同时保留每个 FN 查询行。
- 要求两个分支都产生成功、非空、非全图的对齐掩码。
- 绝不推断异常类型或放置提示。
- 拒绝输出复用，绝不修改训练池。
- 平台技能负责瞬态暂存、缓存和回拷。
编写规范化 parquet 或数据集映射时，请阅读 references/input-contract.md。
适用场景与限制
该技能适用于需要将目标检测假阴性转化为 AnomalyGenNext 异常生成输入的流程，要求输入数据已按契约规范化，且具备对应的微调检查点、配方和池布局。限制包括：输出根目录必须不存在；不做文件名或目录布局推断；缺失干净参考或掩码资格失败会导致部分或全部 FN 被跳过；GPU 工作前需满足特定的模型缓存和挂载路径要求；平台必须遵守声明的挂载点。