Koharu Hy-MT2 + Qwen 流水线

一个独立的、实验性的日译韩漫画翻译流水线，用于 Koharu。本仓库不是 Koharu 官方项目，也不是上游贡献请求。

本仓库包含：

• 一个固定到 Koharu 提交 a81c5829ea99a45e04580ff97fd6affa81b2db34 的补丁，添加了仅回环访问的无头 Web UI、HTTP API 和 MCP 端点；

• 一个兼容 OpenAI 的翻译 sidecar，先运行固定的 Hy-MT2 初遍翻译，然后卸载它，启动外部管理的 Qwen 审校器，允许一次有针对性的修复遍，并在未解决区域上失败关闭；

• 进程包装器，在停止或重启 Koharu 或 sidecar 之前记录并随后验证确切的进程身份。

它不包含模型权重、漫画页面、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

sidecar 默认绑定到回环地址。它拒绝为 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. 서비스 시작 启动回环 sidecar 和无头 Koharu。

3. 프로젝트 가져오기 创建或打开一个空项目，并导入所选文件或文件夹。这不会启动翻译。

4. 전체 번역 실행 仅在明确确认后启动 GPU 流水线。

5. 내보내기 将 PNG 或 PSD 结果写入所选输出文件夹。

Web UI 열기 打开 Koharu 的详细编辑器，상태 새로고침 报告活动项目和任务，안전 종료 使用本仓库记录的确切进程身份。关闭启动器窗口不会静默停止正在运行的服务。

特定机器的选择会保存到被忽略的 config/local.launcher.json 中；不会被提交。启动期间，启动器会逐字节备份用户的 Koharu 配置，仅写入 Hy-MT2→Qwen 会话配置文件足够长的时间以让无头 Koharu 初始化，然后立即恢复并验证原始字节。如果另一个 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，返回 JSON，其 qwen.state 和 comfyui 字段在流水线启动前报告 off；

• -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 初始化后恢复用户的原始偏好。

同时启动 sidecar 和打过补丁的 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 环境中的实时功能测试。未进行独立的第三方代码或安全审计。

简而言之： AI 生成、用户测试、未经人工代码审查。

上游归属与许可证

Koharu 补丁基于 mayocream 及贡献者在上文标识的确切提交处的 Koharu。依赖边界和归属信息请参见 THIRD_PARTY_NOTICES.md。本仓库在 Apache License 2.0 或 MIT License 中任选其一提供；请参见 LICENSE-APACHE 和 LICENSE-MIT。