企业官网建设流程全解析

kotaemon 从零到对话：本地部署、接模型、传文档、问出答案的完整上手路径

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

kotaemon 是一个开源的 RAG 文档问答工具（RAG 即：先检索文档里相关的内容，再交给大模型基于这些内容作答）。装好到问出问题，一共四步：跑起来、接模型、传文档、开聊。本文按你第一次打开它的真实时间线走一遍，每一步告诉你屏幕上该看到什么、该点哪里、哪里最容易卡住。

🚀 先让 kotaemon 跑起来

把仓库拉到本地（没有的话）：

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

Linux / macOS 用户不用手动折腾依赖，仓库自带一键安装脚本 scripts/run_linux.sh，macOS 对应 scripts/run_macos.sh，Windows 用 scripts/run_windows.bat。以 Linux 为例，运行bash scripts/run_linux.sh后它会依次做三件事：装好 Conda 环境（Python 3.10）、安装 kotaemon 与 ktem 两个库、下载浏览器内 PDF 预览组件，然后自动打开浏览器。

启动成功后这一屏你会看到：http://localhost:7860上出现登录页，用户名密码都是admin。登录进去就是 Chat 页——这就是 kotaemon 文档问答的主界面。

⚠️ 最容易踩的坑：仓库路径里不能有空格，安装脚本检测到会直接退出；另外项目要求 Python ≥ 3.10，别用系统自带的 3.8。想省事也可以直接拉官方 Docker 镜像（README.md 有完整命令，注意把镜像 tag 改成main-lite或main-full才存在）。

🧠 给 kotaemon 接上大脑：LLM 和嵌入模型

登录后的第一屏就是 Chat 页，但此刻它还不会答——点右上角的Resources标签页，你会看到 LLMs 和 Embedding Models 两个列表，都是空的。这一屏的作用是把"嘴"和"耳朵"装给 kotaemon：

• LLM（大语言模型）：负责生成回答。
• 嵌入模型（Embedding）：把文档切成小块并转成向量存起来，检索时用它按相似度找相关段落——没有它，上传的文档等于没传。

用 API 的接法：Resources → LLMs → Add，起个名字，选厂商（如 ChatOpenAI），填入 API 密钥（OpenAI 的密钥以sk-开头），保存并勾选设为默认。然后到 Embedding Models 子页，用同样的步骤再加一个嵌入模型。

用本地模型的接法：文档推荐 Ollama。终端先拉模型：ollama pull llama3.1:8b（LLM）和ollama pull nomic-embed-text（嵌入），然后在 Resources 里各加一条，type 都选 OpenAI，base_url填http://localhost:11434/v1/，api_key随便填（本地服务不校验）。如果坚持用 GGUF 权重本地跑，把模型文件路径写进项目根目录.env的LOCAL_MODEL变量即可，完整步骤见 docs/local_model.md。

⚠️ 最容易踩的坑：本地模型要选内存装得下的。官方经验值是"模型大小 ≤ 可用内存 − 2 GB"，16 GB 的机器配 8B 级别（约 5 GB 起）比较稳，别贪大。

📄 上传并索引第一份文档

模型接好后，切到File Index标签页。这一屏分上下两块：上面是上传区（拖拽或选择文件），下面是已上传文件列表。

操作只有两步：拖入一个 PDF，点Upload and Index。然后等——应用会解析、切块、向量化并写入向量库，文件多、模型慢时进度条会走一阵子，处理完成会有提示。

⚠️ 最容易踩的坑：内置 loader 原生只覆盖.pdf、.html、.mhtml、.xlsx这几类，要处理.docx等其他格式，需要额外安装 Unstructured（README.md 的 System requirements 一节有说明）。

💬 向文档提问，并调出好答案

回到Chat页，开始问之前先看左侧的检索开关——这是新手漏掉的第一件事：

• Disabled：纯靠 LLM 自己的知识回答，不查你上传的文档；
• Search All：所有已索引文件都参与检索；
• Select：手动勾选本次要参考的文件。

不选任何文件时，回答不会引用你的文档。确认勾好之后直接提问，右侧信息面板会给出：检索到的证据段落、答案中的直接引用高亮，以及几类分数（Answer confidence、Relevance score、Vectorstore score 等）。分数很低，基本意味着检索没命中，而不是 LLM 胡说。

觉得答案不理想时，进 Settings → Retrieval settings 调 检索设置：可以换文件加载器、开关 LLM 相关度打分、配置重排序模型。

🔍 卡住了：按这条路径自查

1. 先看启动终端：python app.py所在终端打印的就是运行时日志，报错基本都在这里。
2. 再看数据目录：./ktem_app_data存放全部应用数据（文件、索引、配置），备份或迁移机器时整份拷走即可。
3. 配置从两个文件查起：flowsettings.py 控制应用行为（文档库、向量库、推理管线等），根目录.env控制模型凭据（OPENAI_API_KEY、LOCAL_MODEL等）。
4. 推倒重来：删掉.venv和ktem_app_data，重跑一次 scripts/run_linux.sh。注意仓库本身只读，重装只针对环境和数据，不动仓库代码。

验收动作：新建一个会话，把左侧文件选择指向你刚上传的文档，问一个只有那份文档才答得上来的问题。回答中出现指向文档段落的高亮引用、右侧面板能看到证据和相关度分数——这条链路就通了。

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