docs: update docs_v1.0/ documentation

- Fix markdown lint issues (MD030, MD047, MD051, MD028, MD005) - Update AI agents, architecture, implementation docs - Add new identity, face recognition, and API documentation - Remove deprecated face/person API guides
2026-04-30 15:10:41 +08:00
parent 8f05a7c188
commit 4d75b2e251
185 changed files with 21071 additions and 1605 deletions
@@ -287,4 +287,4 @@ MOMENTRY_POSE_MAX_PERSONS=10
 1. [AI-Driven Processor Contract](../REFERENCE/AI_DRIVEN_PROCESSOR_CONTRACT.md)
 2. [Processor Standardization Template](../REFERENCE/PROCESSOR_STANDARDIZATION_TEMPLATE.md)
 3. [ASR Configuration Unification](../REFERENCE/ASR_CONFIGURATION_UNIFICATION.md)
-4. [AGENTS.md](../../AGENTS.md) - Updated configuration documentation
+4. [AGENTS.md](../../AGENTS.md) - Updated configuration documentation
@@ -385,7 +385,7 @@ refrigerator, book, clock, vase, scissors, teddy bear, hair drier, toothbrush
 ```sql
 -- 存储到 MongoDB (非结构化数据)
 db.yolo_frames.insertOne({
-    uuid: "384b0ff44aaaa1f1",
+    uuid: "384b0ff44aaaa1f14cb2cd63b3fea966",
    frame_number: 0,
    objects: [...]
 })
@@ -1162,4 +1162,4 @@ CREATE TABLE person_appearances (
 ---

 **维护者**: OpenCode
-**最后更新**: 2026-04-09
+**最后更新**: 2026-04-09
@@ -454,4 +454,4 @@ python3 -c "import torch; print(torch.__version__)"
 # MPS支持
 python3 -c "import torch; print(torch.backends.mps.is_available())"
 # True
-```
+```
@@ -1,6 +1,6 @@
 # Momentry Core Processors 快速参考

-**更新日期**: 2026-04-09
+**更新日期**: 2026-04-28

 ---

@@ -13,16 +13,18 @@
 | 3 | **CUT** | 场景检测 | ✅ 100% | ✅ | ✅ | ✅ | ✅ | PySceneDetect |
 | 4 | **YOLO** | 物体检测 | ✅ 100% | ✅ | ✅ | ✅ | ✅ | YOLOv8 |
 | 5 | **OCR** | 文字识别 | ✅ 100% | ✅ | ✅ | ✅ | ✅ | PaddleOCR |
-| 6 | **Face** | 人脸检测 | ✅ 100% | ✅ | ✅ | ✅ | ✅ | RetinaFace |
+| 6 | **Face** | 人脸检测 | ✅ 100% | ✅ | ✅ | ✅ | ✅ | InsightFace ⭐ |
 | 7 | **Pose** | 姿态估计 | ✅ 100% | ✅ | ✅ | ✅ | ✅ | MediaPipe |
-| 8 | **Scene** | 场景分类 | ✅ 100% | ✅ | ✅ | ✅ | ⚠️ | **MIT Places365** |
+| 8 | **Scene** | 场景分类 | ✅ 100% | ✅ | ✅ | ✅ | ✅ | **MIT Places365** ⭐ |
 | 9 | **Caption** | 字幕生成 | ✅ 100% | ✅ | ✅ | ✅ | ⚠️ | GPT-4V (付费) |
 | 10 | **Story** | 故事生成 | ✅ 100% | ✅ | ✅ | ✅ | ⚠️ | GPT-4 (付费) |

 **统计**:
- ✅ 完成: 9/10 (90%)
+- ✅ 完成: 8/10 (80%)
 - ⚠️ 修复中: 1/10 (10%)
+- ⚠️ 待数据库: 2/10 (20%)
 - 💰 付费 API: 2/10 (Caption, Story)
+- ⭐ Benchmark完成: 4/10 (Face, YOLO, CUT, Scene)

 ---

@@ -34,7 +36,7 @@
 python3 scripts/asr_processor.py video.mp4 output.json

 # API
-curl http://localhost:3002/api/v1/asr/384b0ff44aaaa1f1
+curl http://localhost:3002/api/v1/asr/384b0ff44aaaa1f14cb2cd63b3fea966

 # 示例
 ExaSAN: 78 segments, 15KB
@@ -47,7 +49,7 @@ Charade: 1826 segments, 198KB
 python3 scripts/asrx_processor_custom.py video.mp4 output.json

 # API
-curl http://localhost:3002/api/v1/asrx/384b0ff44aaaa1f1
+curl http://localhost:3002/api/v1/asrx/384b0ff44aaaa1f14cb2cd63b3fea966

 # 测试结果
 Charade: 1118 segments, 8 speakers, 99.82% match rate
@@ -63,7 +65,7 @@ Charade: 1118 segments, 8 speakers, 99.82% match rate
 python3 scripts/cut_processor.py video.mp4 output.json

 # API
-curl http://localhost:3002/api/v1/cut/384b0ff44aaaa1f1
+curl http://localhost:3002/api/v1/cut/384b0ff44aaaa1f14cb2cd63b3fea966

 # 示例
 Charade: 1331 scenes, 217KB
@@ -76,7 +78,7 @@ ExaSAN: 18 scenes, 2KB
 python3 scripts/yolo_processor.py video.mp4 output.json

 # API
-curl http://localhost:3002/api/v1/yolo/384b0ff44aaaa1f1
+curl http://localhost:3002/api/v1/yolo/384b0ff44aaaa1f14cb2cd63b3fea966

 # 示例
 Charade: 127MB, 15234 objects, 80 classes
@@ -232,11 +234,17 @@ cargo run -- process video.mp4 --modules asr --force
 ## 待办事项

 ### 高优先级
+- [x] Scene: 添加数据库存储 ✅ (2026-04-28)
 - [ ] ASRX: 切换到自定义 SpeechBrain 实现
- [ ] Scene: 添加数据库存储
 - [ ] Caption: 添加数据库存储
 - [ ] Story: 添加数据库存储

+### 已完成 (2026-04-28)
+- [x] **Scene Processor**: ProcessorType + store_scene_pre_chunks_batch + Benchmark测试
+- [x] **CUT Processor**: PySceneDetect Benchmark测试 (2.54秒, 19场景)
+- [x] **YOLO Processor**: CPU版本 Benchmark测试 (111.81秒, 8486物体, 26类)
+- [x] **Face Processor**: InsightFace Benchmark测试 (7.04秒, 112人脸, 100%检测率) ⭐
+
 ### 中优先级
 - [ ] 统一 API 错误处理
 - [ ] 添加批量处理接口
@@ -244,4 +252,4 @@ cargo run -- process video.mp4 --modules asr --force

 ---

-**详细文档**: `docs/PROCESSOR_IMPLEMENTATION_STATUS.md`
+**详细文档**: `docs/PROCESSOR_IMPLEMENTATION_STATUS.md`
@@ -0,0 +1,430 @@
+# 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版本