Koharu Hy-MT2 + Qwen パイプライン

Koharu 向けの、独立した実験的な日本語→韓国語マンガ翻訳パイプラインです。このリポジトリは Koharu の公式プロジェクトではなく、アップストリームへの貢献リクエストでもありません。

このリポジトリには以下が含まれます:

• Koharu コミット a81c5829ea99a45e04580ff97fd6affa81b2db34 に固定されたパッチ。ループバック専用のヘッドレス Web UI、HTTP API、MCP エンドポイントを追加します。

• OpenAI 互換の翻訳サイドカー。固定された Hy-MT2 のファーストパスを実行し、アンロードしてから、外部管理の Qwen レビューアを起動し、1回のターゲットを絞った修復パスを許可し、未解決領域がある場合はフェイルクローズします。

• Koharu またはサイドカーを停止・再起動する前に、正確なプロセス ID を記録し、後で検証するプロセスラッパー。

モデルウェイト、マンガページ、OCR コーパス、生成された翻訳、非公開の評価出力、Qwen ランタイムは含まれません。非公開の 512 ページ / 6,525 領域のパイロットが開発に役立ちましたが、そのソース資料や詳細な出力はここには公開されていません。

アーキテクチャと境界

Koharu pipeline
  -> loopback OpenAI-compatible sidecar
  -> pinned Hy-MT2-7B first translation (CUDA only)
  -> Hy-MT2 process exits and releases VRAM
  -> externally owned Qwen lifecycle starts the reviewer
  -> sparse review, then at most one targeted repair
  -> deterministic validation and Koharu typography update
  -> Qwen lifecycle stops the reviewer

サイドカーはデフォルトでループバックにバインドします。Hy-MT2 の CPU フォールバックを拒否し、Qwen がすでに実行中の場合は翻訳を拒否し、Qwen プロセスが現在のリクエストによって起動されたことを報告することを要求し、GPU ジョブを直列化し、未解決の出力を黙って受け入れる代わりにエラーを返します。

Related MCP server: mcp-i18n

要件

• Windows 11 と PowerShell 7

• Python 3.13

• Rust ツールチェーンと Koharu が必要とするビルド依存関係

• CUDA 対応の NVIDIA GPU。開発構成では 32 GB の RTX 5090 を使用しました。

• ローカルドライバと互換性のある CUDA 対応 PyTorch ビルド

• curl.exe

• 外部の OpenAI 互換 Qwen サーバーと、後述するライフサイクルスクリプト

コードはデフォルトで Qwen モデル ID dirk-qwen3.8-27b-q5 を http://127.0.0.1:8000/v1 で使用します。どちらの値も設定可能です。モデルウェイトとそのライセンスは運用者の責任です。

Windows GUI ランチャー

後述のように Koharu、Python、Hy-MT2、Qwen ライフサイクルスクリプトを準備した後、ダブルクリックします:

Launch-Koharu-GUI.cmd

韓国語のランチャーは、ネイティブのファイルおよびフォルダピッカーを提供します。고급 실행 설정 を一度開き、ローカルの Python 実行ファイル、パッチ適用済みの koharu.exe、Hy-MT2 モデルフォルダ、Qwen ライフサイクルスクリプトを選択します。次に、番号付きボタンを使用します:

1. 설정 검사 はローカルランタイムパスを検証します。

2. 서비스 시작 はループバックサイドカーとヘッドレス Koharu を起動します。

3. 프로젝트 가져오기 は空のプロジェクトを作成または開き、選択したファイルまたはフォルダをインポートします。これは翻訳を開始しません。

4. 전체 번역 실행 は明示的な確認後にのみ GPU パイプラインを開始します。

5. 내보내기 は選択した出力フォルダに PNG または PSD の結果を書き込みます。

Web UI 열기 は Koharu の詳細なエディタを開き、상태 새로고침 はアクティブなプロジェクトとジョブを報告し、안전 종료 はこのリポジトリの正確に記録されたプロセス ID を使用します。ランチャーウィンドウを閉じても、実行中のサービスが黙って停止することはありません。

マシン固有の選択は無視される config/local.launcher.json に保存され、コミットされません。起動時に、ランチャーはユーザーの Koharu 設定をバイト単位でバックアップし、ヘッドレス Koharu が初期化するのに十分な時間だけ Hy-MT2→Qwen セッションプロファイルを書き込み、すぐに元のバイトを復元して検証します。別の Koharu プロセスがすでに実行されている場合、プロファイルの切り替えを拒否します。

Koharu の準備

リポジトリローカルの vendor/koharu ディレクトリに正確なアップストリームリビジョンをクローンし、固定されたパッチを適用します:

git clone https://github.com/mayocream/koharu.git vendor/koharu
git -C vendor/koharu checkout a81c5829ea99a45e04580ff97fd6affa81b2db34
pwsh -File .\scripts\apply-koharu-patch.ps1 -KoharuCheckout .\vendor\koharu
cargo build --manifest-path .\vendor\koharu\Cargo.toml -p koharu

アプリケーションスクリプトは、異なるコミット、ダーティなチェックアウト、または git apply --check に合格しないパッチを拒否します。

Python と Hy-MT2 の準備

リポジトリ所有の仮想環境を作成します。ローカルドライバに適したコマンドを使用して CUDA PyTorch ビルドをインストールし、残りの固定パッケージをインストールします:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
# Install a compatible CUDA build of PyTorch here.
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe .\scripts\download-model.py hy-mt2-7b

download-model.py は config/model-lock.json に記録されたリビジョンのみをダウンロードし、ローカルの SHA-256 マニフェストを書き込みます。モデルディレクトリは Git によって無視されます。

Qwen ライフサイクル契約

-QwenLifecycleScript 引数は必須であり、マシン固有です。そのスクリプトは以下をサポートする必要があります:

• -Operation status -Summary。パイプライン起動前に qwen.state と comfyui フィールドが off を報告する JSON を返します。

• -Operation start-qwen。このリクエストが起動した Qwen プロセスを所有する場合にのみ、started_by_request: true を含む JSON を返します。

• -Operation stop-qwen。所有するプロセスのみを停止し、JSON を返します。

ライフサイクル実装は、Qwen ランタイム、起動コマンド、モデルの場所、GPU 共有ポリシーがマシンごとに異なるため、意図的にバンドルされていません。

設定と実行

コマンドラインスクリプトを直接使用する場合は、Koharu の OpenAI 互換プロバイダーをモデル koharu-hy-qwen-v1、ベース URL http://127.0.0.1:4020/v1 に設定します。GUI ランチャーはこのプロファイルを一時的に適用し、ヘッドレス Koharu の初期化後にユーザーの元の設定を復元します。

サイドカーとパッチ適用済み Koharu の両方を起動します:

pwsh -File .\scripts\start.ps1 `
  -QwenLifecycleScript C:\path\to\your\Invoke-QwenLifecycle.ps1

次に http://127.0.0.1:4010/ を開きます。JSON API は /api/v1 に、MCP JSON-RPC エンドポイントは /mcp にあります。

このリポジトリによって記録されたプロセスのみを停止します:

pwsh -File .\scripts\stop.ps1

stop.ps1 は、PID に触れる前に、記録された各実行ファイルパス、開始時刻、親 PID、作成時刻、完全なコマンドラインを検証します。ID が変更された場合は、状態を保持して停止を拒否します。

検証

ポータブルチェックを実行します:

.\.venv\Scripts\python.exe -m unittest service.test_server

$scripts = Get-ChildItem .\scripts -Filter *.ps1
foreach ($script in $scripts) {
  $tokens = $null
  $errors = $null
  [void][System.Management.Automation.Language.Parser]::ParseFile($script.FullName, [ref]$tokens, [ref]$errors)
  if ($errors.Count) { throw ($errors | Out-String) }
}

パッチ適用済み Koharu チェックアウトの場合:

cargo test --manifest-path .\vendor\koharu\Cargo.toml -p koharu-app api::tests
cargo test --manifest-path .\vendor\koharu\Cargo.toml -p koharu-pipeline onomatopoeia_becomes_a_sound_effect_text_layer
cargo test --manifest-path .\vendor\koharu\Cargo.toml -p koharu-translator serializes_optional_koharu_region_metadata
cargo build --manifest-path .\vendor\koharu\Cargo.toml -p koharu

CI ワークフローは、ポータブル Python テスト、Python コンパイル、PowerShell パーサーチェックを実行します。完全な Koharu ビルドと GPU/モデルテストは、プラットフォーム固有のネイティブおよびモデル入力を必要とするため、ローカルのままです。

制限事項

• パッチは意図的に 1 つの Koharu コミットに固定されており、それ以降のリビジョンに適用されるとは主張されていません。

• パイプラインは現在、日本語から韓国語へのテキストと、固定されたレタリングロールポリシーを対象としています。

• エンドツーエンドの運用には、オペレーター提供の Qwen ライフサイクル実装とモデルが必要です。

• 自動化およびライブの機能検証は、手動のソースレビューや独立したセキュリティ監査に代わるものではありません。

AI 開発の開示

下流の変更のほとんどは、ユーザー提供の要件と反復的な受け入れリクエストから OpenAI Codex によって生成および改訂されました。リポジトリ所有者はソースコードを手動でレビューしていません。検証は、所有者の Windows/Codex 環境での自動テストとライブ機能テストに基づいています。独立した第三者によるコードまたはセキュリティ監査は実施されていません。

要約: AI 生成、ユーザーテスト済み、手動コードレビューなし。

アップストリームの帰属とライセンス

Koharu パッチは、上記で特定された正確なコミットにおける mayocream とコントリビューターによる Koharu に基づいています。依存関係の境界と帰属については THIRD_PARTY_NOTICES.md を参照してください。このリポジトリは、Apache License 2.0 または MIT License のいずれかを選択して提供されます。LICENSE-APACHE と LICENSE-MIT を参照してください。