kotaemon 文档问答：从克隆到第一次回答的避坑笔记

kotaemon 文档问答：从克隆到第一次回答的避坑笔记

【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon

kotaemon 是一个开源的 RAG 文档问答工具：把 PDF、文本这些私有文档喂进去，就能在浏览器里直接对它们提问，回答带引用、带置信度评分。从git clone到问出第一个靠谱答案，中间最容易卡住的是三件事：环境起不来、模型连不上、检索答非所问。这篇笔记按你实际操作的顺序把这条路走一遍，每个节点把实际跑下来踩过的坑直接标出来，不用翻文档逐页查。

🚀 3 分钟把服务跑起来

先克隆代码，然后用仓库自带的启动脚本：

git clone https://gitcode.com/GitHub_Trending/kot/kotaemon cd kotaemon ./scripts/run_linux.sh

Linux 用scripts/run_linux.sh，macOS 用run_macos.sh，Windows 用run_windows.bat。脚本会自己装 Miniconda、创建 Python 3.10 的 conda 环境、装好libs/kotaemon和libs/ktem两个核心包，最后拉起 Web UI。你不用手动装任何依赖，这也是它比手搓pip install省心的地方——版本冲突基本被脚本隔离掉了。

这里有个坑：Linux 版脚本会拒绝在含空格的路径下运行。如果你把仓库放在My Projects这类目录里，脚本直接退出且不报明显错误，看着就像"无响应"。把仓库挪到一个无空格路径再跑就行。

启动成功后打开浏览器，会看到登录与初始设置界面：

不想装 Python 环境的可以走 Docker：拉 lite 或 full 镜像、映射 7860 端口即可，full 版额外装了 unstructured，能处理.docx这类格式；lite 版默认只支持.pdf、.html、.xlsx等少数类型。

给问答接上"大脑"：模型配置

服务起来后第一件事是配模型。进Resources标签页，分别添加一个 LLM 和一个 Embedding 模型，然后点连接——页面上有实时日志，密钥错了会直接显示Invalid API key，不用等聊天时报错再回头查。API 密钥的格式问题是最常见失败原因：OpenAI 的以sk-开头，Cohere 的以cohere-开头，多一个空格都过不去。

想做本地 RAG 部署，推荐用 Ollama，它对 kotaemon 来说就是一个 OpenAI 兼容端点：

ollama pull llama3.1:8b ollama pull nomic-embed-text

然后在 Resources 里把两个模型都建成 OpenAI 类型：base_url填http://localhost:11434/v1/，api_key随便填个占位值，模型名填 Ollama 里的准确名称。说白了， kotaemon 不认"Ollama"这个类型，它只认端点和模型名，填错了会报Model not found，先核对名称再怀疑服务。

没有 Ollama、手头只有一个 GGUF 文件的话，仓库带了现成的 llama-cpp 服务脚本：用LOCAL_MODEL=<模型绝对路径> python scripts/serve_local.py起服务，Resources 里base_url指向http://localhost:8000/v1/即可。Windows 上记得用绝对路径，相对路径会直接加载失败。更多本地模型方案（text-generation-webui 等）见 docs/local_model.md。

配完之后记得把本地模型设为默认 LLM 和默认 Embedding 模型，否则新建的索引还会去调 API。

上传文件：索引阶段的两个高频坑

切到File Index标签页，拖入文件后点Upload and Index。这一步看着简单，实际有两处容易卡住。

第一处是格式限制。索引管道按扩展名分发解析器，.pdf、.txt开箱即用；.docx、.xlsx之外的格式依赖 unstructured 库，裸装环境没带它，上传后进度条会卡死而不是报错。转换格式最简单的办法是导出成 PDF 再传，比补装依赖快。

第二处是限制配置。File Index 的设置面板里有max_file_size（单位 MB）和max_number_of_files两项，默认上限很宽松，但如果你部署时改过小，超出限制的文件会被静默跳过。想放开就调大数值，填 0 表示不限制。同理，chunk_size设 0 是走开发者默认值，不用自己猜分块大小。

索引完成后文件会出现在下方列表里，可以随时删除重建。如果某份文件索引完却检索不到，先确认它的 Embedding 模型和你现在用的默认 Embedding 模型一致——换过模型后旧索引的向量是不兼容的，需要重新索引。

第一次问答：让回答可信

回到Chat标签页，聊天区分三块：左侧是会话和文件选择，中间是对话，右侧是信息面板。发第一个问题前，先看左侧的文件索引选择：Disabled表示完全不检索（纯靠 LLM 裸答），Search All检索全部文件，Select手动勾选。回答"对不上文档"这个高频问题，八成是这里没勾中目标文档。

发问后如果卡在Thinking...，先看右侧信息面板而不是干等。面板会给出四类分数：答案置信度、整体相关度、向量库分数、LLM 相关度评分。分数偏低且相关证据为空，说明是检索没捞到东西，往回查文件选择和索引；分数正常但回答跑偏，那是生成端的问题，换个推理类型再试。复杂推理默认可能走 ReWOO 这类 agent 链路，多跳规划会放大延迟和失败率，日常单文档问答直接切Settings → Simple模式最稳，省下的 token 和延迟都很可观。

⚙️ 进阶：调好检索质量再谈体验

模型和流程通了之后，回答质量的天花板主要在检索设置里。进Settings → Retrieval，最值得动的两个开关：

一是LLM 相关度评分：用一个 LLM 给检索到的证据逐条打相关分，排序质量比纯向量相似度好一截，代价是每轮问答多一批并行的 LLM 请求。机器带得动就开，带不动就关掉或换个小模型，官方文档里专门提了这一点。二是重排序模型（如 Cohere rerank），它给出的 Reranking score 是四类分数里仅次于 LLM 评分的质量指标，开上之后低相关证据会被压下去。

分块参数也可以在这附近微调：chunk_size决定每段文本的 token 数，文档以长段落为主就调大，以短条目为主就调小。改完记得对已索引文件重新索引才生效。

🩹 快速排障速查表

延伸资源

• 功能总览与完整使用流程：docs/usage.md
• 本地 LLM 与 Embedding 模型全方案：docs/local_model.md
• 不想装本地环境的在线部署指南：docs/online_install.md
• 想基于自己的 RAG 管道定制 UI：看核心库 libs/kotaemon/ 的说明与libs/kotaemon/tests/simple_pipeline.py的最小管道示例

还卡着？别再自己耗了——打开ktem_app_data下的app.log，把最后 50 行连同你的 Python 版本号一起贴到项目 Issue，标题直接写清楚"哪一步、什么现象"，这比十句描述都管用。

【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon