macOS DETR 车辆动态打标

这是一个参考 ../VideoPipe 思路实现的 macOS 友好版 Python 项目：

RTSP/HLS/本地文件源节点 -> DETR 车辆检测推理节点 -> OSD 画框节点 -> FastAPI 远程输出节点

本项目不直接移植 VideoPipe 的 C++、TensorRT、CUDA、GStreamer RTSP Server 工程，而是保留它的“源节点 → 推理节点 → OSD → 输出节点”思想，使用 Python、OpenCV、PyTorch、Transformers DETR 和 FastAPI，方便在 Mac mini / Apple Silicon 上运行。

架构和推理流程

flowchart TD
    A[devicelist.env 摄像头列表] --> B[DeviceManager 默认选择第一个设备]
    B --> C[能力开放接口获取 RTSP 地址]
    C --> D[OpenCV VideoCapture 读取视频流]
    D --> E[StreamWorker 抽帧]
    E --> F[DetrVehicleDetector 车辆检测]
    F --> G[OpenCV OSD 画框]
    G --> H[FastAPI MJPEG /video]
    H --> I[WebSocket /ws/detections]
    I --> J[浏览器动态打标画面]

---

flowchart TD
    A[读取一帧 BGR 图像] --> B{是否达到 FRAME_SKIP}
    B -- 否 --> F[复用上一轮检测结果]
    B -- 是 --> C[转换为 RGB]
    C --> D[Transformers ImageProcessor 预处理]
    D --> E[PyTorch DETR 推理]
    E --> G[按 DETR_CONFIDENCE 过滤车辆类别]
    F --> H[绘制检测框和标签]
    G --> H
    H --> I[JPEG 编码]
    I --> J[FastAPI 输出到远程浏览器]

安装

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

配置

视频流地址通过环境变量传入，不要把 RTSP/HLS token 写进代码或文档。

export STREAM_URL='rtsp://你的摄像头或视频流地址'
export DETR_CONFIDENCE=0.6
export FRAME_SKIP=5

可选配置：

export DETR_MODEL='facebook/detr-resnet-50'
export JPEG_QUALITY=80
export RESIZE_WIDTH=960
export VEHICLE_LABELS='car,motorcycle,bus,truck,bicycle'

配置说明：

• STREAM_URL：RTSP、HLS 或本地视频文件路径，必填。
• DETR_CONFIDENCE：检测置信度阈值，默认 0.6。
• FRAME_SKIP：每隔多少帧做一次 DETR 推理，默认 3。数值越大，负载越低。
• RESIZE_WIDTH：可选，设置后会按宽度等比缩小视频帧，降低 Mac mini 压力。
• VEHICLE_LABELS：需要保留的 COCO 车辆类别。

运行

uvicorn app.main:app --host 0.0.0.0 --port 8000

本机访问：

http://127.0.0.1:8000

局域网远端访问：

http://<Mac-IP>:8000

接口

• GET /：中文浏览器看板。
• GET /video：MJPEG 动态打标视频流。
• GET /detections：最近一帧检测结果 JSON。
• GET /status：运行状态、模型、设备、帧号、FPS。
• WS /ws/detections：实时推送检测元数据。

RTSP 和 HLS 选择

建议优先使用 RTSP，实时性更好。HLS .m3u8 通常更稳定，但会有几秒到十几秒延迟。

OpenCV 需要带 FFmpeg 支持才能打开很多 RTSP/HLS 地址。如果无法打开远端流，可以先用本地视频文件验证项目，再考虑增加 PyAV 或 ffmpeg-python 输入后端。

macOS 远端访问检查

如果其他机器访问不到页面，检查 macOS 防火墙，并确认服务监听在 0.0.0.0。

curl http://127.0.0.1:8000/status
curl http://<Mac-IP>:8000/status
lsof -i :8000

性能建议

DETR 原版模型较重。Mac mini 上建议先这样跑：

export FRAME_SKIP=5
export RESIZE_WIDTH=960

Apple Silicon 上会优先使用 PyTorch MPS；不可用时自动回退到 CPU。

与 VideoPipe 的对应关系

VideoPipe 概念	本项目实现
源节点	StreamWorker 中的 OpenCV VideoCapture
推理节点	DetrVehicleDetector
OSD 节点	StreamWorker._draw()
输出节点	FastAPI /video、/detections、/ws/detections
分析看板	浏览器中文 Dashboard