# YG-Dataset 架构设计文档

## 一、项目概述

YG-Dataset 是一个**数据生成平台**，用于将各类文档（PDF、DOCX、Excel、CSV等）转换为可用于训练大语言模型的高质量数据集。

### 1.1 核心能力
- 多格式文档解析与处理
- 智能文本分割（多种算法）
- 基于 LLM 的问题自动生成
- 数据集管理与多格式导出
- 模型评估与盲测系统

### 1.2 技术架构
```
┌─────────────────────────────────────────────────────────────┐
│                        Vue 3 Frontend                       │
│  (Element Plus + Pinia + Vue Router)                        │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP/WebSocket
┌─────────────────────────▼───────────────────────────────────┐
│                     FastAPI Backend                          │
│  (REST API + WebSocket)                                     │
├─────────────────────────────────────────────────────────────┤
│  Services Layer                                             │
│  ├── FileProcessor (PDF/DOCX/Excel/CSV解析)                │
│  ├── TextSplitter (6种分割算法)                             │
│  ├── LLMService (问题生成/评估)                             │
│  └── ExportService (多格式导出)                             │
├─────────────────────────────────────────────────────────────┤
│  Data Access Layer (SQLAlchemy 2.0)                         │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                   PostgreSQL + Redis                         │
│  (主数据库 + 缓存/任务队列)                                 │
└─────────────────────────────────────────────────────────────┘
```

---

## 二、系统架构

### 2.1 分层架构

```
┌────────────────────────────────────────────────────────┐
│                    Presentation Layer                   │
│  Vue 3 + Element Plus + Pinia + Vue Router             │
├────────────────────────────────────────────────────────┤
│                     API Layer                            │
│  FastAPI + Pydantic + CORS Middleware                  │
├────────────────────────────────────────────────────────┤
│                   Service Layer                          │
│  FileProcessor / TextSplitter / LLM / Export           │
├────────────────────────────────────────────────────────┤
│                  Repository Layer                        │
│  SQLAlchemy Models + Async Session                      │
├────────────────────────────────────────────────────────┤
│                   Infrastructure                         │
│  PostgreSQL / Redis / File System                      │
└────────────────────────────────────────────────────────┘
```

### 2.2 数据流架构

```
文件上传 → 文档解析 → 文本提取 → 分割处理 → 问题生成 → 数据集构建 → 导出
                                              ↓
                                        评估/盲测
```

---

## 三、模块设计

### 3.1 后端模块

| 模块 | 职责 | 关键类/函数 |
|------|------|-------------|
| `app/api/v1/` | REST API 路由 | Router 配置 |
| `app/models/` | SQLAlchemy ORM 模型 | Project, File, Chunk, Question 等 |
| `app/schemas/` | Pydantic 数据验证 | Request/Response 模型 |
| `app/services/` | 业务逻辑 | FileProcessor, TextSplitter, LLMWrapper |
| `app/core/` | 核心配置 | Config, Database, Security |

### 3.2 前端模块

| 目录 | 职责 |
|------|------|
| `views/` | 页面组件 (Home, Project, Playground, DataSquare) |
| `components/` | 可复用组件 |
| `stores/` | Pinia 状态管理 |
| `api/` | API 封装 |
| `router/` | 路由配置 |

---

## 四、API 设计

### 4.1 API 路由结构

```
/api/v1/
├── /projects/          # 项目管理
│   ├── GET /          # 列表
│   ├── POST /         # 创建
│   ├── GET /{id}      # 详情
│   └── DELETE /{id}   # 删除
├── /files/            # 文件处理
│   ├── POST /upload   # 上传
│   ├── POST /process  # 处理
│   └── GET /{id}      # 状态
├── /chunks/           # 文本分割
│   ├── POST /split    # 执行分割
│   └── GET /          # 列表
├── /questions/        # 问题管理
│   ├── POST /generate # 生成
│   └── GET /          # 列表
├── /datasets/         # 数据集
│   ├── GET /          # 列表
│   ├── POST /         # 创建
│   └── POST /export   # 导出
└── /eval/             # 评估系统
    ├── POST /generate # 生成评估题
    └── POST /run      # 运行评估
```

---

## 五、数据库设计

### 5.1 核心表

| 表名 | 说明 |
|------|------|
| `projects` | 项目表 |
| `files` | 文件表（上传的文件） |
| `chunks` | 文本块表（分割后的片段） |
| `tags` | 标签/领域树 |
| `questions` | 问题表 |
| `datasets` | 数据集表 |
| `eval_datasets` | 评估数据集表 |
| `model_configs` | 模型配置表 |
| `tasks` | 任务表 |

### 5.2 ER 关系

```
Project 1──∞ File
Project 1──∞ Chunk
Project 1──∞ Question
Project 1──∞ Dataset
File 1──∞ Chunk
Chunk 1──∞ Question
Chunk *──* Tag
Dataset *──* Question
```

---

## 六、部署架构

### 6.1 Docker Compose

```yaml
services:
  postgres:   # 主数据库
  redis:      # 缓存/队列
  backend:    # FastAPI 服务
  frontend:   # Vue 3 服务
```

### 6.2 目录结构

```
YG-Datasets/
├── backend/           # FastAPI 后端
│   ├── app/
│   │   ├── api/      # API 路由
│   │   ├── models/   # ORM 模型
│   │   ├── schemas/  # Pydantic 模型
│   │   ├── services/ # 业务逻辑
│   │   └── core/     # 核心配置
│   ├── alembic/      # 数据库迁移
│   └── requirements.txt
├── frontend/          # Vue 3 前端
│   ├── src/
│   │   ├── views/    # 页面
│   │   ├── components/
│   │   ├── stores/   # Pinia
│   │   └── api/
│   └── package.json
├── docker-compose.yml
└── README.md
```

---

## 七、技术选型理由

| 技术 | 选型理由 |
|------|----------|
| FastAPI | 高性能、异步支持、自动 API 文档 |
| SQLAlchemy 2.0 | 异步 ORM、类型安全 |
| PostgreSQL | 可靠的关系型数据库 |
| Redis | 缓存、任务队列 |
| Vue 3 | Composition API、更好的 TypeScript 支持 |
| Element Plus | 成熟的 Vue 3 UI 组件库 |
| Pinia | 轻量级、TypeScript 友好 |
| Docker Compose | 简化开发/部署 |

---

## 八、安全考虑

- CORS 配置（生产环境需限制域名）
- 文件上传大小限制
- API 请求验证
- 数据库连接池管理

---

*文档版本: v1.0*
*更新日期: 2026-03-17*