Repository navigation
Admin Tuning
対象読者：管理者 目的：「出来上がりが気に入らない／動かない」を症状から引いて、どの設定をどちらへ動かすかを示す。
設定の場所・意味は 上級設定リファレンス、処理のどこで効くかは 動作原理、JSON書式は 設定ファイルリファレンス。初回構築は 管理者セットアップ。
設定はすべて 設定タブ（歯車）> 上級者向け設定（接続系は「接続設定」）にあります。本ページは設定を設定画面の表示名で示します。変更後は短い動画で1本流して効果を確認してください。
| 何に困っているか | 節 |
|---|---|
| 接続できない・実行が失敗する | 接続・実行のトラブル |
| 失敗の原因を調べる・報告する | 失敗時の調査と報告 |
| 字幕が細切れ／1枚が長すぎる | 品質：分割・結合 |
| 1行がはみ出す・読む速さ | 品質：行長とCPS |
| 訳が詰め込みすぎ／情報不足 | 品質：訳の密度 |
| 「要確認」が多すぎる／少なすぎる | 品質：要確認の量 |
| 用語が訳語どおりにならない | 品質：用語 |
| 1本が高い／遅い | コストと速度 |
並び順は実際の流れに合わせています：まず接続して動かす → 動いたら出来上がりの品質を整える。初回構築でつまずいたら、まず下の「接続・実行のトラブル」を見てください。
「接続設定 > 接続テスト」は実行先への疎通確認です。
- リモート：Service URL と Service Auth Token を確認
- ローカル：アプリ内サービスの起動を待つ／再起動
- 設定変更直後は結果が「未確認」に戻ります。もう一度押す
詳しくは 管理者セットアップ Step 3
接続設定の「AI Gateway 接続チェック」は Connection / Chat Text / Embeddings / Chat Vision を個別に確認します。失敗した項目には画面上にも「確認する設定」の案内が出ます。失敗項目ごとの対処：
| 失敗項目 | 確認すること |
|---|---|
| Connection（/models） | OpenAI互換 Base URL（/v1 まで含めるか／LM Studio :1234/v1・Ollama :11434/v1）。接続先サーバーが起動し /models を返せるか |
| Chat Text | モデルIDが正しいか。response_format 等が合わず失敗する場合は API Compatibility Profile（Auto が合わなければ LM Studio / Ollama / User）を見直す。本番で context size exceeded が出るならサーバーの context length を増やす |
| Embeddings | Embeddingモデルが用意されているか。使わないなら未対応でも字幕生成は可能 |
| Chat Vision | 画像入力対応モデルか。PDF Vision抽出を使わないなら未対応でも可 |
API互換プロファイルやモデルプロファイルのJSON書式 → 設定ファイルリファレンス §2・§3 / 仕組み → 動作原理 §8
- ローカル：GPU/Docker/VRAM の問題が多い → ローカルWhisperXセットアップのトラブルシューティング
- リモート：バックエンドのジョブ状態を確認 → AWS バックエンド設定マニュアル
- WhisperXが失敗するとその実行はエラーで終了します（字幕生成タブのログで原因を確認できます）。仕組み → 動作原理 §2
自動翻訳が最終的に失敗したブロックです。手動で訳すか、原因（content_filter / context超過等）を処理ログで確認。仕組み → 動作原理 §5.1
字幕の区切り方の問題です。細切れを減らす主レバーは次の2つです（まず上げてみるのが定石）。
| 設定画面の項目 | 動かすとどうなるか |
|---|---|
| 「長い字幕を分割するしきい値（秒）」 | この秒数を超える字幕を「長すぎ」とみなして分割する。上げると分割されにくくなり、細切れが減って1枚にまとまる。上げすぎると長すぎる字幕が残る |
| 「結合後の字幕の最長表示時間（秒）」 | 結合してできた字幕がこの秒数を超えると違反扱い。上げると長めの結合を許容し、細切れが減る。上げすぎると間延びした字幕が残る |
| 「短い字幕を結合するしきい値（秒）」 | この秒数未満の字幕を「短すぎ」とみなして隣と結合する。上げると結合される範囲が広がり、短い断片が減る。上げすぎると別内容まで結合する |
仕組み → 動作原理 §4.2〜4.4 / 違反コード merged_long・long_segment・short_duration（§5.3）
人が修正して納品した字幕がある場合、機械翻訳との差分を次回の設定改善に再利用できます。本プロジェクトでは、編集内容の分析で「意味単位の分割」が最も多かったため、納品字幕の分割粒度を追加分析しました。
| 納品字幕の分割粒度 | 実測値 |
|---|---|
| cue表示時間の中央値 | 6.6〜7.1秒（講義間で安定） |
| 2秒未満のcue | 1% |
| 分割位置 | 節境界のみ |
この結果から、既存設定よりも分割を急がないしきい値として、次の候補値を検討しました。
| 設定 | 変更前 | 候補値 |
|---|---|---|
| 「長い字幕を分割するしきい値（秒）」 | 10 | 14 |
| 「結合後の字幕の最長表示時間（秒）」 | 7 | 12 |
14秒・12秒は、本プロジェクトの納品字幕から得た検討用の候補値です。現行デフォルトや一般的な推奨値ではありません。実際に調整する場合は、短い動画で比較してから採用してください。
「〜が」「〜の」で切れたブロックを翻訳が補おうとして英文が伸びる場合は、前処理で結合します。
| 設定画面の項目 | 動かすとどうなるか |
|---|---|
| 「未完結な文を次の字幕と結合する」 | ONで前処理が働く（既定ON）。途中で切れたブロックを次と結合してから翻訳する。OFFにすると結合しない |
| 「結合可能な最大隣接gap（秒）」「結合後の最大duration（秒）」「結合後の最大書きおこし文字数」 | 結合してよい条件の上限。いずれも大きくするほど結合しやすくなり、途中で切れた字幕がつながりやすい。大きくしすぎると間隔の空いた・長い字幕まで結合する |
仕組み → 動作原理 §4.3
| 設定画面の項目 | 動かすとどうなるか |
|---|---|
| 「1行の最大文字数」 | 1行の長さの上限。下げると1行を短く折り返す（はみ出しが減る）。下げすぎると折り返しが増えて行数が膨らむ |
| 「最大行数」（既定2） | 1枚の字幕の最大行数。増やすと長い訳を複数行に収めやすくなるが画面占有が増える。減らすと省スペースだが1行に詰まりやすい |
違反コード line_length_only（§5.3）
| 設定画面の項目 | 動かすとどうなるか |
|---|---|
| 「最大CPS（文字/秒）」（既定16.9） | 読む速さの上限。下げるほど厳しくなり、速い字幕を違反として短縮・時間再配分の対象にする（読みやすくなるが処理が増える）。上げると速い字幕を許容する |
| 「低速発話と判定するCPS（下限）」（既定3.0） | このCPS未満を「間延び（遅すぎ）」と判定する。上げると間延び判定が増え、下げると減る |
| 「字幕最短表示時間（秒）」（既定0.833） | 字幕1枚の最小表示時間。上げると各字幕が最低でもこの秒数は表示され、短く詰める余地が減る。下げるとより短い表示を許容する |
違反コード verbose_en・slow_speech（§5.3）。CPSの考え方 → 動作原理 §5.2〜5.5
| 設定画面の項目 | 動かすとどうなるか |
|---|---|
| 「過圧縮と判定する英日文字比（下限）」（既定0.25） | 訳が原文に比べこの比率より短いと「詰め込みすぎ」候補（over_compressed）。上げると詰め込みすぎとみなす範囲が広がり、展開（情報を補う）対象が増える。下げると判定が厳しくなり減る |
| 「過圧縮判定の最小日本語文字数」（既定15） | 元の日本語がこの文字数を超えるときだけ詰め込みすぎ判定を行う。下げると短い字幕も判定対象になり、上げると長い字幕だけが対象になる |
| 「冗長と判定する英日文字比（上限）」（既定1.5） | 訳が原文に比べこの比率より長いと「冗長」（verbose_en）。下げると冗長とみなす範囲が広がり、短縮対象が増える。上げると緩くなり減る |
| 「圧縮リトライ上限（1ブロックあたり）」「展開リトライ上限（1ブロックあたり）」 | 基準に収めるための短縮・展開の試行回数の上限。上げると基準を満たせる確率が上がるが、AI呼び出しが増えてコスト・時間が増える |
仕組み → 動作原理 §5.4
要確認は「自動補正後も残った形式違反（行長・CPS・表示時間）や翻訳失敗」に付きます。多すぎる＝品質基準がその動画に対して厳しすぎるか、自動修復が足りていない可能性。
| 設定画面の項目 | 動かす向き | 効果 |
|---|---|---|
| 「カバレッジ修復エージェント」有効化 | ON | 取りこぼしをAIで自動修復（コスト増） |
| 「汎用修復エージェント」有効化 | ON | 残った違反を段階的に修復。OFFだと残違反は即「要確認」 |
要確認は意味の良し悪しでは付きません（仕様）。内容面のレビューは翻訳者が全ブロックを確認する前提です。形式違反すら出ないのは健全な状態です。
| 対処 | 場所 |
|---|---|
| 共有辞書に日英ペアを登録し確定する | 辞書タブ「専門用語 > 共有辞書」（UI §5-1） |
| PDFから用語候補を抽出して有効化 | 辞書タブ「用語集作成」 |
| 訳語の方向性を指示する | 「翻訳 追加指示」（書式 → 設定ファイル §5） |
確定済みの日英ペアが翻訳プロンプトに用語集として注入されます。仕組み → 動作原理 §3 / §5.1
LLM呼び出しの量とモデル格で決まります。まず字幕生成タブの処理ログで、どのノードが時間・回数を食っているかを見てから調整します。
| 設定画面の項目 | 動かす向き | 効果と副作用 |
|---|---|---|
| 「カバレッジ修復エージェント」「汎用修復エージェント」有効化 | OFF | 修復のAI呼び出しを止める（コスト大幅減／残違反は要確認へ） |
| 各 reasoning effort / エスカレーション上限 | 下げる | 1回あたりの推論を浅く（速く・安く／品質低下の可能性） |
| 各モデル設定 | 軽量モデル（nano級）へ | 機械的な変換ノードを格下げしてコスト減（品質は要確認） |
| 「並列リクエスト数」 | 下げる | レート制限エラーの回避（遅くなる）／上げると速いが429が出やすい |
仕組み → 動作原理 §5.4〜5.6 / §8
- 字幕生成タブの「現在の実行状態」「処理ログ」で、どのノードがどう失敗したかを確認する。
- 上部ツールバーの 保存（プロジェクトJSON）で現在の状態を書き出す。これには処理ログ・設定スナップショット・各段の中間結果が含まれ、そのまま障害報告に使えます。
- ローカルLLM特有の不具合（context超過・思考タグ混入）は、サーバーの context length 設定と モデルプロファイルJSON を確認。
詳しい画面の見方 → 画面リファレンス §4
- 設定項目の意味（辞書） → 上級設定リファレンス
- 処理の中身 → 動作原理
- JSON・プロンプトの書式 → 設定ファイルリファレンス
- 初回構築 → 管理者セットアップ