Skip to content

Commit 2d14019

Browse files
earayuearayu
authored
Chore/update readme (#1025)
* feat: update readme * feat: update * feat: update makefile & readme * feat: update makefile & readme
1 parent f220499 commit 2d14019

9 files changed

Lines changed: 715 additions & 20 deletions

‎Makefile‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -121,17 +121,17 @@ endif
121121
.PHONY: compose-up compose-down compose-logs compose-infra
122122
# Full application startup
123123
compose-up:
124-
VERSION=v0.5.0-alpha.31 DOCRAY_VERSION=v0.1.1 $(_EXTRA_ENVS) docker-compose --profile app $(_PROFILES_TO_ACTIVATE) -f docker-compose.yml up -d
124+
$(_EXTRA_ENVS) docker-compose $(_PROFILES_TO_ACTIVATE) -f docker-compose.yml up -d
125125

126126
# Infrastructure only (databases + supporting services)
127127
compose-infra:
128-
VERSION=v0.5.0-alpha.31 DOCRAY_VERSION=v0.1.1 docker-compose $(_PROFILES_TO_ACTIVATE) -f docker-compose.yml up -d
128+
docker-compose $(_PROFILES_TO_ACTIVATE) -f docker-compose.yml up -d postgres redis qdrant es
129129

130130
compose-down:
131-
VERSION=v0.5.0-alpha.31 DOCRAY_VERSION=v0.1.1 docker-compose --profile app --profile docray --profile docray-gpu --profile neo4j -f docker-compose.yml down $(_COMPOSE_DOWN_FLAGS)
131+
docker-compose --profile docray --profile docray-gpu --profile neo4j -f docker-compose.yml down $(_COMPOSE_DOWN_FLAGS)
132132

133133
compose-logs:
134-
VERSION=v0.5.0-alpha.31 DOCRAY_VERSION=v0.1.1 docker-compose -f docker-compose.yml logs -f
134+
docker-compose -f docker-compose.yml logs -f
135135

136136
##################################################
137137
# Development Services

‎README-zh.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# ApeRAG
2+
3+
[Read English Documentation](README.md)
4+
5+
- [快速开始](#快速开始)
6+
- [核心特性](#核心特性)
7+
- [Kubernetes 部署（推荐生产环境）](#kubernetes-部署推荐生产环境)
8+
- [开发指南](./docs/development-guide-zh.md)
9+
- [构建 Docker 镜像](./docs/build-docker-image-zh.md)
10+
- [致谢](#致谢)
11+
- [许可证](#许可证)
12+
13+
ApeRAG 是一个生产级 RAG（检索增强生成）平台，结合了图 RAG、向量搜索和全文搜索。构建具有混合检索、多模态文档处理和企业级管理功能的复杂 AI 应用程序。
14+
15+
## 快速开始
16+
17+
> 在安装 ApeRAG 之前，请确保您的机器满足以下最低系统要求：
18+
>
19+
> - CPU >= 2 核心
20+
> - RAM >= 4 GiB
21+
> - Docker & Docker Compose
22+
23+
启动 ApeRAG 最简单的方法是通过 Docker Compose。在运行以下命令之前，请确保您的机器上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/)：
24+
25+
```bash
26+
git clone https://github.com/apecloud/ApeRAG.git
27+
cd ApeRAG
28+
cp envs/env.template .env
29+
cp frontend/deploy/env.local.template frontend/.env
30+
docker compose up -d
31+
```
32+
33+
运行后，您可以在浏览器中访问 ApeRAG：
34+
- **Web 界面**: http://localhost:3000/web/
35+
- **API 文档**: http://localhost:8000/docs
36+
37+
#### 增强文档解析
38+
39+
为了获得增强的文档解析能力，ApeRAG 支持由 MinerU 驱动的**高级文档解析服务**，可为复杂文档、表格和公式提供优异的解析能力。
40+
41+
<details>
42+
<summary><strong>增强文档解析命令</strong></summary>
43+
44+
```bash
45+
# 启用高级文档解析服务
46+
DOCRAY_HOST=http://aperag-docray:8639 docker compose --profile docray up -d
47+
48+
# 启用带 GPU 加速的高级解析
49+
DOCRAY_HOST=http://aperag-docray-gpu:8639 docker compose --profile docray-gpu up -d
50+
```
51+
52+
或使用 Makefile 快捷方式（需要 [GNU Make](https://www.gnu.org/software/make/)）：
53+
```bash
54+
# 启用高级文档解析服务
55+
make compose-up WITH_DOCRAY=1
56+
57+
# 启用带 GPU 加速的高级解析（推荐）
58+
make compose-up WITH_DOCRAY=1 WITH_GPU=1
59+
```
60+
61+
</details>
62+
63+
#### 开发与贡献
64+
65+
对于有兴趣进行源代码开发、高级配置或为 ApeRAG 做贡献的开发人员，请参考我们的[开发指南](./docs/development-guide-zh.md)获取详细的设置说明。
66+
67+
## 核心特性
68+
69+
**1. 混合检索引擎**：
70+
结合图 RAG、向量搜索和全文搜索，实现全面的文档理解和检索。
71+
72+
**2. 基于 LightRAG 的图 RAG**：
73+
增强版的 LightRAG，用于高级图形知识提取，支持深度关系和上下文查询。
74+
75+
**3. MinerU 集成**：
76+
由 MinerU 技术驱动的高级文档解析服务，为复杂文档、表格、公式和科学内容提供优异的解析能力，可选 GPU 加速。
77+
78+
**4. 生产级部署**：
79+
完整的 Kubernetes 支持，配有 Helm charts 和 KubeBlocks 集成，简化生产级数据库（PostgreSQL、Redis、Qdrant、Elasticsearch、Neo4j）的部署。
80+
81+
**5. 多模态文档处理**：
82+
支持各种文档格式（PDF、DOCX 等），具有智能内容提取和结构识别功能。
83+
84+
**6. 企业管理**：
85+
内置审计日志、LLM 模型管理、图形可视化和全面的文档管理界面。
86+
87+
**7. 开发者友好**：
88+
FastAPI 后端、React 前端、使用 Celery 的异步任务处理、广泛的测试以及全面的开发指南，便于贡献和定制。
89+
90+
## Kubernetes 部署（推荐生产环境）
91+
92+
> **具有高可用性和可扩展性的企业级部署**
93+
94+
使用我们提供的 Helm chart 将 ApeRAG 部署到 Kubernetes。这种方法提供高可用性、可扩展性和生产级管理能力。
95+
96+
### 前提条件
97+
98+
* [Kubernetes 集群](https://kubernetes.io/docs/setup/)（v1.20+）
99+
* [`kubectl`](https://kubernetes.io/docs/tasks/tools/) 已配置并连接到您的集群
100+
* [Helm v3+](https://helm.sh/docs/intro/install/) 已安装
101+
102+
### 克隆仓库
103+
104+
首先，克隆 ApeRAG 仓库以获取部署文件：
105+
106+
```bash
107+
git clone https://github.com/apecloud/ApeRAG.git
108+
cd ApeRAG
109+
```
110+
111+
### 步骤 1：部署数据库服务
112+
113+
ApeRAG 需要 PostgreSQL、Redis、Qdrant 和 Elasticsearch。您有两个选择：
114+
115+
**选项 A：使用现有数据库** - 如果您的集群中已经运行这些数据库，请编辑 `deploy/aperag/values.yaml` 配置您的数据库连接详情，然后跳到步骤 2。
116+
117+
**选项 B：使用 KubeBlocks 部署数据库** - 使用我们的自动化数据库部署（数据库连接已预配置）：
118+
119+
```bash
120+
# 进入数据库部署脚本目录
121+
cd deploy/databases/
122+
123+
# （可选）查看配置 - 默认设置适用于大多数情况
124+
# edit 00-config.sh
125+
126+
# 安装 KubeBlocks 并部署数据库
127+
bash ./01-prepare.sh # 安装 KubeBlocks
128+
bash ./02-install-database.sh # 部署 PostgreSQL、Redis、Qdrant、Elasticsearch
129+
130+
# 监控数据库部署
131+
kubectl get pods -n default
132+
133+
# 返回项目根目录进行步骤 2
134+
cd ../../
135+
```
136+
137+
等待所有数据库 pod 状态变为 `Running` 后再继续。
138+
139+
### 步骤 2：部署 ApeRAG 应用
140+
141+
```bash
142+
# 如果您在步骤 1 中使用 KubeBlocks 部署了数据库，数据库连接已预配置
143+
# 如果您使用现有数据库，请使用您的连接详情编辑 deploy/aperag/values.yaml
144+
145+
# 部署 ApeRAG
146+
helm install aperag ./deploy/aperag --namespace default --create-namespace
147+
148+
# 监控 ApeRAG 部署
149+
kubectl get pods -n default -l app.kubernetes.io/instance=aperag
150+
```
151+
152+
### 配置选项
153+
154+
**资源要求**：默认包含 [`doc-ray`](https://github.com/apecloud/doc-ray) 服务（需要 4+ CPU 核心，8GB+ RAM）。要禁用：在 `values.yaml` 中设置 `docray.enabled: false`。
155+
156+
**高级设置**：查看 `values.yaml` 了解额外的配置选项，包括镜像、资源和 Ingress 设置。
157+
158+
### 访问您的部署
159+
160+
部署完成后，使用端口转发访问 ApeRAG：
161+
162+
```bash
163+
# 转发端口以便快速访问
164+
kubectl port-forward svc/aperag-frontend 3000:3000 -n default
165+
kubectl port-forward svc/aperag-api 8000:8000 -n default
166+
167+
# 在浏览器中访问
168+
# Web 界面: http://localhost:3000
169+
# API 文档: http://localhost:8000/docs
170+
```
171+
172+
对于生产环境，请在 `values.yaml` 中配置 Ingress 以获得外部访问。
173+
174+
### 故障排除
175+
176+
**数据库问题**：查看 `deploy/databases/README.md` 了解 KubeBlocks 管理、凭据和卸载程序。
177+
178+
**Pod 状态**：检查 pod 日志以查看任何部署问题：
179+
```bash
180+
kubectl logs -f deployment/aperag-api -n default
181+
kubectl logs -f deployment/aperag-frontend -n default
182+
```
183+
184+
## 致谢
185+
186+
ApeRAG 集成并构建在几个优秀的开源项目之上：
187+
188+
### LightRAG
189+
ApeRAG 中基于图的知识检索能力由深度修改的 [LightRAG](https://github.com/HKUDS/LightRAG) 版本提供支持：
190+
- **论文**: "LightRAG: Simple and Fast Retrieval-Augmented Generation" ([arXiv:2410.05779](https://arxiv.org/abs/2410.05779))
191+
- **作者**: Zirui Guo, Lianghao Xia, Yanhua Yu, Tu Ao, Chao Huang
192+
- **许可证**: MIT License
193+
194+
我们对 LightRAG 进行了广泛修改，以支持生产级并发处理、分布式任务队列（Celery/Prefect）和无状态操作。详情请参见我们的 [LightRAG 修改更新日志](./aperag/graph/changelog.md)。
195+
196+
## 许可证
197+
198+
ApeRAG 采用 Apache License 2.0 许可。详情请参见 [LICENSE](./LICENSE) 文件。

‎README.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# ApeRAG
22

3+
[阅读中文文档](README-zh.md)
4+
35
- [Quick Start](#quick-start)
46
- [Key Features](#key-features)
57
- [Kubernetes Deployment (Recommended for Production)](#kubernetes-deployment-recommended-for-production)
@@ -25,7 +27,7 @@ git clone https://github.com/apecloud/ApeRAG.git
2527
cd ApeRAG
2628
cp envs/env.template .env
2729
cp frontend/deploy/env.local.template frontend/.env
28-
make compose-up
30+
docker compose up -d
2931
```
3032

3133
After running, you can access ApeRAG in your browser at:
@@ -39,6 +41,15 @@ For enhanced document parsing capabilities, ApeRAG supports an **advanced docume
3941
<details>
4042
<summary><strong>Enhanced Document Parsing Commands</strong></summary>
4143

44+
```bash
45+
# Enable advanced document parsing service
46+
DOCRAY_HOST=http://aperag-docray:8639 docker compose --profile docray up -d
47+
48+
# Enable advanced parsing with GPU acceleration
49+
DOCRAY_HOST=http://aperag-docray-gpu:8639 docker compose --profile docray-gpu up -d
50+
```
51+
52+
Or use the Makefile shortcuts (requires [GNU Make](https://www.gnu.org/software/make/)):
4253
```bash
4354
# Enable advanced document parsing service
4455
make compose-up WITH_DOCRAY=1

‎aperag/app.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,14 @@
3636

3737
register_custom_llm_track()
3838

39+
40+
# Health check endpoint
41+
@app.get("/health")
42+
async def health_check():
43+
"""Simple health check endpoint for container health monitoring"""
44+
return {"status": "healthy", "service": "aperag-api"}
45+
46+
3947
app.include_router(auth_router, prefix="/api/v1")
4048
app.include_router(main_router, prefix="/api/v1")
4149
app.include_router(api_key_router, prefix="/api/v1")

0 commit comments

Comments
 (0)