Lar
digital-health-clinical-asr-eval
NVIDIA/skills
Avalie um manifesto clínico ASR em relação a um NIM escolhido, gere um ranking KER com cinco seções e direcione o usuário por meio de uma árvore de decisão pós-avaliação.
...Expandir tudoFlywheel Clínico do ASR — Estágio 3 (Avaliação)
⚠ Agente: leia a seção “Regras críticas do fluxo de trabalho” abaixo antes de responder. Este arquivo SKILL.md é autônomo —
as pastas evals/,references/eassets/são apenas referências, não contêm dados de trabalho. Responda às perguntas de metodologia diretamente a partir deste arquivo; só invoque ferramentas quando o usuário solicitar explicitamente a execução com base em um manifesto real.
Você está na etapa de pontuação e roteamento. O usuário chega com um arquivo manifest.jsonl no formato NeMo (seja proveniente de /digital-health-clinical-asr-build ou trazido de outro lugar). Você o transcreve por meio do NIM de ASR escolhido, avalia quatro métricas, gera um quadro de classificação com cinco seções e consulta a árvore de decisão para determinar se o usuário deve avançar para /digital-health-clinical-asr-finetune, retornar a /digital-health-clinical-asr-build ou interromper e otimizar a avaliação.
Esta skill não gera áudio. Se o manifesto estiver ausente ou vazio, redirecione o usuário de volta para /digital-health-clinical-asr-build.
O áudio sai do seu ambiente — informe isso ao usuário antes que qualquer clipe seja enviado
Esta etapa transmite o arquivo WAV de cada linha do manifesto, juntamente com seu texto de referência, para um serviço externo da NVIDIA. Informe isso antes de invocar a primeira chamada de ASR:
| Serviço | O que é enviado | Quando |
|---|---|---|
NVIDIA NVCF Parakeet/Nemotron ASR (grpc.nvcf.nvidia.com) |
Todos os clipes de áudio referenciados pelo manifesto (bytes PCM brutos), além da transcrição de referência e dos metadados de extensão clínica para pontuação | Etapa 3b, uma chamada por linha do manifesto |
Os clipes devem ser áudio sintético gerado pela Etapa 2 (Magpie TTS com base em uma lista de termos selecionada pelo usuário) — não áudio real de pacientes. Não envie gravações reais de ASR, consultas reais com pacientes ou quaisquer informações de saúde protegidas (PHI) por meio desta habilidade. A pontuação é então executada localmente (WER/CER/KER/SER em Python puro ou jiwer, se instalado). A etapa de pontuação em si não transmite nada; apenas a etapa de ASR o faz.
Regras críticas do fluxo de trabalho (aplicáveis a cada ativação)
Para questões de metodologia (estrutura da tabela de classificação, definição de KER, árvore de decisão), responda com base neste arquivo. Não invoque ferramentas, não chame outras habilidades nem execute scripts, a menos que o usuário solicite explicitamente a execução com base em um manifesto real. Destaque esses fatos em qualquer resposta:
- Saída antecipada primeiro. Se o usuário estiver perguntando sobre algo fora da pontuação, redirecione e interrompa sem executar nenhum fluxo de trabalho:
- Seleção/comparação do catálogo de modelos ASR / NIMs alternativos →
/riva-asr - Autenticação ASR (chaves de API, tokens de portador, IDs de função) →
/riva-asr - Protocolo gRPC do ASR, streaming, processamento em lote, fragmentação, novas tentativas →
/riva-asr - Implantação de NIM /
riva-build/riva-deploy→/riva-asr-custom - NGC / Docker / NVIDIA Container Toolkit →
/riva-nim-setup - Ainda não há manifesto →
/digital-health-clinical-asr-build - Deseja realizar o ajuste fino agora com um KER conhecido →
/digital-health-clinical-asr-finetune
- Seleção/comparação do catálogo de modelos ASR / NIMs alternativos →
- O NIM padrão do ASR é
nvidia/parakeet-tdt-0.6b-v2(ID da função NVCFd3fe9151-442b-4204-a70d-5fcc597fd610, gRPC offline). Substituições de variáveis de ambiente:ASR_MODEL_NAME(nome exibido no quadro de líderes),ASR_NVCF_FUNCTION_ID(trocar para um NIM hospedado diferente — por exemplo, Whisper Large v3b702f636-…enquanto o backend do Parakeet estiver com falha, ou um NIM ajustado),ASR_ENDPOINT(gRPC auto-hospedado; tem prioridade). Reenvie o NIM escolhido e o ID da função resolvido antes de gastar créditos da API. - A transcrição do ASR é incorporada na Etapa 3b (NVCF gRPC +
riva.client.ASRService.offline_recognize, mesmo padrão de autenticação da Etapa 1). Para questões mais aprofundadas sobre protocolo/autenticação, catálogos alternativos de NIM ou configuração do NIM Riva auto-hospedado, consulte/riva-asr. - O KER é o destaque. Verificação por linha: as
palavras-chavesinalizadas devem aparecer em ordem, contíguas e adjacentes na hipótese normalizada.cefazolin → cefa zoliné uma falha. O WER agregado oculta falhas clinicamente perigosas; ambas são relatadas, mas o KER é o filtro. - A divisão
por ipa_sourceé o único número mais informativo no quadro de classificação. A diferença entremerriam-websteremagpie_g2pcomprova que o pipeline de substituição SSML está funcionando de fato. Leia em voz alta para o usuário. - Roteamento para casos especiais. Linhas
do merriam-webstercorretas, linhasdo magpie_g2pincorretas → lacuna na cobertura da pronúncia, não uma lacuna no modelo. Retorne à etapa 2dde /digital-health-clinical-asr-build. NÃO recomende/digital-health-clinical-asr-finetunecomo primeira resposta. - Ordem do quadro de líderes em cinco seções. Título (WER/CER/KER/SER) → KER por
entity_category→ KER poripa_source→ KER pornoise_level→ KER por termo, do pior para o melhor. A seçãopor ipa_sourceé obrigatória; é a prova de que o pipeline SSML funciona.
Objetivo
Avaliar um manifesto de ASR clínico, produzir um ranking KER de cinco seções e direcionar o usuário por meio da árvore de decisão pós-avaliação. Detalhes da metodologia (definições de métricas, normalização, ordem do ranking, direcionamento em casos especiais) estão nas Regras Críticas do Fluxo de Trabalho acima e nas Instruções abaixo.
Quando usar esta habilidade
Ative em frases do usuário como:
- “Avalie meu manifesto de ASR”
- “Qual é o KER do Parakeet TDT v2?”
- “Execute a avaliação no ciclo N”
- “Compare dois modelos de ASR no benchmark clínico”
- “Gere a tabela de classificação”
- "Tenho um arquivo manifest.jsonl, como faço para avaliá-lo?"
- "Por que o KER é 0,4 se o WER é 0,07?"
- "Devemos fazer um ajuste fino?" (essa é a pergunta do lado da avaliação — a árvore de decisão pós-avaliação está nesta skill)
Verificação de não ativação por palavras-chave literais — se a mensagem do usuário contiver qualquer uma das seguintes palavras: authenticate, API key, bearer, function ID, gRPC, streaming, chunking, batching, transcription retry, riva-build, riva-deploy, NIM deploy, NGC, Docker, Container Toolkit, ou perguntar “qual modelo de ASR é o melhor” / “comparar modelos” / “diferenças entre fornecedores” — NÃO ative o fluxo de trabalho de pontuação. Aplique a Regra Crítica de Fluxo de Trabalho nº 1 acima para direcionar para a skill irmã correta e interromper. Isso se aplica mesmo que o usuário mencione “KER” ou “eval” junto com a palavra-chave.
Pré-requisitos
- Um manifesto no formato NeMo com os campos de extensão clínica (
term,entity_category,ipa_source,voice_id,noise_level,context_type). O esquema está documentado no arquivoreferences/manifest-schema.mdda skill de construção. NVIDIA_API_KEYexportada (o pré-requisito da Etapa 1 ainda se aplica).nvidia-riva-client+soundfileinstalados (pré-requisito da Etapa 1). Para detalhes sobre o Riva NIM auto-hospedado, consulte/riva-asrOpção B.- Arquivos de áudio efetivamente presentes no disco — execute a verificação prévia de existência de áudio (audio-existence) a partir da referência manifest-schema antes de gastar créditos da API.
Instruções
3a. Escolha o NIM ASR
Padrão: nvidia/parakeet-tdt-0.6b-v2 via NVCF gRPC (offline), ID da função d3fe9151-442b-4204-a70d-5fcc597fd610. Recomendação atual da NVIDIA para ASR em inglês — a mais rápida e econômica do catálogo, e compatível com a receita SFT padrão do NeMo, de modo que a linha de base do Estágio 3 e o ajuste fino do Estágio 4 utilizam a mesma família de modelos.
Três controles de substituição de variáveis de ambiente em tempo de execução (ASR_MODEL_NAME para exibição no quadro de líderes, ASR_NVCF_FUNCTION_ID para alternar para um NIM hospedado diferente, ASR_ENDPOINT para gRPC auto-hospedado), além do catálogo completo de NIMs alternativos (Parakeet TDT 1.1B, Parakeet CTC 1.1B, Whisper Large v3, streaming Nemotron) com IDs de função e notas sobre o formato das chamadas: references/offline-asr-recipe.md.
Informe ao usuário o NIM escolhido, o ID da função resolvido e quaisquer substituições de variáveis de ambiente antes de gastar créditos da API. Um manifesto de 200 linhas no Parakeet TDT v2 hospedado é barato; uma execução acidental com o modelo errado em um manifesto de 1.000 linhas, não.
3b. Transcrever
Para cada linha no manifest.jsonl, transcreva o audio_filepath e grave o per_sample.json (um objeto JSON por linha, JSONL ou uma matriz JSON — à escolha do chamador):
{
"audio_filepath": "...",
"ref": "",
"hyp": "",
"term": "",
"entity_category": "",
"ipa_source": "",
"voice_id": "",
"noise_level": "",
"context_type": ""
}
Receita (código Python completo em references/offline-asr-recipe.md): transcribe_manifest(api_key, manifest_path, out_path, language_code="en-US") abre um fluxo gRPC offline para o NVCF (ou para ASR_ENDPOINT, se configurado para o Riva auto-hospedado), chama riva.client.ASRService.offline_recognize por linha — as frases em um manifesto clínico têm duração ≤ 30 s, portanto não há necessidade de streaming/processamento em lote — e grava o JSONL acima. O formato de auth_for é o mesmo do teste de verificação da configuração do Estágio 1. O harness do agente passa o `api_key` explicitamente; a receita lê as três substituições de variáveis de ambiente (ASR_NVCF_FUNCTION_ID, ASR_MODEL_NAME, ASR_ENDPOINT) no início, para que os auditores vejam os parâmetros de ajuste em um único lugar.
Padrões de variáveis de ambiente parao fallback do Whisper (quando o backend NVCF do Parakeet apresenta falha devido a acesso ilegal à memória CUDA proveniente do Triton) e para o Riva NIM auto-hospedado (ASR_ENDPOINT=localhost:50051): consulte references/offline-asr-recipe.md (§Fallback do Whisper, §Riva NIM auto-hospedado).
Controles de resiliência deixados a cargo do usuário. Se o NVCF retornar RESOURCE_EXHAUSTED no meio de um lote, o loop será interrompido nessa linha; execute novamente a partir da linha com falha. Streaming/processamento em lote/retenta com recuo estão fora do escopo — consulte /riva-asr.
3c. Calcular quatro métricas
Para cada linha, calcule:
| Métrica | O que ela mede | Por que a mantemos |
|---|---|---|
| WER | Taxa de erro de palavras (Levenshtein em tokens, após normalização) | Padrão do setor; ferramenta pouco precisa para fins clínicos |
| CER | Taxa de erros de caracteres | Detecta erros de quase omissão em nomes compostos longos |
| KER ★ | Taxa de erro de palavra-chave — o termo sinalizado apareceu na hipótese (correspondência normalizada e contígua )? |
Sinal clínico principal |
| SER | Taxa de erro da frase (1 se houver algum erro, 0 se estiver perfeita) | Limite de plausibilidade; o que o médico vivencia |
Normalização (aplicar tanto à referência quanto à hipótese antes das quatro métricas):
- Letras minúsculas.
- Normalização NFKD (aspas curvas → ASCII, etc.).
- Remover pontuação, exceto o hífen.
- Reduzir sequências de espaços em branco a um único espaço.
Receitas de pontuação embutidas — normalize / edit_distance / wer / cer / ker / ser (Python puro, sem dependência do jiwer ): consulte references/scoring-recipes.md. Agregue pelas linhas calculando a média (pontuação por linha) para cada métrica.
KER estrito — as palavras do termo devem aparecer em ordem, adjacentes na hipótese normalizada. Isso é conservador: cefazolina → cefa zolina conta como um erro. Essa é a decisão correta clinicamente — uma consulta posterior na farmácia falhará devido ao token com erro ortográfico.
O KER não penaliza erros circundantes. Uma linha em que o termo esteja correto e o restante da frase seja irrelevante ainda recebe pontuação KER=0; o WER nessa linha revelará o problema mais amplo separadamente.
3d. Detalhamento + tabela de classificação
Escreva um quadro de classificação em Markdown com cinco seções, nesta ordem:
- Título — WER, CER, KER e SER gerais para o modelo escolhido.
- KER por
categoria de entidade— medicamento x procedimento x anatomia x ... É isso que realmente interessa ao usuário para a implantação. - KER por
ipa_source— o único número mais informativo no quadro de classificação. A diferença entre as linhasdo Merriam-Websteredo magpie_g2pé a prova de que o pipeline de substituição do SSML está funcionando de verdade. Leia esta seção em voz alta para o usuário. - KER por
noise_level— os ambientes clínicos são ruidosos. As linhassnr_5dbestão mais próximas da realidade do queas limpas. - KER por termo (do pior ao melhor) — essas são suas metas de ajuste fino do Estágio 4.
Uma divisão representativa do ipa_source com a interpretação da diferença entre merriam-webster e magpie_g2p: references/scoring-recipes.md §Divisão representativa do ipa_source. O delta conta a história da implantação — se o usuário perceber uma grande diferença e perguntar “devemos fazer o ajuste fino?”, a resposta é “ainda não”; encaminhe-o de volta ao pipeline de controle de qualidade de IPA do /digital-health-clinical-asr-build(Estágio 2d). Veja a árvore de decisão abaixo.
Árvore de decisão (após a avaliação)
Leia o KER da categoria de prioridade (KER de medicamento para a maioria dos fluxos de trabalho clínicos, KER de procedimento para fluxos de trabalho cirúrgicos) e encaminhe:
| KER por categoria de prioridade | Recomendar |
|---|---|
| > 0,3 | /digital-health-clinical-asr-finetune. O manifesto já está pronto para o formato NeMo. Observação: o número mínimo de linhas para um sinal de ajuste fino confiável é ≥ 100; se o manifesto for menor, aumente-o primeiro por meio de /digital-health-clinical-asr-build. |
| 0,1 – 0,3 | Expanda a lista de termos (volte a /digital-health-clinical-asr-build com novos termos de domínio — geralmente revela mais falhas de forma mais econômica do que o ajuste) ou faça o ajuste fino. Em uma primeira avaliação, expanda. Em uma avaliação posterior, quando você já tiver ampliado o manifesto, faça o ajuste. |
| < 0,1 | Linha de base sólida. Não faça ajuste ainda — você estaria otimizando com base em uma métrica saturada. Intensifique a avaliação: adicione vozes, níveis de ruído, contextos e termos adversários. Volte para /digital-health-clinical-asr-build. |
Caso especial — as linhas do “merriam-webster” apresentam boa pontuação, mas as do “magpie_g2p” são ruins. Trata-se de uma lacuna na cobertura das dicas de pronúncia, não de uma falha no modelo. Volte para /digital-health-clinical-asr-build Etapa 2d (revisão de QA do IPA), e não para /digital-health-clinical-asr-finetune. O ajuste fino com base em uma lacuna de pronúncia do TTS ensina o modelo a reconhecer erroneamente seus próprios erros — a correção errada.
Exemplos
Cenário A — primeira avaliação em um manifesto novo do ciclo 1. Usuário: “Tenho um manifest.jsonl com 200 linhas de áudio clínico, com os campos term e entity_category. Como faço para avaliá-lo?” → Pule o Estágio 2 por completo. Execute a verificação prévia de existência de áudio. Escolha parakeet-tdt-0.6b-v2 (padrão) e repita a escolha + o ID da função resolvida. Execute a receita incorporada da Etapa 3b (transcribe_manifest(...)). Avalie as quatro métricas. Gere o ranking de cinco seções. Leia a divisãopor ipa_source para o usuário. Aplique a árvore de decisão em relação ao KER de medicamentos.
Cenário B — interpretando um resultado misto. Usuário: “A avaliação mostra KER de 0,05 nas linhas marcadas como ‘merriam-webster’, mas 0,40 nas linhas marcadas como ‘magpie_g2p’. Devo fazer um ajuste fino?” → Não — este é um caso especial. O modelo está correto; as dicas de pronúncia não estão cobrindo os termos de cauda longa. Redirecione o usuário de volta para /digital-health-clinical-asr-build, Etapa 2d, para testar as linhas “magpie_g2p” e acrescentar o IPA verificado ao arquivo pronunciation_overrides.csv. Reexecute a Etapa 3 após a reconstrução antes de reconsiderar a Etapa 4.
Artefatos produzidos
per_sample.json— resultados de transcrição por linha com todos os campos de extensão clínica preservados (o ASRhypvinculado àreferênciae aos metadados do manifesto)results.csv— pontuações WER/CER/KER/SER por linhaleaderboard_cycle— relatório em Markdown com cinco seções.md
(Os nomes dos arquivos são escolhidos pelo usuário; os nomes acima são convenções que o restante desta skill assume.)
Solução de problemas
- “Nenhum manifesto encontrado” → o usuário pulou a Etapa 2. Acesse
/digital-health-clinical-asr-buildou confirme$MANIFEST_PATH. - Todas as linhas com KER=1 → incompatibilidade de normalização entre
refehyp. Aplique as quatro etapas de normalização a ambos os lados. - Todas as linhas com KER=0, mas WER alto → provavelmente há um manifesto desalinhado (incompatibilidade nas linhas de áudio). Verifique manualmente alguns pares
(ref, hyp). merriam-websterbaixo,magpie_g2palto → lacuna na cobertura de pronúncia. Acesse/digital-health-clinical-asr-buildEtapa 2d. Não faça ajuste fino — o modelo não é o problema.- Tanto
o merriam-websterquantoo magpie_g2paltos → lacuna real no modelo. O Estágio 4 é o caminho correto (manifesto com ≥ 100 linhas). - Linhas
limpasestão boas,snr_5dbdispara → lacuna de robustez; expandir a diversidade de ruído via/digital-health-clinical-asr-build. - Os resultados do Riva-NIM e do NeMo offline divergem → pré-processamento do Riva / sinalizadores
do riva-build. Siga para/riva-asr-custom. RESOURCE_EXHAUSTEDem manifestos grandes → tente novamente após 30 s; divida em fatias + reexecute as linhas descartadas. Retardamento integrado:/riva-asr.Auth.__init__() recebeu 'ssl_cert'/ acesso ilegal à memória CUDA no ID da função do Parakeet: consultereferences/offline-asr-recipe.md(renomear ssl_root_cert + fallback do §Whisper).
Outros casos: identifique o proprietário upstream. Protocolo ASR / implantação NIM → /riva-asr. Pontuação → aqui.
Limitações
- Padrão: apenas em inglês. A tokenização + normalização pressupõem o alfabeto latino e o léxico en-US.
- O KER estritamente contíguo é conservador. Um quase-erro como
“cefa zolin”conta como um erro. Isso é intencional — consultas farmacêuticas falham em casos de quase-erros. Usuários que desejarem uma correspondência “suave” podem mudar para a distância de edição no nível do fonema, o que é uma extensão da metodologia, não um ajuste de configuração. - Um modelo por execução de avaliação. Comparar dois modelos significa executar a avaliação duas vezes e comparar os dois arquivos
`leaderboard_cycle(ou estender a receita para escrever você mesmo linhas com vários modelos)..md` - Presume-se o uso exclusivo de modelos hospedados. NIMs auto-hospedados funcionam, mas exigem a execução prévia
do /riva-nim-setup.
Próximos passos
- Avançar (KER > 0,3, manifesto ≥ 100 linhas):
/digital-health-clinical-asr-finetune. - Voltar à compilação (KER 0,1–0,3 na primeira avaliação ou diferença em relação ao
magpie_g2p):/digital-health-clinical-asr-build. - Parar (KER < 0,1): a avaliação está saturada. Fortaleça o sistema antes de declarar vitória.
- Detalheslaterais sobre o protocolo ASR / autenticação / streaming / NIM auto-hospedado:
/riva-asr.
Referências
references/offline-asr-recipe.md— receita completa em Python da Etapa 3b (transcribe_manifest,resolve_asr_config,build_asr_auth), catálogo de IDs de funções com notas sobre o formato das chamadas, fallback do Whisper, configuração do NIM do Riva auto-hospedadoreferences/scoring-recipes.md— funções de pontuação WER/CER/KER/SER em Python puro com a normalização canônica de 4 etapas
---
name: digital-health-clinical-asr-eval
description: Score a clinical ASR manifest against a chosen NIM, produce a five-section KER leaderboard, and route the user via a post-eval decision tree.
license: Apache-2.0
---
<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->
# Clinical ASR Flywheel — Stage 3 (Eval)
> **⚠ Agent: read the Critical Workflow Rules section below before answering.** This SKILL.md is self-contained — `evals/`, `references/`, and `assets/` are pointers, not load-bearing. Answer methodology questions from this file directly; only invoke tools when the user explicitly asks to execute against a real manifest.
You are the **score-and-route** stage. The user arrives with a NeMo-format `manifest.jsonl` (either from `/digital-health-clinical-asr-build` or carried in from elsewhere). You transcribe it via the chosen ASR NIM, score four metrics, produce a five-section leaderboard, and read the decision tree to decide whether the user should advance to `/digital-health-clinical-asr-finetune`, loop back to `/digital-health-clinical-asr-build`, or stop and harden the eval.
**This skill does not generate audio.** If the manifest is missing or empty, send the user back to `/digital-health-clinical-asr-build`.
## Audio leaves your environment — disclose this to the user before any clip is sent
This stage transmits each manifest row's WAV file plus its reference text to an external NVIDIA service. Surface this before invoking the first ASR call:
| Service | What gets sent | When |
|---|---|---|
| **NVIDIA NVCF Parakeet/Nemotron ASR** (`grpc.nvcf.nvidia.com`) | Every audio clip referenced by the manifest (raw PCM bytes), plus the reference transcript and the clinical-extension metadata for scoring | Step 3b, one call per manifest row |
The clips should be **synthetic audio generated by Stage 2** (Magpie TTS over a user-curated term list) — not real patient audio. **Do not pass real ASR recordings, real patient encounters, or any PHI through this skill.** Scoring then runs locally (pure-Python WER/CER/KER/SER, or `jiwer` if installed). The scoring step itself does not transmit anything; only the ASR step does.
## Critical workflow rules (apply on every activation)
For methodology questions (leaderboard structure, KER definition, decision tree), answer from this file. Don't invoke tools, call other skills, or run scripts unless the user explicitly asks to execute against a real manifest. Surface these facts in any response:
1. **Off-ramp first.** If the user is asking about something outside scoring, route and stop without running any workflow:
- ASR model-catalog selection / comparison / alternative NIMs → `/riva-asr`
- ASR auth (API keys, bearer tokens, function IDs) → `/riva-asr`
- ASR gRPC protocol, streaming, batching, chunking, retries → `/riva-asr`
- NIM deploy / `riva-build` / `riva-deploy` → `/riva-asr-custom`
- NGC / Docker / NVIDIA Container Toolkit → `/riva-nim-setup`
- No manifest yet → `/digital-health-clinical-asr-build`
- Wants to fine-tune now with a known KER → `/digital-health-clinical-asr-finetune`
2. **Default ASR NIM is `nvidia/parakeet-tdt-0.6b-v2`** (NVCF function-id `d3fe9151-442b-4204-a70d-5fcc597fd610`, offline gRPC). Env-var overrides: `ASR_MODEL_NAME` (leaderboard display name), `ASR_NVCF_FUNCTION_ID` (swap to a different hosted NIM — e.g. Whisper Large v3 `b702f636-…` while the Parakeet backend is faulting, or a fine-tuned NIM), `ASR_ENDPOINT` (self-hosted gRPC; takes precedence). Echo the chosen NIM **and the resolved function-id** back before spending API credits.
3. **ASR transcription is inlined in Step 3b** (NVCF gRPC + `riva.client.ASRService.offline_recognize`, same auth pattern as Stage 1). For deeper protocol/auth questions, alternative NIM catalogs, or self-hosted Riva NIM configuration, defer to `/riva-asr`.
4. **KER is the headline.** Per-row check: the flagged `term` words must appear *in order, contiguous, adjacent* in the normalized hypothesis. `cefazolin → cefa zolin` is a miss. Aggregate WER hides clinically dangerous failures; both are reported, KER is the gate.
5. **The by-`ipa_source` split is the most informative single number** in the leaderboard. The `merriam-webster` vs `magpie_g2p` delta proves the SSML override pipeline is doing real work. Read it aloud to the user.
6. **Special-case routing.** `merriam-webster` rows good, `magpie_g2p` rows bad → pronunciation-coverage gap, **not** a model gap. Route back to `/digital-health-clinical-asr-build` Step 2d. **Do NOT recommend `/digital-health-clinical-asr-finetune`** as a first response.
7. **Five-section leaderboard order.** Headline (WER/CER/KER/SER) → KER by `entity_category` → KER by `ipa_source` → KER by `noise_level` → Per-term KER worst-first. The by-`ipa_source` section is mandatory; it is the proof the SSML pipeline works.
## Purpose
Score a clinical-ASR manifest, produce a five-section KER leaderboard, and route the user via the post-eval decision tree. Methodology details (metric definitions, normalization, leaderboard order, special-case routing) live in Critical Workflow Rules above and Instructions below.
## When to use this skill
Activate on user phrases like:
- "Score my ASR manifest"
- "What's the KER on Parakeet TDT v2?"
- "Run the eval on cycle-N"
- "Compare two ASR models on the clinical benchmark"
- "Generate the leaderboard"
- "I have a manifest.jsonl, how do I score it?"
- "Why is KER 0.4 when WER is 0.07?"
- "Should we fine-tune?" *(this is the eval-side question — the post-eval decision tree lives in this skill)*
**Literal-keyword non-activation check** — if the user's message contains any of `authenticate`, `API key`, `bearer`, `function ID`, `gRPC`, `streaming`, `chunking`, `batching`, `transcription retry`, `riva-build`, `riva-deploy`, `NIM deploy`, `NGC`, `Docker`, `Container Toolkit`, or asks "which ASR model is best" / "compare models" / "vendor differences" — **do NOT activate** the scoring workflow. Apply Critical Workflow Rule #1 above to route to the right sibling skill and stop. This applies even if the user mentions "KER" or "eval" alongside the keyword.
## Prerequisites
- **A NeMo-format manifest** with the clinical extension fields (`term`, `entity_category`, `ipa_source`, `voice_id`, `noise_level`, `context_type`). The schema is documented in the build skill's `references/manifest-schema.md`.
- **`NVIDIA_API_KEY`** exported (Stage 1 prerequisite still applies).
- **`nvidia-riva-client` + `soundfile`** installed (Stage 1 prerequisite). For self-hosted Riva NIM details, see `/riva-asr` Option B.
- **Audio files actually present on disk** — run the audio-existence pre-flight from the manifest-schema reference before spending API credits.
## Instructions
### 3a. Pick the ASR NIM
**Default**: `nvidia/parakeet-tdt-0.6b-v2` via NVCF gRPC (offline), function-id `d3fe9151-442b-4204-a70d-5fcc597fd610`. NVIDIA's current English ASR recommendation — fastest/cheapest in the catalog, and supported in NeMo's stock SFT recipe so the Stage 3 baseline and a Stage 4 fine-tune ride the same model family.
Three runtime env-var override knobs (`ASR_MODEL_NAME` for leaderboard display, `ASR_NVCF_FUNCTION_ID` to swap to a different hosted NIM, `ASR_ENDPOINT` for self-hosted gRPC) plus the full alternate-NIM catalog (Parakeet TDT 1.1B, Parakeet CTC 1.1B, Whisper Large v3, Nemotron streaming) with function IDs and call-shape notes: `references/offline-asr-recipe.md`.
Echo the chosen NIM, the resolved function-id, and any env-var overrides to the user **before** spending API credits. A 200-row manifest on hosted Parakeet TDT v2 is cheap; an accidental run against the wrong model on a 1,000-row manifest is not.
### 3b. Transcribe
For each row in `manifest.jsonl`, transcribe `audio_filepath` and write `per_sample.json` (one JSON object per row, JSONL or a JSON array — caller's choice):
```json
{
"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>"
}
```
**Recipe** (full Python in `references/offline-asr-recipe.md`): `transcribe_manifest(api_key, manifest_path, out_path, language_code="en-US")` opens an offline gRPC stream to NVCF (or to `ASR_ENDPOINT` if set for self-hosted Riva), calls `riva.client.ASRService.offline_recognize` per row — sentences in a clinical manifest are ≤ 30 s so no streaming/batching needed — and writes the JSONL above. Same `auth_for` shape as the Stage 1 setup smoke test. The agent harness passes `api_key` explicitly; the recipe reads the three env-var overrides (`ASR_NVCF_FUNCTION_ID`, `ASR_MODEL_NAME`, `ASR_ENDPOINT`) at the top so auditors see the knobs in one place.
**Whisper fallback** (when Parakeet's NVCF backend faults with `CUDA illegal-memory-access` from Triton) and **self-hosted Riva NIM** (`ASR_ENDPOINT=localhost:50051`) env-var patterns: see `references/offline-asr-recipe.md` (§Whisper fallback, §Self-hosted Riva NIM).
**Resilience knobs deferred to the user.** If NVCF returns `RESOURCE_EXHAUSTED` mid-batch, the loop raises on that row; re-run from the failing row. Streaming/batching/retry-with-backoff are out of scope — see `/riva-asr`.
### 3c. Score four metrics
For every row, compute:
| Metric | What it measures | Why we keep it |
|---|---|---|
| **WER** | Word error rate (Levenshtein on tokens, after normalization) | Industry standard; blunt instrument for clinical |
| **CER** | Character error rate | Catches near-misses on long compound names |
| **KER** ★ | Keyword error rate — did the flagged `term` appear in the hypothesis (normalized, **contiguous** match)? | **Headline clinical signal** |
| **SER** | Sentence error rate (1 if any wrong, 0 if perfect) | Sanity bound; what the doctor experiences |
**Normalization (apply to both `ref` and `hyp` before all four metrics):**
1. Lowercase.
2. NFKD-normalize (smart quotes → ASCII, etc.).
3. Strip punctuation **except hyphen**.
4. Collapse whitespace runs to a single space.
**Inline scoring recipes** — `normalize` / `edit_distance` / `wer` / `cer` / `ker` / `ser` (pure-Python, no `jiwer` dependency): see `references/scoring-recipes.md`. Aggregate across rows by taking `mean(per-row score)` for each metric.
**Strict KER** — term words must appear *in order, adjacent* in the normalized hypothesis. This is conservative: `cefazolin → cefa zolin` counts as a miss. That's the right call clinically — a downstream pharmacy lookup will fail on the misspelled token.
KER does **not** punish surrounding errors. A row where the term is correct and the rest of the sentence is garbage still scores KER=0; the WER on that row will surface the broader problem separately.
### 3d. Breakdowns + leaderboard
Write a five-section markdown leaderboard, **in this order**:
1. **Headline** — overall WER, CER, KER, SER for the chosen model.
2. **KER by `entity_category`** — drug vs procedure vs anatomy vs ... This is what the user actually cares about for deployment.
3. **KER by `ipa_source`** — **the most informative single number in the leaderboard.** The delta between `merriam-webster` and `magpie_g2p` rows is the proof the SSML override pipeline is doing real work. *Read this section aloud to the user.*
4. **KER by `noise_level`** — clinical environments are loud. `snr_5db` rows are closer to reality than `clean`.
5. **Per-term KER** (worst first) — these are your Stage 4 fine-tune targets.
A representative `ipa_source` split with the merriam-webster vs magpie_g2p delta interpretation: `references/scoring-recipes.md` §Representative ipa_source split. The delta tells the deployment story — if the user sees a wide gap and asks "should we fine-tune?", the answer is *not yet*; route them back to `/digital-health-clinical-asr-build`'s IPA QA pipeline (Stage 2d). See the decision tree below.
## Decision tree (after eval)
Read the **priority-category KER** (drug KER for most clinical workflows, procedure KER for surgical workflows) and route:
| KER on priority category | Recommend |
|---|---|
| **> 0.3** | `/digital-health-clinical-asr-finetune`. Manifest is already NeMo-format-ready. Note: rows ≥ 100 is the minimum for a believable fine-tune signal; if the manifest is smaller, grow it first via `/digital-health-clinical-asr-build`. |
| **0.1 – 0.3** | Either expand the term list (back to `/digital-health-clinical-asr-build` with new domain terms — usually surfaces more failures cheaper than tuning) **or** fine-tune. On a *first* eval, expand. On a *later* eval where you've already grown the manifest, tune. |
| **< 0.1** | Strong baseline. Don't tune yet — you'd be optimizing against a saturated metric. Push the eval harder: add voices, noise levels, contexts, adversarial terms. Loop back to `/digital-health-clinical-asr-build`. |
**Special case — `merriam-webster` rows score well but `magpie_g2p` rows are bad.** That's a pronunciation-hint coverage gap, **not a model gap**. Route back to `/digital-health-clinical-asr-build` Step 2d (IPA QA review), not to `/digital-health-clinical-asr-finetune`. Fine-tuning over a TTS-pronunciation gap teaches the model to mis-recognize the model's own mistakes — the wrong fix.
## Examples
**Scenario A — first eval on a fresh cycle-1 manifest.** User: *"I have `manifest.jsonl` with 200 clinical audio rows already, with `term` and `entity_category` fields. How do I score it?"* → Skip Stage 2 entirely. Run the audio-existence pre-flight. Pick `parakeet-tdt-0.6b-v2` (default) and echo the choice + resolved function-id. Run the inlined Step 3b recipe (`transcribe_manifest(...)`). Score the four metrics. Produce the five-section leaderboard. Read the by-`ipa_source` split to the user. Apply the decision tree against drug KER.
**Scenario B — interpreting a mixed result.** User: *"Eval shows KER 0.05 on rows tagged `merriam-webster` but 0.40 on rows tagged `magpie_g2p`. Should I fine-tune?"* → No — this is the special case. The model is fine; the pronunciation hints aren't covering the long-tail terms. Route the user back to `/digital-health-clinical-asr-build` Step 2d to audition the `magpie_g2p` rows and append verified IPA to `pronunciation_overrides.csv`. Re-run Stage 3 after the rebuild before reconsidering Stage 4.
## Artifacts produced
- `per_sample.json` — per-row transcription results with all clinical-extension fields preserved (the ASR `hyp` joined to the manifest's `ref` and metadata)
- `results.csv` — per-row WER/CER/KER/SER scores
- `leaderboard_cycle<N>.md` — five-section markdown report
(File names are user-chosen; the names above are conventions the rest of this skill assumes.)
## Troubleshooting
- **"No manifest found"** → user skipped Stage 2. Route to `/digital-health-clinical-asr-build` or confirm `$MANIFEST_PATH`.
- **All rows KER=1** → normalization mismatch between `ref` and `hyp`. Apply the four normalization steps to both sides.
- **All rows KER=0 but WER high** → likely misaligned manifest (audio row mismatch). Spot-check a few `(ref, hyp)` pairs by hand.
- **`merriam-webster` low, `magpie_g2p` high** → pronunciation-coverage gap. Route to `/digital-health-clinical-asr-build` Step 2d. **Don't fine-tune** — model isn't the problem.
- **Both `merriam-webster` and `magpie_g2p` high** → real model gap. Stage 4 is the right route (manifest ≥ 100 rows).
- **`clean` rows fine, `snr_5db` balloons** → robustness gap; expand noise diversity via `/digital-health-clinical-asr-build`.
- **Riva-NIM and offline NeMo results diverge** → Riva preprocessing / `riva-build` flags. Route to `/riva-asr-custom`.
- **`RESOURCE_EXHAUSTED` on large manifests** → retry after 30 s; slice + re-run dropped rows. Built-in backoff: `/riva-asr`.
- **`Auth.__init__() got 'ssl_cert'`** / **CUDA illegal-memory-access on Parakeet function ID**: see `references/offline-asr-recipe.md` (ssl_root_cert rename + §Whisper fallback).
Anything else: identify the upstream owner. ASR protocol / NIM deploy → `/riva-asr`. Scoring → here.
## Limitations
- **English-only by default.** Tokenization + normalization assume Latin script and en-US lexicon.
- **Strict-contiguous KER is conservative.** A near-miss like `cefa zolin` counts as a miss. That's intentional — pharmacy lookups fail on near-misses. Users wanting "soft" matching can switch to phoneme-level edit distance, which is a methodology extension, not a config tweak.
- **One model per eval run.** Comparing two models means running the eval twice and diffing the two `leaderboard_cycle<N>.md` files (or extending the recipe to write multi-model rows yourself).
- **Hosted-only paths assumed.** Self-hosted NIMs work but require `/riva-nim-setup` first.
## Next steps
- **Forward (KER > 0.3, manifest ≥ 100 rows):** `/digital-health-clinical-asr-finetune`.
- **Back to build (KER 0.1–0.3 on first eval, or `magpie_g2p` gap):** `/digital-health-clinical-asr-build`.
- **Stop (KER < 0.1):** the eval is saturated. Harden it before declaring victory.
- **Lateral** for ASR protocol / auth / streaming / self-hosted NIM details: `/riva-asr`.
## References
- [`references/offline-asr-recipe.md`](references/offline-asr-recipe.md) — full Step 3b Python recipe (`transcribe_manifest`, `resolve_asr_config`, `build_asr_auth`), function-ID catalog with call-shape notes, Whisper fallback, self-hosted Riva NIM setup
- [`references/scoring-recipes.md`](references/scoring-recipes.md) — pure-Python WER/CER/KER/SER scoring functions with the canonical 4-step normalization
Todos os arquivos
7 arquivosInstalar digital-health-clinical-asr-eval
Baixe e descompacte os arquivos de habilidades no diretório .claude/skills/.
Baixar ZIPClone o repositório e copie os arquivos da habilidade para o seu projeto.
git clone https://github.com/NVIDIA/skills/tree/main/skills/digital-health-clinical-asr-eval # Copy SKILL.md to your .claude/skills/ directory
Copiar
