# rag-dev

**Repository Path**: gooree/rag-dev

## Basic Information

- **Project Name**: rag-dev
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 知识库智能问答系统

基于 Retrieval-Augmented Generation (RAG) 技术的智能问答系统，支持知识库管理、文档上传、智能检索和对话式问答。

## 🏗️ 技术架构

### 后端 (Python/FastAPI)
- **Web 框架**: FastAPI + Uvicorn
- **数据库**: PostgreSQL + pgvector (向量存储)
- **ORM**: SQLAlchemy 2.0 (异步)
- **RAG 引擎**: LangChain + 自定义 Pipeline
- **文档解析**: PyPDF, python-docx, unstructured
- **日志**: Loguru

### 前端 (Vue3)
- **框架**: Vue 3 + TypeScript + Composition API
- **UI 库**: Element Plus
- **状态管理**: Pinia
- **构建工具**: Vite
- **HTTP 客户端**: Axios

### 部署
- **容器化**: Docker + Docker Compose
- **反向代理**: Nginx

## 📋 功能特性

1. **知识库管理**
   - 创建/编辑/删除知识库
   - 配置分块策略（大小、重叠）
   - 查看文档统计信息

2. **文档管理**
   - 支持 PDF, DOCX, TXT, MD 格式
   - 自动文本解析与分块
   - 向量化处理与存储
   - 文档状态实时监控

3. **智能问答**
   - 基于 RAG 的精准回答
   - 混合检索（向量 + 关键词）
   - 引用来源展示
   - 多轮对话支持

4. **系统集成**
   - 兼容 OpenAI 格式的自托管 LLM
   - 支持 Ollama, vLLM, TGI 等
   - 灵活的 Embedding 模型配置

## 🚀 快速开始

### 前置要求
- Docker & Docker Compose
- Python 3.12+ (本地开发)
- Node.js 22+ (本地开发)

### 方式一：Docker 一键部署

```bash
# 1. 克隆项目
cd rag-dev

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置 LLM 服务地址

# 3. 启动所有服务
docker-compose up -d

# 4. 访问应用
# 前端: http://localhost
# 后端 API: http://localhost:8000
# API 文档: http://localhost:8000/docs
```

### 方式二：本地开发

#### 后端开发

```bash
# 1. 进入后端目录
cd rag-backend

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 5. 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

#### 前端开发

```bash
# 1. 进入前端目录
cd rag-frontend

# 2. 安装依赖
pnpm install  # 或 npm install

# 3. 启动开发服务器
pnpm dev  # 或 npm run dev

# 4. 访问应用
# http://localhost:5173
```

## 📁 项目结构

```
rag-dev/
├── rag-backend/              # Python 后端
│   ├── app/
│   │   ├── api/             # API 路由层
│   │   ├── models/          # 数据模型 (SQLAlchemy)
│   │   ├── schemas/         # API Schema (Pydantic)
│   │   ├── services/        # 业务逻辑层
│   │   ├── repositories/    # 数据访问层
│   │   ├── rag/             # RAG 核心模块
│   │   │   ├── chunkers/    # 文本分块
│   │   │   ├── embedders/   # 向量化器
│   │   │   ├── retrievers/  # 检索器
│   │   │   ├── generators/  # LLM 生成器
│   │   │   └── pipeline.py  # Pipeline 编排
│   │   ├── utils/           # 工具函数
│   │   ├── config.py        # 配置管理
│   │   ├── database.py      # 数据库连接
│   │   └── main.py          # FastAPI 入口
│   ├── tests/               # 测试代码
│   ├── migrations/          # Alembic 迁移
│   ├── requirements.txt     # Python 依赖
│   └── Dockerfile
├── rag-frontend/             # Vue3 前端
│   ├── src/
│   │   ├── api/             # API 请求封装
│   │   ├── components/      # 公共组件
│   │   ├── composables/     # 组合式函数
│   │   ├── router/          # 路由配置
│   │   ├── stores/          # Pinia 状态管理
│   │   ├── styles/          # 全局样式
│   │   ├── types/           # TypeScript 类型
│   │   ├── views/           # 页面组件
│   │   ├── App.vue
│   │   └── main.ts
│   ├── package.json
│   ├── vite.config.ts
│   └── Dockerfile
├── docker-compose.yml        # Docker 编排
├── init.sql                  # 数据库初始化
└── README.md
```

## 🔧 配置说明

### 环境变量 (.env)

```bash
# LLM 服务配置
LLM_BASE_URL=http://localhost:11434/api    # Ollama 地址
LLM_MODEL=qwen2.5:7b                       # 模型名称
LLM_API_KEY=sk-not-needed                  # API Key (如需要)

# Embedding 配置
EMBEDDING_MODEL=bge-m3                     # 向量模型
EMBEDDING_DIMENSION=1024                   # 向量维度

# 数据库配置
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/rag_db

# 检索配置
VECTOR_SEARCH_TOP_K=5                      # 默认检索数量
VECTOR_SEARCH_SCORE_THRESHOLD=0.5          # 最低相似度阈值
```

## 📡 API 接口

### 知识库管理
```
GET    /api/v1/knowledge-bases            # 获取列表
POST   /api/v1/knowledge-bases            # 创建
GET    /api/v1/knowledge-bases/{id}       # 详情
PUT    /api/v1/knowledge-bases/{id}       # 更新
DELETE /api/v1/knowledge-bases/{id}       # 删除
```

### 文档管理
```
GET    /api/v1/documents/kb/{kb_id}       # 获取文档列表
POST   /api/v1/documents/upload           # 上传文档
DELETE /api/v1/documents/{doc_id}         # 删除文档
```

### 智能问答
```
POST   /api/v1/chat/query                 # 发送问题
GET    /api/v1/chat/sessions/{session_id} # 获取历史
DELETE /api/v1/chat/sessions/{session_id} # 删除会话
```

## 🔍 RAG 流程详解

```
1. 文档上传 → 2. 文本解析 → 3. 智能分块 → 4. 向量化 → 5. 存储到 pgvector
                                                                      ↓
用户提问 ← LLM 生成 ← 提示词工程 ← 混合检索 ← 查询向量化
```

### 分块策略
- **递归字符分块** (默认): 按段落、句子、单词递归分割
- **语义分块**: 基于语义边界分割，保持内容完整性
- **固定长度分块**: 按固定字符数分割

### 检索策略
- **向量检索**: 使用余弦相似度匹配
- **混合检索**: 向量检索 + BM25 关键词检索
- **RRF 融合**: 使用倒数秩融合算法合并结果

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License