YOLOv8-Streamlit 实时目标检测与跟踪系统

📖 项目概述

这是我基于 YOLOv8 算法和 Streamlit 框架开发的实时目标检测与跟踪系统。经过多次优化和调整，该系统在保持高检测准确性的同时，确保了流畅的实时性能，适合在普通硬件上部署使用。

系统支持多种输入源和任务类型，可灵活应用于各种实际场景，如视频监控、物体计数、交通分析等。

✨ 核心特性

• 🎯 双任务支持：目标检测与实例分割自由切换
• 📹 全源兼容：本地图像、视频文件、摄像头、RTSP流和YouTube视频全覆盖
• 🚀 精准跟踪：集成 ByteTrack 和 BoTSORT 先进跟踪算法
• ⚡ 性能优化：多线程处理、帧队列管理、智能模型选择，确保流畅运行
• 🎨 友好界面：基于 Streamlit 的现代化 Web 界面，操作简单直观
• 📊 实时监控：帧率显示和性能指标，随时了解系统状态
• 🔧 高度定制：支持自定义模型、参数配置，满足个性化需求
• 📝 详细日志：完整的检测过程和性能指标记录，便于分析和调试

🛠️ 技术栈

📁 项目结构

├── .devcontainer/          # DevContainer 配置
│   └── devcontainer.json
├── app.py                  # 主应用入口
├── helper.py               # 核心功能模块
├── settings.py             # 配置文件
├── requirements.txt        # 依赖列表
├── packages.txt            # 系统依赖
├── README.md               # 项目说明文档
├── USAGE_GUIDE.md          # 使用指南（本文件）
├── realtime_webcam.py      # 实时摄像头示例
├── test.py                 # 测试脚本
├── assets/                 # 静态资源
......

🚀 快速开始

1. 安装依赖

1.1 环境准备

• 推荐使用 Python 3.8 或更高版本
• 建议使用虚拟环境（venv 或 conda）避免依赖冲突
• 如需 GPU 加速，请确保安装了对应版本的 CUDA 和 cuDNN

1.2 安装步骤

# 进入项目目录
cd yolov8-streamlit-detection
# 创建虚拟环境（可选但推荐）
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# 安装Python依赖
pip install -r requirements.txt

# （可选）安装系统依赖（主要用于视频处理）
# 对于 Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y $(cat packages.txt)

# 对于 Windows
# 下载并安装 FFmpeg：https://ffmpeg.org/download.html

2. 准备模型权重

我已经在 weights 目录中预先准备了常用的模型：

• yolov8n.pt：检测模型（默认，速度最快）
• yolov8n-seg.pt：分割模型（速度最快）
• yolov8s.pt：检测模型（平衡速度和准确性）

3. 启动应用

streamlit run app.py

应用将在浏览器中自动打开，默认地址：http://localhost:8501

🎮 使用指南

模型配置

1. 模型路径：直接输入模型文件的路径（如 weights/yolov8n.pt）
2. 置信度阈值：调整滑块设置模型检测置信度（25%-100%）
   • 较低值：检测更多目标，但可能包含误检
   • 较高值：只检测高置信度目标，减少误检
3. 运行设备：选择 CPU 或 CUDA（如果可用）

输入源选择

🖼️ 图像检测

1. 选择输入源为 "Image"
2. 点击 "Browse files" 上传图像
3. （可选）启用跟踪器并选择跟踪类型
4. 点击 "开始检测" 按钮
5. 查看检测结果和详细信息
6. 可点击 "检测结果详情" 展开查看完整的检测数据

📹 视频检测

1. 选择输入源为 "Video"
2. 上传视频文件（支持 mp4、avi、mov、mkv、wmv、flv、webm 格式）
3. （可选）启用跟踪器并选择跟踪类型
4. 点击 "开始检测" 按钮
5. 观看实时检测结果
6. 检测结果将显示目标类型、置信度和推理时间

📷 摄像头实时检测

1. 选择输入源为 "Webcam"
2. （可选）启用跟踪器并选择跟踪类型
3. （可选）调整性能优化参数：
   • 目标帧率：控制显示帧率
   • 缓冲区大小：调整帧队列大小
   • 跳帧数量：控制处理频率
   • 使用GPU加速：提高处理性能
   • 检测置信度：调整检测阈值
4. 点击 "开始检测" 按钮
5. 观看实时摄像头检测结果
6. 点击 "停止检测" 按钮结束检测

📡 RTSP 流检测

1. 选择输入源为 "RTSP"
2. 输入 RTSP 流地址（示例：rtsp://admin:12345@192.168.1.210:554/Streaming/Channels/101）
3. （可选）启用跟踪器并选择跟踪类型
4. 点击 "开始检测" 按钮
5. 观看实时 RTSP 流检测结果

📺 YouTube 视频检测

1. 选择输入源为 "YouTube"
2. 输入 YouTube 视频链接（支持普通视频和直播流）
3. （可选）启用跟踪器并选择跟踪类型
4. 点击 "开始检测" 按钮
5. 观看实时 YouTube 视频检测结果

⚡ 性能优化

系统已经集成了多项性能优化措施，确保流畅的实时检测体验：

1. 多线程处理

摄像头捕获和模型推理在独立线程中运行，避免阻塞和卡顿：

• 捕获线程：负责从摄像头读取帧并放入队列
• 处理线程：从队列获取最新帧进行模型推理和显示

2. 帧队列管理

使用大小为 1 的队列，确保只处理最新的帧，避免帧堆积：

frame_queue = queue.Queue(maxsize=1)  # 只保留最新一帧

3. 跳帧处理

每隔一帧处理一次，减轻计算负担：

frame_count += 1
if frame_count % 2 != 0:
    continue  # 跳帧处理，减轻负担

4. 图像显示优化

使用固定宽度显示图像，避免 Streamlit 自动调整大小的性能开销：

st_frame.image(res_plotted, channels="BGR", width=720)

5. 模型大小选择

根据设备性能选择合适的模型大小，在速度和准确性之间取得平衡：

6. 性能参数调优

• 置信度阈值：提高阈值可减少检测数量，提高速度
• 输入尺寸：减小输入尺寸（imgsz参数）可显著提高速度
• 最大检测数量：减少max_det参数可提高速度
• 跳帧数：增加跳帧数可减少计算负担
• GPU加速：使用CUDA可大幅提高性能

🔧 定制化开发

1. 添加自定义模型

1. 将自定义模型权重文件放入 weights 目录
2. 在 settings.py 中配置模型路径：

# 添加到 DETECTION_MODELS 或 SEGMENTATION_MODELS 字典
DETECTION_MODELS = {
    # ... 现有模型
    'custom': MODEL_DIR / 'my_custom_model.pt',
}

2. 添加自定义视频源

1. 将视频文件放入 videos 目录
2. 在 settings.py 中更新 VIDEOS_DICT：

VIDEOS_DICT = {
    # ... 现有视频
    'my_video': VIDEO_DIR / 'my_video.mp4',
}

3. 修改默认设置

在 settings.py 中可以修改以下默认设置：

# 默认图像路径
DEFAULT_IMAGE = IMAGES_DIR / 'office_4.jpg'

# 默认摄像头路径
WEBCAM_PATH = 0  # 0 表示默认摄像头

# 默认模型
DETECTION_MODEL = DETECTION_MODELS['nano (最快)']

4. 扩展功能

添加新的输入源类型

1. 在 settings.py 中添加新的输入源类型
2. 在 helper.py 中添加对应的处理函数
3. 在 app.py 中添加对应的UI和处理逻辑

自定义检测结果显示

修改 _display_detected_frames 函数以调整检测结果的显示方式：

def _display_detected_frames(conf, model, image, frame_idx, logger):
    # 自定义处理逻辑
    # ...
    return res_plotted, caption, total_time

添加新的跟踪器

1. 将跟踪器配置文件放入项目目录
2. 在UI中添加跟踪器选项
3. 在模型预测时使用新的跟踪器

🐛 故障排除

1. 摄像头无法打开

• 确保摄像头没有被其他应用占用
• 检查 settings.py 中的 WEBCAM_PATH 设置
• 对于 Windows，尝试修改 cv2.VideoCapture 使用 DirectShow 后端：

  vid_cap = cv2.VideoCapture(source_webcam, cv2.CAP_DSHOW)

• 使用 test.py 脚本诊断摄像头问题

2. 应用运行缓慢

• 降低模型大小，选择 "nano" 或 "small"
• 提高置信度阈值
• 减少检测的目标类别
• 关闭跟踪功能
• 启用跳帧处理
• 减小输入尺寸
• 使用GPU加速（如果可用）

3. YouTube 视频无法播放

• 确保网络连接正常
• 检查 YouTube 视频链接是否有效
• 尝试不同的 YouTube 视频
• 确认视频不是私有或受限制的
• 检查是否安装了最新版本的 yt-dlp

4. RTSP 流无法连接

• 检查 RTSP 地址格式是否正确
• 确保网络连接正常
• 验证 RTSP 服务器是否可访问
• 检查用户名和密码是否正确
• 确保防火墙没有阻止连接

5. 模型无法加载

• 检查模型路径是否正确
• 确保模型文件存在
• 验证模型格式是否正确（应为.pt文件）
• 检查是否安装了最新版本的 ultralytics 包
• 查看日志文件以获取详细错误信息

6. 检测结果不准确

• 降低置信度阈值
• 选择更大的模型
• 使用更合适的自定义模型
• 确保光线条件良好
• 调整摄像头焦距和角度

📊 性能指标

系统在不同配置下的性能参考（基于 Intel i7 CPU）：

📝 日志系统

系统提供了详细的日志记录功能：

• 日志文件位置：log/ 目录下
• 日志分类：
  • time_all_log_*.log：所有操作的综合日志
  • YouTube.log：YouTube视频处理日志
  • RTSP.log：RTSP流处理日志
  • Webcam.log：摄像头处理日志
  • Video.log：本地视频处理日志
  • General.log：通用操作日志
• 日志内容：
  • 模型加载信息
  • 检测过程详情
  • 性能指标（帧率、推理时间等）
  • 错误信息和异常堆栈

💡 最佳实践

1. 模型选择

• 实时应用：使用 Nano 或 Small 模型
• 静态图像分析：使用 Medium 或 Large 模型
• 高精度要求：使用 Large 或 Extra Large 模型

2. 参数设置

• 置信度阈值：建议设置在 40%-60% 之间
• 输入尺寸：640x640 是速度和准确性的最佳平衡
• 跟踪器：ByteTrack 适用于大多数场景，BoTSORT 适用于更复杂的场景

3. 硬件选择

• CPU：至少 4 核心处理器，推荐 8 核心以上
• 内存：至少 8GB RAM，推荐 16GB 以上
• GPU：推荐使用 NVIDIA GPU（RTX 30 系列或更高）
• 存储：SSD 可提高模型加载速度

感谢使用本项目！如有任何问题或建议，欢迎交流。