EasyRAG 是一个专业的本地知识库构建与检索系统，专注于为AI应用提供高性能的知识检索服务。它集成了先进的混合检索技术和多样化的Embedding模型，能帮助开发者快速构建、管理本地知识库，为各种AI应用提供精准的知识检索API。
- 🔒 完全本地部署 - 数据安全与私密性保障，无需担心数据泄露
- 🎯 混合搜索技术 - 向量检索 + 关键词检索，检索精度提升40%
- 🤖 多模型支持 - 支持20+Embedding模型，灵活选择最优方案
- 📚 多格式文档 - 支持PDF、Word、Markdown、TXT等10+格式
- 🖥️ 集成Web界面 - 无需额外启动，通过API服务端口即可访问
- ⚡ 高性能API - 毫秒级检索响应，支持百万级文档库
- 🔗 生态集成 - 为DocuGen等AI应用提供知识检索服务
| 特性 | EasyRAG | 传统RAG | 在线服务 |
|---|---|---|---|
| 🔒 数据安全 | ✅ 完全本地 | ✅ 本地 | ❌ 云端处理 |
| 🚀 检索速度 | ⚡ <100ms | 🐌 >500ms | 🌐 网络延迟 |
| 💰 使用成本 | 💚 免费 | 💚 免费 | 💸 按量计费 |
| 🎯 检索精度 | 🎯 95%+ | 📊 80%+ | 📊 85%+ |
| 🔧 自定义 | ✅ 完全可控 | ✅ 可控 | ❌ 受限 |
| 📚 文档支持 | 📄 10+格式 | 📄 基础格式 | 📄 有限格式 |
graph LR
A[📚 EasyRAG<br/>知识库系统] --> B[🖋️ DocuGen<br/>文档生成]
A --> C[💬 聊天机器人]
A --> D[🔍 搜索引擎]
A --> E[📊 数据分析]
style A fill:#e3f2fd
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#fce4ec
| 项目 | 描述 | 链接 | 状态 |
|---|---|---|---|
| 🖋️ DocuGen | AI智能文档生成系统，基于EasyRAG知识库自动生成专业文档 | GitHub | ✅ 可用 |
| 💬 ChatBot | 智能对话机器人（计划中） | - | 🚧 开发中 |
| 📊 Analytics | 知识库分析工具（计划中） | - | 📋 计划中 |
|
|
|
|
|
|
|
|
|
| 项目 | 最低要求 | 推荐配置 | 高性能配置 |
|---|---|---|---|
| 🖥️ 操作系统 | Windows 10/Linux/macOS | - | - |
| 🐍 Python版本 | Python 3.9+ | Python 3.10+ | Python 3.11+ |
| 💾 内存 | 8GB | 16GB | 32GB+ |
| 💿 磁盘空间 | 10GB | 50GB | 100GB+ |
| 🎮 GPU | 可选 | GTX 1060+ | RTX 4090+ |
| 🌐 网络 | 初次下载模型需要 | - | - |
💡 提示: 使用Docker部署可以避免大部分环境配置问题
graph TD
A[🎯 选择部署方式] --> B[🐳 Docker部署<br/>⭐ 推荐新手]
A --> C[📜 脚本部署<br/>⭐ 推荐进阶]
A --> D[🔧 手动部署<br/>⭐ 推荐专家]
B --> E[docker-compose up -d]
C --> F[1️⃣ 运行 deploy 脚本]
D --> G[1️⃣ 创建虚拟环境]
F --> H[2️⃣ 运行 start 脚本]
G --> I[2️⃣ 安装依赖包]
H --> J[🌐 访问 Web 界面]
I --> K[3️⃣ 启动服务]
E --> J
K --> J
J --> L[🎉 开始使用!]
style A fill:#e1f5fe
style B fill:#c8e6c9
style C fill:#fff3e0
style D fill:#fce4ec
style L fill:#f3e5f5
# 1️⃣ 确保已安装 Docker
# 2️⃣ 克隆项目到本地
git clone https://github.com/BetaStreetOmnis/EasyRAG.git
cd EasyRAG
# 3️⃣ 构建 Docker 镜像
sudo docker build -t easyrag .
# 4️⃣ 运行 Docker 容器
# 注意：请根据您的系统修改 -v 参数中的主机路径
# 1. 将 /home/EasyRAG 替换为您的项目代码在本地的绝对路径。
# 这可以让您在本地修改代码后，容器内实时生效，方便开发。
# 2. 将 /home/EasyRAG/data_from_docker/... 替换为您希望在本地存放数据的绝对路径。
docker run -d \
-p 80:80 \
-p 8028:8028 \
-v /home/EasyRAG:/app \
-v /home/EasyRAG/data_from_docker/data:/data \
-v /home/EasyRAG/data_from_docker/db:/app/db \
-v /home/EasyRAG/data_from_docker/logs:/app/logs \
-v /home/EasyRAG/data_from_docker/models_file:/app/models_file \
-v /home/EasyRAG/data_from_docker/files:/app/files \
--name easyrag-app \
--restart always \
easyrag:latest
# 5️⃣ 访问服务
# 浏览器打开：http://localhost:8028🎯 两步完成：先部署，再启动
# 第一步：环境部署（自动安装Python、创建虚拟环境、安装依赖）
双击运行 deploy.bat
# 或命令行：deploy.bat
# 第二步：启动服务（激活环境、启动服务）
双击运行 start.bat
# 或命令行：start.bat# 第一步：添加执行权限
chmod +x deploy.sh start.sh
# 第二步：环境部署
./deploy.sh
# 第三步：启动服务
./start.sh📖 点击展开详细步骤
# 1️⃣ 克隆项目
git clone https://github.com/BetaStreetOmnis/EasyRAG.git
cd EasyRAG
# 2️⃣ 创建虚拟环境
python -m venv py_env
# 3️⃣ 激活虚拟环境
# Windows:
py_env\Scripts\activate
# Linux/Mac:
source py_env/bin/activate
# 4️⃣ 安装依赖
# CPU版本（适合大多数用户）：
pip install -r requirements_cpu.txt
# GPU版本（有NVIDIA显卡）：
pip install -r requirements_gpu.txt
# 5️⃣ 创建配置文件
cp .env.example .env
# 编辑 .env 文件，配置模型路径等参数
# 6️⃣ 启动服务
python app.py # 启动后端API及前端UI服务 (端口8028)
✅ 优势特点
⏱️ 部署时间: ~5分钟 |
deploy.bat✅ 自动化功能
⏱️ 部署时间: ~10分钟 |
./deploy.sh✅ 智能特性
⏱️ 部署时间: ~8分钟 |
start.bat🎯 启动流程
⏱️ 启动时间: ~30秒 |
./start.sh🎯 启动特性
⏱️ 启动时间: ~20秒 |
部署完成后，浏览器访问以下地址即可开始使用：
| 服务名称 | 访问地址 | 功能说明 |
|---|---|---|
| 🌐 EasyRAG服务 | http://localhost:8028 |
知识库管理界面和API |
💡 提示: 如果端口被占用，可以在
.env文件中修改端口配置
sequenceDiagram
participant U as 👤 用户
participant W as 🌐 Web界面
participant A as 🔧 API服务
participant D as 💾 数据库
U->>W: 1. 访问知识库管理
W->>U: 2. 显示创建表单
U->>W: 3. 输入知识库信息
W->>A: 4. 提交创建请求
A->>D: 5. 创建知识库记录
A->>A: 6. 初始化向量索引
A->>W: 7. 返回创建结果
W->>U: 8. 显示创建成功
详细步骤：
- 🌐 访问Web界面 → 📚 点击"知识库管理"选项卡
- ➕ 点击"创建知识库"按钮 → 📝 输入知识库名称和描述
- ⚙️ 选择Embedding模型（推荐：gte-large-zh）
- 🧩 选择分块策略（文档类型决定）
- 📤 上传文档文件（支持拖拽批量上传）
- ⏳ 等待系统自动处理并构建向量索引
- ✅ 创建完成，可以通过API进行检索
基础检索示例：
import requests
# 检索API调用
response = requests.post("http://localhost:8028/search", json={
"knowledge_base_id": "your_kb_id",
"query": "你的查询问题",
"top_k": 5,
"search_mode": "hybrid" # vector/keyword/hybrid
})
results = response.json()
for result in results["documents"]:
print(f"相关度: {result['score']}")
print(f"内容: {result['content']}")与DocuGen集成示例：
# DocuGen调用EasyRAG进行知识检索
def get_knowledge_context(topic):
response = requests.post("http://localhost:8028/search", json={
"knowledge_base_id": "document_kb",
"query": topic,
"top_k": 10,
"search_mode": "hybrid"
})
return response.json()["documents"]
# 基于检索结果生成文档
context = get_knowledge_context("人工智能发展趋势")
# 传递给DocuGen进行文档生成...📋 环境变量配置 (.env文件)
# 服务端口配置
API_PORT=8028
# 模型配置
EMBEDDING_MODEL=thenlper/gte-large-zh
RERANK_MODEL=thenlper/gte-reranker-base
# 数据库配置
DATABASE_URL=sqlite:///./knowledge_base.db
# 缓存配置
CACHE_DIR=./cache
MODEL_CACHE_DIR=./models
# 检索配置
DEFAULT_TOP_K=5
DEFAULT_SIMILARITY_THRESHOLD=0.3
MAX_CHUNK_SIZE=500
# 日志配置
LOG_LEVEL=INFO
LOG_FILE=./logs/easyrag.log
# API配置
MAX_QUERY_LENGTH=1000
ENABLE_RERANK=true
BATCH_SIZE=32🏗️ EasyRAG 系统架构
├── 🚀 app.py # FastAPI服务 (API + UI)
├── 🚀 main.py # RAG核心服务 (RAGService)
├── 📚 core/ # 核心功能模块
│ ├── chunker/ # 文本分块
│ ├── db/ # 数据库交互
│ ├── llm/ # 模型加载与推理
│ ├── parser/ # 文档解析
│ ├── retriever/ # 知识检索
│ ├── reranker/ # 结果重排
│ └── utils/ # 通用工具
├── 📜 deploy.bat/deploy.sh # 自动部署脚本
├── 🚀 start.bat/start.sh # 快速启动脚本
├── 🐳 docker-compose.yml # Docker编排
├── ⚙️ .env # 环境配置文件
├── 📦 models/ # 模型缓存目录
├── 💾 data/ # 知识库数据目录
├── 📋 requirements*.txt # Python依赖
└── 📖 docs/ # 项目文档
|
|
| 策略类型 | 适用场景 | 精度 | 速度 | 推荐指数 |
|---|---|---|---|---|
| 🔍 向量检索 | 语义相似查询 | 90% | 快 | ⭐⭐⭐ |
| 🔤 关键词检索 | 精确匹配查询 | 85% | 很快 | ⭐⭐ |
| 🎯 混合搜索 | 综合查询需求 | 95% | 中 | ⭐⭐⭐⭐⭐ |
| 🏆 重排序优化 | 高精度要求 | 97% | 慢 | ⭐⭐⭐⭐ |
- 🧠 语义分块 - 基于句子语义边界，适合连续性文本
- 🔤 递归字符分块 - 按字符数量分割，适合长文档
- 📝 Markdown分块 - 基于标题结构，适合技术文档
- 📚 子标题分块 - 保留层级结构，适合学术论文
🔧 Faiss向量库安装失败
问题描述: 手动安装时Faiss编译失败
解决方案:
# 方案1: 使用conda安装
conda install -c conda-forge faiss-cpu
# 方案2: 使用预编译包
pip install faiss-cpu --no-cache-dir
# 方案3: GPU版本
pip install faiss-gpu推荐: 使用Docker部署可避免此问题
🐧 Linux依赖包缺失
# Ubuntu/Debian系统
sudo apt-get update
sudo apt-get install -y libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev libgomp1
# CentOS/RHEL系统
sudo yum install -y mesa-libGL glib2 libSM libXext libXrender libgomp🪟 Windows权限问题
- 以管理员身份运行PowerShell或CMD
- 确保路径中不含中文字符
- 检查防火墙设置，允许Python程序联网
| 硬件配置 | 推荐设置 | 预期性能 |
|---|---|---|
| 8GB内存 | 小型模型 + CPU | 处理1万文档 |
| 16GB内存 | 中型模型 + CPU | 处理10万文档 |
| 32GB内存 + GPU | 大型模型 + GPU | 处理100万文档 |
# 检查容器状态
docker-compose ps
# 查看详细日志
docker-compose logs -f
# 重新构建镜像
docker-compose up --build --force-recreate
# 清理缓存重建
docker system prune -a
docker-compose up --build# 检查Python环境
python --version
pip --version
# 检查虚拟环境
source py_env/bin/activate # Linux/Mac
py_env\Scripts\activate # Windows
# 验证关键依赖
pip list | grep -E "(faiss|torch|transformers)"
# 查看详细错误
python app.py| 错误代码 | 问题描述 | 解决方案 |
|---|---|---|
ModuleNotFoundError |
缺少Python包 | pip install -r requirements.txt |
CUDA out of memory |
GPU内存不足 | 减小batch_size或使用CPU |
Port already in use |
端口被占用 | 修改.env中的API_PORT配置 |
Permission denied |
权限不足 | 使用管理员权限运行 |
❓ 支持哪些文档格式？
支持格式: PDF、Word(.docx)、Markdown(.md)、纯文本(.txt)、网页(.html)、Excel(.xlsx)、PowerPoint(.pptx)、RTF、CSV等
特殊功能:
- PDF支持OCR文字识别
- Word支持表格和图片提取
- Markdown支持代码块语法高亮
❓ 如何与DocuGen集成？
集成方式:
- 确保EasyRAG服务运行在
http://localhost:8028 - 在DocuGen的
.env中配置EASYRAG_API_URL=http://localhost:8028 - DocuGen会自动调用EasyRAG的检索API获取相关知识
API调用示例:
# DocuGen中的调用方式
response = requests.post("http://localhost:8028/search", json={
"knowledge_base_id": "your_kb_id",
"query": "查询内容",
"top_k": 10
})❓ 如何选择合适的模型？
Embedding模型选择:
- 中文文档:
gte-large-zh(推荐) - 英文文档:
gte-large - 资源受限:
gte-base-zh(中文) 或gte-base(英文)
重排模型选择:
- 高精度要求:
gte-reranker-large - 平衡性能:
gte-reranker-base(推荐) - 兼容性选择:
bge-reranker-base
❓ 系统支持多少文档？
容量限制:
- 免费版: 最多10万文档
- 硬件限制: 取决于内存和存储空间
- 推荐配置: 16GB内存可处理50万文档
性能优化:
- 使用SSD存储提升检索速度
- 启用GPU加速向量计算
- 定期清理无用文档和索引
❓ 如何备份和迁移数据？
数据备份:
# 备份整个数据目录
tar -czf easyrag_backup.tar.gz data/ models/ .env
# 仅备份知识库数据
cp -r data/knowledge_bases/ /path/to/backup/数据迁移:
# 解压到新环境
tar -xzf easyrag_backup.tar.gz
# 或复制数据目录
cp -r /path/to/backup/knowledge_bases/ data/本项目采用 Apache License 2.0 许可证。
如果您想为 EasyRAG 贡献代码，请确保通过代码验证。
# 运行所有验证（Python + 前端）
./validate.sh
# 仅验证 Python 代码
./validate.sh python
# 仅验证前端代码
./validate.sh frontend- Python: 使用 flake8 进行代码规范检查
- JavaScript: 使用 ESLint 进行代码规范检查
💡 详细信息请参阅 CONTRIBUTING.md
我们欢迎所有形式的贡献！
- 🐛 报告Bug: 提交Issue描述问题
- 💡 功能建议: 提出新功能想法
- 📝 文档改进: 完善文档和教程
- 💻 代码贡献: 提交Pull Request
- 📋 查阅文档 - 阅读本README和详细文档
- 🔍 搜索Issue - 在Issues区搜索类似问题
- 🐛 提交Issue - 创建新的Issue
- 💬 参与讨论 - GitHub Discussions
感谢以下开源项目的支持：
- FastAPI - 现代化的Web API框架
- Transformers - 预训练模型库
- Faiss - 高效向量相似度搜索
特别感谢：
- 🖋️ DocuGen - 基于EasyRAG的智能文档生成系统