---
document_type: "spec"
service: "MOMENTRY_CORE"
title: "YOLO Processor V1.0.0"
date: "2026-05-02"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
parent: "PROCESSOR_SELECTION_V1.0.0.md"
tags:
  - "momentry"
  - "core"
  - "processor"
  - "yolo"
  - "object-detection"
  - "yolov8"
  - "v1.0.0"
ai_query_hints:
  - "YOLO 使用 yolov8n (nano) 模型進行物件偵測"
  - "YOLO 在 M4 Mac Mini 上可達 100~200 FPS"
  - "YOLO 支援 GPU 加速（MPS），可快 2~5 倍"
  - "YOLO 輸出 4.3 MB 含偵測結果"
  - "YOLO 是 VisualChunk 和 Scene 的依賴"
related_documents:
  - "PROCESSOR_SELECTION_V1.0.0.md"
  - "../VISUAL_CHUNK_V1.0.0.md"
  - "../POSE_V1.0.0.md"
  - "../OCR_V1.0.0.md"
  - "../CHUNK_DEFINITION_V1.0.0.md"
---

# YOLO Processor V1.0.0

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-05-02 |
| 文件版本 | V1.0 |

**狀態**: ✅ 100% | **模型**: YOLOv8n (nano) | **GPU**: 是

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| YOLO | You Only Look Once，即時物件偵測演算法 |
| YOLOv8n | Ultralytics YOLO 第八代 nano 版本，最小最快 |
| object detection | 物件偵測，辨識影像中的物體類別與位置 |
| MPS | Metal Performance Shaders，Apple Silicon GPU 加速 |
| bottleneck | 處理瓶頸，YOLO 與 Pose 同為最耗時的 processor |

---

## 選型過程

| 模型 | 參數 | 大小 | 速度 | 精度 |
|------|------|------|------|------|
| **yolov8n (nano)** | **3.2M** | **6.2MB** | **最快** | **較低** |
| yolov8s (small) | 11.2M | - | 快 | 中等 |
| yolov8m (medium) | 25.9M | - | 中 | 高 |
| yolov8l (large) | 43.7M | - | 慢 | 很高 |
| yolov8x (x-large) | 68.2M | - | 最慢 | 最高 |

**決策**: 預設使用 `yolov8n.pt`（nano），在 M4 Mac Mini 上可達 100~200 FPS。可透過配置檔切換至更大模型。

---

## 效能實測（ExaSAN 159.6s 影片, 全幀處理）

| 指標 | 值 |
|------|-----|
| 處理時間 | 65.72s |
| 即時倍率 | 2.4x（瓶頸之一） |
| 輸出 | 4.3 MB |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |

## 資源預估

| 資源 | 值 |
|------|-----|
| CPU | 0.3 |
| 記憶體 | 1024 MB |
| GPU | 支援（`yolo_processor_mps.py` 可使用 MPS，快 2~5 倍） |
| 依賴 | 無 |

---

## Apple Vision Framework 替代評估

### POC 目標

評估 Apple Vision Framework 是否可取代 YOLOv8n 進行物件偵測，目標是利用 ANE 加速降低記憶體與處理時間。

### 測試結果

測試影像：展場人物場景（640x360）、人物訪談場景（1920x1080）

| Vision 功能 | 測試結果 | YOLOv8n 對應 | 可取代 |
|------------|---------|-------------|--------|
| **VNClassifyImageRequest** | `people:0.94`, `adult:0.94`, `sign:0.40` | 場景分類（目前用 Places365） | ✅ **可取代 Scene processor** |
| **VNDetectHumanRectanglesRequest** | 2 persons, conf=0.68~0.76 | YOLO 'person' 類別 | ✅ **可取代 person 檢測** |
| **VNDetectHumanBodyPoseRequest** | 19 joints (neck, shoulders, wrists) | MediaPipe Pose | ✅ **可取代 Pose processor** |
| **VNDetectHumanHandPoseRequest** | 1 hand, conf=1.0 | 無對應 | ✅ 新功能 |
| **VNGenerateObjectnessBasedSaliency** | 1 region, 無 class label | 無對應 | ⚠️ 僅顯著性區域 |
| **一般物件偵測 (car/dog/bottle/chair...)** | ❌ **無此 API** | YOLO 80 COCO 類別 | ❌ **無法取代** |

### 關鍵限制

Vision Framework **沒有通用物件偵測器**。YOLOv8n 可偵測 80 個 COCO 類別（person, car, dog, bottle, chair, tv 等），Vision Framework 僅能偵測「人物」相關（人體、姿勢、手勢）和場景分類，無法辨識具體物體類別。

### 選型結論

| 用途 | 方案 |
|------|------|
| **人物偵測** | Vision Framework **可取代**（更快、更輕量） |
| **一般物件偵測（car/dog/bottle）** | YOLOv8n **維持現狀**（Vision Framework 無法取代） |
| **場景分類** | Vision Framework **可取代** MIT Places365 |
| **姿態估計** | Vision Framework **可取代** MediaPipe Pose |

若僅需 person 類別，Vision Framework 可完全取代 YOLO。但若需要其他 79 個 COCO 類別，YOLOv8n 仍是必要方案。

### 相關檔案

```
scripts/swift_processors/vision_object_test.swift
```

---

## CoreML 加速實驗

### 動機

YOLOv8n 使用 PyTorch CPU 推論（67ms/frame）且 **AGPL-3.0 License 有商用限制**。改用 YOLOv5n（**Apache 2.0**）+ CoreML 轉換，可同時解決 License 和效能問題。

### 測試結果

| 引擎 | License | Per frame | 加速比 | ANE |
|------|---------|-----------|--------|-----|
| **YOLOv8 PyTorch CPU** | AGPL-3.0 | 67ms | 1x | ❌ |
| **YOLOv8 CoreML** | AGPL-3.0 | 13ms | 5.3x | ✅ |
| **YOLOv5 PyTorch CPU** | **Apache 2.0** | 59ms | 1x | ❌ |
| **YOLOv5 CoreML** ⭐ | **Apache 2.0** | **13ms** | **4.5x** | ✅ |

**決定**: 以 YOLOv5 CoreML（`yolov5nu.mlpackage`）取代 YOLOv8。

### 實作

`yolo_processor.py` 模型載入順序：
1. `yolov5nu.mlpackage`（CoreML, ANE）→ 優先使用
2. `yolov5nu.pt`（PyTorch CPU）→ fallback
3. 自動下載（若無本地檔案）

### 相關檔案

```
yolov5nu.mlpackage  # CoreML model (5.2MB, Apache 2.0)
yolov5nu.pt         # PyTorch weights (5.3MB, Apache 2.0)
scripts/yolo_processor.py
```

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
| V1.1 | 2026-05-04 | 以 YOLOv5 CoreML (Apache 2.0) 取代 YOLOv8 (AGPL) + Vision Framework 評估 | OpenCode | deepseek-chat |
| V1.1 | 2026-05-04 | 新增 Apple Vision Framework 替代評估記錄 | OpenCode | deepseek-chat |
