企业官网建设流程全解析

5步玩转 Kotaemon：把本地文档变成可对话的 AI 知识库

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

Kotaemon（kotaemon）是一个开源的 RAG 工具，核心能力就一句话：把你手头的 PDF、Word、网页等文档喂给它，然后用自然语言直接向文档提问，答案还会带上引用出处和置信度。这篇指南按真实使用顺序走一遍：装起来、接上模型、传文档、开聊，最后附上最常见的几个卡点怎么破 🐾

第一次启动：跑通一键安装脚本

官方为每个系统都准备了一键脚本，会自动装好 Miniconda、创建 Python 3.10 环境、拉依赖并打开浏览器：

• Linux：终端执行bash scripts/run_linux.sh
• macOS：双击scripts/run_macos.sh
• Windows：双击scripts/run_windows.bat

装完后浏览器会自动打开，首次登录用默认账号admin / admin，登录后建议立刻改成自己的密码：

两个高频坑先提醒一下：

1. 目录路径里不能有空格。Linux 脚本开头就会检查路径，带空格会直接退出，把项目挪到类似/data/web/kotaemon这种干净路径下再跑。
2. 报 ModuleNotFoundError 之类的依赖错误，说明安装中途被中断过。删掉项目下的install_dir/env环境目录后重新跑一遍脚本即可；脚本会自动重建环境并重新安装libs/kotaemon和libs/ktem两个本地包。

之后每次想启动，重跑对应run_*.sh（或.bat）就行，浏览器会再次自动打开。

接入 AI 模型：云端 API 和本地模型任选

打开顶部的Resources标签页，这里分 LLMs 和 Embedding Models 两个子标签，至少要各配一个模型应用才能正常工作（推荐把你手上有的都加上，聊天时可以随时切换）。流程是：Add → 起个名字 → 选提供商（如ChatOpenAI）→ 填密钥等参数 → 保存。

用云端 API 的话，密钥别手抖敲错：OpenAI 的 key 以sk-开头，Cohere 的以co-开头，界面里也提供了在线注册入口：

不想把文档传到云端？本地路线有三条：Ollama（最省事）、text-generation-webui、以及项目自带的 llama.cpp 服务。以 Ollama 为例：

1. 装好 Ollama 后拉两个模型：一个对话、一个嵌入，例如ollama pull llama3.1:8b和ollama pull nomic-embed-text；
2. 在 Resources 面板里以 OpenAI 兼容类型接入：base_url填http://localhost:11434/v1/，api_key填ollama，model分别填你拉的模型名：

如果走的是 GGUF 单文件路线，就在项目根目录的.env里写一行LOCAL_MODEL=<模型文件绝对路径>，然后用LOCAL_MODEL=<路径> python scripts/serve_local.py起服务，同样以 OpenAI 兼容方式在 8000 端口接入。选模型时掂量下内存：模型大小要小于设备可用内存并预留约 2GB——16GB 内存的机器跑 10GB 以内的比较稳。最后一步别忘：把默认的 LLM、默认嵌入模型都指到本地变体上，方法见 docs/local_model.md。

上传文档：三条限制先记住

进入File Index标签页，把文件拖进上传区，点Upload and Index就开始解析建索引了：

上传前先对一下这三条限制（文档里有硬性校验）：

超了怎么办？大 PDF 拆成几个小文件分批传；格式不支持就先转成 PDF 再传。另外注意一个细节：同名文件再次上传时默认会跳过索引，如果你改过文档内容，记得勾上强制重新索引的选项，否则聊天时用的还是旧版本。

开始对话：选对上下文，看明白评分

回到Chat标签页。发送前先看左侧的文件范围选择：Disabled完全不引用文档、Search All全部文件参与检索、Select只圈定你勾的几个文件。答案不贴题时，第一步永远是检查这里。

提问后模型会先进入 "Thinking..." 状态，右侧信息面板会实时列出检索到的证据段落和几个分数：答案置信度、向量相似度分、LLM 相关性分、重排分等。判断检索质量时，LLM 相关性分一般比纯向量分更靠谱，整体相关性默认就取它。

如果引用内容明显不相关，按这个顺序调整：先确认文件范围勾选正确；再进设置里的 Retrieval 选项，把 LLM 相关性打分模型选上（机器带不动太多并发 LLM 请求时可以关掉该功能）：

更多参数含义说明在 docs/usage.md 和 docs/pages/app/functional-description.md。

卡住了怎么查：一份快速排障清单

😌 遇到异常别慌，八成是下面五件事之一，从上往下过：

1. 密钥或网络：聊天报认证错误、连接失败，先回 Resources 页核对 API key 与base_url；
2. 换轻量推理模式：复杂推理模式下响应特别慢甚至卡死时，到设置里把推理类型切到Simple试试；
3. 历史会话干扰：删掉当前对话、点 New 新建一个再问一次；
4. 配置与数据落点：用户级配置模板参考 settings.yaml.example，开发者级设置声明在 flowsettings.py，数据库连接在 libs/ktem/db/engine.py 里，改动前先备份；
5. 看现场：终端里run_*脚本的滚动输出是第一手信息，install_dir目录下也有运行日志可以翻。

彻底搞不定时，重新克隆仓库再跑一遍更新脚本（如scripts/update_linux.sh）是最干脆的"核选项"；仍不行就在项目仓库的 Issues 区提交完整日志和截图，附 docs/ 里的功能说明会方便维护者定位 ⚡

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