企业官网建设流程全解析

Kotaemon 快速上手指南：搭建本地文档问答（RAG）Web 应用

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

本篇指南面向终端用户，讲解如何以最直接的方式安装并运行 Kotaemon——一个开源的、基于 RAG（检索增强生成）的文档问答工具，用于"与你的文档对话"。文章覆盖 HuggingFace Space 在线安装（约 10 分钟）与离线一键安装（约 20 分钟）两条路径，并结合仓库内的启动脚本与源码，剖析安装脚本的内部工作流程、默认登录凭据与首次启动后的三步走用法，读完即可在浏览器中开始对本地文档进行提问与检索。

若你是希望为项目贡献代码的开发者，请移步 开发指南；本文专注于把应用跑起来并投入使用。

安装前的准备：两条路径怎么选

Kotaemon 提供两条官方安装路径，区别仅在于部署位置与耗时：

无论选择哪条路径，应用的核心形态一致：一个基于 Gradio 的多标签页 Web UI，包含 Chat（对话）、File Collection（文件索引）、Resources（模型资源）、Settings（设置）等页面，具体结构可在应用入口 libs/ktem/ktem/main.py 中看到。

方式一：在线安装（HuggingFace Space）

Kotaemon 在 HuggingFace 上维护了一个可一键复制的模板 Space，详细步骤见 在线安装指南：

1. 打开cin-model/kotaemon_templateSpace，使用Duplicate功能创建属于你自己的 Space（官方也提供了带?duplicate=true的直达复制链接）。
2. 等待构建完成并完成首次启动，整个过程约 10 分钟。
3. 按照首次设置引导完成初始化（如需要，注册并填写 Cohere API Key 用于重排序等能力）。
4. 完成设置后，即可使用你自己的私有 Space。

在线安装的核心价值在于"零本地依赖"：模型密钥、检索参数全部在 Space 内配置，文档数据同样存储于你的私有 Space 中。关于 Space 构建期间可能遇到的环境变量与模型预配置问题，可参考仓库根目录的 README.md 中关于.env仅用于首次启动时填充数据库的说明。

方式二：离线安装（本机部署）

离线安装是多数终端用户的首选，它由"下载发布包 + 运行安装脚本"两步组成。

第一步：下载发布包

从仓库最新 Release 页面下载kotaemon-app.zip文件并解压。该发布包打包了应用本体与配套脚本，解压后即可开始安装。

第二步：运行与操作系统匹配的安装脚本

进入解压后的scripts目录，选择对应你操作系统的脚本运行：

• Windows：双击 run_windows.bat 即可。
• macOS：右键 run_macos.sh，选择"打开方式"→"其他"，启用"所有应用程序"并选择"终端"；若希望以后都默认用终端打开，勾选"始终使用此 App 打开"。
• Linux：在终端中执行bash run_linux.sh运行 run_linux.sh。

安装结束后，脚本会询问是否立即启动 ktem 的 Web UI，输入y继续即可；应用随后会在浏览器中自动打开。首次登录的默认账号密码均为admin / admin，请在登录后立刻在 UI 中修改该凭据。

安装脚本内部到底做了什么（源码级解析）

所谓"一键安装"并非简单的解压复制，run_linux.sh 的主流程清晰地展示了完整的自动化步骤，macOS 与 Windows 版本逻辑一致：

1. 路径检查：check_path_for_spaces会检测当前工作目录是否包含空格，若有则中止安装——这是为了避免空格导致的不可预期行为。
2. 安装 Miniconda：根据uname -m识别x86_64/aarch64架构并下载对应安装包，以-b -p静默安装到install_dir/conda。
3. 创建隔离环境：使用conda create -k --prefix install_dir/env python=3.10创建 Python 3.10 环境（注意这里明确锁定了python_version="3.10"）。
4. 安装依赖：检测到仓库根目录存在pyproject.toml时，以可编辑模式安装libs/kotaemon与libs/ktem两个子包（pip install -e），并安装根目录应用；否则按VERSION文件中的版本号从 git 仓库对应 tag 安装。安装完成后清理 conda 与 pip 缓存，再询问是否启动 UI。
5. 下载 PDF.js：将pdfjs-4.0.379-dist下载解压到libs/ktem/ktem/assets/prebuilt/，为浏览器内的 PDF 高亮预览提供支持。
6. 设置本地模型：调用 scripts/serve_local.py，读取.env中的LOCAL_MODEL变量——若指向一个.gguf模型文件，则询问是否启动本地模型服务，并通过对应平台的server_llamacpp_*脚本拉起 llama.cpp 服务器（默认端口 31415，且会针对 qwen 等模型启发式猜测chat_format）。
7. 启动 UI：以PDFJS_PREBUILT_DIR环境变量指向 PDF.js 目录，执行python app.py完成启动。

这套脚本把"Python 环境、依赖、PDF 查看器、本地模型服务、Web 服务"全部串成了一条流水线，因此脚本天然具备幂等性：若pip list中已存在kotaemon，依赖步骤会直接跳过，下次再运行只会快速拉起 UI。

启动应用

无论是初次安装完成，还是之后每次想再次使用，只需再次运行对应的run_*脚本即可启动应用。

启动的实质入口是仓库根目录的 app.py：它从flowsettings读取配置，构造ktem.main.App实例，并以demo.queue().launch(inbrowser=True, ...)的方式启动 Gradio 服务——inbrowser=True正是"浏览器自动打开"这一行为的来源，同时allowed_paths将libs/ktem/ktem/assets与 Gradio 临时目录暴露给前端，供 PDF 预览等资源加载使用。若设置了KH_GRADIO_SHARE=True（对应环境变量KH_GRADIO_SHARE），还会生成一个可公网访问的 Gradio Share 链接。

启动成功后，浏览器会打开应用首页，默认展示 Chat 对话界面：

关于首次启动（含在线 Space 方式）的完整界面形态，可参考应用初始化截屏：

使用：三步完成一次文档问答

完整操作说明见 使用指南（该页面也会内置在应用内，随时可查阅）。核心流程为三步：

第一步：添加 AI 模型

Kotaemon 的 QA 流水线依赖大语言模型（LLM），因此需要先让应用能够访问你使用的模型：

1. 进入Resources标签页；
2. 选择LLMs子标签，再进入Add子标签；
3. 配置模型：为它命名、选择厂商（如ChatOpenAI）、填写规格参数，并（可选）设为默认模型；
4. 点击Add添加；
5. 切到Embedding Models子标签重复上述操作，添加一个 Embedding 模型。

至少提供一个 LLM 即可运行，但官方建议把你可用的模型全部接入，这样在对话时可以在不同模型间自由切换。从 flowsettings.py 可以看出，应用在启动时也会根据环境变量预置一批模型：配置了OPENAI_API_KEY会注册 OpenAI 的 Chat 与 Embedding；配置了AZURE_OPENAI_API_KEY与AZURE_OPENAI_ENDPOINT会注册 Azure 系列；设置LOCAL_MODEL会注册基于 Ollama 兼容接口的本地模型与nomic-embed-text嵌入模型；此外 Claude、Google Gemini、Groq、Cohere、Mistral、VoyageAI 等也均有预置配置。

第二步：上传文档

进入File Index标签页：

• 文件上传区：拖拽文件到 UI 或从文件系统选择，点击Upload and Index。应用会花费一些时间解析、切分并建立索引，完成后给出提示。
• 文件列表区：展示已上传文件，支持删除。

默认的File Collection索引支持.pdf、.doc、.docx、.pptx、.xlsx、.html、.txt、.md等多种格式（完整列表见 flowsettings.py）。

第三步：与文档对话

回到Chat标签页，界面分为三个区域：

1. 对话设置面板：选择、创建、重命名、删除会话；下方是文件索引选择器——Disabled（对话时完全不考虑任何文件）、Search All（检索全部文件）或Select（下拉勾选参与检索的文件，不选则无文件参与）。
2. 对话面板：与聊天机器人交互的主区域。
3. 信息面板：展示检索到的证据与引用，LLM 回答中的直接引用会被高亮，并给出多项打分以评估回答与检索质量：
   • Answer confidence：LLM 给出的回答置信度；
   • Relevance score：证据与用户问题的总体相关度（默认直接取 LLM 相关分）；
   • Vectorstore score：向量嵌入相似度得分（若来自全文检索则显示full-text search）；
   • LLM relevant score：LLM 基于特定提示词判断的"问题-证据"相关度；
   • Reranking score：Cohere 重排序模型的得分。

一般而言，分数质量排序为LLM relevant score > Reranking score > Vectorstore score，证据最终按总体相关度与是否被引用进行排序展示。这种"混合检索 + 重排序 + 引用打分"的默认流水线，正是 README.md 中所描述的 Hybrid RAG 能力在界面层面的体现。

进阶：通过.env预配置模型

除了在 UI 上添加模型，也可以在应用目录下创建/编辑.env文件来预配置（详见 使用指南 的折叠章节）：

# OpenAI OPENAI_API_BASE=https://api.openai.com/v1 OPENAI_API_KEY=<your OpenAI API key here> OPENAI_CHAT_MODEL=gpt-3.5-turbo OPENAI_EMBEDDINGS_MODEL=text-embedding-ada-002 # Azure OpenAI（按你的部署情况填写） AZURE_OPENAI_ENDPOINT= AZURE_OPENAI_API_KEY= OPENAI_API_VERSION=2024-02-15-preview AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-35-turbo AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT=text-embedding-ada-002 # 本地模型（GGUF 文件全路径，如 Windows 11 可用"复制为路径"获取） LOCAL_MODEL=<full path to your model file>

本地模型的优势在于隐私（文档本地存储处理）、可选模型丰富与零调用成本，劣势是生成质量与速度受限于本机硬件。关于在无外网环境下使用本地模型的更多细节，可参考 本地模型说明。需要留意的是，.env只在首次启动时用于填充数据库，之后的启动不再读取它——后续改动请在 UI 中完成。

数据存储与应用配置

应用的所有数据默认存放在./ktem_app_data目录（具体由 flowsettings.py 定义：用户数据、向量库、文档存储、markdown/切片缓存、HuggingFace 模型缓存均归于此），备份或迁移到新机器时直接复制该目录即可。KH_DOCSTORE默认使用 LanceDB（支持全文检索）、KH_VECTORSTORE默认使用 Chroma，均可通过修改 flowsettings.py 切换为 Elasticsearch、Milvus、Qdrant 等方案；KH_REASONINGS则决定了可用的推理流水线（基础 QA、问题分解 QA、ReAct Agent、ReWOO Agent 等）。高级用户可通过编辑flowsettings.py与应用根目录的 settings.yaml.example 进一步定制。

反馈与获取帮助

使用过程中遇到 Bug 或有功能建议，欢迎在项目仓库的 Issues 中提交反馈（贡献指南 中说明了参与开发的入口）。此外，应用内置的 Help 标签页与 使用指南 都是随时可查阅的官方文档，覆盖从模型接入到多模态文档解析、GraphRAG 索引等进阶能力（参见 多模态解析集成 与 PaddleOCR 集成）。

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