wehub-resource-sync
dedc673850
Auto Bump and Release / auto-bump-and-release (push) Has been cancelled
style-check / pre-commit (push) Has been cancelled
unit-test / unit testing with python (push) Has been cancelled
unit-test / unit testing with python 3.10 (push) Has been cancelled
unit-test / unit testing with python 3.11 (push) Has been cancelled
407 lines
18 KiB
Markdown
407 lines
18 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/Cinnamon/kotaemon) · [上游 README](https://github.com/Cinnamon/kotaemon/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
|
||
# kotaemon
|
||
|
||
一款开源、简洁且可自定义的 RAG UI，用于与文档对话。同时面向终端用户和开发者打造。
|
||
|
||
|
||
|
||
<a href="https://trendshift.io/repositories/11607" target="_blank"><img src="https://trendshift.io/api/badge/repositories/11607" alt="Cinnamon%2Fkotaemon | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
||
|
||
[在线演示 #1](https://huggingface.co/spaces/cin-model/kotaemon) |
|
||
[在线演示 #2](https://huggingface.co/spaces/cin-model/kotaemon-demo) |
|
||
[在线安装](https://cinnamon.github.io/kotaemon/online_install/) |
|
||
[Colab 笔记本（本地 RAG）](https://colab.research.google.com/drive/1eTfieec_UOowNizTJA1NjawBJH9y_1nn)
|
||
|
||
[用户指南](https://cinnamon.github.io/kotaemon/) |
|
||
[开发者指南](https://cinnamon.github.io/kotaemon/development/) |
|
||
[反馈](https://github.com/Cinnamon/kotaemon/issues) |
|
||
[联系](mailto:kotaemon.support@cinnamon.is)
|
||
|
||
[](https://www.python.org/downloads/release/python-31013/)
|
||
[](https://github.com/psf/black)
|
||
<a href="https://github.com/Cinnamon/kotaemon/pkgs/container/kotaemon" target="_blank">
|
||
<img src="https://img.shields.io/badge/docker_pull-kotaemon:latest-brightgreen" alt="docker pull ghcr.io/cinnamon/kotaemon:latest"></a>
|
||
|
||
<a href='https://huggingface.co/spaces/cin-model/kotaemon-demo'><img src='https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue'></a>
|
||
<a href="https://hellogithub.com/en/repository/d3141471a0244d5798bc654982b263eb" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=d3141471a0244d5798bc654982b263eb&claim_uid=RLiD9UZ1rEHNaMf&theme=small" alt="Featured｜HelloGitHub" /></a>
|
||
|
||
</div>
|
||
|
||
<!-- start-intro -->
|
||
|
||
## 简介
|
||
|
||
本项目为希望对文档进行问答（QA）的终端用户，以及希望构建自有 RAG 流水线的开发者，提供一款实用的 RAG UI。
|
||
<br>
|
||
|
||
```yml
|
||
+----------------------------------------------------------------------------+
|
||
| End users: Those who use apps built with `kotaemon`. |
|
||
| (You use an app like the one in the demo above) |
|
||
| +----------------------------------------------------------------+ |
|
||
| | Developers: Those who built with `kotaemon`. | |
|
||
| | (You have `import kotaemon` somewhere in your project) | |
|
||
| | +----------------------------------------------------+ | |
|
||
| | | Contributors: Those who make `kotaemon` better. | | |
|
||
| | | (You make PR to this repo) | | |
|
||
| | +----------------------------------------------------+ | |
|
||
| +----------------------------------------------------------------+ |
|
||
+----------------------------------------------------------------------------+
|
||
```
|
||
|
||
### 面向终端用户
|
||
|
||
- **简洁极简 UI**：面向基于 RAG 的问答，提供友好的用户界面。
|
||
- **支持多种 LLM**：兼容 LLM API 提供商（OpenAI、AzureOpenAI、Cohere 等）以及本地 LLM（通过 `ollama` 和 `llama-cpp-python`）。
|
||
- **安装简便**：提供简单脚本，助你快速上手。
|
||
|
||
### 面向开发者
|
||
|
||
- **RAG 流水线框架**：提供工具，助你构建基于 RAG 的文档问答流水线。
|
||
- **可自定义 UI**：通过内置 UI 直观查看 RAG 流水线运行效果，基于 <a href='https://github.com/gradio-app/gradio'>Gradio <img src='https://img.shields.io/github/stars/gradio-app/gradio'></a> 构建。
|
||
- **Gradio 主题**：若你使用 Gradio 进行开发，可在此查看我们的主题：[kotaemon-gradio-theme](https://github.com/lone17/kotaemon-gradio-theme).
|
||
|
||
## 核心特性
|
||
|
||
- **自托管文档问答（RAG）Web UI**：支持多用户登录，在私有/公开集合中整理文件，协作并与他人分享你喜爱的对话。
|
||
|
||
- **管理 LLM 与 Embedding 模型**：支持本地 LLM 及主流 API 提供商（OpenAI、Azure、Ollama、Groq）。
|
||
|
||
- **混合 RAG 流水线**：提供合理的默认 RAG 流水线，采用混合（全文与向量）检索器并重排序，以确保最佳检索质量。
|
||
|
||
- **多模态问答支持**：对包含图表、表格的多份文档进行问答。支持多模态文档解析（可在 UI 中选择选项）。
|
||
|
||
- **高级引用与文档预览**：默认提供详细引用，以确保 LLM 回答的准确性。可在_浏览器内 PDF 查看器_中直接查看引用（含相关度分数）及高亮。当检索流水线返回相关性较低的文章时会发出警告。
|
||
|
||
- **支持复杂推理方法**：通过问题分解回答复杂/多跳问题。支持基于智能体的推理，可使用 `ReAct`、`ReWOO` 及其他智能体。
|
||
|
||
- **可配置设置 UI**：可在 UI 上调整检索与生成过程中的大多数重要环节（含提示词 prompts）。
|
||
|
||
- **可扩展**：基于 Gradio 构建，你可自由自定义或添加任意 UI 元素。此外，我们致力于支持多种文档索引与检索策略。`GraphRAG` 索引流水线作为示例提供。
|
||
|
||
|
||
|
||
## 安装
|
||
|
||
> 若你不是开发者，仅想使用本应用，请参阅我们易于上手的[用户指南](https://cinnamon.github.io/kotaemon/). 从[最新发布版](https://github.com/Cinnamon/kotaemon/releases/latest) 下载 `.zip` 文件，以获取所有最新功能与错误修复。
|
||
|
||
### 系统要求
|
||
|
||
1. [Python](https://www.python.org/downloads/) >= 3.10
|
||
2. [Docker](https://www.docker.com/): 可选，若你[使用 Docker 安装](#with-docker-recommended)
|
||
3. [Unstructured](https://docs.unstructured.io/open-source/installation/full-installation#full-installation) 若你希望处理除 `.pdf`、`.html`、`.mhtml` 和 `.xlsx` 以外的文档，则需安装。安装步骤因操作系统而异。请访问该链接并按其中说明操作。
|
||
|
||
### 使用 Docker（推荐）
|
||
|
||
1. 我们同时支持 `lite` 与 `full` 两种 Docker 镜像版本。使用 `full` 版本时，将安装 `unstructured` 的额外软件包，可支持更多文件类型（`.doc`、`.docx` 等），但镜像体积更大。对大多数用户而言，`lite` 镜像在多数情况下即可满足需求。
|
||
|
||
- 使用 `full` 版本。
|
||
|
||
```shell
|
||
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_。
|
||
|
||
```shell
|
||
# change image name to
|
||
docker run <...> ghcr.io/cinnamon/kotaemon:main-ollama
|
||
```
|
||
|
||
- 使用 `lite` 版本。
|
||
|
||
```shell
|
||
# change image name to
|
||
docker run <...> ghcr.io/cinnamon/kotaemon:main-lite
|
||
```
|
||
|
||
2. 我们目前支持并测试两个平台：`linux/amd64` 与 `linux/arm64`（适用于较新的 Mac）。可在 `docker run` 命令中通过传入 `--platform` 指定平台。例如：
|
||
|
||
```shell
|
||
# 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/kotaemon:main-lite
|
||
```
|
||
|
||
3. 一切配置正确后，可访问 `http://localhost:7860/` 打开 WebUI。
|
||
|
||
4. 我们使用 [GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) 存储 Docker 镜像，所有镜像可在[此处](https://github.com/Cinnamon/kotaemon/pkgs/container/kotaemon) 找到。
|
||
|
||
### 不使用 Docker
|
||
|
||
1. 克隆仓库：
|
||
|
||
```shell
|
||
git clone https://github.com/Cinnamon/kotaemon
|
||
cd kotaemon
|
||
```
|
||
|
||
2. 配置环境：
|
||
|
||
- **选项 1：使用 [uv](https://docs.astral.sh/uv/getting-started/installation/)（推荐）**
|
||
|
||
```shell
|
||
uv sync --python 3.10
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
- **选项 2：使用 conda**
|
||
|
||
```shell
|
||
conda create -n kotaemon python=3.10
|
||
conda activate kotaemon
|
||
|
||
pip install -e "libs/kotaemon[all]"
|
||
pip install -e "libs/ktem"
|
||
```
|
||
|
||
3. 在本项目根目录创建 `.env` 文件。以 `.env.example` 为模板。
|
||
|
||
`.env` 文件用于满足用户在启动应用前预先配置模型的场景（例如将应用部署到 HF hub）。该文件仅在首次运行时用于填充数据库一次，后续运行将不再使用。
|
||
|
||
4.（可选）要启用浏览器内 `PDF_JS` 查看器，请下载 [PDF_JS_DIST](https://github.com/mozilla/pdf.js/releases/download/v4.0.379/pdfjs-4.0.379-dist.zip)，然后解压到 `libs/ktem/ktem/assets/prebuilt`。
|
||
|
||
<img src="https://raw.githubusercontent.com/Cinnamon/kotaemon/main/docs/images/pdf-viewer-setup.png" alt="pdf-setup" width="300">
|
||
|
||
5. 启动 Web 服务器：
|
||
|
||
```shell
|
||
python app.py
|
||
```
|
||
|
||
- 应用会自动在浏览器中打开。
|
||
- 默认用户名和密码均为 `admin`。你可以通过 UI 直接添加更多用户。
|
||
|
||
|
||
|
||
6. 检查 `Resources` 标签页和 `LLMs and Embeddings`，确保你的 `api_key` 值已从 `.env` 文件正确设置。若未设置，可在该处进行配置。
|
||
|
||
### 配置 GraphRAG
|
||
|
||
> [!NOTE]
|
||
> 官方 MS GraphRAG 索引仅支持 OpenAI 或 Ollama API。
|
||
> 我们建议大多数用户使用 NanoGraphRAG 实现，以便与 Kotaemon 轻松集成。
|
||
|
||
<details>
|
||
|
||
<summary>配置 Nano GRAPHRAG</summary>
|
||
|
||
- 安装 nano-GraphRAG：`pip install nano-graphrag`
|
||
- `nano-graphrag` 安装可能会引发版本冲突，请参阅 [此 issue](https://github.com/Cinnamon/kotaemon/issues/440)
|
||
- 快速修复：`pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib`
|
||
- 使用 `USE_NANO_GRAPHRAG=true` 环境变量启动 Kotaemon。
|
||
- 在 Resources（资源）设置中配置默认 LLM 和 Embedding 模型，NanoGraphRAG 会自动识别。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
|
||
<summary>配置 LIGHTRAG</summary>
|
||
|
||
- 安装 LightRAG：`pip install git+https://github.com/HKUDS/LightRAG.git`
|
||
- `LightRAG` 安装可能会引发版本冲突，请参阅 [此 issue](https://github.com/Cinnamon/kotaemon/issues/440)
|
||
- 快速修复：`pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib`
|
||
- 使用 `USE_LIGHTRAG=true` 环境变量启动 Kotaemon。
|
||
- 在 Resources（资源）设置中配置默认 LLM 和 Embedding 模型，LightRAG 会自动识别。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
|
||
<summary>配置 MS GRAPHRAG</summary>
|
||
|
||
- **非 Docker 安装**：如果不使用 Docker，请使用以下命令安装 GraphRAG：
|
||
|
||
```shell
|
||
pip install "graphrag<=0.3.6" future
|
||
```
|
||
|
||
- **配置 API KEY**：要使用 GraphRAG 检索器功能，请确保设置 `GRAPHRAG_API_KEY` 环境变量。你可以直接在环境中设置，或将其添加到 `.env` 文件。
|
||
- **使用本地模型与自定义设置**：如果想使用本地模型（如 `Ollama`）运行 GraphRAG，或自定义默认 LLM 及其他配置，请将 `USE_CUSTOMIZED_GRAPHRAG_SETTING` 环境变量设为 true。然后在 `settings.yaml.example` 文件中调整设置。
|
||
|
||
</details>
|
||
|
||
### 配置本地模型（用于本地/私有 RAG）
|
||
|
||
请参阅 [本地模型配置](docs/local_model.md)。
|
||
|
||
### 配置多模态文档解析（OCR、表格解析、图表提取）
|
||
|
||
可选方案如下：
|
||
|
||
- [Azure Document Intelligence（API）](https://azure.microsoft.com/en-us/products/ai-services/ai-document-intelligence)
|
||
- [Adobe PDF Extract（API）](https://developer.adobe.com/document-services/docs/overview/pdf-extract-api/)
|
||
- [Docling（本地、开源）](https://github.com/DS4SD/docling) – 有关 Kotaemon 专属配置，请参阅 [integrations/docling.md](./docs/integrations/docling.md)。
|
||
- [PaddleOCR（本地、开源）](https://github.com/PADDLEPADDLE/PADDLEOCR) – 有关 Kotaemon 专属配置，请参阅 [integrations/paddle_ocr.md](./docs/integrations/paddle_ocr.md)。
|
||
|
||
在 `Settings -> Retrieval Settings -> File loader` 中选择相应的加载器
|
||
|
||
### 自定义应用
|
||
|
||
- 默认情况下，所有应用数据存储在 `./ktem_app_data` 文件夹中。你可以备份或复制该文件夹，以便将安装迁移到新机器。
|
||
|
||
- 对于高级用户或特定场景，可以自定义以下文件：
|
||
|
||
- `flowsettings.py`
|
||
- `.env`
|
||
|
||
#### `flowsettings.py`
|
||
|
||
该文件包含应用配置。你可以参考[此处示例](flowsettings.py)作为起点。
|
||
|
||
<details>
|
||
|
||
<summary>重要设置</summary>
|
||
|
||
```python
|
||
# setup your preferred document store (with full-text search capabilities)
|
||
KH_DOCSTORE=(Elasticsearch | LanceDB | SimpleFileDocumentStore)
|
||
|
||
# setup your preferred vectorstore (for vector-based search)
|
||
KH_VECTORSTORE=(ChromaDB | LanceDB | InMemory | Milvus | Qdrant)
|
||
|
||
# Enable / disable multimodal QA
|
||
KH_REASONINGS_USE_MULTIMODAL=True
|
||
|
||
# Setup your new reasoning pipeline or modify existing one.
|
||
KH_REASONINGS = [
|
||
"ktem.reasoning.simple.FullQAPipeline",
|
||
"ktem.reasoning.simple.FullDecomposeQAPipeline",
|
||
"ktem.reasoning.react.ReactAgentPipeline",
|
||
"ktem.reasoning.rewoo.RewooAgentPipeline",
|
||
]
|
||
```
|
||
|
||
</details>
|
||
|
||
#### `.env`
|
||
|
||
该文件提供另一种配置模型与凭据的方式。
|
||
|
||
<details>
|
||
|
||
<summary>通过 .env 文件配置模型</summary>
|
||
|
||
- 你也可以通过 `.env` 文件配置模型，填入连接 LLM 所需的信息。该文件位于应用文件夹中；若不存在，可自行创建。
|
||
|
||
- 目前支持以下提供商：
|
||
|
||
- **OpenAI**
|
||
|
||
在 `.env` 文件中，将 `OPENAI_API_KEY` 变量设置为你的 OpenAI API key，以启用对 OpenAI 模型的访问。还有其他可修改的变量，请根据需要自行调整；否则默认参数对大多数用户应已足够。
|
||
|
||
```shell
|
||
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 key。根据你在 Azure 上的部署方式，可能还需要提供聊天模型和嵌入模型的部署名称。
|
||
|
||
```shell
|
||
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
|
||
```
|
||
|
||
- **Local Models**
|
||
|
||
- 使用 `ollama` OpenAI 兼容服务器：
|
||
|
||
- 安装 [ollama](https://github.com/ollama/ollama) 并启动应用。
|
||
|
||
- 拉取模型，例如：
|
||
|
||
```shell
|
||
ollama pull llama3.1:8b
|
||
ollama pull nomic-embed-text
|
||
```
|
||
|
||
- 在 Web UI 中设置模型名称并将其设为默认：
|
||
|
||
|
||
|
||
- 使用 `GGUF` 配合 `llama-cpp-python`
|
||
|
||
你可以从 [Hugging Face Hub](https://huggingface.co/models). 搜索并下载在本地运行的 LLM。目前支持以下模型格式：
|
||
|
||
- GGUF
|
||
|
||
应选择体积小于设备内存的模型，并预留约 2 GB 空间。例如，若设备共有 16 GB RAM，其中 12 GB 可用，则应选择最多占用 10 GB RAM 的模型。更大的模型通常生成效果更好，但处理时间也更长。
|
||
|
||
以下是一些推荐模型及其内存占用：
|
||
|
||
- [Qwen1.5-1.8B-Chat-GGUF](https://huggingface.co/Qwen/Qwen1.5-1.8B-Chat-GGUF/resolve/main/qwen1_5-1_8b-chat-q8_0.gguf?download=true): 约 2 GB
|
||
|
||
在 Web UI 中添加一个新的 LlamaCpp 模型，使用提供的模型名称。
|
||
|
||
</details>
|
||
|
||
### 添加你自己的 RAG 流水线
|
||
|
||
#### 自定义推理流水线（Reasoning Pipeline）
|
||
|
||
1. 在[此处](libs/ktem/ktem/reasoning/simple.py)查看默认流水线实现。你可以快速调整默认 QA 流水线的工作方式。
|
||
2. 在 `libs/ktem/ktem/reasoning/` 中添加新的 `.py` 实现，随后在 `flowssettings` 中引入，以在 UI 上启用。
|
||
|
||
#### 自定义索引流水线（Indexing Pipeline）
|
||
|
||
- 在 `libs/ktem/ktem/index/file/graph` 中查看示例实现
|
||
|
||
> （更多说明待补充 WIP）。
|
||
|
||
<!-- end-intro -->
|
||
|
||
## 引用
|
||
|
||
请按如下方式引用本项目：
|
||
|
||
```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}},
|
||
}
|
||
```
|
||
|
||
## Star 历史
|
||
|
||
<a href="https://star-history.com/#Cinnamon/kotaemon&Date">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Cinnamon/kotaemon&type=Date&theme=dark" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Cinnamon/kotaemon&type=Date" />
|
||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Cinnamon/kotaemon&type=Date" />
|
||
</picture>
|
||
</a>
|
||
|
||
## 贡献
|
||
|
||
由于本项目仍在积极开发中，我们非常重视你的反馈与贡献。请参阅我们的[贡献指南](https://github.com/Cinnamon/kotaemon/blob/main/CONTRIBUTING.md) 以开始参与。感谢所有贡献者！
|
||
|
||
<a href="https://github.com/Cinnamon/kotaemon/graphs/contributors">
|
||
<img src="https://contrib.rocks/image?repo=Cinnamon/kotaemon" />
|
||
</a>
|