Koharu故障排除手册启动失败、GPU初始化错误与模型加载问题快速排查清单【免费下载链接】koharuAI-powered manga translator, written in Rust.项目地址: https://gitcode.com/gh_mirrors/ko/koharuKoharu 是一款用 Rust 编写的 AI 漫画翻译工具将目标检测、OCR 文字识别、AI 修补inpainting与大语言模型整合到本地优先的漫画翻译流程中。本文是一份Koharu 故障排除清单帮你快速定位三类最常见的问题Koharu 启动失败、GPU 初始化错误回退 CPU、模型下载/加载问题以及 OCR 质量、翻译服务商、导出异常等疑难场景并教你用 debug 日志精准收集报错信息。 排查总原则先看启动界面、活动中心或弹窗里显示的确切错误信息在弄清是哪一层出问题之前不要删除项目数据或缓存。1️⃣ 启动失败快速排查Koharu 迟迟无法进入项目界面Koharu 的原生运行时会在项目浏览器可用之前完成初始化。首次启动时它会按需下载原生运行时包Torch、llama.cpp、diffusion 等因此首次启动明显更久是正常的。常见原因与排查步骤网络不可达启动下载依赖 GitHub 发布资源与 Hugging Face模型权重。请确认两者可访问并让活动中心里的下载完成下载进行中不要关闭窗口。驱动过旧关闭全部 Koharu 进程 → 更新 GPU 驱动 → 重启电脑。反复启动失败时按此顺序执行关闭所有 Koharu 进程更新显卡驱动并重启在稳定网络下重新启动捕获完整的初始化错误见第 7 节。配置文件被手动改坏设置保存在~/.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.md2️⃣ GPU 初始化错误与 CPU 回退诊断Koharu 在启动时探测硬件并只为整个 ML 栈选择一个共享设备优先级如下优先级加速后端适用平台前置条件1MetalApple 芯片 macOS系统自带2CUDA 13.0Windows / LinuxNVIDIAR580 或更新驱动Turing 及以上架构3ROCm/HIPWindows / LinuxAMD安装 ROCm Core SDK with HIP4VulkanWindows / Linux可用的 Vulkan 设备5CPU全部无需 GPU SDK速度明显更慢检测到 GPU ≠ 一定能用即使发现显卡也需要兼容的驱动 对应运行时包。如果任何一条加速路径不可用回退到 CPU 是预期行为——Koharu 在此场景下优先保证正确性而非速度。确认当前实际使用的后端打开编辑器内的资源监控Resource Monitor查看计算利用率与模型驻留状态检查启动日志中被选中的 backend用第 7 节的方法开 debug 日志。其他 GPU 相关注意点画布也吃显卡编辑器画布使用 WebGPU内嵌 CEF webview即使 ML 推理回退到 CPU也需要可用的 WebGPU 适配器和较新的图形驱动N 卡只需安装最新 NVIDIA 驱动不需要完整 CUDA SDKA 卡按你的操作系统安装 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 点比盲目调参数更有效确认页面方向正确、内容可读检查检测是否生成了正确的文本区域检测框是否覆盖文字在多页样本上保守地调整阈值检测文本/气泡/面板阈值位于Settings → Pipeline日文原稿可尝试漫画专用 OCR 模型手动更正识别出的源文本后再重跑翻译。 判断技巧不要用翻译输出质量来反推 OCR 是否读对了原文两者是独立环节。5️⃣ AI 修补Inpainting弄坏画面的处理使用更小的手动 Remove 遮罩避开气泡边框和线条稿先试直接的修补模型再考虑更重的生成式模型把手动修图保留在独立的手绘光栅层上这样重跑 inpainting 不会覆盖你的修图成果。6️⃣ 翻译服务商失败与 Agent 登录问题服务商报错打开Settings → Providers逐项核对凭据、base URL 与服务商专属字段然后刷新模型选择器。OpenAI 兼容服务需确认 chat 端点正确且仅当所选模型支持图片消息时才开启Settings → Translation → Vision inputAgent 无法登录/运行同一时间只允许一个设备登录或一个 Agent 请求——先取消现有尝试确认浏览器授权针对的是目标账户再重试。注意Agent 登录与 OpenAI 服务商凭据是两套独立体系凭据存放在操作系统的安全凭据服务中不在配置文件里无需手动处理。 相关源码各服务商实现位于 crates/koharu-translator/src/remote/Agent 位于 crates/koharu-agent/src/。7️⃣ 导出与画布不一致 收集 debug 日志导出结果和画布对不上PNG 与 PSD 导出都基于与画布相同的保留帧有意义的差异属于 Bug而非另一种渲染模式。报告时请记录项目 revision、页码、输出格式并附上两边截图。收集 debug 日志三平台命令调试日志能显示问题发生前 Koharu 正在做什么。必须从终端启动才会生效先完全关闭所有 Koharu 窗口系统命令macOSRUST_LOGdebug koharu若提示 command not found改用RUST_LOGdebug /Applications/koharu.app/Contents/MacOS/koharuLinuxRUST_LOGdebug koharu备用路径/usr/bin/koharuWindows PowerShell$env:RUST_LOGdebug; koharu.exe把日志存到文件长日志贴文件比截图更有用RUST_LOGdebug koharu 21 | tee $HOME/koharu-debug.log$env:RUST_LOGdebug; koharu.exe *1 | Tee-Object -FilePath $HOME\koharu-debug.log分享前注意搜索并替换掉 API 密钥、凭据、私有文件名与页面文字用[removed]占位保留周边报错行附上操作系统、Koharu 版本、操作目标、复现步骤和日志中的大致时间。✅ 故障排查总结清单症状第一步关键检查点启动卡住等待下载完成GitHub / Hugging Face 可达性、驱动版本回退 CPU看资源监控驱动 运行时包是否齐备属预期行为模型下载失败原样重试一次代理/杀毒拦截、磁盘空间OCR 差检查检测区域页面方向、多页调阈值、换漫画专用模型修补毁图缩小遮罩避开气泡边框/线条稿服务商报错核对凭据与 URL模型选择器是否已刷新导出异常记录 revision 与格式大概率是 Bug准备完整日志更多细节请阅读官方故障排除文档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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考