Koharu Hy-MT2 + Qwen pipeline

Un pipeline independiente y experimental de traducción de manga del japonés al coreano para Koharu. Este repositorio no es un proyecto oficial de Koharu ni una solicitud de contribución ascendente.

El repositorio contiene:

• un parche fijado al commit a81c5829ea99a45e04580ff97fd6affa81b2db34 de Koharu que añade una interfaz web sin cabeza solo de bucle local, una API HTTP y un endpoint MCP;

• un sidecar de traducción compatible con OpenAI que ejecuta una primera pasada fijada de Hy-MT2, la descarga, inicia un revisor Qwen gestionado externamente, permite una pasada de reparación específica y falla de forma cerrada en regiones no resueltas;

• envoltorios de proceso que registran y luego verifican la identidad exacta del proceso antes de detener o reiniciar Koharu o el sidecar.

No contiene pesos de modelos, páginas de manga, corpus de OCR, traducciones generadas, resultados de evaluación privados ni un runtime de Qwen. Un piloto privado de 512 páginas / 6,525 regiones informó el desarrollo, pero ninguno de esos materiales fuente ni resultados detallados se publican aquí.

Arquitectura y límites

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

El sidecar se vincula a loopback por defecto. Rechaza la alternativa de CPU para Hy-MT2, se niega a traducir mientras Qwen ya está en ejecución, exige que el proceso de Qwen informe que fue iniciado por la solicitud actual, serializa los trabajos de GPU y devuelve un error en lugar de aceptar silenciosamente una salida no resuelta.

Related MCP server: mcp-i18n

Requisitos

• Windows 11 y PowerShell 7

• Python 3.13

• Cadena de herramientas de Rust y las dependencias de compilación requeridas por Koharu

• una GPU NVIDIA compatible con CUDA; la configuración de desarrollo usó una RTX 5090 de 32 GB

• una compilación de PyTorch habilitada para CUDA compatible con el controlador local

• curl.exe

• un servidor Qwen externo compatible con OpenAI y un script de ciclo de vida descrito a continuación

El código usa por defecto el ID de modelo Qwen dirk-qwen3.8-27b-q5 en http://127.0.0.1:8000/v1. Ambos valores son configurables. Los pesos del modelo y sus licencias siguen siendo responsabilidad del operador.

Lanzador GUI de Windows

Después de preparar Koharu, Python, Hy-MT2 y el script de ciclo de vida de Qwen como se describe a continuación, haga doble clic:

Launch-Koharu-GUI.cmd

El lanzador en idioma coreano proporciona selectores nativos de archivos y carpetas. Abra 고급 실행 설정 una vez y elija el ejecutable de Python local, koharu.exe parcheado, la carpeta del modelo Hy-MT2 y el script de ciclo de vida de Qwen. Luego use los botones numerados:

1. 설정 검사 valida las rutas del runtime local.

2. 서비스 시작 inicia el sidecar de loopback y Koharu sin cabeza.

3. 프로젝트 가져오기 crea o abre un proyecto vacío e importa el archivo o carpeta seleccionados. Esto no inicia la traducción.

4. 전체 번역 실행 inicia el pipeline de GPU solo después de una confirmación explícita.

5. 내보내기 escribe los resultados PNG o PSD en la carpeta de salida seleccionada.

Web UI 열기 abre el editor detallado de Koharu, 상태 새로고침 informa sobre el proyecto activo y los trabajos, y 안전 종료 utiliza las identidades de proceso exactas registradas por el repositorio. Cerrar la ventana del lanzador no detiene silenciosamente un servicio en ejecución.

Las opciones específicas de la máquina se guardan en config/local.launcher.json ignorado; no se confirman. Durante el inicio, el lanzador hace una copia de seguridad byte a byte de la configuración de Koharu del usuario, escribe el perfil de sesión Hy-MT2→Qwen solo el tiempo necesario para que Koharu sin cabeza se inicialice, y restaura y verifica inmediatamente los bytes originales. Se niega a cambiar de perfil si otro proceso de Koharu ya está en ejecución.

Preparar Koharu

Clone la revisión ascendente exacta en el directorio vendor/koharu local del repositorio y aplique el parche fijado:

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

El script de aplicación rechaza un commit diferente, un checkout sucio o un parche que no pase git apply --check.

Preparar Python y Hy-MT2

Cree un entorno virtual propiedad del repositorio. Instale una compilación de PyTorch CUDA usando el comando apropiado para el controlador local, luego instale los paquetes fijados restantes:

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 descarga solo la revisión registrada en config/model-lock.json y escribe un manifiesto SHA-256 local. El directorio del modelo es ignorado por Git.

Contrato de ciclo de vida de Qwen

El argumento -QwenLifecycleScript es obligatorio y específico de la máquina. Su script debe admitir:

• -Operation status -Summary, que devuelve JSON cuyos campos qwen.state y comfyui informan off antes del inicio del pipeline;

• -Operation start-qwen, que devuelve JSON con started_by_request: true solo cuando esta solicitud es dueña del proceso Qwen iniciado;

• -Operation stop-qwen, que detiene solo ese proceso propiedad y devuelve JSON.

La implementación del ciclo de vida no se incluye deliberadamente porque los runtimes de Qwen, los comandos de lanzamiento, las ubicaciones de modelos y la política de uso compartido de GPU difieren según la máquina.

Configurar y ejecutar

Al usar los scripts de línea de comandos directamente, configure el proveedor compatible con OpenAI de Koharu para usar el modelo koharu-hy-qwen-v1 y la URL base http://127.0.0.1:4020/v1. El lanzador GUI aplica este perfil temporalmente y restaura las preferencias originales del usuario después de que Koharu sin cabeza se inicialice.

Inicie tanto el sidecar como Koharu parcheado:

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

Luego abra http://127.0.0.1:4010/. La API JSON tiene su raíz en /api/v1, y el endpoint MCP JSON-RPC está en /mcp.

Detenga solo los procesos registrados por este repositorio:

pwsh -File .\scripts\stop.ps1

stop.ps1 valida cada ruta de ejecutable registrada, hora de inicio, PID padre, hora de creación y línea de comandos completa antes de tocar un PID. Si la identidad ha cambiado, conserva el estado y rechaza la detención.

Verificación

Ejecute las comprobaciones portátiles:

.\.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) }
}

Para el checkout de Koharu parcheado:

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

El flujo de trabajo de CI ejecuta las pruebas portátiles de Python, la compilación de Python y las comprobaciones del analizador de PowerShell. Las compilaciones completas de Koharu y las pruebas de GPU/modelo permanecen locales porque requieren entradas nativas y de modelo específicas de la plataforma.

Limitaciones

• El parche está fijado intencionalmente a un commit de Koharu; no se afirma que se aplique a revisiones posteriores.

• El pipeline actualmente se dirige a texto japonés a coreano y una política fija de roles de rotulación.

• La operación de extremo a extremo requiere una implementación y un modelo de ciclo de vida de Qwen proporcionados por el operador.

• La validación funcional automatizada y en vivo no reemplaza la revisión manual del código fuente ni una auditoría de seguridad independiente.

Divulgación de desarrollo con IA

La mayoría de las modificaciones posteriores fueron generadas y revisadas por OpenAI Codex a partir de requisitos proporcionados por el usuario y solicitudes de aceptación iterativas. El propietario del repositorio no revisó manualmente el código fuente. La validación se basa en pruebas automatizadas y pruebas funcionales en vivo en el entorno Windows/Codex del propietario. No se ha realizado ninguna auditoría de código o seguridad independiente de terceros.

En resumen: generado por IA, probado por el usuario, no revisado manualmente.

Atribución ascendente y licencia

El parche de Koharu se basa en Koharu de mayocream y colaboradores en el commit exacto identificado anteriormente. Consulte THIRD_PARTY_NOTICES.md para conocer los límites de dependencias y la atribución. Este repositorio se ofrece bajo su elección de la Licencia Apache 2.0 o la Licencia MIT; consulte LICENSE-APACHE y LICENSE-MIT.