every_holiday/VRCT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bcfbf5169641c0f8ead8fd7780a334f958934bfb
VRCT/src-python/docs/仕様書.md
misyaguziya bcfbf51696 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

8.1 KiB
Raw Blame History

仕様書

概要

  • プロジェクト名: VRCT (VR Chat Translator)
  • 目的: マイク入力とスピーカー出力をリアルタイムに文字起こし・翻訳し、VR オーバーレイや OSC/WebSocket 経由で外部に送出するバックエンドロジック。
  • 言語: Python

対象ユーザー

  • VR 環境でリアルタイム翻訳・文字起こしを利用したいエンドユーザー
  • フロントエンド（GUI）や VR クライアント（OSC）と連携するアプリケーション開発者

主要機能（機能要件）

  1. 音声の取り込み・文字起こし

    • マイク（送信）およびスピーカー（受信）から音声を取得し、ローカル Whisper（faster-whisper）または外部サービスによりテキスト化する。
    • 音声エネルギー（音量）監視を行い、閾値ベースで検出する。

  2. 翻訳

    • DeepL / DeepL API / 各クラウド翻訳 / ローカル CTranslate2 モデルの複数バックエンドをサポート。
    • 複数出力言語への一括翻訳、翻訳エンジンのフォールバック（CTranslate2 など）。
    • 翻訳モデルのダウンロードと管理機能。

  3. 表示・通知

    • OpenVR オーバーレイ（small/large）用の画像生成と更新。
    • OSC による VR へのメッセージ送信（typing/通知等）。
    • WebSocket サーバーを介した外部クライアントへの JSON ブロードキャスト。

  4. 入出力インターフェース

    • stdin ラインベースの JSON コマンド受信（mainloop が実装）。
    • stdout に対して構造化された JSON レスポンスを出力（printResponse/printLog）。

  5. 設定・永続化

    • JSON ベースの設定ファイルを使用（config.py による読み書きとデバウンス保存）。

  6. ロギングと監視

    • プロセスログ（process.log）とエラーログ（error.log）をローテーションで管理。
    • ウォッチドッグ機構で定期的に死活チェック・コールバック。

非機能要件

  • プラットフォーム: 主に Windows（Audio 周りは WASAPI を利用）を想定。クロスプラットフォームでの import 安全性を考慮。
  • 可用性: 外部依存（PyAudio, CUDA, ctranslate2 等）が無い環境でも安全にインポートでき、機能劣化しつつ動作する。
  • パフォーマンス: ローカルモデル利用時は GPU を利用して計算性能を確保。compute type 選択ロジックを実装。
  • セキュリティ: 外部への API キー（DeepL など）は設定で扱い、コード上では平文保持を避ける（設定ファイルに保存）。

運用フロー

  • 起動: stdin でコマンドを受け付ける mainloop を実行。必要な初期化は遅延実行（lazy init）を採用。
  • モデル重ダウンロード: CTranslate2/Whisper 重みは weights/ 配下にダウンロードし、チェックサム等で整合性確認。
  • 障害時: 例外は utils.errorLogging() でトレースを error.log に出力。重要機能はフォールバック実装。

インターフェース（抜粋）

  • stdin(JSON): {"endpoint": "/set/..." | "/get/..." | "/run/...", "data": <base64(JSON)|any>}
  • stdout(JSON): 標準化されたレスポンスを printResponse/printLog が出力（status, endpoint, result など）。

依存関係（オプション含む）

  • 必須（実装時想定）: requests, packaging, flashtext, pillow, pyaudiowpatch, speech_recognition
  • ローカル推奨: faster-whisper, ctranslate2, torch（GPU 利用時）
  • Windows 固有（音声ループバック）: pycaw, comtypes

参考: 実装上の安全設計として optional な import は try/except でガードしており、存在しない依存があっても import 時にクラッシュしない。

最近の更新 (2025-10-20 translate_api ブランチ)

本章は既存仕様への差分のみを記載します。コードベースの事実に基づく更新点です。

翻訳エンジン / モデル管理の拡張

  • OpenAI / Plamo / Gemini の選択モデルプロパティを PLAMO_MODEL / GEMINI_MODEL / OPENAI_MODEL から SELECTED_PLAMO_MODEL / SELECTED_GEMINI_MODEL / SELECTED_OPENAI_MODEL にリネーム (旧名称は保存対象から移行)。
  • 新規ローカル LLM 接続: LMStudio (LMSTUDIO_URL, SELECTABLE_LMSTUDIO_MODEL_LIST, SELECTED_LMSTUDIO_MODEL) を追加。
  • 新規ローカル LLM 接続: Ollama (SELECTABLE_OLLAMA_MODEL_LIST, SELECTED_OLLAMA_MODEL) を追加。
  • OpenAI 認証キー設定時にモデル一覧 (SELECTABLE_OPENAI_MODEL_LIST) を自動取得し、未選択時に第一候補へフォールバックする処理を追加。メソッド名を OpenAi → OpenAI に統一。

エンドポイント追加 / 変更

mainloop.py の mapping / run_mapping に以下を追加:

  • /get/data/lmstudio_model_list, /get/data/lmstudio_model, /set/data/lmstudio_model, /get/data/lmstudio_url, /set/data/lmstudio_url
  • /get/data/ollama_connection, /get/data/ollama_model_list, /get/data/ollama_model, /set/data/ollama_model
  • OpenAI 系: getOpenAIAuthKey, setOpenAIAuthKey, delOpenAIAuthKey, getOpenAIModelList, getOpenAIModel, setOpenAIModel に名称統一。

翻訳言語定義の構造変更

  • CTranslate2 の言語定義をトップレベル直接キー (例: m2m100_418M-ct2-int8) から translation_lang['CTranslate2'][weight_type] のネスト構造へ再編。利用側の互換ロジック (model.findTranslationEngines) は weight_type 経由で参照するよう修正。
  • 新規 YAML 言語マッピングファイル models/translation/languages/languages.yml を追加。config.init_config() 内で loadTranslationLanguages() を呼び出し統合 (失敗時は空辞書フォールバック)。

プロンプトファイルの整理

  • translation_gemini.yml, translation_lmstudio.yml から supported_languages ブロックを削除し、system_prompt 内に簡潔化。

リソース / PyInstaller

  • PyInstaller spec (backend.spec, backend_cuda.spec) の datas に ./src-python/models/translation/prompt および ./src-python/models/translation/languages を追加。
  • フォント配置を fonts/ 直下から src-python/models/overlay/fonts/ へ移動し、overlay_image.py にビルド時 (_internal/fonts) と開発時の動的探索ロジックを追加。

依存パッケージの追加

  • requirements.txt / requirements_cuda.txt に PyYAML==6.0.2 (YAML読込), google-genai==1.45.0, grpcio==1.67.1 を追加。

認証処理の微調整

  • Plamo / Gemini 認証メソッドで root_path=config.PATH_LOCAL を渡すよう変更し、ローカル参照を統一。
  • OpenAI モデル設定メソッドの名称を setTranslatorOpenAiModel → setTranslatorOpenAIModel に変更。

テスト拡張

  • backend_test.py に全言語ペア翻訳網羅テスト test_translate_all_language_pairs() を追加。結果を translation_test_results.json として保存。

内部ユーティリティの修正

  • downloadCTranslate2Tokenizer() が tokenizer_path を正しく作成し transformers.AutoTokenizer.from_pretrained(tokenizer, cache_dir=tokenizer_path) を使用するよう修正。

影響範囲まとめ

区分 影響内容
設定 新規プロパティ / 既存名称変更 (SELECTED_*, LMSTUDIO_URL)
エンドポイント LMStudio / Ollama / OpenAI 名称統一追加
翻訳言語 CTranslate2 ネスト構造 / YAML マッピング導入
リソース PyInstaller datas 追加 / フォントパス移行
依存 PyYAML / google-genai / grpcio 追加
認証 OpenAI/Plamo/Gemini 認証後モデルリスト更新 & root_path 引数追加
テスト 全言語ペア網羅テスト追加
ユーティリティ Tokenizer ダウンロード処理修正

ライセンス影響

追加された依存は既存 LICENSE の記載範囲に変更を強制するものではなく、ライセンス本文の更新不要 (現行 OSS ライセンス許容範囲内)。

Reference in New Issue View Git Blame Copy Permalink