# RAG A Platform

**Repository Path**: to-doing/rag-a-platform

## Basic Information

- **Project Name**: RAG A Platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG Platform

企业级 RAG 知识库平台 - 前后端交互 + K8s 分布式部署

## 项目简介

这是一个完整的企业级 RAG（Retrieval-Augmented Generation）知识库平台，支持：

- 📚 **多格式文档处理**: PDF、Markdown、Word、Excel、CSV 等格式
- 🔍 **混合检索**: 向量检索 + 关键词检索 + RRF 融合排序
- 🤖 **智能问答**: 基于 RAG 的对话系统，支持流式输出
- 🏢 **多租户隔离**: 完整的租户数据隔离
- 🔐 **权限控制**: RBAC 权限模型
- ☸️ **K8s 部署**: 完整的 Helm Chart 和自动化部署

## 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                        用户层                                │
│          Web 前端 / 管理后台 / API SDK                        │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                     API Gateway                              │
│              (认证 / 限流 / 路由分发)                         │
└─────────────────────────────┬───────────────────────────────┘
                              │
         ┌────────────────────┴────────────────────┐
         ▼                    ▼                    ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ Document    │      │ Retrieval   │      │   Chat      │
│  Service    │      │  Service    │      │  Service    │
│ (文档管理)  │      │ (混合检索)  │      │ (RAG问答)   │
└──────┬──────┘      └──────┬──────┘      └──────┬──────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
         ┌──────────────────┴──────────────────┐
         ▼                  ▼                  ▼
   ┌───────────┐     ┌───────────┐     ┌───────────┐
   │ Embedding │     │  Rerank   │     │  Ingest   │
   │  Service  │     │  Service  │     │  Worker   │
   └───────────┘     └───────────┘     └───────────┘
                            │
         ┌──────────────────┴──────────────────┐
         ▼                  ▼                  ▼
   ┌───────────┐     ┌───────────┐     ┌───────────┐
   │  Milvus   │     │ PostgreSQL│     │    ES     │
   │ (向量库)  │     │ (关系库)  │     │ (全文)    │
   └───────────┘     └───────────┘     └───────────┘
```

## 快速开始

### 本地开发（无需 Docker）

```bash
# 1. 安装依赖
pip install -r backend/requirements.txt

# 2. 启动基础设施（PostgreSQL、Redis、Milvus、ES）
# 需要自行安装或使用云服务

# 3. 初始化数据库
python backend/scripts/init_db.py --create-tables

# 4. 启动服务
python backend/scripts/run_all_services.py
```

### Docker Compose

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

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### Kubernetes 部署

```bash
# Helm 安装
helm install rag-platform ./infrastructure/helm/rag-platform \
  -n rag-platform \
  --create-namespace

# 或使用 Makefile
make helm-install
```

## 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| document-service | 8001 | 知识库/文档管理 |
| retrieval-service | 8002 | 混合检索 |
| chat-service | 8003 | RAG 对话 |
| embedding-service | 8004 | 文本向量化 |
| rerank-service | 8005 | 重排序 |

## API 使用示例

### Python SDK

```python
from rag_sdk import RAGClient

# 初始化客户端
client = RAGClient(base_url="http://localhost:8001", api_key="your-key")

# 创建知识库
kb = client.create_knowledge_base(name="产品文档库")

# 上传文档
doc = client.upload_document(kb_id=kb.id, file_path="./manual.pdf")

# 检索
results = client.retrieve(query="如何使用？", kb_ids=[kb.id])

# 对话
response = client.chat(
    messages=[{"role": "user", "content": "产品功能有哪些？"}],
    kb_ids=[kb.id]
)
print(response.content)
```

### REST API

```bash
# 创建知识库
curl -X POST http://localhost:8001/v1/knowledge-bases \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "我的知识库"}'

# 上传文档
curl -X POST http://localhost:8001/v1/knowledge-bases/{kb_id}/documents \
  -H "Authorization: Bearer <token>" \
  -F "file=@document.pdf"

# 检索
curl -X POST http://localhost:8002/v1/retrieve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "搜索内容", "kb_ids": ["kb_id"]}'

# 对话
curl -X POST http://localhost:8003/v1/chat/completions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "问题"}],
    "kb_ids": ["kb_id"],
    "stream": true
  }'
```

## 目录结构

```
rag-x/
├── backend/                    # 后端代码
│   ├── shared/                 # 共享库
│   │   ├── auth/               # 认证模块
│   │   ├── config/             # 配置管理
│   │   ├── database/           # 数据库
│   │   ├── middleware/         # 中间件
│   │   ├── models/             # 数据模型
│   │   └── utils/              # 工具类
│   ├── services/               # 微服务
│   │   ├── document-service/   # 文档服务
│   │   ├── retrieval-service/  # 检索服务
│   │   ├── chat-service/       # 问答服务
│   │   ├── embedding-service/  # 向量化服务
│   │   ├── rerank-service/     # 重排序服务
│   │   └── ingest-worker/      # 摄入 Worker
│   ├── alembic/                # 数据库迁移
│   ├── tests/                  # 测试代码
│   └── scripts/                # 工具脚本
│
├── sdk/                        # SDK
│   └── python/                 # Python SDK
│
├── infrastructure/             # 基础设施
│   ├── k8s/                    # K8s 部署文件
│   └── helm/                   # Helm Chart
│
├── docs/                       # 文档
│   └── api-spec.yaml           # API 规范
│
├── docker-compose.yml          # Docker Compose
├── Makefile                    # 常用命令
└── README.md                   # 项目文档
```

## 核心功能

### 1. 混合检索 (Hybrid Retrieval)

- **向量检索**: 基于语义相似度
- **关键词检索**: 基于 BM25 全文检索
- **RRF 融合**: Reciprocal Rank Fusion 排序
- **重排序**: Cross-Encoder 精细排序

### 2. 多格式文档处理

| 格式 | 处理策略 |
|------|----------|
| PDF | PyPDF 按页解析 + 段落切分 |
| Markdown | 按标题层级切分 |
| Word | 段落解析 |
| Excel/CSV | 按行切分为自然语言 |

### 3. 企业级特性

- **多租户隔离**: Tenant ID 自动注入
- **RBAC 权限**: Admin/Editor/Viewer 角色
- **审计日志**: 操作记录追踪
- **限流**: 滑动窗口算法

## 配置说明

环境变量配置见 `backend/.env.example`:

```bash
# 数据库
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Milvus
MILVUS_HOST=localhost
MILVUS_PORT=19530

# 模型
EMBEDDING_MODEL=BAAI/bge-m3
LLM_MODEL=gpt-4-turbo
```

## 开发指南

### 运行测试

```bash
cd backend
pytest tests/ -v --cov=.
```

### 数据库迁移

```bash
# 创建迁移
alembic revision --autogenerate -m "description"

# 执行迁移
alembic upgrade head
```

### 代码风格

```bash
# 格式化
black .
isort .

# 检查
flake8 .
mypy .
```

## 技术栈

| 类别 | 技术 |
|------|------|
| 后端框架 | FastAPI |
| 数据库 | PostgreSQL |
| 缓存/队列 | Redis |
| 向量数据库 | Milvus |
| 全文检索 | Elasticsearch |
| 对象存储 | MinIO |
| Embedding | BGE-M3 |
| LLM | OpenAI/Azure |
| 容器化 | Docker |
| 编排 | Kubernetes |

## License

MIT