digital-health-clinical-asr-build

临床 ASR 飞轮 — 阶段 2（构建基准）

⚠ Agent：回答前请阅读完整的 SKILL.md。 此阶段采用对话式流程，并设有门槛。具体来说：先提出 1–2 个结合专科背景的澄清问题，再推荐术语（步骤 2a）；在步骤 2c 中，引导用户了解双层 IPA 流程（override → merriam-webster → magpie_g2p）；在完成全面笛卡尔积合成之前，先通过步骤 2d 中明确的 QA 模式试听门槛；并指出 KER 是用户在阶段 3 将看到的核心指标。跳过其中任何一步都会破坏这套方法。

你负责整理并合成这一阶段。用户从 /digital-health-clinical-asr-setup 进入，离开时将获得 NeMo 格式的 manifest.jsonl 及其引用的音频，两者均可用于 /digital-health-clinical-asr-eval 评分。

请采用对话式交流。这是整个飞轮中最亲切、最了解领域的一步：你要询问临床医生（或与其合作的人）哪些术语目前最容易出错，并围绕他们的实际情况构建基准。问题要简短、聚焦。让用户了解新增了哪些内容。不要长篇说教。

任何术语发送出去之前，请告知用户数据会离开其环境

此阶段会将用户整理的内容发送到两个外部服务。调用任何一个服务之前，都要向用户说明：

服务	发送的内容	时间
Merriam-Webster（dictionaryapi.com API 或 merriam-webster.com 公共网站）	种子列表中的每个术语各发送一个 HTTP 请求——术语会放入 URL 路径	步骤 2c — 请参阅下方的 MW 路径要点
NVIDIA NVCF Magpie TTS（grpc.nvcf.nvidia.com）	每条生成的临床句子（文本，以及其中任何 SSML IPA 包装标签）	步骤 2d 和 2e，每次合成调用都会发送

这两个端点都要求使用非 PHI 合成内容——也就是你整理的术语列表，以及 /data-designer（或备用模板）据此生成的句子。请勿通过此技能传入真实患者记录、真实 ASR 转写文本或任何 PHI。 如果术语列表本身包含敏感信息（专有药物代号、尚未发布的产品名称、客户机密适应症），请先确认用户接受向外部 API 传输，并符合其所在组织的数据治理政策，再继续操作。

如果用户不接受任何 MW 数据传输，请采用下方的路径 C（跳过 MW；此流程将转而使用 Magpie G2P，但对长尾术语的覆盖率会降低）。

目的

整理一份临床专科术语列表，通过 Magpie TTS 和双层 IPA 流程为其生成评估音频，并写入 NeMo 格式清单，其中包含临床扩展字段（term、entity_category、ipa_source、voice_id、noise_level、context_type）。此输出将作为阶段 3 的输入。

用户最终将获得：

$EVAL_DIR/cycle<N>/
├── audio/<slug>.wav        synthesized clips
├── manifest.jsonl          NeMo format + clinical extension
├── term_seed.csv           the curated input
└── pronunciation_overrides.csv   appendable across cycles

（$EVAL_DIR 由用户自行决定——此技能不规定目录布局。以上结构仅为建议，并非必需。）

何时使用此技能

遇到以下用户表述时启用：

• “构建临床 ASR 基准”
• “为 ASR 评估整理药物名称 / 手术名称”
• “为医学术语生成评估音频”
• “根据临床术语创建 NeMo 清单”
• “将肿瘤科 / 心脏科 / 骨科术语添加到我的基准”
• “试听这些药物名称的 TTS 发音”
• “为我生成一个 cycle-N 清单”

以下情况不要启用（另外，如果消息提及 auth、API key、gRPC、streaming、riva-build、NIM deploy、NGC 或 Docker，请根据下面的项目进行路由，然后停止）：

• 用户已有清单并想为其评分 → /digital-health-clinical-asr-eval
• 用户想基于现有清单进行微调 → /digital-health-clinical-asr-finetune
• 用户询问通用 TTS / SSML / 声音克隆 / 语音目录问题 → /read-aloud（或 /riva-tts）
• TTS/ASR 身份验证 / API 密钥 / gRPC / 流式传输 → /riva-tts 或 /riva-asr
• NIM 部署或 riva-build / riva-deploy 标志 → /riva-asr-custom 或 /riva-tts-custom
• NGC / Docker / NVIDIA Container Toolkit → /riva-nim-setup
• 用户询问通用合成数据问题 → /data-designer

前置条件

• 已完成 /digital-health-clinical-asr-setup — 已导出 NVIDIA_API_KEY、已安装 Python 依赖项，并已确认六项上游技能。
• 可访问 /read-aloud（或 /riva-tts）。默认使用通过 NVCF 托管的 Magpie。可使用可自托管的 Magpie NIM，但这会将 /riva-nim-setup 加入前置条件链。
• 可访问 /data-designer。如果 /data-designer 不可用，首轮可以使用模板作为备用方案，但请为这些行添加标记，以便后续轮次重新生成。
• 用户拥有的工作目录。此技能建议使用 $EVAL_DIR/cycle<N>/，但不强制要求。

说明

2a. 专科访谈 → term_seed.csv

一次只问一个问题。目标是找出 4–10 个具有合适 entity_category 的候选术语，而不是编写教科书。

按顺序提问：

1. 这适用于哪个专科 / 工作流？（肿瘤科口述、ICU 交接、精神科接诊、骨科术后，……）
2. 你遇到过哪些 ASR 失败模式？ — 药物名称、多词手术名称、缩写、复合病症。
3. 哪些术语每天都会出现？哪些比较难？ — 日常常见术语用作合理性基线；日常难点术语则用于体现信号。

提出 4–10 个带有 entity_category 的候选术语。先让用户确认，再写入 term_seed.csv：

term,entity_category
cefazolin,drug
acetabular reamer,procedure
tibial plateau,anatomy
femoroacetabular impingement,condition
hemoglobin a1c,lab
respiratory therapist,role

类别词表固定不变。 KER 依赖该词表。允许的值：

drug | procedure | anatomy | condition | lab | role

如果用户提出新类别，请予以说明：它要么对应六个类别之一，要么需要有意扩展方法（这是未来轮次的工作，不应临时随意添加）。

2b. 通过 /data-designer 生成句子

向 /data-designer 提供简要说明：

对于 term_seed.csv 中的每一行，生成一个或多个自然的英文句子，将 term 嵌入符合该行 entity_category 的语境中。输出架构：{term, entity_category, sentence, context_type}。每个术语生成 3–5 种 context_type 变体。初始 context_type 词表：dictation、handoff、chart_note、history。句子长度为 10–30 个词。

此步骤的输出是一个按术语整理的句子变体文件。文件名不限——选定一个，并在整个轮次的目录中保持一致。

模板备用方案。 如果 /data-designer 不可用，则使用 4 个模板（每种 context_type 一个），并机械地替换 term。在清单中为这些行添加标记（设置 context_type，并注明句子自然度较低），以便后续轮次重新生成。

2c. 双层 IPA 标注（决定质量的关键）

每个词条都会依次通过一个三层管线：

1. 覆盖项 — pronunciation_overrides.csv 保存了团队审核确认的 IPA。如果 term 与其中某一行匹配，就采用覆盖项。
2. Merriam-Webster — 对未被覆盖的词条，获取 MW 转写，转换为 IPA，并根据 Magpie 的 en-US 音素集进行验证。如果两步都成功，该词条会标记为 merriam-webster。
3. Magpie G2P（兜底） — 如果覆盖项和 MW 都无法生成有效 IPA，则在合成时将纯文本传递给 Magpie 的神经 G2P。该行会标记为 magpie_g2p。

每个清单行都会带有 ipa_source 标签（override | merriam-webster | magpie_g2p）。Stage 3 排行榜中 merriam-webster 行与 magpie_g2p 行之间的差异，就是发音策略有效的证明——生成排行榜时请明确指出这一点。

MW 查询的三种选择——三者都会标记为 merriam-webster。A：dictionaryapi.com JSON API + DICTIONARY_API_KEY（可在 dictionaryapi.com 免费获取）——推荐独立使用。B：抓取 merriam-webster.com HTML——无需密钥，但容易受网站 HTML 变更影响；配方已内嵌在 references/pronunciation-pipeline.md 中。C：跳过 MW，直接回退到 Magpie G2P，长尾覆盖较弱。两种配方和完整的转写→IPA 对照表都在 references/pronunciation-pipeline.md 中。Path A 函数将 api_key 作为参数（不会读取 os.environ）；传入 None 即可跳过 MW。

pronunciation_overrides.csv 的架构：

term,ipa,verified_by,verified_at,notes
cefazolin,sɛfəˈzoʊlɪn,brandoing,2026-05-13,confirmed against MW respelling + ear test

在各轮次间只追加内容。稍后重新运行构建时，会自动读取新增条目。

2d. QA 模式合成（请勿跳过此关卡）

运行完整笛卡尔积之前，为每个术语合成 一个 wav，使用：第一种声音、干净噪声、默认上下文。与用户一起试听每段音频。

对于每个标记为 magpie_g2p 的术语，使用临床后缀模式提出一个 IPA 候选，并在建议之前，根据 Magpie 的 en-US 音素集进行验证：

后缀	重音模式（示例）
-mycin	…ˈmaɪsɪn（vancomycin、gentamicin）
-prazole	…ˈpreɪzoʊl（esomeprazole、omeprazole）
-statin	…ˈstætɪn（atorvastatin、rosuvastatin）
-sartan	…ˈsɑːrtən（losartan、valsartan）
-azole	…ˈeɪzoʊl（fluconazole、ketoconazole）
-cillin	…ˈsɪlɪn（amoxicillin、piperacillin）
-parin	…ˈpɛərɪn（enoxaparin、heparin）

音素验证模式 — 使用候选 IPA 对 Magpie 的 en-US 神经 G2P 进行实时探测。如果 Magpie 接受该 SSML，则该 IPA 属于其音素库。将上述后缀模式用作预筛选（低成本启发式方法），并在确定覆盖项之前通过实时探测进行确认。references/pronunciation-pipeline.md 中的 magpie_validates_ipa(ipa, api_key, voice_id) 配方是一种最简 NVCF gRPC 合成调用，可在失败时关闭并返回 True/False。

在向用户展示之前，对每个候选 IPA 调用一次。用户批准后，将经过验证的 IPA 追加到 pronunciation_overrides.csv。下次生成清单时，该行的 ipa_source 会从 magpie_g2p 切换为 override。

进入步骤 2e 前的 HITL 试听关卡 — 失败时关闭。 在以下任一事项明确在对话中发生之前，不得合成完整笛卡尔积，不得将任何暂存的 IPA 候选提升至 pronunciation_overrides.csv，也不得进入阶段 3：

1. 用户确认已试听 QA 音频片段，并报告每段音频（或每个类别）的评定结果，例如：“MW 组听起来没问题”“修正 pembrolizumab”等。提供 afplay（macOS）或 paplay/aplay（Linux）命令，以便用户播放；然后停下并等待用户听完后回复。仅通过 AskUserQuestion 提示进行纸面批准——点击“全部提升”或“确认”但未试听——不满足此关卡要求。Magpie 验证 IPA 只能证明它属于音素库，不能证明它符合预期发音。只有用户的耳朵才能做到这一点。
2. 用户明确表示本轮跳过试听，并使用审慎明确的措辞（例如 “跳过试听，接受发音错误可能削弱阶段 3 KER 信号的风险——将此记录为 cycle-N 的注意事项”），而不是因一次点击操作附带跳过。请在周期级别的备注中记录此次跳过（例如 eval/cycle<N>/cycle_notes.md），以便未来操作人员知道试听已延期。

对于超过 100 行的任务，Magpie NVCF 会严格限流；返工既消耗 API 额度，也耗费时间——但更大的风险是发布包含错误发音参考音频的清单，悄然损害阶段 3 KER 信号。花时间试听，比重新运行整个周期代价更低。

2e. 完整基准生成

锁定发音后，生成完整的笛卡尔积 |terms| × |voices| × |noise_levels| × |context_types|。默认值：2–4 个 Magpie en-US 音色（Mia/Jason/Ray）、[clean, snr_15db, snr_5db]、[dictation, handoff, chart_note, history]。

独立合成，无需 /read-aloud。synthesize_row(row, all_overrides, out_dir, api_key) 配方——打开 NVCF gRPC 流，通过 render_sentence_with_overrides 将覆盖项封装到 SSML 中，并将 16 位单声道 PCM 写入 <out_dir>/audio/<slug>.wav——位于 references/pronunciation-pipeline.md（§Synthesis call）。关键不变量：all_overrides 包含 pronunciation_overrides.csv 中的每一项（包括 intravenously 等上下文词覆盖项），这样渲染器就会封装在 row['text'] 中出现的任何覆盖项。如果只封装 row['term']，上下文词覆盖项会被悄然丢弃。

噪声注入（clean → snr_15db → snr_5db）和清单架构（NeMo 标准字段 + 临床扩展，以及预检架构和音频存在性检查）均位于 references/manifest-schema.md。

当乘积 > 100 行时发出警告。 在大型任务中，Magpie NVCF 会限流，约有 5–10% 的请求因 RESOURCE_EXHAUSTED 而失败。重新运行失败的行。

第 2 阶段完成检查清单

只有所有五个子步骤都已运行，才能认为第 2 阶段完成。Agent 常常在 2a 或 2b 后就停止；目标是生成合成后的清单并完成交接：

• 2a — term_seed.csv，4–10 个术语，entity_category ∈ {drug, procedure, anatomy, condition, lab, role}
• 2b — 每个术语有 3–5 个 context_type 句子变体
• 2c — 每个术语都标记了 ipa_source ∈ {override, merriam-webster, magpie_g2p}
• 2d — 已试听 QA wav，并在获得用户明确批准后锁定 IPA 覆盖项
• 2e — manifest.jsonl + 笛卡尔积中每一行对应的音频
• 交接 — 将 /digital-health-clinical-asr-eval 指定为下一个技能，并将 KER 作为其核心指标

写入操作只能写入用户选择的 $EVAL_DIR/cycle<N>/。不要写入其他位置、修改环境或安装软件包——这些属于 /digital-health-clinical-asr-setup。

示例

场景 A——全新肿瘤学基准。 用户：“我们发现化疗药物名称经常被转录错误。我该从哪里开始？”→ 步骤 2a：确认专科为肿瘤学，询问具体涉及哪些药物（免疫治疗生物制剂、铂类药物、紫杉烷类）。提出约 10 个候选项：cisplatin、paclitaxel、pembrolizumab、nivolumab、carboplatin、docetaxel、bevacizumab、trastuzumab、cetuximab、pemetrexed。将它们的 entity_category 全部设为 drug，写入 term_seed.csv。步骤 2b：简要告知 /data-designer 为每个术语生成 4 个上下文变体，共 40 个句子。步骤 2c：逐个查询 MW——pembrolizumab 等生物制剂可能会使用 magpie_g2p，铂类药物则可能在 MW 中查到。步骤 2d：每个术语合成一个 QA wav，引导用户试听 pembrolizumab 等片段，并提出 IPA 候选读音，注意 -mab 后缀的重音模式。步骤 2e：获得批准后，运行 10 个术语 × 2 个音色 × 2 个噪声级别 × 3 个上下文 = 120 行。

场景 B——向现有周期追加内容。 用户：“我有一份 cycle-1 清单，想再添加 5 个手术项目。”→ 只需重新运行步骤 2a（仅针对新术语进行专科访谈）、2b（为新增术语生成句子）、2c（为新增术语运行 IPA 流程）、2d（试听新术语）和 2e（仅合成新术语对应的行）。追加到现有的 manifest.jsonl。不要为现有术语重新生成音频——有意隔离周期，确保排行榜可以清晰地比较 cycle N 与 cycle N+1。

生成的产物

• term_seed.csv — 筛选整理后的术语及其 entity_category
• pronunciation_overrides.csv — 已验证的 IPA，可跨周期追加
• manifest.jsonl — NeMo 格式，含临床扩展字段（每行一个 JSON 对象）
• audio/<slug>.wav — 合成的片段，每条清单记录对应一个

故障排查

• 生成超过 100 行时，TTS 触发速率限制并丢弃（RESOURCE_EXHAUSTED） → 这是 Magpie NVCF 的预期情况。确认 /read-aloud 中已启用指数退避；大型任务预计会丢弃约 5–10% 的行，请重新运行以补齐缺失项。
• 所有 ipa_source 行都标记为 magpie_g2p → MW 查询全面失败，或候选 IPA 未通过音素验证。重新验证所配置的 MW 路径（A 的 DICTIONARY_API_KEY；B 的 HTTPS 连通性和解析器），然后根据 Magpie 的 en-US 音素清单检查候选项。
• 即使使用 IPA 覆盖，Magpie 仍会误读某个术语 → 首先确认 IPA 存在于 Magpie 的 en-US 音素清单中，且 SSML 包装语法有效。如果两项都没问题，则底层 TTS 错误由 /read-aloud（/riva-tts）负责处理，请转至该处诊断。此技能提供覆盖机制，但不负责神经 G2P 或 SSML 解析器。
• /data-designer 生成的句子变体平淡，像模板 → 检查任务说明；仅包含架构的提示词有时会生成刻板内容。在任务说明中添加 1–2 个上下文示例，然后重新运行。
• 音频文件存在，但 manifest.jsonl 行数偏少 → 清单写入器跳过了合成时返回 NVCF 错误的行。仅包含缺失行，重新运行构建。

如果问题不在此列表中，请确定涉及哪个上游技能，并转至该技能。digital-health-clinical-asr-build 技能负责方法论，不负责 TTS 或 DataDesigner 的内部实现。

限制

• 默认仅支持英语。 两层 IPA 流水线会根据 Magpie 的 en-US 音素清单进行验证。其他地区语言需要不同的上游音素集和覆盖 CSV 格式。
• 实体类别固定为六种。 扩展 entity_category 属于有意的方法论变更，而非一次性调整——KER 细分、排行榜章节和下游微调脚本都依赖此词汇表。
• 首轮周期规模太小。 少于约 20 个术语时，按 ipa_source 划分的排行榜每个分组行数不足，无法得出有统计意义的结果。即使需要花费一个会话，也要构建有意义的周期。
• Magpie NVCF 有速率限制。 大型任务预计会丢弃约 5–10% 的行；请预留时间重新运行。

后续步骤

• 继续下一步： /digital-health-clinical-asr-eval — 转录清单，计算 WER/CER/KER/SER，并生成包含五个章节的排行榜。
• 返回设置（如果环境中有任何配置损坏）：/digital-health-clinical-asr-setup。
• 转至其他技能进行 TTS 专项调试：/read-aloud 或 /riva-tts。

参考资料

• references/manifest-schema.md — NeMo 标准字段和临床扩展；预检架构与音频存在性检查；跨周期稳定性规则