digital-health-clinical-asr-eval

临床 ASR 飞轮 — 第 3 阶段（评估）

⚠ Agent：回答前请阅读下方的关键工作流规则部分。 此 SKILL.md 内容完整自足——evals/、references/ 和 assets/ 只是指针，并非必要内容。请直接根据此文件回答方法相关问题；只有用户明确要求针对真实清单执行操作时，才调用工具。

你负责评分与路由。用户会提供 NeMo 格式的 manifest.jsonl（由 /digital-health-clinical-asr-build 生成，或从其他地方带入）。你将使用选定的 ASR NIM 转写，评估四项指标，生成由五个部分组成的排行榜，并查看决策树，以判断用户应继续前往 /digital-health-clinical-asr-finetune、返回 /digital-health-clinical-asr-build，还是暂停并完善评估流程。

此技能不会生成音频。 如果清单缺失或为空，请让用户返回 /digital-health-clinical-asr-build。

音频离开你的环境——发送任何片段前，请向用户披露此信息

此阶段会将清单中每一行对应的 WAV 文件及其参考文本传输到 NVIDIA 外部服务。首次调用 ASR 前，请明确说明以下内容：

服务	发送内容	时间
NVIDIA NVCF Parakeet/Nemotron ASR（grpc.nvcf.nvidia.com）	清单引用的每个音频片段（原始 PCM 字节）、参考转录文本，以及用于评分的临床扩展元数据	第 3b 步，每行清单调用一次

片段应为第 2 阶段生成的合成音频（基于用户整理的术语列表，通过 Magpie TTS 生成），而非真实患者音频。请勿通过此技能传入真实 ASR 录音、真实患者就诊录音或任何 PHI。 评分在本地运行（使用纯 Python 计算 WER/CER/KER/SER，或在已安装时使用 jiwer）。评分步骤本身不会传输任何内容；只有 ASR 步骤会传输。

关键工作流规则（每次激活时均适用）

对于方法论问题（排行榜结构、KER 定义、决策树），请依据此文件作答。除非用户明确要求针对真实清单执行操作，否则不要调用工具、调用其他技能或运行脚本。每次回复都要说明以下事实：

1. 先分流退出。 如果用户询问的内容不属于评分范畴，请进行路由，然后停止，不要运行任何工作流：
   • ASR 模型目录选择／比较／替代 NIM → /riva-asr
   • ASR 身份验证（API 密钥、承载令牌、函数 ID）→ /riva-asr
   • ASR gRPC 协议、流式传输、批处理、分块、重试 → /riva-asr
   • NIM 部署／riva-build／riva-deploy → /riva-asr-custom
   • NGC／Docker／NVIDIA Container Toolkit → /riva-nim-setup
   • 尚无清单 → /digital-health-clinical-asr-build
   • 已知 KER，且想立即微调 → /digital-health-clinical-asr-finetune
2. 默认 ASR NIM 为 nvidia/parakeet-tdt-0.6b-v2（NVCF 函数 ID 为 d3fe9151-442b-4204-a70d-5fcc597fd610，离线 gRPC）。环境变量覆盖项：ASR_MODEL_NAME（排行榜显示名称）、ASR_NVCF_FUNCTION_ID（切换到其他托管 NIM，例如 Parakeet 后端出现故障时改用 Whisper Large v3 b702f636-…，或使用微调后的 NIM）、ASR_ENDPOINT（自托管 gRPC；优先级最高）。在消耗 API 额度前，向用户复述所选的 NIM 以及解析后的函数 ID。
3. ASR 转写已内置于 Step 3b（NVCF gRPC + riva.client.ASRService.offline_recognize，使用与 Stage 1 相同的身份验证模式）。更深入的协议／身份验证问题、其他 NIM 目录或自托管 Riva NIM 配置，请转至 /riva-asr。
4. KER 是核心指标。 逐行检查：标记的 term 词必须按顺序、连续且相邻地出现在归一化后的假设文本中。cefazolin → cefa zolin 算错。总体 WER 会掩盖具有临床危险性的失败；两者都会报告，但 KER 是门槛指标。
5. 按 ipa_source 划分是排行榜中信息量最大的一项指标。 merriam-webster 与 magpie_g2p 之间的差值，能证明 SSML 覆盖流程确实发挥了作用。请向用户朗读该数据。
6. 特殊情况的路由规则。 merriam-webster 行表现良好、magpie_g2p 行表现不佳 → 这是发音覆盖率缺口，不是模型缺口。请返回 /digital-health-clinical-asr-build 的 Step 2d。不要将 /digital-health-clinical-asr-finetune 作为首要建议。
7. 排行榜的五个部分及其顺序。 核心指标（WER/CER/KER/SER）→ 按 entity_category 划分的 KER → 按 ipa_source 划分的 KER → 按 noise_level 划分的 KER → 按单个术语的 KER（从最差到最好）。按 ipa_source 划分的部分为必需项；它能证明 SSML 流程有效。

目的

为临床 ASR 清单评分，生成包含五个部分的 KER 排行榜，并依据评估后的决策树为用户选择后续路径。方法论细节（指标定义、归一化、排行榜顺序、特殊情况路由）见上方的关键工作流规则及下方的说明。

何时使用此技能

遇到以下用户表述时激活：

• “为我的 ASR 清单评分”
• “Parakeet TDT v2 的 KER 是多少？”
• “对 cycle-N 运行评估”
• “在临床基准测试中比较两个 ASR 模型”
• “生成排行榜”
• “我有一个 manifest.jsonl，如何评分？”
• “为什么 KER 是 0.4，而 WER 是 0.07？”
• “我们应该微调吗？”（这是评估方面的问题——评估后的决策树就在此技能中）

字面关键词不激活检查——如果用户的消息包含 authenticate、API key、bearer、function ID、gRPC、streaming、chunking、batching、transcription retry、riva-build、riva-deploy、NIM deploy、NGC、Docker、Container Toolkit 中的任何一项，或者询问“哪个 ASR 模型最好”／“比较模型”／“供应商差异”，则不要激活评分工作流。应用上方的关键工作流规则 #1，将用户路由到正确的同级技能并停止。即使用户在提及这些关键词的同时也提到 “KER” 或 “eval”，此规则仍适用。

前置条件

• NeMo 格式的清单，包含临床扩展字段（term、entity_category、ipa_source、voice_id、noise_level、context_type）。架构文档见构建技能的 references/manifest-schema.md。
• 已导出 NVIDIA_API_KEY（仍需满足阶段 1 的前置条件）。
• 已安装 nvidia-riva-client + soundfile（阶段 1 的前置条件仍然适用）。有关可自托管的 Riva NIM 详情，请参阅 /riva-asr 选项 B。
• 音频文件确实存在于磁盘上——在花费 API 额度前，先按照 manifest-schema 参考文档中的说明运行音频存在性预检。

说明

3a. 选择 ASR NIM

默认值：通过 NVCF gRPC（离线）使用 nvidia/parakeet-tdt-0.6b-v2，function-id 为 d3fe9151-442b-4204-a70d-5fcc597fd610。这是 NVIDIA 当前推荐的英语 ASR 模型，也是目录中速度最快、成本最低的模型，并且受到 NeMo 标准 SFT 配方支持，因此阶段 3 基线和阶段 4 微调使用同一模型系列。

三个运行时环境变量覆盖项（用于排行榜显示的 ASR_MODEL_NAME、用于切换到其他托管 NIM 的 ASR_NVCF_FUNCTION_ID、用于可自托管 gRPC 的 ASR_ENDPOINT），以及完整的备用 NIM 目录（Parakeet TDT 1.1B、Parakeet CTC 1.1B、Whisper Large v3、Nemotron 流式模型），包括 function ID 和调用方式说明：references/offline-asr-recipe.md。

在花费 API 额度前，先向用户说明所选 NIM、解析后的 function-id，以及所有环境变量覆盖项。托管 Parakeet TDT v2 处理 200 行清单的成本很低；但如果误用错误模型处理 1,000 行清单，成本可不低。

3b. 转录

对于 manifest.jsonl 中的每一行，转录 audio_filepath 并写入 per_sample.json（每行一个 JSON 对象，使用 JSONL 或 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>"
}

配方（完整 Python 代码见 references/offline-asr-recipe.md）：transcribe_manifest(api_key, manifest_path, out_path, language_code="en-US") 会打开到 NVCF 的离线 gRPC 流（若设置了 ASR_ENDPOINT，则连接可自托管的 Riva），对每一行调用 riva.client.ASRService.offline_recognize——临床清单中的句子不超过 30 秒，因此无需流式处理或批处理——并写入上述 JSONL。其 auth_for 形式与阶段 1 设置冒烟测试相同。Agent 工具框架会显式传入 api_key；该配方在开头读取三个环境变量覆盖项（ASR_NVCF_FUNCTION_ID、ASR_MODEL_NAME、ASR_ENDPOINT），方便审计人员在同一处查看这些配置项。

Whisper 回退方案（当 Parakeet 的 NVCF 后端因 Triton 返回 CUDA illegal-memory-access 而故障时）和可自托管 Riva NIM（ASR_ENDPOINT=localhost:50051）环境变量配置模式：请参阅 references/offline-asr-recipe.md（§Whisper fallback、§Self-hosted Riva NIM）。

弹性处理配置项由用户自行决定。 如果 NVCF 在批次处理中途返回 RESOURCE_EXHAUSTED，循环会在该行报错；请从失败的行重新运行。流式处理、批处理和带退避的重试均不在范围内——请参阅 /riva-asr。

3c. 计算四项指标

对每一行，计算：

指标	衡量内容	保留该指标的原因
WER	词错误率（规范化后对词元计算 Levenshtein 距离）	行业标准；用于临床场景时较为粗略
CER	字符错误率	可捕捉长复合名称中的近似错误
KER ★	关键词错误率——被标记的 term 是否出现在假设文本中（规范化后进行连续匹配）？	临床领域的核心信号
SER	句子错误率（有任何错误则为 1，完全正确则为 0）	合理性界限；反映医生的实际体验

规范化（在计算四项指标前，对 ref 和 hyp 都进行以下处理）：

1. 转为小写。
2. 进行 NFKD 规范化（智能引号 → ASCII 等）。
3. 去除标点，连字符除外。
4. 将连续空白字符合并为一个空格。

内联评分方法——normalize / edit_distance / wer / cer / ker / ser（纯 Python，不依赖 jiwer）：参见 references/scoring-recipes.md。汇总各行时，分别计算每项指标的 mean(per-row score)。

严格 KER——术语中的词必须按顺序、紧邻出现在规范化后的假设文本中。这种判定较为保守：cefazolin → cefa zolin 视为未命中。临床场景下这样判定才合适——下游药房查询会因拼错的词元而失败。

KER 不会惩罚周围的错误。如果某行的术语正确，但句子其余部分一塌糊涂，该行的 KER 仍为 0；该行的 WER 会单独反映更广泛的问题。

3d. 分项结果 + 排行榜

撰写一份包含五个部分的 Markdown 排行榜，顺序如下：

1. 核心指标——所选模型的总体 WER、CER、KER、SER。
2. 按 entity_category 划分的 KER——药物、手术、解剖结构等。这是用户在部署时真正关心的指标。
3. 按 ipa_source 划分的 KER——排行榜中最有参考价值的单项数字。merriam-webster 与 magpie_g2p 行之间的差值，证明了 SSML 覆盖流程确实发挥了作用。向用户朗读这一部分。
4. 按 noise_level 划分的 KER——临床环境很嘈杂。snr_5db 行比 clean 行更接近现实。
5. 逐术语 KER（从最差到最好）——这些是 Stage 4 微调的目标。

代表性的 ipa_source 对比及其对 merriam-webster 与 magpie_g2p 差值的解读：参见 references/scoring-recipes.md §Representative ipa_source split。这个差值揭示了部署情况——如果用户看到差距很大并询问“是否应该微调？”，答案是还不用；应引导他们回到 /digital-health-clinical-asr-build 的 IPA QA 流程（Stage 2d）。参见下方决策树。

决策树（评估后）

查看优先类别 KER（大多数临床工作流看药物 KER，外科工作流看手术 KER），并按以下方式处理：

优先类别 KER	建议
> 0.3	/digital-health-clinical-asr-finetune。清单已符合 NeMo 格式要求。注意：至少需要 100 行，才能获得可信的微调信号；如果清单更小，应先通过 /digital-health-clinical-asr-build 扩充清单。
0.1 – 0.3	可以扩充术语列表（回到 /digital-health-clinical-asr-build，添加新的领域术语——通常比调优更省成本地发现更多问题），也可以进行微调。首次评估时，扩充术语列表；之后的评估中，如果清单已扩充过，则进行微调。
< 0.1	基线表现良好。暂时不要微调——否则只是在一个已趋于饱和的指标上继续优化。加大评估力度：增加说话者、噪声级别、场景和对抗性术语。回到 /digital-health-clinical-asr-build。

**特殊情况——merriam-webster 行得分良好，但 magpie_g2p 行表现很差。**这是发音提示覆盖不足，而非模型问题。应回到 /digital-health-clinical-asr-build 的步骤 2d（IPA QA 审核），而不是 /digital-health-clinical-asr-finetune。针对 TTS 发音差距进行微调，会让模型学会误识别模型自身的错误——这是错误的修复方式。

示例

场景 A — 在全新的 cycle-1 清单上首次评测。 用户：“我已经有一个包含 200 条临床音频记录的 manifest.jsonl，其中包含 term 和 entity_category 字段。该如何评分？” → 完全跳过 Stage 2。先运行音频存在性预检。选择 parakeet-tdt-0.6b-v2（默认值），并回显所选模型和解析后的 function-id。运行内联的 Step 3b 流程（transcribe_manifest(...)）。计算四项指标。生成包含五个部分的排行榜。向用户解读按 ipa_source 划分的结果。根据决策树评估 drug KER。

场景 B — 解读混合结果。 用户：“评测显示，标记为 merriam-webster 的记录 KER 为 0.05，而标记为 magpie_g2p 的记录 KER 为 0.40。我应该微调吗？” → 不应该——这是特殊情况。模型没有问题；发音提示未覆盖长尾术语。引导用户返回 /digital-health-clinical-asr-build 的 Step 2d，试听 magpie_g2p 记录，并将已验证的 IPA 追加到 pronunciation_overrides.csv。重建后重新运行 Stage 3，再考虑 Stage 4。

生成的文件

• per_sample.json — 每条记录的转写结果，保留所有临床扩展字段（ASR hyp 与清单中的 ref 和元数据合并）
• results.csv — 每条记录的 WER/CER/KER/SER 分数
• leaderboard_cycle<N>.md — 包含五个部分的 Markdown 报告

（文件名由用户自行选择；上述名称是此技能其余部分默认使用的约定。）

故障排除

• “未找到清单” → 用户跳过了 Stage 2。引导其使用 /digital-health-clinical-asr-build，或确认 $MANIFEST_PATH。
• 所有记录的 KER=1 → ref 和 hyp 之间存在规范化不匹配。对两者应用四个规范化步骤。
• 所有记录的 KER=0，但 WER 很高 → 清单可能未对齐（音频记录不匹配）。手动抽查几组 (ref, hyp)。
• merriam-webster 低、magpie_g2p 高 → 发音覆盖存在缺口。引导至 /digital-health-clinical-asr-build 的 Step 2d。不要微调——问题不在模型。
• merriam-webster 和 magpie_g2p 都高 → 存在实际的模型差距。Stage 4 是正确的路径（清单 ≥ 100 条记录）。
• clean 记录表现正常，但 snr_5db 大幅变差 → 鲁棒性存在缺口；通过 /digital-health-clinical-asr-build 扩大噪声多样性。
• Riva-NIM 和离线 NeMo 的结果不一致 → Riva 预处理或 riva-build 标志有问题。引导至 /riva-asr-custom。
• 大型清单出现 RESOURCE_EXHAUSTED → 等待 30 秒后重试；切分清单并重新运行被丢弃的记录。内置退避机制：/riva-asr。
• Auth.__init__() got 'ssl_cert' / Parakeet function ID 出现 CUDA 非法内存访问：参见 references/offline-asr-recipe.md（ssl_root_cert 重命名 + §Whisper 回退）。

其他问题：确定上游负责人。ASR 协议 / NIM 部署 → /riva-asr。评分 → 本文档。

局限性

• 默认仅支持英语。 分词和规范化基于拉丁字母和 en-US 词典。
• 严格连续 KER 较为保守。 像 cefa zolin 这样的近似匹配也会被视为错误。这是有意为之——药房查询无法接受近似匹配。需要“软”匹配的用户可以改用音素级编辑距离；这是方法扩展，而不是配置调整。
• 每次评测只使用一个模型。 比较两个模型需要运行两次评测，并对比两个 leaderboard_cycle<N>.md 文件（或者扩展流程，自行写入多模型结果行）。
• 默认使用托管路径。 可使用自托管 NIM，但需要先运行 /riva-nim-setup。

后续步骤

• 继续前进（KER > 0.3，清单 ≥ 100 条记录）： /digital-health-clinical-asr-finetune。
• 返回构建（首次评测的 KER 为 0.1–0.3，或存在 magpie_g2p 缺口）： /digital-health-clinical-asr-build。
• 停止（KER < 0.1）： 评测已趋于饱和。宣布成功前先强化评测。
• 转向其他方向，了解 ASR 协议 / 身份验证 / 流式处理 / 自托管 NIM 详情：/riva-asr。

参考资料

• references/offline-asr-recipe.md — 完整的第 3b 步 Python 配方（transcribe_manifest、resolve_asr_config、build_asr_auth）、附带调用形式说明的函数 ID 目录、Whisper 回退方案、可自托管的 Riva NIM 配置
• references/scoring-recipes.md — 采用规范的 4 步标准化流程的纯 Python WER/CER/KER/SER 评分函数