114 lines
6.6 KiB
Markdown
114 lines
6.6 KiB
Markdown
## 翻訳モジュール (models.translation)
|
||
|
||
このドキュメントは `models/translation` 配下に対して行った最近の変更点、セットアップ手順、API の使い方、テスト方針、トラブルシュートをまとめたものです。
|
||
|
||
### 概要
|
||
- モジュールの責務: テキストの翻訳を行う高レベルの `Translator` クラス、言語コードのマッピング、CTranslate2 用の重み・トークナイザのダウンロード/検証ユーティリティを提供します。
|
||
- 変更点の狙い: 型注釈と docstring を追加し、`translation_utils.py` のダウンロード/検証ロジックをシンプルで堅牢な実装へ置換しました。これにより初回セットアップの手順が明確になります。
|
||
|
||
### 主な変更点（サマリ）
|
||
- `translation_translator.py`: 型注釈、docstring を追記。外部依存は存在するが、例外が発生してもモジュールが壊れないように保護されています。
|
||
- `translation_languages.py`: 言語コードマッピングの説明を追加。
|
||
- `translation_utils.py`: 重みファイルの検証（SHA-256 ハッシュ照合）、zip 展開、`transformers.AutoTokenizer` を使ったトークナイザ取得、ダウンロード進捗用のコールバックを備えた実装へ置換。
|
||
|
||
### インストール（依存関係）
|
||
必須ではないものが含まれます。開発・最小稼働に必要なパッケージはプロジェクト全体の要件に従ってください。
|
||
|
||
主に使うパッケージ:
|
||
- `requests` — ダウンロード処理
|
||
- `transformers` — トークナイザ取得（AutoTokenizer）
|
||
- `ctranslate2` — CTranslate2 を使う場合（ランタイムのみ、テストではモック推奨）
|
||
|
||
推奨インストール例（任意）:
|
||
|
||
```powershell
|
||
pip install requests transformers ctranslate2
|
||
```
|
||
|
||
DeepL や `translators` といった外部 API ラッパーはオプショナルです。CI やローカルテストではモックして動作確認してください。
|
||
|
||
### 初回セットアップ / 重みの準備
|
||
`translation_utils.py` に含まれるユーティリティ関数:
|
||
|
||
- `checkCTranslate2Weight(root: str, weight_type: str = "small") -> bool`
|
||
- 指定した `root/weights/ctranslate2/<model_dir>` 以下に必要なファイルが存在し、既知のハッシュと一致するかをチェックします。
|
||
|
||
- `downloadCTranslate2Weight(root: str, weight_type: str = "small", callback: Optional[Callable[[float], None]] = None, end_callback: Optional[Callable[[], None]] = None) -> None`
|
||
- 重みを ZIP 形式でダウンロードして展開します。
|
||
- `callback(progress: float)` は 0.0〜1.0 の進捗通知に使えます。
|
||
- `end_callback()` は処理完了時に呼び出されます。
|
||
|
||
- `downloadCTranslate2Tokenizer(path: str, weight_type: str = "small") -> None`
|
||
- `transformers.AutoTokenizer.from_pretrained` を利用してトークナイザをダウンロード/キャッシュします（`cache_dir` に保存）。
|
||
|
||
呼び出し例（簡単）:
|
||
|
||
```python
|
||
from models.translation import translation_utils as tu
|
||
|
||
# ルートディレクトリ（プロジェクトルートなど）
|
||
root = "."
|
||
if not tu.checkCTranslate2Weight(root, "small"):
|
||
tu.downloadCTranslate2Weight(root, "small", callback=lambda p: print(f"{p*100:.1f}%"))
|
||
tu.downloadCTranslate2Tokenizer(root, "small")
|
||
```
|
||
|
||
注意: 大きなモデル（`large`）はダウンロードに時間とディスク容量を要します。
|
||
|
||
### API 使用例 (`Translator` の簡易例)
|
||
|
||
以下は `Translator` の想定されるシンプルな使い方です（実装は `translation_translator.py` を参照してください）。
|
||
|
||
```python
|
||
from models.translation.translation_translator import Translator
|
||
|
||
tr = Translator()
|
||
result = tr.translate("Hello", src_lang="en", target_lang="ja")
|
||
if result:
|
||
print(result)
|
||
else:
|
||
print("翻訳に失敗しました")
|
||
```
|
||
|
||
戻り値とエラー: 既存のコードベースとの互換性を重視し、失敗時は False を返すケースがあります。API 呼び出し前に戻り値の型を確認してください。
|
||
|
||
### テスト方針
|
||
- 外部サービス（DeepL、web 翻訳ラッパー、ctranslate2、transformers）はユニットテストでモックします。
|
||
- 推奨: `pytest` と `unittest.mock` を使い、`Translator.translate` の成功パス・失敗パスを検証するテストを追加してください。
|
||
|
||
簡単なテスト設計:
|
||
- 正常系: ctranslate2 経由の翻訳が正しく呼ばれる（モックで期待レスポンスを返す）
|
||
- フォールバック系: ctranslate2 が利用できない場合に別の翻訳経路を辿る（モック）
|
||
|
||
### トラブルシュート
|
||
- `ModuleNotFoundError` (例: `sudachidict_full`) — transliteration/別モジュールで必要な辞書が無い場合。該当パッケージのインストールか、当該機能を無効にしてください。
|
||
- ハッシュ不一致 — ダウンロード済みファイルの破損が疑われます。該当ファイルを削除して再ダウンロードしてください。
|
||
- `transformers` のトークナイザが取得できない場合、ネットワークやキャッシュ先の権限を確認してください。
|
||
|
||
### 変更履歴
|
||
- 2025-10-09: 型注釈と docstring の追加、`translation_utils.py` を再実装してダウンロード/検証ロジックを整理。
|
||
|
||
---
|
||
このドキュメントは簡潔な参照用です。必要なら実行例やさらに詳細なトラブルシュート手順（コマンド出力例、ログの取り方など）を追加します。
|
||
# models/translation — 詳細設計
|
||
|
||
構成ファイル:
|
||
- translation_translator.py — Translator クラス。DeepL/API、Google、Bing、Papago、CTranslate2 を統一インターフェースで扱う。
|
||
- translation_utils.py — 重みファイルのダウンロード・検証ロジック（CTranslate2 用）。
|
||
- translation_languages.py — 各エンジンの対応言語マップ。
|
||
|
||
Translator の契約:
|
||
- translate(translator_name, source_language, target_language, target_country, message) -> str|False
|
||
- 成功時は文字列、失敗または一時的エラーは False を返す。
|
||
- changeCTranslate2Model(path, model_type, device, device_index, compute_type)
|
||
- CTranslate2 の Translator オブジェクトと Tokenizer を初期化する。
|
||
|
||
フォールバック:
|
||
- Controller/Model 層で翻訳が失敗した場合に CTranslate2 にフォールバックする実装がある。
|
||
|
||
外部依存:
|
||
- ctranslate2, transformers, deepl（オプション）、translators（任意）
|
||
|
||
安全性:
|
||
- 翻訳 API キー（DeepL）は Translator.authenticationDeepLAuthKey で検証して保持。
|