企业官网建设流程全解析

Koharu故障排除手册：启动失败、GPU初始化错误与模型加载问题快速排查清单

【免费下载链接】koharuAI-powered manga translator, written in Rust.项目地址: https://gitcode.com/gh_mirrors/ko/koharu

Koharu 是一款用 Rust 编写的 AI 漫画翻译工具，将目标检测、OCR 文字识别、AI 修补（inpainting）与大语言模型整合到本地优先的漫画翻译流程中。本文是一份Koharu 故障排除清单，帮你快速定位三类最常见的问题：Koharu 启动失败、GPU 初始化错误（回退 CPU）、模型下载/加载问题，以及 OCR 质量、翻译服务商、导出异常等疑难场景，并教你用 debug 日志精准收集报错信息。

💡 排查总原则：先看启动界面、活动中心或弹窗里显示的确切错误信息，在弄清是哪一层出问题之前，不要删除项目数据或缓存。

1️⃣ 启动失败快速排查：Koharu 迟迟无法进入项目界面

Koharu 的原生运行时会在项目浏览器可用之前完成初始化。首次启动时，它会按需下载原生运行时包（Torch、llama.cpp、diffusion 等），因此首次启动明显更久是正常的。

常见原因与排查步骤

1. 网络不可达：启动下载依赖 GitHub 发布资源与 Hugging Face（模型权重）。请确认两者可访问，并让活动中心里的下载完成，下载进行中不要关闭窗口。
2. 驱动过旧：关闭全部 Koharu 进程 → 更新 GPU 驱动 → 重启电脑。
3. 反复启动失败时，按此顺序执行：
   • 关闭所有 Koharu 进程；
   • 更新显卡驱动并重启；
   • 在稳定网络下重新启动；
   • 捕获完整的初始化错误（见第 7 节）。
4. 配置文件被手动改坏：设置保存在~/.koharu/config.toml，无效的手动编辑会阻止初始化。请尽量用Settings UI修改，不要手写该文件。

⚠️安全红线：不要在 Koharu 进程仍可能加载着运行时 DLL/动态库时删除运行时目录；删除模型缓存<cache>/koharu/packages/也必须在应用完全关闭时进行（该缓存可再生，删掉后会重新解析下载）。

📁 相关源码：硬件探测位于 crates/koharu-runtime/src/hardware/，运行时包解析位于 crates/koharu-runtime/src/runtime/，下载与缓存位于 crates/koharu-runtime/src/download.rs。

官方文档：docs/getting-started/runtime-models-and-hardware.md

2️⃣ GPU 初始化错误与 CPU 回退诊断

Koharu 在启动时探测硬件，并只为整个 ML 栈选择一个共享设备，优先级如下：

检测到 GPU ≠ 一定能用：即使发现显卡，也需要兼容的驱动 + 对应运行时包。如果任何一条加速路径不可用，回退到 CPU 是预期行为——Koharu 在此场景下优先保证正确性而非速度。

确认当前实际使用的后端

• 打开编辑器内的资源监控（Resource Monitor），查看计算利用率与模型驻留状态；
• 检查启动日志中被选中的 backend（用第 7 节的方法开 debug 日志）。

其他 GPU 相关注意点

• 画布也吃显卡：编辑器画布使用 WebGPU（内嵌 CEF webview），即使 ML 推理回退到 CPU，也需要可用的 WebGPU 适配器和较新的图形驱动；
• N 卡：只需安装最新 NVIDIA 驱动，不需要完整 CUDA SDK；
• A 卡：按你的操作系统安装 ROCm Core SDK with HIP。

3️⃣ 模型下载失败与加载问题排查

Koharu 按需求解析三类数据：原生运行时包、锁定版本的模型文件、本地 GGUF 量化模型。下载采用「先暂存、后发布到缓存」策略，中断的下载可以在下次启动或下次使用该模型时自动重试。

下载卡住或失败的排查清单

• ✅ 确认能访问该模型的 Hugging Face 仓库；
• ✅ 确认磁盘剩余空间充足（4K 级测试素材见下图，实际模型体积更大）；
• ✅ 检查代理、区域限制、认证要求、杀毒软件扫描是否拦截了写入；
• ✅ 对同一模型重试一次；若始终失败在同一个文件，请记录仓库名 + 文件名 + 完整报错，而不只是一句「下载失败」。

想强制重新下载怎么办？

在完全关闭 Koharu后删除缓存目录<cache>/koharu/packages/，下次启动会重新解析并下载所需包与模型。注意：

• 项目数据在Documents/Koharu/，与缓存分离，不受影响；
• 不要运行着应用去动缓存，否则可能损坏正在被占用的原生库。

📁 相关源码：源解析器位于 crates/koharu-runtime/src/source/（Hugging Face / PyPI / 归档），模型加载与设备选择见 crates/koharu-runtime/src/device.rs。

4️⃣ OCR 识别差与文本检测不准：如何快速定位

按顺序检查这 5 点，比盲目调参数更有效：

1. 确认页面方向正确、内容可读；
2. 检查检测是否生成了正确的文本区域（检测框是否覆盖文字）；
3. 在多页样本上保守地调整阈值（检测文本/气泡/面板阈值，位于Settings → Pipeline）；
4. 日文原稿可尝试漫画专用 OCR 模型；
5. 手动更正识别出的源文本后再重跑翻译。

🎯 判断技巧：不要用翻译输出质量来反推 OCR 是否读对了原文，两者是独立环节。

5️⃣ AI 修补（Inpainting）弄坏画面的处理

• 使用更小的手动 Remove 遮罩，避开气泡边框和线条稿；
• 先试直接的修补模型，再考虑更重的生成式模型；
• 把手动修图保留在独立的手绘光栅层上，这样重跑 inpainting 不会覆盖你的修图成果。

6️⃣ 翻译服务商失败与 Agent 登录问题

• 服务商报错：打开Settings → Providers，逐项核对凭据、base URL 与服务商专属字段，然后刷新模型选择器。OpenAI 兼容服务需确认 chat 端点正确，且仅当所选模型支持图片消息时才开启Settings → Translation → Vision input；
• Agent 无法登录/运行：同一时间只允许一个设备登录或一个 Agent 请求——先取消现有尝试，确认浏览器授权针对的是目标账户，再重试。注意Agent 登录与 OpenAI 服务商凭据是两套独立体系；
• 凭据存放在操作系统的安全凭据服务中，不在配置文件里，无需手动处理。

📁 相关源码：各服务商实现位于 crates/koharu-translator/src/remote/，Agent 位于 crates/koharu-agent/src/。

7️⃣ 导出与画布不一致 + 收集 debug 日志

导出结果和画布对不上？

PNG 与 PSD 导出都基于与画布相同的保留帧，有意义的差异属于 Bug而非另一种渲染模式。报告时请记录：项目 revision、页码、输出格式，并附上两边截图。

收集 debug 日志（三平台命令）

调试日志能显示问题发生前 Koharu 正在做什么。必须从终端启动才会生效（先完全关闭所有 Koharu 窗口）：

把日志存到文件（长日志贴文件比截图更有用）：

RUST_LOG=debug koharu 2>&1 | tee "$HOME/koharu-debug.log"

$env:RUST_LOG="debug"; koharu.exe *>&1 | Tee-Object -FilePath "$HOME\koharu-debug.log"

分享前注意：

• 搜索并替换掉 API 密钥、凭据、私有文件名与页面文字（用[removed]占位），保留周边报错行；
• 附上操作系统、Koharu 版本、操作目标、复现步骤和日志中的大致时间。

✅ 故障排查总结清单

更多细节请阅读官方故障排除文档：docs/reference/troubleshooting.md、数据存储边界见 docs/reference/formats-and-data.md、硬件与运行时说明见 docs/getting-started/runtime-models-and-hardware.md。

【免费下载链接】koharuAI-powered manga translator, written in Rust.项目地址: https://gitcode.com/gh_mirrors/ko/koharu