general-rag-system

依赖服务部署

使用 Docker Compose 一键部署所有依赖服务（推荐）：

```bash

🚀 快速开始

创建 docker-compose.yml 后执行

docker-compose up -d ```

或手动安装： - MySQL 8.0+ - 业务数据库 - Redis 6.x/7.x - 缓存、Session、JWT 黑名单 - Milvus 2.6+ - 向量数据库（需配置认证） - MinIO Latest - 对象存储（S3 兼容） - RabbitMQ 3.x - 消息队列（需配置用户名密码）

快速开始贡献

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'feat: add some amazing feature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

1. 编辑 model_config.json（参考 model_config.json.example）

生产环境建议使用环境变量替代硬编码

```

⚠️ 注意： - model_config.json 不要提交到 Git - main.py 中的基础设施配置为硬编码，生产环境需修改或使用环境变量

📖 详细配置说明：rag-llm/README.md

📚 安全配置指南：SECURITY.md

启动服务

1. 启动前端（端口 5173）

```bash cd rag-client npm install npm run dev

后端运行在 http://localhost:8080/api

⚠️ **注意**：必须使用 Java 11（不支持其他版本）

📖 详细配置请参考：[rag-server/README.md](./rag-server/README.md)

#### 3. 启动 LLM 服务（端口 8888，root_path /rag）

LLM 服务运行在 http://localhost:8888

📖 详细配置请参考：[rag-llm/README.md](./rag-llm/README.md)

#### 4. 启动本地向量化服务（可选，需 GPU）

如果需要使用本地向量化和重排序服务（不依赖外部 API），需要 GPU 支持：

启动 Embedding 服务（端口 8890）

python embedding_start.py

启动 Rerank 服务（端口 8891）

python rerank_start.py ```

系统要求： - GPU: NVIDIA GPU（推荐 4GB+ 显存，最佳 8GB+） - CUDA: 11.8+ - Python: 3.8+ - vLLM: 0.8.5+

📖 详细配置请参考： - Embedding 服务文档 - Rerank 服务文档

或使用环境变量

export EMBEDDING_SERVICE_URL="http://localhost:8890" export RERANK_SERVICE_URL="http://localhost:8891" ```

然后在 RAG 流程中调用本地服务替代外部API。 </details>

<details> <summary><b>Q: 本地向量化服务需要什么硬件配置？</b></summary>

A: 最低配置： - GPU: NVIDIA GPU (4GB显存，如GTX 1650) - CPU: 4核 - 内存: 8GB - 硬盘: 10GB

推荐配置： - GPU: NVIDIA GPU (8GB+显存，如RTX 3060) - CPU: 8核+ - 内存: 16GB+ - 硬盘: 20GB+ SSD - CUDA: 11.8+

性能对比： - 4GB显存: 可运行，需调低 gpu_memory_utilization - 8GB显存: 流畅运行，推荐配置 - 16GB+显存: 可同时运行多个服务或更大模型 </details>

配置文件

⚠️ 重要：配置敏感信息

本项目的配置文件包含敏感信息（API 密钥、数据库密码等），已被 .gitignore 排除。您需要手动创建配置文件：

1. 后端配置（rag-server）

```bash cd rag-server/src/main/resources

2. 编辑 main.py 中的基础设施连接配置（约第 30-40 行）：

编辑 src/main/resources/application-dev.yml 配置数据库等信息

mvn clean install mvn spring-boot:run

编辑 model_config.json 配置各 LLM 的 API Key

🔧 配置指南

环境变量方式（推荐生产环境）

```bash

后端服务环境变量

export MYSQL_PASSWORD=your_password export JWT_SECRET=your_jwt_secret_key export MINIO_SECRET_KEY=your_minio_key export REDIS_PASSWORD=your_redis_password

LLM服务环境变量

export OPENAI_API_KEY=sk-xxxxx export DEEPSEEK_API_KEY=sk-xxxxx export QWEN_API_KEY=sk-xxxxx ```

在 config.py 中查找端口配置

search_by_grep(keywords=["port"], file_names=["config.py"])

查找所有配置文件

list_filename_by_like(pattern="%config%", limit=30)

配置说明

在 agentic_rag_controller.py 中可配置： - max_rounds: 最大检索轮次（默认5） - grade_score_threshold: Rerank分数阈值（默认0.4） - top_k: 每轮检索返回数量（默认10）

在 main.py 中配置

EMBEDDING_SERVICE_URL = "http://localhost:8890" RERANK_SERVICE_URL = "http://localhost:8891"

- MinIO 访问密钥（endpoint, access-key, secret-key）

填入各 LLM 的 API Key：

- MinIO 访问密钥（endpoint, access-key, secret-key）

在多个 controller 文件中查找 API 端点

search_by_grep(keywords=["@app.route", "POST"], file_names=["user_controller.py", "auth_controller.py"])

#### 2 & 3. chunk_range 工具 - 文档片段获取
**适用场景**：补全上下文、扩展文档范围、绕过检索失败
- `search_by_document_and_chunk_range` - 按文档ID获取
- `search_by_filename_and_chunk_range` - 按文件名获取
- 解决语义检索和关键词检索都失效的情况

**示例**：

模块详细文档

📚 各模块详细技术文档： - rag-client 前端文档 - Vue 3 开发指南、页面路由、状态管理 - rag-server 后端文档 - Spring Boot 配置、API 路由、MyBatis 使用 - rag-llm AI 服务文档 - Agentic RAG 实现、LLM 集成、RabbitMQ 消费者 - embedding_rerank 本地向量化文档 - vLLM 部署、性能调优

- 其他模型服务

工作流程

用户提问
   ↓
┌─────────────────────────────────────┐
│  Agentic RAG Controller (LangGraph) │
├─────────────────────────────────────┤
│  第1轮：决策检索策略                 │
│  ├─ 分析问题类型                     │
│  ├─ 选择工具（5选1）                 │
│  └─ 执行检索                         │
│                                     │
│  第2-5轮：迭代优化（如需）            │
│  ├─ 评估当前检索结果                 │
│  ├─ 决定继续/停止                    │
│  ├─ 补全上下文/换角度检索            │
│  └─ 更新检索历史                     │
│                                     │
│  构建上下文                          │
│  ├─ 合并检索结果                     │
│  ├─ 去重并排序                       │
│  └─ 格式化为上下文                   │
└─────────────────────────────────────┘
   ↓
生成回答（流式输出）

优势对比

🙋 常见问题

<details> <summary><b>Q: 如何选择合适的 LLM 模型？</b></summary>

A: 建议根据场景选择： - 快速响应：GPT-3.5、DeepSeek-Chat、Qwen-Plus - 高质量：GPT-4、Claude-3、Qwen-Max - 成本优化：本地部署开源模型（LLaMA、ChatGLM） </details>

<details> <summary><b>Q: Agentic RAG 和传统 RAG 有什么区别？</b></summary>

A: 主要区别： - 检索策略：传统RAG单一固定，Agentic RAG自主选择5种工具 - 检索轮次：传统RAG单次检索，Agentic RAG支持最多5轮迭代 - 上下文处理：Agentic RAG自动补全不连续chunk，提供完整上下文 - 适应性：Agentic RAG根据问题类型动态调整策略 - 透明度：Agentic RAG实时展示检索过程和决策理由

推荐在复杂问答、代码搜索、多文档关联等场景使用 Agentic RAG。 </details>

<details> <summary><b>Q: Agentic RAG 的5种工具如何选择？</b></summary>

A: LLM会根据问题类型自动选择： - 结构化查找（如"XXX方法在哪"）→ search_by_grep - 概念理解（如"什么是XXX"）→ search_by_multi_queries_in_database - 文件探索（如"有哪些配置文件"）→ list_filename_by_like - 上下文补全（检索到不连续chunk）→ chunk_range 工具 - 检索失效（其他工具无法命中）→ chunk_range 兜底

系统会在每轮检索后评估结果，决定是否继续、使用哪个工具。 </details>

<details> <summary><b>Q: 向量数据库可以替换为其他方案吗？</b></summary>

A: 可以，本项目基于 LangChain，理论上支持： - Milvus（当前方案，推荐） - Pinecone、Weaviate、Qdrant - Elasticsearch（需要修改部分代码） </details>

<details> <summary><b>Q: 支持哪些文档格式？</b></summary>

A: 当前支持： - PDF（通过 PyMuPDF / pdfplumber） - TXT、MD（纯文本、Markdown） - 图片OCR（通过 Tesseract，需要额外安装）

可通过扩展 rag_utils.py 支持更多格式（Word、Excel、HTML等） </details>

<details> <summary><b>Q: LLM服务为什么运行在8888端口？</b></summary>

A: 这是在 main.py 中配置的，建议使用：

uvicorn main:app --host 0.0.0.0 --port 8888 --workers 2

<details> <summary><b>Q: embedding_rerank 模块的作用是什么？</b></summary>

A: embedding_rerank 提供本地向量化和重排序服务，包含两个独立的微服务：

Embedding 服务 (端口: 8890) - 基于 Qwen3-Embedding-0.6B 模型 - 将文本转换为768维向量 - 支持批量向量化（最多1024条/次） - 兼容 OpenAI Embeddings API 格式

Rerank 服务 (端口: 8891) - 基于 Qwen3-Reranker-0.6B 模型 - 对检索结果进行精确重排序 - 提高召回文档的相关性 - 支持批量重排序

适用场景： - ✅ 对数据隐私有严格要求 - ✅ 希望降低外部API调用成本 - ✅ 有本地GPU资源（推荐4GB+显存） - ✅ 需要完全离线部署

技术栈： - vLLM 0.8.5+ (高性能推理引擎) - FastAPI (异步Web框架) - PyTorch (深度学习框架)

性能参考： - Embedding: ~100条/秒 (单GPU, batch_size=32) - Rerank: ~50对/秒 (单GPU, batch_size=16)

详见: Embedding文档 | Rerank文档 </details>

<details> <summary><b>Q: 如何在 rag-llm 中使用本地向量化服务？</b></summary>

A: 配置 rag-llm/main.py 或使用环境变量：

```python