kotaemon 在线部署指南通过 HuggingFace Space 十分钟搭建专属 RAG 文档问答应用【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemonkotaemon 是一个开源的、基于 RAG检索增强生成的文档问答工具用于与你的文档进行对话。本文聚焦于其最简单、无需本地环境的部署路径——在线安装Online HuggingFace Space借助 HuggingFace 上官方维护的 Space 模板通过复制 SpaceDuplicate功能即可在约 10 分钟内获得一个完全私有的文档问答 Web 应用。读完本文你将掌握从复制 Space、调整运行参数、等待构建到完成首次模型配置与 API Key 注册的全流程并能理解该在线部署背后构建脚本、启动入口、首次设置页面的实现原理方便后续进行个性化调整与维护。一、在线安装Online HuggingFace Space总览官方文档 docs/online_install.md 将在线部署描述为easy10 mins级别整个流程只有 5 个步骤访问官方 kotaemon Space 模板使用 Duplicate 功能创建属于自己的 Space或用直达链接一键复制等待构建完成并启动约 10 分钟按照首次设置引导完成初始化如需 Cohere API Key 则先注册完成设置后即可使用自己的私有 Space。与 Docker 部署推荐给开发者 和 离线安装脚本 相比在线安装不需要本地 Python 3.10 环境、不需要安装 Docker、不需要处理uv sync等依赖解析所有计算资源与存储都托管在 HuggingFace 云端适合希望快速体验或没有本地 GPU/大内存机器的终端用户。二、第一步访问官方 Space 模板并复制打开 kotaemon_template Space页面右上角即可看到Duplicate按钮。更快捷的方式是直接使用官方提供的复制直达链接在 URL 后追加?duplicatetrue它会跳过模板主页直接进入创建 Space 的配置界面。说明公开的 kotaemon Space如官方 Demo是共享资源任何人上传的文件都可能被其他访问者看到因此官方文档强调要通过 Duplicate 创建自己专属的 Space来使用。这也与仓库中 libs/ktem/ktem/pages/setup.py 中定义的DEMO_MESSAGE一致——公共 Space 会在界面上提示请使用右上角的 Duplicate Space 功能创建你自己的 Space。三、第二步调整 Space 参数点击复制后HuggingFace 会跳转到Duplicate this Space配置页需要确认/修改以下关键参数Owner选择 Space 归属账户个人账号或组织Space name给你的私有实例命名Visibility可见性推荐选择Private保证只有你能访问如果你希望与团队协作可选择 Public 但注意隐私风险Hardware硬件配置kotaemon 的 RAG 应用在 CPU 上即可运行默认硬件通常足够若选择带 GPU 的配置会显著增加计费一般不需要Secrets密钥可在此处预先填入环境变量如OPENAI_API_KEYSpace 启动时会被读取。这部分与仓库中.env的用途一致——官方说明指出.env用于在应用首次启动前预配置模型仅首次运行时会写入数据库。确认参数后点击Create SpaceHuggingFace 会立即开始基于仓库中的 Dockerfile 构建镜像并部署。四、第三步等待构建与启动约 10 分钟创建完成后进入 Space 页面页面会显示构建日志。首次构建需要完成以下工作可从 Dockerfile 的源码确认安装系统依赖poppler-utilsPDF 解析、git、gcc/g、cargo等Lite 版本基础层执行 scripts/download_pdfjs.sh 下载 PDF.js 前端查看器资源使用uv sync --frozen安装所有 Python 依赖安装graphrag仅 amd64 架构用于可选的 GraphRAG 检索。构建完成后launch.sh 作为容器入口脚本被调用默认以GRADIO_SERVER_NAME0.0.0.0、GRADIO_SERVER_PORT7860启动若未显式设置随后执行.venv/bin/python app.py拉起 Gradio 应用app.py 中通过ktem.main.App构建 demo 并调用demo.queue().launch(...)应用就绪后会监听 7860 端口由 HuggingFace Space 网关对外提供 HTTPS 访问。期间页面可能出现以下状态构建/启动进行中Build logs / Runtime logs构建完成后应用正在加载模型与资源。构建完成、应用成功启动后可以将构建日志面板收起此时页面顶部会显示应用界面。提示约 10 分钟是基于官方模板在默认硬件配置下的经验值实际耗时取决于所选硬件与网络状况。若超过较长时间仍未就绪可回到 Space 的Settings检查硬件配置或在Logs页查看详细错误。五、第四步完成首次设置并注册 API Key应用首次启动时会自动进入Welcome to kotaemon first setup!引导页。这个页面的实现位于 libs/ktem/ktem/pages/setup.py其核心是一个模型供应商单选组件支持四种接入方式选项用途对应源码配置setup.py 中的 specCohere API推荐免费注册云端 API适合大多数用户ChatLCCohereChat/command-r-plus-08-2024EmbeddingLCCohereEmbeddings/embed-multilingual-v3.0RerankCohereReranking/rerank-v4.0-fastGoogle API免费注册云端 APIChatLCGeminiChat/gemini-1.5-flashEmbeddingLCGoogleEmbeddings/text-embedding-004OpenAI APIGPT 系列模型云端 APIChatChatOpenAI/gpt-4oEmbeddingOpenAIEmbeddings/text-embedding-3-largeLocal LLMOllama完全私有 RAGChatChatOpenAIbase_url 指向 Ollama/ 默认qwen2.5:7bEmbedding默认nomic-embed-text如果你没有其他云端服务商账号官方推荐选择Cohere——注册完全免费且一个 Key 同时覆盖了 LLM 对话、Embedding 向量化和 Rerank 重排序三类模型这正是 kotaemon 混合 RAG 检索管线所需的完整模型组合。选择 Cohere 后在输入框粘贴你的 Cohere API Key 并点击Proceed。此时setup.py中的update_model事件会依次执行将 LLM / Embedding / Rerank 三个模型写入应用数据库并设为默认连接测试向 LLM 发送Hi验证对话可用性再向 Embedding 模型发送Hi验证向量化可用性日志区域会实时显示Connection success或Connection failed及具体错误更新默认检索设置update_default_settings会把重排序 LLM 指向所选供应商选择 Ollama 时会自动关闭基于 LLM 的重排序因为本地小模型重排序质量有限。如果你已经对模型配置非常熟悉也可以点击页面底部的I am an advance user. Skip this.跳过引导之后再到应用内的Resources选项卡手动添加模型详见 docs/usage.md 的Add your AI models章节。六、第五步完成设置使用你的私有 Space设置完成后应用进入主界面即文档中展示的初始启动画面。至此你的私有 RAG 应用已经可以正常使用接下来可参考 docs/usage.md 完成核心操作闭环添加模型进入Resources选项卡在LLMs与Embedding Models子页签中添加/切换更多模型在线安装中 Cohere 配置已就绪可跳过此步上传文档进入File Index选项卡拖拽或选择文件后点击Upload and Index等待索引完成与文档对话回到Chat选项卡在会话设置面板中选择检索文件范围Disabled / Search All / Select即可开始带引用的文档问答右侧信息面板会展示证据、引用高亮与各类相关性分数。七、在线安装的进阶理解与注意事项7.1 在线 Space 与本地部署的差异从源码结构看HuggingFace Space 部署复用的是与本地完全相同的代码路径launch.sh 是 Docker 部署与 Space 部署共用的启动入口区别仅在于数据持久化Space 的磁盘是临时/受限的ktem_app_data目录中的文档索引与会话数据在 Space 重建后可能丢失重要数据请定期备份登录与多用户仓库同时提供KH_DEMO_MODE与KH_SSO_ENABLED两种特殊启动模式见 launch.sh在线公共 Demo 即运行在 demo 模式下关闭用户管理、禁用 LightRAG你自己的私有 Space 默认走标准模式首次登录使用admin / admin作为默认账号来自 README 的安装说明建议登录后立即在 UI 中修改凭据模型出口在线 Space 无法访问你本地的 Ollama因此Local LLM选项要求你另行部署可被公网访问的 Ollama 服务如通过 tunnel这对大多数用户而言成本较高这也是官方推荐在线安装使用 Cohere 等云端 API 的原因。7.2 常见问题排查首次设置连接失败检查 API Key 是否粘贴正确、是否有多余空格Space 的 Runtime Logs 中会打印update_model阶段的具体异常信息页面长时间停留在构建确认硬件配置未被设置为过低的免费档位必要时到 Space Settings 调整后重启想要换一个模型供应商无需重建 Space直接在应用内Resources选项卡添加新模型并设为默认即可这与 docs/usage.md 中的模型管理流程完全一致。结语在线安装HuggingFace Space是 kotaemon 面向终端用户设计的零门槛部署方案复制模板、调整参数、等待构建、完成首次模型配置四步即可获得私有的 RAG 文档问答应用。其背后与仓库本地部署共用同一套 Dockerfile、launch.sh 与 app.py 启动链路首次设置引导则由 libs/ktem/ktem/pages/setup.py 驱动这种一个入口、多种部署形态的设计让在线体验与后续迁移到自建环境保持了一致性。若你需要更高可控性本地模型、数据不出内网、GraphRAG 高级检索可进一步参考仓库内的 Docker 安装说明、离线安装指南 与 本地模型配置。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考