# agentic-rag

**Repository Path**: wzcool/agentic-rag

## Basic Information

- **Project Name**: agentic-rag
- **Description**: agentic rag
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: RAG, Agentic-RAG

## README

# 多模态RAG-企业知识库

## 系统简介
本项目是一个基于RAG（Retrieval-Augmented Generation）的企业知识库系统，支持多模态文档处理、混合检索和智能问答。系统采用Docker Compose进行部署，包含以下核心组件：
1. **RAG API**: 基于FastAPI的后端服务，负责文档处理、检索和问答接口。
2. **Web UI**: 基于Angular的前端界面和Vue的前端界面（赛博朋克样式），提供用户上传文档、对话查询和实时参数配置等功能。
3. **MySQL**: 数据存储，包括用户信息、文档管理、权限管理、角色管理、重置密码、用户反馈、用户操作日志和系统配置等。
4. **Redis**: 缓存和会话管理，用于存储上下文信息，提高系统性能和响应速度。
5. **Ollama**: 用于本地部署Ollama模型，支持多模型调用。
6. **Dashscope**: 用于调用Dashscope的模型，支持多模型调用。
7. **ElasticSearch**: 向量数据库，用于存储和检索文档向量。
8. **Milvus**: 向量数据库，用于模型向量存储和检索。


**ElasticSearch** 和 **Milvus** 根据需要选择安装。
用于存储向量数据（元数据、文档向量、图片向量、视频向量和用户反馈），支持关键字+向量检索的混合检索。
ElasticSearch和Milvus，只需要根据需要更改配置即可在ElasticSearch和Milvus之间切换。

## 项目演示
蓝色风格：（Angular, v19.2）

![企业应用风格](docs/screenshots/rag-angular.gif)

赛博朋克风格：(Vue, v3.5.13) +换肤+ 国际化

![赛博朋克风格](docs/screenshots/rag-vue.gif)

## 本地开发环境
1. Docker Desktop
https://www.docker.com/products/docker-desktop/

2. Ollama, 用于本地部署Ollama模型
https://ollama.com/download/windows

3. Python 3.8+ (推荐3.11.9)
https://www.python.org/downloads/

4. Node.js 16+ （24.12.0 和 npm 11.6.2+）
https://nodejs.org/en/download
你可以安装nvm，利用nvm安装nodejs

5. Git (可选，用于版本控制)
https://git-scm.com/install/windows

6. Visual Studio Code (用于代码编辑和调试)
https://code.visualstudio.com/Download

以下为可选组件，根据需要选择安装，如果运行start-docker.bat默认会被安装到Docker Desktop中：
7. MySQL (可选，用于用户数据存储，可以不安装)
8. Elasticsearch (可选，用于向量数据库)
9. Redis (可选，用于缓存和会话管理，可以不安装)


## 部署到Docker Desktop中

```bash
# 启动服务，会自动部署到Docker中
start-docker.bat
```

### docker-compose.yml中连接说明

所有连接使用的是service name，而不是localhost。例如，API连接MySQL使用`mysql-db:3306`，连接ElasticSearch使用`elasticsearch:9200`。
不要使用container name，而要使用service name。

```bash
services:
  # Server MySQL Database. Make sure to set MYSQL_ROOT_PASSWORD in your .env file.
  # mysql-db:就是API链接字符串中的Server=mysql-db;
  mysql-db:
    env_file:
      - .env
    image: mysql:8.0
    container_name: mysql-container-name
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
    ports:
      - "3306:3306"

  rag-api:
    build: ./rag-api
    container_name: rag-api
    env_file:
      - .env
    ports:
      - "8002:8000"
    environment:
      - MYSQL_HOST=mysql-db # MySQL数据库主机地址适用service name
```sql
SET SQL_SAFE_UPDATES = 0;
```

### 访问服务

- **Web UI**: http://localhost:7002
- **API文档**: http://localhost:8002/docs
- **ElasticSearch**: http://localhost:9201

### 服务说明

#### 1. ElasticSearch (端口9201，Docker容器对外的端口是9201，内部端口是9200)
- 向量数据库
- 存储文档和向量

#### 2. RAG API (端口8002)
- FastAPI后端服务
- 文档处理和查询接口
- 自动文档: http://localhost:8002/docs

#### 3. Web UI (端口7002)
- Angular前端界面
- 文档上传和对话查询
- 实时参数配置

#### 4. MySQL (端口3306)
- 用户数据存储
- 反馈数据存储


## 本地开发

### 安装RAG API依赖

```bash
cd src
cd rag-api

pip install -r requirements.txt
```

### 安装Web UI依赖

```bash
cd src
cd rag-ui

npm install

```

### 运行RAG API + UI

直接运行 start.bat 启动服务，

```bash
start.bat
```

或者分别启动API和UI：
#### API：http://localhost:8000/docs
```bash
cd rag-api

uvicorn api.main:app --host 0.0.0.0 --port 8000
```
#### UI：http://localhost:4200
```bash
cd rag-ui

npm start
```

## 项目结构

```
src/  # 项目源码
├── docker-compose.yml           # 完整服务编排
├── .env                        # 环境变量配置
├── rag-api/         # 后端API
│   ├── api/                    # FastAPI应用
│   ├── benchmark/              # 离线基准测试
│   ├── config/                 # 配置文件
│   ├── models/                 # 模型适配器
│   ├── document_processing/    # 文档处理
│   ├── storage/                # 存储层（ES + MySQL）
│   ├── retrieval/              # 检索层（混合检索+重排序）
│   ├── workflow/               # LangGraph工作流
│   ├── evaluation/             # 评估指标
│   ├── feedback/               # 用户反馈
│   ├── tools/                  # 外部工具（智谱搜索）
│   ├── utils/                  # 工具函数
│   ├── init_mysql.sql          # MySQL初始化脚本
│   └── Dockerfile
├── rag-ui/             # 前端UI（rag-ui：Angular版本；rag-ui-react：React版本；rag-ui-vue:Vue版本）
│   ├── src/                    # 应用
│   ├── nginx.conf              # Nginx配置
│   └── Dockerfile
docs/   # 项目文档
    ├── POSTMAN_README.md       # API测试文档
    └── rag-api.postman_collection.json
```

### 配置

#### 配置文件说明

项目提供三个配置文件，适用于不同的部署场景：

- **models.yaml**: Docker部署配置（默认）
- **models_dev.yaml**: 本地开发配置
- **models_cloud.yaml**: 云端API配置

#### 修改配置文件

编辑 `rag-api/config/models.yaml`:

```yaml
embedding:
  provider: "ollama"  # 或 "cloud"
  model: "bge-m3:567m"  # 快速嵌入模型（1024维）
  base_url: "http://host.docker.internal:11434"

vision:
  provider: "ollama"
  model: "qwen3-vl:4b"  # 视觉模型用于图片处理
  base_url: "http://host.docker.internal:11434"

llm:
  provider: "ollama"
  model: "kamekichi128/qwen3-4b-instruct-2507:latest"
  base_url: "http://host.docker.internal:11434"
  temperature: 0.7

reranker:
  provider: "ollama"
  model: "qllama/bge-reranker-v2-m3:latest"
  base_url: "http://host.docker.internal:11434"
  enabled: true
  timeout: 10

zhipu:
  api_key: "your-zhipu-api-key"
  base_url: "https://open.bigmodel.cn/api/paas/v4"

mysql:
  host: "mysql-db"
  port: 3306
  user: "root"
  password: "Wz@273509239"
  database: "rag_db"

elasticsearch:
  hosts:
    - "http://elasticsearch:9200"
  username: "elastic"
  password: "Wz@273509239"
  text_index: "documents"
  image_index: "images"
  vector_dims: 1024  # 匹配bge-m3模型维度

chunk_size: 500
chunk_overlap: 50
top_k: 10
rerank_top_k: 5

security:
  jwt_secret: "rag-knowledge-base-super-secret-key-change-in-production-min-32-chars"
  jwt_algorithm: "HS256"
  jwt_expire_hours: 24
  enable_prompt_detection: true
  enable_audit_logging: true
  max_login_attempts: 5
  lockout_minutes: 15

rate_limit:
  enabled: true
  query_per_minute: 100
  upload_per_minute: 20
  login_per_minute: 10
```

#### 本地开发配置 (models_dev.yaml)

```yaml
embedding:
  model: "bge-m3:567m"
  base_url: "http://localhost:11434"  # 本地Ollama

elasticsearch:
  hosts:
    - "http://127.0.0.1:9201"  # 本地ES端口
```

#### 云端API配置 (models_cloud.yaml)

```yaml
embedding:
  provider: "cloud"
  model: "bge-m3:567m"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  api_key: ""  # 从环境变量DASHSCOPE_API_KEY读取

llm:
  provider: "cloud"
  model: "qwen-turbo"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"

mysql:
  database: "rag-api_cloud"

elasticsearch:
  text_index: "documents_cloud"
  image_index: "images_cloud"
```

#### 环境变量

编辑 `.env` 文件：

```env
MYSQL_ROOT_PASSWORD=Wz@273509239
MYSQL_DATABASE=rag_db
MYSQL_USER_NAME=root
ASPNETCORE_ENVIRONMENT=Production
```

### 停止服务

```bash
docker-compose down

# 删除数据卷
docker-compose down -v
```

### 查看日志

```bash
# 所有服务
docker-compose logs -f

# 特定服务
docker-compose logs -f rag-api
docker-compose logs -f rag_ui
docker-compose logs -f elasticsearch
docker-compose logs -f mysql-db

```

### 故障排除

### 文件上传问题

**文件大小限制**：
- 默认最大文档大小：100MB
- 默认最大视频大小：500MB
- 默认最大图片大小：10MB

**修改上传限制**：

1. 编辑 `rag-api/config/models.yaml`：
```yaml
storage:
  max_document_size: 209715200  # 200MB
  max_video_size: 1073741824    # 1GB
```

2. 编辑 `rag-ui/nginx.conf`：
```nginx
client_max_body_size 200M;
```

3. 重启服务：
```bash
docker-compose restart rag-ui rag-api
```

详见 [docs/FILE_UPLOAD_CONFIG.md](docs/FILE_UPLOAD_CONFIG.md)

### API超时问题

**症状**：上传大文件或处理复杂文档时出现504 Gateway Timeout

**解决方案**：

1. 增加Nginx超时时间（`rag-ui/nginx.conf`）：
```nginx
location /api/ {
    proxy_connect_timeout 600s;  # 10分钟
    proxy_send_timeout 600s;
    proxy_read_timeout 600s;
}
```

2. 重启UI服务：
```bash
docker-compose restart rag-ui
```

3. 优化处理性能：
- 使用更快的嵌入模型（bge-m3:567m）
- 减小chunk_size（从500降到300）
- 禁用重排序（reranker.enabled: false）

### 服务未启动

```bash
# 检查服务状态
docker-compose ps

# 重启服务
docker-compose restart
```

### 端口冲突

修改 `docker-compose.yml` 中的端口映射：

```yaml
ports:
  - "80:80"  # 改为 "8080:80"
```

### ElasticSearch 内存不足

修改 `docker-compose.yml`:

```yaml
environment:
  - "ES_JAVA_OPTS=-Xms1g -Xmx1g"  # 增加内存
```

### ElasticSearch 重建索引

```bash
cd rag-api

# 预览操作（不执行）
python tools/rebuild_es_indices.py --dry-run

# 重建全部索引
python tools/rebuild_es_indices.py --config models_dev.yaml

# 只重建 documents 索引
python tools/rebuild_es_indices.py --index documents
```


### 查询报错：field [content_vector] does not exist

**问题原因**：图像索引使用 `content_vector` 字段，而不是 `content_vector`。

**解决方案**：
1. 确保使用最新代码（已修复混合检索器中的字段映射）
2. 如果索引已存在，需要重建索引：

```bash
# 删除现有索引
curl -X DELETE "http://localhost:9201/images"

# 重启API服务以重建索引
docker-compose restart rag-api
```

**技术说明**：
- 文本索引 (`documents`) 使用 `content_vector` 字段存储向量
- 图像索引 (`images`) 使用 `content_vector` 字段存储向量
- 图像索引使用 `image_description` 字段进行关键词搜索

## 功能特性

### 文档处理
- ✅ 7种文档格式支持（PDF, Word, Excel, PPT, TXT, MD, 图像）
- ✅ 智能分块（可配置chunk_size和overlap）
- ✅ 多模态支持（文本+图像+表格）
- ✅ 视觉模型处理图片内容
- ✅ 表格结构化提取

### 检索增强
- ✅ 混合检索（向量 + 关键词 + RRF融合）
- ✅ 智能重排序（BGE Reranker）
- ✅ 查询优化和扩展
- ✅ 可配置top_k和rerank_top_k

### 模型支持
- ✅ Ollama本地模型
  - 嵌入: bge-m3:567m (1024维，快速)
  - LLM: qwen3-4b-instruct (4B参数)
  - 视觉: qwen3-vl:4b (多模态)
  - 重排序: bge-reranker-v2-m3
- ✅ 云端API支持
  - 阿里云DashScope (qwen-turbo)
  - 智谱AI搜索工具
- ✅ 多模型适配器架构
- ✅ 灵活切换本地/云端模型

### 工作流
- ✅ LangGraph工作流编排
- ✅ 答案验证和置信度评估
- ✅ 多轮对话支持
- ✅ 流式响应

### 数据存储
- ✅ ElasticSearch向量存储
- ✅ MySQL用户和反馈数据
- ✅ 双索引设计（文本+图像）

### 评估与优化
- ✅ 离线基准测试框架
- ✅ 多维度评估指标（Recall, Precision, MRR）
- ✅ 用户反馈收集
- ✅ 性能监控

### 部署与接口
- ✅ Docker Compose一键部署
- ✅ Angular Web UI
- ✅ RESTful API
- ✅ Swagger文档
- ✅ 健康检查机制
- ✅ 富内容显示（图像、表格、文本）


### 运行基准测试

```bash
cd rag-api
python benchmark/evaluate.py
```

详见 [benchmark/README.md](rag-api/benchmark/README_Benchmark.md)

## API测试

使用Postman导入测试集合：
- 集合文件：`docs/rag-api.postman_collection.json`
- 环境文件：`docs/RAG_Local.postman_environment.json`

详见 [docs/POSTMAN_README.md](docs/POSTMAN_README.md)

## 性能优化

### 推荐配置

**生产环境推荐配置**（平衡性能和质量）：

```yaml
embedding:
  model: "bge-m3:567m"  # 1024维，快速
  
llm:
  model: "kamekichi128/qwen3-4b-instruct-2507:latest"  # 4B参数
  
vector_dims: 1024  # 匹配嵌入模型维度
top_k: 10  # 检索数量
rerank_top_k: 5  # 重排序后保留数量
chunk_size: 500  # 文档块大小
chunk_overlap: 50  # 块重叠大小
```

**性能对比**：

| 配置 | 嵌入速度 | 查询速度 | 质量 |
|------|---------|---------|------|
| qwen3-embedding:4b (2560维) | 4.7s | 慢 | 高 |
| bge-m3:567m (1024维) | 0.5-1.0s | 快 | 高 |
| 云端API | 0.3-0.8s | 很快 | 高 |

### 性能调优建议

1. **使用更快的嵌入模型**: bge-m3 比 qwen3-embedding 快80%
2. **减小top_k**: 从20降到10可提升30%性能
3. **禁用重排序**: 如果对精度要求不高，设置 `reranker.enabled: false`
4. **使用GPU**: 如果有GPU，性能可提升5-10倍
5. **启用缓存**: 相同查询会被缓存，响应时间<0.001s

## 安全配置

### JWT认证

```yaml
security:
  jwt_secret: "your-secret-key-min-32-chars"  # 生产环境必须修改
  jwt_algorithm: "HS256"
  jwt_expire_hours: 24
  enable_prompt_detection: true  # Prompt注入检测
  enable_audit_logging: true  # 审计日志
  max_login_attempts: 5  # 最大登录尝试次数
  lockout_minutes: 15  # 锁定时间
```

### 速率限制

```yaml
rate_limit:
  enabled: true
  query_per_minute: 100  # 每分钟查询次数
  upload_per_minute: 20  # 每分钟上传次数
  login_per_minute: 10  # 每分钟登录次数
```

### 安全最佳实践

1. **修改默认密码**: 修改MySQL和ES的默认密码
2. **使用强JWT密钥**: 至少32个字符的随机字符串
3. **启用HTTPS**: 生产环境使用SSL/TLS
4. **定期备份**: 定期备份MySQL和ES数据
5. **监控日志**: 定期检查审计日志

# 许可证

MIT License

# 联系方式
📧 联系方式

- Wechat: +86 18901599114 
- Tel: +86 18901599114
- Email: 18901599114@163.com

# 开发者
- [Sponsor the developer](https://github.com/sponsors/agentic-rag/sponsor)

# 赞助开发者，助力开源项目成长！💖
| 支付宝 | 微信支付 |
|--------|----------|
|<img src="docs/screenshots/alipay.jpg" width="200px" height="270px" alt="支付宝">|<img src="docs/screenshots/wechat_pay.jpg" width="200px" height="270px" alt="微信">|