---
document_type: "spec"
service: "MOMENTRY_CORE"
title: "Face Embedding 產出流程 V2.0.0"
date: "2026-05-04"
version: "V2.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "core"
  - "face"
  - "embedding"
  - "pgvector"
  - "qdrant"
  - "v2.0.0"
ai_query_hints:
  - "Face Embedding 的完整處理流程（Vision detection → CoreML FaceNet → pgvector + Qdrant）"
  - "V2.0 使用 Apple Vision Framework 取代 InsightFace detection"
  - "V2.0 使用 CoreML FaceNet (MIT) 產出 512-D embedding"
  - "Face processor 的輸出結構與 embedding 欄位說明"
  - "Qdrant face collection 的 payload 結構與點位 ID 規則"
  - "Face embedding 使用 Cosine 距離計算"
  - "Face detection 使用 ANE（Apple Vision Framework），embedding 使用 ANE（CoreML FaceNet）"
  - "face_detections 表與 Qdrant 的資料同步方式"
related_documents:
  - "../VECTOR_SPEC_V1.0.0.md"
  - "../PROCESSORS/FACE_V1.0.0.md"
  - "../PROCESSOR_SELECTION_V1.0.0.md"
  - "../CHUNK_DEFINITION_V1.0.0.md"
  - "../MOMENTRY_CORE_API_V1.0.0.md"
---

# Face Embedding 產出流程 V2.0.0

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

## V2.0 變更摘要

| 項目 | V1.x | V2.0 |
|------|------|------|
| **Detection** | InsightFace SCRFD-10G (CPU, 450%) | **Apple Vision VNDetectFaceRectangles** (ANE, ~0%) |
| **Pose** | InsightFace 2D landmarks → angle | **Apple Vision VNDetectFaceLandmarks** (roll/yaw/pitch) |
| **Embedding** | CoreML FaceNet 512-D (ANE) | 同左，MIT license |
| **CPU usage** | 450%+ | **~0%** |
| **Script** | `face_processor.py` | **`face_processor_vision.py` + `swift_face`** |

## 處理流程

```
1. swift_face (Vision/ANE)
   ├── AVAssetReader 逐幀讀取
   ├── VNDetectFaceRectanglesRequest  → bbox (x, y, w, h) + confidence
   ├── VNDetectFaceLandmarksRequest   → roll, yaw, pitch
   └── 輸出: {uuid}_detect.json

2. face_processor_vision.py
   ├── 讀取 detect.json
   ├── cv2 逐幀 crop face by bbox
   ├── CoreML FaceNet → 512-D embedding (ANE)
   ├── classify_pose(roll, yaw) → frontal/three_quarter/profile
   └── 輸出: {uuid}.face.json (FaceResult format)

3. Rust pipeline (job_worker.rs)
   ├── 讀取 face.json → FaceResult struct
   ├── store_face_chunks() → pre_chunks table
   └── store_face_embeddings_to_qdrant() → Qdrant

4. Post-Face (job_worker.rs)
   ├── store_traced_faces.py
   │   ├── face_tracker.py (IoU + embedding) → trace_id
   │   └── INSERT face_detections (trace_id + bbox + embedding pgvector)
   ├── sync_face_embeddings() → Qdrant face points
   └── cluster_face_embeddings() / search_similar_faces() → pgvector query
```

## 輸出結構

### face.json (FaceResult)

```json
{
  "frame_count": 6872,
  "fps": 59.94,
  "frames": [
    {
      "frame": 30,
      "timestamp": 0.5,
      "faces": [
        {
          "x": 917, "y": 125, "width": 181, "height": 250,
          "confidence": 0.88,
          "embedding": [0.01, -0.04, 0.12, ...],  // 512-D
          "pose_angle": {"angle": "frontal", "roll": 2.5, "yaw": -5.0, "pitch": 1.2},
          "landmarks": null,
          "attributes": null
        }
      ]
    }
  ]
}
```

### face_detections (PostgreSQL + pgvector)

| 欄位 | 型別 | 說明 |
|------|------|------|
| `file_uuid` | VARCHAR | 來源影片 |
| `frame_number` | BIGINT | 幀編號 |
| `trace_id` | INTEGER | 跨幀追蹤 ID（face_tracker 分配） |
| `bbox` | JSONB | `{"x", "y", "width", "height"}` |
| `confidence` | DOUBLE | 檢測信心度 |
| `embedding` | VECTOR(512) | pgvector index (ivfflat, cosine) |
| `identity_id` | BIGINT | 綁定的 identity（可為 NULL） |

### Qdrant Payload (momentry_dev/dev collection)

```json
{
  "file_uuid": "1a04db97...",
  "trace_id": 0,
  "frame_number": 825,
  "type": "face_embedding"
}
```

## Vector 規格

| 屬性 | 值 |
|------|-----|
| 模型 | CoreML FaceNet (InceptionResnetV1, VGGFace2) |
| License | MIT |
| 維度 | 512 |
| 距離 | Cosine |
| Index | pgvector ivfflat (lists=100) |
| Qdrant | Cosine distance, shared collection |

## 來源 Processor 資源預估

| 資源 | V1.x (InsightFace) | V2.0 (Vision + FaceNet) |
|------|--------------------|-------------------------|
| Detection 模型 | IntegrationFace SCRFD-10G (~150MB) | Apple Vision (系統內建) |
| Embedding 模型 | CoreML FaceNet (90MB) | 同左 |
| CPU | 450%+ | **~0%** |
| 記憶體 | ~1.5GB | **<50MB** |
| ANE | 僅 embedding | **detection + embedding** |
| Total time (2hr film, interval=30) | ~1.3hr | **~40min** |

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-05-02 | 初始版本 (InsightFace) | OpenCode | deepseek-chat |
| V2.0 | 2026-05-04 | Apple Vision detection + CoreML FaceNet embedding | OpenCode | deepseek-chat |
