Koharu Hy-MT2 + Qwen 流水线

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

本仓库包含：

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

• 一个兼容 OpenAI 的翻译伴生进程，先运行固定的 Hy-MT2 首轮翻译，然后卸载它，启动外部管理的 Qwen 审校器，允许一次定向修复轮次，并在未解决区域上失败关闭；

• 进程包装器，在停止或重启 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 任务，并在未解决输出上返回错误而非静默接受。

要求

• 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。两个值均可配置。模型权重及其许可证由操作者自行负责。

准备 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。这可以在使用无头模式之前通过 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 环境中的实时功能测试。未进行任何独立的第三方代码或安全审计。

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

上游归属与许可证

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