VRCT/src-python/docs/details/translation_prompt_history.md

翻訳プロンプトへの履歴注入（Chat/Mic/Speaker）

LLM は直前までの会話文脈を理解して翻訳品質を向上させられます。そのため、システムプロンプトに最近の履歴（Chat/Mic/Speaker）を内包する機能を追加しました。大量のログでトークン消費が増えないよう、YAML 設定で取り込み範囲と上限を管理できます。

アーキテクチャ

履歴管理（Model）

model.py でChat/Mic/Speakerのメッセージ履歴を一元管理：

# 履歴バッファ（最大50件）
self.translation_history: list[dict] = []
self.translation_history_max_items = 50

# 履歴追加（オリジナルメッセージのみ、翻訳結果は保存しない）
model.addTranslationHistory("chat", "こんにちは")
model.addTranslationHistory("mic", "今日はいい天気")  
model.addTranslationHistory("speaker", "Hello!")

# 履歴取得
history = model.getTranslationHistory(max_items=10)

# 履歴クリア
model.clearTranslationHistory()

自動注入（Model → Translator → 各LLMクライアント）

• model.getTranslate() で履歴を取得し、translator.translate(..., context_history=history) に渡す。
• Translator.translate() 側でエンジンごとの分岐直前に setContextHistory() を呼び、履歴をプロンプト組み立てに反映する。

# model.getTranslate()
history = self.getTranslationHistory()
translation = self.translator.translate(
  translator_name=translator_name,
  weight_type=config.CTRANSLATE2_WEIGHT_TYPE,
  source_language=source_language,
  target_language=target_language,
  target_country=target_country,
  message=message,
  context_history=history,
)

# Translator.translate() の一例（OpenAI）
case "OpenAI_API":
  if self.openai_client is None:
    result = False
  else:
    if context_history:
      self.openai_client.setContextHistory(context_history)
    result = self.openai_client.translate(message, input_lang=source_language, output_lang=target_language)

メッセージ処理（Controller）

controller.py で各メッセージ処理完了後に履歴へ追加（翻訳の成否に関係なく、オリジナル文だけ保存）：

• Chat: chatMessage() の末尾で model.addTranslationHistory("chat", ...)
• Mic: micMessage() の末尾で model.addTranslationHistory("mic", ...)
• Speaker: speakerMessage() の末尾で model.addTranslationHistory("speaker", ...)

設定ファイル（例: OpenAI）

src-python/models/translation/translation_settings/prompt/translation_openai.yml

system_prompt: |
  You are a helpful translation assistant.
  Supported languages:
  {supported_languages}

  Translate the user provided text from {input_lang} to {output_lang}.
  Return ONLY the translated text. Do not add quotes or extra commentary.
history:
  use_history: true               # 履歴をプロンプトへ注入するか
  sources: [chat, mic, speaker]   # 取り込み対象の履歴種別
  max_messages: 10                # 注入する履歴件数の上限（新しい順）
  max_chars: 4000                 # 履歴整形後の最大文字数（超過時は先頭を切り捨て）
  header_template: |
    Conversation context (recent {max_messages} messages):
    {history}
  item_template: "[{timestamp}][{source}] {text}"

• system_prompt: 従来どおり、{supported_languages}/{input_lang}/{output_lang} が利用可能。
• history.use_history: 履歴注入を有効化します。
• history.sources: 取り込み対象ソース。chat/mic/speaker から選択。
• history.max_messages: 新しい順に N 件を取り込みます。
• history.max_chars: 整形後の履歴文字列の最大長。上限を超えた場合は先頭側を切り捨て（新しい文脈を優先）。
• history.header_template: 履歴ヘッダの整形テンプレート。{max_messages}/{history} が利用可能。
• history.item_template: 各履歴アイテムの整形テンプレート。{timestamp}（HH:MM形式）/{source}/{text} が利用可能。

実装（OpenAI クライアント）

src-python/models/translation/translation_openai.py

• OpenAIClient.setContextHistory(history_items: list[dict]) を追加。
  • history_items は以下のキーを含む辞書の配列：
    • source: "chat" | "mic" | "speaker"
    • text: 文字列
    • timestamp: ISO形式の日時文字列（HH:MM形式にフォーマットされてプロンプトに挿入）
• translate() 呼び出し時、YAML の history 設定に基づき、指定履歴をシステムプロンプト末尾へ整形して注入します。
• 文字数上限は簡易的に max_chars で制御（トークンカウントは行わず、過剰消費抑制用の安全策）。

使い方

基本的な流れ

1. メッセージ発生時に履歴追加（controller.py で自動実行）

# Chat送信時（オリジナルメッセージのみ保存）
model.addTranslationHistory("chat", user_message)

# Mic入力時（音声認識結果のみ保存）
model.addTranslationHistory("mic", transcribed_text)

# Speaker受信時（受信したオリジナルメッセージのみ保存）
model.addTranslationHistory("speaker", received_text)

2. 翻訳時に自動注入（model.py で自動実行）

# getTranslate() 内で自動的に履歴が各LLMクライアントへ注入される
translation = model.getTranslate(translator_name, ...)

3. 設定の調整（YAML編集）

history:
  use_history: true          # 有効/無効
  sources: [chat, mic]       # chatとmicのみ使う場合
  max_messages: 5            # 最新5件のみ
  max_chars: 2000            # 2000文字まで

手動で履歴を操作（必要な場合のみ）

# 履歴をクリア
model.clearTranslationHistory()

# 履歴を取得
recent_history = model.getTranslationHistory(max_items=10)

# 手動で追加
model.addTranslationHistory("chat", "カスタムメッセージ")

連携方法（開発者向け）

既存のcontroller/model統合により、自動で動作します：

1. ユーザーがChat入力 → controller.chatMessage() → メッセージ処理完了後に model.addTranslationHistory() 呼び出し（翻訳の成功/失敗に関係なく）
2. マイク音声 → controller.micMessage() → メッセージ処理完了後に model.addTranslationHistory() 呼び出し（翻訳の成功/失敗に関係なく）
3. スピーカー受信 → controller.speakerMessage() → メッセージ処理完了後に model.addTranslationHistory() 呼び出し（翻訳の成功/失敗に関係なく）
4. 翻訳実行 → model.getTranslate() → LLMクライアントへ履歴を自動注入 → client.translate() で履歴付きプロンプト生成

重要: 履歴にはオリジナルメッセージのみが保存されます。翻訳結果は履歴に含まれません。これによりトークン消費を抑え、文脈として必要な情報のみを提供します。

追加実装は不要です。 YAML設定を変更するだけで履歴注入の有効/無効や範囲を制御できます。

連携方法

対応状況

✅ 全LLMクライアントに展開済み

以下のすべてのクライアントで履歴注入機能が利用可能です：

• OpenAI (translation_openai.py / translation_openai.yml)
• Gemini (translation_gemini.py / translation_gemini.yml)
• Groq (translation_groq.py / translation_groq.yml)
• OpenRouter (translation_openrouter.py / translation_openrouter.yml)
• LMStudio (translation_lmstudio.py / translation_lmstudio.yml)
• Ollama (translation_ollama.py / translation_ollama.yml)
• Plamo (translation_plamo.py / translation_plamo.yml)

各クライアントで同一の設定形式とAPIインターフェースを使用します：

• setContextHistory(history_items: list[dict]) メソッド
• YAML の history セクション

今後の拡張案

• 実トークン見積りに基づく切り詰め（tiktoken 等）
• 要約モデルを使った古い履歴の縮約