Flywheel clínico de ASR — Fase 3 (Evaluación)

⚠ Agente: lee la sección «Reglas críticas del flujo de trabajo» que aparece a continuación antes de responder. Este archivo SKILL.md es autónomo: las carpetas evals/, references/ y assets/ son meros enlaces, no contienen datos. Responde directamente a las preguntas sobre metodología de este archivo; solo invoca herramientas cuando el usuario solicite explícitamente que se ejecute con un manifiesto real.

Te encuentras en la etapa de puntuación y enrutamiento. El usuario llega con un archivo manifest.jsonl en formato NeMo (ya sea procedente de /digital-health-clinical-asr-build o importado desde otro lugar). Lo transcribes mediante el NIM de ASR elegido, evalúas cuatro métricas, generas una tabla de clasificación de cinco secciones y consultas el árbol de decisión para determinar si el usuario debe avanzar a /digital-health-clinical-asr-finetune, volver a /digital-health-clinical-asr-build o detenerse y consolidar la evaluación.

Esta skill no genera audio. Si el manifiesto falta o está vacío, redirige al usuario a /digital-health-clinical-asr-build.

El audio sale de tu entorno; informa de ello al usuario antes de enviar cualquier clip

En esta etapa se transmite el archivo WAV de cada fila del manifiesto, junto con su texto de referencia, a un servicio externo de NVIDIA. Indícalo antes de realizar la primera llamada ASR:

Los clips deben ser audio sintético generado en la Etapa 2 (Magpie TTS sobre una lista de términos seleccionada por el usuario), no audio real de pacientes. No se deben enviar a través de esta skill grabaciones reales de ASR, interacciones reales con pacientes ni ningún dato de salud protegido (PHI). A continuación, la puntuación se ejecuta localmente (WER/CER/KER/SER en Python puro, o jiwer si está instalado). El paso de puntuación en sí mismo no transmite nada; solo lo hace el paso de ASR.

Reglas críticas del flujo de trabajo (aplicables en cada activación)

Para preguntas sobre la metodología (estructura de la tabla de clasificación, definición de KER, árbol de decisión), responde a partir de este archivo. No utilices herramientas, no llames a otras habilidades ni ejecutes scripts a menos que el usuario solicite explícitamente que se ejecute con un manifiesto real. Menciona estos datos en cualquier respuesta:

1. Salida prioritaria. Si el usuario pregunta sobre algo ajeno a la puntuación, redirígelo y detén el proceso sin ejecutar ningún flujo de trabajo:
   • Selección/comparación del catálogo de modelos ASR / NIM alternativos → /riva-asr
   • Autenticación ASR (claves API, tokens de portador, ID de funciones) → /riva-asr
   • Protocolo gRPC de ASR, streaming, procesamiento por lotes, fragmentación, reintentos → /riva-asr
   • Implementación de NIM / riva-build / riva-deploy → /riva-asr-custom
   • NGC / Docker / NVIDIA Container Toolkit → /riva-nim-setup
   • Aún no hay manifiesto → /digital-health-clinical-asr-build
   • Quiere realizar un ajuste fino ahora con un KER conocido → /digital-health-clinical-asr-finetune
2. El NIM predeterminado de ASR es nvidia/parakeet-tdt-0.6b-v2 (ID de función NVCF d3fe9151-442b-4204-a70d-5fcc597fd610, gRPC sin conexión). Anulaciones mediante variables de entorno: ASR_MODEL_NAME (nombre que se muestra en la tabla de clasificación), ASR_NVCF_FUNCTION_ID (cambiar a un NIM alojado diferente —por ejemplo, Whisper Large v3 b702f636-… cuando el backend de Parakeet presente fallos, o un NIM ajustado), ASR_ENDPOINT (gRPC autohospedado; tiene prioridad). Reenvía el NIM elegido y el identificador de función resuelto antes de gastar créditos de la API.
3. La transcripción de ASR se integra en el paso 3b (NVCF gRPC + riva.client.ASRService.offline_recognize, mismo patrón de autenticación que en la etapa 1). Para cuestiones más detalladas sobre el protocolo o la autenticación, catálogos NIM alternativos o la configuración de un NIM de Riva autohospedado, consulta /riva-asr.
4. El KER es el indicador principal. Comprobación por fila: las palabras marcadas deben aparecer en orden, contiguas y adyacentes en la hipótesis normalizada. «cefazolin» → «cefa zolin» es un error. El WER agregado oculta fallos clínicamente peligrosos; ambos se notifican, pero el KER es el filtro decisivo.
5. La división«by-ipa_source» es la cifra individual más informativa de la tabla de clasificación. La diferencia entre «merriam-webster» y «magpie_g2p» demuestra que el proceso de anulación de SSML está funcionando de verdad. Léelo en voz alta al usuario.
6. Enrutamiento de casos especiales. Las filas de «merriam-webster» son buenas, las de «magpie_g2p» son malas → diferencia en la cobertura de la pronunciación, no una diferencia entre modelos. Vuelve a /digital-health-clinical-asr-build, paso 2d. NO recomiendes /digital-health-clinical-asr-finetune como primera respuesta.
7. Orden de la tabla de clasificación de cinco secciones. Encabezado (WER/CER/KER/SER) → KER por «entity_category» → KER por «ipa_source» → KER por «noise_level» → KER por término, de peor a mejor. La sección«by-ipa_source» es obligatoria; es la prueba de que el proceso de SSML funciona.

Objetivo

Puntuar un manifiesto de ASR clínico, generar una tabla de clasificación KER de cinco secciones y dirigir al usuario a través del árbol de decisión posterior a la evaluación. Los detalles de la metodología (definiciones de métricas, normalización, orden de la tabla de clasificación, enrutamiento de casos especiales) se encuentran en las «Reglas críticas del flujo de trabajo» más arriba y en las «Instrucciones» más abajo.

Cuándo utilizar esta habilidad

Actívala ante frases del usuario como:

• «Puntuar mi manifiesto de ASR»
• «¿Cuál es el KER de Parakeet TDT v2?»
• «Ejecuta la evaluación en el ciclo N»
• «Compara dos modelos de ASR en el benchmark clínico»
• «Genera la tabla de clasificación»
• «Tengo un archivo manifest.jsonl, ¿cómo lo evalúo?»
• «¿Por qué el KER es 0,4 si el WER es 0,07?»
• «¿Deberíamos realizar un ajuste fino?» (esta es la pregunta relacionada con la evaluación; el árbol de decisión posterior a la evaluación se encuentra en esta habilidad)

Comprobación de no activación de palabras clave literales: si el mensaje del usuario contiene alguna de las siguientes palabras: «authenticate», «API key», «bearer», «function ID», «gRPC», «streaming», «chunking», «batching», «transcription retry», «riva-build», «riva-deploy», «NIM deploy», «NGC», Docker o Container Toolkit, o si pregunta «¿qué modelo ASR es el mejor?», «comparar modelos» o «diferencias entre proveedores», NO se activará el flujo de trabajo de puntuación. Aplica la regla de flujo de trabajo crítica n.º 1 anterior para redirigir al skill hermano adecuado y detener el proceso. Esto se aplica incluso si el usuario menciona «KER» o «eval» junto con la palabra clave.

Requisitos previos

• Un manifiesto en formato NeMo con los campos de extensión clínicos (term, entity_category, ipa_source, voice_id, noise_level, context_type). El esquema está documentado en el archivo references/manifest-schema.md de la habilidad de compilación.
• NVIDIA_API_KEY exportada (el requisito previo de la etapa 1 sigue siendo válido).
• nvidia-riva-client + soundfile instalados (requisito previo de la etapa 1). Para obtener detalles sobre Riva NIM autohospedado, consulta /riva-asr Opción B.
• Archivos de audio realmente presentes en el disco: ejecute la comprobación previa «audio-existence» de la referencia «manifest-schema» antes de gastar créditos de la API.

Instrucciones

3a. Elige el NIM de ASR

Por defecto: nvidia/parakeet-tdt-0.6b-v2 a través de NVCF gRPC (sin conexión), ID de función d3fe9151-442b-4204-a70d-5fcc597fd610. Recomendación actual de NVIDIA para ASR en inglés: es el más rápido y económico del catálogo, y es compatible con la receta SFT predeterminada de NeMo, por lo que la línea base de la Etapa 3 y el ajuste fino de la Etapa 4 utilizan la misma familia de modelos.

Tres controles para anular variables de entorno en tiempo de ejecución (ASR_MODEL_NAME para la visualización en la tabla de clasificación, ASR_NVCF_FUNCTION_ID para cambiar a un NIM alojado diferente, ASR_ENDPOINT para gRPC autohospedado), además del catálogo completo de NIM alternativos (Parakeet TDT 1.1B, Parakeet CTC 1.1B, Whisper Large v3, Nemotron streaming) con los ID de función y notas sobre el formato de las llamadas: references/offline-asr-recipe.md.

Indica al usuario el NIM elegido, el identificador de función resuelto y cualquier sustitución de variables de entorno antes de gastar créditos de la API. Un manifiesto de 200 filas en un Parakeet TDT v2 alojado es barato; una ejecución accidental con el modelo equivocado en un manifiesto de 1.000 filas no lo es.

3b. Transcribir

Para cada fila de manifest.jsonl, transcribe audio_filepath y escribe per_sample.json (un objeto JSON por fila, JSONL o una matriz JSON —a elección del usuario—):

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

Receta (código completo en Python en references/offline-asr-recipe.md): transcribe_manifest(api_key, manifest_path, out_path, language_code="en-US") abre un flujo gRPC sin conexión hacia NVCF (o hacia ASR_ENDPOINT si se ha configurado para Riva autohospedado), llama a riva.client.ASRService.offline_recognize por fila —las frases de un manifiesto clínico duran ≤ 30 s, por lo que no se necesita streaming ni procesamiento por lotes— y escribe el JSONL anterior. La misma estructura de auth_for que en la prueba de funcionamiento de la configuración de la Etapa 1. El harness del agente pasa la clave «api_key» de forma explícita; la receta lee las tres variables de entorno sobrescritas (ASR_NVCF_FUNCTION_ID, ASR_MODEL_NAME, ASR_ENDPOINT) al principio, para que los auditores vean los parámetros de configuración en un solo lugar.

Patrones de variables de entorno parael plan de contingencia de Whisper (cuando el backend NVCF de Parakeet falla debido a un acceso ilegal a la memoria de CUDA desde Triton) y para el Riva NIM autohospedado (ASR_ENDPOINT=localhost:50051): véase references/offline-asr-recipe.md (§Recurso alternativo de Whisper, §Riva NIM autohospedado).

Los parámetros de resiliencia se dejan a criterio del usuario. Si NVCF devuelve RESOURCE_EXHAUSTED en mitad de un lote, el bucle se detiene en esa fila; se vuelve a ejecutar a partir de la fila en la que se produjo el fallo. El streaming, el procesamiento por lotes y los reintentos con retroceso quedan fuera del alcance de este documento; véase /riva-asr.

3c. Calificar cuatro métricas

Para cada fila, calcular:

Normalización (aplicar tanto a «ref» como a «hyp» antes de las cuatro métricas):

1. Minúsculas.
2. Normalización NFKD (comillas tipográficas → ASCII, etc.).
3. Eliminar la puntuación, excepto el guión.
4. Reducir las secuencias de espacios en blanco a un solo espacio.

Recetas de puntuación en línea: normalizar / edit_distance / wer / cer / ker / ser (Python puro, sin dependencia de jiwer ): véase references/scoring-recipes.md. Agregar por filas calculando la media (puntuación por fila) para cada métrica.

KER estricto: las palabras del término deben aparecer en orden, adyacentes en la hipótesis normalizada. Esto es conservador: «cefazolin» → «cefa zolin» cuenta como un error. Es la decisión correcta desde el punto de vista clínico: una consulta posterior en la farmacia fallará debido al token mal escrito.

El KER no penaliza los errores circundantes. Una fila en la que el término sea correcto y el resto de la frase sea basura sigue obteniendo una puntuación KER = 0; el WER de esa fila pondrá de manifiesto el problema más amplio por separado.

3d. Desgloses + tabla de clasificación

Escribe una tabla de clasificación en Markdown con cinco secciones, en este orden:

1. Título: WER, CER, KER y SER generales del modelo elegido.
2. KER por «entity_category »: fármaco frente a procedimiento frente a anatomía frente a... Esto es lo que realmente le importa al usuario a la hora de la implementación.
3. KER por ipa_source: la cifra más informativa de la tabla de clasificación. La diferencia entre las filas de Merriam-Webster y magpie_g2p es la prueba de que el proceso de anulación de SSML está funcionando de verdad. Lee esta sección en voz alta al usuario.
4. KER por «noise_level »: los entornos clínicos son ruidosos. Las filas «snr_5db» se acercan más a la realidad que las «clean».
5. KER por término (de peor a mejor): estos son tus objetivos de ajuste fino de la Etapa 4.

Una división representativa de ipa_source con la interpretación de la diferencia entre Merriam-Webster y magpie_g2p: references/scoring-recipes.md §División representativa de ipa_source. El delta refleja la situación de la implementación: si el usuario observa una gran diferencia y pregunta «¿deberíamos realizar un ajuste fino?», la respuesta es «todavía no»; redirígelo al proceso de control de calidad de IPA de /digital-health-clinical-asr-build(Etapa 2d). Consulta el árbol de decisión a continuación.

Árbol de decisión (tras la evaluación)

Lee el KER de la categoría de prioridad (KER de fármaco para la mayoría de los flujos de trabajo clínicos, KER de procedimiento para los flujos de trabajo quirúrgicos) y redirige:

Caso especial: las filas de «merriam-webster» obtienen buena puntuación, pero las de «magpie_g2p» son malas. Se trata de una laguna en la cobertura de las pistas de pronunciación, no de una laguna del modelo. Vuelve a /digital-health-clinical-asr-build, paso 2d (revisión de control de calidad del AFI), no a /digital-health-clinical-asr-finetune. El ajuste fino sobre una brecha de pronunciación del TTS enseña al modelo a reconocer erróneamente sus propios errores: es una solución equivocada.

Ejemplos

Escenario A: primera evaluación en un manifiesto nuevo del ciclo 1. Usuario: «Tengo un archivo manifest.jsonl con 200 filas de audio clínico, con los campos «term» y «entity_category ». ¿Cómo lo evalúo?» → Omite la etapa 2 por completo. Ejecuta la comprobación previa de existencia de audio. Selecciona parakeet-tdt-0.6b-v2 (por defecto) y muestra la elección junto con el identificador de función resuelto. Ejecuta la receta integrada del paso 3b (transcribe_manifest(...)). Califica las cuatro métricas. Genera la tabla de clasificación de cinco secciones. Lee al usuario la divisiónpor «ipa_source ». Aplica el árbol de decisión al KER de medicamentos.

Escenario B: interpretación de un resultado mixto. Usuario: «La evaluación muestra un KER de 0,05 en las filas etiquetadas como merriam-webster, pero de 0,40 en las etiquetadas como magpie_g2p. ¿Debería realizar un ajuste fino?» → No — se trata de un caso especial. El modelo funciona bien; las pistas de pronunciación no cubren los términos de cola larga. Redirige al usuario al paso 2d de /digital-health-clinical-asr-build para que revise las filas «magpie_g2p» y añada el IPA verificado al archivo pronunciation_overrides.csv. Vuelve a ejecutar la etapa 3 tras la reconstrucción antes de reconsiderar la etapa 4.

Archivos generados

• per_sample.json: resultados de transcripción por fila con todos los campos de extensión clínica conservados (el hip de ASR unido a la referencia y los metadatos del manifiesto)
• results.csv: puntuaciones de WER/CER/KER/SER por fila
• leaderboard_cycle.md: informe en Markdown de cinco secciones

(Los nombres de los archivos los elige el usuario; los nombres anteriores son convenciones que se dan por supuestas en el resto de esta skill).

Solución de problemas

• «No se ha encontrado ningún manifiesto» → el usuario se ha saltado la Etapa 2. Dirígete a /digital-health-clinical-asr-build o confirma $MANIFEST_PATH.
• Todas las filas tienen KER=1 → discrepancia de normalización entre ref e hyp. Aplica los cuatro pasos de normalización a ambos lados.
• Todas las filas tienen KER=0 pero el WER es alto → probablemente el manifiesto esté desalineado (desajuste entre filas de audio). Comprueba manualmente algunos pares (ref, hyp).
• merriam-webster bajo, magpie_g2p alto → diferencia en la cobertura de la pronunciación. Dirígete a /digital-health-clinical-asr-build, paso 2d. No realices un ajuste fino: el modelo no es el problema.
• Tanto «merriam-webster» como «magpie_g2p» altos → deficiencia real del modelo. La etapa 4 es la ruta correcta (manifiesto ≥ 100 filas).
• Las filaslimpias están bien, pero el snr_5db se dispara → brecha de robustez; ampliar la diversidad del ruido a través de /digital-health-clinical-asr-build.
• Los resultados de Riva-NIM y NeMo offline divergen → preprocesamiento de Riva / indicadores de riva-build. Accede a /riva-asr-custom.
• RESOURCE_EXHAUSTED en manifiestos grandes → reintentar tras 30 s; dividir en segmentos y volver a ejecutar las filas descartadas. Retraso integrado: /riva-asr.
• Auth.__init__() recibió «ssl_cert» / acceso ilegal a la memoria de CUDA en el ID de función de Parakeet: véase references/offline-asr-recipe.md (cambio de nombre de ssl_root_cert + §solución alternativa Whisper).

Cualquier otra cosa: identifica al propietario del origen. Protocolo ASR / implementación de NIM → /riva-asr. Puntuación → aquí.

Limitaciones

• Solo inglés por defecto. La tokenización y la normalización asumen el alfabeto latino y el léxico en-US.
• El KER estrictamente contiguo es conservador. Un resultado «casi erróneo» como «cefa zolin» cuenta como un error. Esto es intencionado: las búsquedas farmacéuticas fallan ante resultados «casi erróneos». Los usuarios que deseen una coincidencia «suave» pueden cambiar a la distancia de edición a nivel de fonema, lo cual es una extensión de la metodología, no un ajuste de configuración.
• Un modelo por ejecución de evaluación. Comparar dos modelos implica ejecutar la evaluación dos veces y comparar los dos archivos `leaderboard_cycle.md ` (o ampliar la receta para escribir tú mismo filas con varios modelos).
• Se asumen rutas únicamente en entorno alojado. Los NIM autohospedados funcionan, pero requieren ejecutar primero /riva-nim-setup.

Próximos pasos

• Avanzar (KER > 0,3, manifiesto ≥ 100 filas): /digital-health-clinical-asr-finetune.
• Volver a la fase de desarrollo (KER entre 0,1 y 0,3 en la primera evaluación, o diferencia con magpie_g2p ): /digital-health-clinical-asr-build.
• Detener (KER < 0,1): la evaluación está saturada. Refuérzala antes de darla por concluida.
• Informaciónadicional sobre el protocolo ASR, la autenticación, el streaming y el NIM autohospedado: /riva-asr.

Referencias

• references/offline-asr-recipe.md — receta completa en Python del paso 3b (transcribe_manifest, resolve_asr_config, build_asr_auth), catálogo de ID de funciones con notas sobre la estructura de las llamadas, recurso de reserva de Whisper, configuración del NIM de Riva autohospedado
• references/scoring-recipes.md — Funciones de puntuación WER/CER/KER/SER en Python puro con la normalización canónica de 4 pasos