Kotaemon 快速上手指南搭建本地文档问答RAGWeb 应用【免费下载链接】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 提供两条官方安装路径区别仅在于部署位置与耗时路径部署位置预计耗时适合场景在线安装HuggingFace Space云端约 10 分钟不想在本地装任何依赖、希望获得一个可分享的私有 Space离线安装本机Windows / macOS / Linux约 20 分钟文档涉及隐私、需要本地/私有 RAG或希望在无外网环境下使用无论选择哪条路径应用的核心形态一致一个基于 Gradio 的多标签页 Web UI包含 Chat对话、File Collection文件索引、Resources模型资源、Settings设置等页面具体结构可在应用入口 libs/ktem/ktem/main.py 中看到。方式一在线安装HuggingFace SpaceKotaemon 在 HuggingFace 上维护了一个可一键复制的模板 Space详细步骤见 在线安装指南打开cin-model/kotaemon_templateSpace使用Duplicate功能创建属于你自己的 Space官方也提供了带?duplicatetrue的直达复制链接。等待构建完成并完成首次启动整个过程约 10 分钟。按照首次设置引导完成初始化如需要注册并填写 Cohere API Key 用于重排序等能力。完成设置后即可使用你自己的私有 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 版本逻辑一致路径检查check_path_for_spaces会检测当前工作目录是否包含空格若有则中止安装——这是为了避免空格导致的不可预期行为。安装 Miniconda根据uname -m识别x86_64/aarch64架构并下载对应安装包以-b -p静默安装到install_dir/conda。创建隔离环境使用conda create -k --prefix install_dir/env python3.10创建 Python 3.10 环境注意这里明确锁定了python_version3.10。安装依赖检测到仓库根目录存在pyproject.toml时以可编辑模式安装libs/kotaemon与libs/ktem两个子包pip install -e并安装根目录应用否则按VERSION文件中的版本号从 git 仓库对应 tag 安装。安装完成后清理 conda 与 pip 缓存再询问是否启动 UI。下载 PDF.js将pdfjs-4.0.379-dist下载解压到libs/ktem/ktem/assets/prebuilt/为浏览器内的 PDF 高亮预览提供支持。设置本地模型调用 scripts/serve_local.py读取.env中的LOCAL_MODEL变量——若指向一个.gguf模型文件则询问是否启动本地模型服务并通过对应平台的server_llamacpp_*脚本拉起 llama.cpp 服务器默认端口 31415且会针对 qwen 等模型启发式猜测chat_format。启动 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(inbrowserTrue, ...)的方式启动 Gradio 服务——inbrowserTrue正是浏览器自动打开这一行为的来源同时allowed_paths将libs/ktem/ktem/assets与 Gradio 临时目录暴露给前端供 PDF 预览等资源加载使用。若设置了KH_GRADIO_SHARETrue对应环境变量KH_GRADIO_SHARE还会生成一个可公网访问的 Gradio Share 链接。启动成功后浏览器会打开应用首页默认展示 Chat 对话界面关于首次启动含在线 Space 方式的完整界面形态可参考应用初始化截屏使用三步完成一次文档问答完整操作说明见 使用指南该页面也会内置在应用内随时可查阅。核心流程为三步第一步添加 AI 模型Kotaemon 的 QA 流水线依赖大语言模型LLM因此需要先让应用能够访问你使用的模型进入Resources标签页选择LLMs子标签再进入Add子标签配置模型为它命名、选择厂商如ChatOpenAI、填写规格参数并可选设为默认模型点击Add添加切到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标签页界面分为三个区域对话设置面板选择、创建、重命名、删除会话下方是文件索引选择器——Disabled对话时完全不考虑任何文件、Search All检索全部文件或Select下拉勾选参与检索的文件不选则无文件参与。对话面板与聊天机器人交互的主区域。信息面板展示检索到的证据与引用LLM 回答中的直接引用会被高亮并给出多项打分以评估回答与检索质量Answer confidenceLLM 给出的回答置信度Relevance score证据与用户问题的总体相关度默认直接取 LLM 相关分Vectorstore score向量嵌入相似度得分若来自全文检索则显示full-text searchLLM relevant scoreLLM 基于特定提示词判断的问题-证据相关度Reranking scoreCohere 重排序模型的得分。一般而言分数质量排序为LLM relevant score Reranking score Vectorstore score证据最终按总体相关度与是否被引用进行排序展示。这种混合检索 重排序 引用打分的默认流水线正是 README.md 中所描述的 Hybrid RAG 能力在界面层面的体现。进阶通过.env预配置模型除了在 UI 上添加模型也可以在应用目录下创建/编辑.env文件来预配置详见 使用指南 的折叠章节# OpenAI OPENAI_API_BASEhttps://api.openai.com/v1 OPENAI_API_KEYyour OpenAI API key here OPENAI_CHAT_MODELgpt-3.5-turbo OPENAI_EMBEDDINGS_MODELtext-embedding-ada-002 # Azure OpenAI按你的部署情况填写 AZURE_OPENAI_ENDPOINT AZURE_OPENAI_API_KEY OPENAI_API_VERSION2024-02-15-preview AZURE_OPENAI_CHAT_DEPLOYMENTgpt-35-turbo AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-embedding-ada-002 # 本地模型GGUF 文件全路径如 Windows 11 可用复制为路径获取 LOCAL_MODELfull 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考