kotaemon 文档问答报错修复指南本地部署后 4 步自查定位法【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemonkotaemon 是一个开源的本地部署文档问答RAG工具让你在浏览器里直接和自己上传的 PDF、网页对话。本文整理仓库里真实出现过的报错信息帮你在新手阶段几分钟内自查并修复装不上、连不上模型、索引失败这三类问题。一、30 秒快速自查先把最容易踩的 6 个基础项过一遍多数一启动就卡住的情况在这一步就能定位。检查项怎么查正常标准Python 版本python --version≥ 3.10安装脚本固定用 3.10 建环境依赖安装pip list能同时看到kotaemon和ktem两条记录仓库路径看终端里的当前目录路径中不含空格.env文件仓库根目录是否存在.env存在注意它只在首次运行时用于初始化数据库模型密钥UI 的 Resources 页签至少一个 LLM 和一个 Embedding 模型已填好 key 并保存服务端口浏览器访问http://localhost:7860/页面能打开出现登录界面启动成功后默认账号密码都是admin建议第一次登录后立刻改密码。二、按报错信息定位启动脚本提示 The current workdir has whitespace可能原因你把仓库放在了带空格的路径下比如某些系统的Program Files目录安装脚本会主动拒绝继续。修复步骤把整个 kotaemon 目录移动到不含空格的路径下。在新路径下重新执行启动脚本命令见第四节。修复后验证脚本不再立刻退出而是继续打印 Setting up Miniconda 并往下走。聊天时报No models in pool可能原因资源池Resources里一个模型都没加或者加了但没设为默认LLM 和 Embedding 两类模型都要有。修复步骤进入 Resources 页签 → LLMs → Add填名称、选供应商如ChatOpenAI并填参数。切到 Embedding Models 子页签同样方式加一个嵌入模型。把各一个模型标记为 default。修复后验证回到 Chat 页签重新提问不再报这个错回答开始逐字流式输出。模型添加的完整字段说明见 docs/usage.md。提示Model not found或Failed to add model可能原因界面上模型名字填错或前后有空格或该模型之前已被你从池里删除。修复步骤在 Resources 页签检查现有列表删掉名字不对的条目。按上一条的步骤重新 Add 一遍并保存。修复后验证保存不报错且该模型能出现在下拉列表里并设为默认。本地模型Ollama连接失败可能原因Ollama 没在运行base_url写错在 Docker 容器里仍然写了localhost。修复步骤在宿主机执行ollama pull llama3.1:8b并确认 Ollama 已启动。在 Resources 页签按 OpenAI 类型添加模型api_key填ollamabase_url填http://localhost:11434/v1/。如果你用 Docker 跑 kotaemon把base_url里的localhost换成host.docker.internal。修复后验证Chat 里发一条消息回答正常流式返回不再卡住。完整配置见 docs/local_model.md。聊天一直停在 Thinking... 不回复可能原因默认 LLM 的密钥或地址失效或选了一个太慢的本地大模型。修复步骤到 Resources 页签确认默认 LLM 的 key、base_url都有效。把默认模型换一个小一号的模型或在设置里把推理类型换成更轻量的 Simple 管道。修复后验证Thinking... 占位符消失右侧信息面板开始显示检索到的证据和分数。文件上传 / 索引不工作可能原因文件超过限制或上传了应用原生不支持的格式处理.pdf、.html、.mhtml、.xlsx以外的文件需要额外安装unstructured组件。修复步骤对照限制拆分文件单个文件 ≤ 10 MB单文件 ≤ 500 页单次上传 ≤ 100 个文件。只上传上面列出的支持格式其余格式先转成 PDF。重新点击 Upload and Index关注右上角的进度与错误通知。修复后验证文件出现在 File 页签列表里并收到索引完成的通知。上传与索引规则详见 docs/pages/app/functional-description.md。安装脚本类报错基本都属于环境问题合并看这张表错误信息常见原因一行修复动作Installation failed. You may need to run the installer again.依赖安装中断或失败重新执行bash scripts/run_linux.shConda environment appears to be brokenconda 环境创建时被中断删除install_dir/env目录后重跑脚本Unknown system architecture系统不是 x86_64 或 arm64改用仓库提供的 Docker 镜像部署Conda not found. Will exit now...Miniconda 下载或安装失败检查网络后重跑脚本三、深入排查前面都对上但还是不对时按这个顺序核对。数据目录所有应用数据都存放在根目录的ktem_app_data/下由flowsettings.py的KH_APP_DATA_DIR指定。备份或复制这个文件夹即可把整套安装迁移到新机器。配置核对清单flowsettings.pyKH_DOCSTORE默认 LanceDB、KH_VECTORSTORE默认 Chroma、KH_DATABASEsqlite位于ktem_app_data/user_data/sql.db.env只在首次运行时读入数据库之后改密钥必须走 UIsettings.yaml.example高级配置模板。内存判断标准本地 GGUF 模型的大小要小于你可用内存并留出约 2 GB。例如总内存 16 GB、可用 12 GB就选最多占 10 GB 的模型。分数怎么看信息面板里的 Answer confidence 是模型自评LLM relevant score 是证据与问题的相关度一般 LLM 分 Reranking 分 向量分分很低说明检索没取到对的内容去检索设置里调整重排与打分模型。日志在哪看本地部署时python app.py所在终端就是主日志报错堆栈都在那里HuggingFace Space 部署则看 Space 页面上的构建日志正常构建约 10 分钟。四、兜底操作与求助重跑安装脚本它同时就是启动入口Linux 执行bash scripts/run_linux.shmacOS 用scripts/run_macos.shWindows 双击scripts/run_windows.bat升级用scripts/update_linux.sh系列脚本。确认是配置乱了而不是数据坏了可以删掉ktem_app_data/目录再首次启动应用会自动重建该目录并用.env重新初始化——但你的文件和对话会一并清空先备份。还是解决不了把终端里的完整报错堆栈和截图贴到项目仓库的 Issue 里反馈入口说明见 docs/index.md 的 Feedback 一节。想在线部署而不是本地跑跟着 docs/online_install.md 复制一个自己的 Space 即可。排障的顺序永远是先自查表、再对报错、最后才动数据目录——多数问题到第二步就已经解决了。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考