|
|
@@ -0,0 +1,120 @@
|
|
|
+# CLAUDE.md
|
|
|
+
|
|
|
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
+
|
|
|
+## 项目概览
|
|
|
+
|
|
|
+基于 PEFT 的前后端分离微调平台，支持文本（LLaMA/Qwen）、视觉（ViT/CLIP）、多模态（LLaVA/Qwen-VL）三类模型，完整 MLOps 流水线。
|
|
|
+
|
|
|
+## 常用命令
|
|
|
+
|
|
|
+### 后端
|
|
|
+
|
|
|
+```bash
|
|
|
+cd backend
|
|
|
+pip install -r requirements.txt
|
|
|
+uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
|
|
+```
|
|
|
+
|
|
|
+API 文档：`http://192.168.91.253:8000/docs`
|
|
|
+
|
|
|
+### 前端
|
|
|
+
|
|
|
+```bash
|
|
|
+cd frontend
|
|
|
+npm install
|
|
|
+npm run dev # 开发
|
|
|
+npm run build # 构建
|
|
|
+npm run preview # 预览构建产物
|
|
|
+```
|
|
|
+
|
|
|
+## 架构
|
|
|
+
|
|
|
+### 三层环境变量
|
|
|
+
|
|
|
+| 文件 | 归属 | 路径 |
|
|
|
+|------|------|------|
|
|
|
+| `.env` | 全局共享 | HF Token、GPU、ModelScope |
|
|
|
+| `backend/.env` | 后端专属 | HOST/PORT/CORS、数据库、训练参数 |
|
|
|
+| `frontend/.env` | 前端专属 | VITE_API_BASE_URL、VITE_WS_BASE_URL |
|
|
|
+
|
|
|
+`backend/app/config.py` 中的 `Settings` 类通过 `pydantic-settings` 加载 `backend/.env`。
|
|
|
+
|
|
|
+### 后端分层
|
|
|
+
|
|
|
+```
|
|
|
+main.py → FastAPI 入口（挂载路由 + CORS + 健康检查）
|
|
|
+├── api/ REST 路由层（薄，委托给 services）
|
|
|
+│ ├── models.py GET /api/v1/models, POST /download
|
|
|
+│ ├── datasets.py 上传/预览/验证/列表/删除
|
|
|
+│ ├── training.py 训练任务 CRUD + 取消 + 日志流
|
|
|
+│ ├── evaluation.py 评估运行 + 结果查询
|
|
|
+│ └── deployment.py adapter 合并 + 导出
|
|
|
+├── core/ 基础设施
|
|
|
+│ ├── db.py SQLAlchemy async + aiosqlite
|
|
|
+│ ├── job_queue.py 训练任务状态模型 + 状态机
|
|
|
+│ ├── websocket.py WebSocket 广播（进度/错误/心跳）
|
|
|
+│ └── logging.py 结构化日志
|
|
|
+├── services/ 业务逻辑层
|
|
|
+│ ├── model_service.py 模型下载/缓存
|
|
|
+│ ├── dataset_service.py 上传/格式检测
|
|
|
+│ ├── training_service.py 任务编排
|
|
|
+│ ├── eval_service.py 评估
|
|
|
+│ └── deploy_service.py adapter 导出
|
|
|
+├── engines/ 按模型类型的训练引擎（BaseEngine 抽象接口）
|
|
|
+│ ├── base.py load_model / get_peft_config / preprocess_dataset / train
|
|
|
+│ ├── text_engine.py LLaMA/Qwen
|
|
|
+│ ├── vision_engine.py ViT/CLIP
|
|
|
+│ └── multimodal_engine.py LLaVA/Qwen-VL
|
|
|
+├── peft/ PEFT 配置工厂（LoRA/QLoRA/IA3/AdaLoRA/PrefixTuning）
|
|
|
+├── schemas/ Pydantic 请求/响应模型
|
|
|
+└── preprocessors/ 数据预处理（待实现）
|
|
|
+```
|
|
|
+
|
|
|
+### 前端结构
|
|
|
+
|
|
|
+```
|
|
|
+src/
|
|
|
+├── api/
|
|
|
+│ ├── client.ts Axios 实例 + 拦截器
|
|
|
+│ └── websocket.ts WebSocket 管理器 + 自动重连
|
|
|
+├── stores/
|
|
|
+│ └── trainingStore.ts Zustand 训练任务状态
|
|
|
+├── components/layout/Layout.tsx 侧边栏导航 + 内容区
|
|
|
+├── pages/ Dashboard / Models / Datasets / Training / Evaluation / Deployment
|
|
|
+└── App.tsx React Router 路由定义
|
|
|
+```
|
|
|
+
|
|
|
+### 关键数据流
|
|
|
+
|
|
|
+1. 前端通过 `/api/v1/training/jobs` POST 创建训练任务
|
|
|
+2. 后端 `training_service` 创建任务记录，加入 job_queue
|
|
|
+3. 训练引擎从 `BaseEngine` 派生（text/vision/multimodal）执行训练
|
|
|
+4. `app/core/websocket.py` 通过 `/ws/training/{job_id}` 实时推送进度到前端
|
|
|
+5. 前端 `wsManager.subscribe()` 接收消息，更新 `trainingStore`
|
|
|
+
|
|
|
+### WebSocket 消息类型
|
|
|
+
|
|
|
+| type | 说明 | 关键字段 |
|
|
|
+|------|------|----------|
|
|
|
+| progress | 训练进度 | epoch, step, total_steps, loss, learning_rate |
|
|
|
+| epoch_done | epoch 完成 | epoch, eval_loss, eval_accuracy |
|
|
|
+| completed | 训练完成 | total_time_seconds, adapter_path |
|
|
|
+| error | 错误 | message |
|
|
|
+| heartbeat | 心跳保活 | timestamp |
|
|
|
+
|
|
|
+### 任务状态机
|
|
|
+
|
|
|
+```
|
|
|
+pending → queued → preprocessing → training → completed
|
|
|
+ ↓
|
|
|
+ cancelled ←── any state ← evaluating → evaluation_done
|
|
|
+ failed ←── any state ←
|
|
|
+```
|
|
|
+
|
|
|
+### 部署信息
|
|
|
+
|
|
|
+- 服务器地址：`192.168.91.253`
|
|
|
+- 项目路径：`/root/Fine-tuning`
|
|
|
+- 数据目录：`/root/Fine-tuning/backend/data`
|
|
|
+- 数据库：`/root/Fine-tuning/backend/data/finetuning.db`
|
