kotaemon开源可定制的 RAG 文档问答框架——安装部署、模型配置与自定义流水线实战【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemonkotaemon 是一个开源、简洁且可定制的 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 构建的应用层包含pagesChat、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 流水线可定制 UIUI 基于 Gradio 构建可自由增删界面元素并配套有独立的 Gradio 主题默认高质量检索内置混合检索全文 向量 重排序的默认流水线保证检索质量。核心特性纵览README 中列出的关键特性均能在源码中找到对应实现特性说明源码佐证自托管文档 QA Web UI支持多用户登录、私有/公共文件集合、协作共享会话flowsettings.py 中KH_FEATURE_USER_MANAGEMENT、main.py 中LoginPage与标签页逻辑LLM 与 Embedding 统一管理支持本地模型与 OpenAI、Azure、Ollama、Groq 等 API 提供商flowsettings.py 中KH_LLMS、KH_EMBEDDINGS混合 RAG 流水线混合全文向量检索器 重排序保障检索质量pipelines.py 中DocumentRetrievalPipeline的retrieval_mode与rerankers多模态 QA支持图表、表格的问答与多模态文档解析UI 可选loaders 目录下的各类加载器、use_multimodal设置项高级引用与文档预览默认提供详细引用支持在浏览器内 PDF 查看器中高亮查看含相关度分数检索相关度低时给出警告simple.py 中show_citations_and_addons、CONTEXT_RELEVANT_WARNING_SCORE警告逻辑复杂推理方法支持问题分解、ReAct、ReWOO等基于 Agent 的推理react.py、rewoo.py可配置设置 UI检索与生成的主要参数含 Prompt可在 UI 上调整get_user_settings系列方法如 simple.py可扩展基于 Gradio 可自由定制 UI支持多种索引策略提供 GraphRAG 索引流水线示例graph 目录安装部署Docker 与源码两种方式系统要求Python 3.10Docker可选仅在使用 Docker 安装时需要Unstructured当需要处理.pdf、.html、.mhtml、.xlsx之外的文件如.doc、.docx时需要按官方说明安装unstructured及其系统依赖不同操作系统的安装步骤不同。方式一Docker 安装推荐kotaemon 提供lite与full两种镜像full版额外安装了unstructured相关包可支持.doc、.docx等更多文件类型但镜像体积更大大多数场景下lite镜像即可胜任。使用full版本docker run \ -e GRADIO_SERVER_NAME0.0.0.0 \ -e GRADIO_SERVER_PORT7860 \ -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-ollamadocker run ... ghcr.io/cinnamon/kotaemon:main-ollama使用lite版本将镜像名替换为ghcr.io/cinnamon/kotaemon:main-litedocker run ... ghcr.io/cinnamon/kotaemon:main-lite需要说明的是docker run ...中的...代表前面full示例中除镜像名以外的完整参数端口映射、数据卷挂载、环境变量等实际执行时请补全为完整命令。平台支持目前官方支持并测试linux/amd64与linux/arm64适配新款 Mac两个平台可通过--platform显式指定docker run \ -e GRADIO_SERVER_NAME0.0.0.0 \ -e GRADIO_SERVER_PORT7860 \ -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源码运行克隆仓库git clone https://github.com/Cinnamon/kotaemon cd kotaemon搭建环境二选一方案 A使用 uv推荐uv sync --python 3.10 source .venv/bin/activate方案 B使用 condaconda create -n kotaemon python3.10 conda activate kotaemon pip install -e libs/kotaemon[all] pip install -e libs/ktem创建.env文件在项目根目录创建.env以.env.example为模板。.env的作用是在应用首次启动前预配置模型例如部署到 HF Hub 的场景它只会在首次运行时用于填充数据库之后的运行不再读取。可选启用浏览器内 PDF 查看器下载 PDF.js 发行包并解压到libs/ktem/ktem/assets/prebuilt目录即可在浏览器内直接预览文档并高亮显示引用位置。启动 Web 服务python app.py应用会自动在浏览器中打开默认用户名和密码均为admin可通过 UI 添加更多用户。app.py 是整个应用的入口它从theflow.settings加载配置实例化ktem.main.App构建 Gradiodemo并调用demo.queue().launch(...)启动服务同时将GRADIO_TEMP_DIR重定向到应用数据目录下的gradio_tmp临时目录。校验模型配置进入Resources标签页的LLMs and Embeddings确认api_key是否正确从.env读取若未读取到可以直接在该界面设置。配置模型.env与 Resources 标签页.env文件是配置模型和凭据的另一种方式。在 flowsettings.py 中可以看到启动时会通过decouple.config读取这些环境变量并自动填充KH_LLMS、KH_EMBEDDINGS、KH_RERANKINGS三个字典供 UI 的 Resources 标签页使用。OpenAIOPENAI_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从 flowsettings.py 的源码看OpenAI 的聊天模型默认映射为kotaemon.llms.ChatOpenAItemperature0、timeout20Embedding 模型默认映射为kotaemon.embeddings.OpenAIEmbeddingscontext_length8191。当.env中配置了OPENAI_API_KEY且不等于占位符时该模型会自动成为默认模型。Azure OpenAIAZURE_OPENAI_ENDPOINT AZURE_OPENAI_API_KEY OPENAI_API_VERSION2024-02-15-preview AZURE_OPENAI_CHAT_DEPLOYMENTgpt-35-turbo AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-embedding-ada-002Azure 配置对应kotaemon.llms.AzureChatOpenAI与kotaemon.embeddings.AzureOpenAIEmbeddings源码中同样设置了temperature0与超时参数聊天 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:2bLLM或nomic-embed-textEmbedding。若在 Docker 中运行需将localhost替换为host.docker.internal才能访问宿主机服务。在 flowsettings.py 中设置LOCAL_MODEL环境变量即可自动注册ollama的 LLM、长上下文变体LCOllamaChat默认num_ctx8192与 Embedding 模型oobabooga/text-generation-webui以python server.py --api启动 OpenAI 兼容服务在 Resources 中配置api_key: dummy、base_url: http://localhost:5000/v1/、model: anyllama-cpp-python仅 LLM下载 GGUF 模型后运行LOCAL_MODELpath/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 中手动设为默认Claudekotaemon.llms.chats.LCAnthropicChat默认模型claude-3-5-sonnet-20240620Google Geminikotaemon.llms.chats.LCGeminiChat默认模型gemini-1.5-flashGroq走 OpenAI 兼容接口base_url: https://api.groq.com/openai/v1默认模型llama-3.1-8b-instantCoherekotaemon.llms.chats.LCCohereChat默认command-r-plus-08-2024同时提供 Cohere Embeddingembed-multilingual-v3.0与默认重排序模型rerank-v4.0-fastMistralOpenAI 兼容接口默认ministral-8b-latest并提供mistral-embedVoyageAIEmbeddingvoyage-3-large与重排序rerank-2。将本地模型用于 RAG 的三步操作按 本地模型配置文档 的Use local models for RAG章节配置完成后还需在 Resources 中将默认 LLM 与默认 Embedding 模型切换为本地模型为文件集合File Collection指定本地 Embedding 模型如ollama在检索设置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 GraphRAGpip install nano-graphrag若安装引入版本冲突可执行pip uninstall hnswlib chroma-hnswlib pip install chroma-hnswlib快速修复以环境变量USE_NANO_GRAPHRAGtrue启动 kotaemon在 Resources 设置中配置好默认 LLM 与 Embedding 模型NanoGraphRAG 会自动识别。方式二LightRAGpip install githttps://github.com/HKUDS/LightRAG.git同样可能引入版本冲突修复方式同上以环境变量USE_LIGHTRAGtrue启动默认 LLM 与 Embedding 模型会在 Resources 设置中被 LightRAG 自动识别。方式三MS GraphRAG非 Docker 安装pip install graphrag0.3.6 future设置 API Key使用 GraphRAG 检索器前需设置GRAPHRAG_API_KEY环境变量可直接在环境中设置或写入.env文件使用本地模型与自定义配置如需用本地模型如 Ollama或自定义默认 LLM 与其他配置请将USE_CUSTOMIZED_GRAPHRAG_SETTING环境变量设为true然后在 settings.yaml.example 中调整参数。仓库根目录的 settings.yaml.example 是一份完整的 GraphRAG 自定义配置模板关键参数包括llmtype: 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 参数chunkssize: 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_gleaningscluster_graphmax_cluster_size: 10local_search/global_search两种检索模式的调优参数如max_tokens、concurrency。该文件仅在USE_CUSTOMIZED_GRAPHRAG_SETTINGtrue时生效。从 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 中的加载器实现方案类型说明Azure Document IntelligenceAPI云端的文档智能服务Adobe PDF ExtractAPIAdobe 官方 PDF 解析 APIDocling本地开源具体接入步骤见 Docling 集成文档PaddleOCR本地开源具体接入步骤见 PaddleOCR 集成文档在 UI 中通过Settings - Retrieval Settings - File loader选择对应的加载器即可。从 pipelines.py 的IndexDocumentPipeline.get_user_settings可以看出该选项的完整取值包括default默认开源解析器adobeAdobe API图表表格提取azure-diAzure AI Document Intelligence图表表格提取doclingDocling图表表格提取paddle-structPaddleOCR PPStructureV3表格图表提取paddle-vlPaddleOCR-VLVLM 文档解析。在 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_MULTIMODALTrue # 设置新的推理流水线或修改现有流水线 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 的ReactAgentPipelineReAct 代理与 rewoo.py 的RewooAgentPipelineReWOO 代理多模态实际通过USE_MULTIMODAL环境变量控制见 flowsettings.py。其他值得关注的默认配置还包括KH_APP_DATA_DIR应用数据目录、KH_DATABASESQLite 数据库路径sqlite:///ktem_app_data/user_data/sql.db、KH_FILESTORAGE_PATH文件存储目录、KH_WEB_SEARCH_BACKENDWeb 搜索后端默认 Tavily可切换 Jina、KH_OLLAMA_URL默认http://localhost:11434/v1/、KH_GRADIO_SHARE是否生成 Gradio 公网分享链接以及用户管理开关默认用户名/密码均为admin。.env.env提供了另一种配置模型与凭据的方式上一节已详细列出各提供商的环境变量。核心要点是.env只会在首次启动时被读取并写入数据库后续修改需要进入 UI 的 Resources 页面调整。添加自定义 RAG 流水线自定义推理流水线Reasoning Pipeline查看 libs/ktem/ktem/reasoning/simple.py 中的默认流水线实现可快速了解默认 QA 流水线的工作方式并做调整在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_modevector/text/hybrid、num_retrieval检索块数、use_reranking、use_llm_rerankingLLM 相关度打分、mmr最大边际相关性去重、prioritize_table优先补充表格上下文等参数在索引侧IndexDocumentPipeline按文件扩展名路由到不同的解析器并通过TokenSplitter默认chunk_size1024、chunk_overlap256分隔符优先\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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 kotaemon：开源可定制的 RAG 文档问答框架——安装部署、模型配置与自定义流水线实战
kotaemon开源可定制的 RAG 文档问答框架——安装部署、模型配置与自定义流水线实战【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemonkotaemon 是一个开源、简洁且可定制的 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 构建的应用层包含pagesChat、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 流水线可定制 UIUI 基于 Gradio 构建可自由增删界面元素并配套有独立的 Gradio 主题默认高质量检索内置混合检索全文 向量 重排序的默认流水线保证检索质量。核心特性纵览README 中列出的关键特性均能在源码中找到对应实现特性说明源码佐证自托管文档 QA Web UI支持多用户登录、私有/公共文件集合、协作共享会话flowsettings.py 中KH_FEATURE_USER_MANAGEMENT、main.py 中LoginPage与标签页逻辑LLM 与 Embedding 统一管理支持本地模型与 OpenAI、Azure、Ollama、Groq 等 API 提供商flowsettings.py 中KH_LLMS、KH_EMBEDDINGS混合 RAG 流水线混合全文向量检索器 重排序保障检索质量pipelines.py 中DocumentRetrievalPipeline的retrieval_mode与rerankers多模态 QA支持图表、表格的问答与多模态文档解析UI 可选loaders 目录下的各类加载器、use_multimodal设置项高级引用与文档预览默认提供详细引用支持在浏览器内 PDF 查看器中高亮查看含相关度分数检索相关度低时给出警告simple.py 中show_citations_and_addons、CONTEXT_RELEVANT_WARNING_SCORE警告逻辑复杂推理方法支持问题分解、ReAct、ReWOO等基于 Agent 的推理react.py、rewoo.py可配置设置 UI检索与生成的主要参数含 Prompt可在 UI 上调整get_user_settings系列方法如 simple.py可扩展基于 Gradio 可自由定制 UI支持多种索引策略提供 GraphRAG 索引流水线示例graph 目录安装部署Docker 与源码两种方式系统要求Python 3.10Docker可选仅在使用 Docker 安装时需要Unstructured当需要处理.pdf、.html、.mhtml、.xlsx之外的文件如.doc、.docx时需要按官方说明安装unstructured及其系统依赖不同操作系统的安装步骤不同。方式一Docker 安装推荐kotaemon 提供lite与full两种镜像full版额外安装了unstructured相关包可支持.doc、.docx等更多文件类型但镜像体积更大大多数场景下lite镜像即可胜任。使用full版本docker run \ -e GRADIO_SERVER_NAME0.0.0.0 \ -e GRADIO_SERVER_PORT7860 \ -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-ollamadocker run ... ghcr.io/cinnamon/kotaemon:main-ollama使用lite版本将镜像名替换为ghcr.io/cinnamon/kotaemon:main-litedocker run ... ghcr.io/cinnamon/kotaemon:main-lite需要说明的是docker run ...中的...代表前面full示例中除镜像名以外的完整参数端口映射、数据卷挂载、环境变量等实际执行时请补全为完整命令。平台支持目前官方支持并测试linux/amd64与linux/arm64适配新款 Mac两个平台可通过--platform显式指定docker run \ -e GRADIO_SERVER_NAME0.0.0.0 \ -e GRADIO_SERVER_PORT7860 \ -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源码运行克隆仓库git clone https://github.com/Cinnamon/kotaemon cd kotaemon搭建环境二选一方案 A使用 uv推荐uv sync --python 3.10 source .venv/bin/activate方案 B使用 condaconda create -n kotaemon python3.10 conda activate kotaemon pip install -e libs/kotaemon[all] pip install -e libs/ktem创建.env文件在项目根目录创建.env以.env.example为模板。.env的作用是在应用首次启动前预配置模型例如部署到 HF Hub 的场景它只会在首次运行时用于填充数据库之后的运行不再读取。可选启用浏览器内 PDF 查看器下载 PDF.js 发行包并解压到libs/ktem/ktem/assets/prebuilt目录即可在浏览器内直接预览文档并高亮显示引用位置。启动 Web 服务python app.py应用会自动在浏览器中打开默认用户名和密码均为admin可通过 UI 添加更多用户。app.py 是整个应用的入口它从theflow.settings加载配置实例化ktem.main.App构建 Gradiodemo并调用demo.queue().launch(...)启动服务同时将GRADIO_TEMP_DIR重定向到应用数据目录下的gradio_tmp临时目录。校验模型配置进入Resources标签页的LLMs and Embeddings确认api_key是否正确从.env读取若未读取到可以直接在该界面设置。配置模型.env与 Resources 标签页.env文件是配置模型和凭据的另一种方式。在 flowsettings.py 中可以看到启动时会通过decouple.config读取这些环境变量并自动填充KH_LLMS、KH_EMBEDDINGS、KH_RERANKINGS三个字典供 UI 的 Resources 标签页使用。OpenAIOPENAI_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从 flowsettings.py 的源码看OpenAI 的聊天模型默认映射为kotaemon.llms.ChatOpenAItemperature0、timeout20Embedding 模型默认映射为kotaemon.embeddings.OpenAIEmbeddingscontext_length8191。当.env中配置了OPENAI_API_KEY且不等于占位符时该模型会自动成为默认模型。Azure OpenAIAZURE_OPENAI_ENDPOINT AZURE_OPENAI_API_KEY OPENAI_API_VERSION2024-02-15-preview AZURE_OPENAI_CHAT_DEPLOYMENTgpt-35-turbo AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-embedding-ada-002Azure 配置对应kotaemon.llms.AzureChatOpenAI与kotaemon.embeddings.AzureOpenAIEmbeddings源码中同样设置了temperature0与超时参数聊天 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:2bLLM或nomic-embed-textEmbedding。若在 Docker 中运行需将localhost替换为host.docker.internal才能访问宿主机服务。在 flowsettings.py 中设置LOCAL_MODEL环境变量即可自动注册ollama的 LLM、长上下文变体LCOllamaChat默认num_ctx8192与 Embedding 模型oobabooga/text-generation-webui以python server.py --api启动 OpenAI 兼容服务在 Resources 中配置api_key: dummy、base_url: http://localhost:5000/v1/、model: anyllama-cpp-python仅 LLM下载 GGUF 模型后运行LOCAL_MODELpath/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 中手动设为默认Claudekotaemon.llms.chats.LCAnthropicChat默认模型claude-3-5-sonnet-20240620Google Geminikotaemon.llms.chats.LCGeminiChat默认模型gemini-1.5-flashGroq走 OpenAI 兼容接口base_url: https://api.groq.com/openai/v1默认模型llama-3.1-8b-instantCoherekotaemon.llms.chats.LCCohereChat默认command-r-plus-08-2024同时提供 Cohere Embeddingembed-multilingual-v3.0与默认重排序模型rerank-v4.0-fastMistralOpenAI 兼容接口默认ministral-8b-latest并提供mistral-embedVoyageAIEmbeddingvoyage-3-large与重排序rerank-2。将本地模型用于 RAG 的三步操作按 本地模型配置文档 的Use local models for RAG章节配置完成后还需在 Resources 中将默认 LLM 与默认 Embedding 模型切换为本地模型为文件集合File Collection指定本地 Embedding 模型如ollama在检索设置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 GraphRAGpip install nano-graphrag若安装引入版本冲突可执行pip uninstall hnswlib chroma-hnswlib pip install chroma-hnswlib快速修复以环境变量USE_NANO_GRAPHRAGtrue启动 kotaemon在 Resources 设置中配置好默认 LLM 与 Embedding 模型NanoGraphRAG 会自动识别。方式二LightRAGpip install githttps://github.com/HKUDS/LightRAG.git同样可能引入版本冲突修复方式同上以环境变量USE_LIGHTRAGtrue启动默认 LLM 与 Embedding 模型会在 Resources 设置中被 LightRAG 自动识别。方式三MS GraphRAG非 Docker 安装pip install graphrag0.3.6 future设置 API Key使用 GraphRAG 检索器前需设置GRAPHRAG_API_KEY环境变量可直接在环境中设置或写入.env文件使用本地模型与自定义配置如需用本地模型如 Ollama或自定义默认 LLM 与其他配置请将USE_CUSTOMIZED_GRAPHRAG_SETTING环境变量设为true然后在 settings.yaml.example 中调整参数。仓库根目录的 settings.yaml.example 是一份完整的 GraphRAG 自定义配置模板关键参数包括llmtype: 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 参数chunkssize: 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_gleaningscluster_graphmax_cluster_size: 10local_search/global_search两种检索模式的调优参数如max_tokens、concurrency。该文件仅在USE_CUSTOMIZED_GRAPHRAG_SETTINGtrue时生效。从 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 中的加载器实现方案类型说明Azure Document IntelligenceAPI云端的文档智能服务Adobe PDF ExtractAPIAdobe 官方 PDF 解析 APIDocling本地开源具体接入步骤见 Docling 集成文档PaddleOCR本地开源具体接入步骤见 PaddleOCR 集成文档在 UI 中通过Settings - Retrieval Settings - File loader选择对应的加载器即可。从 pipelines.py 的IndexDocumentPipeline.get_user_settings可以看出该选项的完整取值包括default默认开源解析器adobeAdobe API图表表格提取azure-diAzure AI Document Intelligence图表表格提取doclingDocling图表表格提取paddle-structPaddleOCR PPStructureV3表格图表提取paddle-vlPaddleOCR-VLVLM 文档解析。在 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_MULTIMODALTrue # 设置新的推理流水线或修改现有流水线 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 的ReactAgentPipelineReAct 代理与 rewoo.py 的RewooAgentPipelineReWOO 代理多模态实际通过USE_MULTIMODAL环境变量控制见 flowsettings.py。其他值得关注的默认配置还包括KH_APP_DATA_DIR应用数据目录、KH_DATABASESQLite 数据库路径sqlite:///ktem_app_data/user_data/sql.db、KH_FILESTORAGE_PATH文件存储目录、KH_WEB_SEARCH_BACKENDWeb 搜索后端默认 Tavily可切换 Jina、KH_OLLAMA_URL默认http://localhost:11434/v1/、KH_GRADIO_SHARE是否生成 Gradio 公网分享链接以及用户管理开关默认用户名/密码均为admin。.env.env提供了另一种配置模型与凭据的方式上一节已详细列出各提供商的环境变量。核心要点是.env只会在首次启动时被读取并写入数据库后续修改需要进入 UI 的 Resources 页面调整。添加自定义 RAG 流水线自定义推理流水线Reasoning Pipeline查看 libs/ktem/ktem/reasoning/simple.py 中的默认流水线实现可快速了解默认 QA 流水线的工作方式并做调整在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_modevector/text/hybrid、num_retrieval检索块数、use_reranking、use_llm_rerankingLLM 相关度打分、mmr最大边际相关性去重、prioritize_table优先补充表格上下文等参数在索引侧IndexDocumentPipeline按文件扩展名路由到不同的解析器并通过TokenSplitter默认chunk_size1024、chunk_overlap256分隔符优先\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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考