LMStudio 認証呼び出しで base_url を明示渡しへ修正 + ドキュメント整備（ローカルLLM/言語マッピング/フォント等）

- controller: model.authenticationTranslatorLMStudio 呼び出しに base_url=config.LMSTUDIO_URL を明示的に渡すよう修正（LMStudio 接続判定で設定 URL を利用） - docs: 新規ドキュメントを追加・更新 - 追加: translation_gemini.md, translation_lmstudio.md, translation_ollama.md, translation_openai.md, translation_plamo.md - 更新: config.md, controller.md, mainloop.md, model.md, overlay.md, translation_languages.md, translation_translator.md, 仕様書.md（翻訳/モデル管理・エンドポイント・YAML 言語定義・フォント探索・VRAM フォールバック等の記載追加） - ドキュメントに記載した主な変更点 - LMStudio / Ollama のローカルLLM統合（モデルリスト/選択用プロパティ追加、接続確認エンドポイント） - CTranslate2 の言語定義を weight_type ネスト構造へ変更対応 - 外部 YAML による言語マッピング導入（loadTranslationLanguages） - フォント探索を PyInstaller バンドル(_internal/fonts/) を考慮して強化 - 認証後のモデルリスト自動更新・SELECTED_* プロパティ名統一、VRAM エラー検知時の自動フォールバック等の動作説明追加（コードの振る舞いは既存処理に合わせた引数指定の修正とドキュメント反映が主体）
2025-10-20 01:19:49 +09:00
parent 83e72b37cc
commit bcfbf51696
14 changed files with 943 additions and 24 deletions
--- a/src-python/docs/details/controller.md
+++ b/src-python/docs/details/controller.md
@@ -4,25 +4,77 @@

 VRCTアプリケーションのビジネスロジックを制御するコントローラークラスです。UI層とモデル層の間に位置し、ユーザーの入力を適切な処理に変換し、結果を UI に返す役割を担います。全ての機能制御、設定管理、状態管理を一元的に行います。

+## 最近の更新 (2025-10-20)
+
+### 新規ローカルLLM翻訳エンジン統合
+
+- LMStudio / Ollama への接続確認エンドポイント追加: `/get/data/lmstudio_connection`, `/get/data/ollama_connection`
+- LMStudio URL 設定: `/get|set/data/lmstudio_url`
+- モデルリスト取得と選択: `/get/data/*_model_list`, `/get|set/data/*_model` (lmstudio / ollama / plamo / gemini / openai)
+- 認証・接続成功時に `selectable_*_model_list` / `selected_*_model` を run 経由で通知 (例: `/run/selectable_lmstudio_model_list`, `/run/selected_lmstudio_model`)
+
+### モデルリスト自動更新フロー
+
+- Plamo / Gemini / OpenAI 認証後に動的に最新モデルリストを取得し未選択時は先頭モデルへ自動設定
+- LMStudio / Ollama は接続成功時にローカル列挙したモデルを即座に選択候補へ反映
+
+### VRAMエラー検出と自動フォールバック
+
+- 翻訳処理中の `CUDA out of memory` / `CUBLAS_STATUS_ALLOC_FAILED` などを検出し `/run/error_translation_*_vram_overflow` で通知
+- 自動で翻訳機能を無効化し CTranslate2 へフォールバック、再度有効化試行時も VRAM エラー検出で安全に解除
+
+### CTranslate2 ウェイト / Whisper ウェイト管理
+
+- ダウンロード進捗/完了/エラー用 run エンドポイント: `download_progress_ctranslate2_weight`, `downloaded_ctranslate2_weight`, `error_ctranslate2_weight` / Whisper も同様
+- `SELECTABLE_CTRANSLATE2_WEIGHT_TYPE_DICT` / `SELECTABLE_WHISPER_WEIGHT_TYPE_DICT` の値更新を完了時に反映
+
+### 命名・構造整理
+
+- 翻訳エンジン選択はタブ別 `SELECTED_TRANSLATION_ENGINES[tab_no]` を使用
+- 言語選択構造: `SELECTED_YOUR_LANGUAGES[tab_no]`, `SELECTED_TARGET_LANGUAGES[tab_no]` のネストを前提にエンジン適合性判定
+- CTranslate2 の言語マッピングはウェイト種別 (`CTRANSLATE2_WEIGHT_TYPE`) でネストされた構造に対応
+
+### 言語マッピング外部化
+
+- `getListLanguageAndCountry()` が YAML からロード済み `translation_lang` / `transcription_lang` を統合して互換言語のみ抽出
+
+### デバイス自動選択改善
+
+- マイク/スピーカー自動選択機能で更新前後に適切な停止/再開コールバックをチェーン設定 (energy チェック再起動含む)
+
+### 影響
+
+| 項目 | 内容 |
+|------|------|
+| 翻訳柔軟性 | ローカルLLM (LMStudio/Ollama) によりネットワーク不要運用が可能 |
+| 回復性 | VRAMエラー時自動フォールバックで異常終了を防止 |
+| 拡張性 | モデルリスト自動更新により新モデル追加時の手動変更不要化 |
+| 一貫性 | 統一された SELECTED_/SELECTABLE_ 命名とタブ別管理で UI 連携が簡易化 |
+| 可読性 | 外部 YAML 言語定義によりコード側のハードコード削減 |
+
 ## 主要機能

 ### 機能制御
+
 - 翻訳機能の有効化・無効化
 - 音声認識機能の制御
 - VRオーバーレイの管理
 - WebSocketサーバーの制御

 ### 設定管理
+
 - アプリケーション設定の取得・更新
 - デバイス設定の管理
 - 言語・エンジン設定の制御

 ### 状態管理
+
 - システム状態の監視
 - エラー状態の管理
 - 初期化プロセスの制御

 ### 通信制御
+
 - OSC通信の管理
 - WebSocket通信の制御
 - 外部アプリケーション連携
@@ -30,6 +82,7 @@ VRCTアプリケーションのビジネスロジックを制御するコント
 ## クラス構造

 ### Controller クラス
+
 ```python
 class Controller:
    def __init__(self) -> None
@@ -40,19 +93,23 @@ class Controller:
 ### 内部ヘルパークラス

 #### DownloadCTranslate2 クラス
+
 ```python
 class DownloadCTranslate2:
    def progressBar(self, progress) -> None
    def downloaded(self) -> None
 ```
+
 - 翻訳モデルのダウンロード進捗管理

-#### DownloadWhisper クラス  
+#### DownloadWhisper クラス
+
 ```python
 class DownloadWhisper:
    def progressBar(self, progress) -> None
    def downloaded(self) -> None
 ```
+
 - 音声認識モデルのダウンロード進捗管理

 ## 主要メソッド
@@ -62,6 +119,7 @@ class DownloadWhisper:
 ```python
 init() -> None
 ```
+
 - コントローラーの初期化
 - 各コンポーネントの起動
 - 初期設定の適用
@@ -71,6 +129,7 @@ setInitMapping(init_mapping: dict) -> None
 setRunMapping(run_mapping: dict) -> None
 setRun(run: Callable) -> None
 ```
+
 - エンドポイント・コールバック設定

 ### 翻訳機能制御
@@ -79,23 +138,27 @@ setRun(run: Callable) -> None
 setEnableTranslation(data) -> dict
 setDisableTranslation(data) -> dict
 ```
+
 - 翻訳機能の有効化・無効化

 ```python
 setSelectedTranslationEngines(data) -> dict
 getSelectedTranslationEngines(data) -> dict
 ```
+
 - 翻訳エンジンの選択・取得

 ```python
 setSelectedYourLanguages(data) -> dict
 setSelectedTargetLanguages(data) -> dict
 ```
+
 - 送信・受信言語の設定

 ```python
 sendMessageBox(data) -> dict
 ```
+
 - メッセージの翻訳・送信処理

 ### 音声認識機能制御
@@ -104,24 +167,28 @@ sendMessageBox(data) -> dict
 setEnableTranscriptionSend(data) -> dict
 setEnableTranscriptionReceive(data) -> dict
 ```
+
 - 音声認識機能の有効化

 ```python
 setSelectedTranscriptionEngine(data) -> dict
 getSelectedTranscriptionEngine(data) -> dict
 ```
+
 - 音声認識エンジンの選択・取得

 ```python
 setSelectedMicDevice(data) -> dict
 setSelectedSpeakerDevice(data) -> dict
 ```
+
 - 音声デバイスの選択

 ```python
 setMicThreshold(data) -> dict
 setSpeakerThreshold(data) -> dict
 ```
+
 - 音声しきい値の設定

 ### VRオーバーレイ制御
@@ -130,12 +197,14 @@ setSpeakerThreshold(data) -> dict
 setEnableOverlaySmallLog(data) -> dict
 setEnableOverlayLargeLog(data) -> dict
 ```
+
 - VRオーバーレイの有効化

 ```python
 setOverlaySmallLogSettings(data) -> dict
 setOverlayLargeLogSettings(data) -> dict
 ```
+
 - オーバーレイ設定の更新

 ### WebSocket制御
@@ -144,12 +213,14 @@ setOverlayLargeLogSettings(data) -> dict
 setEnableWebSocketServer(data) -> dict
 setDisableWebSocketServer(data) -> dict
 ```
+
 - WebSocketサーバーの制御

 ```python
 setWebSocketHost(data) -> dict
 setWebSocketPort(data) -> dict
 ```
+
 - WebSocket接続設定

 ### システム管理
@@ -158,17 +229,20 @@ setWebSocketPort(data) -> dict
 updateSoftware(data) -> dict
 updateCudaSoftware(data) -> dict
 ```
+
 - ソフトウェアアップデート

 ```python
 downloadCtranslate2Weight(data) -> dict
 downloadWhisperWeight(data) -> dict
 ```
+
 - AIモデルのダウンロード

 ```python
 feedWatchdog(data) -> dict
 ```
+
 - ウォッチドッグの生存シグナル送信

 ## 使用方法
@@ -233,6 +307,7 @@ result = controller.setEnableTranscriptionSend(None)
 ```

 ### 成功レスポンス例
+
 ```python
 {
    "status": 200,
@@ -241,6 +316,7 @@ result = controller.setEnableTranscriptionSend(None)
 ```

 ### エラーレスポンス例
+
 ```python
 {
    "status": 400,
@@ -248,19 +324,22 @@ result = controller.setEnableTranscriptionSend(None)
 }
 ```

-## 状態管理
+## 詳細状態管理

 ### システム状態
+
 - 各機能の有効・無効状態
 - デバイスの接続状態
 - ネットワーク接続状態

-### エラー状態  
+### エラー状態
+
 - デバイスエラー
 - 翻訳エンジンエラー
 - VRAMオーバーフローエラー

 ### 初期化状態
+
 - 段階的な初期化プロセス
 - 依存関係の解決状態

@@ -271,32 +350,38 @@ result = controller.setEnableTranscriptionSend(None)
 ```python
 micMessage(result: dict) -> None
 ```
+
 - マイク音声認識結果の処理
 - 翻訳・フィルタリング・送信

 ```python
-speakerMessage(result: dict) -> None  
+speakerMessage(result: dict) -> None
 ```
+
 - スピーカー音声認識結果の処理

 ### ダウンロードイベント
+
 - 進捗通知
- 完了通知  
+- 完了通知
 - エラー通知

 ### デバイス変更イベント
+
 - マイク・スピーカーの選択変更
 - 計算デバイスの変更

 ## 依存関係

 ### 直接依存
+
 - `config`: 設定管理
- `model`: コアモデル機能  
+- `model`: コアモデル機能
 - `device_manager`: デバイス管理
 - `utils`: ユーティリティ機能

 ### 間接依存
+
 - 各種モデルモジュール（翻訳、音声認識等）
 - VRオーバーレイモジュール
 - 通信モジュール
@@ -304,32 +389,39 @@ speakerMessage(result: dict) -> None
 ## エラーハンドリング

 ### VRAM不足エラー
+
 - 自動的にCTranslate2への切り替え
 - ユーザーへの適切な通知

 ### デバイスエラー
+
 - デバイス接続状態の監視
 - 自動復旧機能

-### ネットワークエラー  
+### ネットワークエラー
+
 - 接続状態の定期確認
 - オフライン機能への切り替え

 ### 設定エラー
+
 - 設定値の妥当性チェック
 - デフォルト値への復帰

 ## パフォーマンス考慮事項

 ### 遅延初期化
+
 - 必要な時点での機能初期化
 - メモリ使用量の最適化

 ### 非同期処理
+
 - バックグラウンドでの重い処理
 - UI の応答性維持

 ### キャッシュ機能
+
 - 設定値のキャッシュ
 - 翻訳結果のキャッシュ

@@ -346,4 +438,4 @@ speakerMessage(result: dict) -> None
 - 外部入力の適切な検証
 - APIキーの安全な管理
 - ファイルアクセスの制限
- ネットワーク通信の暗号化（該当する場合）
+- ネットワーク通信の暗号化（該当する場合）