Whisper_large-v3文字起こし講座_法人研修ポートフォリオ

法人研修版｜Python × Whisper large-v3 Whisper large-v3 で 音声ファイルを文字にする ボタンひとつの文字起こしツールを、仕様駆動で作る 全8段階スロープ設計／約1時間 45分 Google Colab・Google Cloud・Azure 設定つき／公式ドキュメント参考 うさうさ研修工房

OV E RVI E W この講座の Why / What / How WHY なぜ学ぶか WHAT 何を作るか HOW どう進めるか 1. 録音の文字起こしは、手作業だと時 間がかかる 1. Colab で動く Whisper large-v3 ノート ブック 1. 8段階スロープで、少しずつ難しくす る 2. 外部サービスに音声を出せない現場 も多い 2. ボタン式の Web ツール（Python＋ HTML/CSS/JS） 2. テスト先行：受入基準 → 実装 3. AIに任せるには、仕様を先に決める 力が要る 3. CLAUDE.md と spec.md（仕様駆動の成 果物） 3. Google / Azure の設定は手順書どおり に進める 対象：Python の基本（変数・関数）が分かる方／前提：Google アカウント、（任意）Azure サブスクリプション Whisper large-v3で音声を文字にする｜法人研修版 2

WHY 現場の「あるある」：録音はあるのに、文字がない 1 2 3 議事録に追われる 録音が溜まっていく 音声を外に出せない 会議の録音を聞き直して書き起こす と、会議の何倍も時間がかかる 研修・商談・問い合わせの録音が、 検索できないまま眠っている 社外サービスへのアップロードは、 規程で止められることがある 今日の答え：音声を文字にする部分は Whisper に任せ、人は「何を作るか（仕様）」と「確認」に集中する Whisper large-v3で音声を文字にする｜法人研修版 3

WHAT Whisper large-v3 とは 約15億 500万時間 10〜20% 128 パラメータ数 （1550M・多言語専用） 学習データ量 （弱ラベル100万＋疑似ラベ ル400万） large-v2 に比べた エラー減（モデルカード記 載） 入力のメル周波数ビン数 （v2は80）＋広東語トーク ン追加 1. 音声認識（同じ言語で文字化）と、他言語から英語への翻訳ができます 2. 本講座は faster-whisper（CTranslate2版）を使います。元の実装より最大4倍高速・省メモリと READMEに記載 3. 初回はモデル（約3GB）をダウンロードします。GPU は CUDA 12 と cuDNN 9 が前提で、なければ CPU（int8）で動かせます 出典：Hugging Face openai/whisper-large-v3 モデルカード／SYSTRAN/faster-whisper README Whisper large-v3で音声を文字にする｜法人研修版 4

C OMP ARE 3つのエンジンを比べる：まず「データの行き先」 観点 Whisper large-v3（local） Azure OpenAI Whisper Google Speech-to-Text 音声データ 自分の環境の中で完結 Azure に送信 Google に送信 上限 実質なし（メモリ次第） ファイル25MB 同期：約1分・10MB 準備 GPU（CUDA12＋cuDNN9）推奨 リソース作成＋デプロイ API有効化＋APIキー 認証 不要 キー（本番はEntra ID推奨） キー（本番はIAM推奨） 向く場面 機密音声・長時間 社内にAzure基盤がある 短い音声・Google環境 出典：Azure OpenAI Whisper クイックスタート／Cloud Speech-to-Text クォータと制限（いずれも変更されうるため、収録前に最新を確認） Whisper large-v3で音声を文字にする｜法人研修版 5

ROADM AP 今日のゴールと8段階の流れ 難易度は少しずつ上がり、STEP7の「山場」でピークに達したあと、STEP8で振り返って着地します STEP7 9 STEP6 STEP5 STEP4 STEP3 STEP2 3 4 7 6 5 STEP8 3 STEP1 1 難易度（1〜9） Whisper large-v3で音声を文字にする｜法人研修版 6

STEP 1 / 8 全体像と完成イメージをつかむ 助走ゾーンA 所要 0:00–0:08 難易度 1 ねらい：「ファイルを選ぶ→ボタン→テキスト」の完成形を見て、今日作るものを自分ごとにする。 1 完成版ツールのデモを見て、音声ファイルが文字になるまでの流れを確認します 2 自分の職場で文字起こしが必要な場面（会議・研修・問い合わせ録音）を1つ書き出します 3 今日の成果物（Colabノートブック／Webツール／CLAUDE.md＋spec.md）を確認します Whisper large-v3で音声を文字にする｜法人研修版 7

STEP 2 / 8 Whisper large-v3 と3つのエンジンを知る 助走ゾーンB 所要 0:08–0:18 難易度 3 ねらい： local / Azure / Google の違いを、自分の言葉で一言で説明できる。 1 Whisper large-v3 の特徴（多言語・約15億パラメータ・オープンな重み）を確認します 2 比較表で、音声データの行き先・ファイル上限・準備の手間の違いを読み取ります 3 「この音声は社外に出してよいか」を判断基準に、エンジンを選びます Whisper large-v3で音声を文字にする｜法人研修版 8

STEP 3 / 8 Colab で large-v3 を動かす 上り坂A 所要 0:18–0:33 難易度 4 ねらい：環境構築で迷わず、まず1本、自分の音声を文字にする。 1 ランタイムを T4 GPU に変更し、ノートブックの Step1〜3 を実行します 2 サンプル音声をアップロードして文字起こしを実行し、時刻付きの結果を表示します 3 segments がジェネレータである点を確認し、結果を .txt で保存します Whisper large-v3で音声を文字にする｜法人研修版 9

STEP 4 / 8 仕様駆動：CLAUDE.md と spec.md を書く 上り坂B 所要 0:33–0:48 難易度 5 ねらい：コードを書く前に、AIと人が同じ「正」を見られる状態をつくる。 1 CLAUDE.md を6見出し（概要・進め方・コマンド・規約・NEVER・制約）で書きます 2 spec.md に要件ID（FR / SEC / NFR）を付けて要件を書きます 3 受入基準を Given / When / Then で3本書き、どの要件のものか ID を添えます Whisper large-v3で音声を文字にする｜法人研修版 10

STEP 5 / 8 テスト先行でバックエンドを作る 上り坂C 所要 0:48–1:03 難易度 6 ねらい：受入基準がそのままテストになり、全部通るまで実装する体験をする。 1 受入基準から pytest を先に書き、失敗（Red）することを確認します 2 FastAPI の /api/transcribe を実装して、全テストを通します（Green） 3 拡張子・サイズ・engine 値の検証と、一時ファイルの削除を確認します Whisper large-v3で音声を文字にする｜法人研修版 11

MOC K ｜S T E P5 補足 モックで動かす：本物なしで、自分のコードを確かめる 本物で動かすと困ること 本物 自分のコード 1 2 モデルが約3GBで、取得も実行も重い GPU や APIキー・課金が必要になる モデル3GB・API・課金 重い／遅い／失敗を作れない transcribe.py （本物のまま動く） 偽物＝モック 3 4 結果が環境で変わり、正解を固定しにくい 失敗（上限超えなど）を起こせない その場で終わる・無料 失敗も自在に起こせる 差し替える場所＝外部との境目 原則：偽物にするのは「外部との境目」だけ。自分のコードは本物のまま動かす Whisper large-v3で音声を文字にする｜法人研修版 12

MOC K ｜S T E P5 補足 モック7つの技法：道具と、確かめられること 技法 道具・書き方 確かめられること 1. 辞書の関数を差し替える monkeypatch.setitem APIの流れだけを確認 2. 環境変数を差し替える setenv / delenv 未設定エラー・キーが漏れないか 3. 外部通信を偽物にして引数を記録 setattr（httpx.post など） キーを正しい場所で渡したか 4. 重い部品を丸ごと偽物にする sys.modules に登録 モデルなしで本体を最後まで 5. 失敗を偽物で起こす 例外を投げる偽物 失敗でも一時ファイルが残らないか 6. ダミー入力を作る tmp_path / ffmpeg の lavfi 空・長すぎ・拡張子違いの扱い 7. サーバなしでHTTPをテスト FastAPI の TestClient 検証と応答コード 限界：確かめられるのは「呼び方と後処理」まで。本物の品質は、本物で別に確認する Whisper large-v3で音声を文字にする｜法人研修版 13

STEP 6 / 8 HTML / CSS / JS でボタンを作る 上り坂D（山場前） 所要 1:03–1:18 難易度 7 ねらい：一人演習で、ブラウザから押せるツールの画面を完成させる。 1 index.html に、ファイル選択・エンジン選択・開始ボタンを置きます 2 app.js で fetch→結果表示を書き、処理中はボタンを無効にします 3 コピーと .txt 保存を付け、エラーは日本語で画面に出します Whisper large-v3で音声を文字にする｜法人研修版 14

STEP 7 / 8 キーを設定して3エンジンを統合する 頂上チャレンジ（山場） 所要 1:18–1:35 難易度 9 ねらい： Google と Azure の設定を終え、同じ音声を3エンジンで動かして比べる。 1 Google の API を有効化し、キーに API 制限を付けて .env に設定します 2 Azure で Whisper をデプロイし、エンドポイント・キー・デプロイ名を .env に設定します 3 同じ音声を3エンジンで実行し、結果・処理時間・上限の違いを比較表に記録します ★チェックポイント ① キーが画面・ログ・Gitに出ていない Whisper large-v3で音声を文字にする｜法人研修版 ② 3エンジンとも結果が返る（または原因を説明できる） 15

STEP 8 / 8 振り返りと職場への持ち帰り 下山・振り返り 所要 1:35–1:45 難易度 3 ねらい：学びを、自社で最初に試す一歩に落とし込む。 1 チェックリスト5項目で、できたことと詰まったところを確認します 2 自社で最初に文字起こしする音声と、使うエンジンを1つ決めます 3 情報システム部門に確認すべきこと（データの行き先・キー管理）を書き出します Whisper large-v3で音声を文字にする｜法人研修版 16

ARC HITEC TURE ツールの構成：ブラウザ → FastAPI → 3つのエンジン local ブラウザ FastAPI（Python） HTML / CSS / JS ファイル選択・ボタン 結果の表示・コピー・保存 入力の検証 （拡張子・サイズ・engine値） 一時ファイル→必ず削除 キーは環境変数だけ faster-whisper large-v3 azure Azure OpenAI Whisper google Speech-to-Text（REST） POST /api/transcribe（file, engine, language） フロントにキーを置かない：ブラウザは音声を送るだけ。外部APIの呼び出しはサーバ側だけが行う Whisper large-v3で音声を文字にする｜法人研修版 17

S PE C - DR IVE N 仕様駆動：spec.md が正、CLAUDE.md が AI への約束 spec.md テスト（Red） 実装（Green） 整理 要件ID＋受入基準 基準をテスト化 全テストを通す 仕様も更新 CLAUDE.md の6見出し 1. 概要 2. 進め方（仕様→テスト→実装） 要件IDとテストをつなぐ（トレーサビリティ） 3. コマンド 1. FR-03：ボタンで文字起こし → test_transcribe_ok 4. コーディング規約 2. SEC-02：拡張子・サイズの検証 → test_reject_* 3. SEC-03：一時ファイル削除 → test_tempfile_removed_* 4. SEC-04：Googleキーはヘッダ → test_google_key_in_header Whisper large-v3で音声を文字にする｜法人研修版 5. 絶対に守ること（NEVER） 6. 既知の制約 18

S E CU RITY 法人研修の必須ルール：APIキーの守り方 1 コードに書かない キーは .env / Colab シークレットだけ。 Git・スライド・スクショに載せない 4 用途ごとに分ける 1アプリ1キー。受講生ごとに別キーが 理想 2 API制限を付ける Googleのキーは「Speech-to-Text APIのみ 」に制限する 5 ローテーション 不要なキーは削除。定期的に新しいキ ーへ入れ替える 3 ヘッダで渡す Google は ?key= ではなく x-goog-api-key ヘッダ（URLに残さない） 6 本番は認証を見直す 公式は、本番ではIAM／Entra IDなどキ ーに頼らない認証を推奨 出典：Google Cloud「APIキー管理のベストプラクティス」／Azure OpenAI クイックスタート Whisper large-v3で音声を文字にする｜法人研修版 19

S E T UP ｜ GO O G L E Google Cloud：Speech-to-Text の APIキーを作る 1 Google Cloud コンソールでプロジェクトを作成し、請求先を紐づけます 2 「APIとサービス」→「ライブラリ」で Cloud Speech-to-Text API を有効にします 3 「認証情報」→「認証情報を作成」→ APIキーを作成します 4 キーの「API の制限」で Cloud Speech-to-Text API のみに絞って保存します 5 キーを .env の GOOGLE_API_KEY（Colab はシークレット）に貼ります 同期認識は約1分・10MBまで。それ以上は Cloud Storage 経由の非同期（本講座では Whisper を使う）。公式は本番でのAPIキー利用を 推奨していません。 出典：Cloud Speech-to-Text 公式ドキュメント（クォータと制限／認証）。画面名称は変わることがあります。 Whisper large-v3で音声を文字にする｜法人研修版 20

S E T UP ｜ A Z URE Azure：OpenAI の Whisper をデプロイする 1 Azure ポータルで Azure OpenAI リソースを作成します（Whisper 提供リージョンを選択） 2 操作する人に Cognitive Services Contributor 以上のロールを付けます 3 Azure AI Foundry で whisper をデプロイし、デプロイ名を決めて控えます 4 ポータルの「キーとエンドポイント」から、KEY 1 とエンドポイントをコピーします 5 .env の AZURE_OPENAI_ENDPOINT / API_KEY / DEPLOYMENT に設定します ファイル上限は25MB。API の model には「モデル名」ではなく「デプロイ名」を渡します（取り違えると失敗します）。 出典：Microsoft Learn「Azure OpenAI Whisper クイックスタート」。Whisper は提供状況・リージョンが変わることがあります。 Whisper large-v3で音声を文字にする｜法人研修版 21

S E T U P ｜ C O L AB Google Colab：GPU とシークレットの設定 1 「ランタイム」→「ランタイムのタイプを変更」で T4 GPU を選びます 2 左の鍵アイコン（シークレット）に、使うキーを名前つきで登録します 3 「ノートブックからのアクセス」をオンにします 4 コードでは userdata.get("名前") で読み込み、キーを直接書きません 5 ノートブックを上から順に実行します（付録A〜Cが Google / Azure / ミニツール） 無料枠ではGPUの割り当てや接続時間に制限があります。セッションが切れるとファイルは消えるため、結果は .txt でダウンロード して保存します。 出典：Google Colab 公式ヘルプ（シークレット機能／ランタイム）。 Whisper large-v3で音声を文字にする｜法人研修版 22

TROUBLES HOOTING つまずき早見表：症状 → 原因 → 対処 症状 よくある原因 対処 cuDNN / cuBLAS のエラー CUDA・cuDNN と ctranslate2 のバージョン不一 致 ctranslate2==4.4.0 に固定して再起動／CPU（int8）で 実行 Google が「長すぎる」で失敗 同期認識の上限（約1分・10MB）を超えた local か Azure を使う（Googleは短い音声のみ） Google が 403 API未有効化、またはキー制限の設定ミス API を有効化し、キーの制限対象を確認する Azure が「デプロイが見つからない 」 model にモデル名を渡している デプロイ名を指定する／エンドポイントの綴りを確 認 最初の実行だけ遅い モデル（約3GB）をダウンロード中 初回のみ。先に読み込みセルだけ実行しておく 出典：SYSTRAN/faster-whisper README（CUDA/cuDNN と ctranslate2 の対応）／各社公式ドキュメント Whisper large-v3で音声を文字にする｜法人研修版 23

S UM MA RY 振り返りチェックリスト エンジン選びを「データの行き先」から説明できた Colab で large-v3 を動かし、結果を .txt で保存できた CLAUDE.md と spec.md を書き、要件IDとテストを対応づけられた ボタンを押して文字になるツールが、自分の環境で動いた APIキーを守るルール（.env・API制限・コミットしない）を実践できた うさうさ研修工房

R E FE R E NC E S 参考にした公式情報 1 Whisper large-v3 モデルカード huggingface.co/openai/whisper-large-v3 2 OpenAI Whisper（GitHub） github.com/openai/whisper 3 faster-whisper（SYSTRAN） github.com/SYSTRAN/faster-whisper 4 Azure OpenAI Whisper クイックスタート learn.microsoft.com/azure/ai-services/openai/whisper-quickstart 5 Cloud Speech-to-Text（クォータ・認証） cloud.google.com/speech-to-text 6 Google Cloud APIキー管理のベストプラクティス docs.cloud.google.com/docs/authentication/api-keys-best-practices 確認状況：上限・仕様は検索結果の抜粋で確認した項目を含みます。Colab・Claude Code（CLAUDE.md）の公式ページは本文を直接確認し ていません。収録前に各公式ページで最新を確認してください。 Whisper large-v3で音声を文字にする｜法人研修版 25