Kotaemon 文档聊天卡住了？5 个环节逐个排查，启动报错、模型连不上、引用不准都能修好

Kotaemon 文档聊天卡住了5 个环节逐个排查启动报错、模型连不上、引用不准都能修好【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon先别急kotaemon 的文档聊天八成是卡在这几个环节环境没装好、模型没接上、文档没喂进去。顺着这条链路逐节自查照着做基本就能跑通。先对号入座你看到的现象直接跳到终端报 ModuleNotFoundError或脚本刚跑就退出把 kotaemon 跑起来localhost:7860 打不开、页面空白把 kotaemon 跑起来Invalid API key / Authentication failed给模型接上电Model not found、CUDA out of memory给模型接上电上传进度条卡住、File too large把文档喂进去点了 Upload and Index 没反应把文档喂进去发完消息一直 Thinking 不出结果把对话调顺回答和上传的文档对不上把对话调顺改完还是不对想看更多细节看清问题卡在哪、终极手段把 kotaemon 跑起来启动脚本直接退出或报 ModuleNotFoundError官方要求 Python ≥ 3.10不过脚本会自己装 Miniconda基本不用你操心。别手动装依赖直接跑仓库自带的启动脚本它会建环境、装依赖、下载 PDF 渲染组件一条龙./scripts/run_linux.shmacOS 用 scripts/run_macos.shWindows 用 scripts/run_windows.bat。⚠️ 一个高频坑仓库所在路径里如果有空格脚本会直接拒绝运行把目录挪到无空格的路径再试。✅ 看到首启页面就算成了默认用户名密码都是 admin。在线部署 Space 卡在 Building 怎么办想省事的走在线部署按 docs/online_install.md 复制一个属于你自己的 Space改好参数等构建正常 10 分钟左右。卡住超过 15 分钟先看构建日志里 Installing dependencies 那一阶段是不是挂了反复失败的话回退本地部署更稳。这一步没问题的话下一个最常见的坑是模型没接上——文档问答的答案全靠它产出。给模型接上电API 密钥认证失败怎么办进 Resources 页签 → LLMs → Add填供应商和密钥。注意密钥只在首次启动时从根目录.env预填进数据库之后要改就得在界面上操作具体见 docs/usage.md 的 Add your AI models 一节。填完顺手把某个模型设为 default聊天时就不用每次挑。本地模型加载失败或显存不够⚠️ 选 GGUF 模型留点余量模型体积要小于可用内存、至少空出 2GB16GB 内存的机器装 10GB 以内比较稳新手建议从 2GB 量级如 Qwen1.5-1.8B试起。Windows 上右键文件选「复制文件地址」拿绝对路径填到.env的LOCAL_MODELDocker 部署时http://localhost要换成http://host.docker.internal。更省心的做法是走 Ollama完整步骤在 docs/local_model.md核心就三行参数api_key: ollama base_url: http://localhost:11434/v1/ model: gemma2:2bLLM/ nomic-embed-textEmbeddingEmbedding 模型别漏索引和检索都靠它漏了就是「能上传、不能问」。模型能跑了但喂给它的文档要是没处理好答案一样会跑偏。把文档喂进去上传卡在进度条或提示文件太大限制摆在这单文件 ≤ 10MB、≤ 500 页一次最多 100 个文件大 PDF 先拆开。PDF、HTML、XLSX、TXT、Markdown 开箱就能解析.doc/.docx 这类需要对应 loaderDocker 选 full 镜像或按 README 装 unstructured实在不行转成 PDF 再传。点了 Upload and Index 没反应先确认文件列表里有没有它同名文件默认跳过索引勾上 Force re-index 强制重建。再往下查 Embedding 模型——索引本质是算向量模型没配好这一步就是静默卡死。在 File Index 的集合设置里把 Embedding 指到本地模型如 ollama完整做法见 docs/local_model.md 的 Use local models for RAG 一节。文档进库之后才轮到真正聊起来。把对话调顺一直 Thinking 不出结果按顺序查先在 Resources 页签确认 LLM 状态正常再看会话左侧的文件选择——选成 Disabled 或不勾任何文件时上下文是空的模型只能干瞪眼还不行就把推理模式从 ReWOO / ReAct 这类 Agent 切回 Simple设置里 Reasoning optionsAgent 链路长先排除它最后新建一个对话重试太长的历史有时会拖垮上下文。回答和文档内容对不上先看右侧信息面板的分数Relevance score 很低说明检索本身没捞到相关段落别怪生成——去设置里调检索配上 Reranking 模型docs/usage.md 里有每个分数的含义。分数还行但答案还是偏多半是上下文混进了不相关文件回到文件选择只留目标文档。改完还是不对劲别再瞎试了先让它把底细露出来。看清问题卡在哪日志和数据都存在哪主日志就是python app.py的启动终端报错堆栈直接看那里界面右上角的通知条会弹出索引、检索的即时报错。所有应用数据SQLite 库、向量索引、上传文件都落在根目录的ktem_app_data里——排查前先确认这个目录没被删、磁盘没满。关键配置项在哪改flowsettings.py向量库/文档库选型KH_VECTORSTORE、KH_DOCSTORE、推理管线列表、数据目录改完重启生效根目录.env模型密钥仅首次启动预填数据库时用settings.yaml.example高级用户的配置模板libs/ktem/ktem/db/engine.py数据库连接怀疑库坏了可以从这里入手终极手段以上都试过还不行就彻底重装先把旧的ktem_app_data备份走想保留文档和对话就留它然后拉最新代码重装git clone https://gitcode.com/GitHub_Trending/kot/kotaemon cd kotaemon ./scripts/run_linux.sh装完还复现同样问题就去项目仓库提 Issue把终端日志、报错截图和你改过的配置一起贴上来也欢迎到 Discussions 板块搜一搜看看有没有人踩过同一块石头。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考