Koharu Hy-MT2 + Qwen pipeline

Un pipeline de traducción de manga japonés a coreano, independiente y experimental, 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 headless solo de loopback, 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 segura en regiones no resueltas;

• envoltorios de proceso que registran y posteriormente 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 nada de ese material fuente ni de los resultados detallados se publica 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 de que fue iniciado por la solicitud actual, serializa los trabajos de GPU y devuelve un error en lugar de aceptar silenciosamente resultados no resueltos.

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 utilizó una RTX 5090 de 32 GB

• una compilación de PyTorch con 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 de los modelos y sus licencias siguen siendo responsabilidad del operador.

Preparar Koharu

Clona la revisión ascendente exacta en el directorio vendor/koharu local del repositorio y aplica 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

Crea un entorno virtual propiedad del repositorio. Instala una compilación de PyTorch con CUDA usando el comando adecuado para el controlador local y, a continuación, instala 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 de modelos es ignorado por Git.

Contrato de ciclo de vida de Qwen

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

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

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

• -Operation stop-qwen, que detiene solo ese proceso propiedad de la solicitud 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 los modelos y la política de uso compartido de GPU difieren según la máquina.

Configurar y ejecutar

En Koharu, configura el proveedor compatible con OpenAI para usar el modelo koharu-hy-qwen-v1 y la URL base http://127.0.0.1:4020/v1. Esto puede guardarse una vez a través de la interfaz de preferencias normal de Koharu antes de usar el modo headless.

Inicia tanto el sidecar como el Koharu parcheado:

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

A continuación, abre http://127.0.0.1:4010/. La API JSON tiene su raíz en /api/v1, y el endpoint MCP JSON-RPC es /mcp.

Detén solo los procesos registrados por este repositorio:

pwsh -File .\scripts\stop.ps1

stop.ps1 valida cada ruta de ejecutable registrada, hora de inicio, PID del proceso 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 se niega a detener.

Verificación

Ejecuta las comprobaciones portables:

.\.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 de Python portables, 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 intencionadamente a un commit de Koharu; no se afirma que se aplique a revisiones posteriores.

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

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

• La validación funcional automatizada y en vivo no sustituye 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. Consulta THIRD_PARTY_NOTICES.md para conocer los límites de dependencias y la atribución. Este repositorio se ofrece bajo tu elección de la Licencia Apache 2.0 o la Licencia MIT; consulta LICENSE-APACHE y LICENSE-MIT.