kotaemon 故障排查手册：安装到聊天 5 个高频坑的自查与修复方法

kotaemon 故障排查手册安装到聊天 5 个高频坑的自查与修复方法【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon用 kotaemon 时启动失败、模型连不上、聊天没动静先别急着重装。本文是一份 kotaemon 故障排查指南先看症状速查表定位问题再按「怎么判断 → 怎么修 → 怎么验证」逐步处理把修复过程讲透。症状速查表遇到卡点时先在这里对号入座10 秒定位症状表现最可能原因对应章节启动脚本报 ModuleNotFoundErrorPython 版本低于 3.10 或依赖没装全4.1提示 Invalid API key 或聊天直接报错API 密钥没生效或未设默认模型4.2本地模型报 Model not found / CUDA OOMLOCAL_MODEL 路径错误或模型超内存4.3Upload and Index 后进度卡住文件超大小/页数限制或同名文件被跳过4.4发送后 Thinking… 一直转未选文件、推理模式过重或模型连不通4.5回答与文档内容不符、引用分数低检索范围没选对文档或检索设置不当4.6先懂原理一句话看懂提问链路排查前要知道问题卡在哪一环。你问一句话后kotaemon 依次做四件事从你上传的文档里检索相关内容就像图书馆按关键词找书→把问题和相关片段一起交给 LLM大语言模型负责读材料写答案→生成回答并标注引用。所以没回答可能是模型这一环没连通答非所问多半是检索这一环没找对文档。分清了环节下面的坑就只是在哪一环出了问题。五大高频坑现象、判断与修复4.1 启动脚本报错或无响应现象运行启动脚本后终端报ModuleNotFoundError或浏览器打不开页面。怎么判断在终端执行python --version。README 要求 Python ≥ 3.10低于这个版本依赖装不全。解决换 3.10 后按 README 用 uv 重建环境uv sync --python 3.10 python app.py确认已修复浏览器自动打开页面默认账号密码均为admin能登录成功。4.2 模型连接失败Invalid API key现象界面提示 Invalid API key或 Resources 里模型列表是空的。怎么判断注意一个易踩的点——项目根目录的.env只在第一次启动时用来预填模型配置之后不再读取。所以改.env不生效很正常要去界面上改。解决进 Resources 选项卡 → LLMs → Add填入供应商、模型和 API 密钥并勾选设为默认嵌入模型把文字变成一串数字以便按意思搜索在 Embedding Models 里同样操作步骤见 docs/usage.md。确认已修复回到 Chat 问一句简单问题能流式吐字即连通。4.3 本地模型加载失败现象提示 Model not found或 CUDA out of memory。怎么判断前者多半是路径问题Windows 要用绝对路径右键文件选 Copy as Path后者对照内存——模型文件要小于可用内存 − 约 2GB比如 16GB 内存最多选约 10GB 的模型。解决在.env里把LOCAL_MODEL指向正确的 GGUF 文件绝对路径或换一个更小的模型如 2GB 的 Qwen1.5-1.8BOllama 方式详见 docs/local_model.md。确认已修复Resources → LLMs 列表里出现你的本地模型设为默认后提问有回复。4.4 文件上传后索引卡住现象点 Upload and Index 后进度不动。怎么判断对照三条限制——单文件 ≤10MB、单文件 ≤500 页、最多 100 个文件另外同名文件默认跳过不重新索引除非勾选 Force re-index。右上角通知会提示开始、完成或出错。解决超限的文档拆分已存在但内容变了就勾选强制重新索引再上传文件集合用哪个嵌入模型在 File Index 页为 Collection 指定。确认已修复文件列表里出现该文件且页数显示正常。4.5 发送后 Thinking… 一直转现象消息发出去转圈不出字。怎么判断先看聊天面板的文件索引选择——选了 Disabled 或 Select 但没勾文件等于没给模型任何材料再看推理模式决定模型分几步思考的策略ReWOO 等 agent 模式步骤多、明显更慢本地小模型上可能久到像死机。解决把文件选择改为 Search All 或勾上目标文档在 Settings 里把推理类型换回 Simple仍无反应就新建一个对话排除历史上下文干扰。确认已修复右侧信息面板开始显示检索到的证据回答逐字流式出现。4.6 引用内容不相关、分数低现象回答跑题信息面板里引用分数偏低。怎么判断信息面板会给出答案置信度和证据相关分数其中 LLM relevant score 最可靠其次是 Reranking score再是 Vectorstore score。分数普遍低说明检索阶段就没找对段落——多半是检索范围没限对文档。解决在聊天面板用 Select 只勾选目标文档再进 Retrieval settings 调检索参数如关掉本机带不动的 LLM 相关性打分。确认已修复同一问题重问引用分数回升PDF 预览里能高亮看到被引用的原文。自助诊断工具箱三件不用求助别人也能做的事按顺序做一遍1. 日志与数据在哪应用运行输出直接看启动终端上线部署HF Space则重点看构建日志的 Installing dependencies 阶段所有用户数据数据库、文件、向量库都集中在ktem_app_data目录该目录完好性直接影响功能2. 该查哪些配置文件flowsettings.py应用主配置含推理管线、文档库/向量库选型根目录.env模型密钥记住它只在首次启动时生效settings.yaml.example高级用户的配置模板3. 环境与版本自检python --version输出 ≥ 3.10环境内pip show kotaemon与pip show ktem均有结果能访问模型服务API 用户可先在别处用同一把密钥请求一次用admin/admin能登录确认不是账号问题官方求助渠道自查走不通时按这个顺序求助效率最高Issues 反馈在仓库 Issues 板块提交README 里的 Feedback 入口指向的就是它使用文档docs/usage.md模型与文档上传、docs/local_model.md本地模型、docs/online_install.md在线部署重新安装兜底确认以上都无效时可彻底重装最新代码git clone https://gitcode.com/GitHub_Trending/kot/kotaemon cd kotaemon ./scripts/update_linux.sh提好 Issue 的小技巧附上完整终端日志、出问题页面的截图并注明你的操作系统、Python 版本和部署方式Docker 还是源码安装。信息给得越全维护者越容易复现修复也越快。排查完这些你的 kotaemon 应该已经能顺畅地读文档、答问题了。若某天又遇到新症状回到开头的速查表按链路分环节定位基本都能快速找回方向。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考