# Identity 系统实验报告

> 实验日期: 2026-04-28
> 实验版本: V1.0
> 实验对象: Accusys Storage Logo

---

## 实验概述

本实验验证 Momentry Core Identity 系统的完整流程，包括：

1. **数据库架构重构**: identities 表扩展（identity_embedding, reference_data JSONB）
2. **人脸处理系统重构**: face_processor.py 强制 InsightFace + Rust Face Struct 添加 embedding
3. **TMDB 整合**: 多角度人脸下载 + ArcFace embedding + Identity 注册
4. **CLIP Logo Identity**: CLIP ViT-L/14 embedding 提取 + Logo Identity 注册

---

## 实验结果

### Phase 0: 文档存档更新

| 文档 | 操作 | 状态 |
|------|------|------|
| `MOMENTRY_CORE_ARCHITECTURE_V2.md` | 更新 identities 表结构 | ✅ 完成 |
| `FILE_IDENTITY_API_DESIGN.md` | 更新 reference_data JSONB 结构 | ✅ 完成 |
| `IDENTITY_REFERENCE_VECTOR_DESIGN.md` | 新建：1对多参考向量设计 | ✅ 完成 |
| `CLIP_EMBEDDING_BENCHMARK_PLAN.md` | 新建：CLIP 测试计划 | ✅ 完成 |
| `SOUND_RECOGNITION_EXTENSION.md` | 新建：声音识别扩展设计 | ✅ 完成 |

---

### Phase 1: 数据库架构重构

| Migration | 操作 | 状态 |
|-----------|------|------|
| Migration 023 | identities 表扩展 | ✅ 完成 |
| Migration 024 | face_embedding 维度修复 (768→512) | ✅ 完成 |

**identities 表最终结构**:

| 字段 | 类型 | 说明 |
|------|------|------|
| uuid | UUID | 唯一标识 |
| name | VARCHAR(255) | 名称 |
| identity_type | VARCHAR(30) | 类型 (CHECK constraint: people, logo, symbol, sound, animal, environmental) |
| source | VARCHAR(20) | 来源 (manual, tmdb, ai_detection) |
| status | VARCHAR(20) | 状态 (pending, confirmed, skipped) |
| **face_embedding** | VECTOR(512) | InsightFace ArcFace (512-dim) |
| **voice_embedding** | VECTOR(192) | ECAPA-TDNN (192-dim) |
| **identity_embedding** | VECTOR(768) | CLIP ViT-L/14 (768-dim) |
| **reference_data** | JSONB | 1对多参考向量存储 |
| tmdb_id | INTEGER | TMDB ID |
| tmdb_profile | TEXT | TMDB profile URL |

---

### Phase 2: 人脸处理系统重构

#### Phase 2.1: face_processor.py 修改

| 修改 | 说明 |
|------|------|
| 移除 Haar Cascade fallback | Haar 无法生成 embedding，导致全链路失败 |
| 强制 InsightFace | 确保 **所有检测的 Face 都有 embedding** |

#### Phase 2.2: Rust Face Struct 修改

| 新增字段 | 类型 | 说明 |
|----------|------|------|
| embedding | Option<Vec<f32>> | 512-dim ArcFace embedding |
| landmarks | Option<Vec<Vec<f32>>> | 关键点坐标 |
| attributes | Option<FaceAttributes> | 年龄、性别 |

**测试结果**: 8 个 Rust 测试全部通过 ✅

#### Phase 2.3: TMDB Identity Integration 脚本

| 功能 | 说明 |
|------|------|
| TMDB /person/:id/images API | 下载多张人脸照片（不同角度） |
| ArcFace embedding 提取 | 提取 512-dim embedding |
| reference_data JSONB 存储 | 存储多个 embedding（1对多） |
| Centroid 计算 | 计算中心向量 |

**Database Integration Test**: 5 个测试全部通过 ✅

---

### Phase 3: CLIP Logo Identity 测试

#### 测试对象

| 属性 | 值 |
|------|-----|
| Logo 名称 | Accusys Storage Logo |
| Logo URL | https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png |
| Logo 尺寸 | 3269x747px |
| 品牌色 | Orange (#EE7632) |

#### 性能基准测试

| 指标 | MPS | CPU | Speedup |
|------|-----|-----|---------|
| **提取速度** | 0.0338s/img | 0.2211s/img | **6.54x** |
| **10 iterations** | 0.338s | 2.211s | |

#### Embedding 提取

| 指标 | 结果 |
|------|------|
| **Embedding 维度** | 768-dim ✅ |
| **模型** | CLIP ViT-L/14 |
| **设备** | MPS (Apple Silicon) |

#### Identity 注册

| 指标 | 值 |
|------|-----|
| **UUID** | 23050c3e-6bea-4b8e-a916-2aaff0024bc2 |
| **identity_type** | logo |
| **status** | confirmed |
| **identity_embedding** | ✅ 存储 768-dim VECTOR |
| **reference_data** | ✅ 存储 JSONB |

#### Similarity Search 测试

| Test | Similarity | Match |
|------|-----------|-------|
| **Test 1** (自己) | 1.0000 | ✅ True |
| **Test 2** (随机) | -0.0298 | ❌ False |

---

## 创建的脚本

| 脚本 | 路径 | 说明 |
|------|------|------|
| TMDB Integration | `scripts/tmdb_identity_integration.py` | TMDB 多角度人脸 + ArcFace + Identity 注册 |
| CLIP Logo Integration | `scripts/clip_logo_integration.py` | CLIP embedding + Logo Identity 注册 |
| DB Test | `scripts/test_identity_db.py` | identities 表结构验证 |

---

## 创建的 Migration

| Migration | 文件路径 |
|-----------|----------|
| Migration 023 | `migrations/023_extend_identities_embeddings.sql` |
| Migration 024 | `migrations/024_fix_face_embedding_dim.sql` |

---

## 关键发现

### 1. Haar Cascade 是"破坏者"

**问题**: Haar Cascade 只能检测人脸，无法生成 embedding。

**后果**: 当 InsightFace 失败时，系统 fallback 到 Haar，导致 embedding=null → 全链路失败。

**解决方案**: 移除 Haar fallback，强制使用 InsightFace。

### 2. Rust Face Struct 缺失 embedding 字段

**问题**: Python 输出的 embedding 在 Rust 解析时被丢弃。

**解决方案**: Face Struct 添加 `embedding: Option<Vec<f32>>` 字段。

### 3. MPS 性能提升 6.54x

**测试结果**: CLIP ViT-L/14 在 MPS 模式下比 CPU 快 6.54 倍。

**建议**: Logo/Symbol/Object Identity 系统优先使用 MPS。

### 4. 1对多参考向量架构验证成功

**设计**: 同一 Identity 可存储多个 embedding（不同角度/场景/版本）。

**验证**: reference_data JSONB 存储成功。

---

## 下一步计划

### Phase 5+: 声音识别扩展

| 类型 | 说明 |
|------|------|
| animal | 动物叫声（狗叫声、猫叫声、鸟叫声） |
| environmental | 环境音（雷声、雨声、风声） |
| weapon | 武器声（枪声、爆炸声、警报声） |
| musical | 乐器声（吉他、钢琴、鼓） |

**设计文档**: `docs_v1.0/ARCHITECTURE/SOUND_RECOGNITION_EXTENSION.md`

---

## 版本信息

- 实验版本: V1.0
- 实验日期: 2026-04-28
- 实验状态: ✅ 全部成功
