目标检测器

目标检测器负责运行 AI 模型并返回类别、置信度和边界框。视频硬件解码与目标检测是两条不同的硬件链路：Intel/NVIDIA GPU 可能只用于 FFmpeg 解码，而 Coral、OpenVINO、ONNX、TensorRT 等负责模型推理。

选择建议

Detector	适合	注意
Coral EdgeTPU	低功耗、多摄像头、成熟稳定	模型必须是 EdgeTPU 编译模型
OpenVINO	Intel CPU/iGPU/NPU	模型输入格式、labelmap 必须匹配
ONNX	自定义 YOLO、跨硬件	输入布局/颜色/dtype 要与导出模型一致
TensorRT	NVIDIA GPU 高性能	镜像、CUDA/驱动版本需匹配
Hailo/RKNN	特定加速器/SoC	按对应硬件和模型格式部署

最重要的匹配项

width / height：模型真正输入尺寸，不是摄像头分辨率。
input_tensor：nhwc 或 nchw。
input_pixel_format：rgb 或 bgr。
input_dtype：int/uint8/float 等必须与模型一致。
labelmap：类别 ID 顺序必须与模型训练/导出时一致。

ONNX 示例

detectors:
  onnx:
    type: onnx

model:
  model_type: yolo-generic
  width: 640
  height: 640
  input_tensor: nchw
  input_pixel_format: rgb
  input_dtype: float
  path: /config/model_cache/securex_custom_yolo.onnx
  labelmap_path: /config/model_cache/securex_custom_yolo_labels.txt

性能判断

不要只看“GPU 使用率”。应同时看 detector inference time、每台摄像头 detect FPS、跳帧、CPU/GPU/TPU 状态。如果模型推理速度慢于所有摄像头合计送帧速度，系统会积压。

常见错误

模型能加载但所有类别错位：通常是 labelmap 不匹配。
尺寸报错：width/height 或 tensor layout 与模型不一致。
ONNX 只跑 CPU：检查所用镜像/运行时是否包含对应 Intel/NVIDIA/ROCm provider。
Coral 找不到设备：先在宿主机确认 PCIe/USB 枚举，再检查容器设备映射。

Object detectors

An object detector runs the AI model and returns labels, confidence scores, and bounding boxes. Video decode acceleration and AI inference are separate paths: a GPU may decode FFmpeg while Coral, OpenVINO, ONNX, or TensorRT performs inference.

Choosing a detector

Detector	Good fit	Key requirement
Coral EdgeTPU	Low power, many cameras	EdgeTPU-compiled model
OpenVINO	Intel CPU/iGPU/NPU	Correct model/label metadata
ONNX	Custom YOLO and portable runtimes	Input layout/color/dtype must match export
TensorRT	NVIDIA GPU	Compatible image, CUDA, and driver
Hailo/RKNN	Dedicated accelerators/SoCs	Hardware-specific model format

Model fields that must match

width / height:actual model input size.
input_tensor:NHWC or NCHW.
input_pixel_format:RGB or BGR.
input_dtype:integer/uint8/float exactly as exported.
labelmap:class ID order must match the trained model.

ONNX example

detectors:
  onnx:
    type: onnx
model:
  model_type: yolo-generic
  width: 640
  height: 640
  input_tensor: nchw
  input_pixel_format: rgb
  input_dtype: float
  path: /config/model_cache/securex_custom_yolo.onnx
  labelmap_path: /config/model_cache/securex_custom_yolo_labels.txt

Performance

Do not judge by GPU percentage alone. Compare inference time, aggregate camera detect FPS, skipped frames, and CPU/GPU/TPU telemetry. If inference throughput is below incoming detect frames, a backlog will form.

Common failures

Wrong classes with a loading model → label map mismatch.
Shape errors → wrong width/height or tensor layout.
ONNX unexpectedly on CPU → runtime/image lacks the intended hardware provider.
Coral missing → verify host enumeration, then container device mapping.

Detectores de objetos

El detector ejecuta el modelo de IA y devuelve clases, confianza y cajas. La decodificación de vídeo y la inferencia son rutas distintas: una GPU puede decodificar FFmpeg mientras Coral, OpenVINO, ONNX o TensorRT ejecutan el modelo.

Elección

Detector	Uso	Requisito
Coral	Bajo consumo y muchas cámaras	Modelo compilado para EdgeTPU
OpenVINO	Intel CPU/iGPU/NPU	Metadatos/modelo correctos
ONNX	YOLO personalizado	Layout/color/dtype correctos
TensorRT	NVIDIA	Imagen, CUDA y driver compatibles
Hailo/RKNN	Aceleradores específicos	Formato de modelo específico

Campos críticos

width/height del modelo.
input_tensor NHWC/NCHW.
RGB/BGR.
dtype.
orden de labelmap.

Ejemplo ONNX

detectors:
  onnx:
    type: onnx
model:
  model_type: yolo-generic
  width: 640
  height: 640
  input_tensor: nchw
  input_pixel_format: rgb
  input_dtype: float
  path: /config/model_cache/securex_custom_yolo.onnx
  labelmap_path: /config/model_cache/securex_custom_yolo_labels.txt

Rendimiento

No mire solo el porcentaje de GPU. Compare tiempo de inferencia, FPS de detección, frames omitidos y telemetría.

Fallos comunes

Clases incorrectas → labelmap.
Error de shape → tamaño/layout.
ONNX en CPU → falta provider adecuado.
Coral no encontrado → revise host y mapeo al contenedor.