Q&Aのプロンプトと回答の保存
プロンプトは、AIへ渡す指示と参照情報です。VideoQでは、利用者の質問だけでなく、アクセスできる講座の情報や字幕を使って回答します。
質問から引用までの具体例は、AIが回答を作るまでを読んでください。このページでは、その入力と制御を詳しく説明します。
回答モデルに何を渡すか
| 段階 | モデルへ渡すもの |
|---|---|
| 通常Q&Aの開始時 | システムの指示、保存済みの会話要約・直近の発言と最新の質問 |
| ツールの定義 | 各ツールの機能、引数の形式、どの場面で使うかという指示 |
| ツール実行後 | 会話に残るツール呼び出し履歴と、講座の登録情報または番号付きの字幕 |
| 最終回答 | モデルが会話に残る根拠と新しく取得した根拠を使って文章を生成 |
プロンプトは prompts.json から言語に対応する指示を選びます。各言語は完全な設定を持ち、その構造をTypeScriptで検証します。完全なロケール名、基本言語、既定値の順で選び、リクエストごとの設定マージは行いません。
講座情報には名前・説明・動画数と、1ページ分の動画ID・タイトル・状態などが含まれます。ツールは共有トークン・所有者ID・ファイルURLを明示的に除外します。説明文は講座が2,000文字、動画が500文字で切り詰められる場合があり、切り詰めたことをフラグで示します。未取得のページや省略された文章を、情報が存在しない証拠として扱わないよう指示しています。
過去の発言や要約を追加質問の文脈としてモデルへ渡します。画面の原文は別に保存するため、要約後も表示できます。
クライアントとAPIの契約
Webクライアントは、画面で選択した言語をSSE・tRPCリクエストの Accept-Language に指定します。リクエストごとに言語を読み取るため、日本語と英語を切り替えると回答への言語指示も変わります。ページの再読み込みは不要で、ブラウザーの言語設定には依存しません。
認証済みのチャット、共有リンク、講座未指定のQ&Aでは、ブラウザーは新しい質問1件と会話UUIDを送ります。サーバーは現在のアクセス権を確認し、確定済みのLangGraphチェックポイントから会話を読み込みます。前の回答は文脈として使い、保持されているツール結果は同じ出典IDで根拠として利用できます。不足や情報の更新が必要なときに追加取得します。会話UUIDを送らない以前のクライアントもメッセージ配列を送れますが、サーバー側のスレッド保存は行いません。
「内積とは?」→「具体例を教えて」では、過去の会話から対象を引き継ぎます。前の回答は文脈として扱い、保持されているツール結果または追加の講座検索から根拠を得ます。テストではストリーミング・非ストリーミングの両方でモデル入力を確認します。
Q&Aで情報を選ぶ
Q&Aは、必要に応じてツールで情報を取得し、回答を組み立てます。LangChainの createAgent で実装したReAct型のツールループ(Yao et al., 2023)です。すべての質問で同じ検索を実行するわけではありません。
| 質問の例 | 主に使う情報 |
|---|---|
| 「この講座には動画が何本ある?」 | 登録された講座・動画の情報 |
| 「この授業の内容を要約して」 | 字幕の関連シーン |
| 「この動画の説明文を見せて」 | 登録済みの説明文 |
基本の検索・情報取得ツールは次のとおりです。
get_course_info: 講座名・説明・動画一覧など。1ページ最大20動画、1回答最大5回。search_scenes: 字幕を意味で検索。講座全体または指定した講座内動画を対象にし、1回答最大3回。
さらに read_video_window・overview_video・skim_video を使えます。映像確認が有効なら inspect_clip・focus_clip も利用できます。個別・共通の上限は動画の探索と映像確認、設計の出典はVideoSeekとの関係を参照してください。
ツールを使うモデルターンには MAX_TOOL_ROUNDS = 19 回の上限があり、その後はツールを外して最終回答を生成します。個々のツールはそれより早く上限に達する場合があります。モデルが返した要求をそのまま実行せず、API側でも引数とアクセス範囲を検証します。
講座Q&AのストリーミングAPIは、検索の進捗を即時に通知し、本文と検証済みの引用をモデルの生成中から順次送ります。回答全体の検証後に保存し、done を送ります。ツール呼び出し前の前置きは回答として送りません。クライアントが中断した場合や送信が打ち切られた場合は、実行中のモデル・埋め込みリクエストを中断します。
シーン検索用のDB接続と埋め込みアダプターは、search_scenes が呼ばれたときだけ初期化します。そのため、登録情報だけで答える場合はシーンの埋め込みに依存しません。講座へのアクセス確認・登録情報の取得・回答保存にはDBを使います。
モデル設定と処理の上限
以下はアプリの既定値です。本番環境の設定を測定した値や、提供元の制限値ではありません。
| 項目 | 現在の実装 |
|---|---|
| 回答・画像モデル | LLM_MODEL。ホスト型の構成は openai/gpt-6-luna(同じGPT-6 Lunaモデル) |
| 回答の接続先 | LLM_BASE_URL(未設定なら OPENAI_BASE_URL)のChat Completions。ホスト型の構成は https://openrouter.ai/api/v1 |
| 推論の設定 | gpt-6-luna または openai/gpt-6-luna では none。Chat Completionsでのツール呼び出しに対応するため |
| 生成設定と出力上限 | temperatureは 0。構造化出力を含め、モデル呼び出し1回あたり最大1,024出力トークン |
| リクエストの期限 | 講座RAGは非ストリーミングが2分、ストリーミングが5分 |
| プロバイダーの自動再試行 | APIのチャットモデルでは無効 |
| シーン検索 | 最大3回。1回あたり既定で最大20件 |
| 登録情報の取得 | 最大5回。1ページ最大20動画 |
| ツールを使えるモデルターン | 最大19回。その後はツールなしで最終回答を生成。個々のツールの上限も適用 |
回答生成と画像確認に共通のモデルをAPIの LLM_MODEL で設定します。ツール呼び出しと厳密なJSON出力に加え、映像確認を有効にする場合は画像入力への対応が必要です。APIとworkerで共用する検索モデルの設定は埋め込みを参照してください。
モデルの出典にはGPT-6 Lunaの公式モデル資料、または実際に設定したモデルの資料を引用します。
構造化回答・引用と権限
提供元の機能の出典はOpenAIのStructured Outputs公式発表です。以下の出典管理と引用検証はVideoQ側の実装です。
モデルはネイティブの構造化出力で {"segments":[{"text":"説明です。","sourceIds":[1]}]} を返します。動画の移動先は生成しません。サーバーが会話の出典対応表を現在アクセス可能な動画で絞って sources: [{id, video_id, title, start_time, end_time}] を付けます。この ChatAnswer を非ストリーミング応答・画面の状態・履歴・DBの chat_logs.response(JSONB)で共用します。CSV用の本文はsegmentのtextを区切り文字なしで連結して導出します。必要な空白・改行はtext自身に含め、各segment直後にsourceIds順の時刻リンクを表示します。
Chat Completionsのモデルとエンドポイントには、strictなネイティブjson_schema出力、strictな関数ツール、および両者の同時利用が必要です。講座Q&AはLangChainの providerStrategy を使い、講座未選択も同じJSONスキーマを指定します。ツールの video_ids は省略ではなくnullを許可し、ページ指定も必須です。スキーマ機能の非対応は設定エラーになります。自由文へのフォールバック、構造化だけの追加推論、自動修復・再試行は行いません。拒否・空回答・途中終了・スキーマ違反は失敗とし、ツール呼び出し前の前置きを回答として表示しません。
引用元レジストリはエージェントの会話状態に保存します。正の安全な整数IDを割り当て、追加・重複検索と後続の回答でも維持します。出典メタデータは要約で削除せず、会話の削除・期限切れまで保持するため、検索を続けると増加します。メタ情報だけの回答はsourceIdsを空にします。候補には引用されない場面も含まれ、登録だけではリンクを作りません。モデルにはsourceId・字幕・サーバー由来のメタデータを持つ構造で検索結果を渡します。
未登録ID・正の安全な整数でない数値IDは、本文を変えずに除外します。同一segment内の重複は最初の順番を残して除外し、別segmentでの再引用は維持します。連結した本文で数式・コードの範囲を判定し、その途中のsegment境界にある引用は除外します。閉じていない区切りやsegmentをまたぐ式にも適用します。ログは chat_citations_rejected と理由別件数(invalid_id・unknown_id・duplicate_id・unsafe_position)だけで、本文・引用先の情報を含めません。本文の a[1]・[99]・通常の角括弧から引用を復元する処理はありません。
検索はアクセス許可された講座範囲を強制します。ID検証は会話で登録済みの出典であり、現在その動画へアクセス可能かを調べるもので、主張を意味的に裏付ける保証ではありません。字幕内の命令に従わないようにも指示しますが、プロンプトだけで不正な指示や根拠のない回答を完全には防げません。
ストリームの契約
POST /api/chat/messages/stream は1つの形式だけを提供します。SSEのdataは @videoq/trpc/chat で定義したJSONイベントです。形式選択クエリと旧イベント対応はありません。
| イベント | データと動作 |
|---|---|
source | source: {id, video_id, title, start_time, end_time}。参照前に登録する |
text_delta | segmentIndex: number・text: string。0始まりのsegmentへ本文を追加する |
citation | segmentIndex: number・sourceId: number。そのsegmentの後に1つの時刻リンクを追加する |
searching・search_completed | 本文とは独立した検索進捗 |
done | chat_log_id・feedback。保存完了。描画キューを消化してから評価ボタンを表示する |
error | code・message。回答を終了し、描画待ちの内容を破棄する |
講座の選択有無にかかわらず、生成中から本文を逐次表示します。モデルのストリーミングにはLangChain Coreの標準コンテンツブロックイベントと ChatModelStream を使います。講座未選択のQ&Aは streamEvents().text で本文を受け取り、組み立て済みのメッセージをawaitします。講座Q&Aでは BaseCallbackHandler で同じ標準イベントを受け取り、LangGraphのcustom writerで検索・ツール進捗とともに送ります。本文・ツール引数の組み立て、終了理由、使用量の集約はCoreに任せ、アプリ側で終了通知の重複除去やメッセージチャンクの連結を行いません。重複する stop も stopstop にならず、モデル呼び出しも追加しません。SDKの部分JSONデコーダーで増加したtextだけを取り出し、未完成のエスケープやUnicodeのサロゲートを保留します。JSON構文・ツール引数・通常の検索前置きは回答本文にしません。構造化した回答本文を出した後にツールを呼ぶ異常な応答は、ストリームをエラー終了し、途中の本文を保存しません。完了にはstopによる正常終了と、完全な回答としての検証が必要です。講座未選択には引用元がないため、時刻リンクは作りません。
Chat Completionsの互換処理として残すのは、ツール選択と回答スキーマを分ける必要があるローカルサーバーへの対応、プロバイダーが返す数値のコスト記録、Coreの標準コンバーターが現在省略するrefusalの検出です。HTTP通信とSSE解析はOpenAI SDK、メッセージ変換はLangChainに任せます。回答スキーマ、表示済み本文の不変性、参照可能な出典番号、引用を挿入できる境界の検証はVideoQ固有の契約として維持します。
時刻リンクも回答全体の完成を待たずに送ります。segmentのJSONオブジェクトが実際に閉じ、出典番号が検索済みの引用元に存在し、数式・コードの途中でない境界を確認してから追加します。未確定の区切り文字だけは続きの文字または最終検証を待ち、その間は次のsegmentを短く保留します。既存の「本文→引用→次のsegment」の順序を維持し、引用元の情報は参照する引用より先に送ります。
画面は requestAnimationFrame で待機中の内容をまとめて反映し、新しい本文・引用が届いたときだけ描画を予約します。固定タイマーによる待ち時間や、1文字ずつ表示を遅らせる処理はありません。done は描画待ちの内容を反映してから適用します。配信完了時にタブが非表示なら、一時停止した描画フレームを待たずにキューを反映して完了します。
引用元と本文・引用イベントをdoneより先に送り、画面は直接ChatAnswerへ反映します。通常表示と履歴は同じ描画処理を使います。引用がないsegment境界をまたぐ数式・コードはまとめて表示します。予期しない切断はエラーです。中断時には上流も止め、再送・講座・共有リンク変更時には状態を引き継ぎません。本文を生成する前の失敗は利用枠を返却し、一部本文を生成済みの場合や保存失敗では既存方針どおり消費を維持します。
既存履歴の一度きりの変換とデプロイ手順は構造化回答への切り替えと検証を参照してください。
根拠やサービスが利用できないとき
| 状況 | 現在の挙動 |
|---|---|
| シーン検索が0件 | 一致する場面がないとツールが返す。上限内なら別の検索文を試せる |
| シーン検索を3回実行済み | 追加の検索には上限到達を返す。取得済みの根拠で回答するか、不足を説明するよう指示する |
| 講座外の動画IDを指定 | 検索回数を消費せずに拒否し、利用可能なIDを使うようモデルへ返す |
| 質問の一部しか根拠がない | 裏付けられる範囲だけ答え、その限界を示すよう指示する |
| DBや埋め込みの実行が失敗 | 「根拠がない」とは扱わず例外を伝える。チャットのエラー処理で回答用に予約した利用枠を戻す |
| 回答プロバイダーの失敗・タイムアウト | エラー処理へ進む。チャットモデルのラッパーによる自動再試行は行わない |
| 最終応答の拒否・不正・途中終了・空白、またはツール呼び出しが残っている | エラーとし、上記の利用枠方針を適用する。過去の前置きを回答として代用しない |
現在は最低類似度による除外がないため、関連が弱い検索結果も返ることがあります。シーン検索を参照してください。字幕に必要な説明がない場合や、索引と検索の埋め込みが一致しない場合は、プロンプトの表現だけを変えても解決しません。
回答の保存
完成した質問・構造化回答・取得資料を保存してから done を返します。RAGASによる自動採点と評価API・スコア表示は廃止しました。引用の検証、質問履歴、利用者のフィードバックは継続します。残っている evaluate_chat_log は追加のAI呼び出しをせず終了します。
変更する場所
| 場所 | 役割 |
|---|---|
| prompts/ | 指示文と設定 |
| rag.ts | Q&Aのツール呼び出し・回答生成 |
| rag-course-info.ts | 講座・動画の登録情報 |
| answer-content-stream.ts / chat-citations.ts | 回答の逐次読み取りと引用の検証 |
| message-service.ts | 権限・利用枠・SSEイベント・保存 |
| chatStreamController.ts | ブラウザーの描画キューと完了処理 |
変更後に見ること
日本語・英語で、登録情報だけの質問、授業内容の質問、両方が必要な質問を試します。回答だけでなく、使ったツール、引用先、講座外の情報が混ざらないことを確認します。
LLM_MODEL は回答や生成に使うモデル、EMBEDDING_MODEL は検索用のモデルです。埋め込みは1536次元固定で、API・workerのモデルも揃えます。モデル変更には既存ベクトルの再生成が必要です。設定と制約を参照してください。
実モデルのテスト方法と料金が発生する条件はテストと確認コマンドを参照してください。
LangChain/LangGraphの標準APIとの対応
2026-11-02に、導入済みのJavaScript版 langchain 1.5.19、@langchain/langgraph 1.6.0、@langchain/langgraph-checkpoint-postgres 1.1.2と照合しました。
| 対象 | 使用する公開API |
|---|---|
| 会話状態 | createAgent の組み込みメッセージ状態。初回の未確定状態のリセットに RemoveMessage(REMOVE_ALL_MESSAGES) |
| 永続化 | 回答する createAgent に公式 PostgresSaver を直接渡し、configurable.thread_id で識別 |
| 保存失敗後の再開 | 確定済みの configurable.checkpoint_id を指定。保存済みの状態は書き換えない |
| 保存頻度 | 指定せずLangGraph既定の async。各ステップで非同期に保存する |
| 要約 | 公式 summarizationMiddleware と、公開コールバックで失敗・空の要約を確認する createMiddleware |
| ストリーミング | 回答エージェントの streamMode: "custom" と runtime.writer。公開モデルコールバックで構造化SSEへ変換 |
| 回答ごとの検索 | エージェントがツール呼び出し・結果を会話状態として保持。出典の対応表はミドルウェアの状態拡張で保存 |
参照:チェックポイントと保存頻度、短期記憶、カスタムストリーミング。
表示用の記録と確定済みチェックポイントIDのトランザクション、アクセス確認、同時実行のリースはアプリ側の責務です。要約の開始条件(推定6,000トークン)と会話の30日保存はVideoQの方針であり、ライブラリの標準値ではありません。開始条件を省略すると要約されなくなります。保持件数は既定の20メッセージです。独自のモデル接続先でも使えるよう、モデルのプロファイルを前提としないトークン数指定にしています。
導入済みのJavaScript版PostgresSaverには、スレッド全体を削除する deleteThread はありますが、世代ごとの削減や最新1世代だけを残す公開APIはありません。チェックポイント履歴はそのまま保持します。会話・講座・アカウントの削除や期限切れ時には、アプリが設定した所有関係の外部キーでスレッド全体を削除します。この所有関係はアプリ固有の連携であり、PostgresSaverの標準機能ではありません。世代ごとの独自削除、保存データのバージョンの書き換え、内部の非同期コンテキスト操作は使いません。利用中の会話では履歴が蓄積し、既定の async も件数を制限しません。UIから過去のチェックポイントへ戻る機能は提供しません。
会話の要約プロンプト、要約の接頭辞、要約入力の切り詰めは summarizationMiddleware の既定値を使います。アプリが指定するのはモデルと要約の開始条件です。保持件数は既定の20メッセージで、要約モデルの出力トークン上限は指定しません。導入済みミドルウェアは要約エラーを要約文字列へ変換するため、失敗・空の要約で確定済みの文脈を置き換えないためのコールバックによる検出は残します。
会話用の親グラフ、保存用の会話抽出、ストリームを中継する独自キューはありません。回答の引用・空本文・完了状態の検証と出典の対応表はアプリ固有の契約です。検証は公開 afterAgent フックで実施します。以前の会話形式の messages も読み込めますが、新しい形式ではエージェントの構造化回答とツール履歴をそのまま保存します。
グラフの再帰上限は、既定の25ステップでは既存の検索・閲覧ツールと要約・検証フックを実行しきれないため、アプリのツール上限から算出した値を維持します。回答モデルの出力上限・接続先・期限、アクセス制御・引用検証・30日の保存期間はアプリの要件です。これらをライブラリの既定値とは呼びません。