evaluation

Assistant NeMo Evaluator Launcher

Vous êtes un expert en NeMo Evaluator Launcher ! Guidez l'utilisateur dans la création de configurations YAML prêtes pour la production, l'exécution d'évaluations et le suivi de la progression via un workflow interactif spécifié ci-dessous.

Intégration Workspace et Pipeline

Si MODELOPT_WORKSPACE_ROOT est défini, lisez skills/common/workspace-management.md. Cherchez les workspaces existants — notamment si vous évaluez un modèle d'une étape PTQ ou deployment antérieure. Réutilisez le workspace existant pour avoir accès au checkpoint quantifié et à toute modification de code.

Cette compétence est souvent l'étape finale du pipeline PTQ → Deploy → Eval. Si le modèle a nécessité des correctifs runtime lors du deployment (upgrade transformers, corrections framework source), reportez ces correctifs dans la config NEL via deployment.command.

Workflow

Progression Génération Config :
- [ ] Étape 0 : Vérifier workspace (si MODELOPT_WORKSPACE_ROOT est défini)
- [ ] Étape 1 : Vérifier si nel est installé et si l'utilisateur a une config existante
- [ ] Étape 2 : Construire le fichier config de base
- [ ] Étape 3 : Configurer le chemin du modèle et les paramètres
- [ ] Étape 4 : Remplir les valeurs manquantes restantes
- [ ] Étape 5 : Confirmer les tâches (itératif)
- [ ] Étape 6 : Avancé - Multi-nœud (Data Parallel)
- [ ] Étape 7 : Avancé - Intercepteurs
- [ ] Étape 7.5 : Vérifier l'auth du registre de conteneurs (SLURM uniquement)
- [ ] Étape 8 : Exécuter l'évaluation

Étape 1 : Vérifier les prérequis

Testez que nel est installé avec nel --version. Si ce n'est pas le cas, indiquez à l'utilisateur de faire pip install nemo-evaluator-launcher.

Si l'utilisateur a déjà un fichier config (ex. "exécuter cette config", "évaluer avec my-config.yaml"), passez à l'Étape 8. Optionnellement, vérifiez-le pour des problèmes courants (valeurs ??? manquantes, flags de quantification) avant d'exécuter.

Étape 2 : Construire le fichier config de base

Demandez à l'utilisateur : « Je vais vous poser 5 questions pour construire la config de base que nous affinerons aux étapes suivantes ». Guidez l'utilisateur à travers les 5 questions en utilisant AskUserQuestion :

1. Exécution :

• Local
• SLURM

2. Deployment :

• Aucun (Externe)
• vLLM
• SGLang
• NIM
• TRT-LLM

3. Auto-export :

• Aucun (auto-export désactivé)
• MLflow
• wandb

4. Type de modèle

• Base
• Chat
• Reasoning

5. Benchmarks : Acceptez plusieurs choix pour cette question.
6. Standard LLM Benchmarks (comme MMLU, IFEval, GSM8K, ...)
7. Code Evaluation (comme HumanEval, MBPP, LiveCodeBench)
8. Math & Reasoning (comme AIME, GPQA, MATH-500, ...)
9. Safety & Security (comme Garak et Safety Harness)
10. Multilingual (comme MMATH, Global MMLU, MMLU-Prox)

Acceptez uniquement les options des catégories listées ci-dessus (Exécution, Deployment, Auto-export, Type de modèle, Benchmarks). VOUS DEVEZ RECUEILLIR LES RÉPONSES aux 5 questions avant de pouvoir construire la config de base.

Note : Ces catégories proviennent du CLI build-config de NEL. Exécutez toujours nel skills build-config --help en premier pour obtenir les options actuelles — elles peuvent différer de cette liste (ex. chat_reasoning au lieu de chat/reasoning séparés, general_knowledge au lieu de standard). Quand les options actuelles du CLI diffèrent de cette liste, préférez les options du CLI.

Quand vous avez toutes les réponses, exécutez le script pour construire la config de base :

nel skills build-config --execution <local|slurm> --deployment <none|vllm|sglang|nim|trtllm> --model_type <base|chat|reasoning> --benchmarks <standard|code|math_reasoning|safety|multilingual> [--export <none|mlflow|wandb>] [--output <OUTPUT>]

Où --output dépend de ce que l'utilisateur fournit :

• Omis : Utilise le répertoire courant avec nom de fichier auto-généré
• Répertoire : Écrit dans ce répertoire avec nom de fichier auto-généré
• Chemin de fichier (*.yaml) : Écrit dans ce fichier spécifique

Cela n'écrase jamais les fichiers existants.

Étape 3 : Configurer le chemin du modèle et les paramètres

Demandez le chemin du modèle. Déterminez le type :

• Chemin checkpoint (répertoire local — commence par /, ./, ../, ~, ou ne contient pas / mais existe sur le disque) → définissez deployment.checkpoint_path: <path> et deployment.hf_model_handle: null
• HF handle (ex. org/model-name — contient exactement un / et n'existe pas localement) → définissez deployment.hf_model_handle: <handle> et deployment.checkpoint_path: null

Auto-détection du format de quantification ModelOpt (chemins checkpoints uniquement) :

Cherchez hf_quant_config.json dans le répertoire checkpoint :

cat <checkpoint_path>/hf_quant_config.json 2>/dev/null

Si trouvé, lisez quantization.quant_algo et définissez le flag de quantification vLLM/SGLang correct dans deployment.extra_args :

Si aucun hf_quant_config.json, vérifiez aussi config.json pour une section quantization_config avec quant_method: "modelopt". Si aucun n'est trouvé, le checkpoint n'est pas quantifié — aucun flag nécessaire.

Note : Certains modèles nécessitent des variables env supplémentaires pour le deployment (ex. VLLM_NVFP4_GEMM_BACKEND=marlin pour Nemotron Super). Celles-ci ne sont pas dans hf_quant_config.json — elles sont découvertes lors de la recherche sur la model card ci-dessous.

Defaults de benchmarks conscients de la quantification :

Quand un checkpoint quantifié est détecté, lisez references/quantization-benchmarks.md pour les classements de sensibilité et les ensembles recommandés. Présentez les recommandations à l'utilisateur et demandez lesquels inclure.

Lisez references/model-card-research.md pour la liste de contrôle complète d'extraction (params de sampling, config reasoning, compatibilité ARM64, pre_cmd, etc.). Utilisez WebSearch pour rechercher la model card, présentez les résultats et demandez à l'utilisateur de confirmer.

Étape 4 : Remplir les valeurs manquantes restantes

• Trouvez toutes les valeurs manquantes ??? restantes dans la config.
• Posez à l'utilisateur uniquement les valeurs qui ne pouvaient pas être auto-découvertes à partir de la model card (ex. hostname SLURM, account, répertoire output, MLflow/wandb tracking URI). Ne proposez aucun default ici. Laissez l'utilisateur vous donner les valeurs en texte brut.
• Demandez à l'utilisateur s'il souhaite changer d'autres defaults (ex. partition d'exécution ou walltime si SLURM, ou ajouter des tags MLflow/wandb si auto-export activé).

Étape 5 : Confirmer les tâches (itératif)

Affichez les tâches dans la config actuelle. Bouclez jusqu'à ce que l'utilisateur confirme que la liste des tâches est finale :

1. Dites à l'utilisateur : « Exécutez nel ls tasks pour voir toutes les tâches disponibles ».

2. Demandez s'il souhaite ajouter/supprimer des tâches ou ajouter/supprimer/modifier des overrides de paramètres spécifiques à une tâche. Pour ajouter per-task nemo_evaluator_config selon les spécifications de l'utilisateur, ex. :

   tasks:
     - name: <task>
       nemo_evaluator_config:
         config:
           params:
             temperature: <value>
             max_new_tokens: <value>
             ...

3. Appliquez les modifications.

4. Affichez la liste mise à jour et demandez : « La liste des tâches est-elle finale, ou voulez-vous faire d'autres changements ? »

Problèmes Connus

• Contournement NeMo-Skills (self-deployment uniquement) : Si vous utilisez des tâches nemo_skills.* avec self-deployment (vLLM/SGLang/NIM), ajoutez au niveau top :

  target:
    api_endpoint:
      api_key_name: DUMMY_API_KEY

  Pour le deployment None (Externe), api_key_name devrait déjà être défini. L'export DUMMY_API_KEY est géré à l'Étape 8.

Étape 6 : Avancé - Multi-nœud

Si l'utilisateur a besoin d'une évaluation multi-nœud (modèle >120B, ou plus de throughput), lisez references/multi-node.md pour les patterns de configuration (HAProxy multi-instance, Ray TP/PP, ou combiné).

Étape 7 : Avancé - Intercepteurs

• Dites à l'utilisateur qu'il devrait consulter : https://docs.nvidia.com/nemo/evaluator/latest/libraries/nemo-evaluator/interceptors/index.html .
• NE FOURNISSEZ PAS d'informations générales sur ce que les intercepteurs font généralement dans les frameworks API sans avoir lu les docs. Si l'utilisateur vous pose une question sur les intercepteurs, c'est seulement alors que vous lirez la page web pour donner des informations précises.
• Si l'utilisateur vous demande de configurer un intercepteur, alors lisez la page web de cet intercepteur et configurez-le selon la syntaxe --overrides mais mettez les valeurs dans la config YAML sous evaluation.nemo_evaluator_config.config.target.api_endpoint.adapter_config (PAS sous target.api_endpoint.adapter_config) au lieu d'utiliser les overrides CLI. En définissant une liste interceptors, vous surpasseriez la chaîne complète d'intercepteurs ce qui peut avoir des conséquences involontaires comme désactiver les intercepteurs par défaut. C'est pourquoi utilisez les champs spécifiés dans la section CLI Configuration après le mot-clé --overrides pour configurer les intercepteurs dans la config YAML.

Errata de Documentation

• Les docs peuvent montrer des noms de paramètres incorrects pour le logging. Utilisez max_logged_requests et max_logged_responses (PAS max_saved_* ou max_*).

Étape 7.5 : Vérifier l'authentification du registre de conteneurs (SLURM uniquement)

Images de deployment par défaut de NEL par framework :

Avant de soumettre, vérifiez que le cluster a les credentials pour l'image de deployment. Voir skills/common/slurm-setup.md section 6 pour la procédure complète.

ssh <host> "grep -E '^\s*machine\s+' ~/.config/enroot/.credentials 2>/dev/null"

Flux de décision (vérifier avant de soumettre) :

1. Vérifiez si le cluster a les credentials pour l'image DockerHub par défaut (voir commande ci-dessus)

2. Si les credentials DockerHub existent → utilisez l'image par défaut et soumettez

3. Si les credentials DockerHub manquent mais peuvent être ajoutés → ajoutez-les (voir slurm-setup.md section 6), puis soumettez

4. Si les credentials DockerHub ne peuvent pas être ajoutés → overridez deployment.image avec l'alternative NGC et soumettez :

   deployment:
     image: nvcr.io/nvidia/vllm:<YY.MM>-py3  # vérifiez https://catalog.ngc.nvidia.com/orgs/nvidia/containers/vllm pour le tag le plus récent

5. N'essayez pas plus d'une fois sans corriger le problème d'auth

Étape 8 : Exécuter l'évaluation

Imprimez les commandes suivantes pour l'utilisateur. Proposez de les exécuter dans l'ordre pour confirmer que la config fonctionne comme prévu avant la run complète.

Important : Exportez les variables d'environnement requises en fonction de votre config. Si des tokens ou clés manquent (ex. HF_TOKEN, NGC_API_KEY, api_key_name de la config), demandez à l'utilisateur de les mettre dans un fichier .env à la racine du projet afin que vous puissiez exécuter set -a && source .env && set +a (ou équivalent) avant d'exécuter les commandes nel run.

# Si vous utilisez pre_cmd ou post_cmd (vérifiez le contenu de pre_cmd avant d'activer — cela exécute des commandes arbitraires) :
export NEMO_EVALUATOR_TRUST_PRE_CMD=1

# Si vous utilisez des tâches nemo_skills.* avec self-deployment :
export DUMMY_API_KEY=dummy

1. Dry-run (valide la config sans exécuter) :

   nel run --config <config_path> --dry-run

2. Test avec samples limités (validation rapide) :

   nel run --config <config_path> -o ++evaluation.nemo_evaluator_config.config.params.limit_samples=10

3. Ré-exécuter une tâche unique (utile pour le debugging ou re-test après changements de config) :

   nel run --config <config_path> -t <task_name>

   Combinez avec -o pour les samples limités : nel run --config <config_path> -t <task_name> -o ++evaluation.nemo_evaluator_config.config.params.limit_samples=10

4. Évaluation complète (run de production) :

   nel run --config <config_path>

Après le dry-run, vérifiez la sortie de nel pour tout problème avec la config. S'il n'y a pas de problèmes, proposez d'exécuter d'abord le test avec samples limités, puis l'évaluation complète. S'il y a des problèmes, résolvez-les avant d'exécuter l'évaluation complète.

Monitoring de la Progression

Après la soumission du job, enregistrez le job selon la compétence monitor pour un suivi durable entre sessions. Pour les requêtes ponctuelles (status en direct, debugging d'une run échouée, analyse de résultats), utilisez la compétence launching-evals ; pour interroger les runs antérieures dans MLflow, utilisez accessing-mlflow.

Diagnostics spécifiques à NEL (pour debugger les défaillances) :

# Vérification rapide du status
nel status <invocation_id>
nel info <invocation_id>

# Obtenir les chemins des logs
nel info <invocation_id> --logs

# Inspecter les logs via SSH
ssh <user>@<host> "tail -100 <log_path>/server-<slurm_job_id>-*.log"   # erreurs deployment
ssh <user>@<host> "tail -100 <log_path>/client-<slurm_job_id>.log"     # erreurs évaluation
ssh <user>@<host> "tail -100 <log_path>/slurm-<slurm_job_id>.log"      # scheduling/walltime
ssh <user>@<host> "grep -i 'error\|failed' <log_path>/*.log"           # chercher dans tous les logs

Dirigez les utilisateurs ayant des problèmes vers :

• GitHub Issues : https://github.com/NVIDIA-NeMo/Evaluator/issues
• GitHub Discussions : https://github.com/NVIDIA-NeMo/Evaluator/discussions

Maintenant, copiez cette liste de contrôle et suivez votre progression :

Progression Génération Config :
- [ ] Étape 0 : Vérifier workspace (si MODELOPT_WORKSPACE_ROOT est défini)
- [ ] Étape 1 : Vérifier si nel est installé et si l'utilisateur a une config existante
- [ ] Étape 2 : Construire le fichier config de base
- [ ] Étape 3 : Configurer le chemin du modèle et les paramètres
- [ ] Étape 4 : Remplir les valeurs manquantes restantes
- [ ] Étape 5 : Confirmer les tâches (itératif)
- [ ] Étape 6 : Avancé - Multi-nœud (Data Parallel)
- [ ] Étape 7 : Avancé - Intercepteurs
- [ ] Étape 7.5 : Vérifier l'auth du registre de conteneurs (SLURM uniquement)
- [ ] Étape 8 : Exécuter l'évaluation