# RAG-Project

**Repository Path**: bingofhy/rag-project

## Basic Information

- **Project Name**: RAG-Project
- **Description**: RAG-Project 是一个基于 LangChain 生态系统的企业级检索增强生成（RAG）问答系统。该项目通过整合 LangChain 的强大抽象能力，实现了代码精简（相比传统实现减少 60%）、类型安全、易于维护的现代化 RAG 系统。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-04-07
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG-LangChain 项目

企业级检索增强生成（RAG）问答系统，基于 LangChain 生态构建，支持三种智能问答模式。

## 🎯 项目概述

这是一个企业级 RAG 系统，通过**三种操作模式**应对不同数据源的问答需求：

| 模式 | 用途 | 数据源 |
|------|---------|-----------|
| **RAG 模式** | 文档问答 | PDF、Word、TXT |
| **Agent 模式** | Excel 数据分析 | Excel (.xlsx) |
| **Text2SQL 模式** | 数据库查询 | ClickHouse |

## ✨ 核心特性

### 智能检索
- **混合检索**: 向量检索（语义）+ BM25 检索（关键词）+ RRF 融合
- **问题改写**: 自动扩展为 3 个查询变体，提升召回率
- **多级存储**: 文件级、列级、元数据级三级存储架构

### 对话记忆
- **双层记忆**: Redis 短期记忆（7天）+ PostgreSQL 长期存储
- **滑动窗口**: 自动保留最近 3 轮对话（6条消息）
- **自动恢复**: 启动时从 PostgreSQL 恢复历史到 Redis

### 三种模式
- **RAG 模式**: 支持知识库检索、流式输出、来源溯源
- **Agent 模式**: 6个预定义工具、业务洞察生成、安全代码执行
- **Text2SQL 模式**: LangGraph 9节点编排、双向量检索、反馈学习

## 🛠️ 技术栈

### 后端
| 组件 | 版本 | 用途 |
|------|------|------|
| Python | 3.12.3 | 运行时 |
| FastAPI | 0.109.0 | Web 框架 |
| LangChain | 0.2.17 | LLM 框架 |
| LangGraph | 最新 | Agent 编排 |
| Celery | 5.3.4 | 异步任务 |

### 数据存储
| 组件 | 版本 | 用途 |
|------|------|------|
| PostgreSQL | 16.x | 元数据、结构化数据 |
| Redis | 7.x | 缓存、对话历史、消息队列 |
| Milvus | 2.4.3 | 向量数据库 |
| ClickHouse | 最新 | 分析数据库 |

### AI 能力
| 组件 | 说明 |
|------|------|
| Embedding 模型 | sentence-transformers/all-MiniLM-L6-v2 (384维) |
| LLM 接口 | ChatOpenAI（支持 MiniMax、Qwen 等兼容 API） |
| Agent 工具 | LangChain Tools、LangGraph StateGraph |

### 前端
| 组件 | 版本 | 用途 |
|------|------|------|
| React | 19.2.4 | UI 框架 |
| TypeScript | 5.9.3 | 类型系统 |
| Vite | 8.0.1 | 构建工具 |
| TailwindCSS | 4.2.2 | 样式框架 |

## 🚀 快速开始

### 前置要求
- Python 3.12+
- Node.js 18+
- Docker & Docker Compose
- MiniMax API Key（或其他兼容的 LLM API）

### 一键启动

```bash
# 克隆项目
git clone <repository-url>
cd RAG-Project

# 启动所有服务（Docker + 后端 + 前端）
bash start-all.sh
```

这将自动启动：
- Docker 服务（PostgreSQL、Redis、Milvus、ClickHouse）
- FastAPI 后端（端口 8000）
- Celery 异步任务处理器
- React 前端（端口 3000）

### 初始化数据库

```bash
cd backend

# 一键初始化（推荐）
bash init_all.sh

# 或分步初始化
PYTHONPATH=/home/bings/project/RAG-Project/backend ./venv/bin/python app/core/database_init.py
```

### 访问应用

- **前端**: http://localhost:3000
- **后端 API**: http://localhost:8000
- **API 文档**: http://localhost:8000/docs
- **Milvus UI**: http://localhost:8001

### 默认账号
- 用户名: `admin`
- 密码: `admin123`

## 📁 项目结构

```
RAG-Project/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── api/               # API 路由（chat、agent、text2sql）
│   │   ├── chains/            # LangChain 链路
│   │   ├── services/          # 业务服务（RAG、Agent、Text2SQL）
│   │   ├── tasks/             # Celery 异步任务
│   │   ├── core/              # 核心模块（配置、数据库、日志）
│   │   └── models/            # 数据模型
│   ├── config.yaml            # 配置文件
│   └── requirements.txt       # Python 依赖
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── pages/            # 页面组件
│   │   ├── services/         # API 客户端
│   │   └── components/       # UI 组件
│   └── package.json          # Node 依赖
├── docker-compose.yml         # Docker 服务编排
├── start-all.sh               # 一键启动脚本
└── stop-all.sh                # 一键停止脚本
```

## 🔧 配置说明

主要配置在 `backend/config.yaml`：

```yaml
# 检索配置
retriever:
  mode: "hybrid"              # vector 或 hybrid
  vector_alpha: 0.7           # 向量检索权重

# 问题改写
rewrite:
  enabled: true               # 启用问题改写

# LLM 配置
llm:
  api_base: "https://api.minimax.chat/v1"
  model: "MiniMax-M2.5"

# Text2SQL 配置
text2sql:
  enabled: true
  max_rows: 10                # 查询结果最大行数
```

环境变量在 `backend/.env`：

```bash
MINIMAX_API_KEY=your_api_key
JWT_SECRET=your_jwt_secret
```

## 📊 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        前端层 (React)                        │
│                   HTTP / SSE 流式输出                        │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   API 路由层 (FastAPI)                       │
│   /chat/*     /agent/*     /text2sql/*    /doc/*   /kb/*   │
│  RAG问答    Excel分析    数据库查询    文档管理  知识库   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                      服务层                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │ RAG Chain    │  │ Excel Agent  │  │ Text2SQL     │    │
│  │ (LangChain)  │  │ (6工具)      │  │ (9节点)      │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │ LLM Service  │  │Memory Service│  │Vector Store  │    │
│  │ (ChatOpenAI) │  │ (Redis+PG)   │  │ (Milvus)     │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                      数据层                                  │
│  PostgreSQL(元数据)  Redis(缓存)  Milvus(向量)  ClickHouse │
└─────────────────────────────────────────────────────────────┘
```

## 🧪 测试

```bash
cd backend

# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_chat_api.py -v        # RAG 模式测试
pytest tests/test_agent_api.py -v       # Agent 模式测试
pytest tests/test_text2sql_api.py -v    # Text2SQL 模式测试

# 生成测试覆盖率报告（后端业务逻辑）
pytest tests/ --cov=app --cov-report=html

# 覆盖率报告生成位置
# htmlcov/index.html - 在浏览器中打开查看详细覆盖率报告
```

**测试覆盖范围**：
- API 路由层（`app/api/`）：所有 API 端点
- 服务层（`app/services/`）：RAG、Agent、Text2SQL 核心业务逻辑
- 链路层（`app/chains/`）：LangChain 链路编排
- 数据模型（`app/models/`）：SQLModel 数据模型
- 核心模块（`app/core/`）：配置、数据库、日志等基础功能

**测试文件位置**：`/home/bings/project/RAG-Project/backend/tests/`

## 📝 日志

```bash
# 查看后端日志
tail -f logs/backend.log

# 查看 Celery 日志
tail -f logs/celery.log

# 查看前端日志
tail -f logs/frontend.log
```

## 🔗 相关文档

- **[架构文档](./ARCHITECTURE.md)** - 详细技术架构和业务流程
- **[开发指南](./CLAUDE.md)** - 开发者指南和命令参考

## 📄 许可证

MIT License

---

**版本**: 3.0.0
**最后更新**: 2026-04-21