Former une Workflow Policy avec RL

Objectif

Résoudre un profil RL en ligne maintenu, vérifier ses contrats Scene/objectif/modèle, lancer le trainer vectorisé sélectionné, évaluer et exporter son artefact, puis transmettre cet artefact à la validation normale de Workflow policy.

Prérequis

• Exécuter d'abord la skill Workflow setup pour que ses environnements uv et checkouts tiers épinglés soient disponibles.
• Utiliser un runtime Isaac Lab/Arena compatible CUDA pour le workflow RSL-RL.
• Pour Trocar, fournir un checkpoint SFT ou base local GR00T N1.5 3B et deux GPUs visibles locaux pour les runtimes controller et simulator isolés. Un checkpoint compatible est un répertoire Hugging Face local complet que le loader GR00T N1.5/RLinf épinglé accepte sans conversion ; il doit conserver l'architecture N1.5 3B et supporter le mappage d'observation trois-caméras plus 28-articulations maintenu et la tête d'action policy 28-D. Rejeter une autre famille de modèle, un artefact Task d'inférence exporté uniquement, ou un checkpoint dont la config modifie ces interfaces.

Instructions

1. Résoudre le checkout et les profils supportés.
2. Confirmer les contrats Workflow, Scene, observations, actions, rewards, resets, termination, trainer et runtime Task.
3. Dry-run la configuration exacte demandée.
4. Préflighter le runtime trainer sélectionné et entraîner au premier plan.
5. Évaluer le succès du simulator, exporter la policy et la valider via le runner Workflow normal.

Résoudre le checkout

export I4H_WORKFLOWS_REPO_URL="${I4H_WORKFLOWS_REPO_URL:-https://github.com/isaac-for-healthcare/i4h-workflows}"
I4H_REPO_DIR_NAME="${I4H_WORKFLOWS_REPO_URL%/}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*/}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*:}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME%.git}"
[ -n "$I4H_REPO_DIR_NAME" ] || { echo "Cannot derive a checkout name from I4H_WORKFLOWS_REPO_URL" >&2; exit 2; }
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/i4h_workflows" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/$I4H_REPO_DIR_NAME}"
  [ -d "$ROOT/workflows/i4h_workflows" ] || git clone "$I4H_WORKFLOWS_REPO_URL" "$ROOT"
fi
export I4H_WORKFLOWS="$ROOT"
cd "$ROOT"

Traiter ce resolver comme faisant partie du contrat de skill. I4H_WORKFLOWS_REPO_URL sélectionne la source du clone ; I4H_WORKFLOWS sélectionne ou réutilise un checkout. Ne jamais remplacer un checkout existant.

Résoudre le profil et les contrats

./train.sh rl list
./train.sh rl show <workflow>
./run.sh show <workflow> --mode policy

Lire le profil sous ./rl/profiles/, sa config trainer déclarative référencée sous ./rl/config/, le manifeste et l'implémentation Workflow/Scene, la config objectif Arena, l'embodiment et le manifeste Task policy runtime avant une longue exécution.

Sélectionner le chemin maintenu à partir du profil :

Pour ultrasound_probe_reach, exiger que la cible soit échantillonnée à partir de points de surface torse-supérieur vérifiés, que la table et le phantom restent fixes, que le succès exige la tolérance position et orientation pour des étapes consécutives, et que l'ordre d'observation Task exportée corresponde exactement à l'entraînement.

Pour assemble_trocar, exiger Unitree G1 avec mains Dex3, caméras front et deux poignets, l'état body 87-valeurs courant (29 positions + 29 vélocités + 29 couples), 14 positions articulations Dex3, le mappage 28-D GR00T bras/main, le préfixe body-action 15-valeurs et le contrat reward/termination g1_trocar maintenu. Ne pas copier un autre environnement Trocar dans l'arbre d'entraînement.

Rédiger une nouvelle Workflow RL-backed

1. Créer et valider visiblement la Workflow et Scene avant d'ajouter l'entraînement. Garder les assets, embodiment, observations, actions, rewards, resets, termination et success dans leurs propriétaires Arena et Workflow normaux.
2. Ajouter ./rl/profiles/<workflow>.yaml en utilisant le schéma ci-dessous. Le nom de fichier et la valeur workflow doivent correspondre.
3. Ajouter une config trainer YAML déclarative sous ./rl/config/ ; utiliser <workflow>_<algorithm>_<backend>.yaml et pointer trainer_config vers elle en tant que ../config/<file>.yaml.
4. Réutiliser un backend générique sous ./rl/i4h_rl/backends/. Ajouter ./rl/i4h_rl/adapters/<workflow>.py uniquement quand la Scene maintenue nécessite conversion observation, action, registration ou evaluation spécifique au workflow. Ne pas ajouter de branches workflow à cli.py, sim_server.py ou un package __init__.py.
5. Entraîner et évaluer le checkpoint natif, l'exporter dans une Task policy en processus ou remote réutilisable, ajouter cette Task à la TaskGraph policy de la Workflow, et valider le succès simulator via le runner Workflow normal. Comparer les valeurs observation/action runtime avec l'entraînement, pas seulement leurs dimensions et ordonnancement : préserver les repères de coordonnées, la convention quaternion, la normalisation, le scaling d'action, l'état action-précédente et les sémantiques de reset.

schema_version: 1
workflow: <workflow>
scene: <scene>
trainer: <rsl_rl-or-rlinf>
algorithm: ppo
adapter_module: i4h_rl.adapters.<workflow>
trainer_config: ../config/<workflow>_ppo_<backend>.yaml
train_task_id: <trainer-environment-id>
eval_task_id: <trainer-evaluation-environment-id>
task_description: <short instruction>
action_dof: <scene-action-width>
policy_action_dof: <policy-action-width>
state_dof: <state-observation-width>
cameras: []
default_num_envs: <positive-integer>
default_epochs: <positive-integer>
simulation:
  env_spacing: <positive-metres>
  presets: physx
  enable_cameras: false

Lancer ./train.sh rl show <workflow> et un petit --dry-run immédiatement. Le chargement du profil doit rejeter les sources manquantes, les champs inconnus, les backends non supportés, les dimensions incohérentes, les caméras absentes de la Scene, les ID task RLinf/mappage action non-correspondants et la propriété config RSL-RL malformée avant qu'un simulator ne démarre.

Dry-run

RSL-RL de zéro :

./train.sh rl ultrasound_probe_reach \
  --num-envs 128 \
  --epochs 400 \
  --dry-run

Post-entraînement foundation-policy RLinf :

./train.sh rl assemble_trocar \
  --model-path /absolute/path/to/gr00t-sft-checkpoint \
  --num-envs 64 \
  --epochs 1000 \
  --dry-run

Inspecter la Scene résolue, le trainer, les ID task, les dimensions observation/action, le nombre d'environnements, le nombre iteration/epoch, le chemin config, le modèle de départ quand requis et les overrides explicites. Garder les valeurs resource demandées par l'utilisateur exactes.

Préflighter et entraîner

Le projet uv léger rl possède la résolution de profil et l'orchestration de commande. Ses configs trainer sont YAML et n'importent pas Isaac Lab. L'intégration du backend RSL-RL s'exécute dans l'environnement Arena car ses dépendances trainer et simulator sont compatibles. Définir son runtime explicitement uniquement quand l'environnement Arena préparé n'est pas approprié :

export I4H_RL_PYTHON=/absolute/path/to/arena-rsl-runtime-python

Entraîner l'exemple compact RSL-RL :

./train.sh rl ultrasound_probe_reach \
  --num-envs 128 \
  --epochs 400

Résoudre TRAIN_RUN à partir du chemin run dir: horodaté imprimé par la commande d'entraînement. Ne pas deviner ou sélectionner un run par récence.

Trocar utilise deux processus isolés sur un hôte car GR00T N1.5/RLinf requiert Python 3.11 tandis que le runtime Isaac Sim/Arena courant requiert Python 3.12. Le controller model par défaut est tasks/gr00t_n15/.venv/bin/python sur GPU physique 0, le simulator par défaut est arena/.venv/bin/python sur GPU physique 1, et les observations/actions traversent un bridge de données socket Unix local. Overrider ces runtimes quand nécessaire :

export I4H_RL_PYTHON=/absolute/path/to/gr00t-rlinf-python
export I4H_RL_SIM_PYTHON=/absolute/path/to/isaac-sim-arena-python

Entraîner le profil GR00T/RLinf uniquement avec un checkpoint de départ local compatible, le checkout RLinf épinglé et deux GPUs visibles :

./train.sh rl assemble_trocar \
  --model-path /absolute/path/to/gr00t-sft-checkpoint \
  --num-envs 64 \
  --epochs 1000

Garder l'entraînement au premier plan. Préserver le répertoire de run et la commande exacte en cas d'échec. Ne pas baisser silencieusement les comptes d'environnements ou epochs. Le launcher RSL-RL courant n'expose pas resume ou entraînement distribué multi-GPU ; un second GPU n'est pas utilisé automatiquement. Les deux GPUs de Trocar isolent les processus model et simulator plutôt que de distribuer un trainer sur les deux GPUs.

Évaluer, exporter et transmettre

Évaluer le checkpoint RSL-RL sur des épisodes randomisés indépendants :

TRAIN_RUN="$PWD/runs/ultrasound_probe_reach/YYYYMMDD_HHMMSS"

./train.sh rl ultrasound_probe_reach \
  --eval \
  --checkpoint "$TRAIN_RUN/model_final.pt" \
  --episodes 20

Exporter un actor TorchScript compatible simulator, puis valider la Task Workflow concrète :

./train.sh rl export ultrasound_probe_reach \
  --checkpoint "$TRAIN_RUN/model_final.pt" \
  --output-dir "$TRAIN_RUN/exported"

./run.sh ultrasound_probe_reach --policy \
  --checkpoint "$TRAIN_RUN/exported/policy.pt" \
  --episodes 20

Un entraînement RLinf réussi écrit checkpoint.json dans le répertoire de run. Il pointe vers le checkpoint FSDP natif et enregistre le modèle GR00T de départ, donc l'évaluation accepte le bundle de run directement sans répéter --model-path. Une évaluation réussie doit écrire evaluation.json avec des métriques TensorBoard non-vides et au moins une trajectoire. L'export découvre aussi la config d'entraînement RLinf résolue stockée dans ce bundle de run :

TRAIN_RUN="$PWD/runs/assemble_trocar/YYYYMMDD_HHMMSS"

./train.sh rl assemble_trocar \
  --eval \
  --checkpoint "$TRAIN_RUN" \
  --video

./train.sh rl export assemble_trocar \
  --checkpoint "$TRAIN_RUN" \
  --output-dir "$TRAIN_RUN/exported"

./run.sh assemble_trocar --policy \
  --checkpoint "$TRAIN_RUN/exported" \
  --episodes 1

Traiter le checkpoint trainer natif comme le résultat d'entraînement et l'évaluer avant export. L'export inférence GR00T est empaquetage runtime pour la Task remote, pas un substitut pour l'évaluation checkpoint. Exiger le statut exit 0, les épisodes d'évaluation demandés quand le trainer les expose, des métriques non-vides, les artefacts checkpoint/export attendus et le succès simulator Workflow normal. Ne jamais revendiquer le succès à partir des courbes de loss ou exit d'entraînement seuls.

Dépannage

Rapporter la première dépendance runtime manquante, chemin checkpoint, échec registration, non-correspondance observation/action, loss non-finie, erreur mémoire CUDA, erreur distribuée/Ray/FSDP, échec construction environnement ou artefact success manquant. Préserver le répertoire de run échoué. Ne pas modifier l'objectif Scene ou les paramètres resource sans direction utilisateur.

Limitations

Les profils maintenus sont ultrasound_probe_reach avec RSL-RL et assemble_trocar avec RLinf. RSL-RL resume, RSL-RL evaluation video et distributed multi-GPU launch ne sont pas encore exposés. Trocar requiert actuellement deux GPUs locaux visibles et son bridge simulator socket Unix est single-host ; un déploiement simulator/controller distribué n'est pas exposé. Cette skill ne réalise pas de fine-tuning supervisionné LeRobot et ne rend pas trainable les workflows non-supportés.

Exemples

• Entraîner la policy ultrasound probe reach avec PPO et évaluer 20 épisodes. → dry-run le profil RSL-RL, entraîner de zéro, évaluer des épisodes randomisés, exporter TorchScript et valider la Task Workflow.
• Post-entraînement RL la policy Trocar à partir de mon checkpoint GR00T local. → dry-run le profil RLinf, vérifier le mappage G1/camera/action, entraîner, exporter un checkpoint GR00T chargeable et valider la Task policy remote.

Porte de fin

Rapporter la Workflow et Scene, trainer/profil/config, checkpoint de départ quand applicable, contrat observation/action/reward/reset/termination, resources demandées et complétées, répertoire de run, métriques d'évaluation, artefacts checkpoint et export, commande validation Workflow exacte et taux de succès, statut exit et toute limitation runtime ou hardware restante.