Koharu Hy-MT2 + Qwen 파이프라인

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

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

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

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

• 프로세스 래퍼 — 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 작업을 직렬화하며, 해결되지 않은 출력을 조용히 수락하는 대신 오류를 반환합니다.

요구 사항

• Windows 11 및 PowerShell 7

• Python 3.13

• Rust 툴체인 및 Koharu에 필요한 빌드 종속성

• CUDA 지원 NVIDIA GPU; 개발 구성에서는 32GB RTX 5090을 사용했습니다

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

• curl.exe

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

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

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로 구성합니다. 이는 헤드리스 모드를 사용하기 전에 Koharu의 일반 기본 설정 UI를 통해 한 번 저장할 수 있습니다.

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

제한 사항

• 패치는 의도적으로 하나의 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를 참조하세요.