企业官网建设流程全解析

kotaemon：开源可定制的 RAG 文档问答框架——安装部署、模型配置与自定义流水线实战

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

kotaemon 是一个开源、简洁且可定制的 RAG（检索增强生成）UI 框架，专为"与你的文档对话"而设计。本文以项目根目录的 README.md 为主线，系统讲解其面向终端用户与开发者的核心能力、Docker 与源码两种安装方式、LLM/Embedding 模型配置、GraphRAG 与多模态解析设置，并结合仓库源码剖析flowsettings.py、.env、推理流水线与索引流水线的底层实现。读完本文，你将能独立部署一套私有文档问答系统，并掌握自定义 RAG 流水线的完整方法。

项目定位：一套代码，服务三类人群

从 README 的引言来看，kotaemon 明确服务于三个层次的使用者，其架构设计也围绕这三个层次展开：

• 终端用户（End users）：直接使用基于 kotaemon 构建的应用，在 Web UI 上对文档进行 QA 问答。
• 开发者（Developers）：在自己的项目中import kotaemon，借助其提供的组件搭建专属的 RAG 流水线。
• 贡献者（Contributors）：向本仓库提交 PR，让 kotaemon 变得更好。

这种"应用层（ktem，即 UI 应用层）"与"框架层（kotaemon，即核心库）"的双层结构，在仓库目录中体现得非常直观：

• libs/kotaemon：核心库，包含indices（索引、检索、排名）、llms（大模型接入）、embeddings（向量模型）、loaders（文档加载器）、storages（文档库/向量库）等通用组件；
• libs/ktem：基于 Gradio 构建的应用层，包含pages（Chat、Settings、Resources 等页面）、reasoning（推理流水线）、index（文件索引管理）等。

面向终端用户的能力

• 简洁清爽的 UI：为 RAG 问答设计的友好界面，主界面在 libs/ktem/ktem/main.py 中由App类渲染出 Chat、Files、Resources、Settings、Help 等标签页；
• 多种 LLM 支持：兼容 OpenAI、AzureOpenAI、Cohere 等 API 提供商，也支持通过ollama与llama-cpp-python运行本地模型；
• 简易安装：提供开箱即用的安装脚本与 Docker 镜像。

面向开发者的能力

• RAG 流水线框架：使用 kotaemon 组件自由组装文档 QA 流水线；
• 可定制 UI：UI 基于 Gradio 构建，可自由增删界面元素，并配套有独立的 Gradio 主题；
• 默认高质量检索：内置"混合检索（全文 + 向量）+ 重排序"的默认流水线，保证检索质量。

核心特性纵览

README 中列出的关键特性，均能在源码中找到对应实现：

安装部署：Docker 与源码两种方式

系统要求

1. Python >= 3.10；
2. Docker（可选，仅在使用 Docker 安装时需要）；
3. Unstructured：当需要处理.pdf、.html、.mhtml、.xlsx之外的文件（如.doc、.docx）时，需要按官方说明安装unstructured及其系统依赖（不同操作系统的安装步骤不同）。

方式一：Docker 安装（推荐）

kotaemon 提供lite与full两种镜像：full版额外安装了unstructured相关包，可支持.doc、.docx等更多文件类型，但镜像体积更大；大多数场景下lite镜像即可胜任。

• 使用full版本：

  docker run \ -e GRADIO_SERVER_NAME=0.0.0.0 \ -e GRADIO_SERVER_PORT=7860 \ -v ./ktem_app_data:/app/ktem_app_data \ -p 7860:7860 -it --rm \ ghcr.io/cinnamon/kotaemon:main-full

• 使用捆绑 Ollama 的full版本（用于本地/私有 RAG）：将镜像名替换为ghcr.io/cinnamon/kotaemon:main-ollama：

  docker run <...> ghcr.io/cinnamon/kotaemon:main-ollama

• 使用lite版本：将镜像名替换为ghcr.io/cinnamon/kotaemon:main-lite：

  docker run <...> ghcr.io/cinnamon/kotaemon:main-lite

需要说明的是，docker run <...>中的<...>代表前面full示例中除镜像名以外的完整参数（端口映射、数据卷挂载、环境变量等），实际执行时请补全为完整命令。

平台支持：目前官方支持并测试linux/amd64与linux/arm64（适配新款 Mac）两个平台，可通过--platform显式指定：

docker run \ -e GRADIO_SERVER_NAME=0.0.0.0 \ -e GRADIO_SERVER_PORT=7860 \ -v ./ktem_app_data:/app/ktem_app_data \ -p 7860:7860 -it --rm \ --platform linux/arm64 \ ghcr.io/cinnamon/kotaemon:main-lite

启动成功后，浏览器访问http://localhost:7860/即可打开 WebUI。这里有一个值得注意的细节：-v ./ktem_app_data:/app/ktem_app_data将宿主机目录挂载为应用数据目录，而 flowsettings.py 中定义KH_APP_DATA_DIR为flowsettings.py所在目录下的ktem_app_data，因此所有用户数据（数据库、向量库、上传文件）都持久化在这个目录中，重装或升级容器不会丢失数据。

方式二：不使用 Docker（源码运行）

1. 克隆仓库：

   git clone https://github.com/Cinnamon/kotaemon cd kotaemon

2. 搭建环境（二选一）：

   • 方案 A：使用 uv（推荐）

     uv sync --python 3.10 source .venv/bin/activate

   • 方案 B：使用 conda

     conda create -n kotaemon python=3.10 conda activate kotaemon pip install -e "libs/kotaemon[all]" pip install -e "libs/ktem"

3. 创建.env文件：在项目根目录创建.env，以.env.example为模板。.env的作用是在应用首次启动前预配置模型（例如部署到 HF Hub 的场景）；它只会在首次运行时用于填充数据库，之后的运行不再读取。

4. （可选）启用浏览器内 PDF 查看器：下载 PDF.js 发行包并解压到libs/ktem/ktem/assets/prebuilt目录，即可在浏览器内直接预览文档并高亮显示引用位置。

5. 启动 Web 服务：

   python app.py

   • 应用会自动在浏览器中打开；
   • 默认用户名和密码均为admin，可通过 UI 添加更多用户。

   app.py 是整个应用的入口：它从theflow.settings加载配置，实例化ktem.main.App，构建 Gradiodemo并调用demo.queue().launch(...)启动服务，同时将GRADIO_TEMP_DIR重定向到应用数据目录下的gradio_tmp临时目录。

6. 校验模型配置：进入Resources标签页的LLMs and Embeddings，确认api_key是否正确从.env读取；若未读取到，可以直接在该界面设置。

配置模型：.env与 Resources 标签页

.env文件是配置模型和凭据的另一种方式。在 flowsettings.py 中可以看到，启动时会通过decouple.config读取这些环境变量，并自动填充KH_LLMS、KH_EMBEDDINGS、KH_RERANKINGS三个字典，供 UI 的 Resources 标签页使用。

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

从 flowsettings.py 的源码看，OpenAI 的聊天模型默认映射为kotaemon.llms.ChatOpenAI（temperature=0、timeout=20），Embedding 模型默认映射为kotaemon.embeddings.OpenAIEmbeddings（context_length=8191）。当.env中配置了OPENAI_API_KEY且不等于占位符时，该模型会自动成为默认模型。

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

Azure 配置对应kotaemon.llms.AzureChatOpenAI与kotaemon.embeddings.AzureOpenAIEmbeddings，源码中同样设置了temperature=0与超时参数（聊天 20s、Embedding 10s）。

本地模型

kotaemon 支持完全本地化运行，实现私有 RAG。详细步骤见 本地模型配置文档。这里给出三条路径的速览：

• Ollama（推荐）：先ollama pull llama3.1:8b和ollama pull nomic-embed-text拉取模型，然后在 Resources 标签页以类型 OpenAI 添加模型，参数为api_key: ollama、base_url: http://localhost:11434/v1/、model: gemma2:2b（LLM）或nomic-embed-text（Embedding）。若在 Docker 中运行，需将localhost替换为host.docker.internal才能访问宿主机服务。在 flowsettings.py 中，设置LOCAL_MODEL环境变量即可自动注册ollama的 LLM、长上下文变体（LCOllamaChat，默认num_ctx=8192）与 Embedding 模型；
• oobabooga/text-generation-webui：以python server.py --api启动 OpenAI 兼容服务，在 Resources 中配置api_key: dummy、base_url: http://localhost:5000/v1/、model: any；
• llama-cpp-python（仅 LLM）：下载 GGUF 模型后运行LOCAL_MODEL=<path/to/GGUF> python scripts/serve_local.py（对应仓库中的 scripts/serve_local.py），再在 Resources 中配置api_key: dummy、base_url: http://localhost:8000/v1/。

其他提供商

从 flowsettings.py 可以确认，框架内置了以下额外提供商（大多默认default: False，需在 UI 中手动设为默认）：

• Claude（kotaemon.llms.chats.LCAnthropicChat，默认模型claude-3-5-sonnet-20240620）；
• Google Gemini（kotaemon.llms.chats.LCGeminiChat，默认模型gemini-1.5-flash）；
• Groq（走 OpenAI 兼容接口，base_url: https://api.groq.com/openai/v1，默认模型llama-3.1-8b-instant）；
• Cohere（kotaemon.llms.chats.LCCohereChat，默认command-r-plus-08-2024；同时提供 Cohere Embeddingembed-multilingual-v3.0与默认重排序模型rerank-v4.0-fast）；
• Mistral（OpenAI 兼容接口，默认ministral-8b-latest，并提供mistral-embed）；
• VoyageAI（Embeddingvoyage-3-large与重排序rerank-2）。

将本地模型用于 RAG 的三步操作

按 本地模型配置文档 的"Use local models for RAG"章节，配置完成后还需：

1. 在 Resources 中将默认 LLM 与默认 Embedding 模型切换为本地模型；
2. 为文件集合（File Collection）指定本地 Embedding 模型（如ollama）；
3. 在检索设置（Retrieval settings）中将"LLM 相关度打分"模型设为本地模型；若机器无法承受大量并行 LLM 请求，可关闭该功能。

完成以上步骤后即可开启新会话，测试本地 RAG 流水线。

搭建 GraphRAG 索引

kotaemon 提供了三种 GraphRAG 实现，默认从 flowsettings.py 中的开关控制（USE_NANO_GRAPHRAG、USE_LIGHTRAG、USE_MS_GRAPHRAG），并通过KH_INDEX_TYPES注册到索引管理器，在 UI 的 Files 标签页中以独立集合形式呈现。需要注意的是，官方 MS GraphRAG 的索引仅支持 OpenAI 或 Ollama API；官方推荐大多数用户使用 NanoGraphRAG 实现，以获得与 kotaemon 更顺畅的集成。

方式一：Nano GraphRAG

pip install nano-graphrag

• 若安装引入版本冲突，可执行pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib快速修复；
• 以环境变量USE_NANO_GRAPHRAG=true启动 kotaemon；
• 在 Resources 设置中配置好默认 LLM 与 Embedding 模型，NanoGraphRAG 会自动识别。

方式二：LightRAG

pip install git+https://github.com/HKUDS/LightRAG.git

• 同样可能引入版本冲突，修复方式同上；
• 以环境变量USE_LIGHTRAG=true启动；
• 默认 LLM 与 Embedding 模型会在 Resources 设置中被 LightRAG 自动识别。

方式三：MS GraphRAG

• 非 Docker 安装：

  pip install "graphrag<=0.3.6" future

• 设置 API Key：使用 GraphRAG 检索器前，需设置GRAPHRAG_API_KEY环境变量（可直接在环境中设置，或写入.env文件）；

• 使用本地模型与自定义配置：如需用本地模型（如 Ollama）或自定义默认 LLM 与其他配置，请将USE_CUSTOMIZED_GRAPHRAG_SETTING环境变量设为true，然后在 settings.yaml.example 中调整参数。

仓库根目录的 settings.yaml.example 是一份完整的 GraphRAG 自定义配置模板，关键参数包括：

• llm：type: openai_chat（或azure_openai_chat）、api_base（示例指向本地 Ollamahttp://127.0.0.1:11434/v1）、model（示例为qwen2）、model_supports_json: true、request_timeout、concurrent_requests（并发请求数，示例为 5）等；
• embeddings.llm：配置type: openai_embedding、model: nomic-embed-text等 Embedding 参数；
• chunks：size: 1200、overlap: 100、group_by_columns: [id]（默认不允许跨文档切块）；
• input/cache/storage/reporting：输入目录、缓存与输出的存储位置（file 或 blob 类型）；
• entity_extraction、summarize_descriptions、claim_extraction、community_reports：各阶段的 Prompt 与参数（如entity_types、max_gleanings）；
• cluster_graph：max_cluster_size: 10；
• local_search/global_search：两种检索模式的调优参数（如max_tokens、concurrency）。

该文件仅在USE_CUSTOMIZED_GRAPHRAG_SETTING=true时生效。从 flowsettings.py 可以看到，注册的 GraphRAG 集合均支持.png, .jpeg, .jpg, .tiff, .tif, .pdf, .xls, .xlsx, .doc, .docx, .pptx, .csv, .html, .mhtml, .txt, .md, .zip等文件类型，且默认私有（private: True）。

多模态文档解析（OCR、表格解析、图表提取）

kotaemon 支持以下多模态文档解析方案，各方案对应 libs/kotaemon/kotaemon/loaders 中的加载器实现：

在 UI 中通过Settings -> Retrieval Settings -> File loader选择对应的加载器即可。从 pipelines.py 的IndexDocumentPipeline.get_user_settings可以看出，该选项的完整取值包括：

• default（默认，开源解析器）；
• adobe（Adobe API，图表+表格提取）；
• azure-di（Azure AI Document Intelligence，图表+表格提取）；
• docling（Docling，图表+表格提取）；
• paddle-struct（PaddleOCR PPStructureV3，表格+图表提取）；
• paddle-vl（PaddleOCR-VL，VLM 文档解析）。

在 pipelines.py 的readers属性中，reader_mode会决定.pdf、.png、.jpeg等文件后缀路由到哪个具体加载器；对于不在映射表中的扩展名，则回退到unstructured通用解析器。

自定义应用：flowsettings.py与.env

默认情况下，所有应用数据存储在./ktem_app_data目录，可将该目录备份或拷贝以迁移到新机器。对于高级用户或特定场景，可自定义两个关键文件：flowsettings.py与.env。

flowsettings.py

该文件是应用配置的核心，仓库根目录的 flowsettings.py 即是一个可直接参考的完整示例。几个关键配置项：

# 设置偏好的文档库（支持全文检索） KH_DOCSTORE=(Elasticsearch | LanceDB | SimpleFileDocumentStore) # 设置偏好的向量库（用于向量检索） KH_VECTORSTORE=(ChromaDB | LanceDB | InMemory | Milvus | Qdrant) # 启用 / 禁用多模态 QA KH_REASONINGS_USE_MULTIMODAL=True # 设置新的推理流水线或修改现有流水线 KH_REASONINGS = [ "ktem.reasoning.simple.FullQAPipeline", "ktem.reasoning.simple.FullDecomposeQAPipeline", "ktem.reasoning.react.ReactAgentPipeline", "ktem.reasoning.rewoo.RewooAgentPipeline", ]

结合仓库实际配置，可以对上述选项做更深入的理解：

• 文档库（Document Store）：从 libs/kotaemon/kotaemon/storages/init.py 可见，实际可用实现还包括InMemoryDocumentStore。当前 flowsettings.py 默认启用LanceDBDocumentStore，数据目录位于ktem_app_data/user_data/docstore；
• 向量库（Vector Store）：可用实现还包括SimpleFileVectorStore。当前默认启用ChromaVectorStore，数据目录为ktem_app_data/user_data/vectorstore；
• 推理流水线：四条默认流水线分别对应 simple.py 中的FullQAPipeline（简单 QA）、FullDecomposeQAPipeline（复杂 QA，问题分解）、react.py 的ReactAgentPipeline（ReAct 代理）与 rewoo.py 的RewooAgentPipeline（ReWOO 代理）；
• 多模态：实际通过USE_MULTIMODAL环境变量控制（见 flowsettings.py）。

其他值得关注的默认配置还包括：KH_APP_DATA_DIR（应用数据目录）、KH_DATABASE（SQLite 数据库路径sqlite:///ktem_app_data/user_data/sql.db）、KH_FILESTORAGE_PATH（文件存储目录）、KH_WEB_SEARCH_BACKEND（Web 搜索后端，默认 Tavily，可切换 Jina）、KH_OLLAMA_URL（默认http://localhost:11434/v1/）、KH_GRADIO_SHARE（是否生成 Gradio 公网分享链接）以及用户管理开关（默认用户名/密码均为admin）。

.env

.env提供了另一种配置模型与凭据的方式，上一节已详细列出各提供商的环境变量。核心要点是：.env只会在首次启动时被读取并写入数据库，后续修改需要进入 UI 的 Resources 页面调整。

添加自定义 RAG 流水线

自定义推理流水线（Reasoning Pipeline）

1. 查看 libs/ktem/ktem/reasoning/simple.py 中的默认流水线实现，可快速了解默认 QA 流水线的工作方式并做调整；
2. 在libs/ktem/ktem/reasoning/下新增.py实现，然后在flowsettings.py的KH_REASONINGS中注册，即可在 UI 上启用。

以FullQAPipeline为例（simple.py），其运行链路清晰展示了 RAG 问答的完整流程：

• stream()方法：若启用重写则先经rewrite_pipeline改写问题 → 调用retrieve()多路检索（每个检索器去重合并结果）→evidence_pipeline整理证据（支持evidence_mode与图片）→ 后台线程并行计算相关度分数 →answering_pipeline.stream()流式生成答案 →show_citations_and_addons()输出引用、思维导图、引用关系可视化图，并在 LLM 相关度分数低于CONTEXT_RELEVANT_WARNING_SCORE时给出警告；
• get_user_settings()暴露了大量可配置项：语言模型、引用样式（highlight / inline / off）、是否生成思维导图、是否生成 Embedding 可视化、是否启用多模态输入、System Prompt、QA Prompt（模板含{context}、{question}、{lang}占位符）、纳入上下文的历史交互数（默认 5）、触发上下文改写的最长消息长度（默认 150）。

自定义索引流水线（Indexing Pipeline）

• 参考libs/ktem/ktem/index/file/graph目录下的示例实现（GraphRAG 系列索引）。

从 libs/ktem/ktem/index/file/index.py 的FileIndex类可以看出索引体系的基础设施：SQL 表Source（记录已索引文件列表）、VectorStore（存放文件片段的向量）、DocumentStore（存放文件片段的文本，与向量一一对应）、SQL 表Index（维护源文件与文档库/向量库的关联关系）。索引流水线类、检索流水线类、文件选择 UI 类均支持通过config、FILE_INDEX_*_PIPELINE等 flowsettings 配置逐级覆盖，最终回退到默认实现（pipelines.py 中的IndexDocumentPipeline与DocumentRetrievalPipeline）。

在检索侧，DocumentRetrievalPipeline支持retrieval_mode（vector/text/hybrid）、num_retrieval（检索块数）、use_reranking、use_llm_reranking（LLM 相关度打分）、mmr（最大边际相关性去重）、prioritize_table（优先补充表格上下文）等参数；在索引侧，IndexDocumentPipeline按文件扩展名路由到不同的解析器，并通过TokenSplitter（默认chunk_size=1024、chunk_overlap=256，分隔符优先\n\n）完成文本切块。

引用与参与贡献

如果你在论文或项目中使用本仓库，请按以下 BibTeX 格式引用：

@misc{kotaemon2024, title = {Kotaemon - An open-source RAG-based tool for chatting with any content.}, author = {The Kotaemon Team}, year = {2024}, howpublished = {\url{https://github.com/Cinnamon/kotaemon}}, }

kotaemon 处于活跃开发状态，欢迎通过 贡献指南 提交反馈与代码贡献。

小结

kotaemon 通过"核心库 + 应用层"的双层架构，同时满足了终端用户"开箱即用的文档问答"与开发者"自由构建 RAG 流水线"两类需求。本文从安装部署、模型配置、GraphRAG 搭建、多模态解析到自定义流水线，完整还原了 README 的实操路径，并结合 flowsettings.py、reasoning/simple.py、index/file/pipelines.py 等源码阐明了底层机制。上手时，建议优先使用 Docker 快速体验，再通过flowsettings.py与.env逐步定制，最终按需扩展属于自己的推理与索引流水线。

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