構造化回答への切り替えと検証
#996では、本文に埋め込んだ引用を segments: [{text, sourceIds}] とサーバー由来の sources に置き換えます。回答とSSEの契約を参照してください。互換モードや二重書き込み期間はありません。
現在のアプリは、すでにこの契約を使用しています。このページは旧DBからの更新手順と、切り替え時の測定結果を残したものです。現在の生成中ストリーミング・描画フレーム単位の表示・評価処理はQ&Aのプロンプトと回答の保存を参照してください。ここに掲載する過去の時間測定は、現在の画面の性能測定ではありません。
既存履歴の移行
リポジトリの npm run db:migrate を使います。内部で node --import tsx により apps/api/scripts/migrate-database.ts を実行するため、移行環境にもNodeと開発依存パッケージが必要です。今回の切り替えで drizzle-kit migrate を直接実行すると、DDL間のデータ変換を実行できません。
- 生成済みの
0024_add_structured_chat_responseでnullableなresponse JSONBを追加します。 - トランザクションでchat_logsを排他ロックし、250件ずつ未変換レコードを読み出して変換します。
scripts/migrations/structured-answerに隔離した旧パーサーで有効な引用を変換し、本文・数式・コード・空白・改行・未知のマーカー・引用元の順番とIDを保持します。API・Webはこの変換処理を読み込みません。 - 生成済みの
0025_retire_plain_chat_answerでresponseを先にNOT NULLへ変更し、その後で旧answer・citations列を削除します。新規DBも同じ手順で、変換対象が0件になります。
セッション単位のadvisory lockで複数の移行処理を直列化します。再実行時は完了済みの処理を省きます。変換失敗時はデータ更新をロールバックし、旧列とレコードを残します。壊れた引用JSONやメタデータは黙って捨てずに移行を止めます。バックアップと照合して該当記録を修正してから再実行してください。履歴削除を前提にしません。空の過去回答も保持し、評価・フィードバック・取得資料・日時・チャットIDも維持します。
変換時の排他ロックだけではDDL間の古い書き込みを防げないため、旧APIと評価workerの停止が必要です。進捗・エラー出力には回答本文や引用先の情報を含めません。
一括デプロイ
メンテナンス時間を設けます。旧版と新版を混在させるローリング更新には対応しません。
- DBをバックアップし、復元手順を確認します。履歴・評価の件数と確認用の履歴IDを記録します。
- 新規チャットを停止し、処理中リクエストの終了を待って旧APIを停止します。評価ジョブの新規配信を止め、実行中ジョブの完了を待って旧workerも停止します。待機中ジョブは残して構いません。ペイロードはチャットIDなので、新workerが新形式を読みます。
- 書き込みを停止したうえで、対象DBに対して
npm ciとSTRUCTURED_ANSWER_WRITERS_STOPPED=1 npm run db:migrateを実行します。成功するまでAPI・workerを停止したままにします。生成された移行の検証はnpm run db:checkとnpm run db:verifyで行えます。 - レコード件数の一致、responseの非null、旧列の削除、代表履歴の引用ID・移動先を確認します。私的な本文はデプロイログに出しません。
- 対応するAPI・Web・Python評価workerをまとめて配置します。モデルのstrict構造化出力、通常・共有チャット、履歴の時刻リンク、CSV本文、評価ジョブを確認します。
- 全コンポーネントの切り替えを確認してから評価処理とアクセスを再開します。
変換失敗時は停止を維持して修正・再実行します。旧列削除後に旧バイナリだけを戻すことはできません。戻す場合は切り替え前のDBと対応する旧コンポーネントを復元し、切り替え後の書き込みも考慮してください。
旧answer列がある既存DBでは、この明示指定なしに切り替えを実行できません。新規DB・移行済みDBには不要です。CDでは手順2の停止を終えてから、production-app 環境の変数 STRUCTURED_ANSWER_WRITERS_STOPPED を 1 にし、完了後に削除します。ワークフローは移行→API→Web→評価workerの依存順で配置するため、移行が止まれば新しいアプリも配置されません。この変数自体がサービスを停止するわけではありません。
比較方法
回転行列とPythonの2つの字幕・講座情報を固定し、同じモデル・エンドポイントで日本語と英語の8問を各3回実行します。講座未選択、メタ情報、単一・複数根拠、TeX、コードブロックを含みます。検索順位の品質はこの比較の対象外です。
STRUCTURED_ANSWER_LIVE=1 STRUCTURED_ANSWER_BROWSER=1 STRUCTURED_ANSWER_REPORT=/tmp/videoq-answer-structured.json npm run test:unit --workspace @videoq/api -- test/structured-answer.live.test.ts
実APIを呼ぶ有料の任意テストです。API設定は環境変数または .dev.vars から読み、認証情報はレポートへ出しません。Chromiumの導入が必要です。調査時は STRUCTURED_ANSWER_CASE で1問に絞れます。通常CIでは実行しません。
比較前の合格基準は、リクエスト・構造化失敗0件、教材との事実一致、引用漏れ・誤引用なし、数式・コード・段落連結の破損なしです。講座あり/なし別に、本文の表示開始と描画完了の中央値を「旧版×1.25+250ms」以内とします。各試行の時間・LLM呼び出し・修復回数・入出力トークン・引用IDを記録し、IDの妥当性と主張の裏付けは別に評価します。
ブラウザー測定は実際のAPIクライアント・フック・文字送り・本文コンポーネントを使います。送信から回答本文が現れるまでと、文字送りの完了までを2回のanimation frameで描画を挟んで測定します(約1フレームの分解能)。検索進捗は数えません。ローカルSSEから実モデルの回答を渡し、認証・永続化・本番ブラウザーまでの通信距離は測定に含めません。サーバーの本文開始・応答完了も別に記録します。測定用コードはテストに隔離しており、アプリの互換経路ではありません。
2026-09-28の比較結果
以下は構造化回答への切り替え時点の測定値です。講座回答の生成中ストリーミングと画面の文字送り待ち時間を取り除いた後の性能を示すものではありません。
旧版 d07f0c94 と今回の実装を、同じエンドポイントの gpt-4o-mini で各24回ブラウザー測定しました。個別の回答・計測値・プロバイダー報告の使用量を保存しています。
| 1リクエストの中央値 | 講座あり:旧版 → 新版 | 講座なし:旧版 → 新版 |
|---|---|---|
| 本文の表示開始 | 2,398 → 2,314 ms | 619 → 647 ms |
| 文字送り完了 | 5,556 → 4,057 ms | 2,072 → 1,247 ms |
| サーバーの本文開始 | 2,344 → 2,266 ms | 558 → 594 ms |
| サーバーの応答完了 | 2,345 → 2,266 ms | 899 → 803 ms |
| LLM呼び出し回数 | 2 → 2 | 1 → 1 |
| 入力トークン | 4,112 → 4,265.5 | 894.5 → 1,261.5 |
| 出力トークン | 150 → 130 | 48 → 38 |
両方式とも引用対象の18箇所で期待する根拠を使用し、引用漏れはありませんでした。回答の回転行列・90度の例・Pythonの結果・動画数を固定教材と照合し、裏付けを確認しています。メタ情報と講座未選択には引用が付きません。新版は不正ID・構造化失敗・リクエスト失敗・修復・KaTeXエラーが0件で、コードの3試行すべてでコードブロックを、複数segmentの3試行すべてで段落の改行を保持しました。講座未選択の6試行すべてでモデルの完了前に本文を表示できています。根拠IDの1が存在する場合も、通常本文の a[1] は引用に変わりません。
旧版のコード質問はメタ情報取得→検索→回答で3回、新版は検索→回答で2回でした。全体の呼び出しは45回→42回で、修復は両方式とも0回です。中央値だけでこの差を隠さず記録しています。構造化への変換だけを目的にした追加の呼び出しはありません。
表示開始・描画完了とも事前の許容差を満たしました。描画完了の短縮には、特に講座未選択で回答が短くなった影響が含まれるため、構造化自体が速いとは結論しません。講座未選択の入力トークンは、出力指示・スキーマの追加で約41%増えています。少数の固定教材での比較であり、一般的な引用の意味的正確さを保証する結果ではありません。
初期案では英語segment間の空白や指定されたコードブロックが欠けることがあり、出力指示に具体例を加えて最終版の各3試行で解消を確認しました。記録は最終版の完走した一式です。開発中の試行と、自動リロードで中断した測定は時間に混ぜていません。測定時の自動リロードは無効化しました。