一、项目简介
本项目用 YOLOv8 把手势识别建模为目标检测任务，对打电话、比耶、摇滚、OK、握拳等 18 类静态手势做检测。模型在 34,723 张训练图上完成训练后，以 FastAPI 构建 Web 平台，把检测与训练能力一起搬到浏览器里。
平台覆盖图片、批量、视频、摄像头四类输入，并提供网页模型训练：可在页面上配置超参数发起真实训练，训练过程中在线调整学习率、查看实时曲线与日志，训练完成后直接切换新权重用于检测，形成训练与推理的闭环。
图片识别页：上传手势图片后由模型真实推理，输出检测框、类别、置信度与类别分布。
二、数据集说明
1. 数据来源与样本
数据集按 YOLO 检测格式组织，每张图片对应一个手势目标，标注框定位手部区域、类别标注对应手势。下图为 18 类手势各抽取的一张真实样本：
数据集原图样本：call、dislike、fist、four、like、mute、ok、one、palm、peace、peace_inverted、rock、stop、stop_inverted、three、three2、two_up、two_up_inverted。
2. 数据构成
训练集与验证集独立存放，共 42,855 张图片、42,855 个标注框，每个标注文件均含有效目标，无空标注文件。
| 划分 | 图像数量 | 标注框数 | 用途 |
|---|---|---|---|
| 训练集 train | 34,723 | 34,723 | 模型训练与数据增强 |
| 验证集 val | 8,132 | 8,132 | 轮次验证与最优权重选择 |
3. 十八类手势
| 编号 | 英文名称 | 中文名称 | 训练集框数 | 编号 | 英文名称 | 中文名称 | 训练集框数 |
|---|---|---|---|---|---|---|---|
| 0 | call |
打电话 | 1,975 | 9 | peace |
比耶 | 1,960 |
| 1 | dislike |
不喜欢 | 1,793 | 10 | peace_inverted |
倒比耶 | 1,981 |
| 2 | fist |
握拳 | 1,933 | 11 | rock |
摇滚手势 | 1,878 |
| 3 | four |
四 | 1,949 | 12 | stop |
停止 | 1,979 |
| 4 | like |
点赞 | 1,826 | 13 | stop_inverted |
倒停止 | 1,937 |
| 5 | mute |
静音 | 1,847 | 14 | three |
三 | 1,927 |
| 6 | ok |
OK | 1,943 | 15 | three2 |
三变体 | 2,037 |
| 7 | one |
一 | 1,835 | 16 | two_up |
二向上 | 2,016 |
| 8 | palm |
手掌 | 1,995 | 17 | two_up_inverted |
倒二向上 | 1,912 |
18 类样本量相当均衡，每类训练框数集中在 1,800 至 2,040 之间，不存在明显长尾类别。但类间差异主要在手指组合与朝向，peace 与 peace_inverted、three 与 three2、two_up 与 two_up_inverted 这几组属于正反朝向配对，是实际推理中最容易混淆的地方。
4. 标注分布
训练框架对训练集标注的统计：左上为 18 类手势的标注框数量，右上为标注框宽高比分布，下方两张分别是标注框中心位置与宽高分布。
训练产物原图 labels.jpg：18 类手势的标注数量及尺寸、位置分布。
5. 训练时的数据增强
训练阶段启用 mosaic 等增强策略。下图为训练批次的实际输入，多张手势样本被拼接为一张图参与训练，并带有真实标注框：
训练产物原图 train_batch0.jpg：训练批次输入与真实标注。
三、模型训练与结果
1. 训练配置
- 以
yolov8n.pt预训练权重为起点，采用迁移学习。 - 训练 100 轮，batch 16，输入 640 × 640，初始学习率 0.01、余弦退火至 0.0002。
- 动量 0.937，权重衰减 0.0005，预热 3 轮，优化器自动选择。
- 数据增强含 Mosaic 1.0、水平翻转 0.5、HSV 增强、平移 0.1、缩放 0.5、随机擦除 0.4，最后 10 轮关闭 Mosaic。
2. 最终指标
| 指标 | 末轮数值（第 100 轮） | 峰值（对应轮次） |
|---|---|---|
| mAP@0.5 | 0.9916 | 0.9916（第 100 轮） |
| mAP@0.5:0.95 | 0.9153 | 0.9153（第 100 轮） |
| Precision | 0.9830 | 0.9874（第 83 轮） |
| Recall | 0.9793 | 0.9803（第 92 轮） |
mAP@0.5 达到 0.9916，说明 18 类手势在 IoU 0.5 下基本全部命中；mAP@0.5:0.95 为 0.9153，表示框位精度同样稳定。Precision 与 Recall 的峰值分别出现在第 83 与第 92 轮，而 mAP 峰值在末轮，因此末轮表用于查看同一轮完整结果，峰值表用于查看单项最高记录，两者不混为一谈。完整 100 轮训练耗时约 9.73 小时。
平台内的训练指标页：读取真实 results.csv 绘制损失、mAP、精确率召回率与学习率六张曲线。
3. 训练产物曲线
训练完成后框架在 runs/gesture_train/20260225_163759/ 下导出曲线图，下图为损失、精确率召回率与 mAP 的原始图：
训练产物原图 训练损失曲线.png：box、cls、dfl 三类训练损失随轮次变化。
训练产物原图 精确率召回率曲线.png：Precision 与 Recall 随轮次变化。
训练产物原图 mAP曲线.png：mAP@0.5 与 mAP@0.5:0.95 随轮次变化。
训练产物原图 训练指标综合图.png：训练与验证损失、精确率召回率、mAP、学习率与总损失对比共六个子图。
四、功能设计
1. 登录与注册
页面中心单栏卡片，登录与注册共用同一张 3 : 4 比例的卡片。密码哈希保存，会话通过 Cookie 维持，不同账号分别保存检测记录。
2. 图片识别
上传单张手势图片或直接选用验证集实拍样图，检出目标后输出标注结果图，并同步给出总检测数、命中类别数、平均与最高置信度。右侧可切换统计摘要、检测框明细与置信度分布三个视图。
检测框明细：每个目标的类别、中文释义、置信度、坐标与面积。
置信度分布：按 0.1 区间统计检测框数量，用于判断推理质量。
3. 批量识别
一次提交最多 30 张图片批量推理，逐张汇总目标数与识别类别，并给出整批统计：处理图片数、累计检出目标、整体平均置信度与总推理耗时。结果可一键导出为 ZIP，内含汇总表、明细表与全部标注图。
4. 视频识别
上传本地视频或加载验证集图片合成的序列视频，按自定义帧间隔抽帧推理。检测在后台线程执行，页面轮询回显当前帧画面、进度条与实时统计，可随时停止或导出当前帧。
5. 摄像头识别
支持两种输入源：模拟摄像头流（用验证集实拍图片按序列播放，无需外接硬件）与本机物理摄像头（浏览器 WebRTC 采集）。可开关实时检测、设置每 N 帧检测一次，支持截图保存与整段会话写入检测历史。
6. 模型训练
在网页上配置基础权重、训练轮数、批次大小、输入尺寸、初始学习率、优化器与数据集采样比例后发起训练。训练以独立子进程真实执行，页面实时展示当前轮次、生效学习率、最新 mAP 与损失曲线、训练日志。
训练过程中可在线调整学习率，由训练进程在下一个批次确认生效并回执；支持安全停止，停止后已产出的权重与 results.csv 均保留；训练完成后可一键将新权重应用于检测，或下载 best.pt 与 results.csv。
7. 检测历史
所有检测记录按账号保存，支持按类型（图片 / 批量图片 / 视频 / 摄像头）筛选与文件名、手势类别关键词搜索。点击记录可查看完整结果预览与明细 JSON，可导出历史 CSV 或删除单条记录。
8. 模型管理
列出项目内全部可用权重及体积，选择后可验证并切换当前模型；也可手动输入项目内相对路径加载。推理参数包含置信度阈值、NMS IoU 阈值与最大检测框数，修改后持久化保存。页面同时展示运行设备、权重体积与 18 类手势映射表。
9. 训练指标
读取真实训练日志 results.csv，按当前界面主题动态绘制训练损失、验证损失、mAP 演进、精确率召回率、学习率调度与总损失对比六张曲线。支持切换训练记录、按轮次区间截取、查看各项指标的最佳轮次与末轮数值，并可导出当前主题的综合指标图。
五、技术栈
| 类别 | 技术 | 用途 |
|---|---|---|
| 编程语言 | Python、JavaScript | 后端服务与前端页面 |
| 模型与框架 | YOLOv8 / PyTorch | 18 类手势目标检测训练与推理 |
| Web 服务 | FastAPI、Uvicorn | 接口服务、鉴权与后台任务调度 |
| Web 前端 | 原生模块化 JS、CSS | 页面、交互与主题适配 |
| 图像与视频处理 | OpenCV、NumPy | 图像读取、绘制标注、逐帧处理 |
| 数据可视化 | Canvas 自绘图表 | 损失、mAP、精确率召回率、置信度分布 |
| 数据存储 | SQLite、JSON | 账号、会话、检测历史与推理参数 |
| 训练任务 | 子进程 + 状态文件 | 训练隔离执行、进度回写、在线调参与停止 |
六、项目结构
bash
gesture-recognition/
├── gesture_datasets/ # 数据集（train / val，含 images 与 labels）
│ └── data.yaml # 18 类名称与路径配置
├── runs/gesture_train/ # 训练产物：权重、results.csv 与曲线图
├── detection_app/ # PyQt6 桌面端（独立保留）
├── train.py # 训练入口
└── web/ # Web 检测与训练平台
├── run.py # 服务启动入口
├── 一键启动.bat
├── backend/ # 配置、存储、推理、训练管理与接口
├── static/ # 页面、样式、交互与图表
├── data/ # 运行数据：数据库与配置文件
├── exports/ # 检测结果图、CSV 与批量压缩包
└── uploads/ # 上传的视频与序列素材七、运行说明
1. 安装依赖
bash
pip install -r requirements.txt2. 启动 Web 平台
bash
双击 web/一键启动.bat
# 或在该目录执行
python run.py服务默认监听本机 8127 端口，重复启动会提示服务已在运行；端口被其他程序占用时只提示、不擅自结束进程。
3. 默认账号
初始管理员账号为 admin，首次启动时自动创建，密码以哈希形式保存在 web/data/c127_web.db 中。
4. 重新训练（可选）
bash
python train.py也可直接在网页的「模型训练」页配置参数发起训练，无需进入命令行。