文字起こしとシーン検索
質問の前に用意するデータと、質問後に実行する検索を順番に追います。具体的な質問の例から知りたい場合は、AIが回答を作るまでから読んでください。
受講生にどう見えるかは、サンプル講座への質問で確かめられます。AI回答の仕組みと確認方法では、実装の詳細を使わずに、回答と引用先を確認する流れを説明しています。
1. 時刻付きの文章を取得する
Whisperのモデル系列の出典は Radford et al.(ICML 2023)です。実験の説明では、選択したAPIモデルまたはローカルのチェックポイントも記録します。
| 入力元 | 現在の処理 | 進められない場合 |
|---|---|---|
| アップロード動画 | 保存ファイルをHTTPの範囲リクエストで読み取り(ローカル媒体は直接読み取り)、FFmpegでモノラル音声を抽出。選択されたWhisperで文字起こしし、区間をSRTへ変換 | ファイル・音声がない、文字起こしが失敗する、結果が空 |
| YouTube | SearchAPIで手動字幕、次に自動字幕を取得し、SRTへ変換 | SearchAPIの設定がない、利用できる字幕がない |
YouTubeの経路には、字幕がないときに動画をダウンロードして音声認識するフォールバックはありません。アップロードの経路は、WHISPER_BACKEND に応じてOpenRouter経由のWhisper(ホスト型の標準)、直接接続のOpenAI Whisper(旧構成)、ローカルの互換エンドポイントのいずれかを使います。クラウド・NVIDIA 用は300秒、オンプレ CPU 用は30秒に分割し、SQS の最大4レーンで処理します。WHISPER_CHUNK_SECONDS で30〜300秒に調整できます。社内の文字起こしは CPU で whisper.cpp、NVIDIA で vLLM を使い、VAD・音量補正と元動画の時刻への復元を行います。外部の文字起こし API へ自動的に切り替わる処理はありません。各ジョブは保存元の必要な区間だけを抽出し、動画全体に対する時刻付きの結果をDBに保存します。再試行時は保存済みの結果を再利用し、全区間がそろってからSRTを結合します。これらは実装上の設定であり、提供元の最新の利用制限を示す値ではありません。
開発時に ENABLE_HEAVY_PIPELINE を無効にすると、1秒の仮の文字起こしを返します。状態遷移の確認には使えますが、音声認識や検索の精度は確認できません。文字起こしの保存後には、別のジョブで粗い代表画像と約1 FPSの高密度画像も保存します(VIDEO_VISUAL_ENABLED=false で無効)。画像処理の失敗で文字起こしが失われることはありません。画像モデルを呼ぶのはQ&Aで映像確認が必要になった時だけです。映像確認の設定を参照してください。
ファイルのアップロード時には音声の言語を選択でき、初期値にはフロントエンドの表示言語を使用します。選択内容は videos.transcription_language に保存され、分割した音声と再試行のすべてに適用されます。「自動判定」を選んだ場合と既存の動画は、従来どおり言語を自動判定します。この設定は音声認識の対象言語を指定するもので、文字起こしを翻訳する設定ではありません。
2. 字幕を場面にまとめる
SRTの字幕区間には開始時刻・終了時刻・文章があります。WhisperやYouTubeが細かな区間を返した場合、VideoQは動画内の位置を保ちながら、検索用の文章のまとまりにします。
字幕の保存と再生には共通のSRT解析処理を使います。各区間には整数の番号、HH:MM:SS,mmm --> HH:MM:SS,mmm 形式の時刻行、空でない本文が必要です。ミリ秒の区切りにはピリオドも使えます。分・秒は60未満で、終了時刻は開始時刻以降である必要があります。不正な区間は保存時に拒否し、既存字幕の読み取り時にはスキップします。Pythonの索引処理も同じ規則に従い、共通のテストデータで一致を確認しています。空の字幕を保存すると字幕を消去します。
分割には大津法のクラス間分散の基準(Otsu, 1979)を時系列の字幕埋め込みへ応用します。埋め込みの空間で、前後のグループをよく分ける境界を探す方法です。原論文は濃淡画像のしきい値を扱い、字幕への適用はVideoQ側の応用です。長い区間を繰り返し分け、既定の512トークン以内に収めます。区間を結合する前に、間に入る空白も含めた本文のトークン数を確認します。短い区間は途中で話題が変わっても一つの場面に残ることがあります。LLMがすべての話題を判定する処理ではなく、文章の長さに上限を設ける分割処理です。
一つの字幕区間だけで上限を超える場合はトークンを分け、元の時間幅をトークン数の比率で配分します。各断片はSRT読み取り時の空白除去後の本文でも上限内か確認します。このとき途中の時刻は推定値です。二つの区間を分ける境界は一つしかないため、意味による境界選択の埋め込みは三つ以上の区間で必要な場合だけ生成します。埋め込みの契約違反はジョブを失敗させます。それ以外の分割エラーでは元のSRTをそのまま使うため、その経路では512トークン以内になる保証はありません。
3. 検索用データを保存する
元の字幕区間をSRTとして videos.transcript に保存します。索引作成ジョブはその区間を検索用の場面にまとめ、埋め込みに変換して scene_embeddings へ保存します。再生用に保存した字幕は変更しません。埋め込みのリクエストは64件ずつまとめます。各行には文章・ベクトルと、所有者、動画ID・タイトル、場面番号、開始・終了時刻が入ります。
索引の作成時には、その動画の既存ベクトルを置き換えます。APIの検索とworkerの索引作成で、埋め込みモデルと次元を一致させる必要があります。現行DBの列は1536次元です。モデルの設定を変えただけではDBの列や保存済みベクトルは変わりません。埋め込みモデルを変えた場合は、そのモデルで検索する資料の索引を作り直します。
初回処理では、索引作成が終わるとQ&Aが場面を検索できます。更新範囲と確認手順と動画の状態も参照してください。
4. モデルが根拠を要求したら検索する
search_scenes は自然言語の検索文と、任意でアクセス確認済みの講座内動画IDを受け取ります。APIは次の順で処理します。
- 許可された範囲外の動画IDが指定されていれば拒否します。
- 設定された埋め込みプロバイダーで検索文をベクトルにします。
- 所有者と動画IDで範囲を絞り、PGVectorで類似検索します。
- 既定で
RETRIEVER_K = 20、最大20場面の文章・動画タイトルとID・時刻を返します。
例えば「直交するベクトル」という検索文で、質問と同じ単語がなくても「角度が90度」の説明を探せる可能性があります。見つかるかどうかは、文字起こしと埋め込みの内容に依存します。
現在のアプリには、最低類似度による足切りや、別のモデルによる再ランキングはありません。検索結果の数値スコアは、ツールの結果を作るときに取り除きます。「20場面返った」は候補が取得できたという意味で、20場面すべてが質問の根拠になるという意味ではありません。索引にデータがあれば、関連が弱い場面でも0件にならず返ることがあります。
モデルは検索文を変え、1回答につき最大3回まで検索できます。プログラムは動画IDと開始・終了時刻で重複を除き、その回答内で安定した数値のsourceId(1、2など)を付けます。この番号は全動画共通の場面IDでも、回答の信頼度でもありません。
5. 根拠を回答モデルへ渡す
シーン検索の結果には、引用番号・動画タイトル・時刻・字幕の文章が入ります。講座の登録情報は別のツールで取得します。回答モデルは今回のツール実行で得た結果を読み、設定された指示に従って回答を作ります。
モデルは本文と出典IDを持つ segments を返します。APIが対応する引用元情報を付け、生成中から本文と検証済みの引用を配信し、最終検証後に完成した ChatAnswer を保存します。回答とストリームの契約も参照してください。
この経路ではWeb検索を行いません。使えるツールは講座の登録情報と索引済みの場面を取得するものです。長い動画の要約も、取得した場面に制約されます。全場面を自動で巡回して網羅性を確認する処理はありません。
編集・再索引で何が変わるか
初回は文字起こし → シーン索引作成と進み、完了すると動画が completed になります。
文字起こしの完了時は動画行をロックし、現在の字幕と処理開始時の識別値を比較します。 途中で編集・消去された字幕は、外部サービスが失敗した場合も保持し、検索の更新は その編集で登録済みの再索引ジョブに任せます。この場合は文字起こしを完了扱いとし、 索引ジョブを追加しません。削除済みの動画や完了済みの処理は復活させず、 索引への引き継ぎ待ちであれば安全に引き継ぎを再開します。
| 操作 | 更新するデータ | 完了の確認先 |
|---|---|---|
| 初回のアップロード/YouTube取り込み | 字幕を取得し、場面に分割して検索索引を作成 | 動画が completed になったことを確認 |
| 編集した文字起こしの保存 | SRTの保存と reindex_video_transcript の登録を同じDBトランザクションで実施。workerがその動画の場面・ベクトルを置換し、字幕が空ならベクトルを削除 | 字幕の保存を確認し、再索引の完了をworkerログで別途確認 |
| 管理画面から検索用の埋め込みを再索引 | reindex_all_videos_embeddings が、保存字幕が空でない完了済み動画の検索索引を再作成。保存字幕は変更しない | 登録したジョブIDのworkerログ/job_executions を確認 |
同じ字幕の保存や、タイトル・説明文だけの変更では再索引を登録しません。モデルを変える場合は埋め込み設定も確認してください。
全体再索引は、新しい埋め込みの生成後に、動画ごとのトランザクションで索引を置き換えます。 失敗した動画は従来の検索データを保持し、残りの動画を処理したうえでジョブを失敗扱いにして再試行します。 置き換え済みの索引も利用でき、開始時に索引全体を削除する処理はありません。
書き込み前に動画のDB行をロックして最新状態を確認します。削除済みの動画はスキップし、 タイトルは最新値を使い、生成中に字幕が変更されていた場合は再試行します。 APIの編集・削除も同じ行ロックを使うため、古い生成結果による索引の復活やメタデータの巻き戻りを防ぎます。
誤字幕を直してQ&Aで確認する
- 所有する動画の詳細を開き、文字起こし欄の編集でSRTの番号・時刻を保ちながら用語を直し、保存します。
- 字幕を開き直し、修正内容が保存されたことを確認します。元からある
completed表示は、今回の再索引の完了を示しません。 docker compose logs --since=10m workerでreindex_video_transcript・動画ID・ジョブIDを保存時刻と照合し、Successfully reindexed transcript for video …を確認します。運用者は同じジョブのjob_executions.status = 'completed'も確認できます。outboxの完了は配送成功を示すだけです。- 同じ講座で対象を含む新しい質問を送り、引用先の時刻・修正済み字幕を回答と照合します。以前の回答や保存済みチャット履歴は再生成されません。
実装はupdateVideo、字幕の再索引、全体再索引を参照してください。
待機中の文字起こし・索引ジョブが動画の削除後に開始した場合は、外部サービスの呼び出しや 後続ジョブの登録をせずに処理済みとします。索引待ちの動画が残っていて字幕が不正・未設定の場合は 索引処理を失敗として扱い、DBや外部サービスの障害も引き続き再試行します。
回答の問題をどの段階で調べるか
| 症状 | 最初に見るもの |
|---|---|
| スライドの数式に触れない | 音声や字幕で数式が説明されているか |
| 人名や専門用語が違う | 回答用プロンプトを変える前に、保存された文字起こし |
| 引用の再生時刻がずれる | 元字幕の時刻、長い字幕区間を比率で分割していないか |
| 別の授業の話になる | 講座の動画構成、モデルが指定した動画ID、検索文 |
| 検索した文章の関連が弱い | 字幕に必要な説明があるか、埋め込みが一致しているか。現行処理には最低スコアでの除外がない |
実装の参照先
| ファイル | 役割 |
|---|---|
| transcription.py | 音声・字幕の取得と開発用の仮データ |
| scene_otsu/ | 分割、トークン数の計算、元SRTへのフォールバック |
| vector_index.py | 場面の埋め込みとメタデータの保存 |
| vector-repository.ts | 検索範囲と取得件数 |
| rag.ts | ツール実行、場面の重複除去、引用番号 |
次に読む: Q&Aのプロンプトと回答の保存。