Orchestrateur de flux de génération d'images de défauts pour l'IA physique

Table des matières

• Flux supportés
• Désambiguïsation (tableau complet dans references/disambiguation.md)
• Étape 0 : Sélectionner le flux, le cookbook et rassembler les entrées
• Préconditions communes (long format dans references/preconditions.md)
• Walkthroughs de flux (une entrée par flux ; détails dans references/flows/)
• Surveillance OSMO
• Fichiers de support

Orchestration de bout en bout des pipelines de génération, d'augmentation et d'étiquetage d'images de défauts pour les datasets AOI (Automated Optical Inspection). Chaque flux possède un workflow YAML OSMO canonique dans assets/configs/ qui enchaîne toutes les étapes sans interaction. Les cookbooks cas d'usage dans assets/cookbooks/ fournissent les configs PCBA usd2roi/image-edit et les configs d'entraînement AnomalyGen pour l'inspection PCBA, surface métallique et verre. Cette skill gouverne la sélection de flux, les transferts de données et les commandes de soumission ; les internes des composants vivent dans le SKILL.md de chaque composant.

Flux supportés

Tous les flux tournent sur OSMO. Les flux Jour 0 nécessitent image_edit_endpoint (Qwen Image-Edit OVSL2SL — URL existante ou déploiement local depuis references/nim/) ; Finetune uniquement n'a pas de endpoints externes.

Choisir le workflow approprié pour la classe de défaut de l'utilisateur

Paires dorées/défauts ChangeNet : soumettez good_image_generation.yaml + structural_defect_generation.yaml avec le même --set name= (convention d'appairage à deux soumissions).

Jour 0 et Jour 1 partagent la même forme aval : un finetune-job gated Jinja (omis quand use_pretrained_checkpoint=true) alimentant anomaly-infer. Jour 0 préfixe usd2roi-render + augment-image-edit ; Jour 1 commence depuis <dig_url_root>/datasets/<usecase>/raw. Détail par étape : walkthrough de chaque flux.

Intent utilisateur → mappage des paramètres

Chaque flux OV est en deux étapes : crop_max_emit=N plafonne les crops par cellule finaux (étape 2) ; render_patches=N plafonne les patches scan-grid bruts (étape 1, chacun produisant plusieurs crops). NE PAS mapper automatiquement "générer N images" → render_patches=N (mauvaise étape). crop_max_emit n'existe pas sur structural_defect_generation.yaml (un crop par composant — utilisez render_patches) ou texture_defect_generation_day1_real_alignment.yaml (restreindre via la liste blanche crop.classes du cookbook). Tableau complet des paramètres, recettes de smoke-test, valeurs par défaut, avertissements : references/knob_mapping.md.

Dimensionnement des défauts structurels (aucun paramètre crop_max_emit n'existe)

La sortie structurelle est non-linéaire en render_patches — doubler les images ajoute ~1.6–1.7× crops, pas 2×. N'utilisez pas crop_max_emit (sans effet) ou render_patches=0 (échoue). Tableau de rendement validé + formule de taille cible : references/flows/structural_defect_generation.md §"Sizing the output". Pour un "générer N images" ambigu, surfacez le tableau d'étalonnage via AskUserQuestion.

Désambiguïsation : traiter les demandes vagues avant de s'engager

Les prompts mal spécifiés ("générez-moi des images", "lancez le flux PCBA", "donnez-moi des défauts") ne doivent pas être résolus en assumant silencieusement un flux / cas d'usage / mappage de paramètres. Quand l'intent est ambigu, mettez en pause et présentez les interprétations candidates via AskUserQuestion (2–4 options mutuellement exclusives) avant de soumettre. Désambiguïsez les choix critiques : quel flux, quel cas d'usage, à quelle étape un nombre se réfère-t-il, finetune vs. passthrough.

Les valeurs par défaut que vous NE DEVEZ PAS désambiguïser : PCBA Jour 1 → real-alignment ; carte → 0603_H100 ; image-edit endpoint → service cluster local (references/nim/) ; use_pretrained_checkpoint=true ; Jour 1 real-alignment default_spatial_dependency=cad (revenir à free uniquement quand les masques CAD ne sont pas disponibles, voir references/flows/texture_defect_generation_day1_real_alignment.md).

dig_url_root est l'unique exception — AUCUNE valeur par défaut silencieuse. Première fois (pas d'entrée mémoire), DOIT être élicité via AskUserQuestion avant tout submit / osmo data upload / preflight_urls.sh. s3://osmo-workflows/dig est une suggestion à confirmer, jamais auto-sélectionné (~80 GB+ s'y retrouvent). Les exécutions ultérieures peuvent réutiliser la valeur mémorisée silencieusement. Voir Étape 0 + règles de mémoire (§4).

Tableau de déclenchement complet, construction du prompt et exceptions when-NOT-to-ask : references/disambiguation.md — charger avant d'assembler les options AskUserQuestion pour toute demande vague.

Étape 0 : Sélectionner le flux, le cookbook et rassembler les entrées

Avant cette étape, si la demande est vague (ex. "générez-moi des images", "lancez le flux PCBA", "donnez-moi des défauts"), mettez en pause et exécutez la feuille de triche de désambiguïsation ci-dessus — présentez les interprétations candidates via AskUserQuestion et laissez l'utilisateur choisir. Ne sélectionnez pas automatiquement une valeur par défaut critique que l'utilisateur n'a pas vraiment choisie.

Portail première utilisation

Si la mémoire n'a aucune entrée pour cet utilisateur, DEMANDEZ les questions de préférence à l'avance dans UN appel AskUserQuestion AVANT tout preflight / osmo / kubectl / osmo data upload, enregistrez en mémoire (§4), puis continuez. Regroupez :

• dig_url_root — DOIT être élicité, pas auto-sélectionné. Proposez s3://osmo-workflows/dig comme suggestion confirmable ; sinon l'utilisateur fournit son propre préfixe de stockage supporté par OSMO. ~80 GB+ s'y retrouvent. Aucune échappatoire sauf rappel mémoire d'une valeur précédemment confirmée.
• --pool OSMO par défaut — candidats issus de osmo profile list → pool.accessible.
• Confirmation du pod-template — uniquement quand osmo config show POD_TEMPLATE retourne 403 (§2 a la question exacte).
• Image-edit endpoint — Jour 0 uniquement : Option A (URL existante) vs Option B (déploiement local NIM).

Les conversations ultérieures lisent ces valeurs silencieusement depuis la mémoire. Les choix par flux (cas d'usage, checkpoint vs finetune, carte, paramètres) sont demandés à chaque fois — voir ci-dessous.

Ordre des préflights (après le portail première utilisation)

Exécutez §1 preflight_credentials.sh → §2 preflight_pod_template.sh → §3 preflight_urls.sh <flow> <usecase> → §4 générez le run stamp. Cadence : §1 et §2 sont des portails one-per-conversation avec mise en cache mémoire cross-conversation (voir §4a dans references/preconditions.md) — ignorez quand la mémoire les enregistre comme déjà vérifiés / confirmé utilisateur. §3 s'exécute avant chaque submit (varie par flux). §4 est le travail de l'agent — $STAMP frais par submit.

L'application du pod-template est en deux couches : le portail pre-submit preflight_pod_template.sh (§2) plus un preflight runtime in-pod sur chaque tâche OV + training (échoue rapidement sur /usr/share/nvidia/nvoptix.bin manquant ou /dev/shm < 16 GiB). Échec runtime malgré §2 réussi → template a été corrigé → routez vers physical-ai-infrastructure-setup-and-resilient-scaling. Creds / artefacts URL manquants → proposez de soumettre d'abord setup/setup_<case>.yaml + setup/setup_pretrained.yaml.

Puis demandez à l'utilisateur dans un seul message — choix par flux uniquement (le portail première utilisation ci-dessus a déjà couvert dig_url_root, pool, pod-template et préférences endpoint ; tirez ceux-ci de la mémoire) :

1. Cas d'usage — PCBA (utiliser Jour 0 + cookbook pcb), surface métallique (Jour 1 + cookbook metal_surface), verre (Jour 1 + cookbook glass), ou personnalisé ?
2. Checkpoint disponible ? — Si oui (use_pretrained_checkpoint=true), utilisez <dig_url_root>/models/<usecase> et fournissez checkpoint_step. Si non, finetune depuis <dig_url_root>/datasets/<usecase>/raw.
3. Vérification de capacité du pool local-NIM (Jour 0 Option B uniquement) — avant kubectl apply, vérifiez Total Capacity via physical-ai-infrastructure-setup-and-resilient-scaling. Total Capacity < 2 ne peut pas héberger NIM + DIG concurremment → demandez à l'utilisateur d'ajouter des GPUs ou basculer vers Option A. image_edit_model est toujours nvidia/Qwen-Image-Edit-NVPCB-OVSL2SL, jamais générique qwen-image-edit.
4. Enregistrez les préférences utilisateur en mémoire — après le portail première utilisation (et après tout submit divergeant d'une valeur par défaut documentée), persistez les choix critiques (dig_url_root, pool OSMO, carte par défaut, image-edit endpoint, état pod-template, rôle osmo-admin). N'enregistrez jamais image_edit_model (constant — enregistrer invite la dérive) ou l'état éphémère (STAMP, anomaly_types_json one-off). Tableau complet : references/preconditions.md §4a "Memory rules". Lisez les mémoires pertinentes au début de chaque nouvelle conversation et appliquez silencieusement.

Examinez la référence de flux pertinente avant de demander — la plupart des valeurs ont des valeurs par défaut sensibles. Routage Jour 1 : PCBA par défaut vers real_alignment ; métal/verre n'ont pas de flux USD donc toujours manual_roi ; ne demandez pas à l'utilisateur "manuel ou real-alignment ?" pour PCBA sauf s'il demande explicitement de sauter l'alignement.

Préconditions communes (tous les flux)

Référence rapide. Long format : references/preconditions.md.

1. Tokens + credentials OSMO — une fois par conversation. Si un .env existe dans l'espace de travail, sourcez-le d'abord (set -a; . ./.env; set +a) donc HF_TOKEN est exporté. Exécutez scripts/preflight_credentials.sh ; la vérification faisant autorité est que le cred OSMO hf-token est provisionné (les images sont publiques sur nvcr.io/nvidia/ — aucun cred de registry requis). Passez --no-probe dans les shells restricted-egress. Voir references/preconditions.md §1.

2. Pod template — une fois par conversation, avec mise en cache mémoire cross-conversation (voir Étape 0 §6). Ignorez quand la mémoire enregistre le cluster vérifié / confirmé utilisateur / 409-skipped. Sinon exécutez scripts/preflight_pod_template.sh et branchez sur le code de sortie (0=vérifié / 1=patch via infra skill / 2=ask-user (HTTP 403) / 3=skip (HTTP 409) / 4=env-fix). Prose branchement complet et prompts dans references/preconditions.md §2.

3. Artefacts URL requis — avant chaque submit. Exécutez DIG_URL_ROOT=<dig_url_root> scripts/preflight_urls.sh <flow> <usecase> [variant]. Si quelque chose manque, arrêtez et soumettez d'abord les workflows OSMO setup pertinents setup/setup_<case>.yaml + setup/setup_pretrained.yaml (voir references/setup.md). Ne téléchargez jamais d'assets localement pour contourner un problème ; si le setup échoue sur les credentials, demandez à l'utilisateur de les rectifier et re-soumettre sur OSMO. Checklist par flux :

   Flux	Cas d'usage	Artefacts URL requis sous <dig_url_root>
   Jour 0 — Défauts de texture	PCBA	models/pretrained, models/pcb, datasets/pcb/raw, datasets/pcb/assets
   Jour 0 — Bonne image	PCBA	datasets/pcb/assets uniquement
   Jour 0 — Défauts structurels	PCBA	datasets/pcb/assets uniquement
   Jour 1	Surface métallique	models/pretrained, models/metal_surface, datasets/metal_surface/raw
   Jour 1	Verre	models/pretrained, models/glass, datasets/glass/raw
   Jour 1 real-photo alignment	PCBA	Jour 1 PCBA plus datasets/pcb/assets
   Finetune uniquement	N'importe quel	models/pretrained, datasets/<usecase>/raw

   Les valeurs usecase intégrées sont pcb, metal_surface, glass. Voir references/preconditions.md §3.

4. Estampillage de nom — régénérez $STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8) avant chaque submit et passez --set name=<flow>-$STAMP. Les YAMLs production ne livrent aucune valeur par défaut name. Voir references/preconditions.md §4.

5. Cas verre (UC3) — Zip Roboflow — uniquement pour setup_glass.yaml. Uploadez mobile_screen.zip vers un préfixe URL OSMO d'abord ; passez --set uc3_zip_url_root=<prefix>. Procédure complète : references/setup.md §"Glass case (UC3)".

Walkthroughs de flux

Le walkthrough complet de chaque flux — diagrammes de groupe, prérequis, variantes de commande-submit, transferts de données, dépannage par étape — vit sous references/flows/. L'agent doit lire le fichier correspondant avant de soumettre tout flux qu'il n'a pas exécuté dans la conversation actuelle.

Invariants cross-flux

• use_pretrained_checkpoint=true (par défaut) → passthrough contre models/<usecase>. Mettez à false pour insérer un groupe finetune-job in-pod (cookbook yq-patched in-pod, pas d'étape pre-submit render).
• Jour 0 émet des arbres per-cell crop/<MATERIAL>/<cell>/... ; Jour 1 émet des crops per-ROI enregistrés contre l'USD ; structural émet des crops par composant plats.
• checkpoint_step + valeurs par défaut anomaly_types_json livrées par cas d'usage : voir references/preconditions.md §"Shipped checkpoint and anomaly_types_json defaults".

Surveillance OSMO

Chargez references/monitoring.md avant toute action osmo workflow submit, osmo workflow query ou osmo workflow logs dans cette skill. Il définit la cadence d'interrogation, l'interprétation du statut des tâches, les seuils d'escalade de pull log, le routage de classification d'échec, et quoi surfacer à l'utilisateur vs. réessai silencieux. N'assemblez pas une boucle de surveillance post-submit ou un résumé de statut depuis la mémoire — relisez-le à la première telle action de chaque conversation.

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>/

Discipline de surveillance : references/monitoring.md. Récupération : references/output_retrieval.md. Présentation : references/output_rendering.md. Pièges : references/troubleshooting.md.

Modèle de réponse

Pour les demandes "montrez-moi le plan / la recette", émettez votre réponse finale avec ces sections étiquetées (pour que rien ne soit tronqué à mi-recette) :

Workflow : <nom de flux> → assets/configs/<yaml>

Préflights : scripts/preflight_credentials.sh ; scripts/preflight_urls.sh <0|1|finetune> <usecase> [variant]

Artefacts URL requis sous <dig_url_root> : énumérez selon Préconditions communes §3 pour le flux choisi.

Commande de soumission :

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>'

Surveillance : chargez references/monitoring.md avant d'exécuter le submit ; appliquez sa cadence d'interrogation + seuils de pull log après retour de osmo workflow submit avec un id workflow.

Emplacement de sortie : <dig_url_root>/runs/<flow>-$STAMP/anomaly/ (override par flux : voir walkthrough de flux).

Fichiers de support

Inventaire complet — YAMLs workflow, cookbooks, table de scripts, références, évals, skills de composants — dans references/contents.md. Répertoires de haut niveau : assets/configs/, assets/cookbooks/, scripts/, references/, evals/.