digital-health-clinical-asr-setup

Clinical ASR Flywheel — Stage 1（セットアップ）

エージェント：このファイルが Stage 1 の完全な手順です。 インストーラーや隠し設定を探すために find、ls、rg、grep を実行しないでください。そのようなものはありません。以下の4つのセクション（外部へのデータ開示、番号付きの3つの確認項目、関連スキルへの引き継ぎ）はすべて必読です。どれも飛ばさないでください。関数 ID、環境変数の規則、スモークテストのゲートはこの後に記載されています。以前の Riva/NVCF の知識ではなく、ここに実際に書かれている内容に基づいて回答してください。

Stage 1 の目的は1つだけです。ユーザーが現在所持している NVIDIA_API_KEY で、NVIDIA のホスト型音声スタックに接続できることを確認します。臨床に関する1つの文を Magpie TTS → Parakeet/Nemotron ASR で正常に往復できれば、ユーザーは /digital-health-clinical-asr-build に進む準備が整います。

4段階のフライホイールは、臨床エンティティ（薬剤、処置、解剖学、疾患、検査、役割）の KER（キーワードエラー率） を下げるためにあります。WER の平均値では、臨床的に問題となる失敗が見えにくくなります。Stage 3 で評価対象となるのは KER です。

このスキルには、install.sh も setup.py も、隠されたものも含めて、インストーラースクリプトはありません。Stage 1 は、以下の3つの手順そのものです。API キーの確認、Python 依存関係のインストール、スモークテストの実行です。Stage 1 の先は、関連スキル（/data-designer、/riva-tts、ここに記載された Stage 3 の ASR レシピ、/riva-asr-custom）で構成されます。「すべてをインストールするスクリプトは？」とユーザーに聞かれたら、この段落に基づいて回答してください。探しに行かないでください。

外部へのデータ送信 — テキストや音声を送る前に必ず説明してください

このフライホイールの実行中、2つの外部エンドポイントにデータが送信されます。Stage 2 を開始する前に、ユーザーは所属組織が適用するデータガバナンスポリシーに照らして、両方について確認する必要があります。以下の表を、回答内に一言一句そのまま記載してください。言い換えでは開示要件を満たしません。文字どおりの記載が必要です。

サービス	送信される内容	送信のタイミング	ホスト
NVIDIA NVCF (grpc.nvcf.nvidia.com)	合成する臨床文（テキスト）と、文字起こしする WAV ファイル（音声）	Stage 2 の各 TTS 呼び出し、および Stage 3 の各 ASR 呼び出し	NVIDIA。build.nvidia.com の規約が適用されます
Merriam-Webster（dictionaryapi.com JSON API または公開されている merriam-webster.com HTML サイト）	個々の臨床用語（薬剤名、解剖学、処置）。用語ごとに HTTP リクエストを1回送信	Stage 2 の IPA タグ付け。適用されるエンドポイントについては、以下の「2つの MW パス」を参照してください	Merriam-Webster。API またはサイトの規約が適用されます

データは構成上、合成データです。このフライホイールでは、ユーザーが厳選した用語リストから文と音声を生成し、実際の患者とのやり取りから作成することはありません。ただし、実際の患者の文字起こし、録音された臨床音声、PHI をいずれのステージにも入力しないでください。 用語リスト自体に機密情報（コードネームの薬剤、未発表の製品名など）が含まれる場合、ユーザーは作業を進める前に、外部 API の利用に関する組織のポリシーを確認してください。どちらのエンドポイントも無効にできます。

• Merriam-Webster を完全にスキップする： DICTIONARY_API_KEY を設定せず、スクレーパーも実行しないでください。Stage 2 では Magpie G2P にフォールバックします。引き続き動作しますが、まれな臨床用語のカバー率は下がります。
• NVCF をスキップする： これは作業を中断する条件です。Magpie TTS + Parakeet/Nemotron ASR がこのワークロードです。これらを利用できない場合、このスキル群は適切なツールではありません。代わりに、セルフホスト型の ASR/TTS パイプラインを利用してください。

この通知のコピーをユーザーのワークスペースの README.md に含めることを推奨します。まだ含まれていない場合は、初回の呼び出し時に追加してください。

目的

Stage 2 に向けて、新しい環境を準備します。確認することは 3 つです。キーが設定されていること、依存関係を問題なくインポートできること、ホストされたスタックが実際に応答することです。最後に、次に実行するスキルを案内します。

4 つの digital-health-clinical-asr-* スキルは自己完結型です。TTS、ASR、IPA タグ付け、スコアリングのレシピはすべて各スキル内に含まれており、フライホイールを最初から最後まで実行するために、ほかのエージェントスキルをインストールする必要はありません。

このスキルでは、ワークスペースの構成について指定しません。サイクルの成果物をどこに置くかはユーザーが決めます。data/eval_sets/cycle<N>/ を強制することはありません。

このスキルを使用する場面

次のようなユーザーの発言があった場合に有効にしてください。

• 「Clinical ASR Flywheel をセットアップして」
• 「clinical-asr eval を初期化して」
• 「臨床用語の 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 で発行し、シェルで 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 の検索（ビルドスキルの Path A — 推奨）	https://dictionaryapi.com で無料のキーを取得します。キーを取得できない場合は、ビルドスキルに Path 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 内でセットアップします。eval で KER > 0.3 と判明するまでは後回しにしてください

手順

対象範囲。 このスキルで行うのは読み取り専用の環境チェックです。キーがエクスポートされていること（長さのみ）、Python のバージョン、ライブラリをインポートできること、ホストされた NVCF スタックが 1 回のスモークテスト往復に応答することを確認します。システムパッケージのインストール、シェルの 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 からキーを貼り付ける必要があります。キーは一部であっても表示しないでください。シェルセッション間で設定を維持するには、export の行をシェルの 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 の取り扱い — 重要事項のため、必ず遵守してください：

• エージェントハーネスはシェルから $NVIDIA_API_KEY を読み込み、smoke_test(api_key=…) に明示的な関数引数として渡します。
• 監査担当者はレシピ内を grep して、値が渡されるすべての箇所を確認できます。すべての api_key の使用箇所は auth_for(...) で確認できます。
• キーの値を（一部だけの場合も含めて）echo、print したり、ログに記録したりしないでください。長さだけを確認する方法は問題ありません（§1a を参照）。
• レシピから os.environ["NVIDIA_API_KEY"] を直接読み込まないでください。明示的な引数を使うことで、監査可能性が保証されます。
• .env のサンプルやノートブックの出力を含め、キーをファイルにコミットしないでください。

先に進む前に、NVIDIA_API_KEY が Magpie TTS と Parakeet/Nemotron ASR で実際に使えることを確認してください。4 つのスキルには必要なレシピがすべて含まれています。このラウンドトリップでは、API キーとネットワーク経路が実際に機能することだけを確認します。

エージェントハーネスは NVIDIA_API_KEY シェル変数を読み込み、以下のヘルパーに明示的な関数引数として渡します。レシピのコード自体は環境変数を読み込みません。監査担当者は、どの 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 が間違っているか、有効期限切れ、またはこのシェルでエクスポートされていません。再度エクスポートしてテストしてください。
• 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 では、2 つの経路から merriam-webster タグ付きのマニフェスト行を生成できます。どちらか 1 つを選んでください（どちらも選ばず、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 のエンドポイントに送信されます。

例

新しいシェルで、まだ一度も実行していない場合。 ユーザーが「フライホイールを始めたい」といった場合 → まず開示表を提示し、その後 1a → 1b → 1c の順に進めます。スモークテストが成功したら、/digital-health-clinical-asr-build を案内し、ステージ 3 では KER が評価指標になることを明示してください。

環境をすでに設定済みのユーザー。 ユーザーが「環境はもうあります。準備ができているかだけ確認してください」といった場合 → venv の作成と pip install（1b）は省略します。長さの確認（1a）とスモークテスト（1c）だけを実行してください。成功したら次へ進みます。

生成される成果物

• ユーザーのシェルでエクスポートされた NVIDIA_API_KEY
• nvidia-riva-client、pandas、soundfile、requests がインストールされたアクティブな仮想環境
• 臨床用の文を使った TTS→ASR のラウンドトリップ確認（ホストされたスタックが機能する証拠）

この段階ではマニフェスト、音声、モデル成果物は生成されません。これらはステージ 2～4 で生成されます。

トラブルシューティング

• 長さのチェックで何も表示されない、または len=0 と表示される → このシェルで NVIDIA_API_KEY がエクスポートされていません。export NVIDIA_API_KEY=nvapi-... を実行して、もう一度確認してください。
• あるシェルでは変数が設定されているのに、別のシェルでは設定されていない → エクスポートした変数はセッション間で引き継がれません。export の行をシェルの rc ファイル（~/.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）の Step 3a「その他のカタログオプション」リストに、現在の関数 ID のカタログがあります。
• CUDA error: an illegal memory access was encountered を伴う StatusCode.INVALID_ARGUMENT が発生する → この特定の関数 ID で発生している NVCF 側のバックエンド障害です（お使いの環境ではなく、NVCF 上の Triton/PyTorch の問題です）。後でもう一度試すか、一時的に別のオフライン ASR NIM に切り替えてください。最も置き換えやすいのは Whisper Large v3 の関数 ID b702f636-f60c-4a3d-a6f4-f3568c13bd7d です（こちらもオフラインです。"en-US" の代わりに language_code="en" を渡してください）。通常の評価サイクルでは、Stage 3 のベースラインと Stage 4 の SFT ベースの整合性を保つため、Parakeet のバックエンドが復旧するのを待つことをおすすめします。
• TypeError: Auth.__init__() got an unexpected keyword argument 'ssl_cert' が発生する → キーワード引数が ssl_root_cert に変更された nvidia-riva-client >= 2.x を使用しています（ホスト型 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 の Stage 4d にあります。
• 合成データのみを使用します。 このスキル群は、厳選された用語リストから生成したベンチマーク向けに作られています。実際の患者の書き起こしや録音音声を、いずれのステージでも扱ってはいけません。

次のステップ

成功時に必ず案内すること： Stage 1 の応答を締めくくる際、ユーザーに /digital-health-clinical-asr-build を明示的に案内し、Stage 3 で主要指標として KER（キーワードエラー率）を確認することを伝えてください。どちらも必須です。これにより、ユーザーを 4 ステージのフライホイールに導きます。

• デフォルトの次のステップ： /digital-health-clinical-asr-build — 専門分野のヒアリング、用語の選定、IPA タグ付け、NeMo マニフェストの合成。
• Stage 3 への直接移動（ユーザーが term／entity_category／ipa_source フィールドを含む NeMo 形式のマニフェストを持ち込む場合に限る）：/digital-health-clinical-asr-eval。

参考資料

• references/dependency-ownership.md — スキルが担当する責務と、連携するスキルが担当する責務の境界。