简介

该项目既为希望对其文档进行问答的最终用户提供了一个功能齐全的 RAG 用户界面，也为希望构建自有 RAG 流程的开发者提供了支持。

+----------------------------------------------------------------------------+
| 终端用户：使用基于 `kotaemon` 构建的应用程序的人。                       |
| （您使用的是类似上述演示中的应用程序）                            |
|     +----------------------------------------------------------------+     |
|     | 开发者：使用 `kotaemon` 进行开发的人。                   |     |
|     | （您的项目中某处有 `import kotaemon`）         |     |
|     |     +----------------------------------------------------+     |     |
|     |     | 贡献者：致力于让 `kotaemon` 更完善的人员。    |     |     |
|     |     | （您向此仓库提交 PR）                         |     |     |
|     |     +----------------------------------------------------+     |     |
|     +----------------------------------------------------------------+     |
+----------------------------------------------------------------------------+

针对终端用户

• 简洁极简的界面：面向 RAG 式问答的友好用户界面。
• 支持多种 LLM：兼容 LLM API 提供商（OpenAI、Azure OpenAI、Cohere 等）以及本地 LLM（通过 ollama 和 llama-cpp-python）。
• 轻松安装：只需简单脚本即可快速上手。

针对开发者

• RAG 流程框架：帮助您构建自己的基于 RAG 的文档问答流程。
• 可定制界面：借助提供的 UI，亲眼见证您的 RAG 流程运行效果，该界面基于 Gradio 打造。
• Gradio 主题：如果您在开发中使用 Gradio，不妨试试我们的主题：kotaemon-gradio-theme。

核心特性

• 托管您自己的文档问答（RAG）Web 界面：支持多用户登录，将文件组织成私有/公有集合，协作并与他人分享您喜爱的对话。

• 管理您的 LLM 和嵌入模型：同时支持本地 LLM 和主流 API 提供商（OpenAI、Azure、Ollama、Groq 等）。

• 混合 RAG 流程：提供合理的默认 RAG 流程，结合全文检索与向量检索，并加入重排序机制，以确保最佳的检索质量。

• 多模态问答支持：可在包含图表和表格的多份文档上执行问答任务。支持多模态文档解析（UI 上可选择相应选项）。

• 高级引用与文档预览：系统默认会提供详细的引用信息，以确保 LLM 回答的准确性。您可以在带有高亮显示的 浏览器内 PDF 查看器 中直接查看引用内容（包括相关得分）。当检索流程返回相关性较低的文章时，系统会发出警告。

• 支持复杂推理方法：利用问题分解来解答复杂的多跳问题。支持基于代理的推理方式，如 ReAct、ReWOO 等代理。

• 可配置的设置界面：您可以在界面上调整检索和生成过程中的大部分重要参数（包括提示词）。

• 可扩展性：由于基于 Gradio 构建，您可以自由地自定义或添加任何所需的 UI 元素。此外，我们还计划支持多种文档索引与检索策略。作为示例，我们提供了 GraphRAG 索引流程。

安装

如果您不是开发者，只是想使用这款应用，请参阅我们易于操作的用户指南。从最新发布下载 .zip 文件，即可获得所有最新功能和错误修复。

系统要求

1. Python ≥ 3.10
2. Docker：可选，如果您希望通过Docker 安装的话。
3. Unstructured：如果您需要处理除 .pdf、.html、.mhtml 和 .xlsx 之外的其他格式文件，则需安装此工具。具体安装步骤因操作系统而异，请访问链接并按照其中提供的说明进行操作。

使用 Docker（推荐）

1. 我们支持 lite 和 full 两种版本的 Docker 镜像。使用 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 场景：

     # 将镜像名称更改为
     docker run <...> ghcr.io/cinnamon/kotaemon:main-ollama
     

   • 使用 lite 版本：

     # 将镜像名称更改为
     docker run <...> ghcr.io/cinnamon/kotaemon:main-lite
     

2. 目前我们支持并测试两个平台：linux/amd64 和 linux/arm64（适用于较新的 Mac）。您可以通过在 docker run 命令中添加 --platform 参数来指定平台。例如：

   # 在 linux/arm64 平台上运行 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 \
   --platform linux/arm64 \
   ghcr.io/cinnamon/kotaemon:main-lite
   

3. 一切设置正确后，您可以访问 http://localhost:7860/ 来使用 Web UI。

4. 我们使用 GHCR 存储 Docker 镜像，所有镜像都可以在这里找到：链接。

不使用 Docker

选项 1：使用 uv（推荐，安装速度更快）

1. 克隆仓库并运行 uv 安装脚本：

   # 克隆此仓库
   git clone https://github.com/Cinnamon/kotaemon
   cd kotaemon
   
   # 运行 uv 安装脚本（如果未安装 uv，则会自动安装）
   bash scripts/run_uv.sh
   

   该脚本将执行以下操作：

   • 如果未安装 uv 包管理器，则会自动安装。
   • 创建一个基于 Python 3.10 的虚拟环境。
   • 使用 uv 安装所有依赖项（比 conda 或 pip 快得多）。
   • 设置 PDF.js 查看器。
   • 启动应用程序。

选项 2：使用 conda（传统方法）

1. 在一个新的 Python 环境中克隆并安装所需软件包。

   # 可选（设置环境）
   conda create -n kotaemon python=3.10
   conda activate kotaemon
   
   # 克隆此仓库
   git clone https://github.com/Cinnamon/kotaemon
   cd kotaemon
   
   pip install -e "libs/kotaemon[all]"
   pip install -e "libs/ktem"
   

2. 在项目根目录下创建一个 .env 文件，以 .env.example 为模板。

   .env 文件用于在启动应用之前预先配置模型的场景（例如在 HF Hub 上部署应用）。该文件仅会在首次运行时用于填充数据库，后续运行将不再使用。

3. （可选）要启用浏览器中的 PDF_JS 查看器，下载 PDF_JS_DIST，然后将其解压到 libs/ktem/ktem/assets/prebuilt 目录中。

   

4. 启动 Web 服务器：

   python app.py
   

   • 应用程序将自动在您的浏览器中打开。
   • 默认用户名和密码均为 admin。您可以通过 UI 直接添加其他用户。

   

5. 检查“资源”选项卡中的“LLMs 和 Embeddings”，确保从 .env 文件中正确设置了 api_key 值。如果未设置，可以在该页面进行配置。

设置 GraphRAG

[!注意] 官方 MS GraphRAG 索引功能仅支持 OpenAI 或 Ollama API。 对于大多数用户，我们建议使用 NanoGraphRAG 实现，以便与 Kotaemon 更加便捷地集成。

设置本地模型（用于本地/私有 RAG）

请参阅 本地模型设置。

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

可用的选项包括：

• Azure Document Intelligence（API）
• Adobe PDF Extract（API）
• Docling（本地开源）
  • 使用 Docling 时，需先安装其依赖项：pip install docling

请在“设置 -> 检索设置 -> 文件加载器”中选择相应的加载器。

自定义您的应用

• 默认情况下，所有应用数据都存储在 ./ktem_app_data 文件夹中。您可以备份或复制此文件夹，以将您的安装迁移到新机器上。

• 对于高级用户或特定用例，您可以自定义以下文件：

  • flowsettings.py
  • .env

flowsettings.py

此文件包含您应用的配置。您可以使用此处的示例作为起点。

# 设置您偏好的文档存储（具备全文搜索功能）
KH_DOCSTORE=(Elasticsearch | LanceDB | SimpleFileDocumentStore)

# 设置您偏好的向量存储（用于基于向量的搜索）
KH_VECTORSTORE=(ChromaDB | LanceDB | InMemory | Milvus | Qdrant)

# 启用/禁用多模态问答
KH_REASONINGS_USE_MULTIMODAL=True

# 设置新的推理管道或修改现有管道。
KH_REASONINGS = [
    "ktem.reasoning.simple.FullQAPipeline",
    "ktem.reasoning.simple.FullDecomposeQAPipeline",
    "ktem.reasoning.react.ReactAgentPipeline",
    "ktem.reasoning.rewoo.RewooAgentPipeline",
]

.env

此文件提供了另一种配置模型和凭据的方式。

添加您自己的 RAG 流程

自定义推理流程

1. 查看默认流程的实现，位于这里。您可以对默认 QA 流程的工作方式进行快速调整。
2. 在 libs/ktem/ktem/reasoning/ 中添加新的 .py 实现文件，然后将其纳入 flowssettings，以便在 UI 上启用。

自定义索引流程

• 查看 libs/ktem/ktem/index/file/graph 中的示例实现。

（更多说明正在编写中）。

引用

请按以下方式引用本项目：

@misc{kotaemon2024,
    title = {Kotaemon - 一款开源的基于 RAG 的工具，可用于与任何内容对话。},
    author = {Kotaemon 团队},
    year = {2024},
    howpublished = {\url{https://github.com/Cinnamon/kotaemon}},
}

星标历史

贡献

由于我们的项目仍在积极开发中，我们非常重视您的反馈和贡献。请参阅我们的贡献指南以开始参与。感谢所有贡献者！

Kotaemon 快速上手指南

Kotaemon 是一款开源、简洁且可定制的 RAG（检索增强生成）用户界面，专为文档问答设计。它既适合终端用户直接进行文档 QA，也适合开发者构建自己的 RAG 流水线。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux (amd64/arm64) 或 macOS (arm64)。Windows 用户建议使用 WSL2 或 Docker Desktop。
• Python 版本：>= 3.10
• 可选依赖：
  • Docker：推荐使用 Docker 部署，可避免复杂的环境配置。
  • Unstructured：如果您需要处理除 .pdf, .html, .mhtml, .xlsx 以外的文件格式（如 Word 文档），需单独安装 Unstructured 库及其系统依赖。

2. 安装步骤

您可以根据需求选择 Docker 部署（推荐）或 本地源码安装。

方案 A：使用 Docker（推荐）

Docker 方式最简单，支持 lite（轻量版）和 full（完整版，支持更多文件格式）两种镜像。

1. 运行轻量版镜像（适用于大多数 PDF/HTML 场景）：

   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-lite
   

2. 运行完整版镜像（支持 .doc, .docx 等更多格式）：

   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
   

3. 访问应用： 启动成功后，在浏览器打开 http://localhost:7860/。

注意：如果是 Apple Silicon (M1/M2/M3) 芯片的 Mac，请在命令中加入 --platform linux/arm64 参数。

方案 B：本地源码安装（无 Docker）

方法 1：使用 uv（推荐，速度更快）

uv 是一个极速的 Python 包管理器。

1. 克隆仓库并运行安装脚本：

   git clone https://github.com/Cinnamon/kotaemon
   cd kotaemon
   
   # 运行脚本（自动安装 uv、创建虚拟环境、安装依赖并启动）
   bash scripts/run_uv.sh
   

方法 2：使用 Conda/Pip（传统方式）

1. 创建环境并安装依赖：

   # 创建并激活 conda 环境
   conda create -n kotaemon python=3.10
   conda activate kotaemon
   
   # 克隆代码
   git clone https://github.com/Cinnamon/kotaemon
   cd kotaemon
   
   # 安装核心库
   pip install -e "libs/kotaemon[all]"
   pip install -e "libs/ktem"
   

   (国内用户若下载慢，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华源)

2. 配置环境变量（可选）： 复制示例文件创建 .env，用于预配置模型 API Key：

   cp .env.example .env
   # 编辑 .env 文件填入您的 API Key
   

3. 配置 PDF 预览器（可选）： 若需启用浏览器内 PDF 高亮预览，请下载 PDF.js 并解压至 libs/ktem/ktem/assets/prebuilt 目录。

4. 启动服务：

   python app.py
   

   应用将自动在浏览器中打开。

3. 基本使用

启动成功后，您将进入 Gradio 构建的 Web 界面。

1. 登录系统：

   • 默认用户名：admin
   • 默认密码：admin
   • 首次登录后，建议在 UI 界面中创建新用户或修改密码。

2. 配置模型资源：

   • 点击左侧导航栏的 Resources -> LLMs and Embeddings。
   • 确保您的 LLM（大语言模型）和 Embedding（嵌入模型）已正确配置。
   • 支持配置 OpenAI、Azure、Ollama（本地模型）、Groq 等提供商。如果在 .env 中未预设，可在此处手动填入 api_key。

3. 上传文档与对话：

   • 进入 Chat 标签页。
   • 创建一个新的集合（Collection），上传您的文档（支持 PDF, HTML, Markdown 等）。
   • 系统会自动进行索引（默认采用混合检索 + 重排序策略）。
   • 在对话框中输入问题，系统将基于文档内容生成答案，并提供详细的引用来源（点击引用可在内置 PDF 阅读器中高亮显示原文）。

4. 高级功能：

   • 多模态问答：支持包含图表和表格的文档解析。
   • 复杂推理：在设置中可开启问题分解（Question Decomposition）或 Agent 模式（ReAct/ReWOO）以处理多跳推理问题。
   • GraphRAG：如需使用 GraphRAG 索引，需在启动时设置环境变量（如 USE_NANO_GRAPHRAG=true）并安装对应依赖。