# YOLO Object Detection Processor 技术检讨报告

## 检讨日期
2026-04-28 02:00

---

## 一、版本概览

| 版本 | 脚本 | 技术栈 | 文件大小 | 状态 |
|------|------|--------|---------|------|
| **A** | yolo_processor.py | YOLOv8 (ultralytics) CPU | 14 KB | ✅ 默认使用 |
| **B** | yolo_processor_mps.py | YOLOv8 + Metal GPU (MPS) | 11 KB | ✅ MPS加速 |
| **C** | yolo_processor_contract_v1.py | YOLOv8 + Contract v1.0 | 23 KB | ✅ 标准化部署 |

---

## 二、Rust 配置

```rust
// src/worker/processor.rs Line 429-430
let script_path = std::env::var("MOMENTRY_YOLO_SCRIPT")
    .unwrap_or_else(|_| format!("{}/yolo_processor.py", SCRIPTS_DIR.as_str()));
```

**默认使用**: yolo_processor.py ✅

---

## 三、技术栈分析

### 1. yolo_processor.py（默认版本）

#### 技术栈

| 项目 | 内容 |
|------|------|
| **引擎** | ultralytics YOLOv8 |
| **模型** | yolov8n.pt（默认nano） |
| **设备** | CPU |
| **Resume** | ✅ 已支持 |
| **类别数** | 80类（COCO数据集） |
| **功能** | 物体检测 + 轨迹跟踪 |

#### 关键特性

| 特性 | 支持 |
|------|------|
| **Resume断点续传** | ✅ 已实现（Line 124-140） |
| **Ctrl+C暂停保存** | ✅ 已实现（Line 169-186） |
| **自动保存** | ✅ 定期保存（默认30秒） |
| **Redis进度报告** | ✅ 支持 |

#### Resume 实现

```python
# yolo_processor.py Line 124-140
def load_existing_data(output_file: str) -> tuple[Optional[Dict], int]:
    """Load existing detection data. Returns (data, last_processed_frame)"""
    if not os.path.exists(output_file):
        return None, 0
    
    frames = data.get("frames", {})
    if frames:
        last_frame = max(int(k) for k in frames.keys())
        return data, last_frame  # ✅ Resume起点
```

---

### 2. yolo_processor_mps.py（MPS版本）

#### 技术栈

| 项目 | 内容 |
|------|------|
| **引擎** | ultralytics YOLOv8 |
| **模型** | yolov8n.pt（默认nano） |
| **设备** | MPS（Metal GPU）⭐⭐⭐ |
| **Resume** | ✅ 支持 |
| **类别数** | 80类（COCO数据集） |
| **Batch处理** | ✅ 支持（batch_size=8） |

#### MPS加速验证

```python
# yolo_processor_mps.py Line 110-117
def get_device() -> str:
    """Determine the best available device"""
    if torch.backends.mps.is_available():
        return "mps"  # ✅ Apple Silicon Metal GPU
    elif torch.cuda.is_available():
        return "cuda"
    else:
        return "cpu"
```

#### MPS支持确认

```python
# Line 172-173
if device in ["mps", "cuda"]:
    model.to(device)  # ✅ 移动模型到GPU
```

---

### 3. yolo_processor_contract_v1.py（Contract版本）

#### 技术栈

| 项目 | 内容 |
|------|------|
| **引擎** | ultralytics YOLOv8 |
| **模型** | yolov8n.pt（默认） |
| **设备** | CPU/GPU（可选） |
| **Resume** | ✅ 支持 |
| **Contract** | ✅ Processor Contract v1.0 |
| **类别数** | 80类（COCO数据集） |

#### Contract规范特性

```python
# yolo_processor_contract_v1.py Line 44-51
CONTRACT_VERSION = "1.0"
PROCESSOR_VERSION = "1.0.0"
MODEL_NAME = "yolov8n.pt"
MODEL_VERSION = "8.0"
```

#### 标准化功能

| 功能 | 支持 |
|------|------|
| **健康检查** | ✅ `--check-health` |
| **资源监控** | ✅ |
| **信号处理** | ✅ SIGTERM/SIGINT |
| **Redis进度** | ✅ |
| **标准化输出** | ✅ Contract规范 |

---

## 四、功能对比

### 功能矩阵

| 功能 | yolo_processor.py | yolo_processor_mps.py | yolo_processor_contract_v1.py |
|------|------------------|---------------------|----------------------------|
| **物体检测** | ✅ | ✅ | ✅ |
| **轨迹跟踪** | ✅ | ✅ | ✅ |
| **80类COCO** | ✅ | ✅ | ✅ |
| **Metal GPU加速** | ❌ | ✅ MPS ⭐⭐⭐ | ❌（可选GPU） |
| **Resume断点续传** | ✅ ⭐⭐⭐ | ✅ | ✅ |
| **Ctrl+C暂停** | ✅ ⭐⭐⭐ | ✅ | ✅ |
| **Batch处理** | ❌ | ✅ ⭐⭐ | ❌ |
| **Contract规范** | ❌ | ❌ | ✅ ⭐⭐⭐ |
| **Redis进度** | ✅ | ❌ | ✅ ⭐⭐⭐ |
| **健康检查** | ❌ | ❌ | ✅ ⭐⭐⭐ |

---

### Resume支持状态（文档确认）

```
// docs_v1.0/PROCESSORS/_CORE/PROCESSOR_UPGRADE_ANALYSIS.md Line 82
| yolo_processor.py | 已支持 Resume ✅ | ❌ 不需要升级 |
```

---

## 五、模型规格

### YOLOv8 模型对比

| 模型 | 参数量 | 输入尺寸 | 速度 | 精度 | 适用场景 |
|------|--------|---------|------|------|---------|
| **yolov8n**（nano） | 3.2M | 640 | **最快** ⭐⭐⭐ | 较低 | 实时检测 |
| yolov8s（small） | 11.2M | 640 | 快 ⭐⭐ | 中等 | 平衡方案 |
| yolov8m（medium） | 25.9M | 640 | 中等 | 高 ⭐⭐ | 精度优先 |
| yolov8l（large） | 43.7M | 640 | 慢 | 很高 ⭐⭐⭐ | 最高精度 |
| yolov8x（extra） | 68.2M | 640 | 最慢 ⚠️ | 最高 ⭐⭐⭐ | 研究用途 |

---

### 当前默认模型

| 版本 | 默认模型 | 模型大小 | 配置位置 |
|------|---------|---------|---------|
| yolo_processor.py | yolov8n | 6.2 MB | ultralytics自动下载 |
| yolo_processor_mps.py | yolov8n | 6.2 MB | Line 129: model_name="yolov8n" |
| yolo_processor_contract_v1.py | yolov8n | 6.2 MB | Line 155: MOMENTRY_YOLO_MODEL_SIZE |

---

### COCO 80类别列表（部分）

```
常见类别:
- person（人）⭐⭐⭐
- car, truck, bus, motorcycle（交通工具）
- bicycle（自行车）
- dog, cat, bird（动物）
- chair, sofa, bed（家具）
- laptop, cell phone, tv（电子设备）
- bottle, cup, wine glass（饮料容器）
- book, clock（日用品）
```

---

## 六、输出格式对比

### yolo_processor.py 输出格式

```json
{
  "metadata": {
    "video_path": "...",
    "fps": 29.97,
    "total_frames": 4825,
    "status": "completed",
    "detection_method": "YOLOv8",
    "last_saved_frame": 4825
  },
  "frames": {
    "750": {
      "frame_number": 750,
      "time_seconds": 24.99,
      "detections": [
        {
          "class_id": 0,
          "class_name": "person",
          "confidence": 0.85,
          "bbox": [x1, y1, x2, y2],
          "track_id": 1  // ⭐⭐ 轨迹ID
        }
      ]
    }
  }
}
```

---

### yolo_processor_mps.py 输出格式

```json
{
  "video_path": "...",
  "model": "yolov8n",
  "device": "mps",
  "processed_at": "2026-04-28T...",
  "frames": {
    "750": {
      "timestamp": 24.99,
      "detections": [
        {
          "class_id": 0,
          "class_name": "person",
          "confidence": 0.85,
          "bbox": [x, y, w, h]
        }
      ]
    }
  },
  "summary": {
    "total_frames": 4825,
    "total_detections": 1234,
    "processing_time": 10.5
  }
}
```

---

## 七、性能预期对比

### CPU vs MPS 性能差异

| 对比项 | CPU版本 | MPS版本（预期）| 差异 |
|--------|---------|--------------|------|
| **速度** | 基准 | **2-5倍快** ⭐⭐⭐ | MPS加速 |
| **内存** | 系统内存 | **统一内存** ⭐⭐ | Apple Silicon优化 |
| **Batch处理** | 单帧 | **多帧并行** ⭐⭐ | batch_size=8 |

---

### 模型大小影响

| 模型 | CPU速度 | MPS速度（预期）| 精度 |
|------|---------|--------------|------|
| yolov8n | 最快 ⭐⭐⭐ | **极快** ⭐⭐⭐⭐⭐ | 较低 |
| yolov8s | 快 ⭐⭐ | **快** ⭐⭐⭐⭐ | 中等 |
| yolov8m | 中等 | 中等 ⭐⭐⭐ | 高 ⭐⭐ |

---

## 八、场景推荐

### 推荐矩阵

| 场景 | 推荐版本 | 理由 |
|------|---------|------|
| **生产环境（默认）** | yolo_processor.py ⭐⭐⭐⭐⭐ | Resume已支持，稳定可靠 |
| **Metal GPU加速** | yolo_processor_mps.py ⭐⭐⭐⭐⭐ | MPS加速 + Batch处理 |
| **标准化部署** | yolo_processor_contract_v1.py ⭐⭐⭐⭐⭐ | Contract规范 |
| **实时检测** | yolo_processor_mps.py + yolov8n ⭐⭐⭐⭐⭐ | 最快速度 |

---

### 模型选择建议

| 需求 | 推荐模型 | 理由 |
|------|---------|------|
| **实时检测** | yolov8n ⭐⭐⭐⭐⭐ | 最快速度 |
| **精度平衡** | yolov8s ⭐⭐⭐⭐ | 速度+精度平衡 |
| **精度优先** | yolov8m ⭐⭐⭐⭐ | 较高精度 |

---

## 九、关键发现

### Resume支持已确认 ✅

```
文档确认: yolo_processor.py 已支持 Resume ✅
实现位置: Line 124-186
功能: 
  - 加载已存在数据
  - 断点续传
  - Ctrl+C暂停保存
  - 定期自动保存
```

---

### MPS版本支持 Metal GPU ✅

```
实现: torch.backends.mps.is_available()
设备: Apple Silicon Metal GPU
Batch: batch_size=8（多帧并行）
优势: 
  - 2-5倍速度提升（预期）
  - 统一内存优化
```

---

### Contract版本标准化 ✅

```
Contract: Processor Contract v1.0
功能:
  - 健康检查
  - 资源监控
  - 信号处理
  - Redis进度报告
  - 标准化输出
```

---

## 十、与 Face Processor 对比

### 关键差异

| 对比项 | YOLO | Face |
|--------|------|------|
| **检测对象** | 80类物体 | 人脸 |
| **Embedding** | ❌ 无 | ✅ InsightFace有512维 |
| **轨迹跟踪** | ✅ track_id ⭐⭐⭐ | ❌ 无 |
| **Resume** | ✅ 已支持 | ✅ InsightFace已支持 |
| **MPS支持** | ✅ yolo_processor_mps.py | ✅ face_processor_mps.py |
| **用途** | 物体检测/计数 | 人脸聚类/身份识别 |

---

### 功能对比矩阵

| 功能 | YOLO | Face (InsightFace) |
|------|------|-------------------|
| **检测** | ✅ 80类 | ✅ 人脸 |
| **Embedding** | ❌ | ✅ 512维 ⭐⭐⭐ |
| **轨迹跟踪** | ✅ track_id ⭐⭐⭐ | ❌ |
| **Age/Gender** | ❌ | ✅ ⭐⭐ |
| **Landmarks** | ❌ | ✅ 5点 ⭐⭐ |
| **Resume** | ✅ | ✅ |
| **MPS** | ✅ | ✅ |

---

## 十一、总结与建议

### 当前状态

| 项目 | 状态 |
|------|------|
| **Rust默认配置** | ✅ yolo_processor.py |
| **Resume支持** | ✅ 已实现 |
| **MPS版本** | ✅ 已实现（Metal GPU） |
| **Contract版本** | ✅ 已实现（标准化） |
| **默认模型** | yolov8n（nano） |

---

### 推荐方案

| 场景 | 推荐 | 优先级 |
|------|------|--------|
| **生产环境** | yolo_processor.py ⭐⭐⭐⭐⭐ | ✅ 当前默认 |
| **速度优化** | yolo_processor_mps.py ⭐⭐⭐⭐⭐ | 🟡 可选 |
| **标准化** | yolo_processor_contract_v1.py ⭐⭐⭐⭐⭐ | 🟡 可选 |

---

### 关键结论

| 结论 | 说明 |
|------|------|
| ✅ **YOLO Resume已支持** | 无需修复，已稳定 |
| ✅ **MPS版本可用** | Metal GPU加速已实现 |
| ✅ **功能完整** | 检测 + 轨迹跟踪 + Resume |
| ⚠️ **无Embedding** | 与Face不同，YOLO无向量输出 |

---

**检讨完成日期**: 2026-04-28 02:00  
**状态**: ✅ YOLO Processor 已完善，无需修复  
**建议**: 保持当前配置（yolo_processor.py）或根据需求切换到MPS版本
