FuguMT翻訳クライアント 🌸

zagaroid連携専用AI翻訳クライアント

概要

FuguMTモデルを使用したオフライン翻訳サービスを提供するWebSocketクライアントです。zagaroidサーバーに接続し、JSON-RPC 2.0形式の翻訳リクエストを処理します。

主な特徴:

• FuguMT (staka/fugumt-en-ja) モデルを使用したオフライン翻訳
• zagaroidサーバーに接続して翻訳リクエストを処理
• MZP v1.0対応（JSON-RPC 2.0ベースの独自規約。接続確立ごとに initialize（roles=["nmt"]）を送信。仕様の正本は zagaroid/docs/protocol.md）
• 英日・日英翻訳対応
• GPU/MPS/CPU 自動選択対応
• 自動再接続機能（エクスポネンシャルバックオフ）
• 自動設定ファイル生成
• 詳細なログ機能

FuguMTについて

FuguMTはs-takaさんが開発したオープンソースの英日・日英翻訳モデルです：

• MarianNMTベースで構築
• BLEU score 31.65（GPT-3.5の27.04、GPT-4の29.66より高性能）
• CC BY-SA 4.0ライセンス
• Hugging Face: staka/fugumt-en-ja

システム要件

• Python: 3.8 以上
• メモリ: 8GB以上推奨（GPU使用時）
• GPU: NVIDIA GPU (CUDA対応) またはApple Silicon推奨（CPUでも動作可能）
• ストレージ: 5GB以上の空き容量（モデルダウンロード用）
• ネットワーク: 初回実行時のモデルダウンロードに必要

インストール

自動インストール（推奨）

Windows

# プロジェクトをダウンロード
git clone https://github.com/your-username/MenZ-FuguMT.git
cd MenZ-FuguMT

# 自動セットアップを実行
setup.bat

# サーバーを起動
run.bat

Linux/macOS

# プロジェクトをダウンロード
git clone https://github.com/your-username/MenZ-FuguMT.git
cd MenZ-FuguMT

# 自動セットアップを実行
chmod +x setup.sh
./setup.sh

# サーバーを起動
./run.sh

手動インストール

# 1. 仮想環境を作成（推奨）
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# または
venv\Scripts\activate  # Windows

# 2. 依存関係をインストール
pip install -r requirements.txt

# 3. クライアントを起動（初回起動時に自動的に設定ファイルが作成されます）
python main.py

設定

設定ファイル config/fugumt_translator.ini を編集して、サーバーの動作をカスタマイズできます。

主要設定

[WEBSOCKET]
# zagaroidサーバーのIPアドレス
host = 127.0.0.1
# zagaroidサーバーのポート
port = 50001
# 接続パス（zagaroidの翻訳エンドポイント）
path = /translate_text

[TRANSLATION]
model_name_en_ja = staka/fugumt-en-ja
model_name_ja_en = staka/fugumt-ja-en
device = auto  # auto, cpu, cuda, mps
max_length = 128
num_beams = 4
temperature = 1.0
use_cache = true
use_fp16 = false

[LOGGING]
level = INFO
file = logs/fugumt_translator.log

[PERFORMANCE]
timeout_seconds = 30.0
worker_threads = 2

WebSocket設定

zagaroidサーバーの接続先を指定します：

[WEBSOCKET]
host = 192.168.1.100      # zagaroidサーバーのIP
port = 50001               # zagaroidサーバーのポート
path = /translate_text    # 翻訳エンドポイントのパス

デバイス設定

• auto: 自動選択（CUDA → MPS → CPU の順）
• cuda: NVIDIA GPU使用
• mps: Apple Silicon GPU使用
• cpu: CPU使用

使用方法

起動方法

1. 設定ファイルを編集

config/fugumt_translator.ini:

[WEBSOCKET]
host = 192.168.1.100      # zagaroidサーバーのIP
port = 50001               # zagaroidサーバーのポート
path = /translate_text    # 翻訳エンドポイント

2. クライアントを起動

python main.py

カスタム設定ファイル

別の設定ファイルを使用する場合：

python main.py --config my_config.ini

詳細は CLIENT_MODE.md を参照してください。

翻訳リクエスト

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "translate_text",
  "params": {
    "text": "Hello, how are you?",
    "source_lang": "en",
    "target_lang": "ja",
    "priority": "high"
  }
}

レスポンス

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "translated": "こんにちは、元気ですか？",
    "processing_time_ms": 250.5
  }
}

API リファレンス

🔄 サポート形式

このサーバーは JSON-RPC 2.0形式のみ をサポートしています。

type: "translation" などの従来カスタム形式は現在の実装では受け付けず、Invalid Request: JSON-RPC 2.0 format required を返します。

---

📡 JSON-RPC 2.0形式（zagaroid対応・MZP v1.0）

initialize（接続確立ごとに送信）

接続（再接続含む）のたびに自己紹介を送り、zagaroid のセッション台帳に登録される（zagaroid/docs/protocol.md § 4.1 / § 4.5）:

{
  "jsonrpc": "2.0",
  "id": "<uuid>",
  "method": "initialize",
  "params": {
    "protocol": "mzp/1.0",
    "name": "MenZ-FuguMT",
    "roles": ["nmt"]
  }
}

応答 {"result": {"ok": true, "protocol": "mzp/1.0"}} を10秒以内に受けられなければ再接続する。

翻訳リクエスト

リクエスト:

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "translate_text",
  "params": {
    "text": "こんにちは、今日はお元気ですか？",
    "speaker": "discord_user_123456789",
    "source_lang": "ja",
    "target_lang": "en",
    "priority": "normal"
  }
}

レスポンス:

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "translated": "Hello, how are you today?",
    "processing_time_ms": 234.56,
    "speaker": "discord_user_123456789"
  }
}

利用可能なJSON-RPCメソッド

translate_text

テキストを翻訳します。

パラメータ:

• text (string, required): 翻訳対象テキスト
• source_lang (string, optional): 源言語（デフォルト: "en"）
• target_lang (string, optional): 目標言語（デフォルト: "ja"）
• speaker (string, optional): 話者ID
• priority (string, optional): 優先度（デフォルト: "normal"）

health_check

サーバーの健康状態を確認します。

パラメータ: なし

レスポンス例:

{
  "jsonrpc": "2.0",
  "id": "...",
  "result": {
    "status": "healthy",
    "models_loaded": 2,
    "device": "cuda:0",
    "supported_pairs": ["en-ja", "ja-en"]
  }
}

get_stats

翻訳統計情報を取得します。

パラメータ: なし

list_methods

利用可能なメソッド一覧を取得します。

パラメータ: なし

テストクライアント

JSON-RPC形式のテストには、付属のテストスクリプトを使用できます：

python test_jsonrpc_client.py

---

Unity での使用例（JSON-RPC 2.0）

using System;
using System.Threading.Tasks;
using UnityEngine;
using WebSocketSharp;

public class FuguMTClient : MonoBehaviour
{
    private WebSocket ws;
    
    void Start()
    {
        ws = new WebSocket("ws://127.0.0.1:55002");
        ws.OnMessage += OnMessage;
        ws.Connect();
    }
    
    public void TranslateText(string text, string sourceLang = "en", string targetLang = "ja")
    {
        var request = new
        {
            jsonrpc = "2.0",
            id = Guid.NewGuid().ToString(),
            method = "translate_text",
            @params = new
            {
                text = text,
                source_lang = sourceLang,
                target_lang = targetLang
            }
        };
        
        ws.Send(JsonUtility.ToJson(request));
    }
    
    private void OnMessage(object sender, MessageEventArgs e)
    {
        var response = JsonUtility.FromJson<TranslationResponse>(e.Data);
        Debug.Log($"翻訳結果: {response.translated}");
    }
}

[Serializable]
public class TranslationResponse
{
    public string jsonrpc;
    public string id;
    public TranslationResult result;
}

[Serializable]
public class TranslationResult
{
    public string translated;
    public float processing_time_ms;
}

Python クライアントの例

JSON-RPC 2.0形式（zagaroid互換）

import asyncio
import websockets
import json
import uuid

async def translate_text_jsonrpc(text, source_lang="en", target_lang="ja", speaker=None):
    """JSON-RPC 2.0形式で翻訳"""
    uri = "ws://127.0.0.1:50001"
    
    async with websockets.connect(uri) as websocket:
        request = {
            "jsonrpc": "2.0",
            "id": str(uuid.uuid4()),
            "method": "translate_text",
            "params": {
                "text": text,
                "source_lang": source_lang,
                "target_lang": target_lang,
                "speaker": speaker
            }
        }
        
        await websocket.send(json.dumps(request))
        response = await websocket.recv()
        result = json.loads(response)
        
        if "result" in result:
            return result["result"]["translated"]
        else:
            raise Exception(result.get("error", {}).get("message", "Translation failed"))

# 使用例
async def main():
    translation = await translate_text_jsonrpc(
        "Hello world!",
        speaker="user_123"
    )
    print(f"翻訳結果: {translation}")

asyncio.run(main())

トラブルシューティング

GPU が認識されない

# GPU環境をチェック
python check_gpu.py

# NVIDIA GPU
nvidia-smi

# 依存関係を再インストール
pip install torch --index-url https://download.pytorch.org/whl/cu118

翻訳が遅い

1. 設定ファイルを調整:

   [TRANSLATION]
   device = cuda  # または mps
   num_beams = 2  # ビーム数を減らす
   max_length = 256  # 最大長を短縮
   
   [PERFORMANCE]
   batch_size = 4  # バッチサイズを増加
   

2. メモリ不足の場合:

   [TRANSLATION]
   num_beams = 1
   max_length = 128
   

接続エラー

1. ファイアウォール設定を確認
2. ポートが使用されていないか確認:

   # Windows
   netstat -an | findstr :55002
   
   # Linux/macOS
   lsof -i :55002
   

モデルダウンロードエラー

1. ネットワーク接続を確認
2. Hugging Face Hubの設定:

   # キャッシュクリア
   rm -rf ~/.cache/huggingface/
   
   # 手動ダウンロード
   python -c "from transformers import MarianTokenizer, MarianMTModel; MarianTokenizer.from_pretrained('staka/fugumt-en-ja'); MarianMTModel.from_pretrained('staka/fugumt-en-ja')"
   

開発者向け情報

プロジェクト構造

MenZ-FuguMT/
├── FuguMTTranslator/              # メインパッケージ
│   ├── __init__.py
│   ├── config.py                  # 設定管理
│   ├── translator.py              # 翻訳エンジン
│   └── websocket_server.py        # WebSocketサーバー
├── config/
│   └── fugumt_translator.ini      # 設定ファイル
├── logs/                          # ログファイル
├── main.py                        # エントリーポイント
├── setup.py                       # セットアップスクリプト
├── requirements.txt               # 依存関係
├── setup.bat / setup.sh           # 自動セットアップ
├── run.bat / run.sh               # 実行スクリプト
├── check_gpu.py                   # GPU環境チェック
└── README.md                      # このファイル

ログファイル

ログは以下の場所に出力されます：

• Windows: logs\\fugumt_translator.log
• Linux/macOS: logs/fugumt_translator.log

パフォーマンスチューニング

1. GPU最適化:

   [TRANSLATION]
   device = cuda
   use_cache = true
   
   [PERFORMANCE]
   worker_threads = 2
   batch_size = 8
   

2. CPU最適化:

   [TRANSLATION]
   device = cpu
   num_beams = 1
   max_length = 256
   
   [PERFORMANCE]
   worker_threads = 4
   batch_size = 1
   

ライセンス

このプロジェクトはMITライセンスの下で公開されています。

ただし、使用するFuguMTモデルはCC BY-SA 4.0ライセンスの下で配布されており、研究用途での使用が前提となっています。商用利用の際は、モデルライセンスを十分にご確認ください。

謝辞

• FuguMTモデル: s-takaさんによる優秀な翻訳モデルの提供に感謝いたします
• 参考プロジェクト: MenZ-translationのアーキテクチャを参考にさせていただきました
• Marian NMT: MarianNMTフレームワークの開発チームに感謝いたします

貢献

プルリクエストやイシューの報告を歓迎します。

サポート

問題が発生した場合は、GitHub Issues でお知らせください。

---

FuguMT翻訳サーバー - 高品質なオフライン翻訳サービスをあなたのアプリケーションに 🌸