# 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`

## 语言规范要求

### 基础规则

1. 所有日常对话、解释、分析、总结、步骤说明、文字回答**必须使用简体中文**。
2. 代码、变量名、函数名、命令、配置关键字、专业技术术语、报错原文、JSON/配置内容**保留英文原样，不要翻译**。
3. 注释可以用中文清晰说明逻辑。
4. 不要主动输出英文闲聊、英文解释，全程自然中文沟通。
5. 给出方案、排查原因、步骤讲解全部用中文，仅代码和技术固有文本用英文。

### 输出格式

- 说明文字：简体中文
- 代码块、终端命令、JSON、YAML、报错日志：保持原生英文不变
- 列表、步骤、结论一律中文表述