Flywheel ASR clinique — Étape 3 (Évaluation)

⚠ Agent : lisez la section « Règles critiques du flux de travail » ci-dessous avant de répondre. Ce fichier SKILL.md est autonome — les répertoires evals/, references/ et assets/ sont des pointeurs, ils ne contiennent pas de données. Répondez directement aux questions de méthodologie contenues dans ce fichier ; n’invoquez des outils que lorsque l’utilisateur demande explicitement d’exécuter une opération sur un manifeste réel.

Vous représentez l’étape de notation et d’acheminement. L’utilisateur vous transmet un fichier manifest.jsonl au format NeMo (provenant soit de /digital-health-clinical-asr-build, soit d’une autre source). Vous le transcrivez via le NIM ASR choisi, évaluez quatre métriques, générez un classement en cinq sections et consultez l’arbre de décision pour déterminer si l’utilisateur doit passer à /digital-health-clinical-asr-finetune, revenir à /digital-health-clinical-asr-build ou s’arrêter et consolider l’évaluation.

Cette skill ne génère pas de contenu audio. Si le fichier manifest est manquant ou vide, redirigez l’utilisateur vers /digital-health-clinical-asr-build.

Les données audio quittent votre environnement — informez-en l’utilisateur avant l’envoi de tout extrait

Cette étape transmet le fichier WAV de chaque ligne du manifeste ainsi que son texte de référence à un service NVIDIA externe. Signalez-le avant d’effectuer le premier appel ASR :

Les extraits doivent être des fichiers audio synthétiques générés par l’étape 2 (Magpie TTS à partir d’une liste de termes sélectionnés par l’utilisateur) — et non des enregistrements audio réels de patients. Ne transmettez pas d’enregistrements ASR réels, d’entretiens réels avec des patients ni aucune donnée de santé protégée (PHI) via cette skill. L’évaluation s’effectue ensuite localement (WER/CER/KER/SER en Python pur, ou jiwer s’il est installé). L’étape d’évaluation en elle-même ne transmet rien ; seule l’étape ASR le fait.

Règles essentielles du flux de travail (à appliquer à chaque activation)

Pour les questions de méthodologie (structure du classement, définition du KER, arbre de décision), répondez à partir de ce fichier. N’invoquez pas d’outils, n’appelez pas d’autres compétences et n’exécutez pas de scripts, sauf si l’utilisateur demande explicitement d’effectuer une exécution sur un manifeste réel. Indiquez clairement ces éléments dans toute réponse :

1. Commencez par la sortie. Si l’utilisateur pose une question ne relevant pas de l’évaluation, redirigez-le et arrêtez le traitement sans exécuter de workflow :
   • Sélection / comparaison / NIM alternatifs du catalogue de modèles ASR → /riva-asr
   • Authentification ASR (clés API, jetons porteurs, identifiants de fonction) → /riva-asr
   • Protocole gRPC ASR, streaming, traitement par lots, découpage en blocs, tentatives de réessai → /riva-asr
   • Déploiement NIM / riva-build / riva-deploy → /riva-asr-custom
   • NGC / Docker / NVIDIA Container Toolkit → /riva-nim-setup
   • Pas encore de manifeste → /digital-health-clinical-asr-build
   • Souhaite effectuer un ajustement fin dès 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). Remplacements par variables d’environnement : ASR_MODEL_NAME (nom d’affichage dans le classement), ASR_NVCF_FUNCTION_ID (permet de basculer vers un autre NIM hébergé — par ex. Whisper Large v3 b702f636-… lorsque le backend Parakeet rencontre des dysfonctionnements, ou un NIM optimisé), ASR_ENDPOINT (gRPC auto-hébergé ; a la priorité). Renvoie le NIM choisi et l’identifiant de fonction résolu avant de dépenser des crédits API.
3. La transcription ASR est intégrée à l’étape 3b (NVCF gRPC + riva.client.ASRService.offline_recognize, même modèle d’authentification qu’à l’étape 1). Pour toute question plus approfondie concernant le protocole ou l’authentification, les autres catalogues NIM ou la configuration d’un NIM Riva auto-hébergé, consultez /riva-asr.
4. Le KER est le critère principal. Vérification ligne par ligne : les mots des termes signalés doivent apparaître dans l’ordre, de manière contiguë et adjacente dans l’hypothèse normalisée. « cefazolin » → « cefa zolin » est une erreur. Le WER agrégé masque des échecs cliniquement dangereux ; les deux sont signalés, le KER est le critère déterminant.
5. La répartition «by-ipa_source » est le chiffre unique le plus informatif du classement. L’écart entre merriam-webster et magpie_g2p prouve que le pipeline de remplacement SSML est réellement efficace. Lisez-le à voix haute à l’utilisateur.
6. Routage des cas particuliers. Lignes « merriam-webster » bonnes, lignes « magpie_g2p » mauvaises → écart de couverture de la prononciation, et non un écart de modèle. Revenez à /digital-health-clinical-asr-build, étape 2d. Ne recommandez PAS /digital-health-clinical-asr-finetune comme première réponse.
7. Ordre du classement en cinq sections. Titre (WER/CER/KER/SER) → KER par entity_category → KER par ipa_source → KER par noise_level → KER par terme, du pire au meilleur. La section «par ipa_source » est obligatoire ; elle prouve que le pipeline SSML fonctionne.

Objectif

Évaluer un manifeste de reconnaissance vocale clinique (ASR), générer un classement KER en cinq sections et orienter l’utilisateur via l’arbre de décision post-évaluation. Les détails méthodologiques (définitions des métriques, normalisation, ordre du classement, routage des cas particuliers) se trouvent dans les « Règles critiques du flux de travail » ci-dessus et dans les « Instructions » ci-dessous.

Quand utiliser cette compétence

À activer en réponse à des phrases de l’utilisateur telles que :

• « Évalue mon manifeste ASR »
• « Quel est le KER pour Parakeet TDT v2 ? »
• « Lance l'évaluation sur le cycle N »
• « Compare deux modèles ASR sur le benchmark clinique »
• « Génère le classement »
• « J'ai un fichier manifest.jsonl, comment puis-je l'évaluer ? »
• « Pourquoi le KER est-il de 0,4 alors que le WER est de 0,07 ? »
• « Faut-il procéder à un réglage fin ? » (il s’agit d’une question relative à l’évaluation — l’arbre de décision post-évaluation se trouve dans cette compétence)

Vérification de la non-activation des mots-clés littéraux — si le message de l'utilisateur contient l'un des termes suivants : « authenticate », « API key », « bearer », « function ID », « gRPC », « streaming », « chunking », « batching », « transcription retry », « riva-build », « riva-deploy », « NIM deploy », « NGC », Docker, Container Toolkit, ou s’il demande « quel modèle ASR est le meilleur » / « comparer les modèles » / « différences entre les fournisseurs » — NE PAS activer le workflow de notation. Appliquez la règle de workflow critique n° 1 ci-dessus pour rediriger vers la compétence sœur appropriée et arrêter le traitement. Cela s’applique même si l’utilisateur mentionne « KER » ou « eval » en plus du mot-clé.

Prérequis

• Un manifeste au format NeMo comportant les champs d’extension cliniques (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 compétence de construction.
• NVIDIA_API_KEY exportée (le prérequis de l’étape 1 s’applique toujours).
• nvidia-riva-client + soundfile installés (condition préalable de l’étape 1). Pour plus de détails sur Riva NIM auto-hébergé, consultez /riva-asr Option B.
• Fichiers audio effectivement présents sur le disque — exécutez le pré-contrôle « audio-existence » à partir du fichier manifest-schema avant de dépenser des crédits API.

Instructions

3a. Choisissez le NIM ASR

Par défaut: nvidia/parakeet-tdt-0.6b-v2 via NVCF gRPC (hors ligne), ID de fonction d3fe9151-442b-4204-a70d-5fcc597fd610. Recommandation actuelle de NVIDIA pour l’ASR en anglais — le modèle le plus rapide et le moins cher du catalogue, pris en charge dans la recette SFT standard de NeMo ; ainsi, la base de référence de l’étape 3 et l’ajustement fin de l’étape 4 utilisent la même famille de modèles.

Trois paramètres de configuration à modifier via des variables d’environnement d’exécution (ASR_MODEL_NAME pour l’affichage du classement, ASR_NVCF_FUNCTION_ID pour basculer vers un NIM hébergé différent, ASR_ENDPOINT pour le gRPC auto-hébergé), ainsi que le catalogue complet des NIM alternatifs (Parakeet TDT 1.1B, Parakeet CTC 1.1B, Whisper Large v3, Nemotron streaming) avec les identifiants de fonction et les remarques sur la structure des appels : references/offline-asr-recipe.md.

Indiquez à l’utilisateur le NIM choisi, l’ID de fonction résolu et toute modification des variables d’environnement avant de dépenser des crédits API. Un manifeste de 200 lignes sur un Parakeet TDT v2 hébergé ne coûte pas cher ; une exécution accidentelle avec le mauvais modèle sur un manifeste de 1 000 lignes, en revanche, coûte cher.

3b. Transcription

Pour chaque ligne du fichier manifest.jsonl, transcrivez le chemin d’accès au fichier audio (audio_filepath) et générez un fichier per_sample.json (un objet JSON par ligne, au format JSONL ou sous forme de tableau JSON — au choix de l’appelant) :

{
  "audio_filepath": "...",
  "ref": "",
  "hyp": "",
  "term": "",
  "entity_category": "",
  "ipa_source": "",
  "voice_id": "",
  "noise_level": "",
  "context_type": ""
}

Recette (code Python complet 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 configuré pour Riva auto-hébergé), appelle riva.client.ASRService.offline_recognize pour chaque ligne — les phrases d’un manifeste clinique durent ≤ 30 s, donc aucun streaming ni traitement par lots n’est nécessaire — et écrit le JSONL ci-dessus. Même structure auth_for que lors du test de validation de la configuration de l’étape 1. Le harnais de l’agent transmet explicitement l’api_key; la recette lit les trois variables d’environnement de remplacement (ASR_NVCF_FUNCTION_ID, ASR_MODEL_NAME, ASR_ENDPOINT) en haut de la page afin que les auditeurs puissent voir tous les paramètres de réglage au même endroit.

Modèles de variables d’environnement pourla solution de secours Whisper (lorsque le backend NVCF de Parakeet rencontre une erreur liée à un accès mémoire illégal CUDA provenant de Triton) et pour le Riva NIM auto-hébergé (ASR_ENDPOINT=localhost:50051) : voir references/offline-asr-recipe.md (§Rechute vers Whisper, §Riva NIM auto-hébergé).

Les paramètres de résilience sont laissés à la discrétion de l’utilisateur. Si NVCF renvoie RESOURCE_EXHAUSTED en cours de traitement par lots, la boucle s’arrête à cette ligne ; relancez à partir de la ligne où l’échec s’est produit. Le traitement en continu, par lots et les nouvelles tentatives avec délai d’attente ne sont pas pris en charge — voir /riva-asr.

3c. Évaluer quatre métriques

Pour chaque ligne, calculer :

Normalisation (à appliquer à la fois à « ref » et à « hyp » avant les quatre métriques) :

1. Mise en minuscules.
2. Normalisation NFKD (guillemets typographiques → ASCII, etc.).
3. Supprimer la ponctuation à l’exception du trait d’union.
4. Regrouper les séries d’espaces en un seul espace.

Recettes de notation en ligne — normalize / edit_distance / wer / cer / ker / ser (Python pur, sans dépendance jiwer ) : voir references/scoring-recipes.md. Agrégation sur les lignes en calculant la moyenne (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 une approche prudente : « cefazolin » → « cefa zolin » est considéré comme une erreur. C’est la bonne décision d’un point de vue clinique — une recherche en pharmacie en aval échouera sur le mot mal orthographié.

Le KER ne pénalise pas les erreurs environnantes. Une ligne où le terme est correct et où le reste de la phrase est incompréhensible obtient tout de même un score KER = 0 ; le WER de cette ligne mettra en évidence le problème plus général séparément.

3d. Répartitions + classement

Rédigez un classement au format Markdown en cinq sections, dans cet ordre:

1. Titre — WER, CER, KER et SER globaux pour le modèle choisi.
2. KER par catégorie d’entité — médicament vs procédure vs anatomie vs… C’est ce qui intéresse réellement l’utilisateur en vue d’un déploiement.
3. KER par source ipa — le chiffre le plus révélateur du classement. L’écart entre les lignes « merriam-webster » et « magpie_g2p » prouve que le pipeline de remplacement SSML 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 celles de type « clean ».
5. KER par terme (du pire au meilleur) — ce sont vos cibles de réglage fin pour la phase 4.

Un découpage ipa_source représentatif avec l’interprétation de l’écart entre « merriam-webster » et « magpie_g2p » : references/scoring-recipes.md §Découpage ipa_source représentatif. Le delta raconte l’histoire du déploiement — si l’utilisateur constate un écart important et demande « faut-il procéder à un ajustement fin ? », la réponse est « pas encore » ; redirigez-le vers le pipeline de contrôle qualité IPA de /digital-health-clinical-asr-build(étape 2d). Voir l’arbre de décision ci-dessous.

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

Lire le KER de la catégorie de priorité (KER « médicament » pour la plupart des workflows cliniques, KER « procédure » pour les workflows chirurgicaux) et acheminer :

Cas particulier — les lignes « merriam-webster » obtiennent de bons scores, mais celles de « magpie_g2p » sont mauvaises. Il s’agit d’une lacune dans la couverture des indices de prononciation, et non d’une lacune du modèle. Revenez à /digital-health-clinical-asr-build, étape 2d (révision QA de l’API), et non à /digital-health-clinical-asr-finetune. Un réglage fin visant à combler un écart de prononciation TTS apprend au modèle à mal reconnaître ses propres erreurs — ce n’est pas la bonne solution.

Exemples

Scénario A — première évaluation sur un manifeste « cycle-1 » vierge. Utilisateur : « Je dispose d’ un fichier manifest.jsonl contenant déjà 200 lignes d’audio clinique, avec les champs term et entity_category. Comment puis-je l’évaluer ? » → Ignorez complètement l’étape 2. Lancez le contrôle préalable « audio-existence ». Sélectionnez parakeet-tdt-0.6b-v2 (par défaut) et indiquez ce choix ainsi que l’identifiant de la fonction résolue. Exécutez la recette intégrée de l’étape 3b (transcribe_manifest(...)). Évaluez les quatre métriques. Générez le classement en cinq sections. Lisez à l’utilisateur la répartitionpar source IPA. Appliquez l’arbre de décision au KER des médicaments.

Scénario B — interprétation d’un résultat mitigé. Utilisateur : « L’évaluation indique un KER de 0,05 sur les lignes marquées « merriam-webster », mais de 0,40 sur celles marquées « magpie_g2p ». Dois-je affiner le modèle ? » → Non — il s’agit d’un cas particulier. Le modèle est correct ; les indications de prononciation ne couvrent pas les termes de longue traîne. Redirigez l’utilisateur vers l’étape 2d de /digital-health-clinical-asr-build pour qu’il écoute les lignes « magpie_g2p » et ajoute l’IPA vérifiée au fichier pronunciation_overrides.csv. Relancez l’étape 3 après la reconstruction avant de réexaminer l’étape 4.

Fichiers générés

• per_sample.json — résultats de transcription ligne par ligne avec tous les champs d’extension clinique conservés ( l’hyp ASR est associé à la référence et aux métadonnées du manifeste)
• results.csv — scores WER/CER/KER/SER par ligne
• leaderboard_cycle.md — rapport Markdown en cinq sections

(Les noms de fichiers sont choisis par l’utilisateur ; les noms ci-dessus correspondent aux conventions utilisées dans la suite de cette compétence.)

Dépannage

• « Aucun manifeste trouvé » → l’utilisateur a ignoré l’étape 2. Accédez à /digital-health-clinical-asr-build ou vérifiez $MANIFEST_PATH.
• Toutes les lignes ont KER=1 → incohérence de normalisation entre ref et hyp. Appliquez les quatre étapes de normalisation aux deux côtés.
• Toutes les lignes ont KER=0 mais un WER élevé → manifeste probablement mal aligné (incohérence entre les lignes audio). Vérifiez manuellement quelques paires (référence, hypothèse).
• merriam-webster faible, magpie_g2p élevé → écart de couverture de la prononciation. Accédez à /digital-health-clinical-asr-build, étape 2d. Ne procédez pas à un réglage fin — le modèle n’est pas en cause.
• Valeurs élevées à la fois pour merriam-webster et magpie_g2p → véritable lacune du modèle. La phase 4 est la bonne voie à suivre (manifeste ≥ 100 lignes).
• Lignespropres: tout va bien, mais le snr_5db grimpe en flèche → lacune de robustesse ; élargir la diversité du bruit via /digital-health-clinical-asr-build.
• Les résultats de Riva-NIM et de NeMo hors ligne divergent → prétraitement Riva / indicateurs riva-build. Accédez à /riva-asr-custom.
• ErreurRESOURCE_EXHAUSTED sur les manifestes volumineux → réessayer après 30 s ; découper et réexécuter les lignes perdues. Délai d’attente intégré : /riva-asr.
• Auth.__init__() a reçu « ssl_cert » / accès mémoire illégal CUDA sur l’ID de fonction Parakeet: voir references/offline-asr-recipe.md (renommer ssl_root_cert + solution de secours §Whisper).

Autres cas : identifier le propriétaire en amont. Protocole ASR / déploiement NIM → /riva-asr. Notation → ici.

Limitations

• Anglais uniquement par défaut. La tokenisation et la normalisation supposent l’utilisation de l’alphabet latin et du lexique en-US.
• Le KER strictement contigu est conservateur. Un « near-miss » comme « cefa zolin » est considéré comme un échec. C’est intentionnel : les recherches en pharmacie échouent en cas de « near-miss ». Les utilisateurs souhaitant une correspondance « souple » peuvent passer à la distance d’édition au niveau des phonèmes, ce qui constitue une extension de la méthodologie et non un simple ajustement de configuration.
• Un modèle par exécution d’évaluation. Comparer deux modèles implique d’exécuter l’évaluation deux fois et de comparer les deux fichiers `leaderboard_cycle.md ` (ou d’étendre la recette pour écrire vous-même des lignes multi-modèles).
• On part du principe que les chemins sont exclusivement hébergés. Les NIM auto-hébergés fonctionnent, mais nécessitent au préalable l’exécution de la commande /riva-nim-setup.

Prochaines étapes

• Avance (KER > 0,3, manifeste ≥ 100 lignes) : /digital-health-clinical-asr-finetune.
• Retour à la phase de construction (KER compris entre 0,1 et 0,3 lors de la première évaluation, ou écart magpie_g2p ) : /digital-health-clinical-asr-build.
• Arrêt (KER < 0,1) : l’évaluation est saturée. Renforcez le modèle avant de crier victoire.
• Pour plus de détails sur le protocole ASR, l’authentification, le streaming et le 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’identifiants de fonctions avec notes sur la forme des appels, solution de secours Whisper, configuration du NIM Riva auto-hébergé
• references/scoring-recipes.md — fonctions de notation WER/CER/KER/SER en Python pur avec la normalisation canonique en 4 étapes