Koharu Hy-MT2 + Qwen 파이프라인

Koharu용 독립적인 실험적 일-한 만화 번역 파이프라인입니다. 이 저장소는 공식 Koharu 프로젝트가 아니며, 업스트림 기여 요청도 아닙니다.

이 저장소에는 다음이 포함됩니다:

• Koharu 커밋 a81c5829ea99a45e04580ff97fd6affa81b2db34에 고정된 패치 — 루프백 전용 헤드리스 Web UI, HTTP API 및 MCP 엔드포인트를 추가합니다;

• OpenAI 호환 번역 사이드카 — 고정된 Hy-MT2 1차 패스를 실행하고, 이를 언로드한 뒤, 외부 관리형 Qwen 리뷰어를 시작하고, 대상 수정 패스를 한 번만 허용하며, 미해결 영역이 있으면 실패로 종료(fail closed)합니다;

• 프로세스 래퍼 — Koharu 또는 사이드카를 중지하거나 재시작하기 전에 정확한 프로세스 정체성을 기록하고 나중에 검증합니다.

모델 가중치, 만화 페이지, 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; 개발 구성은 32GB RTX 5090을 사용했습니다

• 로컬 드라이버와 호환되는 CUDA 지원 PyTorch 빌드

• curl.exe

• 외부 OpenAI 호환 Qwen 서버 및 아래 설명된 수명 주기 스크립트

코드는 기본적으로 http://127.0.0.1:8000/v1에서 Qwen 모델 ID dirk-qwen3.8-27b-q5를 사용합니다. 두 값 모두 구성 가능합니다. 모델 가중치와 해당 라이선스는 운영자의 책임입니다.

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의 상세 편집기를 열고, 상태 새로고침은 활성 프로젝트와 작업을 보고하며, 안전 종료는 저장소의 정확히 기록된 프로세스 정체성을 사용합니다. 실행기 창을 닫아도 실행 중인 서비스가 조용히 중지되지는 않습니다.

머신별 선택 사항은 무시되는 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, 생성 시간 및 전체 명령줄을 검증합니다. 정체성이 변경된 경우 상태를 유지하고 중지를 거부합니다.

검증

휴대용 검사를 실행하세요:

.\.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/모델 테스트는 플랫폼별 네이티브 및 모델 입력이 필요하므로 로컬에서만 수행됩니다.

제한 사항

• 패치는 의도적으로 하나의 Koharu 커밋에 고정되어 있으며 이후 리비전에 적용된다고 주장하지 않습니다.

• 파이프라인은 현재 일본어-한국어 텍스트와 고정된 레터링 역할 정책을 대상으로 합니다.

• 종단 간 운영에는 운영자가 제공하는 Qwen 수명 주기 구현과 모델이 필요합니다.

• 자동화 및 실시간 기능 검증은 수동 소스 검토나 독립적인 보안 감사를 대체하지 않습니다.

AI 개발 공개

대부분의 후속 수정 사항은 사용자 제공 요구 사항과 반복적인 승인 요청을 바탕으로 OpenAI Codex가 생성하고 수정했습니다. 저장소 소유자는 소스 코드를 수동으로 검토하지 않았습니다. 검증은 소유자의 Windows/Codex 환경에서의 자동화된 테스트와 실시간 기능 테스트를 기반으로 합니다. 독립적인 제3자 코드 또는 보안 감사는 수행되지 않았습니다.

요약: AI 생성, 사용자 테스트 완료, 수동 코드 검토 없음.

업스트림 저작자 표시 및 라이선스

Koharu 패치는 위에서 식별된 정확한 커밋의 mayocream 및 기여자들의 Koharu를 기반으로 합니다. 종속성 경계 및 저작자 표시는 THIRD_PARTY_NOTICES.md를 참조하세요. 이 저장소는 Apache License 2.0 또는 MIT License 중 선택하여 제공됩니다. LICENSE-APACHE 및 LICENSE-MIT를 참조하세요.