digital-health-clinical-asr-build

Clinical ASR Flywheel — Stage 2 (ベンチマークを構築する)

⚠ エージェント：回答する前に、この SKILL.md 全体を読んでください。 このステージは対話形式で、各ステップにゲートがあります。具体的には、用語を提案する（Step 2a）前に、専門分野を踏まえた確認質問を1～2個ユーザーに尋ねてください。Step 2cでは、2段階のIPAパイプライン（override → merriam-webster → magpie_g2p）について順を追って説明し、Step 2dでは、全組み合わせで音声を合成する前に、明示的なQAモードの試聴ゲートを設けてください。また、Stage 3で確認する主要指標として KER を挙げてください。これらを省略すると、この手法の意義が損なわれます。

あなたはキュレーションと合成を行うステージです。ユーザーは /digital-health-clinical-asr-setup から来て、NeMo形式の manifest.jsonl と、それが参照する音声ファイルを持ってこのステージを終えます。どちらも /digital-health-clinical-asr-eval ですぐにスコアリングできます。

対話形式で進めてください。これはフライホイールの中で最も親しみやすく、ドメインへの理解が求められるステップです。臨床医（または臨床医と働く人）に、現在どの用語に困っているかを尋ね、その人の実情に沿ってベンチマークを作成します。質問は短く、焦点を絞ってください。追加する内容をユーザーに示してください。長々と説明しないでください。

データが環境外に送信されます — 用語を送信する前にユーザーに開示してください

このステージでは、ユーザーがキュレーションしたコンテンツを2つの外部サービスに送信します。いずれかの呼び出しを実行する前に、このことをユーザーに伝えてください。

サービス	送信される内容	タイミング
Merriam-Webster（dictionaryapi.com APIまたはmerriam-webster.com公開サイト）	シードリストの用語ごとに1件のHTTPリクエスト。URLパスに用語が含まれます	Step 2c — 以下のMWパスの箇条書きを参照してください
NVIDIA NVCF Magpie TTS（grpc.nvcf.nvidia.com）	生成される各臨床文（テキストと、該当する場合はIPAを囲むSSMLラッパー）	Step 2dおよび2eのすべての合成呼び出し

どちらのエンドポイントにも、PHIを含まない合成コンテンツを送信してください。ここでいうコンテンツとは、キュレーションする用語リスト、およびその用語リストから/data-designer（または代替テンプレート）が生成する文です。このスキルを通じて、実際の患者記録、実際のASR文字起こし、またはPHIを送信しないでください。 用語リスト自体が機密情報（独自の医薬品コードネーム、未公開の製品名、顧客機密の適応症など）に該当する場合は、続行する前に、組織のデータガバナンスポリシーに照らして外部APIへの送信が許可されることをユーザーに確認してください。

MWへの送信が一切許可されない場合は、以下のPath Cを選択してください（MWをスキップし、パイプラインはカバー範囲が狭くなるものの、長尾の用語についてはMagpie G2Pに進みます）。

目的

臨床専門分野の用語リストをキュレーションし、2段階のIPAパイプラインを使ってMagpie TTSで評価用音声を生成し、臨床拡張フィールド（term、entity_category、ipa_source、voice_id、noise_level、context_type）を付与したNeMo形式のマニフェストを作成します。この出力をStage 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 の依存関係がインストール済み、上流の 6 つのスキルが確認済みです。
• /read-aloud（または /riva-tts）が利用できること。NVCF 経由のホスト型 Magpie がデフォルトです。セルフホスト型 Magpie NIM も使用できますが、前提条件の連鎖に /riva-nim-setup が追加されます。
• /data-designer が利用できること。/data-designer が利用できない場合、最初のサイクルではテンプレートの代替を使用できますが、今後のサイクルで再生成できるよう、該当する行にタグを付けてください。
• ユーザーが所有する作業ディレクトリ。このスキルでは $EVAL_DIR/cycle<N>/ を推奨しますが、必須ではありません。

手順

2a. 専門分野のヒアリング → term_seed.csv

質問は一度に 1 つだけしてください。目的は、教科書を書くことではなく、適切な entity_category を持つ候補用語を 4〜10 個見つけることです。

質問の順序：

1. どの専門分野／ワークフロー向けですか？（腫瘍学の口述入力、ICU の引き継ぎ、精神科の初診、整形外科の術後診察など）
2. どのような ASR の失敗モードを見たことがありますか？ — 薬剤名、複数語の処置名、略語、複合疾患など。
3. 日常的に出てくる用語と、難しい用語はどれですか？ — 日常的によく出てくる用語は健全性確認のベースラインに、日常的に使われる難しい用語はシグナルになります。

entity_category を添えて候補用語を 4〜10 個提示します。書き込む前にユーザーに確認してください。その後、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

ユーザーが新しいカテゴリを提案した場合は、受け入れず、6 つのカテゴリのいずれかに対応するか、方法論に意図的な拡張が必要であることを伝えてください（これは今後のサイクルで行うことであり、その場しのぎで追加するものではありません）。

2b. /data-designer による文の生成

次の内容で /data-designer に依頼します。

term_seed.csv の各行について、行の entity_category に合う形で term を含む自然な英語の文を 1 つ以上生成してください。出力スキーマ：{term, entity_category, sentence, context_type}。各用語につき context_type のバリエーションを 3〜5 個生成してください。初期の context_type の語彙：dictation、handoff、chart_note、history。文の長さは 10〜30 語とします。

このステップの出力は、用語ごとの文のバリエーションをまとめたファイルです。ファイル名は任意です。サイクルのディレクトリ内で一貫して使用できる名前を選んでください。

テンプレートによる代替。 /data-designer が利用できない場合は、4 つのテンプレート（context_type ごとに 1 つ）を使用し、term を機械的に置き換えてください。マニフェスト内の該当する行にタグを付けてください（context_type は設定し、文はやや不自然なままにします）。これにより、今後のサイクルで再生成できます。

2c. 2段階のIPAタグ付け（品質を左右する重要な要素）

すべての用語は、次の3段階のパイプラインを順に通ります。

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）が付いています。ステージ3のリーダーボードにおける merriam-webster 行と magpie_g2p 行の差が、発音戦略が機能している証拠です。リーダーボードを作成する際は、これを明示してください。

MW検索方法は3つ — いずれも 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 は読み込みません）。MWをスキップするには None を渡します。

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 モードでの合成（このゲートを省略しないでください）

完全な直積を実行する前に、各用語につき 1 つの音声を合成します。最初の音声、ノイズなし、デフォルトのコンテキストを使用してください。各クリップをユーザーと一緒に試聴します。

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 に、True／False をフェイルクローズで返す最小限の NVCF gRPC 合成呼び出しである magpie_validates_ipa(ipa, api_key, voice_id) のレシピがあります。

ユーザーに候補を提示する前に、候補 IPA ごとに 1 回呼び出してください。ユーザーの承認後、検証済み IPA を pronunciation_overrides.csv に追加します。次回のマニフェスト生成時に、その行の ipa_source は magpie_g2p から override に切り替わります。

Step 2e の前に必要な HITL 試聴ゲート — フェイルクローズ。 次のいずれかが会話内で明示的に行われるまで、完全な直積を合成したり、ステージング済みの IPA 候補を pronunciation_overrides.csv に昇格させたり、Stage 3 に進んだりしてはいけません。

1. ユーザーが QA クリップを試聴したことを確認し、クリップごと、またはカテゴリごとに評価を報告すること（例：「MW セットは問題ないようです」、「pembrolizumab を修正してください」など）。ユーザーが再生できるように、afplay（macOS）または paplay／aplay（Linux）のコマンドを提示してください。その後、ユーザーが試聴して返信するまで停止して待ちます。「すべて昇格」や「確定」をクリックするだけの AskUserQuestion プロンプトによる書面上の承認は、試聴なしではこのゲートを満たしません。Magpie で IPA を検証すれば音素インベントリに含まれることは証明できますが、意図した発音に一致することは証明できません。それを確かめられるのはユーザーの耳だけです。
2. ユーザーが今回のサイクルでは試聴を省略すると明示的に選択すること。その場の単なるクリック操作ではなく、意図を明確に述べる必要があります（例：「試聴を省略し、誤発音によって Stage 3 の KER シグナルが薄まるリスクを受け入れます。cycle-N の注意事項として記録してください」）。試聴を延期したことが後の担当者にもわかるように、サイクル単位のメモ（例：eval/cycle<N>/cycle_notes.md）に省略の旨を記録してください。

Magpie NVCF は 100 行を超えるジョブでレート制限を厳しく適用し、やり直しには API クレジットと時間の両方がかかります。しかし、より大きなリスクは、誤った発音の参照音声を含むマニフェストをリリースし、Stage 3 の KER シグナルを気付かれないまま損なうことです。試聴にかける時間は、サイクルを再実行するよりも安く済みます。

2e. ベンチマーク全体の生成

発音が確定したら、|terms| × |voices| × |noise_levels| × |context_types| の完全な直積を生成します。デフォルトは、Magpie en-US 音声 2～4 種（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 による失敗が発生するレート制限を設けています。失敗した行を再実行してください。

Stage 2 の完了チェックリスト

5 つのサブステップをすべて実行するまで、Stage 2 が完了したと見なさないでください。エージェントは 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 音声を試聴し、ユーザーの明示的な承認を得て IPA オーバーライドを確定
• 2e — 直積の各行に対応する音声を含む manifest.jsonl
• 引き継ぎ — 次のスキルとして /digital-health-clinical-asr-eval を指定し、主要指標として KER を明記

書き込み先は、ユーザーが選択した $EVAL_DIR/cycle<N>/ のみにしてください。それ以外の場所への書き込み、環境の変更、パッケージのインストールは行わないでください。これらは /digital-health-clinical-asr-setup の担当です。

例

シナリオ A — 腫瘍学ベンチマークを新規作成する。 ユーザー：「抗がん剤の名前が誤って書き起こされています。何から始めればよいですか？」→ Step 2a：専門分野が腫瘍学であることを確認し、対象となる薬剤（免疫療法の生物学的製剤、白金製剤、タキサン系薬剤）について尋ねます。候補を約 10 件提案します：cisplatin、paclitaxel、pembrolizumab、nivolumab、carboplatin、docetaxel、bevacizumab、trastuzumab、cetuximab、pemetrexed。すべて entity_category=drug として term_seed.csv に書き込みます。Step 2b：/data-designer に各用語につき 4 種類の文のバリエーションを依頼し、合計 40 文を生成します。Step 2c：各用語を MW で検索します。pembrolizumab のような生物学的製剤は magpie_g2p にフォールバックする可能性が高く、白金製剤は MW で見つかる可能性が高いです。Step 2d：用語ごとに QA 音声を 1 つ合成し、pembrolizumab などの音声クリップをユーザーと一緒に確認し、-mab 接尾辞の強勢パターンを考慮した IPA 候補を提案します。Step 2e：承認後、用語 10 件 × 音声 2 種 × ノイズレベル 2 種 × 文脈 3 種で、120 行を実行します。

シナリオ B — 既存サイクルに追加する。 ユーザー：「cycle-1 のマニフェストがあります。手技をさらに 5 件追加したいです。」→ Step 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 形式（1 行につき JSON オブジェクト 1 個）
• audio/<slug>.wav — 合成された音声クリップ。マニフェストの各行につき 1 つ

トラブルシューティング

• 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 の内部処理ではありません。

制限事項

• デフォルトでは英語のみです。 2 段階の IPA パイプラインは、Magpie の en-US 音素インベントリを基準に検証します。他のロケールでは、別の上流音素セットと上書き CSV 形式が必要です。
• エンティティカテゴリは 6 種類に固定されています。 entity_category の拡張は意図的な方法論の変更であり、場当たり的な調整ではありません。KER の内訳、リーダーボードのセクション、下流のファインチューニングスクリプトは、いずれもこの語彙に依存します。
• 初回サイクルは小規模です。 用語数が約 20 件を下回ると、ipa_source ごとのリーダーボードの区分では、各バケットの行数が少なすぎて統計的に意味のある結果が得られません。1 回分の作業時間がかかっても、意味のあるサイクルを構築してください。
• Magpie NVCF にはレート制限があります。 大規模なジョブでは約 5～10％が失敗するため、再実行の時間を見込んでください。

次のステップ

• 次へ進む： /digital-health-clinical-asr-eval — マニフェストを文字起こしし、WER/CER/KER/SER をスコアリングして、5 セクションのリーダーボードを作成します。
• セットアップに戻る（環境に問題がある場合）：/digital-health-clinical-asr-setup。
• TTS 固有のデバッグに進む： /read-aloud または /riva-tts。

参考資料

• references/manifest-schema.md — NeMo の標準フィールドと臨床向け拡張、実行前のスキーマおよび音声の存在確認、サイクル間の安定性ルール