cleoanka/panoptes

# Panoptes **多流道路与车辆智能分析：检测、跟踪、校准测速、ALPR（车牌识别）以及声明式交通规则引擎——集成于单一可部署进程中。** [](https://github.com/cleoanka/panoptes/actions) [](pyproject.toml) [](LICENSE) Panoptes 将 RTSP 摄像头、视频文件和网络摄像头转化为结构化的交通 智能数据：对车辆进行计数、分类和测速，融合车辆属性与车牌信息，并根据您在 YAML 中声明的规则进行评估—— 所有功能均通过 REST/SSE/WebSocket API 提供，并附带 Prometheus 指标和实时 仪表板。 ## 为什么选择 Panoptes - **原生支持多流。** 单进程运行 N 个按流分配的工作线程， 并在单个 GPU 微批处理推理调度器上运行——来自多个 摄像头的帧被融合进同一次检测器调用中。 - **统一契约下的 YOLO26 级检测器。** `ultralytics` (YOLO26)、 `rfdetr`、通用 ONNX、TensorRT 以及确定性的模拟后端，均输出 相同的标准化检测结果。只需一行配置即可切换后端。 - **纯净室实现的 ByteTrack。** 在恒速卡尔曼滤波器之上进行两阶段 高/低分关联，完全根据公开发表的算法从零编写—— 产品链路中不依赖任何 AGPL 跟踪器。 - **诚实可信的校准测速。** 采用图像到地面的单应性矩阵，基于媒体 PTS 的窗口式 位移计算（绝不依赖系统时钟，也非逐帧计算），并进行 EMA 平滑处理。无校准 → 无测速承诺。 - **声明式规则 DSL。** 逆向行驶、停留、按类别限速、观察列表以及 复合 `all_of`/`any_of` 条件，配合 webhook/快照/日志操作—— 全部在 YAML 中定义，并在启动时验证。详见 [docs/RULES.md](docs/RULES.md)。 - **基于轨迹并带有投票机制的 ALPR。** 在轨迹读取过程中采用基于字符置信度加权的 共识机制，并辅以土耳其语结构感知的 OCR 校正（省份代码 + 合法字母/数字模式）。 - **自适应帧调节器 (Frame Governor)。** 空闲场景以 ~2 fps 采样，繁忙场景 以全帧率采样——GPU 预算花在最需要的地方。 - **KVKK/GDPR 合规姿态。** 车牌属于个人数据：支持可选的加盐哈希 存储（依然支持匹配观察列表），对数据行和快照执行保留期清理， 以及经过身份验证的媒体访问。详见 [docs/PRIVACY.md](docs/PRIVACY.md)。 - **高度可运维。** 带有标准契约名称的 Prometheus 指标，兼容 Grafana， 结构化日志，支持 Docker/Kubernetes 部署。详见 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。 ## 功能矩阵 | 功能 | 您将获得 | 模块位置 | |---|---|---| | 检测 | YOLO26 / RF-DETR / ONNX / TensorRT / mock，统一契约 | `panoptes.detect` | | 跟踪 | 纯净室实现 ByteTrack，按流分配身份标识 | `panoptes.track` | | 速度与运动 | 单应性校准的 km/h、方向、距离 | `panoptes.motion` | | 计数 | 有向连线计数，按类别，带去抖动 | `panoptes.analytics` | | 区域 | 进入/离开/停留、占用率、停留警报 | `panoptes.analytics` | | 规则 | 声明式 DSL + webhook/快照/日志操作 | `panoptes.analytics.rules` | | ALPR | 车牌检测 + OCR + 验证 + 轨迹投票 | `panoptes.alpr` | | 属性 | 车辆颜色（启发式/模型）、品牌-车型钩子 | `panoptes.attributes` | | 观察列表 | 车牌列表，兼容静态哈希存储 | config + `panoptes.alpr` | | API | REST + SSE + WebSocket + MJPEG + 视频任务 | `panoptes.api` | | 存储 | SQLite/PostgreSQL，批量写入，保留策略 | `panoptes.storage` | | 可观测性 | Prometheus 指标，structlog | `panoptes.observability` | | CLI | serve, process, demo, benchmark, calibrate, export | `panoptes.cli` | ## 60秒快速入门 ``` git clone https://github.com/cleoanka/panoptes && cd panoptes python -m venv .venv && source .venv/bin/activate pip install -e ".[onnx,alpr]" # 无需摄像头，无需下载 — 通过完整 pipeline 的合成流量 # （使用内置的 mock detector；完全不需要 model weights）： panoptes demo # → 写入 results.json + annotated.mp4，您可以直接打开 ``` 然后选择一个检测器后端并运行服务器。有两个一级支持配置： ``` # ── Profile A · Flagship（YOLO26，最高准确率）───────────────────────── # ultralytics 是 AGPL-3.0（代码和 weights）— 请参阅 docs/LICENSING.md。 pip install -e ".[yolo,alpr]" panoptes serve -c examples/panoptes.yaml # config ships detector.backend: ultralytics # ── Profile B · License-clean（RF-DETR，Apache-2.0）───────────────────────── pip install -e ".[rfdetr,alpr]" # 在您的 config 中设置 detector.backend: rfdetr，model: rfdetr-medium，然后： panoptes serve -c examples/panoptes.yaml # → API 位于 :8080/api/v1，dashboard 位于 :8080/，metrics 位于 :8080/metrics ``` 更倾向于使用库？[`examples/quickstart.py`](examples/quickstart.py) 生成一段视频片段，在其上运行 pipeline 并打印事件（内置模拟 检测器——无需额外安装）。 ## 架构 ``` flowchart LR SRC["RTSP / files / webcams"] --> W subgraph W["StreamWorker (thread, one per stream)"] direction LR A["source"] --> B["governor"] --> C["(scheduler)"] --> D["tracker"] D --> E["motion / attributes / ALPR"] --> F["analytics"] F --> G["snapshots / annotator / metrics"] end W -- "detection batches" --> S["InferenceScheduler
micro-batching, owns the Detector"] S -- "futures" --> W W -- "events" --> BUS["EventBus
sync handlers + async queues"] BUS --> DB["storage
batched writer"] BUS --> API["FastAPI
WS + SSE + MJPEG + dashboard"] ``` 单一进程。仅在两处跨越线程/异步边界： `EventBus`（线程安全发布 → 异步订阅者）和 `InferenceScheduler`（工作线程阻塞在 futures 上）。完整契约详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 配置预览 一个 YAML 文件声明一切；每个字段都有环境变量覆盖 （`PANOPTES_SERVER__PORT=9000`）。完整示例：[examples/panoptes.yaml](examples/panoptes.yaml)。 ``` detector: backend: ultralytics # ultralytics | rfdetr | onnx | tensorrt | mock conf: 0.25 streams: - id: cam-north source: rtsp://user:pass@10.0.0.11:554/stream1 calibration: # 4+ image->ground point pairs (metres) image_points: [[412, 512], [988, 500], [1160, 820], [212, 843]] ground_points: [[0, 0], [7.2, 0], [7.2, 22.0], [0, 22.0]] speed: { limit_kmh: 90 } zones: - { id: shoulder, points: [[40, 620], [200, 600], [230, 860], [30, 870]], dwell_alert_s: 20 } rules: - id: truck-on-shoulder when: type: all_of conditions: - { type: zone_dwell, zone: shoulder, min_seconds: 20 } - { type: class_is, classes: [truck, bus] } actions: [{ type: snapshot }, { type: webhook, url: "https://ops.example.com/hook" }] ``` ## API 概览 | 方法 | 路径 | 用途 | |---|---|---| | GET | `/api/v1/system/health` | 存活状态（免鉴权） | | GET | `/api/v1/system/info` | 版本、后端、运行时间 | | GET | `/api/v1/system/config` | 配置转储，敏感信息已脱敏 | | GET | `/api/v1/streams` | 视频流状态，包含 fps、实时计数 | | POST | `/api/v1/streams/{id}/start` / `/stop` | 视频流控制 | | GET | `/api/v1/streams/{id}/preview.mjpeg` | 带标注的实时预览 | | GET | `/api/v1/streams/{id}/analytics` | 连线/区域计数器摘要 | | GET | `/api/v1/events` | 事件历史（支持过滤 + 分页） | | GET | `/api/v1/events/stream` | 实时事件 (SSE) | | WS | `/api/v1/events/ws` | 实时事件 (WebSocket) | | GET | `/api/v1/plates` | 车牌搜索 | | POST | `/api/v1/jobs/video` | 上传视频 → 后台任务 | | GET | `/api/v1/jobs/{id}` | 任务状态 / 进度 / 结果 | | GET | `/media/{path}` | 快照（需鉴权） | | GET | `/metrics` | Prometheus 暴露接口 | | GET | `/` | 仪表板 | 认证：`X-API-Key` 请求头（或在无法使用请求头时使用 `?api_key=`）。 包含请求/响应示例的完整参考：[docs/API.md](docs/API.md)。 ## 检测器后端与授权许可 | 后端 | 模型 | 速度/精度 | 许可证 | 商业用途 | |---|---|---|---|---| | `ultralytics` | YOLO26 n–x | 单位延迟下精度最高 | **AGPL-3.0**（涵盖代码*与*权重，包括微调版本） | 需要 Ultralytics 企业版许可证，或完全遵守 AGPL（包含网络条款） | | `rfdetr` | RF-DETR Nano–Large | 竞争力强，无 NMS | **Apache-2.0**（仅限 Nano–Large 权重） | 无限制——推荐用于闭源或商业化构建 | | `onnx` | 任何 YOLO 风格的 ONNX 导出模型 | 取决于模型 | onnxruntime: MIT；模型许可遵循其训练来源 | 需检查导出模型的来源 | | `tensorrt` | 预构建的 `.engine` | 在 NVIDIA 上最快 | TensorRT SDK: NVIDIA EULA；模型许可同上 | 引擎文件绑定特定 GPU 架构 | | `mock` | 合成数据 | — | Apache-2.0（内置） | 仅用于测试/演示 | 包含 ALPR 权重来源以及 PyAV/x264 陷阱的坦诚版本： [docs/LICENSING.md](docs/LICENSING.md)。 ## 文档 | 文档 | 内容 | |---|---| | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 系统设计与模块契约 | | [docs/API.md](docs/API.md) | 所有 endpoint，附带 JSON 示例 | | [docs/RULES.md](docs/RULES.md) | 规则 DSL 参考 + 8 个实用方案 | | [docs/CALIBRATION.md](docs/CALIBRATION.md) | 单应性校准，逐步指南 | | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Docker, Compose, Kubernetes, GPU, 扩展 | | [docs/PERFORMANCE.md](docs/PERFORMANCE.md) | 调节器、批处理、容量规划、调优 | | [docs/LICENSING.md](docs/LICENSING.md) | 逐层级的许可证分析 | | [docs/PRIVACY.md](docs/PRIVACY.md) | KVKK/GDPR：我们提供什么，您需要做什么 | | [training/EGITIM.md](training/EGITIM.md) | 模型训练指南（土耳其语 — Türkçe eğitim rehberi） | | [examples/rules-cookbook.yaml](examples/rules-cookbook.yaml) | 可作为加载配置的实用方案规则 | ## 项目结构 ``` panoptes/ ├── src/panoptes/ │ ├── core/ # types, config schema, events, geometry (no cv2/torch) │ ├── detect/ # detector backends: ultralytics, rfdetr, onnx, tensorrt, mock │ ├── track/ # clean-room ByteTrack (Kalman + two-stage association) │ ├── motion/ # homography, speed/heading/distance estimation │ ├── attributes/ # vehicle color, make/model hooks, evidence fusion │ ├── alpr/ # plate detect, OCR, validation/correction, voting │ ├── analytics/ # lines, zones, rules engine, actions, track lifecycle │ ├── pipeline/ # sources, governor, scheduler, workers, snapshots │ ├── storage/ # SQLAlchemy async models, repos, retention │ ├── api/ # FastAPI app, routes, SSE/WS, jobs, auth │ ├── observability/ # Prometheus metrics, structlog setup │ └── cli.py # Typer CLI ├── docs/ # the manual (see table above) ├── examples/ # panoptes.yaml, rules-cookbook.yaml, quickstart.py ├── training/ # dataset & fine-tuning guide (Turkish) ├── deploy/ # Docker, Compose, Kubernetes, weights manifest └── tests/ # unit + golden tests (base deps only) ``` ## 许可证 Panoptes 基于 **Apache License 2.0** 授权——详见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 可选的附加功能会引入受其各自许可证管辖的第三方软件；对于商业应用 至关重要的是 AGPL-3.0 的 `ultralytics` 后端、 RF-DETR 权重层级、车牌检测器权重来源以及 PyAV 捆绑的 GPL x264/x265。所有这些内容均在 [docs/LICENSING.md](docs/LICENSING.md) 中详细说明。 该文档属于工程尽职调查，不构成法律意见。

标签：AV绕过, CNCF毕业项目, Docker, FastAPI, YOLO, 交通监控, 子域名突变, 安全防御评估, 自定义请求头, 计算机视觉, 请求拦截, 车牌识别, 车辆检测, 逆向工具