<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 -->

Flywheel ASR Clinique — Stage 3 (Évaluation)

⚠ Agent : consultez la section Règles de Flux de Travail Critique ci-dessous avant de répondre. Ce SKILL.md est autonome — evals/, references/, et assets/ sont des pointeurs, non des éléments structurants. Répondez aux questions de méthodologie directement à partir de ce fichier ; n'invoquez les outils que si l'utilisateur demande explicitement une exécution contre un manifest réel.

Vous êtes l'étape score-et-routage. L'utilisateur arrive avec un manifest au format NeMo manifest.jsonl (soit depuis /digital-health-clinical-asr-build, soit apporté d'ailleurs). Vous le transcrivez via le NIM ASR choisi, évaluez quatre métriques, produisez un leaderboard à cinq sections, et consultez l'arbre de décision pour déterminer si l'utilisateur doit avancer vers /digital-health-clinical-asr-finetune, revenir à /digital-health-clinical-asr-build, ou arrêter et consolider l'évaluation.

Cette skill ne génère pas d'audio. Si le manifest est manquant ou vide, renvoyez l'utilisateur à /digital-health-clinical-asr-build.

L'audio quitte votre environnement — divulguez-le à l'utilisateur avant tout envoi de clip

Cette étape transmet le fichier WAV de chaque ligne du manifest ainsi que son texte de référence à un service NVIDIA externe. Rendez cela explicite avant d'invoquer le premier appel ASR :

Les clips doivent être audio synthétique généré par Stage 2 (Magpie TTS sur une liste de termes sélectionnée par l'utilisateur) — pas audio patient réel. N'envoyez pas d'enregistrements ASR réels, d'encounters patients réels, ou toute PHI via cette skill. L'évaluation s'exécute ensuite localement (WER/CER/KER/SER pur Python, ou jiwer si installé). L'étape d'évaluation elle-même ne transmet rien ; seule l'étape ASR le fait.

Règles de Flux de Travail Critique (s'appliquent à chaque activation)

Pour les questions de méthodologie (structure du leaderboard, définition de KER, arbre de décision), répondez à partir de ce fichier. N'invoquez pas les outils, n'appelez pas d'autres skills, ne lancez pas de scripts à moins que l'utilisateur demande explicitement une exécution contre un manifest réel. Surfacez ces faits dans toute réponse :

1. D'abord les sorties. Si l'utilisateur pose une question en dehors de l'évaluation, routez et arrêtez sans lancer de workflow :
   • Sélection / comparaison / NIMs alternatifs du catalogue de modèles ASR → /riva-asr
   • Auth ASR (clés API, bearer tokens, IDs de fonction) → /riva-asr
   • Protocole gRPC ASR, streaming, batching, chunking, retries → /riva-asr
   • Déploiement NIM / riva-build / riva-deploy → /riva-asr-custom
   • NGC / Docker / NVIDIA Container Toolkit → /riva-nim-setup
   • Pas encore de manifest → /digital-health-clinical-asr-build
   • Souhaite fine-tuner maintenant avec un KER connu → /digital-health-clinical-asr-finetune
2. Le NIM ASR par défaut est nvidia/parakeet-tdt-0.6b-v2 (ID de fonction NVCF d3fe9151-442b-4204-a70d-5fcc597fd610, gRPC hors ligne). Surcharges par variable d'environnement : ASR_MODEL_NAME (nom d'affichage du leaderboard), ASR_NVCF_FUNCTION_ID (basculer vers un NIM hébergé différent — par exemple Whisper Large v3 b702f636-… lors d'une panne du backend Parakeet, ou un NIM fine-tuné), ASR_ENDPOINT (gRPC auto-hébergé ; a priorité). Rappelez le NIM choisi et l'ID de fonction résolu avant de dépenser les crédits API.
3. La transcription ASR est intégrée à l'Étape 3b (gRPC NVCF + riva.client.ASRService.offline_recognize, même modèle d'auth que Stage 1). Pour des questions plus approfondies de protocole/auth, des catalogues NIM alternatifs, ou la configuration auto-hébergée de Riva NIM, renvoyez à /riva-asr.
4. KER est le titre. Vérification par ligne : les mots term marqués doivent apparaître dans l'ordre, contigus, adjacents dans l'hypothèse normalisée. cefazolin → cefa zolin est un échec. L'agrégation WER masque les défaillances cliniquement dangereuses ; les deux sont rapportés, KER est la porte.
5. La division par ipa_source est le chiffre unique le plus informatif du leaderboard. Le delta merriam-webster vs magpie_g2p prouve que le pipeline SSML override fonctionne réellement. Lisez-le à voix haute à l'utilisateur.
6. Routage de cas spéciaux. Les lignes merriam-webster bonnes, les lignes magpie_g2p mauvaises → écart de couverture de prononciation, pas une lacune du modèle. Routez vers /digital-health-clinical-asr-build Étape 2d. Ne recommandez PAS /digital-health-clinical-asr-finetune comme première réponse.
7. Ordre du leaderboard à cinq sections. Titre (WER/CER/KER/SER) → KER par entity_category → KER par ipa_source → KER par noise_level → KER par terme (pire d'abord). La section par ipa_source est obligatoire ; c'est la preuve que le pipeline SSML fonctionne.

Objectif

Évaluer un manifest ASR clinique, produire un leaderboard KER à cinq sections, et router l'utilisateur via l'arbre de décision post-évaluation. Les détails de méthodologie (définitions des métriques, normalisation, ordre du leaderboard, routage de cas spéciaux) se trouvent dans les Règles de Flux de Travail Critique ci-dessus et les Instructions ci-dessous.

Quand utiliser cette skill

Activez sur des phrases utilisateur comme :

• « Évaluez mon manifest ASR »
• « Quel est le KER sur Parakeet TDT v2 ? »
• « Lancez l'évaluation sur le cycle-N »
• « Comparez deux modèles ASR sur le benchmark clinique »
• « Générez le leaderboard »
• « J'ai un manifest.jsonl, comment l'évaluer ? »
• « Pourquoi KER est 0,4 quand WER est 0,07 ? »
• « Devrions-nous fine-tuner ? » (c'est la question du côté évaluation — l'arbre de décision post-évaluation se trouve dans cette skill)

Vérification de non-activation par mot-clé littéral — si le message de l'utilisateur contient l'un de ces termes : authentifier, clé API, bearer, ID de fonction, gRPC, streaming, chunking, batching, transcription retry, riva-build, riva-deploy, déploiement NIM, NGC, Docker, Container Toolkit, ou demande « quel modèle ASR est le meilleur » / « comparez des modèles » / « différences de vendeurs » — N'activez PAS le workflow d'évaluation. Appliquez la Règle de Flux de Travail Critique #1 ci-dessus pour router vers la skill sœur appropriée et arrêtez. Ceci s'applique même si l'utilisateur mentionne « KER » ou « évaluation » aux côtés du mot-clé.

Prérequis

• Un manifest au format NeMo avec les champs d'extension clinique (term, entity_category, ipa_source, voice_id, noise_level, context_type). Le schéma est documenté dans le fichier references/manifest-schema.md de la skill de build.
• NVIDIA_API_KEY exportée (prérequis Stage 1 toujours applicable).
• nvidia-riva-client + soundfile installés (prérequis Stage 1). Pour les détails des NIMs Riva auto-hébergés, voir /riva-asr Option B.
• Fichiers audio réellement présents sur disque — lancez le pré-vol d'existence audio du manifest depuis la référence manifest-schema avant de dépenser les crédits API.

Instructions

3a. Choisir le NIM ASR

Par défaut : nvidia/parakeet-tdt-0.6b-v2 via gRPC NVCF (hors ligne), ID de fonction d3fe9151-442b-4204-a70d-5fcc597fd610. Recommandation ASR anglais actuelle de NVIDIA — la plus rapide/bon marché du catalogue, et supportée dans la recette SFT standard de NeMo, donc la baseline Stage 3 et un fine-tune Stage 4 utilisent la même famille de modèles.

Trois boutons de surcharge de variables d'environnement (ASR_MODEL_NAME pour l'affichage du leaderboard, ASR_NVCF_FUNCTION_ID pour basculer vers un NIM hébergé différent, ASR_ENDPOINT pour gRPC auto-hébergé) plus le catalogue complet de NIMs alternatifs (Parakeet TDT 1.1B, Parakeet CTC 1.1B, Whisper Large v3, Nemotron streaming) avec IDs de fonction et notes de forme d'appel : references/offline-asr-recipe.md.

Rappelez le NIM choisi, l'ID de fonction résolu, et les surcharges de variables d'environnement à l'utilisateur avant de dépenser les crédits API. Un manifest de 200 lignes sur Parakeet TDT v2 hébergé est bon marché ; une exécution accidentelle contre le mauvais modèle sur un manifest de 1 000 lignes ne l'est pas.

3b. Transcrire

Pour chaque ligne de manifest.jsonl, transcrivez audio_filepath et écrivez per_sample.json (un objet JSON par ligne, JSONL ou un tableau JSON — choix de l'appelant) :

{
  "audio_filepath": "...",
  "ref": "<row.text>",
  "hyp": "<asr output>",
  "term": "<row.term>",
  "entity_category": "<row.entity_category>",
  "ipa_source": "<row.ipa_source>",
  "voice_id": "<row.voice_id>",
  "noise_level": "<row.noise_level>",
  "context_type": "<row.context_type>"
}

Recette (Python complète dans references/offline-asr-recipe.md) : transcribe_manifest(api_key, manifest_path, out_path, language_code="en-US") ouvre un flux gRPC hors ligne vers NVCF (ou vers ASR_ENDPOINT si défini pour Riva auto-hébergé), appelle riva.client.ASRService.offline_recognize par ligne — les phrases dans un manifest clinique sont ≤ 30 s donc pas de streaming/batching nécessaire — et écrit le JSONL ci-dessus. Même forme auth_for que la configuration de smoke test Stage 1. Le harnais agent transmet api_key explicitement ; la recette lit les trois surcharges de variables d'environnement (ASR_NVCF_FUNCTION_ID, ASR_MODEL_NAME, ASR_ENDPOINT) au sommet pour que les auditeurs voient les boutons en un seul endroit.

Fallback Whisper (quand le backend NVCF de Parakeet fonctionne mal avec CUDA illegal-memory-access depuis Triton) et Riva NIM auto-hébergé (ASR_ENDPOINT=localhost:50051) motifs de variables d'environnement : voir references/offline-asr-recipe.md (§Whisper fallback, §Self-hosted Riva NIM).

Boutons de résilience déférés à l'utilisateur. Si NVCF retourne RESOURCE_EXHAUSTED en milieu de batch, la boucle lève une exception sur cette ligne ; relancez à partir de la ligne défaillante. Le streaming/batching/retry-with-backoff sont hors périmètre — voir /riva-asr.

3c. Évaluer quatre métriques

Pour chaque ligne, calculez :

Normalisation (appliquez-la à ref et hyp avant toutes les quatre métriques) :

1. Minuscules.
2. Normalisation NFKD (guillemets intelligents → ASCII, etc.).
3. Supprimez la ponctuation sauf trait d'union.
4. Réduisez les suites d'espaces à un seul espace.

Recettes d'évaluation intégrées — normalize / edit_distance / wer / cer / ker / ser (pur Python, pas de dépendance jiwer) : voir references/scoring-recipes.md. Agrégez les lignes en prenant mean(score par ligne) pour chaque métrique.

KER strict — les mots du terme doivent apparaître dans l'ordre, adjacents dans l'hypothèse normalisée. C'est conservateur : cefazolin → cefa zolin compte comme un échec. C'est le bon choix cliniquement — une recherche de pharmacie en aval échouera sur le jeton mal orthographié.

KER n'influre pas les erreurs environnantes. Une ligne où le terme est correct et le reste de la phrase est un bazar score toujours KER=0 ; le WER sur cette ligne surfacera le problème plus large séparément.

3d. Ventilations + leaderboard

Écrivez un leaderboard markdown à cinq sections, dans cet ordre :

1. Titre — WER, CER, KER, SER globaux pour le modèle choisi.
2. KER par entity_category — médicament vs procédure vs anatomie vs ... C'est ce qui compte réellement à l'utilisateur pour le déploiement.
3. KER par ipa_source — le chiffre unique le plus informatif du leaderboard. Le delta entre les lignes merriam-webster et magpie_g2p est la preuve que le pipeline SSML override fonctionne réellement. Lisez cette section à voix haute à l'utilisateur.
4. KER par noise_level — les environnements cliniques sont bruyants. Les lignes snr_5db sont plus proches de la réalité que clean.
5. KER par terme (pire d'abord) — ce sont vos cibles de fine-tune Stage 4.

Un exemple représentatif de division ipa_source avec l'interprétation du delta merriam-webster vs magpie_g2p : references/scoring-recipes.md §Representative ipa_source split. Le delta raconte l'histoire du déploiement — si l'utilisateur voit un écart large et demande « devrions-nous fine-tuner ? », la réponse est pas encore ; routez-le vers le pipeline d'assurance qualité IPA de /digital-health-clinical-asr-build's (Stage 2d). Consultez l'arbre de décision ci-dessous.

Arbre de décision (après évaluation)

Lisez le KER de catégorie prioritaire (KER de médicament pour la plupart des workflows cliniques, KER de procédure pour les workflows chirurgicaux) et routez :

Cas spécial — les lignes merriam-webster marchent bien mais les lignes magpie_g2p sont mauvaises. C'est un écart de couverture d'indices de prononciation, pas une lacune du modèle. Routez vers /digital-health-clinical-asr-build Étape 2d (examen d'assurance qualité IPA), pas vers /digital-health-clinical-asr-finetune. Le fine-tuning sur un écart de prononciation TTS enseigne au modèle à mal reconnaître ses propres erreurs — la mauvaise correction.

Exemples

Scénario A — première évaluation sur un manifest de cycle-1 frais. Utilisateur : « J'ai manifest.jsonl avec 200 lignes audio clinique déjà, avec les champs term et entity_category. Comment l'évaluer ? » → Ignorez entièrement Stage 2. Lancez le pré-vol d'existence audio. Choisissez parakeet-tdt-0.6b-v2 (par défaut) et rappelez le choix + ID de fonction résolu. Lancez la recette d'étape 3b intégrée (transcribe_manifest(...)). Évaluez les quatre métriques. Produisez le leaderboard à cinq sections. Lisez la division par ipa_source à l'utilisateur. Appliquez l'arbre de décision contre le KER de médicament.

Scénario B — interprétation d'un résultat mixte. Utilisateur : « L'évaluation montre KER 0,05 sur les lignes tagguées merriam-webster mais 0,40 sur les lignes tagguées magpie_g2p. Devrions-nous fine-tuner ? » → Non — c'est le cas spécial. Le modèle va bien ; les indices de prononciation ne couvrent pas les termes de longue traîne. Routez l'utilisateur vers /digital-health-clinical-asr-build Étape 2d pour auditionner les lignes magpie_g2p et ajouter l'IPA vérifiée à pronunciation_overrides.csv. Relancez Stage 3 après la reconstruction avant de reconsidérer Stage 4.

Artefacts produits

• per_sample.json — résultats de transcription par ligne avec tous les champs d'extension clinique préservés (l'ASR hyp joint au ref et aux métadonnées du manifest)
• results.csv — scores WER/CER/KER/SER par ligne
• leaderboard_cycle<N>.md — rapport markdown à cinq sections

(Les noms de fichiers sont choisis par l'utilisateur ; les noms ci-dessus sont les conventions que le reste de cette skill suppose.)

Dépannage

• « Aucun manifest trouvé » → l'utilisateur a ignoré Stage 2. Routez vers /digital-health-clinical-asr-build ou confirmez $MANIFEST_PATH.
• Toutes les lignes KER=1 → décalage de normalisation entre ref et hyp. Appliquez les quatre étapes de normalisation aux deux côtés.
• Toutes les lignes KER=0 mais WER élevé → probablement manifest mal aligné (décalage de ligne audio). Vérifiez quelques paires (ref, hyp) à la main.
• merriam-webster bas, magpie_g2p élevé → écart de couverture de prononciation. Routez vers /digital-health-clinical-asr-build Étape 2d. Ne pas fine-tuner — le modèle n'est pas le problème.
• merriam-webster et magpie_g2p tous les deux élevés → vraie lacune du modèle. Stage 4 est la bonne route (manifest ≥ 100 lignes).
• Lignes clean bonnes, snr_5db explose → lacune de robustesse ; élargissez la diversité du bruit via /digital-health-clinical-asr-build.
• Résultats Riva-NIM et NeMo hors ligne divergent → prétraitement Riva / drapeaux riva-build. Routez vers /riva-asr-custom.
• RESOURCE_EXHAUSTED sur les grands manifests → relancez après 30 s ; découpez + relancez les lignes abandonnées. Backoff intégré : /riva-asr.
• Auth.__init__() got 'ssl_cert' / CUDA illegal-memory-access sur ID de fonction Parakeet : voir references/offline-asr-recipe.md (renommage ssl_root_cert + §Whisper fallback).

Tout le reste : identifiez le propriétaire en amont. Protocole ASR / déploiement NIM → /riva-asr. Évaluation → ici.

Limitations

• Anglais uniquement par défaut. La tokenization + normalisation supposent un script latin et un lexique en-US.
• KER strict-contigu est conservateur. Une quasi-erreur comme cefa zolin compte comme un échec. C'est intentionnel — les recherches en pharmacie échouent sur les quasi-erreurs. Les utilisateurs voulant une correspondance « douce » peuvent basculer vers la distance d'édition au niveau des phonèmes, ce qui est une extension de méthodologie, pas un ajustement de config.
• Un modèle par évaluation. La comparaison de deux modèles signifie lancer l'évaluation deux fois et diff les deux fichiers leaderboard_cycle<N>.md (ou étendre la recette pour écrire des lignes multi-modèles vous-même).
• Chemins hébergés uniquement supposés. Les NIMs auto-hébergés fonctionnent mais nécessitent d'abord /riva-nim-setup.

Étapes suivantes

• Avancer (KER > 0,3, manifest ≥ 100 lignes) : /digital-health-clinical-asr-finetune.
• Revenir à la construction (KER 0,1–0,3 sur première évaluation, ou écart magpie_g2p) : /digital-health-clinical-asr-build.
• Arrêter (KER < 0,1) : l'évaluation est saturée. Consolidez-la avant de déclarer la victoire.
• Latéral pour les détails du protocole ASR / auth / streaming / NIM auto-hébergé : /riva-asr.

Références

• references/offline-asr-recipe.md — recette Python complète de l'Étape 3b (transcribe_manifest, resolve_asr_config, build_asr_auth), catalogue d'ID de fonction avec notes de forme d'appel, fallback Whisper, configuration auto-hébergée de Riva NIM
• references/scoring-recipes.md — fonctions d'évaluation WER/CER/KER/SER pur Python avec la normalisation canonique à 4 étapes