---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0)"
date: "2026-04-21"
version: "V1.0"
status: "deprecated"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "deprecated"
  - "character"
  - "tmdb"
  - "momentry"
  - "core"
ai_query_hints:
  - "查詢 Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0) 的內容"
  - "Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0) 的主要目的是什麼？"
  - "如何操作或實施 Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0)？"
---

> [!WARNING] **檔案已過時 (Deprecated)**
> 
> **原因**: 此文件定義了舊版 `person_identities` 和 `global_person_identities` 表結構。新的架構設計已採用 `identities` (全域實體) 和 `file_identities` (出現紀錄) 的通用模型，詳見 `FILE_IDENTITY_API_DESIGN.md`。
> 
> **狀態**: 僅供歷史參考，不應用於新功能的開發。
> 
> **搬移日期**: 2026-04-25

# Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0)

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-21 | 定義基於 TMDB API 的自動化全域人物識別與資料建檔流程 | OpenCode | OpenCode / Qwen3.6-Plus |

---

## 0. 設計目標

本規範旨在透過整合 **TMDB (The Movie Database) API**，解決影片處理中「臉部聚類 (Face Clustering)」後無法得知真實身分的問題。

- **核心目標**: 實現電影類型檔案的 **零人工干預 (Zero-Touch)** 人物識別。
- **資料豐富**: 自動獲取 **演員本名 (Actor Name)**、**角色名 (Character Name)** 及 **大頭照 (Profile Photo)**。
- **全域身分**: 建立跨影片的全域人物庫 (`global_person_identities`)，而非僅限於單一影片的標籤。

---

## 1. 整體架構流程 (Workflow)

整合流程發生在影片處理管線的 **「臉部處理 (Face Processing)」** 階段之後，**「內容聚合 (Chunking)」** 階段之前。

```mermaid
graph LR
    A[影片資產] -->|Metadata (Title/Year)| B(TMDB Query Service)
    B -->|Cast List + Photos| C[Cast Local DB]
    D[Face Processor] -->|Face Clusters + Embeddings| E(Face Matcher)
    C -->|Actor Profile Embeddings| E
    E -->|Match Result| F[Identity Resolver]
    F -->|Create/Update| G[(Global Person Identity)]
    G -->|Link| H[Local Person Appearance]
```

### 1.1 關鍵步驟
1. **Metadata 解析**: 從檔名或 `ffprobe` 資訊中提取電影名稱與年份。
2. **TMDB 查詢**: 呼叫 API 獲取 Top Cast (通常前 10-15 名) 及其照片 URL。
3. **照片下載與特徵提取**: 下載演員照片並生成 Face Embedding (512-dim)。
4. **向量比對**: 將演員照片向量與影片內偵測到的 **Face Cluster Centroids** 進行相似度比對 (Cosine Similarity)。
5. **身分決議**: 若相似度超過閾值 (如 0.6)，則自動建立全域身分並標記。

---

## 2. 資料結構設計 (Schema Design)

為了支持此流程，需擴展資料庫以儲存外部資料來源與比對結果。

### 2.1 全域人物身分表 (Global Person Identities)

此表用於存放已確認的真實演員資料，跨影片共享。

```sql
CREATE TABLE global_person_identities (
    id UUID PRIMARY KEY,
    tmdb_id INT,                        -- TMDB Actor ID (唯一索引)
    name VARCHAR(255) NOT NULL,         -- 演員姓名 (e.g., "Cary Grant")
    profile_path VARCHAR(255),          -- 照片路徑 (本地或 URL)
    embedding vector(512),              -- 照片的人臉特徵向量
    source VARCHAR(20) DEFAULT 'tmdb',  -- 來源標記
    created_at TIMESTAMPTZ DEFAULT NOW(),
    
    UNIQUE(tmdb_id)
);
```

### 2.2 本地人物出現紀錄 (Local Person Appearances)

此表記錄特定人物在特定影片中的具體表現 (角色名)。

```sql
CREATE TABLE person_identities (
    id UUID PRIMARY KEY,
    asset_uuid UUID NOT NULL,           -- 所屬影片
    global_person_id UUID REFERENCES global_person_identities(id), -- 關聯全域身分
    
    character_name VARCHAR(255),        -- 角色名 (e.g., "Peter Joshua")
    face_cluster_id VARCHAR(50),        -- 對應的臉部聚類 ID
    match_score FLOAT,                  -- 匹配信心度 (0.0 - 1.0)
    
    appearance_count INT DEFAULT 0,     -- 出現次數
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_person_asset ON person_identities(asset_uuid);
CREATE INDEX idx_person_global ON person_identities(global_person_id);
```

---

## 3. 處理邏輯細節 (Implementation Details)

### 3.1 TMDB 服務註冊 (Service Registry)

根據 `SERVICE_REGISTRY_ARCHITECTURE.md`，TMDB 服務定義如下：

```json
{
  "name": "tmdb-cast-api",
  "type": "external_api",
  "endpoint": "https://api.themoviedb.org/3",
  "metadata": {
    "api_key_env": "TMDB_API_KEY",
    "language": "zh-TW",
    "image_base_url": "https://image.tmdb.org/t/p/w185"
  }
}
```

### 3.2 臉部比對策略 (Face Matching Strategy)

系統如何決定「畫面中的臉」就是「Cary Grant」？

1. **參考集準備 (Reference Set)**:
    - 從 TMDB 獲取演員照片 URL。
    - 下載並使用 InsightFace 提取向量 $V_{actor}$。
2. **目標集 (Target Set)**:
    - 從影片 Face Processor 獲取每個 Cluster 的中心向量 $V_{cluster}$。
3. **計算相似度**:
    - $Score = 1 - \text{CosineDistance}(V_{actor}, V_{cluster})$
4. **決策閾值**:
    - **High Confidence (> 0.70)**: 自動確認身分 (Auto-Confirm)。
    - **Medium Confidence (0.55 - 0.70)**: 標記為 "Suggestion" (建議)，需人工確認。
    - **Low Confidence (< 0.55)**: 忽略，保持為 "Unknown Cluster"。

### 3.3 角色名關聯 (Role Mapping)

TMDB 返回的結構包含 `character` 字段：
```json
{
  "id": 389, // Actor ID
  "name": "Cary Grant",
  "character": "Peter Joshua", // 角色名
  "profile_path": "/path/to/image.jpg"
}
```
當比對成功時，系統將 **"Peter Joshua"** 寫入 `person_identities.character_name`，並將 **"Cary Grant"** 寫入 `global_person_identities.name`。

---

## 4. 自動化流程腳本 (Automation Pipeline)

此流程被打包為一個獨立的 **Post-Face-Processing Job**。

1. **Trigger**: `face_processor` 完成，產生 `face_clusters`。
2. **Action**: 系統檢查 `asset_type == 'movie'` 且 `title` 存在。
3. **Execution**: 執行 `tmdb_cast_ingestion.py`。
    - 查詢 TMDB。
    - 下載圖片 -> 計算向量 -> 存入 `global_person_identities` (若不存在)。
    - 執行比對 -> 更新 `person_identities`。
4. **Output**: 資料庫中充滿了真實姓名與角色名的紀錄，供 Rule 3/4 Chunking 使用。

---

## 5. 容錯與異常處理 (Error Handling)

- **找不到電影**: 若檔名模糊導致 TMDB 無結果，則跳過此步驟，保留原始 Face Cluster ID。
- **無演員照片**: 若某演員在 TMDB 無照片，無法進行向量比對，僅記錄名字 (若 ASR 有提及)。
- **多人飾演一角**: 若臉部特徵同時匹配多個演員 (極罕見)，取 Confidence 最高者，其餘列入候補。

---

## 6. 總結

透過引入 **TMDB API**，Momentry Core 將具備**好萊塢級別的自動標記能力**。

| 特性 | 實作方式 |
|------|----------|
| **資料來源** | TMDB API (Cast Endpoint) |
| **識別方式** | Face Embedding Similarity (Vector Match) |
| **儲存活用** | 建立 `global_person_identities` 實現跨片共享 |
| **元數據豐富** | 同時獲取演員名、角色名、大頭照 |
| **自動化** | 處理管線自動觸發，無需人工介入 |

此機制確保了用戶在搜尋 "Cary Grant" 或 "Peter Joshua" 時，系統都能精確返回對應的影片片段。
