i4h-workflow-validate

Par nvidia · skills

Valider, évaluer ou exécuter des environnements i4h. À utiliser pour les rollouts de policy/checkpoint et les smoke runs de machine à états scriptée.

npx skills add https://github.com/nvidia/skills --skill i4h-workflow-validate

Flux de travail i4h — Validate

Objectif

Déployer une politique ou un contrôleur de machine à états scriptée contre un environnement et enregistrer les épisodes de vérification dans un HDF5. À utiliser quand l'utilisateur demande de valider, évaluer, exécuter ou déployer une politique/checkpoint, ou demande des tests de smoke de machine à états chirurgicaux.

Code de base

Ces étapes pilotent le code de base des workflows i4h (l'arborescence workflows/agentic/). Pour réutiliser un checkout existant, définissez I4H_WORKFLOWS à son chemin (aucun clone ne se produit). Sinon, cela résout le référentiel courant, ou clone vers ~/i4h-workflows — acceptez cette valeur par défaut sans demander confirmation. Exécutez chaque commande ci-dessous depuis la racine résolue :

# Résoudre le code de base i4h-workflows (fournit workflows/agentic/).
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/agentic" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"
  [ -d "$ROOT/workflows/agentic" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"
fi
export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

Concepts de base

  • Configuration de l'env (source de vérité) : workflows/agentic/config/environments/<env>.yaml — lisez-la pour les valeurs par défaut de <env> : policy.model_repo/model_revision, policy.task_description, policy.health_port, et arena.max_timesteps.
  • La validation exécute le daemon de politique et Arena ensemble ; les deux processus sont requis.
  • Le daemon de politique est sans interface. Arena ouvre la fenêtre de simulation par défaut ; ajoutez --headless --enable_cameras --rendering_mode performance uniquement si l'utilisateur demande explicitement une exécution sans interface/sans fenêtre.
  • Dans Claude Code --print, Codex exec, ou toute autre session non-interactive/nouvelle, l'évaluation de la politique doit utiliser Step 2A comme une commande bash unique au premier plan. Ne démarrez pas la politique et Arena dans des appels d'outil séparés, n'utilisez pas les tâches de fond Claude pour l'eval, et ne revenez pas à l'utilisateur jusqu'à ce qu'Arena se termine et que le nettoyage de la politique ait été exécuté.
  • Dans Claude Code spécifiquement, n'utilisez pas le mode de fond de l'outil Bash pour les invites Evaluate ..., ne lancez pas une commande se terminant par &, et ne dites pas « l'eval s'exécute en arrière-plan ». La réponse n'est complète que lorsque le résumé HDF5/log a été inspecté.
  • Les invites quick-run README qui disent « avec la machine à états » utilisent Arena --state-machine et ne démarrent pas de daemon de politique.
  • N'exécutez pas l'annotateur VLM à moins que l'utilisateur ne demande des labels de succès.
  • assemble_trocar est inférence uniquement — validez son modèle YAML par défaut ou un checkpoint N1.5 compatible.

Entrées

  • ENV_ID : id YAML d'env.
  • EPISODES : 1 pour santé, plus pour eval réelle.
  • MAX_TIMESTEPS : utilisez le plafond demandé par l'utilisateur quand l'invite en fournit un (par exemple, 300 timesteps -> MAX_TIMESTEPS=300) ; sinon lisez arena.max_timesteps depuis le YAML d'env pour l'évaluation normale. Utilisez 200 uniquement quand l'utilisateur demande explicitement un smoke, santé, ou vérification rapide.
  • MODEL_PATH (optionnel) : chemin vers un répertoire checkpoint-NNNN/ contenant model-0000{N}-of-*.safetensors, experiment_cfg/, et processor/. Omettez pour utiliser policy.model_repo du YAML.
  • USE_LATEST_CHECKPOINT=1 : définissez ceci quand l'invite dit « nouveau checkpoint » ou « dernier checkpoint » et MODEL_PATH n'est pas déjà connu.
  • STATE_MACHINE : true uniquement quand l'invite dit explicitement state machine.

Exécution

Exécutez les étapes ci-dessous dans l'ordre avec l'outil bash. Les chemins de script comme policy/run.sh, arena/run.sh, et stop.sh sont des commandes à l'intérieur de bash, pas des noms d'outil.

Pour l'évaluation de politique/checkpoint dans Claude Code --print, Codex, codex exec --ephemeral, ou toute autre session non-interactive nouvelle, utilisez Step 2A après la configuration. Les daemons de politique en arrière-plan lancés par un shell terminé peuvent être nettoyés avant qu'Arena se connecte ; le shell contrôlé garde la politique et Arena dans une seule durée de vie de processus et arrête toujours le daemon après. Dans une session interactive locale tmux, le flux séparé Step 2 / Step 3 / Step 4 est également acceptable.

Step 1 — setup

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/agentic" ] || REPO_ROOT="$HOME/i4h-workflows"
ENV_ID=scissor_pick_and_place
EPISODES=1
ENV_CONFIG="${REPO_ROOT}/workflows/agentic/config/environments/${ENV_ID}.yaml"
[ -f "${ENV_CONFIG}" ] || { echo "missing env config: ${ENV_CONFIG}" >&2; exit 1; }
PYTHON="${REPO_ROOT}/workflows/agentic/arena/.venv/bin/python"
[ -x "${PYTHON}" ] || PYTHON="${REPO_ROOT}/workflows/agentic/.venv/bin/python"
[ -x "${PYTHON}" ] || { echo "missing workflow python env; run i4h-workflow-setup first" >&2; exit 1; }
MAX_TIMESTEPS="${MAX_TIMESTEPS:-$("${PYTHON}" -c 'import sys, yaml; print(yaml.safe_load(open(sys.argv[1], encoding="utf-8"))["arena"]["max_timesteps"])' "${ENV_CONFIG}")}"
RUNS_ROOT="${REPO_ROOT}/workflows/agentic/runs"

# Pour des invites comme « Exécuter eval en utilisant un nouveau checkpoint pour 300 timesteps » :
#   définissez MAX_TIMESTEPS=300 et USE_LATEST_CHECKPOINT=1 avant ce bloc.
if [ "${USE_LATEST_CHECKPOINT:-0}" = "1" ] && [ -z "${MODEL_PATH:-}" ]; then
  MODEL_PATH="$(find "${RUNS_ROOT}" -path '*/checkpoint/checkpoint-*' -type d -printf '%T@ %p\n' 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2-)"
  [ -n "${MODEL_PATH}" ] || { echo "validate: no checkpoint found under ${RUNS_ROOT}; run finetune first or set MODEL_PATH" >&2; exit 1; }
fi

RUN_DIR="${RUNS_ROOT}/eval_${ENV_ID}_$(date +%Y%m%d_%H%M%S)"
mkdir -p "${RUN_DIR}/data" "${RUN_DIR}/logs"
ln -sfn "${RUN_DIR}" "${RUNS_ROOT}/.latest"

Step 2 — daemon de politique

Passer cette étape quand STATE_MACHINE=true. Pour les sessions Codex/non-interactive, préférez Step 2A plutôt que cette étape séparée du daemon de politique.

POLICY_ARGS=(--env "${ENV_ID}" --ensure --log "${RUN_DIR}/logs/policy.log")
[ -n "${MODEL_PATH:-}" ] && POLICY_ARGS+=(--model-path "${MODEL_PATH}")
"${REPO_ROOT}/workflows/agentic/policy/run.sh" "${POLICY_ARGS[@]}"

Exécutez cette commande exactement comme une commande bash normale au premier plan. Ne la tubez pas vers head, cat, tee, ou tail ; n'ajoutez pas d'arrêt séparé, de lancement en arrière-plan, de sleep, de boucle grep, de vérification curl, ou de docker ps. policy/run.sh --ensure gère la réutilisation, l'arrêt/redémarrage, et le comportement de start-and-ready.

Step 2A — déploiement de politique contrôlé

Utilisez ceci au lieu des étapes séparées Step 2 / Step 3 / Step 4 lors de l'exécution dans Claude Code --print, Codex, codex exec --ephemeral, ou une autre session nouvelle non-interactive. Exécutez-le comme une commande bash normale au premier plan ; ne le mettez pas en arrière-plan et ne répondez pas jusqu'à ce qu'il imprime ARENA_STATUS.

POLICY_ARGS=(--env "${ENV_ID}" --ensure --log "${RUN_DIR}/logs/policy.log")
[ -n "${MODEL_PATH:-}" ] && POLICY_ARGS+=(--model-path "${MODEL_PATH}")

cleanup_policy() {
  "${REPO_ROOT}/workflows/agentic/stop.sh" policy --env "${ENV_ID}" >/dev/null 2>&1 || true
}
trap cleanup_policy EXIT

"${REPO_ROOT}/workflows/agentic/policy/run.sh" "${POLICY_ARGS[@]}"
ARENA_STATUS=0
"${REPO_ROOT}/workflows/agentic/arena/run.sh" --env "${ENV_ID}" \
  --episodes "${EPISODES}" \
  --max-timesteps "${MAX_TIMESTEPS}" \
  --max-attempts 1 \
  --record-to "${RUN_DIR}/data/verify.hdf5" \
  > "${RUN_DIR}/logs/arena.log" 2>&1 || ARENA_STATUS=$?
"${REPO_ROOT}/workflows/agentic/stop.sh" policy --env "${ENV_ID}"
trap - EXIT
echo "ARENA_STATUS=${ARENA_STATUS}"

Après ce bloc, allez directement à Step 5.

Step 3 — déploiement Arena

Passer cette étape si Step 2A a été utilisé.

Pour les tests de smoke de machine à états, utilisez cette commande Arena au lieu de la commande de déploiement de politique :

"${REPO_ROOT}/workflows/agentic/arena/run.sh" --env "${ENV_ID}" \
  --state-machine \
  --episodes "${EPISODES}" \
  --max-timesteps "${MAX_TIMESTEPS}" \
  --record-to "${RUN_DIR}/data/verify.hdf5" \
  > "${RUN_DIR}/logs/arena.log" 2>&1

Pour l'évaluation de politique ou de checkpoint :

"${REPO_ROOT}/workflows/agentic/arena/run.sh" --env "${ENV_ID}" \
  --episodes "${EPISODES}" \
  --max-timesteps "${MAX_TIMESTEPS}" \
  --max-attempts 1 \
  --record-to "${RUN_DIR}/data/verify.hdf5" \
  > "${RUN_DIR}/logs/arena.log" 2>&1

Step 4 — arrêter la politique

Passer cette étape quand STATE_MACHINE=true ou quand Step 2A a été utilisé.

"${REPO_ROOT}/workflows/agentic/stop.sh" policy --env "${ENV_ID}"

Step 5 — résumer les logs

grep -E "policy job complete|run complete|Traceback|Error|FAILED" "${RUN_DIR}/logs/arena.log" || tail -80 "${RUN_DIR}/logs/arena.log"
grep -E "policy ready|Traceback|Error|FAILED" "${RUN_DIR}/logs/policy.log" || tail -30 "${RUN_DIR}/logs/policy.log"

Notes

  • Lancez le daemon de politique avec policy/run.sh --ensure, puis lancez Arena.
  • Dans les exécutions Codex non-interactive, gardez le daemon de politique et Arena dans un shell contrôlé avec Step 2A afin que le daemon ne soit pas nettoyé entre les appels d'outil.
  • Une fois qu'Arena se termine — que les épisodes aient réussi ou échoué — arrêtez le daemon de politique. Il ne s'auto-termine pas, donc le laisser s'exécuter fuit la mémoire GPU et maintient son port de santé occupé. Arrêtez-le avec "${REPO_ROOT}/workflows/agentic/stop.sh" policy --env "${ENV_ID}".
  • --record-to doit être absolu. L'enregistreur résout les chemins relatifs par rapport à workflows/agentic/arena (son CWD) et produit un répertoire orphelin imbriqué.
  • --max-attempts est 1 par défaut pour les envs de la famille locomanip.

Annotation optionnelle

Exécutez uniquement sur demande :

"${REPO_ROOT}/workflows/agentic/annotator/run.sh" \
  --env "${ENV_ID}" \
  --output "${RUN_DIR}/annotations.jsonl" \
  offline \
  --hdf5-path "${RUN_DIR}/data/verify.hdf5"

Vérifier

  • verify.hdf5 existe sous ${RUN_DIR}/data/.
  • Le log Arena affiche run complete: N/M episodes succeeded.
  • Le log de politique ne contient pas de Traceback.

Prérequis

  • Flux de travail configuré via [[i4h-workflow-setup]] (.venv présent) ; les lancements policy/run.sh et arena/run.sh en dépendent.
  • Un ENV_ID correspondant à un id YAML d'env.
  • Une source de modèle : soit la valeur par défaut policy.model_repo du YAML d'env, soit un MODEL_PATH pointant vers un répertoire checkpoint-NNNN/ (model-0000{N}-of-*.safetensors, experiment_cfg/, processor/).

Limitations

  • Le daemon de politique et Arena sont tous deux requis ; le daemon est sans interface et Arena ouvre la fenêtre de simulation à moins que l'utilisateur ne demande explicitement une exécution sans interface/sans fenêtre.
  • assemble_trocar est inférence uniquement — validez son modèle YAML par défaut ou un checkpoint N1.5 compatible.
  • --record-to doit être absolu ; les chemins relatifs se résolvent par rapport à workflows/agentic/arena et produisent un répertoire orphelin imbriqué.
  • L'annotateur VLM est optionnel et exécuté uniquement sur demande ; il ne fait pas partie du déploiement par défaut.

Dépannage

  • Erreur : .venv / import échoue ou run.sh manquant - Cause : flux de travail non configuré. Solution : exécutez [[i4h-workflow-setup]] d'abord.
  • Erreur : le log de politique affiche Traceback / Error / FAILED avant policy ready - Cause : le daemon de politique n'a pas démarré (par exemple, mauvaise source de modèle). Solution : inspectez ${RUN_DIR}/logs/policy.log ; vérifiez ENV_ID / MODEL_PATH.
  • Erreur : Arena démarre avant que le daemon soit prêt - Cause : ordre de lancement. Solution : lancez d'abord le daemon de politique et attendez policy ready, puis lancez Arena.
  • Erreur : verify.hdf5 se retrouve dans un répertoire orphelin imbriqué - Cause : --record-to relatif. Solution : passez un chemin absolu sous ${RUN_DIR}/data/.
  • Erreur : PermissionError sur /data/verify.hdf5 - Cause : RUN_DIR n'était pas défini quand Arena a s'est exécuté (la configuration a été ignorée ou exécutée hors d'ordre). Solution : exécutez d'abord les lignes de configuration pour que RUN_DIR existe avant --record-to.

Réponse finale

Signalez l'env, la source du modèle, les épisodes sauvegardés vs demandés, le chemin HDF5, les chemins des logs.

Skills similaires

i4h-catheter-navigation-e2e
nvidia / skills

Exécuter un pipeline de navigation cathéter end-to-end : setup, jumeau numérique, rendu DRR et tests.

2 621
agent-observability-eval-pipeline
datadog-labs / agent-skills

Orchestrer un pipeline d'évaluation en six phases pour analyser et améliorer des agents IA instrumentés.

145
llm-obs-eval-bootstrap
datadog-labs / agent-skills

Générer une suite d'évaluateurs prêts à l'emploi à partir de traces LLM en production.

145
agent-observability-eval-bootstrap
datadog-labs / agent-skills

Analyser des traces LLM de production pour générer et publier une suite d'évaluateurs Datadog.

145
i4h-workflow-setup
nvidia / skills

Bootstrapper et vérifier l'environnement agentic i4h-workflows via setup.sh idempotent.

2 621