# 臉部辨識系統部署指南

## 系統概述

Momentry Core 的臉部辨識系統是一個完整的本地化解決方案，具有以下特點：

- ✅ **100% 本地運算**：無雲端依賴，保護隱私
- ✅ **Apple Silicon 優化**：支援 MPS 加速（CoreMLExecutionProvider）
- ✅ **向量相似度搜尋**：使用 pgvector 進行臉部比對
- ✅ **即時學習**：可註冊新臉部並在未來識別
- ✅ **影片分析**：自動分析影片中的臉部

## 系統架構

```
┌─────────────────────────────────────────────────────────────┐
│                   臉部辨識系統架構                           │
├─────────────────────────────────────────────────────────────┤
│ 前端應用/API 客戶端                                          │
│  ↓                                                          │
│  Momentry API 伺服器 (Rust/Axum)                            │
│  ↓                                                          │
│ 臉部辨識處理器 (Python/InsightFace)                         │
│  ↓                                                          │
│  PostgreSQL + pgvector 資料庫                               │
│  ↓                                                          │
│  ONNX Runtime + Apple MPS 加速                              │
└─────────────────────────────────────────────────────────────┘
```

## 部署步驟

### 1. 環境準備

```bash
# 安裝系統依賴
brew install postgresql@18 redis mongodb-community ffmpeg

# 安裝 Python 依賴
pip install insightface onnxruntime-coreml opencv-python pillow psycopg2-binary requests

# 安裝 Rust 工具鏈
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### 2. 資料庫設定

```bash
# 啟動 PostgreSQL
brew services start postgresql@18

# 建立資料庫和使用者
createdb momentry
createuser -s accusys

# 啟用 pgvector 擴展
psql -d momentry -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 執行遷移腳本
psql -d momentry -f migrations/006_face_recognition_tables.sql
```

### 3. 模型下載

```bash
# 下載 InsightFace buffalo_l 模型
python3 -c "
import insightface
app = insightface.app.FaceAnalysis(name='buffalo_l')
app.prepare(ctx_id=0, det_size=(640, 640))
print('✅ Model downloaded successfully')
"
```

### 4. 伺服器部署

```bash
# 編譯生產版本
cd /Users/accusys/momentry_core_0.1
cargo build --release --bin momentry

# 啟動伺服器
./target/release/momentry server --port 3002

# 或使用 systemd 服務（Linux）
sudo cp deploy/momentry.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable momentry
sudo systemctl start momentry
```

### 5. API 金鑰管理

```bash
# 建立 API 金鑰
./target/release/momentry api-key create "face_recognition_app" --key-type user

# 列出金鑰
./target/release/momentry api-key list

# 驗證金鑰
./target/release/momentry api-key validate --key "YOUR_API_KEY"
```

## API 端點

### 臉部辨識 API

| 端點 | 方法 | 功能 | 認證 |
|------|------|------|------|
| `/api/v1/face/recognize` | POST | 識別圖片中的臉部 | ✅ X-API-Key |
| `/api/v1/face/register` | POST | 註冊新臉部 | ✅ X-API-Key |
| `/api/v1/face/list` | GET | 列出已註冊臉部 | ✅ X-API-Key |
| `/api/v1/face/results/{uuid}` | GET | 取得影片分析結果 | ✅ X-API-Key |
| `/api/v1/face/search` | POST | 搜尋相似臉部 | ✅ X-API-Key |

### 使用範例

#### 1. 註冊新臉部（學習）

```bash
curl -X POST http://localhost:3002/api/v1/face/register \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_uuid": "384b0ff44aaaa1f1",
    "frame_number": 19778,
    "face_index": 0,
    "person_name": "張三",
    "metadata": {
      "gender": "male",
      "age": 35,
      "notes": "公司員工"
    }
  }'
```

#### 2. 識別臉部

```bash
curl -X POST http://localhost:3002/api/v1/face/recognize \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@photo.jpg"
```

#### 3. 取得影片分析結果

```bash
curl -X GET "http://localhost:3002/api/v1/face/results/384b0ff44aaaa1f1" \
  -H "X-API-Key: YOUR_API_KEY"
```

## 影片分析流程

### 1. 分析影片中的臉部

```bash
# 使用 Python 腳本分析影片
python3 scripts/analyze_video_faces.py \
  --video-path "/path/to/video.mp4" \
  --output-dir "/tmp/face_analysis" \
  --sample-rate 30
```

### 2. 遷移分析結果到資料庫

```bash
# 遷移結果到 face_recognition_results 表
python3 scripts/migrate_face_results.py
```

### 3. 提取特定臉部（如女性臉部）

```bash
# 提取女性臉部
python3 scripts/extract_female_faces.py \
  --video-uuid "384b0ff44aaaa1f1" \
  --output-dir "/tmp/female_faces"
```

## 監控與日誌

### 日誌位置

```bash
# API 伺服器日誌
/Users/accusys/momentry/log/momentry_api.log
/Users/accusys/momentry/log/momentry_api.error.log

# 資料庫日誌
/Users/accusys/momentry/var/postgresql/logfile

# 處理器日誌
/tmp/face_analysis/analysis.log
```

### 健康檢查

```bash
# 檢查伺服器狀態
curl -X GET "http://localhost:3002/api/v1/face/list" \
  -H "X-API-Key: YOUR_API_KEY"

# 檢查資料庫連接
psql -d momentry -c "SELECT COUNT(*) FROM face_identities;"

# 檢查模型載入
python3 scripts/test_face_processor.py
```

## 效能優化

### 1. Apple Silicon MPS 加速

```python
# 在 Python 腳本中啟用 MPS
import onnxruntime as ort

providers = ['CoreMLExecutionProvider', 'CPUExecutionProvider']
session = ort.InferenceSession('model.onnx', providers=providers)
```

### 2. 資料庫索引優化

```sql
-- 建立臉部搜尋索引
CREATE INDEX idx_face_identities_embedding 
ON face_identities USING ivfflat (embedding vector_cosine_ops);

-- 建立影片查詢索引
CREATE INDEX idx_face_detections_video_frame 
ON face_detections (video_uuid, frame_number);
```

### 3. 批次處理

```bash
# 批次分析多個影片
python3 scripts/batch_analyze_videos.py \
  --input-dir "/path/to/videos" \
  --workers 4 \
  --batch-size 10
```

## 故障排除

### 常見問題

#### 1. API 認證失敗 (401)

```bash
# 檢查 API 金鑰格式
# 正確：X-API-Key: muser_xxx_xxx_xxx
# 錯誤：Authorization: Bearer xxx

curl -X GET "http://localhost:3002/api/v1/face/list" \
  -H "X-API-Key: YOUR_API_KEY"
```

#### 2. 資料庫連接超時

```bash
# 檢查 PostgreSQL 服務
brew services list | grep postgresql

# 增加連接池大小
export DATABASE_MAX_CONNECTIONS=100
```

#### 3. 模型載入失敗

```bash
# 檢查模型檔案
ls -la ~/.insightface/models/buffalo_l/

# 重新下載模型
rm -rf ~/.insightface/models/buffalo_l/
python3 -c "import insightface; app = insightface.app.FaceAnalysis(name='buffalo_l')"
```

#### 4. MPS 加速不工作

```bash
# 檢查 Apple Silicon 支援
python3 -c "import platform; print(f'Architecture: {platform.machine()}')"

# 檢查 ONNX Runtime 提供者
python3 -c "import onnxruntime as ort; print(f'Available providers: {ort.get_available_providers()}')"
```

## 安全考量

### 1. API 金鑰安全

- 使用環境變數儲存 API 金鑰
- 定期輪換金鑰（每 90 天）
- 限制金鑰權限（最小權限原則）
- 記錄所有 API 使用記錄

### 2. 資料保護

- 所有臉部資料本地儲存
- 臉部嵌入向量加密儲存
- 敏感資訊不記錄到日誌
- 定期備份資料庫

### 3. 網路安全

- 使用 HTTPS 生產環境
- 啟用 API 速率限制
- 設定防火牆規則
- 定期安全掃描

## 擴展功能

### 1. 自訂模型

```python
# 使用自訂 InsightFace 模型
app = insightface.app.FaceAnalysis(
    name='custom_model',
    root='~/.insightface/models/custom/'
)
```

### 2. 即時串流分析

```python
# 即時攝影機臉部辨識
python3 scripts/realtime_face_recognition.py \
  --camera 0 \
  --model buffalo_l \
  --output-display
```

### 3. 批次註冊

```bash
# 批次註冊臉部資料庫
python3 scripts/batch_register_faces.py \
  --dataset "/path/to/face_dataset" \
  --metadata "/path/to/metadata.csv"
```

## 聯絡與支援

### 問題回報

1. 檢查日誌檔案
2. 提供重現步驟
3. 包含系統資訊
4. 提交到 GitHub Issues

### 效能問題

- 影片分析速度慢：調整 sample-rate 參數
- 記憶體使用過高：減少批次大小
- 資料庫查詢慢：優化索引

### 功能請求

- 新增臉部屬性分析
- 支援更多影片格式
- 增加匯出功能
- 改進使用者介面

---

**版本**: 1.0.0  
**最後更新**: 2026-03-30  
**作者**: Momentry Core 團隊  
**文件狀態**: ✅ 生產就緒