動画の段階的な探索と映像確認
VideoQのReAct型エージェント(Yao et al., 2023)は、質問に必要な根拠に応じてツールを選びます。 VideoSeek(Lin et al., 2026)の段階的な探索を参考に、 既存の講座へのアクセス制御と引用番号の管理に組み込んだ独自の実装です。 出典と応用範囲に、著者の実装と再利用できる引用情報を示しています。 決まった順序はなく、時刻が分かればその区間を直接確認し、字幕で答えられれば画像確認を省きます。
| ツール | 用途 | 1回答の上限 |
|---|---|---|
search_scenes | 意味検索で関連する字幕を探す | 3回 |
overview_video | 動画全体から字幕12区間と、任意で低詳細度の画像16枚を確認する | 2回 |
skim_video | 900秒以内の候補区間から字幕12区間と、任意で低詳細度の画像8枚を確認する | 2回 |
read_video_window | 既知の区間の前後を連続した字幕で読む | 3回 |
inspect_clip | 180秒以内の区間で最大8枚を高詳細度で見て、図・数式・文字を確認する | 2回 |
focus_clip | 16秒以内の短区間を約1秒間隔・高詳細度の画像で最大16枚確認し、短い表示や変化を調べる | 2回 |
用語の説明には通常の意味検索を使います。字幕に手掛かりのない図を探す場合は、
get_course_info で動画を特定し、全体確認から候補区間、必要な画像の詳細確認へ進めます。
十分な根拠が得られた時点で探索を終えます。各ツールは観察結果と元の時刻を返し、
回答の作成と引用は主エージェントが担当します。
見どころの依頼では動画の種類を確かめ、見る価値のある候補を選びます。視覚的な出来事は、 利用可能なら高密度の画像で直前・行動・結果を確認し、異なる候補を比較するよう指示しています。 主体と観戦対象、残り続ける通知を区別し、根拠のある1〜3区間を時刻と推薦理由付きで紹介します。 動画中のすべての見どころを発見できる保証ではありません。
閲覧結果には共通の残り画像数・呼出し回数と、映像の状態 observed(観察あり)、
no_observations(有効な観察なし)、unavailable(利用不可)、skipped(画像未要求)を返します。
ツールの完了だけでは出来事を確認できたとは限りません。全体確認16枚の後には48枚の枠から
32枚が残り、16枚ずつの詳細確認を2回できます。追加の全体・区間確認はこの枠を消費します。
並行実行のために予約した枚数・回数も残予算に反映します。
overview_video と skim_video の字幕探索は、画像機能が無効でも、YouTube動画でも使えます。
include_visuals=false では画像モデルを呼びません。字幕は冒頭だけでなく時間を分散させて選び、
1区間1,000文字まで返します。サンプルの省略・文章の切り詰め・根拠不足を明示します。
全体を網羅した要約ではなく、最後の字幕時刻も動画の長さとは限りません。
Q&Aの read_video_window は、検索で見つけた場面の前後の字幕を取得します。
アップロード動画・YouTube動画の両方で使え、ツール内で追加のAI呼び出しは行いません。
元の字幕時刻を保持し、1回答につき最大3回、指定区間180秒以内、前後それぞれ30秒まで、
1回40区間・12,000文字まで取得します。省略があれば truncated で明示します。
保存済みの最新字幕を読むため、再索引が終わるまでは意味検索の結果と更新時点が異なる場合があります。
新しい文字起こしは元の発話単位の時刻をSRTに保持し、検索用の場面の結合・分割は索引作成時に行います。
既存の結合済み字幕も読めますが、再索引だけでは失われた元の時刻を復元できません。
字幕の抜粋には、60秒以上の広い区間や強い文章反復を示す transcript_quality も付けます。
これは処理量を制限した文章の特徴の確認であり、音声認識の確信度や誤認識の断定ではありません。
正当な反復も削除せず、不確かな語・数を別の根拠で確かめ、短い出来事を長い字幕全体の時刻で
説明しないために使います。
任意の画像確認は、字幕だけでは分からない図・数式・操作画面などに使います。
アップロード動画では画像確認ツールが既定で有効です。全体・候補区間は低詳細度で探し、
inspect_clip は粗いキャッシュを高詳細度で確認します。focus_clip は別の高密度キャッシュを
使い、短い表示や状態の変化を確認します。字幕で十分な根拠が得られれば画像モデルを呼びません。
設定
API・Python worker・Docker・Terraformの既定値で、アップロード動画の画像確認と
キャッシュ準備を有効にしています。Docker Composeの .env の既定値は次のとおりです。
VIDEO_VISUAL_ENABLED=true
LLM_MODEL=openai/gpt-6-luna
docker compose up -d --force-recreate api worker
ホスト上のAPIでは apps/api/.dev.vars に同じ値を設定します。Python workerには
実際の動画処理には ENABLE_HEAVY_PIPELINE=1 が必要です。
画像確認と回答生成はAPIの LLM_MODEL・LLM_API_KEY・LLM_BASE_URL(共通のキーと OPENAI_BASE_URL を任意で上書き)を共用します。
ホスト型の構成は OPENROUTER_API_KEY と openai/gpt-6-luna を使います。GPT-6 Lunaへのリクエストでは
reasoning_effort=none を指定します。画像入力と厳密なJSON Schema出力を扱えるモデルが必要です。
通常の回答モデルには引き続きツール呼び出しへの対応が必要です。無効にする場合はAPIとworkerの
両方で VIDEO_VISUAL_ENABLED=false にしてください。以前の設定に明示的な false がある場合は、
変更してプロセスを再起動するまで無効のままです。
新規アップロードでは文字起こし後に、映像を60秒ずつ処理する独立したジョブをまとめて登録します。
並列数はSQSイベントソースの上限(本番は最大10)で制御します。区間ジョブから次の区間ジョブを起動する連鎖を作らず、
AWS Lambdaの再帰ループ検出を有効にしたまま、長い動画も最後まで処理します。区間ごとに画像と完了状態を保存し、
再試行では保存済みの区間を読み直しません。字幕の完成と映像の準備状態は別に表示します。抽出に失敗した場合も字幕は保持し、
終了コードまたは終了シグナルをログに記録します。既存動画は、DBとストレージの設定を用意して
apps/worker から次を実行すると、文字起こし・埋め込み生成なしで画像を準備できます。
python scripts/prepare_visual_frames.py --video-id 42
SQS設定がある場合、このコマンドは区間処理をキューに登録します。SQSがないローカル環境では区間ごとに順次処理します。 粗い画像だけを持つ既存動画にも高密度画像を追加できます。 埋め込みの再索引では画像を準備しません。YouTube取り込みは動画ファイルを保存しないため 映像確認の対象外です。キャッシュがない場合も、AIへ映像未確認であることを伝えます。
制限と引用
- 動画全体から最大240枚、5秒以上の間隔で抽出します。長い動画では
max(5, 動画秒数 / 240)秒の間隔になります。画像は1024×1024以内に縮小し、 選択したフレームの表示時刻をミリ秒単位で保持します。 - 非公開の
media/<file_key>.frames-v1.jsonに保存し、base64を含めて最大16 MiB、 JPEG単体は256 KiBまでです。公開時に動画行をロックし、削除後のキャッシュ復活を防ぎます。 - 高密度画像は各秒に実在するフレームを選び、複製や時刻の付け替えをしません。
ミリ秒単位の表示時刻を保持し、画像を1024×1024以内にします。索引とJPEGを非公開の
media/<file_key>.visual-v2/<run_id>/<chunk_index>.binに60秒分ずつ保存します。 動画は最大10時間・600区間です。各区間は最大60枚・約15 MiBで、動画全体を1つの512 MiBファイルに収める必要はありません。 全区間が完成した後にmedia/<file_key>.focus-v2.jsonを公開します。旧形式も引き続き読み出せます。 focus_clipは16秒以内の半開区間[start_seconds, end_seconds)を最大16枚で確認します。 APIは小さなマニフェストと、対象の最大2区間のヘッダー・索引・必要な画像だけを部分読み出しし、ETagで同じ版を確認します。 全体確認でも選択された画像だけを読み出し、大きな画像JSON全体をAPIへ読み込みません。 高密度キャッシュ全体を読み込みません。画像の残り枠が足りない場合は、密度を黙って下げずに通知します。- 4つの閲覧ツール共通で、1回答の画像確認は最大4回・計48枚です。全体・高密度確認は1回16枚、
区間・粗い画像の詳細確認は各8枚までです。並列呼び出しでもプログラムで上限を守り、画像の読み込みと
モデル呼び出しは順に実行します。
gpt-4o-mini(日付付き版を含む)では入力上限に収めるため、 高精細画像を最大4枚ずつ送ります。選択した画像は省略せず、元の画像番号を維持します。 1回の閲覧で行う分割リクエスト全体で60秒以内とし、Q&A全体の制限時間にも従います。自動リトライしません。 - AIが返す画像番号を、サーバーが実際の動画・フレーム時刻へ対応付けます。
映像由来の引用には
evidence_type: "visual"を保存し、画面には時刻だけを表示します。 時刻をクリックすると、確認したフレームの再生位置へ移動できます。 この任意フィールドがない過去の引用も引き続き使えます。 - 回答の生成中は、進捗欄に実行中のツール名と処理内容を表示します。欄を開くと、各呼び出しの 完了・エラー・中断状況を確認できます。通知に含めるのはツール名・呼び出しID・状態だけで、 ツールの引数・結果・画像は含めません。
- 粗い画像では短い表示を見逃すため、時間方向に細かい根拠が必要なら
focus_clipを使います。 約1 FPSでも、未取得の動作や1秒未満の出来事までは確認できず、元動画の欠落も補いません。 観察結果が空でも「動画に存在しない」とは言えません。高密度キャッシュがない場合は明示し、 粗い画像で高密度に確認したとは扱いません。FFmpegはアップロード・既存動画の準備時に動き、 回答中はキャッシュを使います。字幕検索にヒットがなくても映像探索できますが、映像の埋め込み検索用 インデックスはありません。
画像データはチャット履歴や公開メディア経路に出しません。選択した画像を設定先のAIサービスへ送り、 履歴には観察結果の文章を保存します。動画・アカウントの削除時は、機能を無効に戻した後でも 両方のキャッシュを削除します。削除失敗は既存の再試行処理の対象です。
導入と比較
開発・本番のAPI設定とworkerは画像確認を既定で有効にしています。実装をデプロイすると、
明示的な上書き設定がない限り新規アップロードで使えます。Terraformも worker_visual_enabled=true が既定値です。
APIの LLM_MODEL には、画像入力・ツール呼び出し・厳密なJSON出力に対応したモデルを設定します。DBの変更や新しいクラウドサービスは不要です。
workerのフラグはSSMの秘密JSONではなくLambda環境変数へ設定してください。
現在のSSMローダーは指定された秘密情報のキーのみを受け付けます。
同じアップロード講義・同じ質問を、映像無効/有効で比較します。字幕だけで答えられる質問、 図・数式が必要な質問、短い動作の質問、答えが存在しない質問を用意し、正答と根拠の時刻を 人手で確認します。回答の正しさ、根拠のない断定、引用時刻、待ち時間、API使用量を比較してください。 ツール選択には揺れがあるため、複数回の試行が必要です。
visual_inspection ログには閲覧モード・枚数・モデル呼び出し時間・入力/出力トークン数を記録します。
画像・質問・非公開パスは記録しません。この値は映像確認の追加分で、Q&A全体の費用ではありません。
この実装による精度・費用の改善は未計測で、回答後のAI評価ジョブも追加していません。
画像キャッシュはサービス側の追加ストレージとして扱います。粗い画像の互換キャッシュは最大16 MiB、 高密度画像は1分につき最大60枚・約15 MiBで、動画の長さに応じて増えます。 既存の利用者ストレージ枠は元動画のサイズで計算し、キャッシュ容量は含みません。 全体の保存容量・アップロードの処理時間・AI使用量を監視してください。