# rag

**Repository Path**: quancundiyi/rag

## Basic Information

- **Project Name**: rag
- **Description**: 完全使用openclaw创建一个rag系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 村度 RAG · 企业级知识库系统

> 检索增强生成（RAG）系统，支持文档上传、智能分块、向量检索、AI 问答。

## 架构

```
┌─────────────────────────────────────────────────────┐
│                  数据接入层                          │
│  PDF / Word / PPT / Excel / Markdown / 文本 → Parser │
│                    ↓                                 │
│              Docling + LibreOffice                   │
│                    ↓                                 │
│              智能分块 (Chunker)                      │
│      语义分割 / 固定窗口 / 层级分块                  │
│                    ↓                                 │
│            Embedding (bge-large-zh-v1.5)             │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│                 检索生成层                           │
│                                                    │
│   ┌──────────┐   ┌──────────┐   ┌──────────────┐  │
│   │ Qdrant   │   │ Redis    │   │  Reranker    │  │
│   │ 向量库   │◄──┤ 语义缓存 │◄──┤ 重排序       │  │
│   └──────────┘   └──────────┘   └──────────────┘  │
│        ↓              ↓               ↓            │
│   ┌──────────────────────────────────────────┐     │
│   │          RAG Context Builder             │     │
│   │   Prompt 组装 + 引用溯源 + 上下文压缩    │     │
│   └──────────────────────────────────────────┘     │
│        ↓                                            │
│   ┌──────────────────────────────────────────┐     │
│   │     LLM (DeepSeek V4 Flash)             │     │
│   │     最终生成 + 流式输出                  │     │
│   └──────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│              服务与基础设施层                        │
│  FastAPI ←→ PostgreSQL ←→ MinIO ←→ RabbitMQ        │
│  (Web)         (元数据)    (文件存储)  (消息队列)    │
└─────────────────────────────────────────────────────┘
```

## 中间件

| 组件 | 用途 | 端口 | 说明 |
|------|------|------|------|
| **PostgreSQL + pgvector** | 关系数据 + 向量辅助检索 | `28003` | 存储文档元数据、用户、租户信息 |
| **Qdrant** | 主向量检索库 | `6333` / `6334` | 向量存储与 ANN 搜索 |
| **Redis** | 语义缓存 + 会话状态 | `6379` | 缓存相似查询结果，减少 LLM 调用 |
| **MinIO** | 文件存储 | `9000` (API) / `9001` (控制台) | 原始文档与备份，兼容 S3 协议 |
| **RabbitMQ** | 增量同步消息队列 | `5672` / `15672` | 异步文档索引任务调度 |

## 项目结构

```
rag/
├── app/
│   ├── main.py                 # FastAPI 入口，生命周期管理
│   ├── config.py               # 全局配置（从 .env 读取）
│   ├── api/
│   │   └── routes.py           # REST API 路由
│   ├── core/
│   │   ├── database.py         # PostgreSQL 连接与初始化
│   │   ├── redis_client.py     # Redis 缓存客户端
│   │   ├── storage.py          # MinIO 文件存储封装
│   │   └── vector_store.py     # Qdrant 向量库封装
│   ├── ingestion/
│   │   ├── parser.py           # 文档解析（Docling + LibreOffice）
│   │   ├── chunker.py          # 智能分块策略
│   │   ├── embedder.py         # Embedding 生成
│   │   └── indexer.py          # 索引编排（解析→分块→嵌入→写入）
│   ├── retrieval/
│   │   ├── search.py           # 向量检索（多路召回）
│   │   ├── reranker.py         # 重排序（Cross-Encoder）
│   │   └── context.py          # 上下文构建（Prompt 组装 + 引用）
│   ├── generation/
│   │   └── llm.py              # LLM 调用封装（DeepSeek API）
│   └── models/
│       └── schemas.py          # Pydantic 数据模型
├── frontend/
│   └── index.html              # 单页前端（对话 + 知识库 + 设置）
├── sql/
│   └── init.sql                # 数据库初始化脚本
├── docker-compose.yml          # 中间件容器编排
├── requirements.txt            # Python 依赖
├── start.sh                    # 快速启动脚本
├── .env.example                # 环境变量模板
└── README.md
```

## 快速启动

### 前置条件

- Docker & Docker Compose
- Python 3.11+
- DeepSeek API Key（或其他兼容 OpenAI 的 LLM）

### 启动步骤

```bash
# 1. 启动中间件（PostgreSQL、Qdrant、Redis、MinIO、RabbitMQ）
docker compose up -d

# 2. 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate

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

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 LLM API Key

# 5. 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 28005
```

访问 `http://localhost:28005/` 进入前端。

### 生产部署

```bash
# 使用 nohup 后台运行
nohup uvicorn app.main:app --host 0.0.0.0 --port 28005 > rag.log 2>&1 &

# 或使用 systemd 管理服务（推荐）
```

## API 参考

### 健康检查

```
GET /api/v1/health
```

响应：
```json
{ "status": "ok", "service": "rag" }
```

### 文档管理

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/documents` | GET | 文档列表（支持 `tenant_id` 参数） |
| `/api/v1/documents/upload` | POST | 上传文档（multipart/form-data） |
| `/api/v1/documents/{id}` | DELETE | 删除文档 |
| `/api/v1/documents/{id}/detail` | GET | 文档详情（含分块列表） |

上传参数：

| 字段 | 类型 | 说明 |
|------|------|------|
| `file` | File | 文档文件 |
| `title` | str | 文档标题 |
| `tenant_id` | str | 租户 ID（默认 `default`） |

支持格式：PDF、Word (.docx)、PPT (.pptx)、Excel (.xlsx)、Markdown、纯文本

### RAG 问答

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/query` | POST | 标准问答（非流式） |
| `/api/v1/query/stream` | POST | 流式问答（SSE） |
| `/api/v1/query/trace` | POST | 带检索溯源链的问答 |

请求体：

```json
{
  "query": "你的问题",
  "top_k": 5,
  "tenant_id": "default"
}
```

/trace 响应包含 `sources` 字段，提供引用来源（文档名、页码、匹配度）。

### 其他

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/query/cached` | POST | 带缓存命中的问答（减少重复 LLM 调用） |

## 技术特点

- **文档解析**：基于 Docling + LibreOffice，支持多格式文档高保真转换
- **智能分块**：支持固定窗口分块、语义分割、层级分块多种策略
- **Embedding**：默认使用 `BAAI/bge-large-zh-v1.5`（1024 维），可选远程 API
- **多路召回**：向量检索 + 关键词检索组合，提高召回率
- **重排序**：Cross-Encoder 重排序，精排 Top-K 结果
- **语义缓存**：Redis 缓存相似查询，降低延迟和 LLM 成本
- **流式输出**：SSE 实时返回，前端逐字展示
- **引用溯源**：回答附带来源文档名、页码、匹配度分数
- **多租户**：通过 `tenant_id` 隔离不同用户的数据

## 配置项

所有配置通过 `.env` 文件管理：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PG_DSN` | `postgresql+asyncpg://rag:rag_secret_2026@localhost:28003/rag` | PostgreSQL 连接串 |
| `QDRANT_HOST` | `localhost` | Qdrant 地址 |
| `QDRANT_PORT` | `6333` | Qdrant REST 端口 |
| `REDIS_URL` | `redis://localhost:6379/0` | Redis 地址 |
| `MINIO_ENDPOINT` | `localhost:9000` | MinIO 端点 |
| `LLM_API_KEY` | - | LLM API 密钥 |
| `LLM_API_URL` | `https://api.deepseek.com/v1` | LLM API 地址 |
| `LLM_MODEL` | `deepseek-v4-flash` | 模型名称 |
| `EMBEDDING_MODEL` | `BAAI/bge-large-zh-v1.5` | Embedding 模型 |
| `CHUNK_SIZE` | `512` | 分块大小（token） |
| `CHUNK_OVERLAP` | `76` | 分块重叠 |
| `TOP_K_RETRIEVE` | `20` | 召回数量 |
| `TOP_K_RERANK` | `5` | 重排序后保留数量 |
| `HOST` | `0.0.0.0` | 服务监听地址 |
| `PORT` | `28005` | 服务端口 |

## 依赖

- Python 3.11+
- FastAPI + Uvicorn
- SQLAlchemy (async) + asyncpg
- Qdrant Client
- Redis (redis-py)
- MinIO (S3 SDK)
- aio-pika (RabbitMQ)
- Docling + python-pptx + python-docx + openpyxl
- Transformers (BGE Embedding)
- DeepSeek API / OpenAI 兼容 API