255 lines
5.3 KiB
Markdown
255 lines
5.3 KiB
Markdown
# Easy Dataset Agent 指南
|
||
|
||
## 项目概述
|
||
|
||
Easy Dataset 是一个专为大型语言模型（LLM）微调数据集创建而设计的应用程序。它提供完整的workflow，从文档处理到数据集导出，支持多种文件格式和AI模型。
|
||
|
||
## 技术栈
|
||
|
||
- **前端**: Next.js 14 (App Router), React 18, Material-UI v5
|
||
- **后端**: Node.js, Prisma ORM, SQLite
|
||
- **AI集成**: OpenAI API, Ollama, 智谱AI, OpenRouter
|
||
- **桌面应用**: Electron
|
||
- **国际化**: i18next
|
||
- **构建工具**: npm/pnpm, Electron Builder
|
||
|
||
## 核心架构
|
||
|
||
### 1. 数据流架构
|
||
|
||
```
|
||
文档上传 → 文本分割 → 问题生成 → 答案生成 → 数据集导出
|
||
↓ ↓ ↓ ↓ ↓
|
||
文件处理 智能分块 LLM生成 LLM生成 格式转换
|
||
```
|
||
|
||
### 2. 模块结构
|
||
|
||
```
|
||
lib/
|
||
├── api/ # API接口层
|
||
├── db/ # 数据访问层
|
||
├── file/ # 文件处理模块
|
||
├── llm/ # AI模型集成
|
||
├── services/ # 业务逻辑层
|
||
└── util/ # 工具函数
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 环境设置
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 数据库初始化
|
||
npm run db:push
|
||
|
||
# 开发模式
|
||
npm run dev
|
||
|
||
# 构建
|
||
npm run build
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
- 使用ES6+语法
|
||
- 模块化开发
|
||
- 异步操作使用async/await
|
||
- 错误处理使用try/catch
|
||
- 注释使用JSDoc格式
|
||
|
||
### 重要文件路径
|
||
|
||
- **主入口**: `app/page.js`
|
||
- **项目路由**: `app/projects/[projectId]/`
|
||
- **API路由**: `app/api/`
|
||
- **LLM核心**: `lib/llm/core/index.js`
|
||
- **任务处理**: `lib/services/tasks/`
|
||
|
||
## 功能模块详解
|
||
|
||
### 1. 文档处理模块 (`lib/file/`)
|
||
|
||
- **支持的格式**: PDF, Markdown, DOCX, EPUB, TXT
|
||
- **核心功能**:
|
||
- 智能文本分割
|
||
- 目录结构提取
|
||
- 自定义分隔符分块
|
||
- 多语言支持
|
||
|
||
### 2. AI模型集成 (`lib/llm/`)
|
||
|
||
- **支持的提供商**:
|
||
- OpenAI (GPT系列)
|
||
- Ollama (本地模型)
|
||
- 智谱AI (GLM系列)
|
||
- OpenRouter (多模型聚合)
|
||
- **功能特性**:
|
||
- 统一API接口
|
||
- 流式输出支持
|
||
- 多语言提示词
|
||
- 错误重试机制
|
||
|
||
### 3. 任务系统 (`lib/services/tasks/`)
|
||
|
||
- **任务类型**:
|
||
- 文件处理任务
|
||
- 问题生成任务
|
||
- 答案生成任务
|
||
- 数据清洗任务
|
||
- **状态管理**: 待处理、处理中、完成、失败
|
||
|
||
### 4. 数据管理 (`lib/db/`)
|
||
|
||
- **数据模型**:
|
||
- Project (项目)
|
||
- Text/Chunk (文本块)
|
||
- Question (问题)
|
||
- Dataset (数据集)
|
||
- Tag (标签)
|
||
|
||
## 常用开发任务
|
||
|
||
### 添加新的AI模型提供商
|
||
|
||
1. 在 `lib/llm/core/providers/` 创建新的provider文件
|
||
2. 实现基础接口 (generate, streamGenerate)
|
||
3. 在 `lib/llm/core/index.js` 中注册provider
|
||
4. 更新配置文件和UI界面
|
||
|
||
### 添加新的文件格式支持
|
||
|
||
1. 在 `lib/file/file-process/` 创建格式处理器
|
||
2. 实现内容提取和文本转换逻辑
|
||
3. 更新文件类型检测和验证
|
||
4. 添加相应的UI组件
|
||
|
||
### 自定义提示词模板
|
||
|
||
1. 在 `lib/llm/prompts/` 创建新的提示词文件
|
||
2. 使用i18n支持多语言
|
||
3. 在设置界面添加配置选项
|
||
4. 测试不同模型的效果
|
||
|
||
### 添加新的导出格式
|
||
|
||
1. 在 `components/export/` 创建新的导出组件
|
||
2. 实现数据格式转换逻辑
|
||
3. 更新导出对话框界面
|
||
4. 添加格式验证和错误处理
|
||
|
||
## 调试技巧
|
||
|
||
### 1. 数据库调试
|
||
|
||
```bash
|
||
# 打开Prisma Studio
|
||
npm run db:studio
|
||
|
||
# 查看数据库文件
|
||
sqlite3 prisma/db.sqlite
|
||
```
|
||
|
||
### 2. LLM API调试
|
||
|
||
```javascript
|
||
// 在lib/llm/core/index.js中添加日志
|
||
console.log('LLM Request:', { provider, model, prompt });
|
||
console.log('LLM Response:', response);
|
||
```
|
||
|
||
### 3. 文件处理调试
|
||
|
||
```javascript
|
||
// 在lib/file/中添加调试信息
|
||
console.log('File processing:', fileName, fileType);
|
||
console.log('Text chunks:', chunks.length, chunks[0]);
|
||
```
|
||
|
||
## 性能优化建议
|
||
|
||
### 1. 文件处理优化
|
||
|
||
- 大文件分片处理
|
||
- 异步并发处理
|
||
- 内存使用监控
|
||
- 进度条显示
|
||
|
||
### 2. LLM调用优化
|
||
|
||
- 请求缓存机制
|
||
- 批量处理请求
|
||
- 重试策略优化
|
||
- 并发数控制
|
||
|
||
### 3. 前端性能优化
|
||
|
||
- 组件懒加载
|
||
- 虚拟滚动列表
|
||
- 图片懒加载
|
||
- 代码分割
|
||
|
||
## 常见问题解决
|
||
|
||
### 1. 数据库相关问题
|
||
|
||
- **问题**: 数据库连接失败
|
||
- **解决**: 检查prisma配置，确保数据库文件存在
|
||
|
||
### 2. LLM API相关问题
|
||
|
||
- **问题**: API调用超时
|
||
- **解决**: 调整超时时间，检查网络连接，增加重试机制
|
||
|
||
### 3. 文件处理问题
|
||
|
||
- **问题**: 大文件处理内存溢出
|
||
- **解决**: 使用流式处理，分块读取，增加内存限制
|
||
|
||
### 4. Electron打包问题
|
||
|
||
- **问题**: 打包后应用无法启动
|
||
- **解决**: 检查依赖项配置，确保native模块正确打包
|
||
|
||
## 部署指南
|
||
|
||
### Docker部署
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t easy-dataset .
|
||
|
||
# 运行容器
|
||
docker run -d -p 1717:1717 -v ./local-db:/app/local-db easy-dataset
|
||
```
|
||
|
||
### 桌面应用构建
|
||
|
||
```bash
|
||
# 构建各平台安装包
|
||
npm run electron-build-mac # macOS
|
||
npm run electron-build-win # Windows
|
||
npm run electron-build-linux # Linux
|
||
```
|
||
|
||
## 贡献指南
|
||
|
||
### 提交规范
|
||
|
||
- 使用conventional commits格式
|
||
- 提交前运行lint检查
|
||
- 更新相关文档
|
||
- 添加测试用例
|
||
|
||
### 分支策略
|
||
|
||
- `main`: 主分支，稳定版本
|
||
- `dev`: 开发分支，集成新功能
|
||
- `feature/*`: 功能分支
|
||
- `fix/*`: 修复分支
|
||
|
||
---
|