# https://github.com/Cinnamon/kotaemon 项目说明书 生成时间：2026-06-22 15:43:07 UTC ## 目录 - [项目概览与系统架构](#page-overview) - [RAG 核心：加载、索引与检索](#page-rag) - [LLM、Embedding 与智能体推理](#page-models) - [前端、部署与定制化](#page-ui-deploy) ## 项目概览与系统架构 ### 相关页面 相关主题：[RAG 核心：加载、索引与检索](#page-rag), [LLM、Embedding 与智能体推理](#page-models), [前端、部署与定制化](#page-ui-deploy)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Cinnamon/kotaemon/blob/main/README.md) - [libs/kotaemon/README.md](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/README.md) - [libs/kotaemon/kotaemon/loaders/ocr_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/ocr_loader.py) - [libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py) - [libs/kotaemon/kotaemon/loaders/docling_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docling_loader.py) - [libs/kotaemon/kotaemon/loaders/docx_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docx_loader.py) - [libs/kotaemon/kotaemon/loaders/mathpix_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/mathpix_loader.py) - [libs/kotaemon/kotaemon/agents/tools/__init__.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/__init__.py) - [libs/kotaemon/kotaemon/agents/tools/mcp.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/mcp.py) - [libs/kotaemon/kotaemon/agents/tools/wikipedia.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/wikipedia.py) - [libs/kotaemon/kotaemon/agents/rewoo/agent.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/agent.py) - [libs/kotaemon/kotaemon/agents/rewoo/prompt.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/prompt.py) - [libs/ktem/ktem/utils/render.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/ktem/ktem/utils/render.py)
# 项目概览与系统架构 ## 1. 项目定位与目标用户 `kotaemon` 是一个开源、可定制的 RAG（Retrieval-Augmented Generation）文档问答系统，对终端用户和开发者都提供了清晰的切入点。仓库根目录的 `README.md` 将生态参与者划分为三层：终端用户（使用基于 kotaemon 构建的应用）、开发者（在自己的项目中 `import kotaemon`）、以及贡献者（直接向本仓库提交 PR）。资料来源：[README.md](https://github.com/Cinnamon/kotaemon/blob/main/README.md) 仓库在 `libs/kotaemon/README.md` 中进一步说明，核心包 `kotaemon` 是“可快速复用的 AI 组件”，目标是让构建 RAG 流水线变得简单；推荐使用 Conda 创建 Python 3.10 环境并以 `pip install -e ".[dev]"` 方式安装。资料来源：[libs/kotaemon/README.md](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/README.md) ## 2. 仓库顶层结构 项目采用“核心库 + 应用层”的双包结构： - `libs/kotaemon/`：可独立发布的 Python 库，提供 RAG 流水线所需的组件抽象、加载器、向量存储、LLM 适配、Agent 等。 - `libs/ktem/`：基于 Gradio 的应用层，提供多用户登录、文档集合管理、对话界面等终端用户可见的功能。 这一分层使得库可以被其他项目复用，而 UI 与状态管理逻辑被隔离在 `ktem` 中。 ## 3. 核心子系统 ### 3.1 文档加载器（Loaders） `kotaemon.loaders` 提供了多种文件解析器，统一返回 `Document` 对象并附带 `page_label` 等元数据： - `ImageReader` 通过外部 OCR HTTP 端点（`OCR_READER_ENDPOINT` 环境变量或默认值）抽取扫描型 PDF 中的文本与表格。资料来源：[libs/kotaemon/kotaemon/loaders/ocr_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/ocr_loader.py) - `PaddleOCRAdapter` 适配 PaddleOCR 家族（PPStructureV3、PaddleOCRVL）的输出结构，将 `parsing_res_list` 中的 `block_label`/`block_content` 归类为文本、表格、图片或公式。资料来源：[libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py) - `DoclingReader` 利用 docling 的页面坐标信息，将 `texts`、`tables`、`figures` 拆分为独立的 `Document` 并保留页码与文件名。资料来源：[libs/kotaemon/kotaemon/loaders/docling_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docling_loader.py) - `DocxReader` 将 DOCX 中的表格以 CSV 形式存入 `table_origin` 元数据并生成额外的非表格文本 `Document`。资料来源：[libs/kotaemon/kotaemon/loaders/docx_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docx_loader.py) - `MathpixPDFReader` 通过 Mathpix API 处理 PDF，并将表格与正文拆分到带 `page_label` 的不同 `Document` 中。资料来源：[libs/kotaemon/kotaemon/loaders/mathpix_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/mathpix_loader.py) ### 3.2 Agent 与工具 `kotaemon.agents.tools` 通过 `__init__.py` 暴露了一组统一接口的工具基类与具体实现：`BaseTool`、`ComponentTool`、`GoogleSearchTool`、`WikipediaTool`、`LLMTool` 以及 MCP 工具集。资料来源：[libs/kotaemon/kotaemon/agents/tools/__init__.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/__init__.py) `MCPTool` 是面向 Model Context Protocol 服务的适配层：`_json_schema_type_to_python` 将 JSON Schema 类型映射为 Python 类型，`build_args_model` 动态生成 Pydantic 参数模型，使任意 MCP 工具都能被 Agent 调度。资料来源：[libs/kotaemon/kotaemon/agents/tools/mcp.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/mcp.py) `WikipediaTool` 封装 `wikipedia` Python 包：在 `PageError` 或 `DisambiguationError` 时返回相似条目，否则返回带 `page` URL 元数据的 `Document`。资料来源：[libs/kotaemon/kotaemon/agents/tools/wikipedia.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/wikipedia.py) `ReWOOAgent` 沿“规划—执行—求解”三阶段推进：`planner` 生成 `#Plan1/#E1` 形式的步骤，worker 并发调用工具并把结果写回 `worker_log`，最后由 `solver` 综合输出，并可在 `use_citation=True` 时附加 `CitationPipeline` 输出。资料来源：[libs/kotaemon/kotaemon/agents/rewoo/agent.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/agent.py) 其提示词模板（含 zero/few-shot 变体）定义在 `prompt.py` 中。资料来源：[libs/kotaemon/kotaemon/agents/rewoo/prompt.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/prompt.py) ### 3.3 UI 渲染 `libs/ktem/ktem/utils/render.py` 提供了把 `RetrievedDocument` 转为 HTML 的工具集：`Render.collapsible` 生成可折叠证据块，`get_header` 自动拼接 `[Page X]` 与 `file_name`，并通过 `GR_FILE_ROOT_PATH` 环境变量构造 PDF 预览链接（同时根据 `fast_langdetect` 的语言结果决定高亮策略）。资料来源：[libs/ktem/ktem/utils/render.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/ktem/ktem/utils/render.py) ## 4. 整体数据流 ```mermaid flowchart LR U[用户] --> UI[Gradio UI / ktem] UI --> AG[ReWOO / ReAct Agent] AG --> TL[kotaemon.agents.tools] TL --> MCP[MCP 服务] TL --> EXT[Wikipedia / Google] UI --> LD[kotaemon.loaders] LD --> DOC[Document + 元数据] DOC --> VS[向量库 / 检索器] VS --> AG AG --> AN[答案 + Citation] AN --> UI ``` ## 5. 社区关注点与扩展方向 - **本地部署体验**：Issue #138 反映 Apple Silicon (M1) 用户在 Docker 镜像外的本地安装流程缺乏文档，需要参照 `libs/kotaemon/README.md` 中的 Conda + `pip install -e ".[dev]"` 步骤。资料来源：[Issue #138](https://github.com/Cinnamon/kotaemon/issues/138) - **新增 LLM Provider**：社区对 AWS Bedrock（#392，使用 Converse API 接入 Anthropic、Meta、Mistral、Cohere 等）以及 Gemini（#160）有明确需求，但目前仓库文档中列出的 Provider 仍以 OpenAI、AzureOpenAI、Cohere、Ollama、llama-cpp-python 为主。资料来源：[Issue #392](https://github.com/Cinnamon/kotaemon/issues/392)、[Issue #160](https://github.com/Cinnamon/kotaemon/issues/160) - **GraphRAG 替代实现**：Issue #243 提出集成 `nano-graphrag` 等更轻量的 GraphRAG 后端。资料来源：[Issue #243](https://github.com/Cinnamon/kotaemon/issues/243) - **FastAPI 端点**：Issue #647 提议在 Docker 镜像中暴露 FastAPI，以便将 GUI 与程序化调用解耦。资料来源：[Issue #647](https://github.com/Cinnamon/kotaemon/issues/647) - **多模态加载器**：v0.12.0 版本日志显示 PaddleOCR 已作为新的文档加载器集成，聊天与索引 UI 也获得增强。资料来源：[Release v0.12.0](https://github.com/Cinnamon/kotaemon/releases) ## See Also - 文档加载器与 OCR 适配详情 - ReWOO Agent 与 MCP 工具集成 - Gradio 应用层（ktem）多用户与渲染管线 --- ## RAG 核心：加载、索引与检索 ### 相关页面 相关主题：[项目概览与系统架构](#page-overview), [LLM、Embedding 与智能体推理](#page-models), [前端、部署与定制化](#page-ui-deploy)
相关源码文件 以下源码文件用于生成本页说明： - [libs/kotaemon/README.md](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/README.md) - [README.md](https://github.com/Cinnamon/kotaemon/blob/main/README.md) - [libs/kotaemon/kotaemon/loaders/ocr_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/ocr_loader.py) - [libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py) - [libs/kotaemon/kotaemon/loaders/docling_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docling_loader.py) - [libs/kotaemon/kotaemon/loaders/docx_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docx_loader.py) - [libs/kotaemon/kotaemon/loaders/mathpix_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/mathpix_loader.py) - [libs/kotaemon/kotaemon/loaders/utils/pdf_ocr.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/utils/pdf_ocr.py) - [libs/ktem/ktem/utils/render.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/ktem/ktem/utils/render.py) - [libs/kotaemon/kotaemon/agents/tools/mcp.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/mcp.py) - [libs/kotaemon/kotaemon/agents/rewoo/agent.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/agent.py)
# RAG 核心：加载、索引与检索 ## 概述 kotaemon 是一个面向终端用户与开发者的开源 RAG 问答 UI/框架，其核心目标是把任意格式的文档通过统一的 `Document` 抽象加载、切分、向量化，进而在用户提问时执行混合检索与重排序，最终把相关证据送入 LLM 生成答案。资料来源：[README.md:9-18]() 将项目明确定位为"an open-source clean & customizable RAG UI for chatting with your documents"。资料来源：[libs/kotaemon/README.md:3-7]() 进一步说明 `kotaemon` 是构建 RAG 流水线所需的 AI 组件库。 整个 RAG 核心由三个相互衔接的阶段组成：**文档加载（Loading）→ 索引（Indexing）→ 检索（Retrieval）**。前两个阶段发生在用户上传文件时，检索阶段则在每次用户对话时执行。 ## 文档加载层 `kotaemon/loaders/` 子包提供多格式、可插拔的加载器，所有加载器都最终产出 `Document` 对象列表，并保留 `page_label`、`file_name`、`type`（text/table/figure）等元数据，便于后续按页定位。 ### 多格式加载器 | 加载器 | 适用场景 | 关键能力 | | --- | --- | --- | | `DocxReader` | Word 文档 | 提取段落与表格，表格以 CSV 形式写入 `table_origin` 元数据 资料来源：[libs/kotaemon/kotaemon/loaders/docx_loader.py:39-58]() | | `DoclingReader` | PDF/Office 复杂版面 | 使用 Docling 解析版面，把 bbox 从 bottom-left 转换为 top-left 坐标 资料来源：[libs/kotaemon/kotaemon/loaders/docling_loader.py:124-136]() | | `MathpixReader` | 含数学公式的 PDF | 同步提取页面文本与公式（LaTeX），保留 `page_number` 元数据 资料来源：[libs/kotaemon/kotaemon/loaders/mathpix_loader.py:60-80]() | ### OCR 集成 对于扫描件或图片型 PDF，kotaemon 提供两套 OCR 路径。`ImageReader`（位于 `ocr_loader.py`）通过调用外部 FullOCR 端点（默认 `http://127.0.0.1:8000/v2/ai/infer/`，可通过环境变量 `OCR_READER_ENDPOINT` 覆盖）抽取图片与表格 资料来源：[libs/kotaemon/kotaemon/loaders/ocr_loader.py:60-80]()。在 v0.12.0 版本中，社区新增了 PaddleOCR 加载器，其 `PaddleOCRAdapter` 将 `PPStructureV3`/`PaddleOCRVL` 的原始输出按 `text_labels`、`table_labels`、`image_labels`、`formula_labels` 分类，并对 figure 进行裁剪与 base64 编码 资料来源：[libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py:18-46]()。两个 OCR 流水线之间还提供了 `merge_ocr_and_pdf_texts` 工具，基于 IOU 重叠度合并 OCR 与原生 PDF 文本，避免重复 资料来源：[libs/kotaemon/kotaemon/loaders/utils/pdf_ocr.py:84-110]()。 ## 索引与检索流程 加载器输出的 `Document` 流经索引流水线（切片 → embedding → 写入向量库）后，会在用户提问时触发检索。下面是端到端数据流： ```mermaid flowchart LR A[原始文件
PDF/DOCX/Image] --> B[Loader
多格式解析] B --> C[Document 列表
含 page_label/type] C --> D[Chunking & Embedding] D --> E[(向量库 + 全文索引)] F[用户问题] --> G[Hybrid Retriever
向量 + BM25] E --> G G --> H[Re-ranker] H --> I[LLM 生成答案] I --> J[Render 渲染
可折叠证据] ``` 检索阶段采用"向量召回 + 全文召回 + 重排序"的混合策略，这是 README 中"Hybrid RAG pipeline"的默认实现 资料来源：[README.md:43-46]()。在多步推理场景下，ReWOO Agent 会先调用 `planner` 生成 `#Plan` / `#E` 计划，再让 worker 串行执行工具调用（如 `MCPTool`、`WikipediaTool`），最后由 `solver` 综合证据得出结论 资料来源：[libs/kotaemon/kotaemon/agents/rewoo/agent.py:96-122]()。MCP 工具通过 `build_args_model` 把 MCP Server 的 JSON Schema 动态转成 Pydantic 模型，从而无缝接入同一套检索/Agent 框架 资料来源：[libs/kotaemon/kotaemon/agents/tools/mcp.py:25-40]()。 ## 渲染与展示 检索到的证据最终要在 Gradio UI 中以可折叠、含页码定位的方式呈现。`ktem.utils.render.Render` 负责把 `RetrievedDocument` 渲染为 HTML：它会从元数据中读取 `page_label` 与 `file_name` 作为标题，PDF 还会附带一个 `data-page` 属性的 `[Preview]` 链接，点击后跳转到对应页 资料来源：[libs/ktem/ktem/utils/render.py:30-39]() 与 资料来源：[libs/ktem/ktem/utils/render.py:90-115]()。这种"证据 + 预览"双视图是 kotaemon 区别于纯命令行 RAG 框架的关键体验。 ## 常见问题 - **Docker 镜像与本地安装差异**：社区反馈官方 Docker 镜像在 Apple Silicon 上不可用，建议在 M1/M2 Mac 上直接 `pip install -e ".[dev]"` 进行本地部署 资料来源：[README.md:9-18]()。 - **OCR 后端选择**：如需识别公式或复杂版面，优先选择 Mathpix；如需中文场景的版面分析，v0.12.0 新增的 PaddleOCR 加载器是更轻量的替代方案 资料来源：[libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py:18-46]()。 - **检索质量调优**：可在 UI 中替换 embedding 模型或重排序模型，无需修改任何加载器代码，因为所有加载器只产出统一的 `Document` 抽象。 ## See Also - [README.md](https://github.com/Cinnamon/kotaemon/blob/main/README.md) — 项目总览与功能列表 - [libs/kotaemon/README.md](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/README.md) — `kotaemon` 组件库安装与开发指南 - `libs/ktem/` — Gradio 应用层（含 UI 页面、用户管理、对话流程） - `libs/kotaemon/kotaemon/agents/` — ReAct / ReWOO Agent 实现 - `libs/kotaemon/kotaemon/loaders/` — 全部文档加载器入口 --- ## LLM、Embedding 与智能体推理 ### 相关页面 相关主题：[项目概览与系统架构](#page-overview), [RAG 核心：加载、索引与检索](#page-rag), [前端、部署与定制化](#page-ui-deploy)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Cinnamon/kotaemon/blob/main/README.md) - [libs/kotaemon/README.md](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/README.md) - [libs/kotaemon/kotaemon/agents/tools/__init__.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/__init__.py) - [libs/kotaemon/kotaemon/agents/tools/mcp.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/mcp.py) - [libs/kotaemon/kotaemon/agents/tools/wikipedia.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/wikipedia.py) - [libs/kotaemon/kotaemon/agents/rewoo/agent.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/agent.py) - [libs/kotaemon/kotaemon/agents/rewoo/prompt.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/prompt.py) - [libs/ktem/ktem/utils/render.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/ktem/ktem/utils/render.py)
# LLM、Embedding 与智能体推理 ## 概述与组件定位 kotaemon 是一个面向终端用户与开发者的开源 RAG 用户界面。在系统中，**LLM 与 Embedding 模型**承担"生成"与"语义表示"的职责，**智能体推理层**则负责"调度"与"多步决策"。README 明确写道：项目"支持本地 LLM 与主流 API 提供商（OpenAI、Azure、Ollama、Groq）"，并"使用问题分解回答复杂/多跳问题，且支持基于代理的推理（`ReAct`、`ReWOO` 等代理）"（资料来源：[README.md:37-49]()）。 智能体层的核心代码位于 `libs/kotaemon/kotaemon/agents/`，主要包含 `tools/`（工具集合）与 `rewoo/`（ReWOO 代理实现）两个子包；前端的证据渲染则由 `libs/ktem/ktem/utils/render.py` 提供 HTML 折叠块、表格与标题生成能力。 ## LLM 与 Embedding 接入 README 在 *Key Features* 中总结了接入策略： - **多模型组织**：用户可在 UI 中切换本地 LLM（Ollama、llama-cpp-python）或 API 提供商（OpenAI、Azure、Groq 等）（资料来源：[README.md:46-49]()）。 - **混合 RAG 默认管道**：结合全文本检索与向量检索，并由 re-ranker 保证召回质量（资料来源：[README.md:50-52]()）。 - **多模态问答**：可对带图表的文档进行问答，并支持多种文档解析后端（资料来源：[README.md:53-56]()）。 社区请求反映出接入面仍在扩张：例如 #392 要求增加 **AWS Bedrock**（通过 Converse API 接入 Anthropic、Meta、Mistral、Cohere 等），#160 要求支持 **Google Gemini API**。这些均显示"模型无关"适配层是当前重点演进方向。开发者在二次开发时应遵循 `libs/kotaemon/README.md` 的流程：创建 conda 环境、克隆仓库、`pip install -e ".[dev]"`（资料来源：[libs/kotaemon/README.md:11-23]()）。 ## 智能体推理框架 ### ReWOO 代理工作流 `libs/kotaemon/kotaemon/agents/rewoo/agent.py` 实现了 ReWOO 的"规划 → 执行 → 求解"三阶段流程，整体数据流如下： ```mermaid flowchart LR U[用户问题] --> P[Planner LLM] P -->|Plan+E 序列| Parse[解析计划与证据映射] Parse --> W[Worker 调用工具] W -->|worker_log| S[Solver LLM] S --> Cite[CitationPipeline 可选] Cite --> Out[AgentOutput] ``` 具体执行逻辑： 1. **规划（Plan）**：调用 `self.planner(instruction)` 让 LLM 输出多步计划与对应工具调用，解析为 `plan_to_es`（计划→证据映射）与 `plans`（资料来源：[libs/kotaemon/kotaemon/agents/rewoo/agent.py:18-30]()）。 2. **执行（Work）**：`_get_worker_evidences` 真正调用外部工具，把每条证据的回写日志整理为 `worker_log`（资料来源：[libs/kotaemon/kotaemon/agents/rewoo/agent.py:31-45]()）。 3. **求解（Solve）**：`self.solver(instruction, worker_log)` 汇总计划与证据生成最终回答；若 `use_citation=True`，再经 `CitationPipeline` 抽取引用（资料来源：[libs/kotaemon/kotaemon/agents/rewoo/agent.py:46-58]()）。 最终结果被包装为 `AgentOutput`，包含文本、代理类型、状态、总 token 与总成本，以及可选的 `citation` 字段。`stream` 方法以同样的三阶段结构支持流式输出（资料来源：[libs/kotaemon/kotaemon/agents/rewoo/agent.py:60-78]()）。 ### 工具系统（Tools） `libs/kotaemon/kotaemon/agents/tools/__init__.py` 统一导出工具抽象与具体实现（资料来源：[libs/kotaemon/kotaemon/agents/tools/__init__.py:1-15]()）： | 工具 | 作用 | 关键源文件 | | --- | --- | --- | | `BaseTool` / `ComponentTool` | 工具基类与组件式封装 | `tools/base.py` | | `LLMTool` | 以另一个 LLM 作为工具 | `tools/llm.py` | | `GoogleSearchTool` | 通过 Google 搜索获取外部证据 | `tools/google.py` | | `WikipediaTool` | 检索维基百科条目 | `tools/wikipedia.py` | | `MCPTool` | 桥接 Model Context Protocol 服务 | `tools/mcp.py` | `WikipediaTool` 在 `wikipedia.py` 中调用 `wikipedia` Python 包：若页面存在则返回内容与 URL，否则返回 `Could not find [...]` 与相似条目列表（资料来源：[libs/kotaemon/kotaemon/agents/tools/wikipedia.py:10-32]()）。其参数由 `WikipediaArgs` 定义，强制 `query` 字段，将任意字符串安全映射为 Pydantic 校验后的输入（资料来源：[libs/kotaemon/kotaemon/agents/tools/wikipedia.py:34-43]()）。 ### MCP 工具集成 `tools/mcp.py` 把 MCP SDK 的工具 schema 桥接到 `BaseTool`，让 ReAct/ReWOO 代理透明使用任意 MCP 服务器暴露的能力。模块提供： - `_json_schema_type_to_python`：将 JSON Schema 类型映射到 Python 原生类型（资料来源：[libs/kotaemon/kotaemon/agents/tools/mcp.py:36-46]()）。 - `build_args_model`：依据 `input_schema` 动态构建 Pydantic 模型，使每个 MCP 工具具备类型安全的参数 schema（资料来源：[libs/kotaemon/kotaemon/agents/tools/mcp.py:48-65]()）。 - 同时导出 `discover_tools_info`、`create_tools_from_config`、`parse_mcp_config`、`format_tool_list` 等辅助函数，便于在配置文件中声明 MCP 服务并自动装配工具列表（资料来源：[libs/kotaemon/kotaemon/agents/tools/mcp.py:1-15]()）。 ## 提示词模板与求解策略 `libs/kotaemon/kotaemon/agents/rewoo/prompt.py` 定义 ReWOO 的核心提示词： - **规划提示词**（默认与 `few_shot_planner_prompt`）：要求 LLM 输出 `#Plan1: ... #E1: toolname[input]` 序列，并显式说明"每条证据存入不同变量 `#E1, #E2, #E3 …` 以便后续工具调用引用"（资料来源：[libs/kotaemon/kotaemon/agents/rewoo/prompt.py:1-40]()）。 - **求解提示词**（`zero_shot_solver_prompt` / `few_shot_solver_prompt`）：把规划与证据拼接为"先做…再…，所以…"的总结形式，并要求以 `{lang}` 指定的语言输出（资料来源：[libs/kotaemon/kotaemon/agents/rewoo/prompt.py:42-80]()）。 模板通过 `PromptTemplate` 注入可用工具描述（`{tool_description}`）与任务（`{task}`），实现"工具集合动态拼装 + 规划/求解解耦"的工程模式。 ## 引用与协同渲染 推理结果在 UI 中呈现时，`libs/ktem/ktem/utils/render.py` 提供统一 HTML 渲染器： - `Render.collapsible` 将每条证据渲染为 `
` 折叠块，便于在答案中并列展示多份引用（资料来源：[libs/ktem/ktem/utils/render.py:32-40]()）。 - `get_header` 从 `RetrievedDocument.metadata` 抽取 `page_label` 与 `file_name`，生成形如 `[Page 3] report.pdf` 的证据标题（资料来源：[libs/ktem/ktem/utils/render.py:22-30]()）。 - `Render.table` 把 Markdown 表格经 `markdown.markdown` 转 HTML，并预先用 `replace_mardown_header` 替换 `#` 标题，防止误解析（资料来源：[libs/ktem/ktem/utils/render.py:3-12, 41-50]()）。 ## 失败模式与排障提示 - **MCP 工具不可用**：若未安装 MCP SDK，`tools/mcp.py` 的导入将失败；需确认 `libs/kotaemon/README.md` 中 `pip install -e ".[dev]"` 已完整执行（资料来源：[libs/kotaemon/README.md:11-23]()）。 - **Wikipedia 工具缺包**：`WikipediaTool` 在缺失 `wikipedia` 包时抛出 `ValueError`，提示执行 `pip install wikipedia`（资料来源：[libs/kotaemon/kotaemon/agents/tools/wikipedia.py:11-18]()）。 - **ReWOO 计划解析失败**：若 LLM 输出不符合 `#Plan` / `#E` 格式，`_parse_plan_map` 与 `_parse_planner_evidences` 可能返回空，使 `worker_log` 为空；建议保留 few-shot 示例以稳定格式（资料来源：[libs/kotaemon/kotaemon/agents/rewoo/prompt.py:21-40]()）。 ## See Also - 文档加载与解析（PaddleOCR、Docling、Mathpix、Web、DocX、OCR） - 检索与重排序管道 - Gradio UI 与多用户协作 - AWS Bedrock / Gemini 等模型提供商的扩展请求（#392、#160） --- ## 前端、部署与定制化 ### 相关页面 相关主题：[项目概览与系统架构](#page-overview), [RAG 核心：加载、索引与检索](#page-rag), [LLM、Embedding 与智能体推理](#page-models)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Cinnamon/kotaemon/blob/main/README.md) - [libs/kotaemon/README.md](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/README.md) - [libs/ktem/ktem/utils/render.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/ktem/ktem/utils/render.py) - [libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py) - [libs/kotaemon/kotaemon/loaders/ocr_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/ocr_loader.py) - [libs/kotaemon/kotaemon/loaders/docling_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docling_loader.py) - [libs/kotaemon/kotaemon/loaders/docx_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/docx_loader.py) - [libs/kotaemon/kotaemon/loaders/mathpix_loader.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/mathpix_loader.py) - [libs/kotaemon/kotaemon/agents/tools/__init__.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/__init__.py) - [libs/kotaemon/kotaemon/agents/tools/mcp.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/mcp.py) - [libs/kotaemon/kotaemon/agents/rewoo/agent.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/agent.py) - [libs/kotaemon/kotaemon/agents/rewoo/prompt.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/rewoo/prompt.py)
# 前端、部署与定制化 ## 一、概述 kotaemon 是一个面向终端用户与开发者的开源 RAG（检索增强生成）UI 框架。终端用户可以使用它直接与文档对话，开发者可以基于其组件构建自定义的 RAG 流水线。在前端层面，kotaemon 基于 Gradio 构建可定制的 UI；在部署层面，项目提供本地 pip 安装、conda 环境与 Docker 镜像三种主要途径；在定制化层面，框架通过解耦的 Loader、Tool、Agent 与渲染工具，便于扩展新的数据源、模型与交互行为。资料来源：[README.md:1-50]()。 ## 二、前端渲染与交互管线 前端的职责集中在将检索结果（`RetrievedDocument`）与聊天内容渲染为可阅读的 HTML。`Render` 工具类负责多种渲染样式：可折叠证据块（`collapsible`）、Markdown 表格（`table`）、PDF 高亮链接、`` 标签（`highlight`）和图片（`image`）等。资料来源：[libs/ktem/ktem/utils/render.py:1-100]()。 `get_header` 工具会根据元数据中的 `page_label` 与 `file_name` 拼装证据标题，例如 ` [Page 3] report.pdf`，并最终通过 `Render.collapsible` 形成可折叠 HTML 片段。资料来源：[libs/ktem/ktem/utils/render.py:24-31]()。`preview_pdf` 还会通过 `fast_langdetect` 推断文本语言，针对非中日韩文本自动选择高亮片段并生成可在 PDF 阅读器中跳转的 `` 锚点。资料来源：[libs/ktem/ktem/utils/render.py:50-100]()。 ```mermaid flowchart LR A[用户提问] --> B[Gradio ChatPanel] B --> C[RAG Pipeline] C --> D[RetrievedDocument] D --> E[Render 工具] E --> F[collapsible/table/highlight] F --> G[Gradio Markdown 渲染] G --> H[浏览器展示] ``` ## 三、部署方式 | 部署方式 | 关键步骤 | 适用场景 | 资料来源 | | --- | --- | --- | --- | | 本地 pip | `pip install kotaemon@git+ssh://...` + `pip install -e ".[dev]"` | 二次开发与单元测试 | [libs/kotaemon/README.md:5-20]() | | Conda 环境 | `conda create -n kotaemon python=3.10` | 多版本 Python 隔离 | [libs/kotaemon/README.md:15-25]() | | Docker 镜像 | 官方预构建镜像 + 端口映射 | 快速体验与团队分发 | [README.md:1-30]() | | Hugging Face Spaces | 直接运行 Live Demo | 演示与分享 | [README.md:8-10]() | 社区中 M1 Mac 用户曾反馈 Docker 镜像落后于主分支且与 `arm64` 平台不兼容（Issue #138），因此在 Apple Silicon 上更推荐使用本地 pip + Conda 的方式。资料来源：[README.md:1-30]()。 ## 四、扩展与定制化 ### 4.1 文档加载器 kotaemon 内置多种 Loader，可通过新增模块加入 `kotaemon/loaders/` 目录进行扩展。例如 `PaddleOCRAdapter` 接收 `PPStructureV3` 或 `PaddleOCRVL` 的原始结果，将 `parsing_res_list` 转换为 `Document` 对象，并根据 `block_label` 区分文本、表格、图像与公式。资料来源：[libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py:1-50]()。`OCRReader` 通过 `OCR_READER_ENDPOINT` 环境变量连接外部 OCR 服务，用于从扫描 PDF 中提取文本与表格。资料来源：[libs/kotaemon/kotaemon/loaders/ocr_loader.py:40-70]()。`DocxReader` 使用 `docx` 解析 DOCX 文件中的表格与非表格文本，分别以 `type: table` 与 `type: text` 的元数据标记。资料来源：[libs/kotaemon/kotaemon/loaders/docx_loader.py:1-50]()。 ### 4.2 Agent 与工具 `kotaemon/agents/tools/__init__.py` 集中暴露了 `BaseTool`、`ComponentTool`、`LLMTool`、`GoogleSearchTool`、`WikipediaTool` 与 `MCPTool` 等可插拔工具。资料来源：[libs/kotaemon/kotaemon/agents/tools/__init__.py:1-25]()。`MCPTool` 通过 `build_args_model` 把 MCP Server 返回的 JSON Schema 转成 Pydantic 模型，并支持 `parse_mcp_config` / `create_tools_from_config` 进行批量发现。资料来源：[libs/kotaemon/kotaemon/agents/tools/mcp.py:1-50]()。`ReWOOAgent` 在 `_get_worker_evidence` 中按计划并行调用这些工具，并在 `Solver` 阶段结合 `zero_shot_solver_prompt` 或 `few_shot_solver_prompt` 汇总证据输出最终答案。资料来源：[libs/kotaemon/kotaemon/agents/rewoo/agent.py:1-50]()、[libs/kotaemon/kotaemon/agents/rewoo/prompt.py:1-50]()。 ### 4.3 LLM 提供方扩展 社区多次请求增加新的 LLM 提供方（Issue #160 Gemini、Issue #392 AWS Bedrock）。`LLMTool` 抽象了推理接口，结合 `ComponentTool` 与配置层，可在不改动前端的情况下接入 OpenAI、Azure、Cohere、Ollama 等不同后端。资料来源：[libs/kotaemon/kotaemon/agents/tools/__init__.py:1-25]()。 ### 4.4 渲染层定制 若需要改变证据展示样式，可在 `Render` 类中新增静态方法并在聊天面板中调用。例如新增加 `Render.code_block(text, language)`，即可在 UI 中以语法高亮形式展示代码片段，而无需改动 RAG 流水线。资料来源：[libs/ktem/ktem/utils/render.py:1-100]()。 ## 五、常见问题与最佳实践 - **Docker 镜像与平台不匹配**：在 Apple Silicon 上避免使用过时镜像，优先本地安装。资料来源：[README.md:1-30]()。 - **OCR 端点未启动**：`OCRReader` 默认指向 `http://127.0.0.1:8000/v2/ai/infer/`，启动前需确认服务在线。资料来源：[libs/kotaemon/kotaemon/loaders/ocr_loader.py:40-70]()。 - **扩展 Loader 后未生效**：确认新模块已加入 `kotaemon/loaders/` 命名空间，并按 `BaseReader` 接口实现 `load_data`。资料来源：[libs/kotaemon/kotaemon/loaders/docling_loader.py:1-50]()。 - **自定义 MCP 工具**：使用 `build_args_model` 自动生成参数模型，避免手写 Pydantic。资料来源：[libs/kotaemon/kotaemon/agents/tools/mcp.py:1-50]()。 ## See Also - 项目主页与用户指南：[README.md](https://github.com/Cinnamon/kotaemon/blob/main/README.md) - 开发者贡献流程：[libs/kotaemon/README.md](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/README.md) - 文档加载器集合：[libs/kotaemon/kotaemon/loaders/](https://github.com/Cinnamon/kotaemon/tree/main/libs/kotaemon/kotaemon/loaders) - Agent 工具注册：[libs/kotaemon/kotaemon/agents/tools/__init__.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/tools/__init__.py) - 前端渲染工具：[libs/ktem/ktem/utils/render.py](https://github.com/Cinnamon/kotaemon/blob/main/libs/ktem/ktem/utils/render.py) --- --- ## Doramagic 踩坑日志 项目：Cinnamon/kotaemon 摘要：发现 12 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Windows Install fails with ImportError: cannot import name 'HfFolder' from 'huggingface_hub'。 ## 1. 安装坑 · 来源证据：Windows Install fails with ImportError: cannot import name 'HfFolder' from 'huggingface_hub' - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Install fails with ImportError: cannot import name 'HfFolder' from 'huggingface_hub' - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/833 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安全/权限坑 · 来源证据：Sanitize PaddleOCR table HTML before storage and UI render - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Sanitize PaddleOCR table HTML before storage and UI render - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/834 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 依赖 Docker 环境 - 严重度：medium - 证据强度：runtime_trace - 发现：安装/运行入口包含 Docker 命令：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 - 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。 - 复现命令：`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` - 证据：identity.distribution | https://github.com/Cinnamon/kotaemon | 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 ## 4. 安装坑 · 来源证据：[BUG] it give no quickstart ! - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] it give no quickstart ! - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/839 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：[DOCS] README references missing `scripts/run_uv.sh` (uv installation path) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[DOCS] README references missing `scripts/run_uv.sh` (uv installation path) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/821 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/Cinnamon/kotaemon | README/documentation is current enough for a first validation pass. ## 7. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Cinnamon/kotaemon | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Cinnamon/kotaemon | no_demo; severity=medium ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Cinnamon/kotaemon | no_demo; severity=medium ## 10. 安全/权限坑 · 来源证据：[BUG] i requested security bug, please check !!!!! - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] i requested security bug, please check !!!!! - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/841 | 来源类型 github_issue 暴露的待验证使用条件。 ## 11. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Cinnamon/kotaemon | issue_or_pr_quality=unknown ## 12. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Cinnamon/kotaemon | release_recency=unknown