企业官网建设流程全解析

Kotaemon文档问答快速部署：启动、模型、索引与验证四步走

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

Kotaemon 是一个开源的 RAG 文档问答工具，让你在自己的机器上上传 PDF、Office 等文档，然后用 LLM 与之对话并获得带引用的回答。本文按实际使用顺序组织内容：先确认环境能启动，再接入模型，然后上传文档，最后验证问答质量；每一步都给出可核对的检查项与关键路径。

启动前：确认运行环境与安装方式

先确定用哪种方式部署，再核对启动后的登录信息。

方式一：源码脚本安装（适合本地开发）

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

• 脚本安装：Linux 执行 scripts/run_linux.sh，macOS 执行 scripts/run_macos.sh，Windows 执行 scripts/run_windows.bat。脚本会安装 Miniconda（Python 3.10）、依赖与 PDF.js 浏览器插件。
• 手动安装：uv sync --python 3.10创建环境，然后python app.py启动服务。

方式二：Docker 安装

• 使用ghcr.io/cinnamon/kotaemon:main-lite（通用）或main-full（需要处理 .doc/.docx 等更多格式），将-p 7860:7860映射端口，并用-v ./ktem_app_data:/app/ktem_app_data挂载数据目录。

启动后核对三件事：

1. 浏览器访问http://localhost:7860/能打开 WebUI；
2. 默认用户名与密码均为admin，可在界面内追加新用户；
3. 项目根目录出现ktem_app_data文件夹——之后所有文件、索引与数据库都存放在这里，备份或迁移机器时只需拷贝这个目录。

注意：项目根目录的.env文件只在首次启动时用于预填模型配置，后续改动请直接在 WebUI 中设置。

接入模型：为问答管道准备 LLM 与 Embedding

Kotaemon 的问答依赖两类模型：负责生成回答的 LLM 和负责文档向量化检索的 Embedding。至少需要各配置一个。

通过 Resources 界面添加

1. 进入Resources选项卡，在LLMs子页签选择Add；
2. 填写名称、选择供应商（如ChatOpenAI）、填入 API 密钥与模型名，可勾选设为默认；
3. 切到Embedding Models子页签重复上述操作。

配置本地模型实现私有 RAG

如果文档敏感，不希望数据出内网，可接入本地模型，详见 docs/local_model.md：

• Ollama 方式（推荐）：先执行ollama pull llama3.1:8b与ollama pull nomic-embed-text，再在 Resources 中以 OpenAI 类型添加，参数为api_key: ollama、base_url: http://localhost:11434/v1/；Docker 部署时把localhost换成host.docker.internal。
• GGUF 权重方式：下载 GGUF 模型后运行LOCAL_MODEL=<path/to/GGUF> python scripts/serve_local.py，在界面中以base_url: http://localhost:8000/v1/接入。

选择 GGUF 权重时，模型体积应小于设备内存并预留约 2GB。例如 16GB 内存的机器，建议选用 10GB 以内的模型。

接入本地模型后还要完成两处联动设置：将 File Collection 的嵌入模型设为本地模型，并在检索设置中把 LLM 相关性打分模型改为本地模型（机器负载高时可关闭该打分功能）。

处理文档：上传并确认索引生效

问答的质量取决于文档是否被正确索引。打开File Index选项卡，页面分为上传区和文件列表两部分。

上传操作与核对要点：

• 将文件拖入上传区（或点击选择），点击Upload and Index；处理完成后界面会给出通知，此时文件才真正可用于检索。
• 上传前核对三个限制：单文件不超过 10MB、单文件不超过 500 页、最多 100 个文件。
• 重新上传同名文件时，注意“Force re-index”选项：开启才会重建索引，关闭则跳过已存在的文件。
• 完成后在文件列表核对文件名、大小、页数与上传日期；列表下方还会汇总总页数与总大小。

如果某个文件上传后无法被检索引用，优先重新执行一次强制重新索引，并确认该文件使用的嵌入模型与当前默认模型一致——更换嵌入模型后旧索引会失效。

验证问答：检查检索结果与引用质量

切回Chat选项卡，界面由三块组成：左侧会话设置面板、中间对话区、右侧信息面板。验证时按以下顺序检查：

1. 文件范围：会话面板中可设Disabled（不使用任何文档）、Search All（全部文件参与检索）或Select（仅勾选指定文件）。回答偏离预期时，先确认这里勾选的是目标文档。
2. 发送测试问题：处理过程中会显示 "Thinking..."，随后开始流式输出回答。
3. 查看信息面板：右侧展示检索到的证据与引用，引用位置在浏览器内 PDF 查看器中会高亮显示；面板同时给出多个分数用于判断质量。

面板中的分数含义：

相关度排序为LLM relevant score > Reranking score > Vectorstore score，默认整体相关度直接取 LLM 评分。若相关度普遍偏低，说明检索质量不佳，可进入Settings → Retrieval Settings调整检索与打分模型；仍不理想时，可在推理类型中从默认管道切换为分解式或 Agent 管道（ReAct / ReWOO），以支持多跳问题。

排障入口：数据目录、配置文件与关键路径

当界面表现异常时，按下面的路径逐项定位，而不是从头重装：

常见定位思路：模型连接失败 → 回 Resources 选项卡核对密钥与 base_url；索引无结果 → 检查 docstore/vectorstore 目录是否有数据、嵌入模型是否更换过；行为不符合预期 → 检查flowsettings.py中启用的推理管道与存储类型。更多背景可参考 docs/usage.md 与 docs/pages/app/settings/overview.md。

下一步：完整检查清单

• http://localhost:7860/可打开，admin/admin能登录
• Resources 中至少各有一个可用的 LLM 与 Embedding 模型，且默认模型已勾选
• 本地模型场景：Ollama 或 llama-cpp 服务正在运行，base_url 与内存规格匹配
• File Index 中目标文件显示正常页数，且已完成一次（强制）索引
• Chat 中文件范围选中目标文档，信息面板相关度分数符合预期
• ktem_app_data可正常读写，docstore 与 vectorstore 目录有数据

按顺序走完这份清单，绝大多数“装不起来、连不上模型、答非所问”的问题都能定位到具体环节。

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