digital-health-clinical-asr-eval

Clinical ASR Flywheel — Stage 3（評価）

⚠ エージェント：回答する前に、以下の「重要なワークフロールール」セクションをお読みください。 この SKILL.md は自己完結型です。evals/、references/、assets/ は参照先であり、不可欠な情報は含まれていません。方法に関する質問にはこのファイルの内容に基づいて回答してください。実際のマニフェストに対する実行をユーザーが明示的に求めた場合に限り、ツールを呼び出してください。

あなたはスコアリングとルーティングを担う段階です。ユーザーが NeMo 形式の manifest.jsonl（/digital-health-clinical-asr-build で作成されたもの、または別の場所から持ち込まれたもの）を用意してきます。選択された ASR NIM で文字起こしを行い、4 つの指標をスコアリングし、5 セクションのリーダーボードを作成してから、意思決定ツリーに従って、ユーザーが /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、マニフェストの各行につき 1 回

クリップはステージ 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. リーダーボードは次の5セクションの順序にします。 全体指標（WER/CER/KER/SER）→ entity_category 別 KER → ipa_source 別 KER → noise_level 別 KER → 用語別 KER（最悪のものから）。ipa_source 別のセクションは必須です。SSML パイプラインが機能している証拠となるためです。

目的

臨床 ASR マニフェストをスコアリングし、5セクション構成の KER リーダーボードを作成して、評価後の判断ツリーに従ってユーザーを案内します。方法論の詳細（指標の定義、正規化、リーダーボードの順序、特別なケースの案内）は、上記の重要なワークフロールールと以下の手順に記載されています。

このスキルを使用するタイミング

次のようなユーザーの発言があった場合に有効化します。

• 「ASR マニフェストをスコアリングして」
• 「Parakeet TDT v2 の KER は？」
• 「cycle-N で評価を実行して」
• 「臨床ベンチマークで 2 つの ASR モデルを比較して」
• 「リーダーボードを生成して」
• 「manifest.jsonl があるのですが、どうスコアリングすればよいですか？」
• 「WER が 0.07 なのに、KER が 0.4 なのはなぜですか？」
• 「ファインチューニングすべきですか？」（これは評価側の質問です。評価後の判断ツリーはこのスキルに記載されています）

文字列キーワードによる非アクティベーション確認 — ユーザーのメッセージに authenticate、API key、bearer、function ID、gRPC、streaming、chunking、batching、transcription retry、riva-build、riva-deploy、NIM deploy、NGC、Docker、Container Toolkit のいずれかが含まれている場合、または「which ASR model is best」「compare models」「vendor differences」と尋ねている場合は、スコアリングのワークフローを有効化しないでください。上記の重要なワークフロールール #1 に従って適切な兄弟スキルへ案内し、そこで終了してください。ユーザーが同時に「KER」や「eval」に言及していても、このルールは適用されます。

前提条件

• NeMo 形式のマニフェスト。臨床用拡張フィールド（term、entity_category、ipa_source、voice_id、noise_level、context_type）が必要です。スキーマについては、ビルドスキルの references/manifest-schema.md に記載されています。
• NVIDIA_API_KEY がエクスポートされていること（Stage 1 の前提条件も引き続き適用されます）。
• nvidia-riva-client + soundfile がインストールされていること（Stage 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 レシピにも対応しているため、Stage 3 のベースラインと Stage 4 のファインチューニングで、同じモデルファミリーを利用できます。

実行時の環境変数による上書き設定が 3 つあります（リーダーボード表示用の ASR_MODEL_NAME、別のホスト型 NIM に切り替えるための ASR_NVCF_FUNCTION_ID、セルフホスト型 gRPC 用の ASR_ENDPOINT）。function ID と呼び出し形式に関する注記を含む、代替 NIM の全カタログ（Parakeet TDT 1.1B、Parakeet CTC 1.1B、Whisper Large v3、Nemotron ストリーミング）については、references/offline-asr-recipe.md を参照してください。

API クレジットを消費する前に、選択した NIM、解決された function-id、環境変数による上書き設定があれば、それらをユーザーに提示してください。ホスト型 Parakeet TDT v2 で 200 行のマニフェストを処理するのは低コストですが、1,000 行のマニフェストを誤って別のモデルで処理すると、そうはいきません。

3b. 文字起こしする

manifest.jsonl の各行について、audio_filepath を文字起こしし、per_sample.json に書き込みます（各行に JSON オブジェクトを 1 つずつ記録します。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（またはセルフホスト型 Riva 用に ASR_ENDPOINT が設定されている場合はそのエンドポイント）へのオフライン gRPC ストリームを開き、各行に対して riva.client.ASRService.offline_recognize を呼び出し、上記の JSONL を書き込みます。臨床用マニフェストの各文は 30 秒以下のため、ストリーミングやバッチ処理は不要です。Stage 1 のセットアップ動作確認と同じ auth_for 形式を使います。エージェントハーネスは api_key を明示的に渡します。レシピでは、環境変数による 3 つの上書き設定（ASR_NVCF_FUNCTION_ID、ASR_MODEL_NAME、ASR_ENDPOINT）を先頭で読み込むため、監査担当者は設定箇所をまとめて確認できます。

Parakeet の NVCF バックエンドが Triton から CUDA illegal-memory-access エラーを返す場合の Whisper フォールバック と、セルフホスト型 Riva NIM（ASR_ENDPOINT=localhost:50051）の環境変数パターンについては、references/offline-asr-recipe.md（§Whisper fallback、§Self-hosted Riva NIM）を参照してください。

回復性に関する設定はユーザーに委ねます。 バッチ処理の途中で NVCF が RESOURCE_EXHAUSTED を返した場合、その行でループはエラーになります。失敗した行から再実行してください。ストリーミング、バッチ処理、バックオフ付き再試行は対象外です。詳しくは /riva-asr を参照してください。

3c. 4つの指標をスコアリングする

すべての行について、次を計算します。

指標	測定内容	保持する理由
WER	単語誤り率（正規化後のトークンに対するレーベンシュタイン距離）	業界標準。臨床領域には粗すぎる指標
CER	文字誤り率	長い複合名での惜しい誤りを捉える
KER ★	キーワード誤り率 — フラグが立てられた term が仮説に（正規化済みで、連続一致で）出現したか？	臨床上の主要シグナル
SER	文誤り率（1つでも誤りがあれば1、完璧なら0）	健全性の目安。医師が実際に体験するもの

正規化（4つの指標すべての前に、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. 内訳 + リーダーボード

5セクションの Markdown リーダーボードを、この順序で書きます。

1. ヘッドライン — 選択したモデルの総合 WER、CER、KER、SER。
2. entity_category 別の KER — 薬剤 vs 処置 vs 解剖 vs ... デプロイにおいて、ユーザーが実際に気にするものです。
3. ipa_source 別の KER — リーダーボードの中で最も情報量の多い単一の数値です。 merriam-webster と magpie_g2p の行の差分は、SSML オーバーライドパイプラインが実際に機能している証拠です。このセクションをユーザーに音読してください。
4. noise_level 別の KER — 臨床環境は騒がしいです。snr_5db の行は clean よりも現実に近いです。
5. 用語別 KER（ワースト順）— これらが Stage 4 のファインチューニング対象です。

merriam-webster vs magpie_g2p の差分解釈を含む代表的な ipa_source の内訳：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-finetune ではなく、/digital-health-clinical-asr-build の Step 2d（IPA QA レビュー）に戻してください。TTS 発音のギャップに対してファインチューニングすると、モデル自身の誤りを誤認識するようにモデルを教え込むことになります — 間違った修正です。

例

シナリオ A — サイクル 1 の新しいマニフェストで初回評価を行う場合。 ユーザー：「すでに term フィールドと entity_category フィールドを含む臨床音声データの行が 200 件ある manifest.jsonl を持っています。どうスコアリングすればよいですか？」→ ステージ 2 は完全にスキップします。音声の存在確認を事前に行います。デフォルトの parakeet-tdt-0.6b-v2 を選び、選択内容と解決済みの function-id をユーザーに伝えます。インラインのステップ 3b の手順（transcribe_manifest(...)）を実行します。4 つの指標をスコアリングします。5 セクションのリーダーボードを作成します。ipa_source 別の内訳をユーザーに伝えます。薬剤の KER に基づいて判断ツリーを適用します。

シナリオ B — 結果が混在している場合の解釈。 ユーザー：「評価では、merriam-webster のタグが付いた行の KER は 0.05 ですが、magpie_g2p のタグが付いた行では 0.40 です。ファインチューニングすべきですか？」→ いいえ、これは特殊なケースです。モデルに問題はなく、発音ヒントがロングテールの用語を十分にカバーできていません。ユーザーを /digital-health-clinical-asr-build のステップ 2d に戻し、magpie_g2p の行を試聴して、確認済み IPA を pronunciation_overrides.csv に追加するよう案内します。ステージ 4 を再検討する前に、再ビルド後にステージ 3 を再実行します。

生成される成果物

• per_sample.json — 行ごとの文字起こし結果。すべての臨床拡張フィールドが保持されます（ASR の hyp を、マニフェストの ref とメタデータに結合したもの）
• results.csv — 行ごとの WER/CER/KER/SER スコア
• leaderboard_cycle<N>.md — 5 セクションの Markdown レポート

（ファイル名はユーザーが指定します。上記の名前は、このスキル内で使用される規約です。）

トラブルシューティング

• 「マニフェストが見つかりません」 → ユーザーがステージ 2 をスキップしています。/digital-health-clinical-asr-build に案内するか、$MANIFEST_PATH を確認します。
• すべての行で KER=1 → ref と hyp の正規化に不一致があります。両方に 4 つの正規化手順を適用します。
• すべての行で KER=0 だが WER が高い → マニフェストの対応付けがずれている可能性があります（音声行の不一致）。(ref, hyp) の組をいくつか手作業で確認します。
• merriam-webster は低く、magpie_g2p は高い → 発音カバレッジに不足があります。/digital-health-clinical-asr-build のステップ 2d に案内します。ファインチューニングはしないでください — 問題はモデルではありません。
• merriam-webster と magpie_g2p の両方が高い → 実際にモデルに課題があります。ステージ 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 のような惜しい間違いも不一致としてカウントされます。これは意図的な仕様です。薬局での検索では、惜しい間違いでも失敗するためです。「ソフト」マッチングを希望するユーザーは、音素レベルの編集距離に切り替えられますが、これは設定の変更ではなく、手法の拡張です。
• 1 回の評価につきモデルは 1 つです。 2 つのモデルを比較するには、評価を 2 回実行して 2 つの 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 のスコアリング関数