基于 Ultralytics YOLO26 和 OpenCV 的本地实时监控工具。支持摄像头、视频文件、RTSP/HTTP 流、屏幕/游戏画面采集输入，实时检测并记录事件，具备断流自动重连、目标跟踪去重、ROI 区域过滤、告警通知推送等能力。
third_party/ultralytics 保留为第三方源码快照，项目业务入口在 yolo_monitor/。
已配置好环境的机器，直接运行：
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source 0新机器请先按下方"从零搭建"完成环境准备。
- Python 3.13.x（项目要求
>=3.13,<3.14） - Git
- NVIDIA 显卡 + CUDA 驱动（可选，无 GPU 时自动回退 CPU）
git clone <仓库地址>
cd yolo_projectpython3.13 -m venv .venv-ultralytics
.\.venv-ultralytics\Scripts\pip.exe install --upgrade pip
.\.venv-ultralytics\Scripts\pip.exe install -e ".[dev]"这条命令会根据 pyproject.toml 安装三个核心依赖（opencv-python、torch、ultralytics）和两个开发依赖（pytest、ruff）。安装过程约 3-5 分钟，torch 包较大（约 2.5GB）。
如需 GPU 加速，确认安装的 PyTorch 版本与本机 CUDA 版本匹配。当前默认安装 CUDA 12.6 版本。检查方式：
.\.venv-ultralytics\Scripts\python.exe -c "import torch; print(torch.cuda.is_available())"输出 True 表示 GPU 可用。
如需使用屏幕/游戏画面采集功能，额外安装可选依赖：
.\.venv-ultralytics\Scripts\pip.exe install -e ".[screen]"这会安装 mss（跨平台截图）、dxcam（Windows DXGI 高性能采集）和 pywin32（窗口定位）。
首次运行时程序会自动下载 yolo26n.pt 到 weights/ 目录，无需手动操作。如需离线使用，提前将模型文件放入 weights/ 即可：
mkdir weights
# 将 yolo26n.pt 复制到 weights/ 目录用示例图片跑一次 headless 验证：
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source third_party\ultralytics\ultralytics\assets\bus.jpg --loop-image --headless --max-frames 3 --imgsz 640 --device cpu正常输出应包含：
summary frames=3 inference_frames=3 events=3 average_fps=... run_dir=...
支持五种输入：摄像头索引（--source 0）、本地视频文件、图片循环（--loop-image）、RTSP/HTTP 流、屏幕/游戏画面采集（--source screen）。
YOLO26 实时推理，检测到目标后保存标注截图和 events.jsonl 日志。支持 --classes 类别过滤、--conf 置信度阈值、--imgsz 推理尺寸、--frame-skip 跳帧。
RTSP/HTTP 流断开后自动指数退避重连，恢复后继续监控。窗口显示 "Reconnecting..." 状态。重连次数和耗时记录在运行摘要中。--max-reconnect 控制最大重连次数，超过后退出。
启用 Ultralytics 内置 ByteTrack 跟踪器，为每个目标分配唯一 ID。同一目标在冷却期内不重复记录事件，大幅减少重复告警。
指定多边形区域，仅当目标中心点在区域内时才触发事件。区域外目标仍显示在窗口标注中。参数格式为空格分隔的坐标对：--roi "100,200 300,200 300,400 100,400"。
启用生产者-消费者模式，读帧线程与推理线程并行工作。队列满时丢弃旧帧，确保推理端始终处理最新帧。--buffer-size 4 即可显著降低 GPU 等待时间。
事件触发后向指定 URL 发送 HTTP POST JSON 请求，可对接钉钉、飞书、企业微信等。通知失败静默处理，不阻塞主循环。
将运行参数写入 YAML 文件，避免每次输入长串 CLI 参数。CLI 参数可覆盖文件中的同名字段。示例文件见 config.example.yaml。
对桌面或游戏窗口进行实时截屏检测，适用于游戏辅助、UI 自动化测试、桌面监控等场景。支持三种格式：
--source screen：全屏采集（或用--screen-region指定区域）--source screen:100,200,800,600：内联指定采集区域（left,top,width,height）--source screen:window=窗口名称：通过窗口名自动定位采集区域（需安装 pywin32）
检测结果的坐标自动映射回绝对屏幕位置，ROI 过滤和事件记录均使用屏幕坐标。
默认使用 mss 后端（跨平台截图）。Windows 上可通过 --screen-backend dxcam 切换到 DXGI 高性能后端，适合 DirectX 独占全屏游戏。屏幕采集需安装可选依赖：
.\.venv-ultralytics\Scripts\pip.exe install -e ".[screen]"# 摄像头实时监控
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source 0
# RTSP 流 + 目标跟踪 + 断流重连
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source rtsp://camera.local/stream --track --reconnect-delay 2 --max-reconnect 20
# ROI 区域过滤 + 并行取帧
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source 0 --roi "100,100 500,100 500,400 100,400" --buffer-size 4
# 后台运行 + Webhook 通知
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source rtsp://camera.local/stream --headless --webhook-url "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN"
# 使用 YAML 配置文件
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --config my_config.yaml
# 配置文件 + CLI 覆盖（CLI 优先）
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --config my_config.yaml --conf 0.6 --headless
# 低配机器降低推理压力
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source 0 --imgsz 480 --frame-skip 2
# 只记录指定类别
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source 0 --classes person,car
# 全屏采集（需先 pip install -e ".[screen]"）
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source screen
# 指定区域采集
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source screen --screen-region "0,0,1280,720"
# 通过窗口名定位 + dxcam 高性能后端
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source "screen:window=记事本" --screen-backend dxcam
# 屏幕采集 + ROI + 后台运行
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --source screen --screen-region "0,0,1280,720" --roi "100,100 600,100 600,600 100,600" --headless| 参数 | 默认值 | 说明 |
|---|---|---|
--source |
0 |
摄像头索引、图片、视频、RTSP 或 HTTP 流 |
--model |
weights/yolo26n.pt |
YOLO 模型权重路径 |
--device |
auto |
auto、cpu、0、1 等 |
--conf |
0.35 |
检测置信度阈值（0-1） |
--cooldown |
5.0 |
事件保存冷却秒数 |
--save-dir |
runs/monitor |
监控输出根目录 |
--headless |
false |
不显示 OpenCV 窗口 |
--max-frames |
无限制 | 最多读取帧数后退出 |
--loop-image |
false |
图片源循环读取 |
--imgsz |
640 |
YOLO 推理尺寸 |
--frame-skip |
1 |
每 N 帧推理一次 |
--classes |
无过滤 | 逗号分隔类别名或 ID |
--max-snapshots |
无限制 | 最多保存截图数 |
--reconnect-delay |
1.0 |
重连初始延迟秒数（指数退避，上限 30s） |
--max-reconnect |
10 |
最大重连次数 |
--track |
false |
启用 ByteTrack 目标跟踪 |
--roi |
无 | ROI 多边形顶点，空格分隔坐标对 |
--buffer-size |
0 |
帧缓冲区大小，>0 启用并行模式 |
--webhook-url |
无 | Webhook 通知 URL |
--config |
无 | YAML 配置文件路径 |
--screen-region |
全屏 | 屏幕采集区域：left,top,width,height |
--screen-backend |
mss |
屏幕采集后端：mss 或 dxcam |
窗口模式按键：q 退出，s 保存当前显示帧。
项目根目录提供 config.example.yaml 示例文件，包含所有可配置项和中文注释。使用方式：
# 复制示例文件并修改
copy config.example.yaml my_config.yaml
# 编辑 my_config.yaml 中的参数
# 启动时指定配置文件
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --config my_config.yaml优先级规则：CLI 参数 > YAML 文件 > 默认值。
每次运行在 runs/monitor/<run_id>/ 下创建：
runs/monitor/<run_id>/
snapshots/*.jpg # 事件截图和手动截图
events.jsonl # 事件日志，每行一条 JSON
events.jsonl 每行包含 timestamp、source、frame_index、model、device、image_path 和 detections。启用 --track 时每条检测额外包含 track_id 字段。
运行退出时输出摘要：
summary frames=1200 inference_frames=600 events=15 average_fps=25.30 reconnect_count=0 reconnect_time=0.00s run_dir=runs/monitor/...
# 运行全部测试
.\.venv-ultralytics\Scripts\python.exe -m pytest
# 代码检查
.\.venv-ultralytics\Scripts\ruff.exe check .
# 查看帮助
.\.venv-ultralytics\Scripts\python.exe -m yolo_monitor --helpthird_party/ultralytics 以普通源码形式纳入根仓库（非 submodule），可直接打断点调试：
.\.venv-ultralytics\Scripts\python.exe debug_ultralytics.pyPyCharm 可使用 Debug Ultralytics 运行配置进入 third_party/ultralytics 源码。
项目根目录是唯一 Git 仓库。third_party/ultralytics 是纳入根仓库的普通源码快照，更新第三方源码时在根仓库中统一提交。
.gitignore 已忽略：.venv*、runs/、weights/、*.pt、__pycache__/、.pytest_cache/、.ruff_cache/。
最后更新：2026-06-13（v0.3.0）