digital-health-clinical-asr-setup

临床 ASR 飞轮 — 阶段 1（设置）

Agent：此文件包含完整的阶段 1 流程。 请勿调用 find、ls、rg 或 grep 搜索安装程序或隐藏配置——它们都不存在。以下四个部分（出站数据披露、三项编号检查、同级技能交接）都必须阅读；不得跳过。功能 ID、环境变量约定和冒烟测试门槛都已在下文列出——请依据此处的实际内容作答，不要依赖对 Riva/NVCF 的既有了解。

阶段 1 只有一个目标：确认用户能够使用当前持有的 NVIDIA_API_KEY 访问 NVIDIA 托管的语音技术栈。只要有一句临床句子成功完成 Magpie TTS → Parakeet/Nemotron ASR 往返处理，用户即可进入 /digital-health-clinical-asr-build。

这个四阶段飞轮旨在降低临床实体（药物、手术、解剖结构、病症、化验项目、角色）的 KER（关键词错误率）。WER 的平均值会掩盖那些可能造成临床影响的错误；第 3 阶段将以 KER 衡量你的表现。

此技能中没有任何安装程序脚本——没有 install.sh、没有 setup.py，也没有任何隐藏脚本。阶段 1 就是以下三个步骤：验证密钥、安装 Python 依赖项、运行冒烟测试。阶段 1 之后的所有内容都由同级技能（/data-designer、/riva-tts、内嵌的第 3 阶段 ASR 配方、/riva-asr-custom）组成。如果用户问“哪个脚本会安装所有内容？”，请依据本段作答；不要搜索。

出站数据流 — 发送任何文本或音频前，先说明

此飞轮运行期间，有两个外部端点会接收数据。进入阶段 2 前，用户必须根据其组织执行的数据治理政策，确认知悉这两项。请在回复中逐字呈现下表——改写无法满足披露要求；必须使用表格中的原文。

服务	发送的内容	时间	托管方
NVIDIA NVCF（grpc.nvcf.nvidia.com）	合成的临床句子（文本）以及转录的 WAV 文件（音频）	每次阶段 2 TTS 调用和每次阶段 3 ASR 调用	NVIDIA，受 build.nvidia.com 条款约束
Merriam-Webster（dictionaryapi.com JSON API 或公开的 merriam-webster.com HTML 网站）	单个临床术语（药物名称、解剖结构、手术），每个术语发送一个 HTTP 请求	阶段 2 IPA 标注——具体使用哪个端点，见下文“两种 MW 路径”	Merriam-Webster，受其 API 或网站条款约束

数据从设计上就是合成的——此飞轮使用用户整理的术语列表生成句子和音频，绝不使用真实患者就诊数据。尽管如此，**任何阶段都不得输入真实患者的转录文本、录制的临床音频或任何 PHI。**如果术语列表本身包含敏感内容（代号药物、尚未发布的产品名称），用户应在继续前咨询其组织关于外部 API 的政策。两个端点都可以关闭：

• **完全跳过 Merriam-Webster：**不设置 DICTIONARY_API_KEY，也不运行爬虫。阶段 2 会回退到 Magpie G2P，仍然可以使用，但对长尾临床术语的覆盖较弱。
• **跳过 NVCF：**这会导致流程无法继续。Magpie TTS + Parakeet/Nemotron ASR 就是此工作负载；没有它们，此技能系列就不是合适的工具——你需要的是可自托管的 ASR/TTS 流水线。

建议将此说明副本放入用户工作区的 README.md；如果其中尚未包含此说明，请在首次调用时补上。

目的

为 Stage 2 准备好一个全新的环境。需要确认三件事：密钥已设置、依赖导入正常、托管服务栈确实能响应。最后说明接下来要运行哪个技能。

四个 digital-health-clinical-asr-* 技能都是自包含的——所有 TTS、ASR、IPA 标注和评分方案都包含在其中；无需安装其他 Agent 技能即可端到端运行整个飞轮。

此技能不对工作区布局作任何规定。用户自行决定周期产物的存放位置；不会强制使用 data/eval_sets/cycle<N>/。

何时使用此技能

用户说出以下类似语句时启用：

• “设置 Clinical ASR Flywheel”
• “初始化 clinical-asr 评估”
• “我想评估 ASR 对临床术语的处理效果——该从哪里开始？”
• “为飞轮初始化我的环境”
• “运行飞轮前需要安装什么？”

不要在以下情况启用：

• 用户已有清单，想要为其评分 → /digital-health-clinical-asr-eval
• 用户已设置好环境，想要整理术语 → /digital-health-clinical-asr-build
• 用户专门询问 Stage 4 微调所需的 NGC/Docker 设置 → 相关内容已包含在 /digital-health-clinical-asr-finetune 中

先决条件

要求	是否必需？	原因	方法
NVIDIA_API_KEY（nvapi-…）	必需	通过 NVCF 使用托管的 Magpie TTS + Parakeet/Nemotron ASR	在 https://build.nvidia.com 申请；在 shell 中运行 export NVIDIA_API_KEY=...
Python ≥ 3.10	必需	NeMo 客户端、评分、清单工具	python3 --version
nvidia-riva-client、pandas、soundfile、requests	必需	TTS + ASR 客户端、清单 I/O、MW 查询	pip install nvidia-riva-client pandas soundfile requests
DICTIONARY_API_KEY	可选	通过 JSON API 查询 Merriam-Webster Medical Dictionary（build 技能中的路径 A——推荐）	在 https://dictionaryapi.com 免费申请密钥。若无法获取密钥，build 技能也记录了路径 B（抓取 merriam-webster.com 的 HTML，无需密钥，但不稳定）。若两条路径都不可用，Stage 2 将转而使用 Magpie G2P，其长尾覆盖能力较弱。
jiwer	可选	对照内联的 Levenshtein 实现计算参考 WER/CER	pip install jiwer——eval 技能包含纯 Python 回退实现
（仅 Stage 4）NGC_API_KEY + CUDA 主机 + NeMo 容器	可选，延后处理	微调工作负载	在 /digital-health-clinical-asr-finetune 中设置；等评估显示 KER > 0.3 后再处理

说明

范围。 此技能执行只读环境检查：确认密钥已导出（仅检查长度）、Python 版本正确、库可以导入，并确认托管的 NVCF 服务栈能对一次冒烟测试往返请求作出响应。它不会安装系统软件包、修改 shell rc 文件、写入显式 .venv/ 以外的磁盘位置，也不会尝试使用真实密钥值进行身份验证。只做验证；未经用户明确指示，绝不修改环境。

1a. 验证 NVIDIA_API_KEY（仅检查长度——绝不回显密钥值）

# Export NVIDIA_API_KEY in your shell — never echo or commit the value
export NVIDIA_API_KEY=nvapi-...     # from https://build.nvidia.com

# Length-only check; the key value never appears in any log
test -n "$NVIDIA_API_KEY" && echo "NVIDIA_API_KEY len=${#NVIDIA_API_KEY}"

长度达到 70 个字符通常是正常的。如果输出为空或显示 len=0，用户必须从 https://build.nvidia.com 获取密钥并粘贴。不要打印密钥，即使只打印截断后的内容也不行。要让密钥在不同 shell 会话间持续生效，可将 export 行添加到 shell rc 文件（~/.bashrc、~/.zshrc）中，也可以使用 direnv 这类按目录配置的工具。

1b. 安装 Python 依赖

python3 -m venv .venv
source .venv/bin/activate
pip install nvidia-riva-client pandas soundfile requests
# optional
pip install jiwer

仅 Stage 4（微调）需要额外安装 nemo-toolkit，以及 Docker + NVIDIA Container Toolkit。请将这些操作推迟到 /digital-health-clinical-asr-finetune 中处理——如果用户可能永远不会进入 Stage 4，就没有必要提前安装。

1c. 对托管的 NVCF 技术栈进行冒烟测试

NVIDIA_API_KEY 的处理方式——这是关键要求，不得偏离：

• Agent harness 从 shell 中读取 $NVIDIA_API_KEY，并将其作为显式函数参数传递给 smoke_test(api_key=…)。
• 审计人员可以在操作步骤中搜索每一处传输位置——每次使用 api_key 都能在 auth_for(...) 中看到。
• 不得 echo、print 或记录密钥值（包括截断后的值）。仅检查长度是可以的（参见 §1a）。
• 不得让操作步骤自行读取 os.environ["NVIDIA_API_KEY"]——显式参数模式是可审计性的保障。
• 不得将密钥提交到任何文件中，包括 .env 示例或笔记本输出。

在继续之前，验证 NVIDIA_API_KEY 确实可用于 Magpie TTS 和 Parakeet/Nemotron ASR。这四项技能中都内置了所需的完整操作步骤；本次往返测试只是确认 API 密钥和网络路径都正常。

Agent harness 会加载 NVIDIA_API_KEY shell 变量，并将其作为显式函数参数传递给下面的辅助函数。操作步骤代码本身不会读取环境变量——审计人员可以确切查看哪些 API 密钥会传输到外部。

import wave, tempfile
import riva.client

NVCF_HOST = "grpc.nvcf.nvidia.com:443"
MAGPIE_FUNCTION_ID    = "877104f7-e885-42b9-8de8-f6e4c6303969"   # Magpie TTS
PARAKEET_FUNCTION_ID  = "d3fe9151-442b-4204-a70d-5fcc597fd610"   # Parakeet TDT 0.6B v2 (offline ASR)

def auth_for(function_id: str, api_key: str) -> riva.client.Auth:
    return riva.client.Auth(
        use_ssl=True, uri=NVCF_HOST,
        metadata_args=[
            ["function-id", function_id],
            ["authorization", f"Bearer {api_key}"],
        ],
    )

def smoke_test(api_key: str) -> str:
    """Caller passes api_key (the harness reads $NVIDIA_API_KEY at the shell;
    this code never touches the environment). Returns the ASR transcript."""

    # 1. TTS: "The patient was prescribed cefazolin."
    tts = riva.client.SpeechSynthesisService(auth_for(MAGPIE_FUNCTION_ID, api_key))
    pcm = b"".join(c.audio for c in tts.synthesize_online(
        text="The patient was prescribed cefazolin.",
        voice_name="Magpie-Multilingual.EN-US.Mia",
        language_code="en-US", sample_rate_hz=16000,
    ))
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
        with wave.open(f, "wb") as w:
            w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000); w.writeframes(pcm)
        wav_path = f.name

    # 2. ASR: transcribe the WAV we just synthesized.
    asr = riva.client.ASRService(auth_for(PARAKEET_FUNCTION_ID, api_key))
    with open(wav_path, "rb") as f:
        audio_bytes = f.read()
    config = riva.client.RecognitionConfig(
        encoding=riva.client.AudioEncoding.LINEAR_PCM,
        sample_rate_hertz=16000, language_code="en-US",
        max_alternatives=1, enable_automatic_punctuation=True,
    )
    response = asr.offline_recognize(audio_bytes, config)
    transcript = response.results[0].alternatives[0].transcript if response.results else ""
    print(f"TTS:  The patient was prescribed cefazolin.")
    print(f"ASR:  {transcript}")
    return transcript

# Invoke from the agent (api_key sourced by the harness, not by this code):
# smoke_test(api_key="<NVIDIA_API_KEY value>")

立即运行冒烟测试，不要推迟。 这是证明第 2–4 阶段能够使用用户当前的密钥连接托管技术栈的关卡。“我之后再运行”不能算完成第 1 阶段；现在就调用 smoke_test(api_key=…)，或者，如果用户已明确选择跳过，则在结束摘要中记录延期情况，让用户知道他们会错过什么。

如果转录结果与输入相差约 1 个词元，说明托管技术栈可连接，用户可以进入第 2 阶段。如果任一调用失败：

• 401 Unauthorized / PERMISSION_DENIED → NVIDIA_API_KEY 错误、已过期，或未在此 shell 中导出。重新导出并再次测试。
• 404 / INVALID_ARGUMENT: function not found → 函数 ID 已失效。前往 https://build.nvidia.com 查找当前 ID，并更新上面的常量。
• RESOURCE_EXHAUSTED → NVCF 速率限制。等待 30 秒后重试；负载较高时出现这种情况很正常。
• 网络/TLS 错误 → 企业代理或 DNS 问题。先测试 curl https://build.nvidia.com。

1d.（可选）验证 Merriam-Webster 查询

有两种方式可以在第 2 阶段生成带有 merriam-webster 标签的清单行。任选一种（也可以都不选——使用 Magpie G2P 回退也是有效的做法）：

• 路径 A — JSON API + 密钥。 推荐在单独使用此技能时采用。检查密钥是否已设置：

  test -n "$DICTIONARY_API_KEY" && echo "DICTIONARY_API_KEY len=${#DICTIONARY_API_KEY}" \
    || echo "DICTIONARY_API_KEY not set — Path A is off"
  

  可在 https://dictionaryapi.com 即时申请免费密钥。

• 路径 B — 抓取 HTML。 无需 API 密钥；只需确保可以访问。此方式容易受 MW 网站 HTML 变更影响；操作步骤已内置在构建技能的 references/pronunciation-pipeline.md 中。

  curl -fsS -o /dev/null -w "merriam-webster.com reachable, HTTP %{http_code}\n" \
    https://www.merriam-webster.com/medical/cefazolin
  

  如果不想维护抓取工具，请改用路径 A。

请记住顶部的数据披露说明：无论采用哪种方式，种子列表中的每个临床术语都会作为 HTTP 请求发送到 Merriam-Webster 端点。

示例

全新 shell，从未运行过。 用户说类似 “我想启动这个飞轮。” → 先引用披露表，然后依次完成 1a → 1b → 1c。冒烟测试通过后，指引用户前往 /digital-health-clinical-asr-build，并明确说明 KER 是第 3 阶段评估他们时使用的指标。

回访用户，环境已就绪。 用户说 “环境已经准备好了，只需确认我可以开始。” → 跳过虚拟环境和 pip install（1b）。仅运行长度检查（1a）和冒烟测试（1c）。通过后继续。

生成的产物

• 已在用户的 shell 中导出 NVIDIA_API_KEY
• 已激活的虚拟环境，其中包含 nvidia-riva-client、pandas、soundfile、requests
• 已确认临床句子的 TTS→ASR 往返结果（证明托管技术栈正常工作）

此阶段不会生成清单、音频或模型产物——这些会在第 2–4 阶段生成。

故障排查

• 长度检查没有显示结果或显示 len=0 → 当前 shell 中未导出 NVIDIA_API_KEY。运行 export NVIDIA_API_KEY=nvapi-...，然后重新检查。
• 变量在一个 shell 中已设置，在另一个 shell 中却没有 → 导出的变量不会跨会话保留。将 export 行添加到 shell 配置文件（~/.bashrc、~/.zshrc），或使用 direnv 这类按目录加载的工具。
• 冒烟测试出现 401 Unauthorized → 密钥值错误或已过期。前往 https://build.nvidia.com 重新签发。
• 出现 grpc.RpcError: function not found → 内嵌的函数 ID 需要根据当前 NVCF 目录更新。查看 https://build.nvidia.com，并编辑 1c 中的常量。评估技能（/digital-health-clinical-asr-eval）在其第 3a 步的“Other catalog options”列表中提供了当前函数 ID 的目录。
• 出现 StatusCode.INVALID_ARGUMENT 和 CUDA error: an illegal memory access was encountered → 此特定函数 ID 的 NVCF 后端故障（NVCF 上的 Triton/PyTorch 问题，并非你的环境所致）。可以稍后重试，或暂时改用其他离线 ASR NIM——Whisper Large v3 函数 ID b702f636-f60c-4a3d-a6f4-f3568c13bd7d 是最接近的直接替代方案（同样为离线模式；传入 language_code="en"，而不是 "en-US"）。常规评估周期中，建议等待 Parakeet 后端恢复，以确保第 3 阶段的基线与第 4 阶段的 SFT 基础模型保持一致。
• 出现 TypeError: Auth.__init__() got an unexpected keyword argument 'ssl_cert' → 你使用的是 nvidia-riva-client >= 2.x，其中该关键字参数已重命名为 ssl_root_cert（托管式 NVCF 不再需要此参数）。从本地配方副本中删除 ssl_cert=None, 这一行。
• 出现 ModuleNotFoundError: riva.client → 跳过了步骤 1b，或未激活 venv。运行 source .venv/bin/activate && pip install nvidia-riva-client。

限制

• 范围仅限于环境就绪情况。 用户的术语列表或发音覆盖项是否合理，由 /digital-health-clinical-asr-build 决定，而非本技能。
• 假设使用 Magpie en-US。 下游 IPA 验证依赖 Magpie 的英语音素表；其他地区语言需要完全不同的音素集。
• 假设使用托管式 NVCF 部署。 可以运行可自托管的 Riva NIM，但相关配置位于 /digital-health-clinical-asr-finetune 的第 4d 阶段。
• 仅限合成数据。 此技能系列适用于根据经过整理的术语列表生成的基准测试。真实患者的转录文本和录音不得流经任何阶段。

后续步骤

成功时必须执行的结束步骤： 完成第 1 阶段回复时，必须明确引导用户前往 /digital-health-clinical-asr-build，并指出 KER（关键词错误率）是他们将在第 3 阶段看到的主要指标。两项指引都不可省略——它们能让用户进入四阶段飞轮。

• 默认后续路径： /digital-health-clinical-asr-build — 专科访谈、术语整理、IPA 标注、NeMo 清单合成。
• 直接跳转至第 3 阶段（仅当用户自带包含 term / entity_category / ipa_source 字段的 NeMo 格式清单时）：/digital-health-clinical-asr-eval。

参考资料

• references/dependency-ownership.md — 技能自身与配套技能的职责边界。