全栈病虫害检测系统，基于 YOLOv12 实现害虫检测功能，包含 FastAPI 后端服务和 React 前端界面，提供图像上传与害虫识别功能。
- FastAPI - Python 高性能 API 框架
- YOLOv12 - 目标检测模型（本地定制版）
- SQLAlchemy - ORM 数据库映射
- Redis - 缓存与会话管理
- Uvicorn - ASGI 服务器
- Pydantic - 数据验证
- OpenCV - 图像处理
- Docker - 容器化部署
- React 18 - 组件化 UI 框架
- TypeScript - 类型安全
- Vite - 现代前端构建工具
- Ant Design - UI 组件库
- React Router - 客户端路由
- Axios - API 请求库
- ✅ 用户认证 (登录/注册)
- ✅ 图像害虫识别上传与结果展示
- ✅ 视频害虫识别分析
- ✅ 历史记录管理
- ✅ 个人信息管理
- ✅ 自定义 YOLOv12 模型集成
- ✅ 实时检测结果可视化
- ✅ 检测结果统计分析
- ✅ 响应式界面设计
- 前端应用 - React 单页应用，处理用户交互与结果展示
- 后端 API 服务 - FastAPI 提供 RESTful 接口
- 检测引擎 - 封装 YOLOv12 模型的图像识别服务
- 数据管理 - 用户和检测历史的存储与检索
- 任务队列 - 处理视频等长时间任务
- 用户上传图像/视频 → 前端预处理
- API 请求 → 后端服务器
- 后端处理 → 模型推理
- 结果返回 → 前端展示
- 数据存储 → 历史记录
- Python 3.8+
- Node.js 18+
- npm 9+
- Redis 7+
- Docker 20.10+ (可选)
cd backend
# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# 或 .venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
# 安装本地修改的YOLOv12
pip install -e ./ultralytics
# 初始化数据库表结构
python create_tables.py
# 启动服务
uvicorn main:app --reload访问 API 文档：http://localhost:8000/docs
cd frontend
npm install
npm run devdocker-compose up --build访问前端：http://localhost
访问后端文档：http://localhost:8000/docs
├── backend
│ ├── app/ # 应用核心代码
│ │ ├── api/ # API路由和处理函数
│ │ ├── core/ # 配置和基础设施
│ │ ├── models/ # 数据库模型
│ │ ├── schemas/ # Pydantic模型
│ │ ├── services/ # 业务逻辑
│ │ └── static/ # 静态资源
│ ├── ultralytics/ # 自定义修改的YOLOv12代码
│ ├── main.py # 应用入口
│ ├── requirements.txt # 依赖库
│ └── create_tables.py # 数据库初始化
├── frontend
│ ├── src/ # 前端源码
│ │ ├── components/ # React组件
│ │ │ ├── common/ # 通用组件
│ │ │ ├── layout/ # 布局组件
│ │ │ ├── display/ # 展示组件
│ │ │ ├── media/ # 媒体组件
│ │ │ ├── analysis/ # 分析组件
│ │ │ ├── charts/ # 图表组件
│ │ │ ├── history/ # 历史记录组件
│ │ │ ├── profile/ # 个人信息组件
│ │ │ ├── statistics/ # 统计组件
│ │ │ └── assistant/ # 助手组件
│ │ ├── pages/ # 页面组件
│ │ ├── services/ # API服务
│ │ ├── hooks/ # 自定义Hooks
│ │ ├── contexts/ # React Context
│ │ ├── styles/ # 全局样式
│ │ ├── types/ # TypeScript类型定义
│ │ └── utils/ # 工具函数
│ ├── public/ # 静态资源
│ ├── index.html # HTML入口
│ ├── package.json # Node.js配置
│ └── vite.config.ts # Vite配置
└── docker-compose.yml # Docker编排配置
- 媒体组件 - 负责处理图像和视频上传、预览和播放
- 展示组件 - 呈现检测结果和标注图像
- 分析组件 - 提供数据可视化和统计分析功能
- 历史组件 - 管理和展示历史检测记录
// 在组件中使用全局检测状态
import { useDetectionContext } from '../contexts/DetectionContext'
function MyComponent() {
const { results, isProcessing, resetResults } = useDetectionContext()
// ...
}POST /api/detection/image
Content-Type: multipart/form-data
Request:
- file: 图像文件(jpg, png, jpeg)
Response:
{
"status": "success",
"results": [
{
"class": "褐飞虱",
"confidence": 0.95,
"bbox": {
"x1": 120,
"y1": 50,
"x2": 220,
"y2": 130
}
}
],
"annotated_image": "base64编码图像..."
}POST /api/detection/video
Content-Type: multipart/form-data
Request:
- file: 视频文件(mp4, avi)
Response:
{
"status": "success",
"task_id": "abcd1234",
"message": "视频处理已开始，请通过任务ID查询进度"
}GET /api/detection/video/status/{task_id}
Response:
{
"status": "processing", // processing, completed, failed
"progress": 45.5, // 百分比
"results": null, // 完成后返回结果
"error": null // 失败时返回错误信息
}GET /api/history
Authorization: Bearer {token}
Response:
{
"records": [
{
"id": "uuid",
"type": "image",
"filename": "example.jpg",
"timestamp": 1648454400000,
"result": {...}
}
]
}后端通过 PestDetector 类实现模型集成：
class PestDetector:
def __init__(self):
self.model = YOLO(settings.model_path, task="detect")
self.img_size = settings.img_size
self.conf_thresh = settings.conf_thresh
def process_image(self, image_bytes: bytes):
# 预处理图像
img_rgb = self.preprocess(image_bytes)
# 模型推理
results = self.model(img_rgb, imgsz=self.img_size, conf=self.conf_thresh)
# 解析结果并返回
predictions = self.parse_results(results)
return {
"status": "success",
"results": predictions,
"annotated_image": "..." # base64编码图像
}- 全局单例模型 - 避免重复加载模型
- 批处理推理 - 视频处理中使用批处理提升性能
- 缓存机制 - 使用 Redis 缓存部分计算结果
- 异步任务处理 - 长时间运行的任务使用后台队列
- 懒加载组件 - 按需加载页面组件
- 图像压缩 - 上传前压缩大图像
- 结果缓存 - 缓存检测结果避免重复请求
- 虚拟列表 - 历史记录中使用虚拟滚动
-
代码格式化：
- 后端：Black 格式化工具（4 空格缩进）
- 前端：ESLint + Prettier（2 空格+单引号）
-
环境配置：
- 开发环境：
.env.development - 生产环境：Docker 环境变量或
.env.production
- 开发环境：
-
依赖管理：
- Python：固定版本在 requirements.txt
- Node.js：package-lock.json 锁定版本
-
组件设计原则：
- 单一职责 - 每个组件只负责一个功能点
- 可组合性 - 小组件可以组合成更复杂的组件
- 可重用性 - 抽象通用逻辑，避免重复代码
- 可测试性 - 组件设计便于单元测试
- 响应式设计 - 所有组件适配多种屏幕尺寸
安装 OpenCV 并检查模型路径：
pip install opencv-python-headless==4.11.0.86确保模型文件位于正确路径:
# 检查模型路径设置
print(settings.model_path)
# 应指向 model_weights/best.pt修改 Vite 配置以连接后端：
// vite.config.ts
export default defineConfig({
// ...
server: {
proxy: {
'/api': 'http://localhost:8000',
},
},
})确保正确映射卷：
# docker-compose.yml
volumes:
- ./backend/models:/app/models检查后端连接配置：
// 检查.env文件中的API地址配置
console.log(import.meta.env.VITE_API_BASE_URL)前端与后端坐标系统可能不一致，请确保转换：
// 将后端返回的bbox转换为前端可用格式
const box = result.bbox
? [result.bbox.x1, result.bbox.y1, result.bbox.x2, result.bbox.y2]
: result.box确保正确设置了轮询间隔：
// 建议使用自定义Hook管理视频处理进度
useEffect(() => {
const interval = setInterval(checkProgress, 2000) // 每2秒检查一次
return () => clearInterval(interval)
}, [taskId])GPL-3.0 license