# RAG学习

**Repository Path**: tdnm/rag-learning

## Basic Information

- **Project Name**: RAG学习
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-31
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG Enterprise - 企业级 RAG 问答系统

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)
[![Docker](https://img.shields.io/badge/Docker-Compose-blue.svg)](https://docker.com)
[![FastAPI](https://img.shields.io/badge/FastAPI-Latest-green.svg)](https://fastapi.tiangolo.com)
[![vLLM](https://img.shields.io/badge/vLLM-Latest-orange.svg)](https://github.com/vllm-project/vllm)

## 📋 项目简介

这是一个基于企业级架构设计的 RAG（Retrieval-Augmented Generation）问答系统，支持高性能、可扩展的本地部署。

### 🎯 核心特性

- **高性能推理**: 基于 vLLM 的高吞吐 LLM 推理
- **智能检索**: BGE Embedding + 重排序器优化
- **可扩展架构**: Docker 容器化，支持横向扩展
- **企业级评估**: 集成 RAGAS 评估框架
- **RESTful API**: 标准化的接口设计
- **健康监控**: 完整的服务监控和日志

### 🛠️ 技术栈

| 组件 | 技术选择 | 说明 |
|------|----------|------|
| **LLM 推理** | vLLM | 高性能 GPU 推理服务 |
| **Embedding** | BAAI/bge-small-en-v1.5 | 轻量级多语言向量模型 |
| **向量数据库** | Qdrant | 高性能向量存储 |
| **Web 框架** | FastAPI | 现代异步 API 框架 |
| **RAG 框架** | LlamaIndex | 优化的 RAG 构建工具 |
| **重排序** | BGE Reranker | 检索结果优化 |
| **评估** | RAGAS | RAG 系统评估标准 |
| **部署** | Docker Compose | 容器化编排 |

## 🚀 快速开始

### 系统要求

- **操作系统**: Linux/Windows/macOS
- **Docker**: 20.10.0+
- **Docker Compose**: 2.0.0+
- **GPU**: NVIDIA GPU (推荐 RTX 3090/4090 或更高)
- **内存**: 16GB+ (推荐 32GB+)
- **存储**: 50GB+ 可用空间

### 一键启动

```bash
# 1. 克隆项目
git clone <repository-url>
cd rag-enterprise

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

# 3. 检查服务状态
docker-compose ps

# 4. 构建索引（首次运行）
docker-compose exec rag-api python ingest.py
```

### 验证部署

```bash
# 测试 API 接口
curl -X GET "http://localhost:18001/health"

# 测试问答功能
curl -X POST "http://localhost:18001/query" \
     -H "Content-Type: application/json" \
     -d '{"query": "请假流程是什么？"}'
```

## 📖 详细部署指南

### 1. 环境准备

#### 安装 Docker 和 Docker Compose

**Ubuntu/Debian:**
```bash
# 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```

**Windows/macOS:**
- 下载并安装 [Docker Desktop](https://www.docker.com/products/docker-desktop)

#### 配置 GPU 支持（推荐）

```bash
# 安装 NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
```

### 2. 项目配置

#### 环境变量配置

```bash
# 复制并编辑环境配置
cp .env .env.local

# 根据实际情况修改配置
vim .env.local
```

主要配置项说明：

```bash
# 模型配置
VLLM_MODEL=Qwen/Qwen2-7B-Instruct        # LLM 模型名称
EMBED_MODEL=BAAI/bge-small-en-v1.5       # Embedding 模型

# 服务端口
QDRANT_PORT=18033                        # Qdrant 端口
VLLM_PORT=18000                          # vLLM 端口  
RAG_PORT=18001                           # API 服务端口

# 性能调优
VLLM_MAX_TOKENS=512                      # 最大生成 token 数
TOP_K=3                                  # 检索 top-k
CHUNK_SIZE=1024                          # 文档分块大小
```

#### 准备知识库文档

```bash
# 将企业文档放入 data 目录
mkdir -p data
# 复制您的 PDF/MD/TXT 文档到 data/ 目录
cp /path/to/your/documents/* data/

# 支持的文档格式：.pdf, .md, .txt, .docx
```

### 3. 启动服务

#### 标准启动

```bash
# 启动所有服务
docker-compose up -d

# 查看服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f vllm
```

#### 分阶段启动（推荐用于调试）

```bash
# 1. 启动向量数据库
docker-compose up -d qdrant

# 等待 Qdrant 启动完成
sleep 30

# 2. 启动 LLM 推理服务
docker-compose up -d vllm

# 等待模型加载完成（约 2-5 分钟）
sleep 120

# 3. 启动 API 服务
docker-compose up -d rag-api

# 4. 验证所有服务健康状态
docker-compose ps
```

### 4. 构建向量索引

#### 自动构建索引

```bash
# 在容器内执行索引构建
docker-compose exec rag-api python ingest.py
```

#### 手动构建索引（调试用）

```bash
# 进入 API 容器
docker-compose exec rag-api bash

# 执行索引构建脚本
python ingest.py

# 检查索引状态
python -c "
from query_service import rag_service
rag_service.initialize()
print('索引构建完成')
"
```

### 5. 验证部署

#### 健康检查

```bash
# 检查所有服务状态
curl -s http://localhost:18001/health | jq

# 检查 Qdrant 状态
curl -s http://localhost:18033/health

# 检查 vLLM 状态
curl -s http://localhost:18000/v1/models | jq
```

#### 功能测试

```bash
# 基础问答测试
curl -X POST "http://localhost:18001/query" \
     -H "Content-Type: application/json" \
     -d '{
       "query": "公司的请假流程是什么？",
       "top_k": 3,
       "include_sources": true
     }' | jq

# 获取服务统计信息
curl -s http://localhost:18001/stats | jq
```

## 📚 API 文档

### 基础接口

#### 健康检查
```http
GET /health
```

响应示例：
```json
{
  "status": "healthy",
  "service": "RAG Enterprise API",
  "version": "1.0.0"
}
```

#### 问答查询
```http
POST /query
Content-Type: application/json

{
  "query": "请假流程是什么？",
  "top_k": 3,
  "include_sources": true,
  "temperature": 0.7,
  "max_tokens": 512
}
```

响应示例：
```json
{
  "answer": "根据公司制度，请假流程包括：1. 员工在系统中填写请假申请 2. 直属领导审核申请 3. HR 部门备案 4. 系统自动更新假期余额。",
  "sources": [
    {
      "text": "## 请假流程\n1. 员工需要在系统中填写请假申请\n2. 直属领导审核申请\n3. HR 部门备案\n4. 系统自动更新假期余额",
      "score": 0.95,
      "metadata": {
        "file_path": "sample_policy.md",
        "chunk_id": 0
      }
    }
  ],
  "confidence": 0.92,
  "query_time": 0.85
}
```

#### 服务统计
```http
GET /stats
```

响应示例：
```json
{
  "collection_name": "rag_enterprise",
  "vectors_count": 156,
  "indexed_vectors_count": 156,
  "status": "green",
  "config": {
    "embed_model": "BAAI/bge-small-en-v1.5",
    "llm_model": "Qwen/Qwen2-7B-Instruct",
    "reranker_model": "BAAI/bge-reranker-v2-m3"
  }
}
```

### 高级功能

#### 重建索引
```http
POST /rebuild_index
```

异步重建向量索引，适用于文档更新后重新索引。

#### GET 方式查询（简单测试）
```http
GET /query?q=请假流程是什么？&top_k=3&include_sources=true
```
```
## 🔍 系统评估

### 运行 RAGAS 评估

```bash
# 运行完整评估
docker-compose exec rag-api python eval/evaluate_rag.py

# 使用自定义测试数据集
docker-compose exec rag-api python eval/evaluate_rag.py --dataset eval/test_dataset.json
```

### 评估指标说明

| 指标 | 范围 | 含义 | 目标值 |
|------|------|------|--------|
| **faithfulness** | 0-1 | 答案忠实度 | >0.8 |
| **answer_relevancy** | 0-1 | 答案相关性 | >0.8 |
| **context_recall** | 0-1 | 上下文召回率 | >0.7 |
| **context_precision** | 0-1 | 上下文精确度 | >0.8 |
| **answer_similarity** | 0-1 | 答案相似度 | >0.7 |

### 查看评估结果

```bash
# 查看 JSON 格式结果
cat eval/evaluation_results.json | jq

# 查看详细报告
cat eval/evaluation_results_report.txt
```

## 🛠️ 运维指南

### 日志管理

```bash
# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f rag-api
docker-compose logs -f vllm
docker-compose logs -f qdrant

# 保存日志到文件
docker-compose logs rag-api > logs/api.log
```

### 性能监控

#### 系统资源监控
```bash
# 查看容器资源使用情况
docker stats

# 查看 GPU 使用情况
nvidia-smi
```

#### 服务性能监控
```bash
# 查看 API 服务性能指标
curl -s http://localhost:18001/stats | jq

# 查看 Qdrant 集合状态
curl -s http://localhost:18033/collections | jq

# 测试服务响应时间
time curl -s http://localhost:18001/health
```

### 备份和恢复

#### 向量数据库备份
```bash
# 创建 Qdrant 数据备份
docker-compose exec qdrant qdrantctl backup create --collection rag_enterprise --backup-path /qdrant/backup

# 恢复数据
docker-compose exec qdrant qdrantctl backup restore --backup-path /qdrant/backup/rag_enterprise
```

#### 文档数据备份
```bash
# 备份原始文档
tar -czf backup/documents_$(date +%Y%m%d).tar.gz data/

# 备份配置文件
cp .env backup/env_$(date +%Y%m%d).backup
```

### 常见问题解决

#### 服务启动失败

**问题**: vLLM 服务启动失败
```bash
# 检查 GPU 是否可用
nvidia-smi

# 检查模型是否下载成功
docker-compose logs vllm | grep "Model loaded"

# 手动下载模型
docker-compose exec vllm python -c "from transformers import AutoModelForCausalLM; AutoModelForCausalLM.from_pretrained('Qwen/Qwen2-7B-Instruct')"
```

**问题**: Qdrant 连接失败
```bash
# 检查 Qdrant 端口
netstat -tulpn | grep 18033

# 重启 Qdrant 服务
docker-compose restart qdrant

# 检查数据目录权限
ls -la qdrant_data/
```

#### 检索质量不佳

**问题**: 检索结果不相关
```bash
# 1. 重新构建索引，增加分块重叠
# 编辑 ingest.py 中的 CHUNK_OVERLAP 参数
sed -i 's/CHUNK_OVERLAP=200/CHUNK_OVERLAP=400/' ingest.py

# 2. 调整 Top-K 参数
# 在查询时增加 top_k 值
curl -X POST "http://localhost:18001/query" -d '{"query": "xxx", "top_k": 5}'

# 3. 检查文档质量
ls -la data/
```

#### 响应速度慢

**问题**: API 响应时间过长
```bash
# 1. 检查 GPU 利用率
nvidia-smi

# 2. 调整 vLLM 参数
# 减小 max_tokens
# 增加 max_num_seqs

# 3. 使用 Redis 缓存（可选）
# 配置 Redis 服务并启用缓存
```

### 升级和扩展

#### 模型升级
```bash
# 1. 更新 .env 文件中的模型配置
VLLM_MODEL=Qwen/Qwen2-14B-Instruct

# 2. 重启 vLLM 服务
docker-compose restart vllm

# 3. 重新构建索引（如果模型变化）
docker-compose exec rag-api python ingest.py
```

#### 水平扩展
```bash
# 增加 API 服务实例
docker-compose up -d --scale rag-api=3

# 配置负载均衡
# 编辑 nginx/nginx.conf 添加 upstream 配置
```

## 📊 最佳实践

### 1. 文档准备

- **格式标准化**: 统一使用 Markdown 格式，便于分块和检索
- **内容结构化**: 使用标题层级，便于理解文档结构
- **质量控制**: 确保文档内容准确、完整、最新

### 2. 参数调优

#### 分块策略
```python
# 平衡上下文完整性和检索精度
CHUNK_SIZE = 1024      # 适中分块大小
CHUNK_OVERLAP = 200    # 25% 重叠，保证上下文连续
```

#### 检索参数
```python
# 根据文档复杂度调整
TOP_K = 3              # 简单问题用 3-5
TOP_K = 5              # 复杂问题用 5-8
```

#### 生成参数
```python
# 控制答案质量
TEMPERATURE = 0.7      # 创造性回答
TEMPERATURE = 0.1      # 准确性回答
MAX_TOKENS = 512       # 控制答案长度
```

### 3. 安全考虑

- **API 访问控制**: 配置身份认证和访问频率限制
- **数据安全**: 对敏感文档进行加密存储
- **网络安全**: 使用 HTTPS 和防火墙保护服务

### 4. 监控告警

- **服务健康**: 定期检查所有服务的健康状态
- **性能指标**: 监控响应时间、吞吐量、错误率
- **资源使用**: 监控 CPU、内存、GPU 使用率

## 📞 技术支持

### 获取帮助

- **文档**: 查看本 README 和代码注释
- **日志**: 检查容器日志定位问题
- **社区**: 访问相关技术社区寻求帮助

### 报告问题

提交 Issue 时请包含：
1. 系统环境信息
2. 错误日志和复现步骤
3. 期望的行为描述

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---

**构建企业级 RAG 系统，从这里开始！** 🚀