YOLO Vision - 游戏画面毫秒级识别系统

基于 YOLO 的高性能图像识别系统，支持自定义训练、CPU/GPU 双模式、毫秒级游戏画面识别。

---

特性

分类	功能	说明
推理引擎	自定义训练	支持训练识别人物、物体、场景、UI、地图等各类模型
	双模式推理	CPU/GPU 无缝切换，自动选择最优设备
	毫秒级识别	优化推理管道 (CPU 30-100ms, GPU 5-15ms, TensorRT 2-8ms)
	多后端支持	.pt (ultralytics) / .onnx (ONNX Runtime) / .engine (TensorRT)
数据源	屏幕捕获	dxcam (Windows 1000+ FPS) / mss (跨平台)
	摄像头支持	实时摄像头画面识别
	视频文件	视频逐帧批量检测
	图片文件	单张/批量图片检测
训练模块	数据集转换	COCO/VOC 格式自动转换为 YOLO 格式
	自定义训练	一键训练脚本，支持数据增强
	模型导出	支持 ONNX、TensorRT 格式导出
部署服务	REST API	FastAPI 接口，支持 Base64/文件上传检测
	WebSocket	实时流检测，支持多客户端
	Web 平台	可视化训练界面，从零构建数据集

---

快速开始

安装

# 使用 uv (推荐)
git clone https://git.skcks.cn/Shikong/yolo-vision.git
cd yolo-vision
uv venv
uv pip install -e ".[full]"      # 全功能安装 (GPU + 开发工具 + 可视化)

# Windows 高性能捕获
uv pip install -e ".[windows]"   # dxcam (1000+ FPS 屏幕捕获)

# 或使用 pip (清华镜像)
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

快速使用

# 实时屏幕检测
yolo-vision detect --source screen --model yolo11n.pt --show

# 图像检测
yolo-vision detect --source image --image-path test.jpg --model yolo11n.pt

# 训练自定义模型
yolo-vision train --data datasets/data.yaml --model yolo11n.pt --epochs 100

# 导出 ONNX 模型
yolo-vision export --model yolo11n.pt --format onnx --half

# 启动 API 服务
yolo-vision serve --port 8000 --model yolo11n.pt

# 性能基准测试
yolo-vision benchmark --model yolo11n.pt --iterations 100

# 启动 Web 训练平台
yolo-vision web --port 8080

Python API

from yolo_vision import YOLOEngine, Detector, ScreenCapture, InferencePipeline

# 基础推理
engine = YOLOEngine("yolo11n.pt", device="auto")
detections = engine.infer(image)
print(f"检测到 {len(detections)} 个目标")

# 高级检测器
detector = Detector("yolo11n.pt")
detections = detector.detect(image)
persons = detector.filter_by_class(detections, ["person"])
top5 = detector.sort_by_confidence(detections)[:5]

# 屏幕捕获
with ScreenCapture(monitor_idx=0) as cap:
    frame = cap.capture()
    detections = detector.detect(frame)

# 推理管道 (异步)
def on_result(result):
    print(f"FPS: {result.fps:.1f}, 检测: {len(result.detections)}")

pipeline = InferencePipeline(
    model_path="yolo11n.pt",
    on_result=on_result,
    async_mode=True,
)
pipeline.start()

REST API

# 启动服务
yolo-vision serve --port 8000

# Base64 图像检测
curl -X POST http://localhost:8000/detect \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "...", "confidence": 0.25}'

# 文件上传检测
curl -X POST http://localhost:8000/detect/file \
  -F "file=@test.jpg" \
  -F "model=yolo11n.pt" \
  -F "confidence=0.25"

# WebSocket 实时流
ws://localhost:8000/ws/stream

---

Web 训练平台

启动可视化训练平台，无需命令行即可完成从数据集创建到模型训练的全流程：

yolo-vision web --port 8080

访问 http://localhost:8080 即可使用以下功能：

功能模块	说明
数据集管理	上传 YOLO/COCO/VOC 格式数据集，在线标注
数据集创建	可视化标注工具，支持创建自定义数据集
可视化训练	配置参数、实时监控训练进度
模型管理	查看、测试、下载训练好的模型
在线检测	上传图像测试模型效果

数据集格式支持：

格式	目录结构	说明
YOLO	train/images/, train/labels/, data.yaml	推荐格式，纯文本标注
COCO	annotations.json, images/	JSON 元数据，通用标注格式
VOC	Annotations/, JPEGImages/	PASCAL VOC XML 格式

---

项目结构

yolo-vision/
├── pyproject.toml      # 项目配置 (uv/pip)
├── uv.toml             # UV 镜像配置
├── requirements.txt    # 依赖列表
│
├── yolo_vision/        # 核心包
│   ├── __init__.py     # 包入口，导出核心 API
│   ├── core/           # 推理引擎核心
│   │   ├── engine.py   # YOLOEngine - 设备选择、模型加载
│   │   ├── detector.py # Detector - 高级封装，过滤/排序/合并
│   │   └── config.py   # 数据类型定义
│   ├── capture/        # 画面捕获
│   │   └── screen.py   # ScreenCapture - dxcam/mss 双后端
│   ├── inference/      # 推理管道
│   │   └── pipeline.py # InferencePipeline - 捕获-推理-回调
│   ├── training/       # 训练模块
│   │   └── trainer.py  # YOLOTrainer, DatasetConverter
│   ├── api/            # REST API
│   │   └── server.py   # FastAPI 服务
│   ├── web/            # Web 平台
│   │   └── app.py      # Web 可视化训练界面
│   ├── cli_commands/   # CLI 命令实现
│   │   ├── detect.py   # detect 命令
│   │   ├── train.py    # train 命令
│   │   ├── export.py   # export 命令
│   │   ├── benchmark.py # benchmark 命令
│   │   └── serve.py    # serve 命令
│   └── utils/          # 工具函数
│
├── models/             # 模型文件目录
├── datasets/           # 数据集目录
└── runs/               # 训练输出目录

---

设备支持

设备	推理速度	适用场景
CPU	30-100ms	开发调试、轻量部署
GPU (CUDA)	5-15ms	实时游戏识别
GPU (TensorRT)	2-8ms	极致性能需求

设备自动选择优先级: TensorRT > CUDA > CPU

---

自定义训练

数据集格式转换

支持从 COCO/VOC 格式自动转换为 YOLO 格式：

from yolo_vision.training import DatasetConverter

converter = DatasetConverter("output_dir")

# 从 COCO 转换
converter.convert_from_coco("annotations.json", "images/", class_names=["person", "car", "dog"])

# 从 VOC 转换
converter.convert_from_voc("voc_dir/", class_names=["person", "car", "dog"])

训练流程

# 1. 准备数据集配置 data.yaml
# data.yaml 示例:
#   path: ./datasets/my_data
#   train: images/train
#   val: images/val
#   nc: 3
#   names: ['person', 'car', 'dog']

# 2. 开始训练
yolo-vision train --data datasets/data.yaml --model yolo11n.pt --epochs 100 --batch 16

# 3. 导出模型
yolo-vision export --model runs/train/exp/weights/best.pt --format onnx --half

在 Web 平台创建数据集

1. 访问 http://localhost:8080
2. 进入"数据集创建"模块
3. 上传原始图片
4. 使用在线标注工具标注目标
5. 导出为 YOLO 格式，直接用于训练

---

API 端点汇总

检测接口

端点	方法	参数	说明
/detect	POST	image_base64, confidence, model	Base64 图像检测
/detect/file	POST	file, model, confidence	文件上传检测
/detect/batch	POST	files[], model, confidence	批量图片检测

模型管理

端点	方法	参数	说明
/models	GET	-	列出已加载模型
/models/load	POST	model_path, device	加载模型
/models/unload	POST	model_name	卸载模型

训练接口

端点	方法	参数	说明
/train	POST	data_yaml, model, epochs	启动训练任务
/train/status	GET	task_id	查询训练状态
/train/cancel	POST	task_id	取消训练任务

系统接口

端点	方法	参数	说明
/stats	GET	-	性能统计 (FPS, 延迟, 设备)
/health	GET	-	健康检查
/ws/stream	WebSocket	model, confidence	实时流检测

---

文档索引

详细文档请参考以下指南：

文档	内容
安装指南	uv/pip 安装、依赖说明、镜像配置
快速开始	CLI 命令、Python API、REST API
Web 平台	可视化训练、数据集创建
项目结构	目录说明、模块介绍
设备支持	CPU/GPU/TensorRT 性能对比
自定义训练	数据集转换、训练流程、模型导出
API 端点	所有 REST API 接口说明

---

License

MIT License - 详见 LICENSE