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 流水线。

常用命令

后端

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

前端

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 路由定义

关键数据流

前端通过 /api/v1/training/jobs POST 创建训练任务
后端 training_service 创建任务记录，加入 job_queue
训练引擎从 BaseEngine 派生（text/vision/multimodal）执行训练
app/core/websocket.py 通过 /ws/training/{job_id} 实时推送进度到前端
前端 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

语言规范要求

基础规则

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

输出格式

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

CLAUDE.md 4.9 KB 文件歷史 原始文件