Kotaemon：本地文档问答的开源RAG框架

Kotaemon：本地文档问答的开源RAG框架 | 前端进阶之旅

Full translation

完整中文译文

Kotaemon：一个用于与文档聊天的开源 RAG 工具

一个开源的清洁、可定制 RAG UI，用于与您的文档聊天。为最终用户和开发者而设计。

Live Demo #1 | Live Demo #2 | Online Install | Colab Notebook (Local RAG)

User Guide | Developer Guide | Feedback | Contact

该项目既可作为最终用户对其文档进行问答的功能性 RAG UI，也可作为开发者构建自己 RAG 管道的工具。

+----------------------------------------------------------------------------+
| End users: Those who use apps built with `kotaemo`.                        |
| (You use an app like the one in the demo above)                            |
|     +----------------------------------------------------------------+     |
|     | Developers: Those who built with `kotaemo`.                   |     |
|     | (You have `import kotaemo` somewhere in your project)         |     |
|     |     +----------------------------------------------------+     |     |
|     |     | Contributors: Those who make `kotaemo` better.    |     |     |
|     |     | (You make PR to this repo)                         |     |     |
|     |     +----------------------------------------------------+     |     |
|     +----------------------------------------------------------------+     |
+----------------------------------------------------------------------------+

清洁且极简的 UI：一个用户友好的基于 RAG 的问答界面。

支持各种 LLM：兼容 LLM API 提供商（OpenAI、AzureOpenAI、Cohere 等）和本地 LLM（通过 ollama 和 llama-cpp-python）。

简易安装：简单的脚本让您快速入门。

RAG 管道框架：用于构建您自己的基于 RAG 的文档问答管道的工具。

可定制的 UI：使用提供的 UI（使用 Gradio 构建）查看您的 RAG 管道的运行情况。

Gradio 主题：如果您在开发中使用 Gradio，请查看我们的主题：kotaemo-gradio-theme。

托管您自己的文档问答 (RAG) Web UI：支持多用户登录、将您的文件组织在私有/公开集合中、与他人协作和分享您最喜欢的聊天。

组织您的 LLM 和嵌入模型：支持本地 LLM 和流行的 API 提供商（OpenAI、Azure、Ollama、Groq）。

混合 RAG 管道：智能的默认 RAG 管道，具有混合（全文和向量）检索器以及重新排名，以确保最佳检索质量。

多模态问答支持：在多个文档上执行问答，支持图表和表格。支持多模态文档解析（UI 上可选择的选项）。

带有文档预览的高级引用：默认情况下，系统将提供详细的引用以确保 LLM 答案的正确性。在浏览器内 PDF 查看器中直接查看您的引用（包括相关性分数）并突出显示。当检索管道返回低相关性文章时进行警告。

支持复杂推理方法：使用问题分解来回答您的复杂/多跳问题。支持基于 AI 智能体的推理，包括 ReAct、ReWOO 和其他 AI 智能体。

可配置的设置 UI：您可以在 UI 上调整检索和生成过程的最重要方面（包括提示词）。

可扩展：基于 Gradio 构建，您可以自由自定义或添加任何 UI 元素。此外，我们的目标是支持多种文档索引和检索策略。提供 GraphRAG 索引管道作为示例。

如果您不是开发者，只想使用应用程序，请查看我们易于跟随的用户指南。从最新版本下载 .zip 文件以获取所有最新功能和错误修复。

安装

Docker：可选，如果您使用 Docker 安装

Unstructured（如果您想处理除 .pdf、.html、.mhtml 和 .xlsx 以外的文件）。安装步骤因操作系统而异。请访问链接并按照那里提供的具体说明进行操作。

使用 Docker（推荐）

我们支持 Docker 镜像的轻量版和完整版。完整版将安装额外的 unstructured 包，可支持其他文件类型（.doc、.docx 等），但代价是更大的 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/kotaemo:main-full

使用包含 Ollama 的完整版进行本地/私有 RAG

# change image name to
docker run <...> ghcr.io/cinnamon/kotaemo:main-ollama

使用轻量版

 # change image name to
 docker run <...> ghcr.io/cinnamon/kotaemo:main-lite

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

# To run docker with platform linux/arm64
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/kotaemo:main-lite

完成一切设置后，您可以访问 http://localhost:7860/ 来访问 WebUI。

我们使用 GHCR 存储 docker 镜像，所有镜像都可以在这里找到。

从源代码安装

克隆仓库

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

设置环境

选项 1：使用 uv（推荐）

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

选项 2：使用 conda

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

pip install -e "libs/kotaemon[all]"
pip install -e "libs/ktem"

在此项目的根目录创建 .env 文件。以 .env.example 为模板。此 .env 文件用于支持用户在启动应用前预配置模型的使用场景（例如在 HF hub 上部署应用）。该文件仅在首次运行时用于填充数据库，之后的运行中将不再使用。

在此项目的根目录创建 .env 文件。以 .env.example 为模板。

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

（可选）如需启用浏览器内 PDF_JS 查看器，请下载 PDF_JS_DIST，然后将其解压到 libs/ktem/ktem/assets/prebuilt。

启动 web 服务器：python app.py 应用程序将自动在浏览器中启动。默认用户名和密码都是 admin。你可以通过 UI 直接设置其他用户。

启动 web 服务器：

python app.py

应用程序将自动在浏览器中启动。

默认用户名和密码都是 admin。你可以通过 UI 直接设置其他用户。

检查"资源"选项卡中的 LLM 和嵌入模型，确保 api_key 值已从 .env 文件正确设置。如果未设置，可以在那里进行设置。

官方 MS GraphRAG 索引仅适用于 OpenAI 或 Ollama API。我们建议大多数用户使用 NanoGraphRAG 实现来与 Kotaemo 进行直接集成。

安装 nano-GraphRAG：pip install nano-graphrag

nano-graphrag 的安装可能会引入版本冲突，详见此问题。快速修复方法：pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib

快速修复方法：pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib

使用 USE_NANO_GRAPHRAG=true 环境变量启动 Kotaemon。

在资源设置中设置默认 LLM 和嵌入模型，NanoGraphRAG 将自动识别。

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

LightRAG 的安装可能会引入版本冲突，详见此问题。快速修复方法：pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib

快速修复方法：pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib

使用 USE_LIGHTRAG=true 环境变量启动 Kotaemon。

在资源设置中设置默认 LLM 和嵌入模型，LightRAG 将自动识别。

非 Docker 安装：如果不使用 Docker，请用以下命令安装 GraphRAG：pip install "graphrag<=0.3.6" future

非 Docker 安装：如果不使用 Docker，请用以下命令安装 GraphRAG：

pip install "graphrag<=0.3.6" future

API KEY 设置：要使用 GraphRAG 检索器功能，请确保设置 GRAPHRAG_API_KEY 环境变量。你可以直接在环境中设置，或将其添加到 .env 文件中。

使用本地模型和自定义设置：如果你想将 GraphRAG 与本地模型（如 Ollama）一起使用，或自定义默认 LLM 和其他配置，请将 USE_CUSTOMIZED_GRAPHRAG_SETTING 环境变量设置为 true。然后，在 settings.yaml.example 文件中调整设置。

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

详见本地模型设置。

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

以下选项可用：

Azure Document Intelligence（API）

Adobe PDF Extract（API）

Docling（本地、开源）– 详见 integrations/docling.md 获取 Kotaemon 特定设置。

PaddleOCR（本地、开源）– 详见 integrations/paddle_ocr.md 获取 Kotaemon 特定设置。

在"设置"->"检索设置"->"文件加载器"中选择对应的加载器。

自定义应用程序

默认情况下，所有应用数据存储在 ./ktem_app_data 文件夹中。你可以备份或复制此文件夹以将安装转移到新计算机。

对于高级用户或特定使用场景，你可以自定义这些文件：flow 和 settings.py 和 .env。

对于高级用户或特定使用场景，你可以自定义这些文件：

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

# 设置首选的文档存储（具有全文搜索功能）
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 文件配置模型，提供连接到 LLM 所需的信息。该文件位于应用程序文件夹中。如果看不到，可以创建一个。

目前支持以下提供商：OpenAI 在 .env 文件中，使用你的 OpenAI API 密钥设置 OPENAI_API_KEY 变量，以启用对 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 Azure OpenAI 对于通过 Azure 平台的 OpenAI 模型，你需要提供 Azure 端点和 API 密钥。根据 Azure 部署的设置方式，可能还需要为聊天模型和嵌入模型提供部署名称。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 本地模型使用 ollama OpenAI 兼容服务器：安装 ollama 并启动应用程序。拉取模型，例如：ollama pull llama3.1:8b ollama pull nomic-embed-text 在 web UI 中设置模型名称并将其设为默认值：使用 llama-cpp-python 和 GGUF 你可以从 Hugging Face Hub 搜索并下载 LLM 在本地运行。目前支持这些模型格式：GGUF 你应该选择大小小于设备内存的模型，并应保留约 2 GB。例如，如果总共有 16 GB RAM，其中 12 GB 可用，则应选择占用最多 10 GB RAM 的模型。更大的模型往往会产生更好的生成效果，但也需要更多处理时间。以下是一些建议及其内存大小：Qwen1.5-1.8B-Chat-GGUF：约 2 GB 使用提供的模型名称在 web UI 上添加新的 LlamaCpp 模型。

目前支持以下提供商：

OpenAI 在 .env 文件中，使用你的 OpenAI API 密钥设置 OPENAI_API_KEY 变量，以启用对 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

在 .env 文件中，使用你的 OpenAI API 密钥设置 OPENAI_API_KEY 变量，以启用对 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

Azure OpenAI 如果要通过 Azure 平台使用 OpenAI 模型，你需要提供 Azure 端点和 API 密钥。根据你对 Azure 部署的设置方式，你可能还需要为聊天模型和嵌入模型提供开发环境名称。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 平台使用 OpenAI 模型，你需要提供 Azure 端点和 API 密钥。根据你对 Azure 部署的设置方式，你可能还需要为聊天模型和嵌入模型提供开发环境名称。

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

本地模型使用 ollama OpenAI 兼容服务器：安装 ollama 并启动应用。拉取你的模型，例如：ollama pull llama3.1:8b ollama pull nomic-embed-text 在 Web UI 上设置模型名称并将其设为默认：使用 GGUF 和 llama-cpp-python 你可以从 Hugging Face Hub 搜索并下载要在本地运行的 LLM。目前支持以下模型格式：GGUF 你应该选择大小小于设备内存的模型，并应留出约 2 GB 的空间。例如，如果你的总内存为 16 GB，其中可用 12 GB，那么你应该选择占用最多 10 GB 内存的模型。更大的模型往往能产生更好的结果，但处理时间也会更长。以下是一些推荐及其内存大小：Qwen1.5-1.8B-Chat-GGUF：约 2 GB 在 Web UI 上使用提供的模型名称添加一个新的 LlamaCpp 模型。

使用 ollama OpenAI 兼容服务器：安装 ollama 并启动应用。拉取你的模型，例如：ollama pull llama3.1:8b ollama pull nomic-embed-text 在 Web UI 上设置模型名称并将其设为默认：

使用 ollama OpenAI 兼容服务器：

安装 ollama 并启动应用。

拉取你的模型，例如：

ollama pull llama3.1:8b
ollama pull nomic-embed-text

在 Web UI 上设置模型名称并将其设为默认：

使用 GGUF 和 llama-cpp-python 你可以从 Hugging Face Hub 搜索并下载要在本地运行的 LLM。目前支持以下模型格式：GGUF 你应该选择大小小于设备内存的模型，并应留出约 2 GB 的空间。例如，如果你的总内存为 16 GB，其中可用 12 GB，那么你应该选择占用最多 10 GB 内存的模型。更大的模型往往能产生更好的结果，但处理时间也会更长。以下是一些推荐及其内存大小：Qwen1.5-1.8B-Chat-GGUF：约 2 GB 在 Web UI 上使用提供的模型名称添加一个新的 LlamaCpp 模型。

使用 GGUF 和 llama-cpp-python

你可以从 Hugging Face Hub 搜索并下载要在本地运行的 LLM。目前支持以下模型格式：

GGUF 你应该选择大小小于设备内存的模型，并应留出约 2 GB 的空间。例如，如果你的总内存为 16 GB，其中可用 12 GB，那么你应该选择占用最多 10 GB 内存的模型。更大的模型往往能产生更好的结果，但处理时间也会更长。以下是一些推荐及其内存大小：

你应该选择大小小于设备内存的模型，并应留出约 2 GB 的空间。例如，如果你的总内存为 16 GB，其中可用 12 GB，那么你应该选择占用最多 10 GB 内存的模型。更大的模型往往能产生更好的结果，但处理时间也会更长。

以下是一些推荐及其内存大小：

Qwen1.5-1.8B-Chat-GGUF：约 2 GB 在 Web UI 上使用提供的模型名称添加一个新的 LlamaCpp 模型。

Qwen1.5-1.8B-Chat-GGUF：约 2 GB

在 Web UI 上使用提供的模型名称添加一个新的 LlamaCpp 模型。

添加你自己的 RAG 管道

在此处检查默认管道实现。你可以快速调整默认 QA 管道的工作方式。

在 libs/ktem/ktem/reasoning/ 中添加新的 .py 实现，稍后将其包含在 flows 设置中以在 UI 上启用它。

在 libs/ktem/ktem/index/file/graph 中查看示例实现

（更多说明正在进行中）。

请按以下方式引用本项目

@misc{kotaemon2024,
    title = {Kotaemon - 一个用于与任何内容聊天的开源基于 RAG 的工具。},
    author = {The Kotaemon Team},
    year = {2024},
    howpublished = {\url{https://github.com/Cinnamon/kotaemon}},
}

由于我们的项目正在积极开发中，我们非常重视你的反馈和贡献。请查看我们的贡献指南来入门。感谢所有贡献者！