warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: update docs_v1.0/ documentation

Browse Source 
- 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
This commit is contained in:
Warren
2026-04-30 15:10:41 +08:00
parent 8f05a7c188
commit 4d75b2e251
185 changed files with 21071 additions and 1605 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs_v1.0/AI_AGENTS/CONTEXT/METADATA_PROCESSORS.md
View File

@@ -193,7 +193,7 @@ GROUP BY metadata_version;
| `person_id` | varchar(255) | 人物唯一 ID (如 person_001) | | `person_id` | varchar(255) | 人物唯一 ID (如 person_001) |
| `name` | varchar(255) | 人物名稱 (可確認) | | `name` | varchar(255) | 人物名稱 (可確認) |
| `speaker_id` | varchar(255) | 對應的說話者 ID | | `speaker_id` | varchar(255) | 對應的說話者 ID |
| `video_uuid` | varchar(255) | 影片 UUID | | `file_uuid` | varchar(255) | 影片 UUID |
| `face_identity_id` | integer | 對應的 global identity | | `face_identity_id` | integer | 對應的 global identity |
| `appearance_count` | integer | 出現次數 | | `appearance_count` | integer | 出現次數 |
| `first_appearance_time` | double | 首次出現時間 | | `first_appearance_time` | double | 首次出現時間 |
@@ -264,13 +264,13 @@ Step 4: Global Matching
-- 取得影片中的人物列表 -- 取得影片中的人物列表
SELECT person_id, name, speaker_id, appearance_count SELECT person_id, name, speaker_id, appearance_count
FROM dev.person_identities FROM dev.person_identities
WHERE video_uuid = '384b0ff44aaaa1f1' WHERE file_uuid = '384b0ff44aaaa1f14cb2cd63b3fea966'
ORDER BY appearance_count DESC; ORDER BY appearance_count DESC;
-- 取得 chunk 的人物 -- 取得 chunk 的人物
SELECT c.chunk_id, pi.name, pi.speaker_id SELECT c.chunk_id, pi.name, pi.speaker_id
FROM dev.chunks c FROM dev.chunks c
JOIN dev.person_identities pi ON c.uuid = pi.video_uuid JOIN dev.person_identities pi ON c.uuid = pi.file_uuid
WHERE c.chunk_id = 'sentence_0001'; WHERE c.chunk_id = 'sentence_0001';
``` ```
@@ -280,7 +280,7 @@ WHERE c.chunk_id = 'sentence_0001';
-- 取得某 chunk 的人物 -- 取得某 chunk 的人物
SELECT pi.name, pi.speaker_id, pi.appearance_count SELECT pi.name, pi.speaker_id, pi.appearance_count
FROM dev.person_identities pi FROM dev.person_identities pi
JOIN dev.chunks c ON c.uuid = pi.video_uuid JOIN dev.chunks c ON c.uuid = pi.file_uuid
WHERE c.chunk_id = 'sentence_0001'; WHERE c.chunk_id = 'sentence_0001';
``` ```
@@ -484,19 +484,19 @@ SELECT COUNT(*) FROM dev.chunks WHERE visual_stats IS NOT NULL;"
```bash ```bash
# Step 1: ASRX 執行說話者分離 # Step 1: ASRX 執行說話者分離
python scripts/asrx_processor.py --uuid 384b0ff44aaaa1f1 python scripts/asrx_processor.py --uuid 384b0ff44aaaa1f14cb2cd63b3fea966
# Step 2: Face 執行臉部偵測 # Step 2: Face 執行臉部偵測
python scripts/analyze_video_faces.py --uuid 384b0ff44aaaa1f1 python scripts/analyze_video_faces.py --uuid 384b0ff44aaaa1f14cb2cd63b3fea966
# Step 3: Auto-identify 建立影片級人物 # Step 3: Auto-identify 建立影片級人物
python scripts/auto_identify_persons.py --uuid 384b0ff44aaaa1f1 python scripts/auto_identify_persons.py --uuid 384b0ff44aaaa1f14cb2cd63b3fea966
# Step 4: 全局 Identity 比對 (需累積一定數量的 face_identities) # Step 4: 全局 Identity 比對 (需累積一定數量的 face_identities)
python scripts/match_faces_to_identities.py python scripts/match_faces_to_identities.py
# Step 5: 重新生成 chunk 5W1H (包含新的 identity 資訊) # Step 5: 重新生成 chunk 5W1H (包含新的 identity 資訊)
python scripts/generate_chunk_summaries.py --uuid 384b0ff44aaaa1f1 python scripts/generate_chunk_summaries.py --uuid 384b0ff44aaaa1f14cb2cd63b3fea966
``` ```
### 檢查待處理狀態 ### 檢查待處理狀態
@@ -515,7 +515,7 @@ WHERE face_ids IS NOT NULL AND array_length(face_ids, 1) > 0;"
# 檢查 person_identities # 檢查 person_identities
psql -h localhost -U accusys -d momentry -c " psql -h localhost -U accusys -d momentry -c "
SELECT COUNT(*) FROM dev.person_identities SELECT COUNT(*) FROM dev.person_identities
WHERE video_uuid = '384b0ff44aaaa1f1';" WHERE file_uuid = '384b0ff44aaaa1f14cb2cd63b3fea966';"
# 檢查 face_identities (全局) # 檢查 face_identities (全局)
psql -h localhost -U accusys -d momentry -c " psql -h localhost -U accusys -d momentry -c "
@@ -560,4 +560,4 @@ SELECT COUNT(*) FROM dev.face_identities;"
2. **face_ids** → 進入 `chunk_identity.faces` 2. **face_ids** → 進入 `chunk_identity.faces`
3. **person_identities** → 進入 `chunk_identity.person_name` 3. **person_identities** → 進入 `chunk_identity.person_name`
確保 LLM 產生的 5W1H 包含最新的角色資訊。 確保 LLM 產生的 5W1H 包含最新的角色資訊。

112
docs_v1.0/AI_AGENTS/CORE/AGENT_SPEC.md
View File

@@ -1,10 +1,33 @@
---
document_type: "standard_doc"
service: "MOMENTRY_CORE"
title: "AI Agent 設計規範"
date: "2026-04-27"
version: "V1.1"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "AI Agent"
- "設計規範"
- "三層架構"
- "processing_status"
ai_query_hints:
- "查詢 AI Agent 設計規範的內容"
- "AI Agent 的三層架構定義"
- "Agent 類型列表"
- "Agent 進度追蹤方式"
- "processing_status JSONB agents 字段"
- "如何設計 AI Agent"
---
# AI Agent 設計規範 (Agent Design Specification) # AI Agent 設計規範 (Agent Design Specification)
| 項目 | 內容 | | 項目 | 內容 |
|------|------| |------|------|
| 建立者 | OpenCode | | 建立者 | OpenCode |
| 建立時間 | 2026-04-25 | | 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 | | 文件版本 | V1.1 |
--- ---
@@ -13,6 +36,7 @@
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 | | 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------| |------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 定義 Momentry Core 中 AI Agent 的標準設計與職責 | OpenCode | OpenCode | | V1.0 | 2026-04-25 | 定義 Momentry Core 中 AI Agent 的標準設計與職責 | OpenCode | OpenCode |
| V1.1 | 2026-04-27 | 添加 Agent 類型列表和進度追蹤（processing_status JSONB） | OpenCode | GLM-5 |
--- ---
@@ -33,10 +57,10 @@
AI Agent 負責處理那些傳統程式難以精確定義規則的任務。 AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
**注意**: 在系統架構中，Agent 被視為一種 **資源 (Resource)**，與 Processor 和 Service 統一由 **資源註冊中心 (Resource Registry)** 管理。 **注意**: 在系統架構中，Agent 被視為一種 **資源 (Resource)**，與 Processor 和 Service 統一由 **資源註冊中心 (Resource Registry)** 管理。
1. **語義理解 (Semantic Understanding)**: 將非結構化數據（如 OCR 文字、雜訊 ASR 文本）轉化為結構化標籤 (5W1H)。 1. **語義理解 (Semantic Understanding)**: 將非結構化數據（如 OCR 文字、雜訊 ASR 文本）轉化為結構化標籤 (5W1H)。
2. **跨模態匹配 (Cross-Modal Matching)**: 綜合視覺、聽覺和文本證據，判斷「畫面中的臉」是否為「資料庫中的人」。 2. **跨模態匹配 (Cross-Modal Matching)**: 綜合視覺、聽覺和文本證據，判斷「畫面中的臉」是否為「資料庫中的人」。
3. **內容生成 (Content Generation)**: 為影片片段生成自然的摘要或標題。 3. **內容生成 (Content Generation)**: 為影片片段生成自然的摘要或標題。
4. **查詢解析 (Query Parsing)**: 將用戶的自然語言請求轉譯為系統可執行的 API 調用序列。 4. **查詢解析 (Query Parsing)**: 將用戶的自然語言請求轉譯為系統可執行的 API 調用序列。
--- ---
@@ -45,8 +69,8 @@ AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
所有 AI Agent 的設計文件必須遵循以下結構： 所有 AI Agent 的設計文件必須遵循以下結構：
### 3.1 檔案命名 ### 3.1 檔案命名
* **格式**: `[AGENT_TYPE]_[PURPOSE].md` * **格式**: `[AGENT_TYPE]_[PURPOSE].md`
* **範例**: `CONTEXT_5W1H_INFERENCE.md` * **範例**: `CONTEXT_5W1H_INFERENCE.md`
### 3.2 文件內容 ### 3.2 文件內容
@@ -56,17 +80,17 @@ AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
#### 3.2.2 輸入數據 (Input) #### 3.2.2 輸入數據 (Input)
定義 Agent 接收的數據格式。通常來自 Processor 輸出或 Rule 產物。 定義 Agent 接收的數據格式。通常來自 Processor 輸出或 Rule 產物。
* **來源**: `PROCESSORS/` 或 `CHUNKING/` * **來源**: `PROCESSORS/` 或 `CHUNKING/`
* **格式**: JSON, Text, List of Frames. * **格式**: JSON, Text, List of Frames.
#### 3.2.3 核心邏輯 (Core Logic: Prompt / Workflow) #### 3.2.3 核心邏輯 (Core Logic: Prompt / Workflow)
這是 Agent 的靈魂。 這是 Agent 的靈魂。
* **單一 Prompt Agent**: 提供完整的 System Prompt。 * **單一 Prompt Agent**: 提供完整的 System Prompt。
```markdown ```markdown
## System Prompt ## System Prompt
You are a scene analysis assistant... You are a scene analysis assistant...
``` ```
* **多步 Workflow Agent**: 提供步驟圖或偽代碼。 * **多步 Workflow Agent**: 提供步驟圖或偽代碼。
```mermaid ```mermaid
graph TD graph TD
A[Start] --> B[Extract Entities] A[Start] --> B[Extract Entities]
@@ -86,31 +110,71 @@ AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
#### 3.2.5 模型配置 (Model Config) #### 3.2.5 模型配置 (Model Config)
建議使用的模型類型及其原因。 建議使用的模型類型及其原因。
* **推理模型 (Reasoning)**: `o1`, `R1` (用於複雜邏輯判斷) * **推理模型 (Reasoning)**: `o1`, `R1` (用於複雜邏輯判斷)
* **生成模型 (Generation)**: `GPT-4o`, `Sonnet` (用於摘要) * **生成模型 (Generation)**: `GPT-4o`, `Sonnet` (用於摘要)
* **本地模型 (Local)**: `Llama-3`, `Qwen` (用於隱私數據) * **本地模型 (Local)**: `Llama-3`, `Qwen` (用於隱私數據)
--- ---
## 4. 開發工作流 (Development Workflow) ## 4. 開發工作流 (Development Workflow)
1. **定義需求**: 確定是否需要 AI 介入 (若規則可解，優先使用 Rule)。 1. **定義需求**: 確定是否需要 AI 介入 (若規則可解，優先使用 Rule)。
2. **撰寫 Prompt**: 在文檔中迭代 Prompt，直到達到穩定輸出。 2. **撰寫 Prompt**: 在文檔中迭代 Prompt，直到達到穩定輸出。
3. **工具串接**: 若需要外部數據 (如 TMDB)，定義 Tool 定義。 3. **工具串接**: 若需要外部數據 (如 TMDB)，定義 Tool 定義。
4. **實作封裝**: 將 Prompt/Workflow 封裝為 Rust/Python 模組，透過 API 調用。 4. **實作封裝**: 將 Prompt/Workflow 封裝為 Rust/Python 模組，透過 API 調用。
--- ---
## 5. 相關文件 ## 5. 相關文件
* `UNIFIED_RESOURCE_REGISTRY.md` - 系統統一資源管理架構 (Agents 作為資源註冊)。 * `UNIFIED_RESOURCE_REGISTRY.md` - 系統統一資源管理架構 (Agents 作為資源註冊)。
* `AI_DRIVEN_PROCESSOR_CONTRACT.md` - Processor 層級的整合合約。 * `AI_DRIVEN_PROCESSOR_CONTRACT.md` - Processor 層級的整合合約。
* `CHUNKING_ARCHITECTURE.md` - Rule 層級的架構。 * `CHUNKING_ARCHITECTURE.md` - Rule 層級的架構。
* `FILE_IDENTITY_API_DESIGN.md` - 全局架構。 * `FILE_IDENTITY_API_DESIGN.md` - 全局架構。
---
## 6. Agent 類型列表
| Agent | 目的 | 觸發條件 | 文檔 |
|-------|------|----------|------|
| **Translation Agent** | 多語言翻譯 | 用戶手動觸發 | `AI_AGENTS/TRANSLATION/TEXT_TRANSLATION.md` |
| **5W1H Agent** | 場景分析（Who/What/When/Where/Why/How） | Rule 3 完成 | `AI_AGENTS/SUMMARIZATION/CHUNK_RULE_4_SUMMARY.md` |
| **Identity Agent** | 身份解析（Face/Speaker → Person） | Face/Speaker 完成 | `AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_WORKFLOW.md` |
---
## 7. Agent 進度追蹤
從 V1.2 起，所有 Agent 任務透過 `processing_status` JSONB 的 `agents` 字段追蹤。
### JSONB 範例
```json
{
"agents": {
"5w1h": {
"status": "running",
"scenes_processed": 5,
"scenes_total": 1332,
"progress_pct": 0.4
}
}
}
```
### 查詢 Agent 進度
```sql
SELECT processing_status->'agents'->'5w1h'->>'status' FROM videos WHERE uuid = 'xxx';
```
詳細規範請參考: `REFERENCE/PROCESSING_STATUS_JSONB_SPEC.md`
--- ---
## 版本資訊 ## 版本資訊
- 版本: V1.0 * 版本: V1.1
- 建立日期: 2026-04-25 * 建立日期: 2026-04-25
* 文件更新: 2026-04-27

248
docs_v1.0/AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_API_GUIDE.md
View File

@@ -1,248 +0,0 @@
# Momentry Face / Speaker / Person API 開發指南
> **版本**: 3.5 | **更新日期**: 2026-04-17
> **適用對象**: n8n 自動化流程開發者、Portal 前端開發者
---
## 快速開始
### 環境
| 環境 | URL | 說明 |
|------|-----|------|
| **正式版** | `https://api.momentry.ddns.net` | 外部存取 (HTTPS/TLSv1.3) |
| **本機版** | `http://localhost:3002` | 同一台機器使用 (延遲更低) |
### 認證
所有 API 請求需在 Header 加入 API Key：
```bash
curl https://api.momentry.ddns.net/api/v1/person/list \
-H "X-API-Key: YOUR_API_KEY"
```
**API Key**（marcom 團隊使用）:
```
muser_68600856036340bcafc01930eb4bd839
```
---
## ⚠️ 鐵律：所有 Face/Speaker/Person API 都必須提供 video_uuid
**沒有例外。** 所有端點都需要 `video_uuid`。
```
錯誤: GET /api/v1/person/list → 400 missing field `video_uuid`
錯誤: GET /api/v1/person/Person_0 → 400 missing field `video_uuid`
正確: GET /api/v1/person/list?video_uuid=xxx → 200 OK
```
| 識別碼 | 全域唯一 | 說明 |
|--------|:---:|------|
| `chunk_id` | ❌ | 每部影片重新編號 |
| `person_id` | ❌ | 每部影片有自己的 Person_0, Person_1... |
| `speaker_id` | ❌ | 每部影片有自己的 SPEAKER_0, SPEAKER_1... |
| **`video_uuid + person_id`** | ✅ | 唯一組合 |
| **`video_uuid + chunk_id`** | ✅ | 唯一組合 |
| `face_id` | ✅ | UUID 格式，全域唯一 |
| `merge_id` | ✅ | UUID 格式，全域唯一 |
---
## API 端點總覽（全部需要 video_uuid）
| 端點 | 方法 | video_uuid 位置 | 說明 |
|------|:---:|:---:|------|
| `/api/v1/person/list` | GET | query | 列出人物 |
| `/api/v1/person/auto-identify` | POST | body | 自動識別人 |
| `/api/v1/person/suggest` | POST | body | AI 建議 |
| `/api/v1/person/:id` | GET | query | 人物詳情 |
| `/api/v1/person/:id` | PATCH | query | 更新人物 |
| `/api/v1/person/:id/thumbnail` | GET | query | 臉部截圖 |
| `/api/v1/person/:id/timeline` | GET | query | 出場時間軸 |
| `/api/v1/person/:id/similar` | GET | query | 相似人物 |
| `/api/v1/person/:id/appearances` | GET | query | 出場紀錄 |
| `/api/v1/person/:id/unbind-speaker` | POST | body | 解除 Speaker |
| `/api/v1/person/:id/reassign-speaker` | POST | body | 重新綁定 Speaker |
| `/api/v1/person/:id/remove-appearance` | POST | body | 刪除出場紀錄 |
| `/api/v1/person/:id/reassign-appearance` | POST | body | 轉移出場紀錄 |
| `/api/v1/person/:id/split` | POST | body | 分割人物 |
| `/api/v1/person/merge` | POST | body | 合併人物 |
| `/api/v1/person/merge/undo` | POST | body | 撤銷合併 |
| `/api/v1/person/merge/history` | GET | query | 合併歷史 |
| `/api/v1/search/universal` | POST | body | 統一搜尋 |
| `/api/v1/search/persons` | GET | query | 搜尋人物 |
| `/api/v1/chunks/:id/persons` | GET | query | chunk 內人物 |
| `/api/v1/face/register` | POST | body | 註冊臉孔 |
| `/api/v1/face/list` | GET | query | 已註冊臉孔列表 |
---
## 詳細 API 說明
### 1. GET /api/v1/person/list
列出指定影片的人物。
**Query Parameters:**
| 參數 | 類型 | 必填 | 說明 |
|------|:---:|:---:|------|
| `video_uuid` | string | **是** | 影片 UUID |
| `limit` | int | 否 | 每頁筆數 (預設 50) |
| `offset` | int | 否 | 偏移量 (預設 0) |
| `min_appearances` | int | 否 | 最低出場次數 |
| `has_speaker` | bool | 否 | 僅顯示有 Speaker 的人物 |
**Request:**
```
GET /api/v1/person/list?video_uuid=384b0ff44aaaa1f1&limit=10&min_appearances=100
```
**Response:**
```json
{
"success": true,
"persons": [
{
"person_id": "Person_0",
"name": null,
"speaker_id": "SPEAKER_0",
"appearance_count": 17832,
"total_appearance_duration": 3600.5,
"first_appearance_time": 79.56,
"last_appearance_time": 6863.34,
"is_confirmed": false,
"speaker_confidence": 0.504
}
],
"total": 303
}
```
### 2. GET /api/v1/person/:id
取得人物詳情。
**Query Parameters:**
| 參數 | 類型 | 必填 |
|------|:---:|:---:|
| `video_uuid` | string | **是** |
### 3. POST /api/v1/person/merge
合併多個人物為一人。
**Request:**
```json
{
"video_uuid": "384b0ff44aaaa1f1",
"target_person_id": "Person_0",
"source_person_ids": ["Person_4", "Person_25"]
}
```
**Response:**
```json
{
"success": true,
"message": "Merged 2 persons into Person_0",
"target_person_id": "Person_0",
"merge_id": "5b12e3ac-12fa-45c0-88e1-5cff67604a7d"
}
```
> ⚠️ **請儲存 `merge_id`**，以便日後撤銷合併。
### 4. POST /api/v1/search/universal
統一搜尋。
**Request:**
```json
{
"query": "stamp",
"uuid": "384b0ff44aaaa1f1",
"types": ["chunk", "person"],
"limit": 20
}
```
---
## 影片定位：Frame 為主
**重要**: 所有影片位置都以 **frame (幀號)** 為唯一準確單位，time 僅供參考。
```json
{
"start_frame": 29795,
"end_frame": 29963,
"fps": 59.94,
"start_time": 497.08,
"end_time": 499.88
}
```
**轉換公式**: `time = frame / fps`
> ⚠️ **注意**: 所有搜尋 API (`/api/v1/search`, `/api/v1/n8n/search`, `/api/v1/search/universal`) 現在都統一回傳 `start_frame`, `end_frame`, `fps` 欄位，確保前端可以精確定位影片幀號。
---
## n8n 工作流範例
```
[Webhook: video_processed]
body: { "uuid": "384b0ff44aaaa1f1" }
↓
[HTTP: POST /api/v1/person/auto-identify]
body: { "video_uuid": "{{ $json.uuid }}" }
↓
[HTTP: POST /api/v1/person/suggest]
body: { "video_uuid": "{{ $json.uuid }}" }
↓
[IF: confidence >= 0.7]
├─ YES → [HTTP: PATCH /api/v1/person/{{person_id}}?video_uuid={{uuid}}]
└─ NO → [等待人工確認]
```
---
## 錯誤碼
| HTTP | 說明 |
|:---:|------|
| 200 | 成功 |
| 400 | 缺少 video_uuid 或參數錯誤 |
| 401 | API Key 無效 |
| 404 | 資源不存在 |
| 422 | 請求體缺少 video_uuid |
| 500 | 伺服器錯誤 |
---
## 資料庫結構
### person_identities
| 欄位 | 類型 | 說明 |
|------|------|------|
| `person_id` | VARCHAR | 識別碼 (每部影片獨立) |
| `video_uuid` | VARCHAR | **所屬影片 (必填)** |
| `name` | VARCHAR | 人物名稱 |
| `speaker_id` | VARCHAR | 對應說話者 ID (每部影片獨立) |
| `appearance_count` | INT | 出場次數 |
| `is_confirmed` | BOOLEAN | 是否已確認 |
### 唯一性約束
```sql
UNIQUE (video_uuid, person_id)
```
每部影片可以有自己的 `Person_0`，但同一部影片內 `person_id` 必須唯一。

28
docs_v1.0/AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_IDENTITY_TUTORIAL.md
View File

@@ -6,27 +6,27 @@
在開始之前，請區分以下名詞： 在開始之前，請區分以下名詞：
1. **Face (臉孔)**: 影像中偵測到的具體臉部特徵數據（向量）。 1. **Face (臉孔)**: 影像中偵測到的具體臉部特徵數據（向量）。
2. **Person (角色實體)**: 在特定影片中出現的角色。他是 Face + Speaker (說話者) 的集合體。 2. **Person (角色實體)**: 在特定影片中出現的角色。他是 Face + Speaker (說話者) 的集合體。
* *例如：影片 `384b0ff44aaaa1f1` 中的 `Person_17`。* * *例如：影片 `384b0ff44aaaa1f14cb2cd63b3fea966` 中的 `Person_17`。*
3. **Identity (真實身份)**: 跨越所有影片的全域實體（如真實演員或新聞人物）。 3. **Identity (真實身份)**: 跨越所有影片的全域實體（如真實演員或新聞人物）。
* *例如：Cary Grant, Audrey Hepburn。* * *例如：Cary Grant, Audrey Hepburn。*
--- ---
## 前置準備 ## 前置準備
* **API URL**: `http://localhost:3003` * **API URL**: `http://localhost:3003`
* **API Key**: `/` * **API Key**: `/`
* **目標影片 (Video UUID)**: `384b0ff44aaaa1f1` (Charade) * **目標影片 (Video UUID)**: `384b0ff44aaaa1f14cb2cd63b3fea966` (Charade)
--- ---
## 情境設定 ## 情境設定
我們要在影片中識別兩位主角： 我們要在影片中識別兩位主角：
1. **Audrey Hepburn** (飾演 Reggie Lampert) 1. **Audrey Hepburn** (飾演 Reggie Lampert)
2. **Cary Grant** (飾演 Peter Joshua) 2. **Cary Grant** (飾演 Peter Joshua)
--- ---
@@ -35,7 +35,7 @@
首先，我們查詢系統在影片中偵測到了哪些人物 (Person)。 首先，我們查詢系統在影片中偵測到了哪些人物 (Person)。
```bash ```bash
curl -s "http://localhost:3003/api/v1/person/list?video_uuid=384b0ff44aaaa1f1&limit=5" \ curl -s "http://localhost:3003/api/v1/person/list?file_uuid=384b0ff44aaaa1f14cb2cd63b3fea966&limit=5" \
-H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
| python3 -m json.tool | python3 -m json.tool
``` ```
@@ -77,7 +77,7 @@ curl -s -X POST "http://localhost:3003/api/v1/identities/from-person" \
-H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"video_uuid": "384b0ff44aaaa1f1", "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"person_id": "Person_17", "person_id": "Person_17",
"identity_name": "Audrey Hepburn", "identity_name": "Audrey Hepburn",
"metadata": { "role": "Reggie Lampert" } "metadata": { "role": "Reggie Lampert" }
@@ -107,7 +107,7 @@ curl -s -X POST "http://localhost:3003/api/v1/identities/from-person" \
-H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"video_uuid": "384b0ff44aaaa1f1", "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"person_id": "Person_4", "person_id": "Person_4",
"identity_name": "Cary Grant", "identity_name": "Cary Grant",
"metadata": { "role": "Peter Joshua" } "metadata": { "role": "Peter Joshua" }
@@ -163,7 +163,7 @@ curl -s "http://localhost:3003/api/v1/identities?limit=10" \
再次查詢影片中的 `Person` 列表，確認名稱是否已自動更新。 再次查詢影片中的 `Person` 列表，確認名稱是否已自動更新。
```bash ```bash
curl -s "http://localhost:3003/api/v1/person/list?video_uuid=384b0ff44aaaa1f1&limit=5" \ curl -s "http://localhost:3003/api/v1/person/list?file_uuid=384b0ff44aaaa1f14cb2cd63b3fea966&limit=5" \
-H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
| python3 -m json.tool | python3 -m json.tool
``` ```

12
docs_v1.0/AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_PROGRESS.md
View File

@@ -1,6 +1,6 @@
# Face/Speaker/Person 分析完成度 # Face/Speaker/Person 分析完成度
**UUID**: `384b0ff44aaaa1f1` **UUID**: `384b0ff44aaaa1f14cb2cd63b3fea966`
**视频**: Charade (1963) - ~115 min, 412,343 frames, 59.94 fps **视频**: Charade (1963) - ~115 min, 412,343 frames, 59.94 fps
**更新日期**: 2026-04-14 **更新日期**: 2026-04-14
@@ -10,11 +10,11 @@
| 模块 | 状态 | 文件 | 数据量 | | 模块 | 状态 | 文件 | 数据量 |
|------|------|------|--------| |------|------|------|--------|
| **Face Detection** | ✅ 完成 | `384b0ff44aaaa1f1.face.json` | 10,691 frames, 25,174 faces | | **Face Detection** | ✅ 完成 | `384b0ff44aaaa1f14cb2cd63b3fea966.face.json` | 10,691 frames, 25,174 faces |
| **Face Clustering** | ✅ 完成 | `384b0ff44aaaa1f1.face_clustered.json` | 302 unique Person IDs | | **Face Clustering** | ✅ 完成 | `384b0ff44aaaa1f14cb2cd63b3fea966.face_clustered.json` | 302 unique Person IDs |
| **ASR (语音识别)** | ✅ 完成 | `384b0ff44aaaa1f1.asr.json` | 1,011 segments | | **ASR (语音识别)** | ✅ 完成 | `384b0ff44aaaa1f14cb2cd63b3fea966.asr.json` | 1,011 segments |
| **ASRX (增强语音)** | ✅ 完成 | `384b0ff44aaaa1f1.asrx.json` | - | | **ASRX (增强语音)** | ✅ 完成 | `384b0ff44aaaa1f14cb2cd63b3fea966.asrx.json` | - |
| **Pose (姿态)** | ✅ 完成 | `384b0ff44aaaa1f1.pose.json` | - | | **Pose (姿态)** | ✅ 完成 | `384b0ff44aaaa1f14cb2cd63b3fea966.pose.json` | - |
| **Speaker Diarization** | ⚠️ 未集成 | - | ASR segments 无 speaker 信息 | | **Speaker Diarization** | ⚠️ 未集成 | - | ASR segments 无 speaker 信息 |
--- ---

14
docs_v1.0/AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_QUICK_START.md
View File

@@ -12,7 +12,7 @@
```bash ```bash
export BASE="http://localhost:3002" export BASE="http://localhost:3002"
export KEY="muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" export KEY="muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
export UUID="384b0ff44aaaa1f1" export UUID="384b0ff44aaaa1f14cb2cd63b3fea966"
``` ```
--- ---
@@ -145,11 +145,11 @@ curl "$BASE/api/v1/person/list?min_appearances=100&has_speaker=true&limit=20" \
curl "$BASE/api/v1/person/Person_0" -H "X-API-Key: $KEY" curl "$BASE/api/v1/person/Person_0" -H "X-API-Key: $KEY"
# 取得臉部截圖 # 取得臉部截圖
curl "$BASE/api/v1/person/Person_0/thumbnail?video_uuid=$UUID" \ curl "$BASE/api/v1/person/Person_0/thumbnail?file_uuid=$UUID" \
-H "X-API-Key: $KEY" -o person0_face.jpg -H "X-API-Key: $KEY" -o person0_face.jpg
# 取得第 5 次出現的臉部截圖 # 取得第 5 次出現的臉部截圖
curl "$BASE/api/v1/person/Person_0/thumbnail?video_uuid=$UUID&index=4" \ curl "$BASE/api/v1/person/Person_0/thumbnail?file_uuid=$UUID&index=4" \
-H "X-API-Key: $KEY" -o person0_face_5.jpg -H "X-API-Key: $KEY" -o person0_face_5.jpg
``` ```
@@ -188,11 +188,11 @@ curl -X POST "$BASE/api/v1/face/register" \
```bash ```bash
# 預設：第一次出現的臉部 # 預設：第一次出現的臉部
curl "$BASE/api/v1/person/Person_0/thumbnail?video_uuid=$UUID" \ curl "$BASE/api/v1/person/Person_0/thumbnail?file_uuid=$UUID" \
-H "X-API-Key: $KEY" -o face.jpg -H "X-API-Key: $KEY" -o face.jpg
# 指定第 N 次出現 # 指定第 N 次出現
curl "$BASE/api/v1/person/Person_0/thumbnail?video_uuid=$UUID&index=10" \ curl "$BASE/api/v1/person/Person_0/thumbnail?file_uuid=$UUID&index=10" \
-H "X-API-Key: $KEY" -o face_10.jpg -H "X-API-Key: $KEY" -o face_10.jpg
``` ```
@@ -229,7 +229,7 @@ curl "$BASE/api/v1/person/Person_0/similar?threshold=0.5&limit=10" \
curl -X POST "$BASE/api/v1/person/suggest" \ curl -X POST "$BASE/api/v1/person/suggest" \
-H "X-API-Key: $KEY" \ -H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"video_uuid": "'$UUID'"}' -d '{"file_uuid": "'$UUID'"}'
``` ```
```json ```json
@@ -373,7 +373,7 @@ curl "$BASE/api/v1/person/merge/history" -H "X-API-Key: $KEY"
| **搜尋人物** | GET | `/api/v1/search/persons?query=Person` | | **搜尋人物** | GET | `/api/v1/search/persons?query=Person` |
| **列出人物** | GET | `/api/v1/person/list?limit=20` | | **列出人物** | GET | `/api/v1/person/list?limit=20` |
| **人物詳情** | GET | `/api/v1/person/:id` | | **人物詳情** | GET | `/api/v1/person/:id` |
| **人物截圖** | GET | `/api/v1/person/:id/thumbnail?video_uuid=...` | | **人物截圖** | GET | `/api/v1/person/:id/thumbnail?file_uuid=...` |
| **相似人物** | GET | `/api/v1/person/:id/similar` | | **相似人物** | GET | `/api/v1/person/:id/similar` |
| **AI 建議** | POST | `/api/v1/person/suggest` | | **AI 建議** | POST | `/api/v1/person/suggest` |
| **綁定名稱** | PATCH | `/api/v1/person/:id` | | **綁定名稱** | PATCH | `/api/v1/person/:id` |

407
docs_v1.0/AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_WORKFLOW.md
View File

@@ -1,22 +1,43 @@
# Face / Speaker / Person / Identity Workflow Guide # Face to Identity Workflow Guide
This document describes the end-to-end workflow for managing characters in Momentry Core, from raw detection to a clean, aggregated identity database. > Version: V4.0 | Date: 2026-04-28
> Architecture: Two-layer (Face → Identity)
> Related: [FACE_TO_IDENTITY_FLOW.md](./FACE_TO_IDENTITY_FLOW.md)
## 📊 1. Workflow Visualization ---
## Overview
V4.0 架構實現 Face → Identity 直接綁定，移除 person_id 中間層，簡化工作流程。
### Key Changes (V3.x → V4.0)
| Change | V3.x | V4.0 |
|--------|------|------|
| **Architecture** | Three-layer (Face → Person → Identity) | Two-layer (Face → Identity) |
| **Person ID** | Video-local person_id | ❌ Removed |
| **Registration** | POST /identities/from-person | POST /identities/register |
| **Merge** | POST /person/merge | POST /agents/suggest/merge |
| **Candidates** | GET /person/list | GET /faces/candidates |
| **file_uuid** | Used everywhere | **file_uuid** |
---
## Workflow Visualization
```mermaid ```mermaid
graph TD graph TD
%% Nodes %% Nodes
Start((Start Analysis)) Start((Start Analysis))
ListPersons[List Persons] ListCandidates[List Face Candidates]
subgraph "Phase 1: Registration" subgraph "Phase 1: Registration"
CheckIdentity{Identity Exists?} CheckIdentity{Identity Exists?}
Register[Register Identity] Register[Register Identity]
Link[Link Person to Identity] Bind[Bind Faces]
end end
subgraph "Phase 2: Aggregation" subgraph "Phase 2: AI Analysis"
Suggest[Get AI Suggestions] Suggest[Get AI Suggestions]
Review[Review Suggestions] Review[Review Suggestions]
Merge[Execute Merge] Merge[Execute Merge]
@@ -26,19 +47,19 @@ graph TD
End((Database Clean)) End((Database Clean))
%% Flow %% Flow
Start --> ListPersons Start --> ListCandidates
ListPersons --> CheckIdentity ListCandidates --> CheckIdentity
CheckIdentity -- No --> Register CheckIdentity -- No --> Register
Register --> Link Register --> Bind
Link --> Suggest Bind --> Suggest
CheckIdentity -- Yes --> Suggest CheckIdentity -- Yes --> Bind
Bind --> Suggest
Suggest --> Review Suggest --> Review
Review -- Merge Recommended --> Merge Review -- Merge Recommended --> Merge
Review -- Naming Recommended --> Rename[Update Name] Review -- Bind Recommended --> Bind
Rename --> Confirm
Merge --> Confirm Merge --> Confirm
Confirm --> End Confirm --> End
@@ -46,122 +67,306 @@ graph TD
style Start fill:#f9f,stroke:#333 style Start fill:#f9f,stroke:#333
style End fill:#bbf,stroke:#333 style End fill:#bbf,stroke:#333
style Register fill:#dfd,stroke:#333 style Register fill:#dfd,stroke:#333
style Merge fill:#dfd,stroke:#333 style Bind fill:#dfd,stroke:#333
``` ```
--- ---
## 🛠️ 2. Step-by-Step API Operations ## Phase 1: Registration
### Phase 1: Registration (Creating Identities) **Scenario**: You found unregistered faces and want to create a new identity.
**Scenario**: You see `Person_17` is Audrey Hepburn. You want to create a global record for her.
1. **Find the Person**: ### Step 1: List Face Candidates
```bash
curl -s "http://localhost:3003/api/v1/person/list?video_uuid=...&limit=5" ...
# Output: Person_17 (1636 frames, null name)
```
2. **Register Identity**: ```bash
```bash curl -s "http://localhost:3003/api/v1/faces/candidates?min_confidence=0.8&pose_angle=frontal&limit=5" \
curl -X POST "http://localhost:3003/api/v1/identities/from-person" ... \ -H "X-API-Key: YOUR_KEY"
-d '{ ```
"video_uuid": "...",
"person_id": "Person_17",
"identity_name": "Audrey Hepburn"
}'
```
*Result: `Person_17` is now named "Audrey Hepburn". A global `identity_id` is created.*
--- **Response**:
### Phase 2: Suggestion (AI Analysis) ```json
**Scenario**: You suspect `Person_25` might also be Audrey Hepburn, or you just want to clean up the data. {
"success": true,
1. **Ask for Suggestions**: "data": {
```bash "candidates": [
curl -X POST "http://localhost:3003/api/v1/person/suggest" ... \ {
-d '{"video_uuid": "..."}' "face_id": "face_100",
``` "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
*Response*: "frame": 100,
```json "timestamp": 5.2,
{ "pose_angle": "frontal",
"merge_suggestions": [ "confidence": 0.92,
{ "trace_id": 2
"person_id": "Person_17", }
"merge_with": ["Person_25"], ],
"reasons": ["All share speaker_id: SPEAKER_1", "Person_17 has 88% of frames"], "statistics": {
"action": "auto_apply" "total_candidates": 78,
} "avg_confidence": 0.85
]
} }
``` }
}
```
### Step 2: Register Identity
```bash
curl -X POST "http://localhost:3003/api/v1/identities/register" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"face_ids": ["face_100", "face_150", "face_200"],
"name": "Audrey Hepburn",
"source": "manual",
"auto_bind_chunks": true
}'
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
"name": "Audrey Hepburn",
"faces_bound": 3,
"chunks_bound": 10,
"speaker_ids": ["SPEAKER_0"],
"reference_vectors": {
"total": 3,
"angles": ["frontal"]
}
}
}
```
--- ---
### Phase 3: Review & Execution ## Phase 2: AI Analysis
**Scenario**: You verify the suggestion. The AI logic (Shared Speaker + Frame dominance) seems correct.
1. **Execute the Merge**: **Scenario**: You want AI to suggest potential merges or additional bindings.
```bash
curl -X POST "http://localhost:3003/api/v1/person/merge" ... \ ### Step 1: Get AI Suggestions
-d '{
"video_uuid": "...", ```bash
"target_person_id": "Person_17", curl -X POST "http://localhost:3003/api/v1/agents/suggest/clustering" \
"source_person_ids": ["Person_25"] -H "X-API-Key: YOUR_KEY" \
}' -H "Content-Type: application/json" \
``` -d '{
*Result*: `Person_25` is deleted. All 217 frames of `Person_25` are added to `Person_17`. "min_confidence": 0.8,
"pose_angles": ["frontal"],
"max_suggestions": 5
}'
```
**Response**:
```json
{
"success": true,
"data": {
"suggestions": [
{
"suggestion_id": "suggest_1",
"cluster_type": "high_confidence",
"confidence": 0.92,
"recommended_faces": [
{
"face_id": "face_100",
"pose_angle": "frontal",
"confidence": 0.95,
"is_primary": true
}
],
"cluster_stats": {
"total_faces": 50,
"avg_similarity": 0.89
},
"reason": "High confidence frontal faces from same trace",
"action": "register"
},
{
"suggestion_id": "suggest_2",
"cluster_type": "existing_identity",
"confidence": 0.88,
"identity_uuid": "a9a90105...",
"recommended_faces": [
{
"face_id": "face_300",
"confidence": 0.87
}
],
"reason": "Similar to Audrey Hepburn (0.88)",
"action": "bind"
}
]
}
}
```
### Step 2: Review & Execute
**Option A: Bind to Existing Identity**
```bash
curl -X POST "http://localhost:3003/api/v1/identities/a9a90105.../bind" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"face_ids": ["face_300", "face_400"],
"auto_bind_chunks": true
}'
```
**Option B: Register New Identity**
```bash
curl -X POST "http://localhost:3003/api/v1/identities/register" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"face_ids": ["face_500", "face_550"],
"name": "Cary Grant",
"source": "manual"
}'
```
### Step 3: Merge Identities
**Scenario**: Two identities are the same person.
```bash
curl -X POST "http://localhost:3003/api/v1/agents/suggest/merge" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"identity_uuids": ["a9a90105...", "b8b80206..."],
"threshold": 0.85
}'
```
**Response**:
```json
{
"success": true,
"data": {
"suggestions": [
{
"suggestion_type": "merge",
"confidence": 0.88,
"identities": [
{"identity_uuid": "a9a90105...", "name": "Person A", "face_count": 500},
{"identity_uuid": "b8b80206...", "name": "Person B", "face_count": 300}
],
"reason": "High embedding similarity (0.88)",
"recommended_action": {
"merge_target": "a9a90105...",
"merge_sources": ["b8b80206..."]
}
}
]
}
}
```
--- ---
## 🚀 3. Automated Demo Script ## Query Operations
Run the following script to see the entire process in action automatically. ### List Identities in a File
```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/identities" \
-H "X-API-Key: YOUR_KEY"
```
### List Files for an Identity
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../files" \
-H "X-API-Key: YOUR_KEY"
```
### List Faces for an Identity
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../faces?limit=100" \
-H "X-API-Key: YOUR_KEY"
```
### List Chunks for an Identity
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../chunks" \
-H "X-API-Key: YOUR_KEY"
```
---
## Demo Script
```bash ```bash
#!/bin/bash #!/bin/bash
# scripts/demo_identity_workflow.sh # scripts/demo_identity_workflow_v4.sh
# Usage: chmod +x scripts/demo_identity_workflow.sh && ./scripts/demo_identity_workflow.sh
API_URL="http://localhost:3002" API_URL="http://localhost:3003"
API_KEY="muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" API_KEY="YOUR_API_KEY"
UUID="384b0ff44aaaa1f1"
echo "🎬 === MOMENTRY IDENTITY WORKFLOW DEMO ===" echo "=== MOMENTRY IDENTITY WORKFLOW V4.0 ==="
# 1. Registration # 1. List candidates
echo "👉 STEP 1: Registering Person_17 as Audrey Hepburn..." echo "STEP 1: Listing unregistered faces..."
curl -s -X POST "$API_URL/api/v1/identities/from-person" \ curl -s "$API_URL/api/v1/faces/candidates?min_confidence=0.8&limit=5" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \ -H "X-API-Key: $API_KEY" \
-d "{\"video_uuid\":\"$UUID\", \"person_id\":\"Person_17\", \"identity_name\":\"Audrey Hepburn\"}" \
| python3 -m json.tool | python3 -m json.tool
# 2. Suggestion # 2. Register identity
echo "" echo ""
echo "👉 STEP 2: Asking AI for cleaning suggestions..." echo "STEP 2: Registering Audrey Hepburn..."
curl -s -X POST "$API_URL/api/v1/person/suggest" \ curl -s -X POST "$API_URL/api/v1/identities/register" \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \ -H "X-API-Key: $API_KEY" \
-d "{\"video_uuid\":\"$UUID\"}" \ -H "Content-Type: application/json" \
| python3 -c " -d '{"face_ids": ["face_100"], "name": "Audrey Hepburn", "source": "manual"}' \
import sys, json | python3 -m json.tool
d = json.load(sys.stdin)
sugs = d.get('naming_suggestions', []) + d.get('merge_suggestions', [])
if sugs:
print(f' Found {len(sugs)} suggestions.')
for s in sugs:
print(f' - {s}')
else:
print(' No suggestions (Data is already clean!).')
"
# 3. Execution (Example Merge if Person_25 existed) # 3. Get AI suggestions
echo "" echo ""
echo "👉 STEP 3: Simulating a merge (Merging hypothetical Person_25 -> Person_17)..." echo "STEP 3: Getting AI suggestions..."
# Note: In a real scenario, Person_25 would exist. curl -s -X POST "$API_URL/api/v1/agents/suggest/clustering" \
# Here we just show the command structure. -H "X-API-Key: $API_KEY" \
echo " Command: POST /api/v1/person/merge { target: 'Person_17', sources: ['Person_25'] }" -H "Content-Type: application/json" \
echo " Result: Person_25 frames added to Person_17. Person_25 deleted." -d '{"min_confidence": 0.8, "max_suggestions": 3}' \
| python3 -m json.tool
# 4. Bind faces to identity
echo ""
echo "STEP 4: Binding additional faces..."
curl -s -X POST "$API_URL/api/v1/identities/a9a90105.../bind" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"face_ids": ["face_200"]}' \
| python3 -m json.tool
echo "" echo ""
echo "✅ Demo Complete." echo "Demo Complete."
```
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Two-layer architecture, 15 endpoints |
| V3.x | 2026-04-10 | Three-layer architecture, 33 endpoints |
---
## Related Documents
- [IDENTITY_MANAGEMENT_API.md](./IDENTITY_MANAGEMENT_API.md): API design
- [FACE_TO_IDENTITY_FLOW.md](./FACE_TO_IDENTITY_FLOW.md): Binding flow
- [FILE_IDENTITIES_TABLE_SPEC.md](./FILE_IDENTITIES_TABLE_SPEC.md): Table schema
- [IDENTITY_API_SPEC.md](../IDENTITY_API_SPEC.md): Complete API spec

768
docs_v1.0/AI_AGENTS/IDENTITY/FACE_TO_IDENTITY_FLOW.md Normal file
View File

@@ -0,0 +1,768 @@
# Face to Identity Binding Flow
> Version: V4.0 | Date: 2026-04-28
> Architecture: Two-layer (Face → Identity)
> Related: [FILE_IDENTITIES_TABLE_SPEC.md](./FILE_IDENTITIES_TABLE_SPEC.md)
---
## Overview
V4.0 架構實現 Face → Identity 直接綁定，移除 person_id 中間層。
### Key Principles
| Principle | Description |
|-----------|-------------|
| **Direct Binding** | Face 直接綁定到 Identity，無中間層 |
| **One-to-Many Reference** | Identity 擁有多個 Reference Vectors |
| **N:N File-Identity** | Identity 可跨多個 File |
| **Auto Chunk Binding** | Chunk 通過時間對齊自動綁定 |
---
## Data Model
```
┌─────────────────┐
│ face_detections│
├─────────────────┤
│ id │
│ file_uuid ─────┼───┐
│ frame │ │
│ timestamp │ │
│ trace_id │ │
│ pose_angle │ │
│ confidence │ │
│ embedding (512) │ │
│ identity_id ────┼───┼──┐
└─────────────────┘ │ │
│ │
┌─────────────────┐ │ │
│ files │ │ │
├─────────────────┤ │ │
│ uuid ◄──────────┼───┘ │
│ file_name │ │
│ duration │ │
└─────────────────┘ │
│
┌─────────────────┐ │
│ identities │ │
├─────────────────┤ │
│ id ◄────────────┼──────┘
│ uuid │
│ name │
│ source │
│ face_embedding │ (reference vector)
│ reference_data │ (JSONB, multiple vectors)
└─────────────────┘
│
│ N:N
▼
┌─────────────────┐
│ file_identities │
├─────────────────┤
│ file_uuid │
│ identity_id │
│ face_count │
│ speaker_count │
│ confidence │
└─────────────────┘
```
---
## Binding Workflows
### 1. Manual Registration (New Identity)
**Trigger**: User selects face(s) and assigns name
```
User Selection
│
▼
┌─────────────────────────┐
│ POST /identities/register │
├─────────────────────────┤
│ face_ids: ["face_100"] │
│ name: "Audrey Hepburn" │
│ source: "manual" │
│ auto_bind_chunks: true │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 1. Create Identity │
│ - identity_uuid │
│ - name, source │
│ - face_embedding │ (from first face)
│ - reference_data │ (selected vectors)
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 2. Bind Faces │
│ - Update face_detections │
│ - Set identity_id │
│ - Update file_identities │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 3. Auto Bind Chunks │
│ - Time alignment │
│ - Update chunk.metadata │
│ - Update file_identities.speaker_count │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 4. Select Reference Vectors │
│ - Trace-based selection │
│ - Pose diversity │
│ - Quality threshold │
└─────────────────────────┘
```
**Implementation**:
```rust
pub async fn register_identity(
db: &PgPool,
req: RegisterIdentityRequest,
) -> Result<Identity> {
let mut tx = db.begin().await?;
// 1. Get faces
let faces = sqlx::query_as!(
FaceDetection,
"SELECT * FROM face_detections WHERE id = ANY($1)",
&req.face_ids
)
.fetch_all(&mut *tx)
.await?;
// 2. Create identity
let identity = sqlx::query_as!(
Identity,
r#"
INSERT INTO identities (uuid, name, source, face_embedding, reference_data)
VALUES ($1, $2, $3, $4, $5)
RETURNING *
"#,
Uuid::new_v4().to_string(),
req.name,
req.source,
faces[0].embedding.clone(),
json!({
"vectors": vec![ReferenceVector {
embedding: faces[0].embedding.clone(),
pose_angle: faces[0].pose_angle.clone(),
quality: faces[0].confidence,
file_uuid: faces[0].file_uuid.clone(),
face_id: faces[0].id,
}],
"selection_strategy": "manual"
}),
)
.fetch_one(&mut *tx)
.await?;
// 3. Bind faces
for face in &faces {
sqlx::query!(
"UPDATE face_detections SET identity_id = $1 WHERE id = $2",
identity.id,
face.id
)
.execute(&mut *tx)
.await?;
// Update file_identities
update_file_identity_stats(
&mut tx,
&face.file_uuid,
identity.id,
1, // face_count +1
0, // speaker_count
Some(face.confidence),
Some(face.timestamp),
).await?;
}
// 4. Auto bind chunks
if req.auto_bind_chunks {
auto_bind_chunks_for_identity(&mut tx, &identity.id, &faces).await?;
}
tx.commit().await?;
Ok(identity)
}
```
---
### 2. Bind Faces to Existing Identity
**Trigger**: User selects face(s) and assigns to existing identity
```
User Selection
│
▼
┌────────────────────────────┐
│ POST /identities/:uuid/bind │
├────────────────────────────┤
│ face_ids: ["face_200"] │
│ auto_bind_chunks: true │
└────────────────────────────┘
│
▼
┌─────────────────────────┐
│ 1. Validate Identity │
│ - Check existence │
│ - Get reference_data │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 2. Bind Faces │
│ - Update face_detections │
│ - Set identity_id │
│ - Update file_identities │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 3. Update Reference Vectors │
│ - Add new vector if quality > threshold │
│ - Maintain diversity │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 4. Auto Bind Chunks │
│ - Time alignment │
└─────────────────────────┘
```
**Implementation**:
```rust
pub async fn bind_faces_to_identity(
db: &PgPool,
identity_uuid: &str,
req: BindFacesRequest,
) -> Result<()> {
let mut tx = db.begin().await?;
// 1. Get identity
let identity = sqlx::query_as!(
Identity,
"SELECT * FROM identities WHERE uuid = $1",
identity_uuid
)
.fetch_one(&mut *tx)
.await?;
// 2. Get faces
let faces = sqlx::query_as!(
FaceDetection,
"SELECT * FROM face_detections WHERE id = ANY($1)",
&req.face_ids
)
.fetch_all(&mut *tx)
.await?;
// 3. Bind faces
for face in &faces {
sqlx::query!(
"UPDATE face_detections SET identity_id = $1 WHERE id = $2",
identity.id,
face.id
)
.execute(&mut *tx)
.await?;
update_file_identity_stats(
&mut tx,
&face.file_uuid,
identity.id,
1,
0,
Some(face.confidence),
Some(face.timestamp),
).await?;
}
// 4. Update reference vectors
update_reference_vectors(&mut tx, &identity.id, &faces).await?;
// 5. Auto bind chunks
if req.auto_bind_chunks {
auto_bind_chunks_for_identity(&mut tx, &identity.id, &faces).await?;
}
tx.commit().await?;
Ok(())
}
```
---
### 3. Unbind Faces from Identity
**Trigger**: User removes face from identity
```
User Selection
│
▼
┌──────────────────────────────┐
│ POST /identities/:uuid/unbind │
├──────────────────────────────┤
│ face_ids: ["face_400"] │
└──────────────────────────────┘
│
▼
┌─────────────────────────┐
│ 1. Unbind Faces │
│ - Set identity_id = NULL │
│ - Update file_identities │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 2. Auto Unbind Chunks │
│ - Remove if no overlapping faces │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 3. Update Reference Vectors │
│ - Remove if vector source │
│ - Re-select if needed │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 4. Check Identity Deletion │
│ - If face_count = 0, delete identity │
└─────────────────────────┘
```
---
### 4. Auto Chunk Binding
**Trigger**: Face binding/unbinding
**Principle**: Chunk 自動綁定，無需 Candidates/Suggest API
```
Face Timestamps
│
▼
┌─────────────────────────┐
│ Query Chunks by Time │
│ - chunk.start_time <= face.timestamp │
│ - chunk.end_time >= face.timestamp │
│ - Same file_uuid │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Check Overlap │
│ - Count overlapping faces │
│ - Calculate confidence │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Update Chunk Metadata │
│ - identity_id: ... │
│ - confidence: 0.85 │
│ - binding_source: "auto"│
│ - faces: ["face_100"] │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Update file_identities │
│ - speaker_count += 1 │
└─────────────────────────┘
```
**Implementation**:
```rust
pub async fn auto_bind_chunks_for_identity(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
identity_id: &i64,
faces: &[FaceDetection],
) -> Result<()> {
for face in faces {
// Find overlapping chunks
let chunks = sqlx::query!(
r#"
SELECT id, metadata
FROM chunks
WHERE file_uuid = $1
AND start_time <= $2
AND end_time >= $2
"#,
face.file_uuid,
face.timestamp
)
.fetch_all(&mut **tx)
.await?;
for chunk in chunks {
let mut metadata: ChunkMetadata =
serde_json::from_value(chunk.metadata.clone()).unwrap_or_default();
// Update metadata
if !metadata.faces.contains(&face.id) {
metadata.faces.push(face.id);
}
metadata.identity_id = Some(*identity_id);
metadata.confidence = Some(face.confidence);
metadata.binding_source = "auto".to_string();
sqlx::query!(
r#"
UPDATE chunks
SET metadata = $1
WHERE id = $2
"#,
serde_json::to_value(metadata)?,
chunk.id
)
.execute(&mut **tx)
.await?;
// Update file_identities speaker_count
sqlx::query!(
r#"
UPDATE file_identities
SET speaker_count = speaker_count + 1
WHERE file_uuid = $1 AND identity_id = $2
"#,
face.file_uuid,
identity_id
)
.execute(&mut **tx)
.await?;
}
}
Ok(())
}
```
---
### 5. Reference Vector Selection
**Strategy**: Trace-based + Pose diversity
```
Face Detections (identity_id = X)
│
▼
┌─────────────────────────┐
│ Group by trace_id │
│ - Each trace = one person track │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ For each trace: │
│ - Find best frontal face │
│ - Find best profile faces │
│ - Quality > 0.85 │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Select Top N Vectors │
│ - Max 5 per trace │
│ - Max 20 total │
│ - Prioritize quality │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Store in reference_data │
│ {
│ "vectors": [...],
│ "selection_strategy": "trace_based",
│ "total_traces": 4,
│ "total_faces": 500
│ }
└─────────────────────────┘
```
**Implementation**:
```rust
pub async fn update_reference_vectors(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
identity_id: &i64,
new_faces: &[FaceDetection],
) -> Result<()> {
// Get all faces for this identity
let all_faces = sqlx::query_as!(
FaceDetection,
"SELECT * FROM face_detections WHERE identity_id = $1",
identity_id
)
.fetch_all(&mut **tx)
.await?;
// Group by trace_id
let mut trace_groups: HashMap<i32, Vec<&FaceDetection>> = HashMap::new();
for face in &all_faces {
trace_groups.entry(face.trace_id).or_default().push(face);
}
// Select vectors per trace
let mut selected_vectors = Vec::new();
for (_trace_id, faces) in trace_groups.iter() {
// Group by pose_angle
let mut pose_groups: HashMap<String, Vec<&FaceDetection>> = HashMap::new();
for face in faces {
pose_groups
.entry(face.pose_angle.clone())
.or_default()
.push(face);
}
// Select best from each pose (max 5 per trace)
for (_, pose_faces) in pose_groups.iter() {
let best = pose_faces
.iter()
.filter(|f| f.confidence > 0.85)
.max_by(|a, b| a.confidence.partial_cmp(&b.confidence).unwrap());
if let Some(face) = best {
selected_vectors.push(ReferenceVector {
embedding: face.embedding.clone(),
pose_angle: face.pose_angle.clone(),
quality: face.confidence,
file_uuid: face.file_uuid.clone(),
face_id: face.id,
});
}
}
}
// Sort by quality and take top 20
selected_vectors.sort_by(|a, b| b.quality.partial_cmp(&a.quality).unwrap());
selected_vectors.truncate(20);
// Update identity
sqlx::query!(
r#"
UPDATE identities
SET reference_data = $1
WHERE id = $2
"#,
json!({
"vectors": selected_vectors,
"selection_strategy": "trace_based",
"total_traces": trace_groups.len(),
"total_faces": all_faces.len(),
}),
identity_id
)
.execute(&mut **tx)
.await?;
Ok(())
}
```
---
## Query Workflows
### 1. List Identities in File
```bash
GET /api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/identities
```
**SQL**:
```sql
SELECT
i.uuid AS identity_uuid,
i.name,
i.source,
fi.face_count,
fi.speaker_count,
fi.confidence
FROM file_identities fi
JOIN identities i ON i.id = fi.identity_id
WHERE fi.file_uuid = '384b0ff44aaaa1f14cb2cd63b3fea966'
ORDER BY fi.face_count DESC;
```
---
### 2. List Files for Identity
```bash
GET /api/v1/identities/a9a90105.../files
```
**SQL**:
```sql
SELECT
f.uuid AS file_uuid,
f.file_name,
f.duration,
fi.face_count,
fi.speaker_count,
fi.first_appearance,
fi.last_appearance,
fi.confidence
FROM file_identities fi
JOIN files f ON f.uuid = fi.file_uuid
WHERE fi.identity_id = 1
ORDER BY fi.face_count DESC;
```
---
### 3. List Faces for Identity
```bash
GET /api/v1/identities/a9a90105.../faces?limit=100
```
**SQL**:
```sql
SELECT
fd.id AS face_id,
fd.file_uuid,
fd.frame,
fd.timestamp,
fd.pose_angle,
fd.confidence,
fd.trace_id
FROM face_detections fd
WHERE fd.identity_id = 1
ORDER BY fd.timestamp
LIMIT 100;
```
---
### 4. List Unregistered Faces (Candidates)
```bash
GET /api/v1/faces/candidates?min_confidence=0.8&pose_angle=frontal
```
**SQL**:
```sql
SELECT
fd.id AS face_id,
fd.file_uuid,
fd.frame,
fd.timestamp,
fd.pose_angle,
fd.confidence,
fd.trace_id
FROM face_detections fd
WHERE fd.identity_id IS NULL
AND fd.confidence >= 0.8
AND fd.pose_angle = 'frontal'
ORDER BY fd.confidence DESC
LIMIT 100;
```
---
## Performance Considerations
### Indexing Strategy
```sql
-- Face queries
CREATE INDEX idx_face_detections_identity ON face_detections(identity_id)
WHERE identity_id IS NOT NULL;
CREATE INDEX idx_face_detections_candidates ON face_detections(confidence DESC)
WHERE identity_id IS NULL;
-- File identity queries
CREATE INDEX idx_file_identities_file_uuid ON file_identities(file_uuid);
CREATE INDEX idx_file_identities_identity_id ON file_identities(identity_id);
-- Chunk queries
CREATE INDEX idx_chunks_file_time ON chunks(file_uuid, start_time, end_time);
```
### Batch Operations
```rust
// Batch bind faces (recommended for >10 faces)
pub async fn batch_bind_faces(
db: &PgPool,
identity_id: i64,
face_ids: &[i64],
) -> Result<()> {
let mut tx = db.begin().await?;
// Single UPDATE statement
sqlx::query!(
"UPDATE face_detections SET identity_id = $1 WHERE id = ANY($2)",
identity_id,
face_ids
)
.execute(&mut *tx)
.await?;
// Batch update file_identities
// ... (use CTE or temp table)
tx.commit().await?;
Ok(())
}
```
---
## Error Handling
### Common Errors
| Error | Cause | Solution |
|-------|-------|----------|
| `Identity not found` | Invalid identity_uuid | Check UUID format |
| `Face already bound` | Face has identity_id | Unbind first |
| `Invalid face_ids` | Empty array or invalid IDs | Validate input |
| `Chunk overlap conflict` | Multiple identities in same chunk | Use latest binding |
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Two-layer architecture, direct binding |
---
## Related Documents
- [IDENTITY_MANAGEMENT_API.md](./IDENTITY_MANAGEMENT_API.md): API design
- [FILE_IDENTITIES_TABLE_SPEC.md](./FILE_IDENTITIES_TABLE_SPEC.md): Table schema
- [IDENTITY_AGENT_SPEC.md](./IDENTITY_AGENT_SPEC.md): Agent specification

434
docs_v1.0/AI_AGENTS/IDENTITY/FILE_IDENTITIES_TABLE_SPEC.md Normal file
View File

@@ -0,0 +1,434 @@
# File Identities Table Specification
> Version: V4.0 | Date: 2026-04-28
> Architecture: Two-layer (Face → Identity)
> Relationship: N:N (Identity ↔ File)
---
## Overview
`file_identities` 表實現 Identity 與 File 的多對多關係，支援跨檔案身份追蹤。
### Key Features
| Feature | Description |
|---------|-------------|
| **N:N Relationship** | Identity 可跨多個 File，File 可包含多個 Identity |
| **Aggregate Stats** | 統計每個 File 中每個 Identity 的出現次數 |
| **Time Range** | 記錄首次/最後出現時間 |
| **Confidence** | 平均信心度 |
---
## Table Schema
```sql
CREATE TABLE file_identities (
id BIGSERIAL PRIMARY KEY,
file_uuid VARCHAR(64) NOT NULL,
identity_id BIGINT NOT NULL,
face_count INTEGER DEFAULT 0,
speaker_count INTEGER DEFAULT 0,
first_appearance DOUBLE PRECISION,
last_appearance DOUBLE PRECISION,
confidence DOUBLE PRECISION DEFAULT 0.0,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
CONSTRAINT fk_file_identities_file
FOREIGN KEY (file_uuid)
REFERENCES files(uuid)
ON DELETE CASCADE,
CONSTRAINT fk_file_identities_identity
FOREIGN KEY (identity_id)
REFERENCES identities(id)
ON DELETE CASCADE,
CONSTRAINT uq_file_identities
UNIQUE (file_uuid, identity_id)
);
CREATE INDEX idx_file_identities_file_uuid ON file_identities(file_uuid);
CREATE INDEX idx_file_identities_identity_id ON file_identities(identity_id);
CREATE INDEX idx_file_identities_confidence ON file_identities(confidence DESC);
```
---
## Column Descriptions
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| `id` | BIGSERIAL | Primary key | `1` |
| `file_uuid` | VARCHAR(64) | File identifier (FK to files.uuid) | `384b0ff44aaaa1f14cb2cd63b3fea966` |
| `identity_id` | BIGINT | Identity ID (FK to identities.id) | `1` |
| `face_count` | INTEGER | Number of faces bound to identity in this file | `500` |
| `speaker_count` | INTEGER | Number of speaker segments bound | `10` |
| `first_appearance` | DOUBLE PRECISION | First appearance time in seconds | `5.2` |
| `last_appearance` | DOUBLE PRECISION | Last appearance time in seconds | `180.5` |
| `confidence` | DOUBLE PRECISION | Average confidence score | `0.86` |
| `created_at` | TIMESTAMPTZ | Record creation time | `2026-04-28T10:00:00Z` |
| `updated_at` | TIMESTAMPTZ | Record update time | `2026-04-28T12:00:00Z` |
---
## Relationships
### Identity → Files (One-to-Many)
```
identities (1) ──→ file_identities (N) ──→ files (N)
```
**Query**: List all files where an identity appears
```sql
SELECT
f.uuid AS file_uuid,
f.file_name,
fi.face_count,
fi.speaker_count,
fi.first_appearance,
fi.last_appearance,
fi.confidence
FROM file_identities fi
JOIN files f ON f.uuid = fi.file_uuid
WHERE fi.identity_id = ?
ORDER BY fi.face_count DESC;
```
### File → Identities (One-to-Many)
```
files (1) ──→ file_identities (N) ──→ identities (N)
```
**Query**: List all identities in a file
```sql
SELECT
i.uuid AS identity_uuid,
i.name,
i.source,
fi.face_count,
fi.speaker_count,
fi.confidence
FROM file_identities fi
JOIN identities i ON i.id = fi.identity_id
WHERE fi.file_uuid = ?
ORDER BY fi.face_count DESC;
```
---
## Data Flow
### 1. Face Binding
When a face is bound to an identity:
```sql
-- Step 1: Create file_identities record if not exists
INSERT INTO file_identities (file_uuid, identity_id, face_count, confidence)
VALUES (?, ?, 1, ?)
ON CONFLICT (file_uuid, identity_id)
DO UPDATE SET
face_count = file_identities.face_count + 1,
confidence = (file_identities.confidence * file_identities.face_count + EXCLUDED.confidence) / (file_identities.face_count + 1),
updated_at = NOW();
-- Step 2: Update first/last appearance
UPDATE file_identities
SET
first_appearance = LEAST(first_appearance, ?),
last_appearance = GREATEST(last_appearance, ?)
WHERE file_uuid = ? AND identity_id = ?;
```
### 2. Face Unbinding
When a face is unbound from an identity:
```sql
-- Step 1: Get face info before unbinding
SELECT file_uuid, confidence FROM face_detections WHERE id = ?;
-- Step 2: Update file_identities
UPDATE file_identities
SET
face_count = face_count - 1,
updated_at = NOW()
WHERE file_uuid = ? AND identity_id = ?;
-- Step 3: Delete if face_count = 0
DELETE FROM file_identities
WHERE file_uuid = ? AND identity_id = ? AND face_count = 0;
```
### 3. Chunk Binding (Auto)
When a chunk is auto-bound to an identity via time alignment:
```sql
-- Update speaker_count
UPDATE file_identities
SET
speaker_count = speaker_count + 1,
updated_at = NOW()
WHERE file_uuid = ? AND identity_id = ?;
```
---
## Indexes
| Index | Purpose |
|-------|---------|
| `idx_file_identities_file_uuid` | Query identities by file |
| `idx_file_identities_identity_id` | Query files by identity |
| `idx_file_identities_confidence` | Sort by confidence |
---
## Constraints
### Foreign Keys
| Constraint | On Delete | Description |
|------------|-----------|-------------|
| `fk_file_identities_file` | CASCADE | Delete file_identities when file is deleted |
| `fk_file_identities_identity` | CASCADE | Delete file_identities when identity is deleted |
### Unique Constraint
```sql
CONSTRAINT uq_file_identities UNIQUE (file_uuid, identity_id)
```
Ensures one record per file-identity pair.
---
## Query Patterns
### 1. Get Identity Files
```rust
pub async fn get_identity_files(
db: &PgPool,
identity_uuid: &str,
page: i64,
page_size: i64,
) -> Result<IdentityFilesResponse> {
let rows = sqlx::query_as!(
FileIdentityRow,
r#"
SELECT
f.uuid AS file_uuid,
f.file_name,
f.duration,
fi.face_count,
fi.speaker_count,
fi.first_appearance,
fi.last_appearance,
fi.confidence
FROM file_identities fi
JOIN files f ON f.uuid = fi.file_uuid
JOIN identities i ON i.id = fi.identity_id
WHERE i.uuid = $1
ORDER BY fi.face_count DESC
LIMIT $2 OFFSET $3
"#,
identity_uuid,
page_size,
(page - 1) * page_size
)
.fetch_all(db)
.await?;
Ok(IdentityFilesResponse { files: rows })
}
```
### 2. Get File Identities
```rust
pub async fn get_file_identities(
db: &PgPool,
file_uuid: &str,
page: i64,
page_size: i64,
) -> Result<FileIdentitiesResponse> {
let rows = sqlx::query_as!(
IdentityRow,
r#"
SELECT
i.uuid AS identity_uuid,
i.name,
i.source,
fi.face_count,
fi.speaker_count,
fi.confidence
FROM file_identities fi
JOIN identities i ON i.id = fi.identity_id
WHERE fi.file_uuid = $1
ORDER BY fi.face_count DESC
LIMIT $2 OFFSET $3
"#,
file_uuid,
page_size,
(page - 1) * page_size
)
.fetch_all(db)
.await?;
Ok(FileIdentitiesResponse { identities: rows })
}
```
### 3. Update Stats
```rust
pub async fn update_file_identity_stats(
db: &PgPool,
file_uuid: &str,
identity_id: i64,
face_count_delta: i32,
speaker_count_delta: i32,
confidence: Option<f64>,
timestamp: Option<f64>,
) -> Result<()> {
sqlx::query!(
r#"
INSERT INTO file_identities (file_uuid, identity_id, face_count, speaker_count, confidence, first_appearance, last_appearance)
VALUES ($1, $2, $3, $4, $5, $6, $6)
ON CONFLICT (file_uuid, identity_id)
DO UPDATE SET
face_count = file_identities.face_count + $3,
speaker_count = file_identities.speaker_count + $4,
confidence = CASE
WHEN $5 IS NOT NULL AND file_identities.face_count > 0
THEN (file_identities.confidence * file_identities.face_count + $5) / (file_identities.face_count + $3)
ELSE file_identities.confidence
END,
first_appearance = CASE
WHEN $6 IS NOT NULL
THEN LEAST(file_identities.first_appearance, $6)
ELSE file_identities.first_appearance
END,
last_appearance = CASE
WHEN $6 IS NOT NULL
THEN GREATEST(file_identities.last_appearance, $6)
ELSE file_identities.last_appearance
END,
updated_at = NOW()
"#,
file_uuid,
identity_id,
face_count_delta,
speaker_count_delta,
confidence,
timestamp
)
.execute(db)
.await?;
Ok(())
}
```
---
## Migration
### V3.x → V4.0
**Before (V3.x)**:
- `person_identities` table (303 records, 0 registered identities)
- One-to-many relationship (person → identities)
- Video-local person IDs
**After (V4.0)**:
- `file_identities` table (new)
- Many-to-many relationship (identity ↔ file)
- Global identity UUIDs
- Direct face → identity binding
### Migration Script
```sql
-- Step 1: Create file_identities table
CREATE TABLE file_identities ( ... );
-- Step 2: Populate from face_detections
INSERT INTO file_identities (file_uuid, identity_id, face_count, confidence, first_appearance, last_appearance)
SELECT
fd.file_uuid,
fd.identity_id,
COUNT(*) AS face_count,
AVG(fd.confidence) AS confidence,
MIN(fd.timestamp) AS first_appearance,
MAX(fd.timestamp) AS last_appearance
FROM face_detections fd
WHERE fd.identity_id IS NOT NULL
GROUP BY fd.file_uuid, fd.identity_id;
-- Step 3: Update speaker_count from chunks
UPDATE file_identities fi
SET speaker_count = (
SELECT COUNT(DISTINCT c.id)
FROM chunks c
WHERE c.file_uuid = fi.file_uuid
AND c.metadata->>'identity_id' = fi.identity_id::text
);
-- Step 4: Drop person_identities table
DROP TABLE IF EXISTS person_identities;
```
---
## Performance Considerations
### Index Strategy
| Query Pattern | Index |
|---------------|-------|
| Get identities by file | `idx_file_identities_file_uuid` |
| Get files by identity | `idx_file_identities_identity_id` |
| Sort by confidence | `idx_file_identities_confidence` |
### Query Optimization
1. **Use JOINs sparingly**: Fetch identity/file data separately when possible
2. **Pagination**: Always use `LIMIT` and `OFFSET`
3. **Batch updates**: Use transactions for bulk face binding
### Caching Strategy
```rust
// Redis cache key patterns
const CACHE_KEY_FILE_IDENTITIES: &str = "momentry:file_identities:{}";
const CACHE_KEY_IDENTITY_FILES: &str = "momentry:identity_files:{}";
// Cache TTL (5 minutes)
const CACHE_TTL: i64 = 300;
```
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Initial design (N:N relationship) |
---
## Related Documents
- [IDENTITY_MANAGEMENT_API.md](./IDENTITY_MANAGEMENT_API.md): Identity API design
- [IDENTITY_AGENT_SPEC.md](./IDENTITY_AGENT_SPEC.md): Identity Agent specification
- [FACE_TO_IDENTITY_FLOW.md](./FACE_TO_IDENTITY_FLOW.md): Face binding workflow

549
docs_v1.0/AI_AGENTS/IDENTITY/IDENTITY_AGENT_SPEC.md Normal file
View File

@@ -0,0 +1,549 @@
---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Identity Agent Design Specification"
date: "2026-04-28"
version: "V2.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "identity-agent"
- "agent"
- "face-clustering"
- "embedding-matching"
- "multi-file-aggregation"
ai_query_hints:
- "Identity Agent design specification"
- "Face to Identity inference flow"
- "Multi-file identity aggregation"
- "Embedding matching with pose adaptation"
related_documents:
- "AI_AGENTS/CORE/AGENT_SPEC.md"
- "AI_AGENTS/IDENTITY/IDENTITY_MANAGEMENT_API.md"
- "FILE_IDENTITIES_TABLE_SPEC.md"
---
# Identity Agent Design Specification
| Item | Content |
|------|---------|
| Creator | OpenCode |
| Date | 2026-04-28 |
| Version | V2.0 (Two-layer Architecture) |
---
## Version History
| Version | Date | Changes | Author |
|---------|------|---------|--------|
| V2.0 | 2026-04-28 | Two-layer architecture (Face → Identity) | OpenCode |
| V1.0 | 2026-04-27 | Initial design (three-layer) | OpenCode |
---
## Overview
Identity Agent is an L3 Agent in Momentry Core, responsible for inferring "Who is Who" from Face Processor outputs and aggregating identities across multiple files.
---
## Architecture Change (V1.0 → V2.0)
| Aspect | V1.0 (Deprecated) | V2.0 (Current) |
|--------|-------------------|----------------|
| **Layers** | Face → Person → Identity | Face → Identity (2 layers) |
| **person_identities** | Required table | Removed (deprecated) |
| **Binding** | Person → Identity | Face → Identity (direct) |
| **Chunks** | Person → Chunk | Face → Chunk (auto-bind by time) |
---
## Current Status
| Component | Status |
|-----------|--------|
| Face Processor | ✅ Implemented (InsightFace) |
| Face Tracker | ✅ Implemented (trace_id) |
| ASRX Processor | ✅ Implemented (WhisperX) |
| Identity Agent | 🔧 Pending implementation |
---
## 1. Agent Goals
### 1.1 Core Problem
**Question**: How to infer global Identity from Face embeddings across multiple files?
**Challenges**:
1. **Same person in different files**: Need cross-file matching
2. **Different poses**: frontal vs profile have different thresholds
3. **Temporal alignment**: Chunks need time-based binding
4. **Quality variance**: Low-quality faces need filtering
---
### 1.2 Agent Goals
Aggregate evidence across files to create/maintain global Identities:
| Evidence Source | Input | Output |
|-----------------|-------|--------|
| **Face Processor** | Face embedding + pose_angle | Face → identity_id |
| **Face Tracker** | trace_id (face tracking) | Trace statistics |
| **ASRX Processor** | Speaker segments | Chunk → identity_id (auto-bind) |
| **Identity Agent** | Face + trace + time | **Identity** (global) |
---
## 2. Data Flow (Two-layer)
```
File → InsightFace → face_full_traced.json
↓
face_id + embedding + pose_angle + trace_id
↓
Identity Agent
↓
┌─────────────────────────────────────┐
│ Step 1: Select unregistered face │
│ Step 2: Register identity │
│ Step 3: Embedding matching │
│ Step 4: Bind faces → identity_id │
│ Step 5: Auto-bind chunks │
└─────────────────────────────────────┘
↓
identities + file_identities tables
```
---
## 3. Input Data
### 3.1 Face Data Structure
```json
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"fps": 59.94,
"metadata": {
"trace_stats": {
"total_traces": 4,
"long_traces": 3
}
},
"frames": {
"100": {
"faces": [
{
"face_id": "face_100",
"confidence": 0.92,
"embedding": [512-dim vector],
"pose_angle": {
"angle": "frontal",
"yaw": -5.2,
"pitch": 2.1,
"confidence": 0.95
},
"trace_id": 2,
"identity_id": null
}
]
}
},
"traces": {
"2": {
"trace_id": 2,
"total_appearances": 143,
"avg_confidence": 0.86,
"pose_distribution": {
"frontal": 20,
"profile_right": 125
}
}
}
}
```
---
### 3.2 Data Sources
| Data | Source File | Description |
|------|--------------|-------------|
| **Face frames** | `{uuid}.face_full_traced_v2.json` | Face detection + embedding + trace |
| **Speaker segments** | `{uuid}.asrx.json` | Speaker time segments |
| **Chunks** | `chunks` table | Sentence chunks (from pre_chunks) |
---
## 4. Core Logic
### 4.1 Inference Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Identity Agent Workflow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Candidates Query │
│ ───────────────────────────── │
│ Query: GET /api/v1/faces/candidates │
│ Filter: identity_id = NULL, confidence >= 0.8 │
│ Result: Unregistered faces list │
│ │
│ Step 2: AI Suggestion │
│ ───────────────── │
│ Query: POST /api/v1/agents/suggest/clustering │
│ Input: Unregistered faces │
│ Output: Cluster suggestions + recommended primary face │
│ │
│ Step 3: Identity Registration │
│ ───────────────────────────── │
│ Query: POST /api/v1/identities/register │
│ Input: face_ids + name │
│ Output: identity_uuid │
│ │
│ Step 4: Face Binding │
│ ───────────────── │
│ For each face in same trace: │
│ Calculate: embedding_similarity(face, identity.embedding) │
│ Apply: adaptive_threshold(pose_angle) │
│ If similarity > threshold: │
│ UPDATE face_detections SET identity_id = identity.id │
│ │
│ Step 5: Chunk Auto-Binding │
│ ───────────────────────────── │
│ For each face with identity_id: │
│ Query: chunks WHERE time overlaps face timestamp │
│ Update: chunk.metadata.identity_id = identity.uuid │
│ Update: chunk.metadata.chunk_identity.faces.push(face_id) │
│ │
│ Step 6: Statistics Aggregation │
│ ─────────────────────────────── │
│ Update: file_identities (face_count, speaker_count) │
│ Update: identities.metadata (global stats) │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
### 4.2 Adaptive Threshold
**Pose-based threshold strategy**:
```python
def get_adaptive_threshold(pose_angle: str) -> float:
"""Get matching threshold based on pose angle"""
thresholds = {
"frontal": 0.90, # Strict for frontal
"three_quarter": 0.85, # Moderate
"profile_left": 0.80, # Relaxed for profile
"profile_right": 0.80,
}
return thresholds.get(pose_angle, 0.75)
```
**Reasoning**:
- Frontal faces have best embedding quality → strict threshold
- Profile faces have distorted embedding → relaxed threshold
- Three_quarter is intermediate
---
### 4.3 Embedding Matching
```python
def match_face_to_identity(
face_embedding: List[float],
identity_embedding: List[float],
pose_angle: str
) -> Tuple[bool, float]:
"""Match face to identity with pose-adaptive threshold"""
similarity = cosine_similarity(face_embedding, identity_embedding)
threshold = get_adaptive_threshold(pose_angle)
is_match = similarity > threshold
return is_match, similarity
```
---
### 4.4 Chunk Auto-Binding
```python
def bind_chunks_to_identity(
identity_id: int,
file_uuid: str,
pool: PgPool
) -> int:
"""Auto-bind chunks by time alignment"""
# Get face time ranges
faces = sqlx::query(
"SELECT timestamp, pose_angle
FROM face_detections
WHERE identity_id = $1 AND file_uuid = $2"
).bind(identity_id).bind(file_uuid).fetch_all(pool)
# Find overlapping chunks
chunks_updated = 0
for face in faces:
chunks = sqlx::query(
"UPDATE chunks
SET metadata = jsonb_set(
metadata, '{chunk_identity}',
jsonb_build_object(
'identity_id', $1::text,
'binding_source', 'auto'
)
)
WHERE file_uuid = $2
AND ABS(start_time - $3) < 2.0"
).bind(identity_id).bind(file_uuid).bind(face.timestamp)
.execute(pool)
chunks_updated += chunks.rowcount()
return chunks_updated
```
---
## 5. Database Schema
### 5.1 identities Table
| Field | Type | Description |
|-------|------|-------------|
| `uuid` | UUID | identity_uuid (global) |
| `name` | VARCHAR | Identity name |
| `face_embedding` | VECTOR(512) | Reference embedding |
| `reference_data` | JSONB | Multi-angle reference vectors |
| `metadata` | JSONB | Global statistics |
---
### 5.2 file_identities Table (N:N)
| Field | Type | Description |
|-------|------|-------------|
| `file_uuid` | UUID | File UUID |
| `identity_id` | BIGINT | Identity ID |
| `face_count` | INT | Faces in this file |
| `speaker_count` | INT | Speaker segments |
| `first_appearance` | FLOAT | First appearance time |
| `last_appearance` | FLOAT | Last appearance time |
| `confidence` | FLOAT | Avg confidence |
---
### 5.3 face_detections Table
| Field | Type | Description |
|-------|------|-------------|
| `identity_id` | BIGINT | Bound identity (direct) |
| `file_uuid` | UUID | File UUID |
| `pose_angle` | VARCHAR | Pose angle |
| `embedding` | VECTOR(512) | Face embedding |
| `trace_id` | INT | Trace ID (from Face Tracker) |
---
### 5.4 chunks.metadata Structure
```json
{
"chunk_identity": {
"faces": [100, 150],
"speakers": ["SPEAKER_0"],
"identity_id": "a9a90105-...",
"confidence": 0.88,
"binding_source": "auto"
}
}
```
---
## 6. API Design
### 6.1 Candidates API
```http
GET /api/v1/faces/candidates
?min_confidence=0.8
&pose_angle=frontal
&page=1
&page_size=15
&limit=100
```
**Response**:
```json
{
"candidates": [
{
"face_id": "face_100",
"pose_angle": "frontal",
"confidence": 0.92,
"trace_id": 2
}
]
}
```
---
### 6.2 Suggest API
```http
POST /api/v1/agents/suggest/clustering
{
"min_confidence": 0.8,
"max_suggestions": 5
}
```
**Response**:
```json
{
"suggestions": [
{
"cluster_type": "high_confidence",
"recommended_faces": ["face_100"],
"action": "register"
}
]
}
```
---
### 6.3 Register API
```http
POST /api/v1/identities/register
{
"face_ids": ["face_100"],
"name": "Person A",
"auto_bind_chunks": true
}
```
---
## 7. Multi-File Aggregation
### 7.1 Cross-File Matching
When a new file is processed:
1. **Query existing identities**: `SELECT * FROM identities`
2. **For each unregistered face**:
- Calculate similarity with all identity.face_embedding
- Apply adaptive threshold
- If match: bind to existing identity
3. **If no match**: create new identity
---
### 7.2 Statistics Update
```sql
-- Update file_identities after binding
INSERT INTO file_identities (
file_uuid, identity_id, face_count, confidence
)
SELECT
file_uuid,
identity_id,
COUNT(*),
AVG(confidence)
FROM face_detections
WHERE identity_id IS NOT NULL
GROUP BY file_uuid, identity_id
ON CONFLICT (file_uuid, identity_id)
DO UPDATE SET
face_count = EXCLUDED.face_count,
confidence = EXCLUDED.confidence;
```
---
## 8. Implementation Plan
### 8.1 Phase 1: Core Matching
| Task | Status |
|------|--------|
| Adaptive threshold function | Pending |
| Embedding matching logic | Pending |
| Face → Identity binding | Pending |
| Chunk auto-binding | Pending |
---
### 8.2 Phase 2: Candidates API
| Task | Status |
|------|--------|
| Candidates query endpoint | Pending |
| Pose distribution statistics | Pending |
| Trace-based filtering | Pending |
---
### 8.3 Phase 3: Suggest API
| Task | Status |
|------|--------|
| Clustering suggestion logic | Pending |
| Primary face recommendation | Pending |
| Merge suggestion | Pending |
---
### 8.4 Phase 4: Statistics
| Task | Status |
|------|--------|
| file_identities aggregation | Pending |
| identities.metadata update | Pending |
| Cross-file identity stats | Pending |
---
## 9. Key Decisions
| Decision | Reason |
|----------|--------|
| **Remove person_identities** | Middle layer adds complexity, unused (303 records, 0 registered) |
| **Face → Identity direct** | Simpler, embedding comparison is sufficient |
| **Adaptive threshold** | Pose affects embedding quality |
| **Chunk auto-bind** | Chunks follow faces by time alignment |
| **file_identities table** | Needed for N:N relationship tracking |
---
## 10. Metrics
| Metric | Target |
|--------|--------|
| **Matching accuracy** | > 90% for frontal |
| **False positive rate** | < 5% |
| **Processing speed** | 1000 faces/second |
| **Cross-file recall** | > 85% |
---
## Version Information
- Version: V2.0
- Architecture: Two-layer (Face → Identity)
- Date: 2026-04-28
- Status: Specification complete, implementation pending

550
docs_v1.0/AI_AGENTS/IDENTITY/IDENTITY_MANAGEMENT_API.md
View File

@@ -1,214 +1,434 @@
# 📘 Momentry 身份管理 (Identity Management) API 實作指南 # Momentry Identity Management API Guide
本文件示範如何透過 API 完成「從影片選擇 → 臉部分析 → 全域身份註冊」的完整流程。 > Version: 4.0 | Updated: 2026-04-28
> Architecture: Two-layer (Face → Identity)
## 1. 選擇目標影片 > Terminology: file_uuid, identity_uuid
**目標**: 獲取系統中已註冊的影片列表，選擇要進行管理的影片。
**API**: `GET /api/v1/videos`
```bash
curl -s "http://127.0.0.1:3002/api/v1/videos" \
-H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq .
```
**回應範例**:
```json
{
"videos": [
{
"uuid": "384b0ff44aaaa1f1",
"file_name": "Old_Time_Movie_Show_-_Charade_1963.HD.mov",
"duration": 6879.33
},
{
"uuid": "9760d0820f0cf9a7",
"file_name": "ExaSAN PCIe series - Director Ou.mp4",
"duration": 159.64
}
]
}
```
> **決策**: 我們選擇 `Charade 1963` (UUID: `384b0ff44aaaa1f1`) 進行管理。
--- ---
## 2. 分析影片內的所有人物 (Faces / Persons / Speakers) ## Overview
**目標**: 查看該影片內所有偵測到的「臉群 (Clusters)」。區分**已命名 (Named)**、**待命名 (Unregistered)** 與 **AI 建議**。 This guide demonstrates the complete workflow for:
- Choosing a video file
- Analyzing faces (unregistered candidates)
- Registering global identities
- Managing identity ↔ file relationships
**API**: `GET /api/v1/videos/{uuid}/faces` ---
## Terminology
| Term | Scope | Example |
|------|-------|---------|
| **file_uuid** | Video file identifier | `384b0ff44aaaa1f14cb2cd63b3fea966` |
| **identity_uuid** | Global identity identifier | `a9a90105-6d6b-...` |
| **face_id** | Single face detection | `face_100` |
| **trace_id** | Face tracking ID | `2` |
**Note**: `person_id` (video-local identifier) is deprecated. Use direct Face → Identity binding.
---
## 1. List Files
**Endpoint**: `GET /api/v1/files`
```bash ```bash
curl -s "http://127.0.0.1:3002/api/v1/videos/384b0ff44aaaa1f1/faces" \ curl -s "http://127.0.0.1:3003/api/v1/files" \
-H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq . -H "X-API-Key: YOUR_API_KEY" | jq .
``` ```
**回應範例**: **Response**:
```json ```json
{ {
"success": true, "success": true,
"video_uuid": "384b0ff44aaaa1f1", "data": {
"total_faces": 6, "files": [
"registered_count": 0, {
"unregistered_count": 6, "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"clusters": [ "file_name": "Charade_1963.mp4",
{ "duration": 6879.33,
"cluster_id": "Person_4", "status": "completed"
"face_count": 45, }
"status": "unregistered", ]
"identity": { }
"name": "Cary Grant", }
"is_confirmed": true ```
---
## 2. List Unregistered Faces (Candidates)
**Endpoint**: `GET /api/v1/faces/candidates`
Query faces that have not been bound to any identity.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `file_uuid` | UUID | No | - | Filter by file |
| `min_confidence` | float | No | 0.5 | Minimum confidence |
| `pose_angle` | string | No | - | Filter by pose (frontal/profile) |
| `page` | int | No | 1 | Page number |
| `page_size` | int | No | 15 | Items per page |
| `limit` | int | No | 100 | Total limit |
```bash
curl -s "http://127.0.0.1:3003/api/v1/faces/candidates?min_confidence=0.8" \
-H "X-API-Key: YOUR_API_KEY" | jq .
```
**Response**:
```json
{
"success": true,
"data": {
"candidates": [
{
"face_id": "face_100",
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"frame": 100,
"timestamp": 5.2,
"pose_angle": "frontal",
"confidence": 0.92,
"trace_id": 2,
"embedding_quality": 0.88
}
],
"statistics": {
"total_candidates": 78,
"pose_distribution": {
"frontal": 20,
"profile_right": 30,
"three_quarter": 18
} }
}, },
{ "pagination": {
"cluster_id": "Person_17", "page": 1,
"face_count": 32, "page_size": 15,
"status": "unregistered", "total": 78,
"identity": { "total_pages": 6
"name": "Audrey Hepburn",
"is_confirmed": true
}
},
{
"cluster_id": "Person_12",
"face_count": 10,
"status": "unregistered",
"identity": { "name": "Person_12" }
},
{
"cluster_id": "Person_124",
"face_count": 5,
"status": "unregistered",
"identity": null
} }
] }
}
```
### 如何解讀結果？
| 欄位 | 說明 | 狀態 |
| :--- | :--- | :--- |
| **`identity.name`** | 若顯示具體人名 (如 "Audrey Hepburn")，代表 **已命名**。 | ✅ 待註冊 |
| **`identity.name`** | 若顯示 `Person_XX` (系統預設名)，代表 **待命名**。 | 🔄 等待 AI 或人工命名 |
| **`identity: null`** | 代表完全 **未識別**，通常數量較少。 | ❓ 待處理 |
---
## 3. 註冊全域身份 (Register Identity)
**目標**: 將已命名的人物升級為 **全域身份 (Global Identity)**。這能讓系統在其他影片中自動認出他們。
**API**: `POST /api/v1/person/{person_id}/register?video_uuid={uuid}`
### 3.1 註冊 Audrey Hepburn
```bash
curl -s -X POST "http://127.0.0.1:3002/api/v1/person/Person_17/register?video_uuid=384b0ff44aaaa1f1" \
-H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq .
```
**回應**:
```json
{
"success": true,
"message": "Successfully registered as global identity",
"person_id": "Person_17",
"name": "Audrey Hepburn",
"face_identity_id": 12
}
```
### 3.2 註冊 Cary Grant
```bash
curl -s -X POST "http://127.0.0.1:3002/api/v1/person/Person_4/register?video_uuid=384b0ff44aaaa1f1" \
-H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq .
```
**回應**:
```json
{
"success": true,
"face_identity_id": 13,
"name": "Cary Grant"
} }
``` ```
--- ---
## ✅ 驗證成果 ## 3. AI Suggest Clustering
現在可以使用全域搜尋 API 確認身份是否註冊成功： **Endpoint**: `POST /api/v1/agents/suggest/clustering`
AI Agent analyzes unregistered faces and suggests clustering.
```bash ```bash
curl -s -X POST "http://127.0.0.1:3002/api/v1/identities/search" \ curl -s -X POST "http://127.0.0.1:3003/api/v1/agents/suggest/clustering" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "x-api-key: muser_..." \ -H "X-API-Key: YOUR_API_KEY" \
-d '{"query": "Audrey"}' | jq '.identities[] | {name: .profile.name, identity_id: .face_identity_id}' -d '{
"min_confidence": 0.8,
"pose_angles": ["frontal"],
"max_suggestions": 5
}' | jq .
``` ```
**結果**: **Response**:
```json ```json
{ {
"name": "Audrey Hepburn", "success": true,
"identity_id": 12 "data": {
"suggestions": [
{
"suggestion_id": "suggest_1",
"cluster_type": "high_confidence",
"confidence": 0.92,
"recommended_faces": [
{
"face_id": "face_100",
"pose_angle": "frontal",
"confidence": 0.95,
"is_primary": true
},
{
"face_id": "face_150",
"pose_angle": "frontal",
"confidence": 0.91
}
],
"cluster_stats": {
"total_faces": 50,
"avg_similarity": 0.89,
"trace_ids": [2, 3]
},
"reason": "High confidence frontal faces from same trace",
"action": "register"
}
]
}
} }
``` ```
--- ---
## 4. 擷取身份 / 人物 / 臉部 截圖 ## 4. Register Identity from Faces
**目標**: 取得特定人物的臉部特寫截圖。 **Endpoint**: `POST /api/v1/identities/register`
由於「Identity (全域身份)」是由多個影片中的「Person (區域人物)」組成，而「Person」是由多個「Face (臉部偵測點)」聚合而成，因此擷取截圖的核心是取得 **該人物在某部影片中的某幀臉部影像**。
**API**: `GET /api/v1/person/{person_id}/thumbnail` Register a new global identity from face candidates.
### 參數說明
| 參數 | 類型 | 必填 | 說明 |
| :--- | :--- | :--- | :--- |
| `person_id` | Path | ✅ | 人物 ID (例如: `Person_17`) |
| `video_uuid` | Query | ✅ | 影片 UUID (用來定位影像源) |
| `index` | Query | ❌ | 指定第幾張臉 (預設 `0`) |
### 4.1 擷取 Audrey Hepburn 的臉部截圖 (預設第一張)
此指令會自動從 `Charade 1963` 影片中擷取 Audrey Hepburn 最清晰的一張臉，並儲存為 `audrey.jpg`。
```bash ```bash
curl -s -o audrey.jpg \ curl -s -X POST "http://127.0.0.1:3003/api/v1/identities/register" \
"http://127.0.0.1:3002/api/v1/person/Person_17/thumbnail?video_uuid=384b0ff44aaaa1f1" \ -H "Content-Type: application/json" \
-H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "X-API-Key: YOUR_API_KEY" \
-d '{
"face_ids": ["face_100", "face_150", "face_200"],
"name": "Audrey Hepburn",
"source": "manual",
"auto_bind_chunks": true
}' | jq .
``` ```
> **注意**: 回應是 **圖片二進位資料 (JPG)**，請使用 `-o filename.jpg` 儲存，**不要**使用 `| jq`。 **Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
"name": "Audrey Hepburn",
"faces_bound": 3,
"chunks_bound": 10,
"speaker_ids": ["SPEAKER_0"],
"reference_vectors": {
"total": 3,
"angles": ["frontal", "three_quarter"]
}
}
}
```
### 4.2 擷取 Cary Grant 的其他臉部截圖 (指定 Index) ---
若你想看同一人物的其他角度，可以調整 `index` 參數。 ## 5. Query Identity → Files
假設 Cary Grant (`Person_4`) 在影片中出現了 45 次：
**Endpoint**: `GET /api/v1/identities/:identity_uuid/files`
List all files where this identity appears.
```bash ```bash
# 擷取第 5 次出現的臉部截圖 (index 從 0 開始) curl -s "http://127.0.0.1:3003/api/v1/identities/a9a90105.../files" \
curl -s -o cary_face_5.jpg \ -H "X-API-Key: YOUR_API_KEY" | jq .
"http://127.0.0.1:3002/api/v1/person/Person_4/thumbnail?video_uuid=384b0ff44aaaa1f1&index=4" \
-H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
``` ```
### 4.3 Identity (全域身份) 的截圖策略 **Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"files": [
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"face_count": 500,
"speaker_count": 10,
"first_appearance": 5.2,
"last_appearance": 180.5,
"confidence": 0.86
},
{
"file_uuid": "9760d0820f0cf9a7",
"file_name": "Breakfast_at_Tiffanys.mp4",
"face_count": 300,
"speaker_count": 5
}
],
"total_files": 2
}
}
```
由於全域 Identity (`face_identity_id: 12`) 跨越多部影片，要取得它的截圖，請先查詢它所屬的影片： ---
1. **查詢 Identity 所在的影片**: ## 6. Query File → Identities
```bash
curl -s "http://127.0.0.1:3002/api/v1/identities/12/videos" \
-H "x-api-key: muser_..." | jq '.videos[0].video_uuid'
```
2. **取得該影片中的對應 Person ID**: 從上一步結果中找到 `person_id` (例如 `Person_17`)。
3. **呼叫截圖 API**: 使用該 `video_uuid` 和 `person_id` 呼叫上述截圖 API。
**Endpoint**: `GET /api/v1/files/:file_uuid/identities`
List all identities appearing in a file.
```bash
curl -s "http://127.0.0.1:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/identities" \
-H "X-API-Key: YOUR_API_KEY" | jq .
```
**Response**:
```json
{
"success": true,
"data": {
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"identities": [
{
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"face_count": 500,
"speaker_count": 10,
"confidence": 0.86
},
{
"identity_uuid": "b8b80206...",
"name": "Cary Grant",
"face_count": 450,
"speaker_count": 8
}
],
"total_identities": 2
}
}
```
---
## 7. Get Identity Detail
**Endpoint**: `GET /api/v1/identities/:identity_uuid`
```bash
curl -s "http://127.0.0.1:3003/api/v1/identities/a9a90105..." \
-H "X-API-Key: YOUR_API_KEY" | jq .
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"source": "manual",
"identity_type": "person",
"global_stats": {
"total_files": 3,
"total_faces": 1500,
"total_speaker_segments": 30
},
"reference_vectors": {
"total": 4,
"angles": ["frontal", "profile_right", "three_quarter"],
"quality_avg": 0.875
}
}
}
```
---
## 8. Bind Additional Faces to Identity
**Endpoint**: `POST /api/v1/identities/:identity_uuid/bind`
Add more faces to an existing identity.
```bash
curl -s -X POST "http://127.0.0.1:3003/api/v1/identities/a9a90105.../bind" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"face_ids": ["face_300", "face_400"],
"auto_bind_chunks": true
}' | jq .
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"faces_bound": 2,
"chunks_bound": 5,
"updated_stats": {
"total_faces": 1502,
"total_files": 3
}
}
}
```
---
## 9. Unbind Faces from Identity
**Endpoint**: `POST /api/v1/identities/:identity_uuid/unbind`
```bash
curl -s -X POST "http://127.0.0.1:3003/api/v1/identities/a9a90105.../unbind" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"face_ids": ["face_400"]
}' | jq .
```
---
## 10. Get Identity Thumbnail
**Endpoint**: `GET /api/v1/identities/:identity_uuid/thumbnail`
```bash
curl -s -o identity_thumbnail.jpg \
"http://127.0.0.1:3003/api/v1/identities/a9a90105.../thumbnail" \
-H "X-API-Key: YOUR_API_KEY"
```
---
## Complete Workflow Example
```
Step 1: List files → Choose Charade_1963.mp4
Step 2: List face candidates → Find high-confidence frontal faces
Step 3: AI suggest clustering → Get clustering recommendations
Step 4: Register identity → Create "Audrey Hepburn" with 3 faces
Step 5: Auto-bind chunks → 10 sentence chunks bound automatically
Step 6: Verify → Query identity → files (appears in 3 files)
```
---
## API Endpoints Summary
| Category | Endpoint | Description |
|----------|----------|-------------|
| **List** | `GET /api/v1/files` | List files |
| **List** | `GET /api/v1/identities` | List identities |
| **Candidates** | `GET /api/v1/faces/candidates` | Unregistered faces |
| **Suggest** | `POST /api/v1/agents/suggest/clustering` | AI clustering suggestions |
| **Register** | `POST /api/v1/identities/register` | Register new identity |
| **Bind** | `POST /api/v1/identities/:uuid/bind` | Bind faces to identity |
| **Detail** | `GET /api/v1/identities/:uuid` | Identity detail |
| **Relation** | `GET /api/v1/identities/:uuid/files` | Identity → Files (N:N) |
| **Relation** | `GET /api/v1/files/:uuid/identities` | File → Identities (N:N) |
---
## Changes from V3.x
| Change | V3.x | V4.0 |
|--------|------|------|
| **Architecture** | Face → Person → Identity | Face → Identity (2-layer) |
| **file_uuid** | file_uuid | file_uuid |
| **person_id** | 28 person API endpoints | Removed (deprecated) |
| **file_identities** | Not mentioned | Added (N:N relationship table) |
| **chunk candidates** | chunk candidates API | Removed (chunks auto-bind) |
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Two-layer architecture, file_uuid terminology |
| V3.5 | 2026-04-17 | Person-based workflow |
| V3.0 | 2026-04-10 | Initial identity management |

282
docs_v1.0/AI_AGENTS/IDENTITY/PHASE1_MIGRATION_PLAN.md Normal file
View File

@@ -0,0 +1,282 @@
# Phase 1 Migration Plan: file_uuid → file_uuid
> Version: V4.0 | Date: 2026-04-28
> Status: Planning
---
## Overview
将所有 `file_uuid` 重命名为 `file_uuid`，统一术语定义。
### Impact Summary
| Category | Count | Priority |
|----------|-------|----------|
| **Migration SQL** | 6 files | High |
| **Rust API** | ~20 files | High |
| **Portal Vue** | 3 files | Medium |
| **Documents** | 121 refs | Low |
---
## Phase 1.1: Database Migration
### Tables Affected
| Table | Column | New Name |
|-------|--------|----------|
| `face_detections` | `file_uuid` | `file_uuid` |
| `face_clusters` | `file_uuid` | `file_uuid` |
| `person_identities` | `file_uuid` | `file_uuid` |
| `person_appearances` | `file_uuid` | `file_uuid` |
| `chunks` | `file_uuid` | `file_uuid` |
| `files` | - | (already has `uuid`) |
### Indexes Affected
| Old Index | New Index |
|-----------|-----------|
| `idx_face_detections_file_uuid` | `idx_face_detections_file_uuid` |
| `idx_face_clusters_file_uuid` | `idx_face_clusters_file_uuid` |
| `idx_person_identities_file_uuid` | `idx_person_identities_file_uuid` |
### Migration Script
```sql
-- Migration: 011_rename_file_uuid_to_file_uuid.sql
-- Date: 2026-04-28
BEGIN;
-- 1. face_detections
ALTER TABLE face_detections
RENAME COLUMN file_uuid TO file_uuid;
DROP INDEX IF EXISTS idx_face_detections_file_uuid;
CREATE INDEX idx_face_detections_file_uuid ON face_detections(file_uuid);
DROP INDEX IF EXISTS idx_face_detections_frame;
CREATE INDEX idx_face_detections_frame ON face_detections(file_uuid, frame_number);
-- 2. face_clusters
ALTER TABLE face_clusters
RENAME COLUMN file_uuid TO file_uuid;
DROP INDEX IF EXISTS idx_face_clusters_file_uuid;
CREATE INDEX idx_face_clusters_file_uuid ON face_clusters(file_uuid);
-- 3. person_identities (will be removed in Phase 2, but rename for consistency)
ALTER TABLE person_identities
RENAME COLUMN file_uuid TO file_uuid;
DROP INDEX IF EXISTS idx_person_identities_file_uuid;
CREATE INDEX idx_person_identities_file_uuid ON person_identities(file_uuid);
-- 4. person_appearances
ALTER TABLE person_appearances
RENAME COLUMN file_uuid TO file_uuid;
DROP INDEX IF EXISTS idx_person_appearances_file_uuid;
CREATE INDEX idx_person_appearances_file_uuid ON person_appearances(file_uuid);
DROP INDEX IF EXISTS idx_person_appearances_time;
CREATE INDEX idx_person_appearances_time ON person_appearances(file_uuid, start_time, end_time);
-- 5. chunks (if exists)
ALTER TABLE chunks
RENAME COLUMN file_uuid TO file_uuid;
-- 6. Update constraint names
ALTER TABLE face_detections
DROP CONSTRAINT IF EXISTS unique_detection_per_frame,
ADD CONSTRAINT unique_detection_per_frame UNIQUE (file_uuid, frame_number, x, y, width, height);
ALTER TABLE face_clusters
DROP CONSTRAINT IF EXISTS face_recognition_results_file_uuid_key,
ADD CONSTRAINT face_clusters_file_uuid_key UNIQUE (file_uuid);
ALTER TABLE person_identities
DROP CONSTRAINT IF EXISTS unique_person_identity,
ADD CONSTRAINT unique_person_identity UNIQUE (file_uuid, face_identity_id, speaker_id);
COMMIT;
```
---
## Phase 1.2: Rust API Migration
### Files Affected
| File | Changes |
|------|---------|
| `src/api/face_recognition.rs` | Rename struct fields |
| `src/api/videos.rs` | Rename endpoints |
| `src/api/identities.rs` | Update query params |
| `src/api/person_identity.rs` | (will be removed in Phase 2) |
| `src/core/db/*.rs` | Rename column bindings |
### Migration Steps
1. Rename struct fields:
```rust
// Before
pub struct FaceResult {
pub file_uuid: String,
}
// After
pub struct FaceResult {
pub file_uuid: String,
}
```
1. Rename route parameters:
```rust
// Before
"/api/v1/face/results/:file_uuid"
// After
"/api/v1/face/results/:file_uuid"
```
1. Update SQLx bindings:
```rust
// Before
sqlx::query!("WHERE file_uuid = $1", file_uuid)
// After
sqlx::query!("WHERE file_uuid = $1", file_uuid)
```
---
## Phase 1.3: Portal Migration
### Files Affected
| File | Changes |
|------|---------|
| `portal/src/views/IdentitiesView.vue` | Rename field references |
| `portal/src/views/PersonsView.vue` | Rename field references |
| `portal/src/views/IdentityDetailView.vue` | Rename field references |
| `portal/src-tauri/src/api/*.rs` | Rename struct fields |
### Migration Steps
1. Rename TypeScript interfaces:
```typescript
// Before
interface Identity {
file_uuid: string;
}
// After
interface Identity {
file_uuid: string;
}
```
1. Update Vue templates:
```vue
<!-- Before -->
<div>影片: {{ identity.file_uuid }}</div>
<!-- After -->
<div>影片: {{ identity.file_uuid }}</div>
```
---
## Phase 1.4: Document Migration
### Files Affected
- `docs_v1.0/**/*.md` (121 refs)
- `AGENTS.md` (already updated)
### Migration Steps
```bash
# Batch replacement (MacOS/Linux)
find docs_v1.0 -name "*.md" -type f \
-exec sed -i '' 's/file_uuid/file_uuid/g' {} \;
# Verify changes
grep -r "file_uuid" docs_v1.0/*.md | wc -l
```
---
## Execution Order
| Step | Description | Est. Time |
|------|-------------|-----------|
| 1 | Create DB migration script | 5 min |
| 2 | Run DB migration (dev schema) | 2 min |
| 3 | Update Rust API | 30 min |
| 4 | Update Portal | 20 min |
| 5 | Run tests | 10 min |
| 6 | Batch update docs | 5 min |
| **Total** | | **~1 hour** |
---
## Rollback Plan
```sql
-- Rollback migration
BEGIN;
ALTER TABLE face_detections RENAME COLUMN file_uuid TO file_uuid;
ALTER TABLE face_clusters RENAME COLUMN file_uuid TO file_uuid;
ALTER TABLE person_identities RENAME COLUMN file_uuid TO file_uuid;
ALTER TABLE person_appearances RENAME COLUMN file_uuid TO file_uuid;
ALTER TABLE chunks RENAME COLUMN file_uuid TO file_uuid;
-- Restore indexes
DROP INDEX idx_face_detections_file_uuid;
CREATE INDEX idx_face_detections_file_uuid ON face_detections(file_uuid);
-- ... (repeat for other tables)
COMMIT;
```
---
## Test Commands
```bash
# After migration, verify API still works
cargo run --bin momentry_playground -- server
# Test endpoints
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966"
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/identities"
# Run tests
cargo test --lib
cargo clippy --lib
```
---
## Status Checklist
- [ ] Create migration script (011_rename_file_uuid.sql)
- [ ] Test migration on dev schema
- [ ] Update Rust API
- [ ] Update Portal
- [ ] Run cargo test
- [ ] Run cargo clippy
- [ ] Batch update docs
- [ ] Verify all endpoints work
---
## Next Phase
After Phase 1 completion:
- **Phase 2**: Architecture simplification (remove person_identities table)
- **Phase 3**: Implement new binding logic
- **Phase 4**: Portal UI update

113
docs_v1.0/AI_AGENTS/IDENTITY/PHASE2_MIGRATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,113 @@
# Phase 2 Migration Summary
> Version: V4.0 | Date: 2026-04-28
> Status: Completed (Code Ready, Migration Pending)
---
## Completed Tasks
| Task | Status | Details |
|------|--------|---------|
| **DB Migration Scripts** | ✅ | 026, 027, 028 created |
| **New Binding API** | ✅ | identity_binding_v4.rs (473 lines) |
| **Routes Registration** | ✅ | 5 new endpoints |
| **Module Export** | ✅ | mod.rs updated |
---
## New API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/identities/register` | POST | Register identity from face_ids |
| `/api/v1/identities/:uuid/bind` | POST | Bind faces to identity |
| `/api/v1/identities/:uuid/unbind` | POST | Unbind faces from identity |
| `/api/v1/faces/candidates` | GET | List unregistered faces |
| `/api/v1/files/:uuid/identity-stats` | GET | Get file identity stats |
---
## Migration Files Created
| File | Purpose |
|------|---------|
| `migrations/025_rename_video_uuid_to_file_uuid.sql` | Rename columns |
| `migrations/026_create_file_identities_table.sql` | N:N relationship table |
| `migrations/027_add_identity_id_to_face_detections.sql` | Add foreign key |
| `migrations/028_drop_person_identities_table.sql` | Remove old architecture |
---
## Files Modified
| File | Changes |
|------|--------|
| `src/api/mod.rs` | Add identity_binding_v4 module |
| `src/api/server.rs` | Register new routes |
| `src/api/identity_binding_v4.rs` | New binding logic |
---
## Next Steps
### 1. Run DB Migrations
```bash
# Connect to dev schema
psql -U accusys -d momentry -c "SET search_path TO dev;"
# Run migrations
psql -U accusys -d momentry -f migrations/025_rename_video_uuid_to_file_uuid.sql
psql -U accusys -d momentry -f migrations/026_create_file_identities_table.sql
psql -U accusys -d momentry -f migrations/027_add_identity_id_to_face_detections.sql
psql -U accusys -d momentry -f migrations/028_drop_person_identities_table.sql
```
### 2. Update SQLx Cache
```bash
cargo sqlx prepare
```
### 3. Test New Endpoints
```bash
cargo run --bin momentry_playground -- server
# Test candidates API
curl "http://localhost:3003/api/v1/faces/candidates?min_confidence=0.8"
# Test register API
curl -X POST "http://localhost:3003/api/v1/identities/register" \
-H "Content-Type: application/json" \
-d '{"face_ids": [100], "name": "Test Person"}'
```
---
## Compilation Status
- **Code Structure**: ✅ Correct
- **Type Safety**: ⏸ Pending DB migration
- **SQLx Cache**: ⏸ Need `cargo sqlx prepare` after migration
---
## Architecture Comparison
| Aspect | V3.x | V4.0 |
|--------|------|------|
| **Binding Layer** | 3 (Face → Person → Identity) | 2 (Face → Identity) |
| **Tables** | person_identities + person_appearances | file_identities |
| **API Endpoints** | 33 | 15 |
| **Person ID** | Video-local | ❌ Removed |
| **Chunk Binding** | Manual | Auto (time alignment) |
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Two-layer architecture complete |

119
docs_v1.0/AI_AGENTS/IDENTITY/V4_MIGRATION_COMPLETE.md Normal file
View File

@@ -0,0 +1,119 @@
# V4.0 Migration Complete
> Date: 2026-04-28 19:50
> Status: ✅ Successfully Completed
---
## Summary
### Phase 1: Terminology Migration (video_uuid → file_uuid)
| Task | Status | Files Modified |
|------|--------|----------------|
| **DB Migration 025** | ✅ | 4 tables renamed |
| **Rust API** | ✅ | 11 files |
| **Portal Vue/Tauri** | ✅ | 6 files |
| **Documents** | ✅ | 117 MD files |
### Phase 2: Architecture Simplification
| Task | Status | Details |
|------|--------|---------|
| **DB Migration 026** | ✅ | file_identities table created |
| **DB Migration 027** | ✅ | identity_id FK added |
| **DB Migration 028** | ✅ | person_identities dropped |
| **SQLx Fix** | ✅ | 5 JSONB bindings fixed |
| **Compilation** | ✅ | cargo check --lib passed |
| **Tests** | ✅ | 178 tests passed |
| **Clippy** | ✅ | 119 warnings (minor) |
---
## Files Fixed (JSONB Issues)
| File | Line | Fix |
|------|------|-----|
| src/api/identities.rs | 274 | .bind(serde_json::to_string(...)) |
| src/api/face_recognition.rs | 337 | .bind(serde_json::to_string(...)) |
| src/api/person_identity.rs | 1508 | .bind(serde_json::to_string(...)) |
| src/api/person_identity.rs | 2287 | .bind(serde_json::to_string(...)) |
| src/core/worker/job_runner.rs | 105 | serde_json::json!({"status": "COMPLETED"}) |
---
## Database State (dev schema)
```sql
-- Tables Created
file_identities ✅
- file_uuid, identity_id, face_count, confidence
-- Tables Renamed
face_detections.video_uuid → file_uuid ✅
face_clusters.video_uuid → file_uuid ✅
-- Tables Deleted
person_identities ✅
person_appearances ✅
```
---
## Build Status
```bash
# Compilation
cargo check --lib ✅
cargo build --lib ✅
# Tests
cargo test --lib ✅ (178 passed)
# Linting
cargo clippy --lib ✅ (119 warnings, minor)
# SQLx Cache
cargo sqlx prepare ✅ (.sqlx updated)
```
---
## Remaining Tasks (Optional)
| Task | Priority | Status |
|------|----------|--------|
| Create identity_binding_v4.rs | Medium | Pending |
| Remove person_identity.rs | Low | Pending |
| Update Portal UI for new endpoints | Low | Pending |
---
## Migration Summary
| Aspect | V3.x | V4.0 |
|--------|------|------|
| **video_uuid** | Used everywhere | **file_uuid** |
| **person_identities** | 303 records | **Removed** |
| **file_identities** | N/A | **Created** |
| **Architecture** | 3-layer | **2-layer** |
| **Compilation** | Broken | **Fixed** |
| **Tests** | - | **178 passed** |
---
## Next Steps
1. Test API endpoints manually
2. Create identity_binding_v4.rs with proper JSONB handling
3. Update Portal UI to use new endpoints
4. Document API changes in AGENTS.md
---
## Key Lessons
1. **SQLx JSONB**: Must use `serde_json::json!()` for compile-time checks
2. **Batch replacements**: Use sed -i for large-scale renaming
3. **DB Migration**: Test on dev schema first, fix errors incrementally
4. **Compilation**: Fix one error at a time, run cargo check frequently

121
docs_v1.0/AI_AGENTS/IDENTITY/V4_MIGRATION_STATUS.md Normal file
View File

@@ -0,0 +1,121 @@
# V4.0 Migration Status
> Date: 2026-04-28
---
## Completed Tasks
### Phase 1: Terminology Migration (video_uuid → file_uuid)
| Task | Status | Details |
|------|--------|---------|
| **DB Migration 025** | ✅ | face_detections, face_clusters, person_identities renamed |
| **Rust API** | ✅ | 11 files batch replaced |
| **Portal** | ✅ | 6 Vue/Tauri files |
| **Documents** | ✅ | 117 MD files |
### Phase 2: Architecture Simplification
| Task | Status | Details |
|------|--------|---------|
| **DB Migration 026** | ✅ | file_identities table created |
| **DB Migration 027** | ✅ | identity_id FK added to face_detections |
| **DB Migration 028** | ✅ | person_identities + person_appearances dropped |
| **New Binding API** | ⏸ | identity_binding_v4.rs (SQLx compile error) |
---
## Current Issue
**SQLx Compile Error**: "invalid input syntax for type json"
Cause: identities.metadata column is JSONB, but SQLx requires exact type matching during compile-time checks.
---
## Database State
```sql
-- Tables Created
file_identities (N:N relationship)
- file_uuid, identity_id, face_count, confidence
-- Tables Renamed
face_detections.video_uuid → file_uuid
face_clusters.video_uuid → file_uuid
-- Tables Deleted
person_identities ✅
person_appearances ✅
```
---
## Next Steps
### Option A: Fix SQLx (Recommended)
1. Remove identity_binding_v4.rs temporarily
2. Run `cargo sqlx prepare` to update cache
3. Fix SQL queries with proper JSONB binding
4. Re-add identity_binding_v4.rs
### Option B: Use SQLX_OFFLINE
```bash
SQLX_OFFLINE=true cargo build --lib
cargo sqlx prepare
```
### Option C: Skip for Now
Keep existing person_identity.rs API, migrate later when database is stable.
---
## Test Commands
```bash
# Verify tables
psql -U accusys -d momentry -c "\dt dev.*"
# Check columns
psql -U accusys -d momentry -c "
SELECT table_name, column_name
FROM information_schema.columns
WHERE table_schema = 'dev'
AND column_name = 'file_uuid'
ORDER BY table_name;
"
# Build (if SQLx fixed)
cargo build --lib
cargo test --lib
```
---
## Files Modified
| File | Lines |
|------|-------|
| migrations/025_rename_video_uuid_to_file_uuid.sql | 42 |
| migrations/026_create_file_identities_table.sql | 39 |
| migrations/027_add_identity_id_to_face_detections.sql | 30 |
| migrations/028_drop_person_identities_table.sql | 29 |
| src/api/identity_binding_v4.rs | 310 |
| src/api/mod.rs | +1 line |
| src/api/server.rs | +1 line |
---
## Migration Summary
| Aspect | V3.x | V4.0 |
|--------|------|------|
| **video_uuid** | Used everywhere | **file_uuid** |
| **person_identities** | 303 records | **Removed** |
| **file_identities** | N/A | **Created** |
| **API Endpoints** | 33 | 15 (pending) |
| **Binding Logic** | 3-layer | 2-layer (pending) |

18
docs_v1.0/AI_AGENTS/SUMMARIZATION/CHUNK_RULE_4_SUMMARY.md
View File

@@ -51,14 +51,14 @@ ai_query_hints:
Rule 4 是處理管線的終點，依賴 **Rule 3** 的產出以及 **LLM 服務**。 Rule 4 是處理管線的終點，依賴 **Rule 3** 的產出以及 **LLM 服務**。
1. **Rule 3 Chunks (Primary)**: 提供場景級的文本摘要與元數據。 1. **Rule 3 Chunks (Primary)**: 提供場景級的文本摘要與元數據。
- *聚合策略*: 將連續的 5-10 個 Rule 3 Chunks 視為一個「敘事區塊」。 - *聚合策略*: 將連續的 5-10 個 Rule 3 Chunks 視為一個「敘事區塊」。
2. **LLM Processor (Gemma4)**: 2. **LLM Processor (Gemma4)**:
- *任務*: 讀取該區塊內所有 Rule 3 的摘要與 ASR 文本。 - *任務*: 讀取該區塊內所有 Rule 3 的摘要與 ASR 文本。
- *輸出*: - *輸出*:
- **Summary**: 流暢的劇情描述。 - **Summary**: 流暢的劇情描述。
- **5W1H**: 結構化的關鍵要素提取。 - **5W1H**: 結構化的關鍵要素提取。
3. **Visual/Audio Retention**: 3. **Visual/Audio Retention**:
- 保留區塊內所有出現過的 `face_ids` (Who) 和 `objects` (What/Where)。 - 保留區塊內所有出現過的 `face_ids` (Who) 和 `objects` (What/Where)。
--- ---
@@ -139,21 +139,21 @@ ALTER TABLE parent_chunks ADD COLUMN rule4_parent_id UUID REFERENCES chunks_rule
Rule 4 是 **RAG (Retrieval-Augmented Generation)** 的核心數據源。 Rule 4 是 **RAG (Retrieval-Augmented Generation)** 的核心數據源。
### 3.1 劇情摘要搜尋 (Plot Search) ### 3.1 劇情摘要搜尋 (Plot Search)
* **場景**: "這部片在講什麼？"、"他們找到郵票了嗎？" - **場景**: "這部片在講什麼？"、"他們找到郵票了嗎？"
* **邏輯**: - **邏輯**:
1. 搜尋 `summary` 向量。 1. 搜尋 `summary` 向量。
2. 返回包含該情節的完整摘要區塊。 2. 返回包含該情節的完整摘要區塊。
### 3.2 5W1H 結構化查詢 (Structured Query) ### 3.2 5W1H 結構化查詢 (Structured Query)
* **場景**: "找出所有 **Cary Grant (Who)** 在 **車上 (Where)** 的片段"。 - **場景**: "找出所有 **Cary Grant (Who)** 在 **車上 (Where)** 的片段"。
* **邏輯**: - **邏輯**:
1. 過濾 `analysis_5w1h` JSONB 欄位。 1. 過濾 `analysis_5w1h` JSONB 欄位。
2. `who` 包含 "Cary Grant" **AND** `where` 包含 "car"。 2. `who` 包含 "Cary Grant" **AND** `where` 包含 "car"。
3. 這種查詢比傳統關鍵字搜索更精準，因為它是經過 LLM 理解後的結構化數據。 3. 這種查詢比傳統關鍵字搜索更精準，因為它是經過 LLM 理解後的結構化數據。
### 3.3 動機與原因搜尋 (Why/How) ### 3.3 動機與原因搜尋 (Why/How)
* **場景**: "他為什麼要偷東西？" - **場景**: "他為什麼要偷東西？"
* **邏輯**: - **邏輯**:
1. 針對 `analysis_5w1h.why` 進行語意比對。 1. 針對 `analysis_5w1h.why` 進行語意比對。
--- ---

6
docs_v1.0/AI_AGENTS/TRANSLATION/TEXT_TRANSLATION.md
View File

@@ -142,9 +142,9 @@ Content-Type: application/json
在 Portal 的 `ChunkDetailView.vue` 中，翻譯功能的調用流程如下： 在 Portal 的 `ChunkDetailView.vue` 中，翻譯功能的調用流程如下：
1. 使用者點擊「翻譯為 繁體中文」按鈕。 1. 使用者點擊「翻譯為 繁體中文」按鈕。
2. Portal 發送 POST 請求至 `/api/v1/agents/translate`。 2. Portal 發送 POST 請求至 `/api/v1/agents/translate`。
3. 取得結果後，在不重新整理頁面的情況下更新 UI (顯示 `translated_text`)。 3. 取得結果後，在不重新整理頁面的情況下更新 UI (顯示 `translated_text`)。
```typescript ```typescript
// Portal 前端調用範例 // Portal 前端調用範例

442
docs_v1.0/API/PEOPLE_API_MARCOM_MAPPING.md Normal file
View File

@@ -0,0 +1,442 @@
# People API 设计方案 (marcom 需求等效映射)
**日期**: 2026-04-28
**状态**: 设计阶段
**目的**: 根据 marcom 团队需求，在符合现有架构的前提下提供等效 API
---
## 设计原则
1. **遵循 RESTful 规范**: 使用标准 HTTP 方法 (GET, POST, PATCH, DELETE)
2. **统一路径前缀**: `/api/v1/people`
3. **响应格式统一**: `{ success: bool, message: string, data: any }`
4. **向后兼容**: 现有 API 保持不变，新 API 扩展功能
5. **符合 Identity 系统**: 与 `identities` 表和 `identity_bindings` 表集成
---
## API 对照表
### 1. GET /people/candidates (候选人物)
**marcom 需求**: 获取待确认的人物候选列表
**等效 API**:
```
GET /api/v1/people/candidates?file_uuid={uuid}&limit={n}
```
**功能**:
- 返回待确认的人物身份候选
- 包含 face cluster、speaker cluster 的匹配建议
- 状态: `pending`, `suggested`, `unmatched`
**响应示例**:
```json
{
"success": true,
"message": "Found 15 candidates",
"data": {
"candidates": [
{
"candidate_id": "face_cluster_1",
"type": "face",
"suggested_identity": {
"id": 123,
"name": "张曼玉",
"confidence": 0.92
},
"appearance_count": 45,
"status": "pending"
}
],
"total": 15
}
}
```
**实现**: 扩展现有 `/api/v1/people/suggest`
---
### 2. GET /people (人物列表)
**marcom 需求**: 获取所有人物列表
**等效 API**:
```
GET /api/v1/people?file_uuid={uuid}&limit={n}&offset={n}&status={status}
```
**功能**:
- 返回人物身份列表
- 支持按 file_uuid 筛选
- 支持分页
- 支持按状态筛选 (confirmed, pending, all)
**响应示例**:
```json
{
"success": true,
"message": "Found 8 persons",
"data": {
"persons": [
{
"identity_id": "Person_17",
"name": "张曼玉",
"appearance_count": 45,
"total_duration": 350.2,
"is_confirmed": true
}
],
"total": 8
}
}
```
**实现**: 现有 `/api/v1/people/list` 已支持
---
### 3. GET /people/{identity_id} (人物详情)
**marcom 需求**: 获取人物详情
**等效 API**:
```
GET /api/v1/people/{identity_id}?file_uuid={uuid}
```
**功能**:
- 返回人物详细信息
- 包含出场时间线
- 包含关联的 face/speaker
- 包含缩略图
**响应示例**:
```json
{
"success": true,
"data": {
"identity_id": "Person_17",
"name": "张曼玉",
"face_identity_id": 123,
"speaker_id": "SPEAKER_00",
"appearance_count": 45,
"total_duration": 350.2,
"first_appearance_time": 10.5,
"last_appearance_time": 360.2,
"timeline": [...],
"thumbnails": [...]
}
}
```
**实现**: 现有 `/api/v1/people/:person_id` 已支持
---
### 4. POST /people (创建人物)
**marcom 需求**: 手动创建新人物
**等效 API**:
```
POST /api/v1/people
Body: { "name": "张曼玉", "file_uuid": "xxx", "metadata": {...} }
```
**功能**:
- 创建新人物身份
- 关联到指定视频
- 支持添加 metadata (角色名、演员名等)
**响应示例**:
```json
{
"success": true,
"message": "Person created",
"data": {
"identity_id": "Person_99",
"name": "张曼玉",
"file_uuid": "xxx"
}
}
```
**实现**: 需新增，参考 `CreatePersonIdentityRequest`
---
### 5. PATCH /people/{identity_id} (更新人物)
**marcom 需求**: 更新人物信息
**等效 API**:
```
PATCH /api/v1/people/{identity_id}
Body: { "name": "新名字", "is_confirmed": true, "metadata": {...} }
```
**功能**:
- 更新人物名称
- 确认人物身份
- 更新 metadata
**实现**: 现有 `/api/v1/people/:person_id` (PATCH) 已支持
---
### 6. POST /people/merge (合并人物)
**marcom 需求**: 合并多个人物为一个
**等效 API**:
```
POST /api/v1/people/merge
Body: {
"target_identity_id": "Person_17",
"source_identity_ids": ["Person_18", "Person_19"]
}
```
**功能**:
- 合并多个人物身份
- 转移所有出场记录
- 更新统计数据
**实现**: 现有 `/api/v1/people/merge` 已支持
---
### 7. POST /people/skip (跳过人物)
**marcom 需求**: 跳过某个候选人物（不处理）
**等效 API**:
```
POST /api/v1/people/skip
Body: { "candidate_id": "face_cluster_2", "reason": "非人物" }
```
**功能**:
- 标记候选为"已跳过"
- 记录跳过原因
- 不创建人物身份
**响应示例**:
```json
{
"success": true,
"message": "Candidate skipped",
"data": {
"candidate_id": "face_cluster_2",
"status": "skipped",
"reason": "非人物"
}
}
```
**实现**: 需新增，扩展候选管理功能
---
### 8. POST /people/{identity_id}/remove-face (移除人脸)
**marcom 需求**: 从人物身份中移除特定人脸绑定
**等效 API**:
```
POST /api/v1/people/{identity_id}/unbind
Body: { "binding_type": "face", "binding_value": "face_123" }
```
**功能**:
- 解绑人脸与人物身份的关联
- 人脸回到候选状态
- 更新人物出场统计
**响应示例**:
```json
{
"success": true,
"message": "Face unbound",
"data": {
"identity_id": "Person_17",
"unbound_face": "face_123",
"updated_appearance_count": 42
}
}
```
**实现**: 需新增，参考现有 `UnbindIdentityRequest`
---
### 9. POST /people/split-face (分离人脸)
**marcom 需求**: 将人脸从现有人物分离为新人物
**等效 API**:
```
POST /api/v1/people/split
Body: {
"source_identity_id": "Person_17",
"face_ids": ["face_123", "face_124"],
"new_identity_name": "新人物"
}
```
**功能**:
- 从现有人物分离指定人脸
- 创建新人物身份
- 转移出场记录
**实现**: 现有 `/api/v1/people/:person_id/split` 部分支持
---
### 10. GET /people/{identity_id}/resolve (解决冲突)
**marcom 需求**: 获取人物的冲突/歧义信息
**等效 API**:
```
GET /api/v1/people/{identity_id}/conflicts
```
**功能**:
- 返回人物身份的潜在冲突
- 显示相似人脸/声音的匹配
- 提供解决方案建议
**响应示例**:
```json
{
"success": true,
"data": {
"identity_id": "Person_17",
"conflicts": [
{
"type": "similar_face",
"conflicting_identity": "Person_18",
"similarity": 0.85,
"suggestion": "merge"
}
],
"resolution_options": ["merge", "keep_separate", "skip"]
}
}
```
**实现**: 需新增
---
### 11. POST /search (搜索)
**marcom 需求**: 搜索人物
**等效 API**:
```
POST /api/v1/people/search
Body: {
"query": "张",
"filters": { "type": "people", "file_uuid": "xxx" },
"limit": 20
}
```
**功能**:
- 搜索人物身份
- 支持按名称、类型、视频筛选
- 返回匹配结果
**实现**: 现有 `/api/v1/identities/search` 已支持，建议扩展
---
### 12. GET /people/status (人物状态)
**marcom 需求**: 获取人物处理状态统计
**等效 API**:
```
GET /api/v1/people/status?file_uuid={uuid}
```
**功能**:
- 返回人物处理统计
- 待确认数量、已确认数量、跳过数量
- 合并历史
**响应示例**:
```json
{
"success": true,
"data": {
"file_uuid": "xxx",
"total_candidates": 15,
"confirmed": 8,
"pending": 5,
"skipped": 2,
"merge_count": 3,
"split_count": 1
}
}
```
**实现**: 需新增
---
## 实现优先级
| 优先级 | API | 状态 | 预估工时 |
|--------|-----|------|----------|
| **P0** | GET /people | ✅ 已有 | 0h |
| **P0** | GET /people/{identity_id} | ✅ 已有 | 0h |
| **P0** | PATCH /people/{identity_id} | ✅ 已有 | 0h |
| **P0** | POST /people/merge | ✅ 已有 | 0h |
| **P1** | GET /people/candidates | ⚠️ 扩展 | 2h |
| **P1** | POST /people | ❌ 新增 | 2h |
| **P1** | POST /people/search | ⚠️ 扩展 | 1h |
| **P2** | POST /people/skip | ❌ 新增 | 2h |
| **P2** | POST /people/{identity_id}/unbind | ❌ 新增 | 2h |
| **P2** | POST /people/split | ⚠️ 扩展 | 1h |
| **P2** | GET /people/{identity_id}/conflicts | ❌ 新增 | 3h |
| **P2** | GET /people/status | ❌ 新增 | 2h |
**总预估**: ~13h (P1+P2)
---
## 数据库表需求
现有表结构支持大部分需求，可能需要扩展：
```sql
-- 建议新增: candidates 表 (候选管理)
CREATE TABLE person_candidates (
id BIGSERIAL PRIMARY KEY,
file_uuid VARCHAR(36) NOT NULL,
candidate_type VARCHAR(20), -- 'face', 'speaker'
candidate_id VARCHAR(50), -- 'face_cluster_1', 'speaker_2'
suggested_identity_id BIGINT,
confidence FLOAT,
status VARCHAR(20), -- 'pending', 'confirmed', 'skipped'
skip_reason TEXT,
created_at TIMESTAMP,
updated_at TIMESTAMP
);
```
---
## 参考文档
- `docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md` - Identity 系统设计
- `docs_v1.0/ARCHITECTURE/PERSON_IDENTITY_INTEGRATION.md` - Person Identity 整合
- `src/api/person_identity.rs` - 现有 API 实现
- `src/api/identity_binding.rs` - 身份绑定 API

699
docs_v1.0/API_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,699 @@
# Momentry Core API Documentation v1.0.0
## Overview
Momentry Core is a digital asset management system with video analysis, RAG, and face recognition capabilities. This document covers all API endpoints available in v1.0.0.
**Base URL**: `http://<host>:<port>`
- Production: Port 3002
- Development (Playground): Port 3003
**Authentication**: All protected routes require API key validation via `X-API-Key` header.
---
## API Classification
The API is organized into 7 categories:
| Category | Prefix | Description |
|----------|--------|-------------|
| **Health & Auth** | `/health`, `/api/v1/auth` | System health, authentication |
| **Asset Management** | `/api/v1/register`, `/api/v1/files`, `/api/v1/assets` | File registration, probing, processing |
| **Search** | `/api/v1/search`, `/api/v1/n8n` | Text, hybrid, visual, and n8n search |
| **Video Details** | `/api/v1/videos`, `/api/v1/progress` | Video listing, details, chunks |
| **Identity & Binding** | `/api/v1/identities`, `/api/v1/signals` | Face/speaker identity management |
| **Jobs & Rules** | `/api/v1/jobs`, `/api/v1/rules` | Processing job monitoring |
| **Stats & Config** | `/api/v1/stats`, `/api/v1/config` | System statistics, configuration |
---
## 1. Health & Authentication
### `GET /health`
Basic health check.
**Response**:
```json
{
"status": "ok",
"version": "v1.0.0",
"uptime_ms": 12345
}
```
### `GET /health/detailed`
Detailed health check with service status (PostgreSQL, Redis, Qdrant, MongoDB).
**Response**:
```json
{
"status": "ok",
"version": "v1.0.0",
"uptime_ms": 12345,
"services": {
"postgres": { "status": "ok", "latency_ms": 5 },
"redis": { "status": "ok", "latency_ms": 2 },
"qdrant": { "status": "ok", "latency_ms": 10 },
"mongodb": { "status": "ok", "latency_ms": 8 }
}
}
```
### `POST /api/v1/auth/login`
Authenticate and obtain API key.
**Request**:
```json
{
"username": "demo",
"password": "demo"
}
```
**Response**:
```json
{
"success": true,
"message": "Login successful",
"api_key": "muser_test_001",
"user": { "username": "demo" }
}
```
### `POST /api/v1/auth/logout`
Logout session.
**Response**:
```json
{ "success": true }
```
---
## 2. Asset Management
### `POST /api/v1/register`
Register a video file (legacy path-based).
**Request**:
```json
{ "path": "./demo/video.mp4" }
```
**Response**:
```json
{
"file_uuid": "384b0ff44aaaa1f1",
"file_id": 1,
"job_id": 1,
"file_name": "video.mp4",
"duration": 120.5,
"width": 1920,
"height": 1080,
"already_exists": false
}
```
### `POST /api/v1/files/register`
Register a file with full metadata (recommended). Supports move detection.
**Request**:
```json
{
"file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4",
"user_id": null
}
```
**Response**:
```json
{
"success": true,
"file_uuid": "384b0ff44aaaa1f1",
"file_name": "video.mp4",
"file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4",
"file_type": "video",
"duration": 120.5,
"width": 1920,
"height": 1080,
"fps": 30.0,
"total_frames": 3615,
"registration_time": null,
"already_exists": false,
"message": "File registered successfully"
}
```
### `GET /api/v1/files/scan`
Scan filesystem for unregistered files.
### `POST /api/v1/unregister`
Unregister a video file.
**Request**:
```json
{ "uuid": "384b0ff44aaaa1f1" }
```
### `POST /api/v1/probe`
Probe a video file for metadata.
**Request**:
```json
{ "path": "./demo/video.mp4" }
```
**Response**:
```json
{
"uuid": "384b0ff44aaaa1f1",
"file_name": "video.mp4",
"duration": 120.5,
"width": 1920,
"height": 1080,
"fps": 30.0,
"cached": true,
"format": { ... },
"streams": [ ... ]
}
```
### `GET /api/v1/assets/:uuid/probe`
Probe a video by UUID.
### `POST /api/v1/assets/:uuid/process`
Trigger processing pipeline for an asset.
**Request**:
```json
{
"processors": ["asr", "cut", "yolo", "ocr", "face", "pose", "asrx", "visual_chunk"]
}
```
**Response**:
```json
{
"job_id": 1,
"asset_uuid": "384b0ff44aaaa1f1",
"status": "PENDING",
"message": "Processing triggered for video.mp4"
}
```
### `GET /api/v1/assets/:uuid/status`
Get asset processing status with frame progress.
**Response**:
```json
{
"uuid": "384b0ff44aaaa1f1",
"file_name": "video.mp4",
"registration_time": "2026-04-30T10:00:00Z",
"processing_status": "processing",
"current_job_id": "abc-123",
"frame_progress": {
"total_frames": 3615,
"processed_frames": 1200,
"progress_percent": 33.2
}
}
```
---
## 3. Search
### `POST /api/v1/search`
Vector/smart search across chunks.
**Request**:
```json
{
"query": "person talking about AI",
"mode": "smart",
"uuid": "384b0ff44aaaa1f1",
"limit": 10
}
```
**Response**:
```json
{
"results": [
{
"uuid": "384b0ff44aaaa1f1",
"chunk_id": "chunk_1",
"chunk_type": "sentence",
"start_time": 10.5,
"end_time": 15.2,
"text": "AI is transforming...",
"score": 0.85
}
],
"query": "person talking about AI"
}
```
### `POST /api/v1/search/hybrid`
Hybrid search (vector + BM25).
**Request**:
```json
{
"query": "search term",
"limit": 10,
"uuid": "384b0ff44aaaa1f1",
"vector_weight": 0.7,
"bm25_weight": 0.3
}
```
### `POST /api/v1/search/bm25`
BM25 full-text search.
### `POST /api/v1/search/visual`
Search visual chunks by criteria.
**Request**:
```json
{
"uuid": "384b0ff44aaaa1f1",
"criteria": {
"object_class": "person",
"min_count": 1
}
}
```
### `POST /api/v1/search/visual/class`
Search by object class.
**Request**:
```json
{
"uuid": "384b0ff44aaaa1f1",
"object_class": "person",
"min_count": 1,
"max_count": null
}
```
### `POST /api/v1/search/visual/density`
Search by object density.
**Request**:
```json
{
"uuid": "384b0ff44aaaa1f1",
"min_density": 0.5,
"max_density": null
}
```
### `POST /api/v1/search/visual/combination`
Search by object combination.
**Request**:
```json
{
"uuid": "384b0ff44aaaa1f1",
"combination": [["person", 2], ["car", 1]]
}
```
### `POST /api/v1/search/visual/stats`
Get visual chunk statistics.
**Request**:
```json
{ "uuid": "384b0ff44aaaa1f1" }
```
### `POST /api/v1/n8n/search`
Search via n8n integration.
### `POST /api/v1/n8n/search/bm25`
BM25 search via n8n.
### `POST /api/v1/n8n/search/hybrid`
Hybrid search via n8n.
### `POST /api/v1/n8n/search/smart`
Smart search via n8n.
---
## 4. Video Details
### `GET /api/v1/videos`
List all registered videos with pagination.
**Query Parameters**:
- `page`: Page number (default: 1)
- `page_size`: Items per page (default: 20)
- `status`: Filter by status
- `q`: Search query
- `uuid`: Filter by UUID
**Response**:
```json
{
"files": [
{
"file_uuid": "384b0ff44aaaa1f1",
"file_path": "/path/to/video.mp4",
"file_name": "video.mp4",
"file_type": "video",
"duration": 120.5,
"width": 1920,
"height": 1080,
"status": "completed",
"created_at": "2026-04-30T10:00:00Z",
"file_size": 52428800,
"total_frames": 3615
}
],
"count": 1,
"page": 1,
"page_size": 20
}
```
### `DELETE /api/v1/videos/:uuid`
Delete a video and all associated data (faces, chunks, processor results).
**Response**:
```json
{
"success": true,
"message": "File 384b0ff44aaaa1f1 unregistered successfully...",
"file_uuid": "384b0ff44aaaa1f1",
"deleted_face_detections": 150,
"deleted_processor_results": 8,
"deleted_chunks": 45
}
```
### `GET /api/v1/videos/:uuid/details`
Get detailed chunk information.
**Query Parameters**:
- `chunk_id`: Specific chunk ID (required)
- `parent_id`: Parent chunk ID
**Response**:
```json
{
"uuid": "384b0ff44aaaa1f1",
"chunk_id": "chunk_1",
"chunk_type": "sentence",
"frame_range": {
"start_frame": 315,
"end_frame": 456,
"duration_frames": 141,
"fps": 30.0
},
"reference_time": {
"start": 10.5,
"end": 15.2
},
"text_content": "AI is transforming...",
"summary_text": "Discussion about AI impact",
"speaker_ids": ["SPEAKER_0"],
"person_ids": ["face_100"]
}
```
### `GET /api/v1/videos/:uuid/pre_chunks`
List pre-processor chunks.
**Query Parameters**:
- `processor_type`: Filter by processor (asr, yolo, face, etc.)
- `page`: Page number
- `page_size`: Items per page
### `GET /api/v1/progress/:uuid`
Get processing progress for a video.
---
## 5. Identity & Binding
### `POST /api/v1/identities/from-face`
Register a global identity from face.json with multi-angle reference vectors.
**Request**:
```json
{
"face_json_path": "/path/to/face.json",
"identity_name": "John Doe",
"schema": "dev"
}
```
### `POST /api/v1/identities/from-person`
Register identity from a person in a video.
**Request**:
```json
{
"file_uuid": "384b0ff44aaaa1f1",
"person_id": "person_1",
"identity_name": "John Doe"
}
```
### `GET /api/v1/identities`
List all global identities.
**Query Parameters**:
- `page`: Page number
- `page_size`: Items per page
### `GET /api/v1/faces/candidates`
List unbound face candidates.
**Query Parameters**:
- `file_uuid`: Filter by file
- `min_confidence`: Minimum confidence (default: 0.5)
- `page`, `page_size`: Pagination
### `GET /api/v1/identities/:identity_id/faces`
Get all faces for an identity.
### `GET /api/v1/faces/:face_id/thumbnail`
Get face thumbnail image (JPEG).
### `POST /api/v1/identities/bind`
Bind a face/speaker to an identity.
**Request**:
```json
{
"identity_id": 1,
"binding_type": "face",
"binding_value": "face_100",
"source": "manual"
}
```
### `POST /api/v1/identities/unbind`
Unbind an identity.
**Request**:
```json
{
"binding_type": "face",
"binding_value": "face_100"
}
```
### `GET /api/v1/identity/:binding_type/:binding_value`
Get identity info by binding.
### `GET /api/v1/signals/unbound`
List unbound signals.
**Query Parameters**:
- `uuid`: File UUID
- `binding_type`: "face" or "speaker"
### `GET /api/v1/signals/:uuid/:binding_type/:binding_value/timeline`
Get signal timeline (all chunks for a face/speaker).
### `POST /api/v1/identities/suggest-av`
Suggest audio-visual bindings based on temporal overlap.
**Request**:
```json
{
"file_uuid": "384b0ff44aaaa1f1",
"overlap_threshold": 0.6
}
```
---
## 6. Jobs & Rules
### `GET /api/v1/jobs`
List all monitor jobs.
**Query Parameters**:
- `page`, `page_size`: Pagination
- `status`: Filter by status
### `GET /api/v1/jobs/:job_id`
Get job details with processor information.
**Response**:
```json
{
"job_id": "1",
"asset_uuid": "384b0ff44aaaa1f1",
"rule": "default",
"status": "RUNNING",
"current_processor_id": "asr",
"frame_progress": {
"total_frames": 3615,
"processed_frames": 1200,
"progress_percent": 33.2
}
}
```
### `GET /api/v1/rules/:rule/status`
Get rule status with active jobs.
---
## 7. Stats & Configuration
### `GET /api/v1/stats/ingest`
Get ingestion statistics.
**Response**:
```json
{
"total_videos": 50,
"total_chunks": 1200,
"sentence_chunks": 800,
"cut_chunks": 300,
"time_chunks": 100,
"searchable_chunks": 1150,
"chunks_with_visual": 450,
"chunks_with_summary": 200,
"pending_videos": 5
}
```
### `GET /api/v1/stats/sftpgo`
Get SFTPGo status and registered videos.
### `GET /api/v1/stats/inference`
Check inference engine health (Ollama, llama-server).
**Response**:
```json
{
"ollama": {
"engine": "Ollama",
"model": "nomic-embed-text",
"status": "ok",
"latency_ms": 15
},
"llama_server": {
"engine": "llama-server",
"model": "gemma4_e4b_q5",
"status": "ok",
"latency_ms": 25
}
}
```
### `POST /api/v1/config/cache`
Toggle MongoDB cache.
**Request**:
```json
{ "enabled": false }
```
**Response**:
```json
{
"success": true,
"cache_enabled": false,
"message": "Cache disabled"
}
```
---
## API Usage Patterns
### 1. List Pattern
```
GET /api/v1/videos?page=1&page_size=20
```
- Supports pagination
- Optional filters via query parameters
- Returns `{ items: [...], count, page, page_size }`
### 2. Detail Pattern
```
GET /api/v1/videos/:uuid/details?chunk_id=chunk_1
```
- Path parameter for resource identifier
- Query parameters for sub-resource selection
- Returns detailed object with nested structures
### 3. Operation Pattern
```
POST /api/v1/assets/:uuid/process
```
- Action-oriented endpoint
- Request body contains operation parameters
- Returns operation status and job ID
### 4. Application Pattern
```
POST /api/v1/identities/bind
POST /api/v1/identities/suggest-av
```
- Complex workflows with multiple steps
- Often involve external services (Python scripts, FFmpeg)
- Return comprehensive results with metadata
---
## Error Responses
| Status Code | Description |
|-------------|-------------|
| `400` | Bad Request - Invalid parameters |
| `404` | Not Found - Resource doesn't exist |
| `500` | Internal Server Error - Database/service failure |
---
## V4.0 Architecture Notes
### Key Changes from V3.x
- `video_uuid` → `file_uuid` (terminology update)
- `person_identities` table **removed**
- Face → Identity direct binding (no intermediate person_id)
- 28 person_id APIs removed (except register/bind)
- Chunk binding auto via time alignment
### Identity Model
```
Face Detection → Identity (direct binding)
Speaker Detection → Identity (direct binding)
```
### Processing Pipeline
```
Register → Probe → ASR → CUT → YOLO → OCR → Face → Pose → ASRX → Visual Chunk
```

6
docs_v1.0/ARCHITECTURE/API_WORKFLOW_WORDPRESS_N8N.md
View File

@@ -152,7 +152,7 @@ const job = await response.json();
// 狀態檢查 // 狀態檢查
if (job.status === 'completed') { if (job.status === 'completed') {
return [{ json: { done: true, video_uuid: job.video_uuid } }]; return [{ json: { done: true, file_uuid: job.file_uuid } }];
} else { } else {
return [{ json: { done: false, status: job.status } }]; return [{ json: { done: false, status: job.status } }];
} }
@@ -403,13 +403,13 @@ add_shortcode('momentry_search', function($atts) {
$html .= '<ul>'; $html .= '<ul>';
foreach ($results['results'] as $result) { foreach ($results['results'] as $result) {
$video_uuid = $result['uuid']; $file_uuid = $result['uuid'];
$start = $result['start_time'] ?? 0; $start = $result['start_time'] ?? 0;
$end = $result['end_time'] ?? 0; $end = $result['end_time'] ?? 0;
$text = $result['text'] ?? '無文字描述'; $text = $result['text'] ?? '無文字描述';
$html .= '<li>'; $html .= '<li>';
$html .= '<a href="/player?uuid=' . esc_attr($video_uuid) . $html .= '<a href="/player?uuid=' . esc_attr($file_uuid) .
'&start=' . esc_attr($start) . '&start=' . esc_attr($start) .
'&end=' . esc_attr($end) . '">'; '&end=' . esc_attr($end) . '">';
$html .= '播放 ' . $start . 's - ' . $end . 's'; $html .= '播放 ' . $start . 's - ' . $end . 's';

2
docs_v1.0/ARCHITECTURE/ARCHITECTURE_DECISION_CARDS.md
View File

@@ -220,4 +220,4 @@ ai_query_hints:
**最後更新**: 2026-04-22 **最後更新**: 2026-04-22
**卡片數量**: 5 **卡片數量**: 5
**狀態分布**: ✅ 已實施 4，⚠️ 待實施 1 **狀態分布**: ✅ 已實施 4，⚠️ 待實施 1

2
docs_v1.0/ARCHITECTURE/ARCHITECTURE_DECISION_EXECUTION_PLAN.md
View File

@@ -160,4 +160,4 @@ ai_query_hints:
--- ---
**最後更新**: 2026-04-22 **最後更新**: 2026-04-22

2
docs_v1.0/ARCHITECTURE/ARCHITECTURE_DOCUMENTATION_MAP.md
View File

@@ -386,4 +386,4 @@ jobs:
**最後更新**：2026-04-22 **最後更新**：2026-04-22
**文檔狀態**：活躍維護中 **文檔狀態**：活躍維護中
**建議反饋**：請通過 GitHub Issues 或郵件提供反饋 **建議反饋**：請通過 GitHub Issues 或郵件提供反饋

2
docs_v1.0/ARCHITECTURE/ARCHITECTURE_OVERVIEW.md
View File

@@ -326,4 +326,4 @@ Momentry Core 是一個基於 Rust 的數字資產管理系統，專注於視頻
| 2026-04-22 | V1.1 | 更新文檔索引，添加新創建的架構文檔 | OpenCode | | 2026-04-22 | V1.1 | 更新文檔索引，添加新創建的架構文檔 | OpenCode |
| 2026-04-22 | V1.0 | 創建架構總覽文件 | OpenCode | | 2026-04-22 | V1.0 | 創建架構總覽文件 | OpenCode |
**最後更新**: 2026-04-22 (V1.2) **最後更新**: 2026-04-22 (V1.2)

2
docs_v1.0/ARCHITECTURE/ARCHITECTURE_REVIEW_PROCESS.md
View File

@@ -276,4 +276,4 @@ ai_query_hints:
**最後更新**: 2026-04-22 **最後更新**: 2026-04-22
**版本**: V1.0 **版本**: V1.0
**生效日期**: 2026-04-22 **生效日期**: 2026-04-22
**審查週期**: 每季度審查更新 **審查週期**: 每季度審查更新

53
docs_v1.0/ARCHITECTURE/ARCHITECTURE_ROADMAP.md
View File

@@ -39,7 +39,7 @@ ai_query_hints:
本路線圖定義了 Momentry Core 架構發展的階段性目標和時間規劃，涵蓋從基礎架構到高級功能的全面發展。 本路線圖定義了 Momentry Core 架構發展的階段性目標和時間規劃，涵蓋從基礎架構到高級功能的全面發展。
### 階段劃分： ### 階段劃分
``` ```
Phase 0: 現狀 (Current State) [✅ 已實現] Phase 0: 現狀 (Current State) [✅ 已實現]
@@ -226,12 +226,12 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
## 6. 關鍵里程碑 ## 6. 關鍵里程碑
### 2026年： ### 2026年
- ✅ **2026-03-25**: Rule 1 (句子級分片)完整實現 - ✅ **2026-03-25**: Rule 1 (句子級分片)完整實現
- ⏳ **2026-05-31**: 完成 Rule 3 (場景級分片) - ⏳ **2026-05-31**: 完成 Rule 3 (場景級分片)
- ⏳ **2026-09-30**: 完成 Rule 2 (視覺分片) - ⏳ **2026-09-30**: 完成 Rule 2 (視覺分片)
### 2027年： ### 2027年
- 📅 **2027-02-28**: 微服務架構遷移完成 - 📅 **2027-02-28**: 微服務架構遷移完成
- 📅 **2027-06-30**: 實時處理引擎上線 - 📅 **2027-06-30**: 實時處理引擎上線
- 📅 **2027-12-31**: 企業級功能完整實現 - 📅 **2027-12-31**: 企業級功能完整實現
@@ -240,7 +240,7 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
## 7. 風險與挑戰 ## 7. 風險與挑戰
### 技術挑戰： ### 技術挑戰
1. **AI 模型集成**： 1. **AI 模型集成**：
- 多模型協同工作 - 多模型協同工作
@@ -257,7 +257,7 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
- 並發控制 - 並發控制
- 資源調度優化 - 資源調度優化
### 非技術挑戰： ### 非技術挑戰
1. **資源限制**： 1. **資源限制**：
- 計算資源需求 - 計算資源需求
@@ -273,7 +273,7 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
## 8. 成功標準 ## 8. 成功標準
### 技術成功標準： ### 技術成功標準
1. **性能指標**： 1. **性能指標**：
- API 響應時間 < 500ms - API 響應時間 < 500ms
@@ -285,7 +285,7 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
- AI 模型準確率 > 85% - AI 模型準確率 > 85%
- 檢索結果相關性 > 80% - 檢索結果相關性 > 80%
### 業務成功標準： ### 業務成功標準
1. **用戶滿意度**： 1. **用戶滿意度**：
- 搜索結果滿意度 > 85% - 搜索結果滿意度 > 85%
@@ -301,7 +301,7 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
## 9. 監控與評估 ## 9. 監控與評估
### 性能監控： ### 性能監控
1. **實時指標**： 1. **實時指標**：
- API 延遲 - API 延遲
@@ -313,7 +313,7 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
- 用戶活躍度 - 用戶活躍度
- 功能使用頻率 - 功能使用頻率
### 評估機制： ### 評估機制
1. **每月評估**： 1. **每月評估**：
- 進度審查 - 進度審查
@@ -325,20 +325,11 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
- 質量保證 - 質量保證
- 風險管理 - 風險管理
--- ---
## 10. 更新頻率 ## 10. 更新頻率
### 路線圖更新
### 路線圖更新：
| 更新類型 | 頻率 | 責任人 | | 更新類型 | 頻率 | 責任人 |
|----------|------|--------| |----------|------|--------|
@@ -346,34 +337,22 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
| 重大調整 | 季度 | 架構委員會 | | 重大調整 | 季度 | 架構委員會 |
| 年度規劃 | 每年 | 管理層 | | 年度規劃 | 每年 | 管理層 |
### 溝通機制
### 溝通機制：
1. **內部溝通**： 1. **內部溝通**：
- 每周技術會議 - 每周技術會議
- 月度架構審查 - 月度架構審查
- 季度成果展示 - 季度成果展示
2. **外部溝通**： 2. **外部溝通**：
- 每月進度報告 - 每月進度報告
- 季度技術更新 - 季度技術更新
- 年度發展規劃 - 年度發展規劃
--- ---
## 11. 相關文件 ## 11. 相關文件
| 文件 | 描述 | 相關性 | | 文件 | 描述 | 相關性 |
|------|------|--------| |------|------|--------|
| [ARCHITECTURE_OVERVIEW.md](./ARCHITECTURE_OVERVIEW.md) | 架構總覽 | 整體規劃 | | [ARCHITECTURE_OVERVIEW.md](./ARCHITECTURE_OVERVIEW.md) | 架構總覽 | 整體規劃 |
@@ -381,20 +360,12 @@ Phase 3: 遠景目標 (Long-term Vision) [🔮 規劃中]
| [CHUNKING_ARCHITECTURE.md](./chunking/CHUNKING_ARCHITECTURE.md) | 分片架構 | 技術實現 | | [CHUNKING_ARCHITECTURE.md](./chunking/CHUNKING_ARCHITECTURE.md) | 分片架構 | 技術實現 |
| [PROJECT_DOCS_V1_INTEGRATION_PLAN.md](../PROJECT_DOCS_V1_INTEGRATION_PLAN.md) | 項目整合計劃 | 總體規劃 | | [PROJECT_DOCS_V1_INTEGRATION_PLAN.md](../PROJECT_DOCS_V1_INTEGRATION_PLAN.md) | 項目整合計劃 | 總體規劃 |
--- ---
## 12. 最後更新記錄 ## 12. 最後更新記錄
| 版本 | 日期 | 主要變更 | 操作人 | | 版本 | 日期 | 主要變更 | 操作人 |
|------|------|----------|--------| |------|------|----------|--------|
| V1.0 | 2026-04-22 | 創建架構路線圖文件 | OpenCode | | V1.0 | 2026-04-22 | 創建架構路線圖文件 | OpenCode |
**最後更新日期**: 2026-04-22
**最後更新日期**: 2026-04-22

535
docs_v1.0/ARCHITECTURE/CLIP_EMBEDDING_BENCHMARK_PLAN.md Normal file
View File

@@ -0,0 +1,535 @@
---
document_type: "benchmark_plan"
title: "CLIP ViT-L/14 Embedding 性能基准测试计划"
service: "MOMENTRY_CORE"
date: "2026-04-28"
status: "active"
current_state: "planning"
owner: "Warren"
created_by: "OpenCode"
created_at: "2026-04-28"
version: "V1.0"
tags:
- "clip"
- "vit-l/14"
- "embedding"
- "benchmark"
- "logo_detection"
- "mps"
- "accusys_logo"
related_documents:
- "IDENTITY_REFERENCE_VECTOR_DESIGN.md"
- "MOMENTRY_CORE_ARCHITECTURE_V2.md"
- "IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md"
ai_query_hints:
- "查詢 CLIP ViT-L/14 性能测试计划"
- "查詢 Accusys Logo 测试方案"
- "查詢 MPS vs CPU 性能对比"
- "查詢 Logo 檢測 + embedding + 匹配流程"
---
# CLIP ViT-L/14 Embedding 性能基准测试计划
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-28 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-28 | 創建 CLIP ViT-L/14 性能基准测试计划 | OpenCode | OpenCode |
---
## 概述
本文檔定義 Momentry Core Identity 系統的 **CLIP ViT-L/14 Embedding 性能基准测试计划**，测试对象为 **Accusys Storage Logo**。
---
## 测试目标
### 核心目标
| 目標 | 說明 |
|------|------|
| **Logo 檢測** | 使用 OWL-ViT 檢測 Accusys Logo 在视频中的出现 |
| **Embedding 提取** | 使用 CLIP ViT-L/14 提取 Logo 的 768-dim embedding |
| **Identity 注册** | 将 Logo 注册为 Identity (identity_type='logo') |
| **相似度搜索** | 在视频帧中搜索与 Logo 相似的内容 |
| **性能基准** | 测量 CLIP 在 MPS vs CPU 的性能差异 |
| **1对多匹配** | 测试 1对多匹配算法的效果 |
### 测试对象
| 对象 | URL | 尺寸 | 说明 |
|------|-----|------|------|
| **Accusys Logo** | https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png | 3269x747px | Orange 品牌色 (#EE7632) |
---
## 测试环境
### 系统配置
| 配置 | 说明 |
|------|------|
| **OS** | macOS (darwin) |
| **Python** | 3.11 (MOMENTRY_PYTHON_PATH=/opt/homebrew/bin/python3.11) |
| **PyTorch** | MPS backend support ✅ |
| **CLIP Model** | ViT-L/14 (laion/CLIP-ViT-L-14-laion2B-s32B-b82K) |
| **GPU** | Apple Silicon (MPS) |
### 模型信息
| 模型 | 参数 | 说明 |
|------|------|------|
| **CLIP ViT-L/14** | 768-dim embedding | 适合 logo/symbol/object 识别 |
| **OWL-ViT** | 开放词汇检测器 | 检测任意 Logo/Symbol/Object |
| **InsightFace ArcFace** | 512-dim embedding | 人脸识别（对比基准） |
---
## 测试计划
### Phase 1: Logo 檢測 (OWL-ViT)
**目标**: 使用 OWL-ViT 检测 Accusys Logo 在视频帧中的出现
**测试步骤**:
1. 准备测试视频（包含 Accusys Logo）
2. 使用 OWL-ViT 检测 Logo：
```python
from transformers import owl_vit
# 检测文本提示
prompts = ["Accusys Storage Logo", "orange logo", "brand logo"]
# 检测结果
detections = owl_vit.detect(video_frame, prompts)
```
3. 记录检测结果：
- bbox 坐标
- confidence score
- 检测速度
**预期输出**:
- Logo 检测成功率 > 90%
- 检测速度 < 1s/frame
---
### Phase 2: Embedding 提取 (CLIP ViT-L/14)
**目标**: 使用 CLIP ViT-L/14 提取 Logo 的 768-dim embedding
**测试步骤**:
1. 下载 Accusys Logo 图片
2. 使用 CLIP 提取 embedding：
```python
import torch
from transformers import CLIPModel, CLIPProcessor
# 加载模型 (MPS backend)
device = torch.device("mps")
model = CLIPModel.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K").to(device)
processor = CLIPProcessor.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K")
# 提取 embedding
image = Image.open("accusys_logo.png")
inputs = processor(images=image, return_tensors="pt").to(device)
embedding = model.get_image_features(**inputs)
# 输出: 768-dim vector
print(f"Embedding shape: {embedding.shape}") # [1, 768]
```
3. 记录提取速度：
- MPS 模式
- CPU 模式
**预期输出**:
- Embedding 提取成功
- MPS vs CPU 性能对比
---
### Phase 3: Identity 注册
**目标**: 将 Accusys Logo 注册为 Identity
**测试步骤**:
1. 创建 Identity:
```python
identity = {
"identity_id": generate_uuid(),
"name": "Accusys Storage Logo",
"identity_type": "logo",
"source": "manual",
"reference_data": {
"identity_embeddings": [
{
"embedding": embedding.tolist(),
"source": "logo_image",
"image_url": "https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png",
"context": "brand_logo",
"created_at": datetime.now().isoformat()
}
],
"image_urls": ["https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png"]
},
"identity_embedding": embedding.tolist()
}
```
2. 存储到 identities 表
3. 验证存储成功
**预期输出**:
- Identity 注册成功
- reference_data JSONB 结构正确
- identity_embedding VECTOR(768) 存储正确
---
### Phase 4: 相似度搜索
**目标**: 在视频帧中搜索与 Logo 相似的内容
**测试步骤**:
1. 提取视频帧的 CLIP embedding
2. 计算与 Identity 的相似度：
```python
def search_similar_frames(video_frames, identity_embedding):
results = []
for frame in video_frames:
# 提取帧 embedding
frame_embedding = clip_model.extract_embedding(frame)
# 计算相似度
similarity = cosine_similarity(frame_embedding, identity_embedding)
if similarity >= 0.85:
results.append({
"frame": frame,
"similarity": similarity
})
return results
```
3. 测试 1对多匹配算法：
- Strategy 1: Best Match
- Strategy 2: Voting
- Strategy 3: Weighted Average
- Strategy 4: Combined
**预期输出**:
- 相似度搜索成功率
- 匹配算法对比
---
### Phase 5: 性能基准测试
**目标**: 测量 CLIP 在 MPS vs CPU 的性能差异
**测试步骤**:
1. **MPS 模式性能测试**:
```python
device = torch.device("mps")
model = CLIPModel.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K").to(device)
# 测试 1000 次提取
start_time = time.time()
for i in range(1000):
embedding = model.get_image_features(**inputs)
mps_time = time.time() - start_time
```
2. **CPU 模式性能测试**:
```python
device = torch.device("cpu")
model = CLIPModel.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K").to(device)
# 测试 1000 次提取
start_time = time.time()
for i in range(1000):
embedding = model.get_image_features(**inputs)
cpu_time = time.time() - start_time
```
3. **对比分析**:
- 提取速度 (mps_time vs cpu_time)
- 内存使用
- GPU 使用率
**预期输出**:
- MPS 性能提升倍数
- CPU fallback 性能基准
- 推荐使用场景
---
### Phase 6: 与 ArcFace 对比
**目标**: 对比 CLIP ViT-L/14 与 ArcFace 的性能差异
**测试对象**:
- **CLIP ViT-L/14**: Logo/Symbol/Object 识别 (768-dim)
- **ArcFace**: 人脸识别 (512-dim)
**测试步骤**:
1. 使用相同测试集（包含人脸和 Logo）
2. 测量两种模型的：
- Embedding 提取速度
- 匹配准确率
- 匹配速度
3. 对比分析
**预期输出**:
| 模型 | 用途 | 维度 | 提取速度 | 匹配准确率 |
|------|------|------|----------|-----------|
| CLIP ViT-L/14 | Logo/Symbol/Object | 768 | TBD | TBD |
| ArcFace | 人脸识别 | 512 | TBD | TBD |
---
## 测试脚本
### scripts/clip_benchmark_test.py
```python
"""
CLIP ViT-L/14 性能基准测试脚本
测试内容:
1. Logo 檢測 (OWL-ViT)
2. Embedding 提取 (CLIP ViT-L/14)
3. Identity 注册
4. 相似度搜索
5. MPS vs CPU 性能对比
6. 与 ArcFace 对比
"""
import torch
import time
import numpy as np
from PIL import Image
from transformers import CLIPModel, CLIPProcessor
def test_clip_embedding_extraction():
"""Phase 2: Embedding 提取测试"""
# 加载模型
device_mps = torch.device("mps")
device_cpu = torch.device("cpu")
model_mps = CLIPModel.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K").to(device_mps)
model_cpu = CLIPModel.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K").to(device_cpu)
processor = CLIPProcessor.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K")
# 加载 Accusys Logo
image = Image.open("accusys_logo.png")
# MPS 测试
inputs_mps = processor(images=image, return_tensors="pt").to(device_mps)
start_time = time.time()
for i in range(100):
embedding_mps = model_mps.get_image_features(**inputs_mps)
mps_time = time.time() - start_time
# CPU 测试
inputs_cpu = processor(images=image, return_tensors="pt").to(device_cpu)
start_time = time.time()
for i in range(100):
embedding_cpu = model_cpu.get_image_features(**inputs_cpu)
cpu_time = time.time() - start_time
# 输出结果
print(f"MPS 提取速度: {mps_time/100:.4f} s/image")
print(f"CPU 提取速度: {cpu_time/100:.4f} s/image")
print(f"MPS 性能提升: {cpu_time/mps_time:.2f}x")
print(f"Embedding shape: {embedding_mps.shape}")
return {
"mps_time": mps_time/100,
"cpu_time": cpu_time/100,
"mps_speedup": cpu_time/mps_time,
"embedding_shape": embedding_mps.shape
}
def test_similarity_search(identity_embedding, test_frames):
"""Phase 4: 相似度搜索测试"""
device = torch.device("mps")
model = CLIPModel.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K").to(device)
processor = CLIPProcessor.from_pretrained("laion/CLIP-ViT-L-14-laion2B-s32B-b82K")
results = []
for frame in test_frames:
inputs = processor(images=frame, return_tensors="pt").to(device)
frame_embedding = model.get_image_features(**inputs)
similarity = cosine_similarity(frame_embedding, identity_embedding)
if similarity >= 0.85:
results.append({
"frame": frame,
"similarity": similarity
})
return results
def cosine_similarity(a, b):
"""计算余弦相似度"""
a = a.detach().cpu().numpy().flatten()
b = np.array(b).flatten()
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
if __name__ == "__main__":
print("=== CLIP ViT-L/14 性能基准测试 ===")
# Phase 2: Embedding 提取
print("\n=== Phase 2: Embedding 提取测试 ===")
result = test_clip_embedding_extraction()
# Phase 3: Identity 注册 (需要数据库连接)
print("\n=== Phase 3: Identity 注册 ===")
print("待實作: 需要資料庫連接")
# Phase 4: 相似度搜索 (需要测试帧)
print("\n=== Phase 4: 相似度搜索 ===")
print("待實作: 需要测试帧")
print("\n=== 测试完成 ===")
```
---
## 测试数据
### Accusys Logo 信息
| 属性 | 值 |
|------|-----|
| **Logo URL** | https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png |
| **尺寸** | 3269x747px |
| **品牌色** | Orange (#EE7632) |
| **公司** | Accusys Storage |
| **产品线** | ExaSAN Series, Gamma Series, T-Share Series |
| **Momentry Studio** | 网站首页有介绍（AI Video Search） |
### 测试视频需求
| 需求 | 说明 |
|------|------|
| **包含 Logo** | 视频中需包含 Accusys Logo |
| **不同场景** | 白底、黑底、复杂背景 |
| **不同大小** | 大、中、小 Logo |
| **不同角度** | 正面、侧面、倾斜 |
| **时长** | 建议 30-60 秒 |
---
## 预期结果
### 性能基准预期
| 指标 | 预期值 | 说明 |
|------|--------|------|
| **MPS 提取速度** | < 0.05 s/image | MPS 加速 |
| **CPU 提取速度** | < 0.2 s/image | CPU fallback |
| **MPS 性能提升** | > 2x | MPS vs CPU |
| **Logo 检测成功率** | > 90% | OWL-ViT 检测 |
| **匹配准确率** | > 85% | 相似度搜索 |
| **匹配速度** | < 1s/query | 相似度计算 |
### 1对多匹配预期
| 算法 | 预期准确率 | 说明 |
|------|-----------|------|
| **Strategy 1 (Best Match)** | 85% | 快速匹配 |
| **Strategy 2 (Voting)** | 88% | 投票机制 |
| **Strategy 3 (Weighted)** | 90% | 加权平均 |
| **Strategy 4 (Combined)** | 92% | 综合评分 |
---
## 实作计划
### Phase 1: 准备测试环境
- [ ] 下载 Accusys Logo 图片
- [ ] 准备测试视频
- [ ] 安装 CLIP ViT-L/14 模型
- [ ] 安装 OWL-ViT 模型
### Phase 2: Logo 檢測测试
- [ ] OWL-ViT 检测脚本编写
- [ ] 检测结果记录
- [ ] 检测速度测量
### Phase 3: Embedding 提取测试
- [ ] CLIP ViT-L/14 embedding 提取脚本编写
- [ ] MPS vs CPU 性能对比
- [ ] Embedding 存储测试
### Phase 4: Identity 注册测试
- [ ] Identity 注册脚本编写
- [ ] reference_data JSONB 存储测试
- [ ] identity_embedding VECTOR(768) 存储测试
### Phase 5: 相似度搜索测试
- [ ] 相似度搜索脚本编写
- [ ] 1对多匹配算法测试
- [ ] 搜索结果记录
### Phase 6: 性能基准测试
- [ ] MPS vs CPU 性能对比脚本
- [ ] 1000 次提取测试
- [ ] 性能基准报告生成
---
## 待辦事項
| 項目 | 優先級 | 說明 |
|------|--------|------|
| 准备测试环境 | 高 | Phase 1 |
| Logo 檢測测试 | 高 | Phase 2 |
| Embedding 提取测试 | 高 | Phase 3 |
| Identity 注册测试 | 中 | Phase 4 |
| 相似度搜索测试 | 中 | Phase 5 |
| 性能基准测试 | 中 | Phase 6 |
---
## 限制條件
- CLIP ViT-L/14 需要 MPS 或 CUDA 支持
- OWL-ViT 需要 Transformers 库
- 测试视频需包含 Accusys Logo
- 需要 PostgreSQL + pgvector 支持
---
## 相关文件
- `docs_v1.0/ARCHITECTURE/IDENTITY_REFERENCE_VECTOR_DESIGN.md` - 1对多参考向量设计
- `docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md` - 核心架构设计
- `docs_v1.0/IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md` - API 设计
- `scripts/fast_stamp_search.py` - OWL-ViT Logo 检测脚本（已集成）
---
## 版本信息
- 版本: V1.0
- 建立日期: 2026-04-28
- 文件更新: 2026-04-28

2
docs_v1.0/ARCHITECTURE/DESIGN_IMPLEMENTATION_GAP.md
View File

@@ -345,4 +345,4 @@ ASR → OCR → YOLO → CUT → 分片生成
3. **持續優化**：建立長期機制確保設計與實現的一致性 3. **持續優化**：建立長期機制確保設計與實現的一致性
4. **用戶為中心**：以實際用戶需求為導向調整設計 4. **用戶為中心**：以實際用戶需求為導向調整設計
**核心原則重申**：在出現矛盾時，實際的 Rust 代碼實現是最高權威，設計文檔應反映實際實現狀態並指導未來改進方向。 **核心原則重申**：在出現矛盾時，實際的 Rust 代碼實現是最高權威，設計文檔應反映實際實現狀態並指導未來改進方向。

2
docs_v1.0/ARCHITECTURE/EVENT_RECOGNITION_TECHNICAL_ANALYSIS.md
View File

@@ -915,4 +915,4 @@ python3 scripts/test_action_recognition.py video.mp4
| **運動** | ST-GCN + YOLO | 88-92% | 20s/10min | | **運動** | ST-GCN + YOLO | 88-92% | 20s/10min |
| **打架** | ST-GCN | 80-85% | 15s/10min | | **打架** | ST-GCN | 80-85% | 15s/10min |
| **吵架** | 多模態 | 85-90% | 60s/10min | | **吵架** | 多模態 | 85-90% | 60s/10min |
| **細粒度動作** | SlowFast | 90-95% | 100s/10min | | **細粒度動作** | SlowFast | 90-95% | 100s/10min |

2
docs_v1.0/ARCHITECTURE/FAQ.md
View File

@@ -435,4 +435,4 @@ cargo run --bin momentry_playground -- server
**最後更新**: 2026-04-22 **最後更新**: 2026-04-22
**文檔版本**: V1.0 **文檔版本**: V1.0
**更新頻率**: 每月審查更新 **更新頻率**: 每月審查更新
**維護者**: OpenCode **維護者**: OpenCode

573
docs_v1.0/ARCHITECTURE/IDENTITY_REFERENCE_VECTOR_DESIGN.md Normal file
View File

@@ -0,0 +1,573 @@
---
document_type: "architecture"
title: "Identity 1對多參考向量設計"
service: "MOMENTRY_CORE"
date: "2026-04-28"
status: "active"
current_state: "finalized"
owner: "Warren"
created_by: "OpenCode"
created_at: "2026-04-28"
version: "V1.0"
tags:
- "identity"
- "reference_vector"
- "embedding"
- "face_embedding"
- "identity_embedding"
- "1-to-many"
- "matching_algorithm"
related_documents:
- "MOMENTRY_CORE_ARCHITECTURE_V2.md"
- "IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md"
- "CLIP_EMBEDDING_BENCHMARK_PLAN.md"
ai_query_hints:
- "查詢 1對多參考向量架構設計"
- "查詢 reference_data JSONB 結構"
- "查詢多角度人臉 embedding 存儲"
- "查詢 Logo/Symbol identity_embedding"
- "查詢匹配算法 (最佳匹配/投票/加權平均)"
---
# Identity 1對多參考向量設計
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-28 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-28 | 創建 Identity 1對多參考向量架構設計 | OpenCode | OpenCode |
---
## 概述
本文檔定義 Momentry Core Identity 系統的 **1對多參考向量架構設計**，核心理念：
**同一 Identity 可存儲多個參考向量（不同角度、不同場景、不同版本），提高識別鲁棒性。**
---
## 核心設計理念
### 問題背景
**傳統 1對1 設計的局限**：
- 單一參考向量無法覆蓋不同角度（正面、側面、背面）
- 單一參考向量無法覆蓋不同場景（白底 Logo、黑底 Logo、複雜背景 Logo）
- 單一參考向量無法覆蓋不同版本（同一演員的不同定妝造型）
- 匹配失敗率高，鲁棒性不足
### 1對多設計優勢
| 優勢 | 說明 |
|------|------|
| **多角度覆蓋** | 人臉正面、側面、三側角度，覆蓋不同拍攝角度 |
| **多場景覆蓋** | Logo/Symbol 在不同背景下的 embedding |
| **多版本覆蓋** | 同一演員的不同定妝造型（老妝、武俠造型、現代造型） |
| **質量評分** | 每個參考向量記錄質量評分，用於加權匹配 |
| **來源追溯** | 記錄每個 embedding 的來源，方便更新和追溯 |
---
## 架構設計
### 資料庫 Schema
**identities 表核心字段**:
```sql
CREATE TABLE identities (
identity_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name TEXT NOT NULL,
identity_type VARCHAR(30) NOT NULL,
-- 參考向量 (centroid 或最佳代表)
face_embedding VECTOR(512), -- ArcFace centroid
voice_embedding VECTOR(192), -- ECAPA-TDNN centroid
identity_embedding VECTOR(768), -- CLIP ViT-L/14 centroid
-- 1對多參考向量存儲
reference_data JSONB DEFAULT '{}', -- 多角度/多場景/多版本
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
```
**設計理念**:
- `face_embedding` 等 VECTOR 字段存儲 **centroid**（中心向量）或最佳代表向量
- `reference_data` JSONB 存儲 **所有參考向量**（多角度、多場景、多版本）
- 匹配時可選擇：
- **快速匹配**: 使用 centroid（適合低延遲場景）
- **鲁棒匹配**: 使用 reference_data 進行 1對多匹配（適合高精度場景）
---
## reference_data JSONB 結構
### 完整結構
```json
{
"face_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "tmdb_images",
"image_url": "https://image.tmdb.org/t/p/original/xxx.jpg",
"angle": "frontal",
"quality_score": 0.95,
"created_at": "2026-04-28T10:00:00Z"
},
{
"embedding": [0.3, 0.4, ...],
"source": "tmdb_images",
"image_url": "https://image.tmdb.org/t/p/original/yyy.jpg",
"angle": "profile_left",
"quality_score": 0.88,
"created_at": "2026-04-28T10:05:00Z"
}
],
"voice_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "video_segment",
"file_uuid": "vid_001",
"timestamp_start": 120.5,
"timestamp_end": 135.2,
"quality_score": 0.88,
"created_at": "2026-04-28T11:00:00Z"
}
],
"identity_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "logo_image",
"image_url": "https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png",
"context": "brand_logo",
"created_at": "2026-04-28T12:00:00Z"
}
],
"sound_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "audio_segment",
"file_uuid": "vid_001",
"timestamp_start": 10.0,
"timestamp_end": 15.0,
"sound_type": "animal_dog_bark",
"created_at": "2026-04-28T13:00:00Z"
}
],
"image_urls": [
"https://image.tmdb.org/t/p/original/xxx.jpg",
"https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png"
]
}
```
### 欄位說明
#### face_embeddings (人臉向量)
| 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------|
| embedding | Array[512] | Yes | 512-dim ArcFace 向量 |
| source | String | Yes | 來源: tmdb_profile, tmdb_images, manual_upload, auto_detection |
| image_url | String | Yes | 圖片 URL |
| angle | String | No | 人臉角度: frontal, profile_left, profile_right, three_quarter |
| quality_score | Float | No | 質量評分 (0.0-1.0) |
| created_at | String | Yes | 建立時間 (ISO 8601) |
#### voice_embeddings (聲紋向量)
| 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------|
| embedding | Array[192] | Yes | 192-dim ECAPA-TDNN 向量 |
| source | String | Yes | 來源: video_segment, audio_file |
| file_uuid | String | Yes | 檔案 UUID |
| timestamp_start | Float | Yes | 開始時間 (秒) |
| timestamp_end | Float | Yes | 結束時間 (秒) |
| quality_score | Float | No | 質量評分 (0.0-1.0) |
| created_at | String | Yes | 建立時間 (ISO 8601) |
#### identity_embeddings (身份向量 - Logo/Symbol/Object)
| 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------|
| embedding | Array[768] | Yes | 768-dim CLIP ViT-L/14 向量 |
| source | String | Yes | 來源: logo_image, symbol_image, object_image, concept_image |
| image_url | String | Yes | 圖片 URL |
| context | String | No | 識別場景: brand_logo, symbol, object, concept |
| created_at | String | Yes | 建立時間 (ISO 8601) |
#### sound_embeddings (聲音向量 - Phase 5+)
| 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------|
| embedding | Array[TBD] | Yes | TBD (動物叫聲、雷雨、槍炮、樂器) |
| source | String | Yes | 來源: audio_segment |
| file_uuid | String | Yes | 檔案 UUID |
| timestamp_start | Float | Yes | 開始時間 (秒) |
| timestamp_end | Float | Yes | 結束時間 (秒) |
| sound_type | String | Yes | 聲音類型: animal_dog_bark, environmental_thunder, weapon_gunshot, musical_guitar |
| created_at | String | Yes | 建立時間 (ISO 8601) |
---
## 匹配算法
### 1對多匹配策略
#### 策略 1: 最佳匹配 (Best Match)
```python
def best_match(detected_embedding, reference_embeddings):
"""
策略 1: 取所有參考向量中的最高相似度
適用場景:
- 快速匹配
- 低延遲需求
"""
similarities = [
cosine_similarity(detected_embedding, ref["embedding"])
for ref in reference_embeddings
]
return max(similarities)
```
#### 策略 2: 投票機制 (Voting)
```python
def voting_match(detected_embedding, reference_embeddings, threshold=0.85):
"""
策略 2: 統計超過閾值的參考向量數量
適用場景:
- 高鲁棒性需求
- 多角度覆蓋場景
"""
similarities = [
cosine_similarity(detected_embedding, ref["embedding"])
for ref in reference_embeddings
]
votes = sum(1 for sim in similarities if sim >= threshold)
vote_ratio = votes / len(similarities)
return {
"votes": votes,
"vote_ratio": vote_ratio,
"is_match": vote_ratio >= 0.5 # 至少一半參考向量支持
}
```
#### 策略 3: 加權平均 (Weighted Average)
```python
def weighted_match(detected_embedding, reference_embeddings):
"""
策略 3: 根據質量評分加權計算相似度
適用場景:
- 參考向量質量不均
- 需要考慮質量評分
"""
similarities = [
cosine_similarity(detected_embedding, ref["embedding"])
for ref in reference_embeddings
]
weights = [
ref.get("quality_score", 1.0)
for ref in reference_embeddings
]
weighted_sim = sum(sim * w for sim, w in zip(similarities, weights)) / sum(weights)
return {
"weighted_similarity": weighted_sim,
"is_match": weighted_sim >= 0.85
}
```
#### 策略 4: 綜合評分 (Combined)
```python
def combined_match(detected_embedding, reference_embeddings, threshold=0.85):
"""
策略 4: 綜合評分 (最佳匹配 + 投票 + 加權平均)
適用場景:
- 最高精度需求
- 重要場景識別
"""
best_match_score = best_match(detected_embedding, reference_embeddings)
voting_result = voting_match(detected_embedding, reference_embeddings, threshold)
weighted_result = weighted_match(detected_embedding, reference_embeddings)
# 綜合評分: 50% 最佳匹配 + 30% 投票比率 + 20% 加權平均
final_score = (
best_match_score * 0.5 +
voting_result["vote_ratio"] * 0.3 +
weighted_result["weighted_similarity"] * 0.2
)
return {
"best_match": best_match_score,
"vote_ratio": voting_result["vote_ratio"],
"weighted_similarity": weighted_result["weighted_similarity"],
"final_score": final_score,
"is_match": final_score >= threshold
}
```
### 匹配算法選擇建議
| 場景 | 推薦策略 | 說明 |
|------|---------|------|
| **實時搜索** | Strategy 1 (Best Match) | 低延遲，快速匹配 |
| **批量處理** | Strategy 4 (Combined) | 最高精度，綜合評分 |
| **低置信度場景** | Strategy 2 (Voting) | 投票機制，提高鲁棒性 |
| **質量不均場景** | Strategy 3 (Weighted) | 加權平均，考慮質量評分 |
---
## TMDB 整合流程
### 1對多參考向量提取
```python
def tmdb_identity_integration(tmdb_person_id, identity_name):
"""
TMDB 整合流程:
1. 下載多張人臉照片 (TMDB /person/:id/images 端點)
2. 提取每張照片的 ArcFace embedding
3. 存儲到 reference_data JSONB
4. 計算 centroid 存儲到 face_embedding
"""
# Step 1: 獲取 TMDB 人物照片列表
images = tmdb_api.get_person_images(tmdb_person_id)
# Step 2: 下載並提取 embedding
face_embeddings = []
for image in images:
# 下載圖片
image_url = f"https://image.tmdb.org/t/p/original/{image['file_path']}"
image_data = download_image(image_url)
# 提取 ArcFace embedding
embedding = insightface.extract_embedding(image_data)
# 評估人臉角度和質量
angle = detect_face_angle(image_data)
quality_score = evaluate_face_quality(image_data)
# 存儲到 reference_data
face_embeddings.append({
"embedding": embedding.tolist(),
"source": "tmdb_images",
"image_url": image_url,
"angle": angle,
"quality_score": quality_score,
"created_at": datetime.now().isoformat()
})
# Step 3: 存儲到 identities 表
identity = {
"identity_id": generate_uuid(),
"name": identity_name,
"identity_type": "people",
"source": "tmdb",
"tmdb_id": tmdb_person_id,
"reference_data": {
"face_embeddings": face_embeddings,
"image_urls": [img["image_url"] for img in face_embeddings]
}
}
# Step 4: 計算 centroid
centroid = calculate_centroid([e["embedding"] for e in face_embeddings])
identity["face_embedding"] = centroid
# 存儲到資料庫
db.insert_identity(identity)
return identity
```
### Centroid 計算
```python
def calculate_centroid(embeddings):
"""
計算多個 embedding 的中心向量
方法: 平均值
"""
import numpy as np
embeddings_array = np.array(embeddings)
centroid = np.mean(embeddings_array, axis=0)
return centroid.tolist()
```
---
## Logo/Symbol Identity 整合
### CLIP ViT-L/14 Embedding 提取
```python
def logo_identity_integration(logo_name, logo_url):
"""
Logo Identity 整合流程:
1. 下載 Logo 圖片
2. 提取 CLIP ViT-L/14 embedding (768-dim)
3. 存儲到 reference_data JSONB
4. 存儲到 identity_embedding 字段
"""
# Step 1: 下載圖片
image_data = download_image(logo_url)
# Step 2: 提取 CLIP embedding
embedding = clip_model.extract_embedding(image_data)
# Step 3: 存儲到 reference_data
identity_embedding_data = {
"embedding": embedding.tolist(),
"source": "logo_image",
"image_url": logo_url,
"context": "brand_logo",
"created_at": datetime.now().isoformat()
}
# Step 4: 存儲到 identities 表
identity = {
"identity_id": generate_uuid(),
"name": logo_name,
"identity_type": "logo",
"source": "manual",
"reference_data": {
"identity_embeddings": [identity_embedding_data],
"image_urls": [logo_url]
},
"identity_embedding": embedding.tolist()
}
# 存儲到資料庫
db.insert_identity(identity)
return identity
```
### 範例: Accusys Logo
```python
# 註冊 Accusys Logo Identity
accusys_logo = logo_identity_integration(
logo_name="Accusys Storage Logo",
logo_url="https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png"
)
# 測試匹配
detected_logo_embedding = clip_model.extract_embedding(video_frame)
match_result = combined_match(
detected_embedding=detected_logo_embedding,
reference_embeddings=accusys_logo["reference_data"]["identity_embeddings"],
threshold=0.85
)
print(f"Match result: {match_result['is_match']}")
print(f"Final score: {match_result['final_score']}")
```
---
## 實作計畫
### Phase 1: 資料庫 Migration
- [ ] Migration 023: identities 表添加 reference_data JSONB + identity_embedding VECTOR(768)
- [ ] 索引配置: identity_embedding 向量索引 (ivfflat 或 hnsw)
- [ ] 測試資料建立
### Phase 2: TMDB 整合實作
- [ ] TMDB /person/:id/images API 串接
- [ ] 多張照片下載邏輯
- [ ] ArcFace embedding 提取（多角度）
- [ ] reference_data JSONB 存儲
- [ ] Centroid 計算邏輯
### Phase 3: Logo/Symbol Identity 實作
- [ ] CLIP ViT-L/14 模型集成（MPS 支持）
- [ ] Logo/Symbol 檢測（OWL-ViT）
- [ ] identity_embedding 提取
- [ ] reference_data JSONB 存儲
- [ ] 匹配算法實作
### Phase 4: 匹配算法實作
- [ ] Strategy 1: Best Match
- [ ] Strategy 2: Voting
- [ ] Strategy 3: Weighted Average
- [ ] Strategy 4: Combined
- [ ] API 端點設計
### Phase 5: 声音识别扩展 (待辦事項)
- [ ] sound_embeddings 定義
- [ ] 動物叫聲 embedding 提取
- [ ] 雷雨聲 embedding 提取
- [ ] 槍炮聲 embedding 提取
- [ ] 樂器聲 embedding 提取
---
## 待辦事項
| 項目 | 優先級 | 說明 |
|------|--------|------|
| Migration 023 | 高 | Phase 1 |
| TMDB 整合實作 | 高 | Phase 2 |
| Logo/Symbol Identity | 中 | Phase 3 |
| 匹配算法實作 | 中 | Phase 4 |
| 声音识别扩展 | 低 | Phase 5+ (待辦事項) |
---
## 限制條件
- 本設計為全新架構，需要資料庫 Migration
- CLIP ViT-L/14 需要 MPS 或 CUDA 支持
- TMDB 整合需要 TMDB API Key
- 声音识别列为 Phase 5+ 待辦事項
---
## 相關文件
- `docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md` - 核心架構設計
- `docs_v1.0/IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md` - API 設計
- `docs_v1.0/ARCHITECTURE/CLIP_EMBEDDING_BENCHMARK_PLAN.md` - CLIP 测试计划
- `docs_v1.0/STANDARDS/DOCS_STANDARD.md` - 文件創建規範
---
## 版本資訊
- 版本: V1.0
- 建立日期: 2026-04-28
- 文件更新: 2026-04-28

120
docs_v1.0/ARCHITECTURE/JOB_WORKER_IMPLEMENTATION_PLAN.md
View File

@@ -2,18 +2,20 @@
document_type: "architecture_design" document_type: "architecture_design"
service: "MOMENTRY_CORE" service: "MOMENTRY_CORE"
title: "Job Worker 實作計畫" title: "Job Worker 實作計畫"
date: "2026-03-24" date: "2026-04-27"
version: "V1.0" version: "V1.2"
status: "active" status: "active"
owner: "Warren" owner: "Warren"
created_by: "OpenCode" created_by: "OpenCode"
tags: tags:
- "實作計畫" - "實作計畫"
- "worker" - "worker"
- "processing_status"
ai_query_hints: ai_query_hints:
- "查詢 Job Worker 實作計畫 的內容" - "查詢 Job Worker 實作計畫 的內容"
- "Job Worker 實作計畫 的主要目的是什麼？" - "Job Worker 實作計畫 的主要目的是什麼？"
- "如何操作或實施 Job Worker 實作計畫？" - "如何操作或實施 Job Worker 實作計畫？"
- "processing_status 字段設計"
--- ---
# Job Worker 實作計畫 # Job Worker 實作計畫
@@ -22,7 +24,7 @@ ai_query_hints:
|------|------| |------|------|
| 建立者 | Warren / OpenCode | | 建立者 | Warren / OpenCode |
| 建立時間 | 2026-03-24 | | 建立時間 | 2026-03-24 |
| 文件版本 | V1.1 | | 文件版本 | V1.2 |
| 狀態 | ✅ 已實作 | | 狀態 | ✅ 已實作 |
--- ---
@@ -33,6 +35,7 @@ ai_query_hints:
|------|------|------|--------| |------|------|------|--------|
| V1.0 | 2026-03-24 | 建立實作計畫 | OpenCode | | V1.0 | 2026-03-24 | 建立實作計畫 | OpenCode |
| V1.1 | 2026-03-25 | 實作完成，更新狀態 | OpenCode | | V1.1 | 2026-03-25 | 實作完成，更新狀態 | OpenCode |
| V1.2 | 2026-04-27 | 添加 processing_status 字段設計說明 | OpenCode |
--- ---
@@ -689,6 +692,117 @@ export REDIS_URL=redis://:accusys@localhost:6379
| `completed` | 所有處理完成 | | `completed` | 所有處理完成 |
| `failed` | 處理失敗 | | `failed` | 處理失敗 |
### B.1 videos 表 processing_status 欄位
| 值 | 說明 | 適用場景 |
|------|------|----------|
| `REGISTERED` | 已註冊 | 新註冊的視頻，尚未觸發處理 |
| `PENDING` | 等待處理 | 已觸發處理，等待作業分配 |
| `PROBING` | 探測中 | ffprobe 分析執行中 |
| `ASR` | ASR 處理中 | ASR 作業執行中 |
| `OCR` | OCR 處理中 | OCR 作業執行中 |
| `YOLO` | YOLO 處理中 | YOLO 作業執行中 |
| `FACE` | 人臉偵測中 | Face 作業執行中 |
| `POSE` | 姿態估計中 | Pose 作業執行中 |
| `CUT` | 分塊處理中 | Cut 作業執行中 |
| `ASRX` | 說話者分離中 | ASRX 作業執行中 |
| `COMPLETED` | 完成 | 所有處理完成 |
| `FAILED` | 失敗 | 處理失敗 |
| `PAUSED` | 暫停 | 斷點續傳暫停狀態 |
| `RESUMING` | 恢復中 | 斷點續傳恢復中 |
#### B.1.1 status 與 processing_status 的關係
| status | processing_status | 說明 |
|--------|-------------------|------|
| `pending` | `REGISTERED` | 新註冊，Portal顯示「已註冊」（藍色） |
| `processing` | `PENDING` | 已觸發，Portal顯示「等待處理」（黃色） |
| `processing` | `PROBING`/`ASR`/... | 各處理器執行中，Portal顯示處理器名稱（靛藍） |
| `completed` | `COMPLETED` | 完成，Portal顯示「已完成」（綠色） |
| `failed` | `FAILED` | 失敗，Portal顯示「處理失敗」（紅色） |
#### B.1.2 Portal顯示優先級
Portal 優先使用 `processing_status`（詳細狀態），Fallback 使用 `status`（基本狀態）。
#### B.1.3 processing_status JSONB 結構（V1.2 起）
從 V1.2 起，`processing_status` 改為 **JSONB** 格式，支持多層級進度追蹤。
詳細規範請參考: `REFERENCE/PROCESSING_STATUS_JSONB_SPEC.md`
##### JSONB 主要字段
| 字段 | 類型 | 說明 |
|------|------|------|
| `phase` | String | 當前階段（PROCESSING, COMPLETED, FAILED） |
| `active_processors` | Array[String] | 正在執行的處理器列表（大寫） |
| `total_frames` | Integer | 影片總帧數 |
| `processing_summary` | Object | 處理器完成狀態總覽 |
| `pre_chunks_summary` | Object | pre_chunks 表絕計（按處理器） |
| `chunks_summary` | Object | chunks 表絕計（按 Rule） |
| `agents` | Object | Agent 任務狀態（5W1H, Translation） |
| `vectorization_summary` | Object | 向量化絕計 |
| `progress` | Object | 各處理器詳細進度 |
##### JSONB 範例（處理中）
```json
{
"phase": "PROCESSING",
"active_processors": ["YOLO", "OCR"],
"total_frames": 412343,
"progress": {
"YOLO": {
"current_frame": 25000,
"percentage": 6.0,
"status": "running"
}
}
}
```
##### JSONB 範例（完成）
```json
{
"phase": "COMPLETED",
"active_processors": [],
"pre_chunks_summary": {
"total_records": 25000,
"by_processor": {
"asr": {"records": 1466},
"yolo": {"records": 11000}
}
},
"chunks_summary": {
"total_chunks": 2798,
"by_rule": {
"rule_1": {"chunks_count": 1466},
"rule_3": {"chunks_count": 1332}
}
},
"agents": {
"5w1h": {"status": "completed"}
}
}
```
##### SQL 查詢範例
```sql
-- 取得 phase
SELECT processing_status->>'phase' FROM videos WHERE uuid = 'xxx';
-- 取得 active_processors
SELECT processing_status->'active_processors' FROM videos WHERE uuid = 'xxx';
-- 取得 pre_chunks 絕計
SELECT processing_status->'pre_chunks_summary'->>'total_records' FROM videos;
```
---
### C. processor_results 表 status 欄位 ### C. processor_results 表 status 欄位
| 值 | 說明 | | 值 | 說明 |

2
docs_v1.0/ARCHITECTURE/MCP_LAZY_LOADING_STRATEGY.md
View File

@@ -546,4 +546,4 @@ switch_mcp status
年度節省: 年度節省:
$216 USD ✅ $216 USD ✅
``` ```

2
docs_v1.0/ARCHITECTURE/MODULE_STANDARDIZATION_IMPLEMENTATION_PLAN.md
View File

@@ -442,4 +442,4 @@ tests/
*版本: 1.0.0* *版本: 1.0.0*
*創建日期: 2026-03-27* *創建日期: 2026-03-27*
*負責人: Warren (Technical Lead)* *負責人: Warren (Technical Lead)*
*狀態: 審核中* *狀態: 審核中*

158
docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md
View File

@@ -36,14 +36,18 @@ Identity ──[出現在]──→ File
任何可命名的事物都是 Identity： 任何可命名的事物都是 Identity：
| 類型 | 說明 | 範例 | | 類型 | 說明 | 範例 | 參考向量 |
|------|------|------| |------|------|------|----------|
| people | 人 | 演員、公眾人物、虛構角色 | | people | 人 | 演員、公眾人物、虛構角色 | face_embedding (512), voice_embedding (192) |
| object | 物件 | 車輛、建築、道具 | | logo | 商標 | LV logo、Nike 勾勾、Accusys Logo | identity_embedding (768) |
| brand | 品牌 | LV、Hello Kitty、Nike | | symbol | 符號 | 交通標誌、品牌符號 | identity_embedding (768) |
| logo | 商標 | LV logo、Nike 勾勾 | | object | 物件 | 車輛、建築、道具 | identity_embedding (768) |
| concept | 概念 | 愛、自由、科技 | | brand | 品牌 | LV、Hello Kitty、Nike | identity_embedding (768) |
| scene | 場景 | 室內、室外、街道 | | concept | 概念 | 愛、自由、科技 | identity_embedding (768) |
| scene | 場景 | 室內、室外、街道 | identity_embedding (768) |
| sound | 聲音 | 動物叫聲、雷雨、槍炮、樂器 | sound_embedding (TBD) |
| animal | 動物 | 狗、貓、鳥 | identity_embedding (768) + sound_embedding (TBD) |
| environmental | 環境音 | 雨聲、風聲、海浪 | sound_embedding (TBD) |
### 2.2 People Identity 特殊設計 ### 2.2 People Identity 特殊設計
@@ -87,12 +91,68 @@ CREATE TABLE identities (
-- 參考向量 (用於自動比對) -- 參考向量 (用於自動比對)
face_embedding VECTOR(512), -- 參考臉向量 (ArcFace) face_embedding VECTOR(512), -- 參考臉向量 (ArcFace)
voice_embedding VECTOR(192), -- 參考聲紋向量 (ECAPA-TDNN) voice_embedding VECTOR(192), -- 參考聲紋向量 (ECAPA-TDNN)
identity_embedding VECTOR(768), -- 身份向量 (CLIP ViT-L/14) 用於 logo/symbol/object
-- 1對多參考向量存儲 (多角度/多場景/多版本)
reference_data JSONB, -- 存儲多個 embedding，結構見下方說明
created_at TIMESTAMPTZ DEFAULT NOW(), created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW() updated_at TIMESTAMPTZ DEFAULT NOW()
); );
``` ```
#### reference_data JSONB 結構
```json
{
"face_embeddings": [
{
"embedding": [0.1, 0.2, ...], // 512-dim ArcFace
"source": "tmdb_profile", // tmdb_profile, tmdb_images, manual_upload, auto_detection
"image_url": "https://...", // 來源圖片 URL
"angle": "frontal", // frontal, profile_left, profile_right, three_quarter
"quality_score": 0.95, // 人臉質量評分
"created_at": "2026-04-28T10:00:00Z"
}
],
"voice_embeddings": [
{
"embedding": [0.1, 0.2, ...], // 192-dim ECAPA-TDNN
"source": "video_segment",
"file_uuid": "xxx",
"timestamp_start": 120.5,
"timestamp_end": 135.2,
"quality_score": 0.88,
"created_at": "2026-04-28T10:00:00Z"
}
],
"identity_embeddings": [
{
"embedding": [0.1, 0.2, ...], // 768-dim CLIP ViT-L/14
"source": "logo_image", // logo_image, symbol_image, object_image
"image_url": "https://...",
"context": "brand_logo", // brand_logo, symbol, object, concept
"created_at": "2026-04-28T10:00:00Z"
}
],
"sound_embeddings": [
{
"embedding": [0.1, 0.2, ...], // TBD (動物、雷雨、槍炮、樂器)
"source": "audio_segment",
"file_uuid": "xxx",
"timestamp_start": 10.0,
"timestamp_end": 15.0,
"sound_type": "animal_dog_bark", // animal_dog_bark, environmental_thunder, weapon_gunshot, musical_guitar
"created_at": "2026-04-28T10:00:00Z"
}
],
"image_urls": [
"https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png",
"https://image.tmdb.org/t/p/original/xxx.jpg"
]
}
```
--- ---
## 3. File 設計 ## 3. File 設計
@@ -270,23 +330,92 @@ TMDB API → 電影資訊 + 演員名單 → 自動建立 Identity → 關聯到
- 系統自動從 TMDB API 獲取： - 系統自動從 TMDB API 獲取：
- 演員名單 + 角色名 - 演員名單 + 角色名
- 演員人臉照 (profile_path) - 演員人臉照 (profile_path)
- 演員多張照片 (TMDB /person/:id/images 端點)
- 電影元數據 - 電影元數據
2. **建立 Identity**： 2. **建立 Identity**：
- 自動建立或更新 Identity（演員） - 自動建立或更新 Identity（演員）
- 儲存 TMDB ID + 人臉照 URL - 儲存 TMDB ID + 多張人臉照 URL
- 關聯到 File（這部電影） - 關聯到 File（這部電影）
3. **提取參考向量**： 3. **提取參考向量 (1對多)**：
- 下載 TMDB 人臉照 - 下載 TMDB 多張人臉照 (不同角度、定妝造型)
- 提取 face_embedding (512-dim) - 對每張照片提取 face_embedding (512-dim ArcFace)
- 儲存到 identities 表 - 將多個 embedding 存儲到 reference_data JSONB：
```json
{
"face_embeddings": [
{
"embedding": [...],
"source": "tmdb_images",
"image_url": "https://image.tmdb.org/t/p/original/xxx.jpg",
"angle": "frontal",
"quality_score": 0.95
},
{
"embedding": [...],
"source": "tmdb_images",
"image_url": "https://image.tmdb.org/t/p/original/yyy.jpg",
"angle": "profile_left",
"quality_score": 0.88
}
]
}
```
- 計算 centroid（中心向量）存儲到 face_embedding 字段
4. **後續 AI 識別**： 4. **後續 AI 識別**：
- 系統檢測 File 中的 Face - 系統檢測 File 中的 Face
- 自動匹配到已有的 Identity - 自動匹配到已有的 Identity（使用 1對多匹配算法）
- 更新 file_identities 表 - 更新 file_identities 表
#### 6.2.1 1對多匹配算法
```python
def match_face_to_identity(detected_embedding, identity_reference_data):
"""
1對多匹配：檢測到的臉與 Identity 的多個參考向量比對
策略：
1. 最佳匹配：取所有參考向量中的最高相似度
2. 投票機制：統計超過閾值的參考向量數量
3. 加權平均：根據質量評分加權計算相似度
"""
face_embeddings = identity_reference_data.get("face_embeddings", [])
if not face_embeddings:
return None
# 策略 1: 最佳匹配
similarities = [
cosine_similarity(detected_embedding, ref["embedding"])
for ref in face_embeddings
]
best_match = max(similarities)
# 策略 2: 投票機制
threshold = 0.85
votes = sum(1 for sim in similarities if sim >= threshold)
vote_ratio = votes / len(similarities)
# 策略 3: 加權平均
weighted_sim = sum(
sim * ref.get("quality_score", 1.0)
for sim, ref in zip(similarities, face_embeddings)
) / sum(ref.get("quality_score", 1.0) for ref in face_embeddings)
# 綜合評分
final_score = (best_match * 0.5 + vote_ratio * 0.3 + weighted_sim * 0.2)
return {
"best_match": best_match,
"vote_ratio": vote_ratio,
"weighted_sim": weighted_sim,
"final_score": final_score,
"is_match": final_score >= threshold
}
```
### 6.3 TMDB API 端點 ### 6.3 TMDB API 端點
| 端點 | 說明 | | 端點 | 說明 |
@@ -539,3 +668,4 @@ GET /api/v1/identities/search?q=張&type=people&category=P-001
| 版本 | 日期 | 目的 | 操作人 | | 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------| |------|------|------|--------|
| V1.0 | 2026-04-25 | 全新設計 (File + Identity + Category) | OpenCode | | V1.0 | 2026-04-25 | 全新設計 (File + Identity + Category) | OpenCode |
| V1.1 | 2026-04-28 | 添加 identity_embedding (768維 CLIP)、reference_data JSONB (1對多參考向量)、擴展 identity_type (logo/symbol/sound/animal/environmental)、TMDB 多角度人臉整合 | OpenCode |

2
docs_v1.0/ARCHITECTURE/MONITORING_ARCHITECTURE.md
View File

@@ -389,4 +389,4 @@ Momentry Core 的監控架構設計提供：
3. **數據驅動**：基於數據的決策與優化 3. **數據驅動**：基於數據的決策與優化
4. **持續改進**：不斷優化監控策略與工具 4. **持續改進**：不斷優化監控策略與工具
通過完善的監控體系，確保系統穩定運行，快速發現並解決問題，為用戶提供高質量的服務。 通過完善的監控體系，確保系統穩定運行，快速發現並解決問題，為用戶提供高質量的服務。

2
docs_v1.0/ARCHITECTURE/MONITORING_SETUP_GUIDE.md
View File

@@ -189,4 +189,4 @@ async fn metrics_handler() -> impl IntoResponse {
--- ---
**最後更新**: 2026-04-22 **最後更新**: 2026-04-22
**部署時間**: 10-30 分鐘 **部署時間**: 10-30 分鐘

120
docs_v1.0/ARCHITECTURE/MULTIMODAL_SEARCH_DESIGN_V5.md
View File

@@ -130,8 +130,8 @@ graph TD
### 3.1 Chunk 定義 (Video Chunk) ### 3.1 Chunk 定義 (Video Chunk)
**定義**: 特定視頻文件 (`uuid`) 內，從 `start_frame` 到 `end_frame` 之間的**連續畫面**。 **定義**: 特定視頻文件 (`uuid`) 內，從 `start_frame` 到 `end_frame` 之間的**連續畫面**。
**存儲**: **存儲**:
* **PostgreSQL**: 權威主數據 (Metadata, Relations, Complex Queries). * **PostgreSQL**: 權威主數據 (Metadata, Relations, Complex Queries).
* **Qdrant**: 向量檢索與 Payload 過濾 (Fast Retrieval). * **Qdrant**: 向量檢索與 Payload 過濾 (Fast Retrieval).
### 3.2 數據庫 Schema (PostgreSQL) ### 3.2 數據庫 Schema (PostgreSQL)
@@ -201,7 +201,7 @@ CREATE TABLE talents (
-- 劇中角色庫 (Character) -- 劇中角色庫 (Character)
CREATE TABLE characters ( CREATE TABLE characters (
id BIGSERIAL PRIMARY KEY, id BIGSERIAL PRIMARY KEY,
video_uuid TEXT NOT NULL, file_uuid TEXT NOT NULL,
name TEXT NOT NULL, -- 角色名 name TEXT NOT NULL, -- 角色名
language_track TEXT DEFAULT 'original', -- 語言軌道 (dub_zh_tw, dub_en) language_track TEXT DEFAULT 'original', -- 語言軌道 (dub_zh_tw, dub_en)
is_voice_only BOOLEAN DEFAULT FALSE, -- 無臉角色 (動畫/旁白/AI) is_voice_only BOOLEAN DEFAULT FALSE, -- 無臉角色 (動畫/旁白/AI)
@@ -229,7 +229,7 @@ CREATE TABLE identity_bindings (
```json ```json
{ {
"uuid": "384b0ff44aaaa1f1", "uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"chunk_id": "chunk_001", "chunk_id": "chunk_001",
"start_frame": 100, "start_frame": 100,
"end_frame": 200, "end_frame": 200,
@@ -255,48 +255,48 @@ CREATE TABLE identity_bindings (
## 4. 搜尋維度 (5W1H + Context + Sports) ## 4. 搜尋維度 (5W1H + Context + Sports)
### 4.1 人 (Person / Who) ### 4.1 人 (Person / Who)
* **身份解析**: `speaker_X` / `face_Y` -> `talent` -> `character`. * **身份解析**: `speaker_X` / `face_Y` -> `talent` -> `character`.
* **屬性過濾**: 性別、年齡、體型、五官、服裝 (VLM/Heuristics). * **屬性過濾**: 性別、年齡、體型、五官、服裝 (VLM/Heuristics).
* **聲紋檢索**: 上傳音頻片段 -> Cosine Similarity (ECAPA-TDNN 192-dim). * **聲紋檢索**: 上傳音頻片段 -> Cosine Similarity (ECAPA-TDNN 192-dim).
### 4.2 事 (Event / What) ### 4.2 事 (Event / What)
* **語音語義**: ASR 文本向量檢索. * **語音語義**: ASR 文本向量檢索.
* **視覺行為**: Pose Analyzer 標籤 (打架、擁抱、揮手). * **視覺行為**: Pose Analyzer 標籤 (打架、擁抱、揮手).
* **融合事件**: `gunfight`, `romantic_scene`, `interview` (多信號規則融合). * **融合事件**: `gunfight`, `romantic_scene`, `interview` (多信號規則融合).
### 4.3 時 (Time / When) ### 4.3 時 (Time / When)
* **精確幀**: `start_frame`, `end_frame`. * **精確幀**: `start_frame`, `end_frame`.
* **相對時間**: "最後 5 分鐘". * **相對時間**: "最後 5 分鐘".
### 4.4 地 (Location / Where) ### 4.4 地 (Location / Where)
* **場景語義**: Places365 -> 宏觀/語義/原始三層映射 (e.g., `beach` -> `outdoor`). * **場景語義**: Places365 -> 宏觀/語義/原始三層映射 (e.g., `beach` -> `outdoor`).
* **天氣/環境**: `rainy`, `sunny`, `night` (Context Inference). * **天氣/環境**: `rainy`, `sunny`, `night` (Context Inference).
### 4.5 物 (Object / Which) ### 4.5 物 (Object / Which)
* **YOLO 物件**: `car`, `gun`, `dog`. * **YOLO 物件**: `car`, `gun`, `dog`.
* **音頻物件**: `siren`, `barking`. * **音頻物件**: `siren`, `barking`.
### 4.6 上下文 (Context) ### 4.6 上下文 (Context)
* **季節**: `winter` (雪/圍巾), `summer` (泳衣/太陽眼鏡). * **季節**: `winter` (雪/圍巾), `summer` (泳衣/太陽眼鏡).
* **節慶**: `christmas` (聖誕樹/鈴鐺聲), `cny` (鞭炮/紅燈籠). * **節慶**: `christmas` (聖誕樹/鈴鐺聲), `cny` (鞭炮/紅燈籠).
### 4.7 運動 (Sports) ### 4.7 運動 (Sports)
* **球類**: 棒球 (球棒/打擊聲/揮棒), 籃球 (運球聲/投籃), 足球 (哨音/踢球). * **球類**: 棒球 (球棒/打擊聲/揮棒), 籃球 (運球聲/投籃), 足球 (哨音/踢球).
* **水上/冰上運動 (詳細特徵)**: * **水上/冰上運動 (詳細特徵)**:
* **🏊 游泳 (Swimming)**: * **🏊 游泳 (Swimming)**:
* *場景*: `swimming_pool`, `water`. * *場景*: `swimming_pool`, `water`.
* *物件*: `goggles`, `swim_cap`, `lane_rope`. * *物件*: `goggles`, `swim_cap`, `lane_rope`.
* *動作*: `freestyle_stroke` (自由式), `breaststroke` (蛙式), `butterfly` (蝶式), `backstroke` (仰式). * *動作*: `freestyle_stroke` (自由式), `breaststroke` (蛙式), `butterfly` (蝶式), `backstroke` (仰式).
* *音頻*: `water_splash` (水花聲), `rhythmic_breathing` (規律換氣聲). * *音頻*: `water_splash` (水花聲), `rhythmic_breathing` (規律換氣聲).
* **🤿 跳水 (Diving)**: * **🤿 跳水 (Diving)**:
* *場景*: `diving_board`, `platform_10m`. * *場景*: `diving_board`, `platform_10m`.
* *動作序列*: `takeoff` (起跳) → `aerial_twist` (空中翻轉) → `entry` (入水). * *動作序列*: `takeoff` (起跳) → `aerial_twist` (空中翻轉) → `entry` (入水).
* *音頻*: `high_pitch_whistle` (哨音) → `massive_splash` (巨大入水聲). * *音頻*: `high_pitch_whistle` (哨音) → `massive_splash` (巨大入水聲).
* **⛸️ 滑冰 (Ice Skating)**: * **⛸️ 滑冰 (Ice Skating)**:
* *場景*: `ice_rink`, `winter`. * *場景*: `ice_rink`, `winter`.
* *物件*: `ice_skates`, `barrier`. * *物件*: `ice_skates`, `barrier`.
* *動作*: `gliding` (滑行), `spinning` (旋轉), `jumping` (跳躍). * *動作*: `gliding` (滑行), `spinning` (旋轉), `jumping` (跳躍).
* *音頻*: `blade_on_ice` (冰刀摩擦聲), `classical_music` (花滑配樂). * *音頻*: `blade_on_ice` (冰刀摩擦聲), `classical_music` (花滑配樂).
--- ---
@@ -328,53 +328,53 @@ CREATE TABLE identity_bindings (
### 5.3 混合查詢 (Hybrid Query) ### 5.3 混合查詢 (Hybrid Query)
1. **解析身份 (Who)**: 1. **解析身份 (Who)**:
* 查詢 `identity_bindings`，找到符合 "穿西裝男人" 的機器 ID (`face_5`). * 查詢 `identity_bindings`，找到符合 "穿西裝男人" 的機器 ID (`face_5`).
2. **構建 SQL (PostgreSQL)**: 2. **構建 SQL (PostgreSQL)**:
```sql ```sql
SELECT chunk_id, start_frame, end_frame FROM chunks SELECT chunk_id, start_frame, end_frame FROM chunks
WHERE uuid = '384b0ff44aaaa1f1' WHERE uuid = '384b0ff44aaaa1f14cb2cd63b3fea966'
AND 'face_5' = ANY(face_ids) AND 'face_5' = ANY(face_ids)
AND scene_semantic @> ARRAY['office'] AND scene_semantic @> ARRAY['office']
AND action_tags @> ARRAY['arguing', 'shouting'] AND action_tags @> ARRAY['arguing', 'shouting']
AND audio_events @> ARRAY['dog_bark']; AND audio_events @> ARRAY['dog_bark'];
``` ```
3. **構建 Vector Search (Qdrant)**: 3. **構建 Vector Search (Qdrant)**:
* 如果 SQL 結果為空或用戶語意模糊，切換至 Qdrant Payload Filter + Vector Similarity. * 如果 SQL 結果為空或用戶語意模糊，切換至 Qdrant Payload Filter + Vector Similarity.
4. **返回結果**: 4. **返回結果**:
* Chunk 列表，包含精確的 `start_frame`, `end_frame`. * Chunk 列表，包含精確的 `start_frame`, `end_frame`.
--- ---
## 6. 實施路線圖 (Implementation Roadmap) ## 6. 實施路線圖 (Implementation Roadmap)
### Phase 1: 基礎設施與 Schema (第 1 週) ### Phase 1: 基礎設施與 Schema (第 1 週)
- [ ] 執行 PostgreSQL Schema V5 更新 (Chunks, Talents, Castings, Bindings, Sports). * [ ] 執行 PostgreSQL Schema V5 更新 (Chunks, Talents, Castings, Bindings, Sports).
- [ ] 建立 Qdrant Collection (`momentry_chunks`)，配置 Multi-Vector 和 Payload 索引. * [ ] 建立 Qdrant Collection (`momentry_chunks`)，配置 Multi-Vector 和 Payload 索引.
- [ ] 編寫 `scene_hierarchy_processor.py` (場景映射層). * [ ] 編寫 `scene_hierarchy_processor.py` (場景映射層).
- [ ] 編寫 `scene_mapping.json`. * [ ] 編寫 `scene_mapping.json`.
### Phase 2: 信號提取模組 (第 2-3 週) ### Phase 2: 信號提取模組 (第 2-3 週)
- [ ] 部署 `audio_event_processor.py` (PANNs/YAMNet). * [ ] 部署 `audio_event_processor.py` (PANNs/YAMNet).
- [ ] 部署 `pose_analyzer_processor.py` (基礎規則：站/坐/揮手/打鬥/泳姿). * [ ] 部署 `pose_analyzer_processor.py` (基礎規則：站/坐/揮手/打鬥/泳姿).
- [ ] 部署 `context_inference_processor.py` (季節/節慶/天氣推斷). * [ ] 部署 `context_inference_processor.py` (季節/節慶/天氣推斷).
- [ ] 部署 `sports_classifier_processor.py` (運動分類規則引擎). * [ ] 部署 `sports_classifier_processor.py` (運動分類規則引擎).
- [ ] 確保所有處理器的輸出能正確映射並寫入 `chunks` 表. * [ ] 確保所有處理器的輸出能正確映射並寫入 `chunks` 表.
### Phase 3: 身份綁定系統 (第 4 週) ### Phase 3: 身份綁定系統 (第 4 週)
- [ ] 部署 `voice_embedding_extractor.py` (聲紋提取與比對). * [ ] 部署 `voice_embedding_extractor.py` (聲紋提取與比對).
- [ ] 實現 `identity_resolver.py`：將機器 ID 綁定到 `talents` 和 `characters`. * [ ] 實現 `identity_resolver.py`：將機器 ID 綁定到 `talents` 和 `characters`.
- [ ] 提供 API: `POST /api/v1/person/bind`. * [ ] 提供 API: `POST /api/v1/person/bind`.
### Phase 4: 搜尋引擎整合 (第 5 週) ### Phase 4: 搜尋引擎整合 (第 5 週)
- [ ] 開發 `search_processor.py` (LLM Parser + SQL Builder). * [ ] 開發 `search_processor.py` (LLM Parser + SQL Builder).
- [ ] 實現 `POST /api/v1/search/smart` 端點. * [ ] 實現 `POST /api/v1/search/smart` 端點.
- [ ] 測試複雜查詢 (人+事+時+地+物+上下文+運動). * [ ] 測試複雜查詢 (人+事+時+地+物+上下文+運動).
### Phase 5: 優化與前端對接 (第 6 週) ### Phase 5: 優化與前端對接 (第 6 週)
- [ ] 性能優化 (索引調整、查詢緩存). * [ ] 性能優化 (索引調整、查詢緩存).
- [ ] 前端搜尋介面展示多維度過濾條件. * [ ] 前端搜尋介面展示多維度過濾條件.
- [ ] 前端視頻播放器跳轉至精確 `start_frame`. * [ ] 前端視頻播放器跳轉至精確 `start_frame`.
--- ---

36
docs_v1.0/ARCHITECTURE/ON_THE_FLY_PROCESSING_DESIGN.md
View File

@@ -434,24 +434,24 @@ class ParallelScheduler:
self.max_workers = max_workers self.max_workers = max_workers
self.executor = concurrent.futures.ThreadPoolExecutor(max_workers) self.executor = concurrent.futures.ThreadPoolExecutor(max_workers)
async def schedule_processing(self, video_uuid): async def schedule_processing(self, file_uuid):
"""調度處理任務""" """調度處理任務"""
# Phase 1: 上傳時即時處理 # Phase 1: 上傳時即時處理
fast_tasks = [ fast_tasks = [
self.executor.submit(self.run_scene, video_uuid), self.executor.submit(self.run_scene, file_uuid),
self.executor.submit(self.run_face, video_uuid), self.executor.submit(self.run_face, file_uuid),
self.executor.submit(self.run_cut, video_uuid) self.executor.submit(self.run_cut, file_uuid)
] ]
# 等待上傳完成 # 等待上傳完成
await self.wait_for_upload_complete(video_uuid) await self.wait_for_upload_complete(file_uuid)
# Phase 2: 上傳完成後處理 # Phase 2: 上傳完成後處理
slow_tasks = [ slow_tasks = [
self.executor.submit(self.run_asr, video_uuid), self.executor.submit(self.run_asr, file_uuid),
self.executor.submit(self.run_ocr, video_uuid), self.executor.submit(self.run_ocr, file_uuid),
self.executor.submit(self.run_yolo, video_uuid), self.executor.submit(self.run_yolo, file_uuid),
self.executor.submit(self.run_pose, video_uuid) self.executor.submit(self.run_pose, file_uuid)
] ]
# 收集結果 # 收集結果
@@ -488,11 +488,11 @@ from fastapi import WebSocket
class ProgressWebSocket: class ProgressWebSocket:
"""即時進度推送""" """即時進度推送"""
async def broadcast_progress(self, video_uuid, processor, progress): async def broadcast_progress(self, file_uuid, processor, progress):
"""廣播處理進度""" """廣播處理進度"""
message = { message = {
"type": "progress", "type": "progress",
"video_uuid": video_uuid, "file_uuid": file_uuid,
"processor": processor, "processor": processor,
"progress": progress, "progress": progress,
"timestamp": time.time() "timestamp": time.time()
@@ -500,11 +500,11 @@ class ProgressWebSocket:
await self.websocket.send_json(message) await self.websocket.send_json(message)
async def broadcast_result(self, video_uuid, processor, result): async def broadcast_result(self, file_uuid, processor, result):
"""廣播處理結果""" """廣播處理結果"""
message = { message = {
"type": "result", "type": "result",
"video_uuid": video_uuid, "file_uuid": file_uuid,
"processor": processor, "processor": processor,
"result": result, "result": result,
"timestamp": time.time() "timestamp": time.time()
@@ -607,20 +607,20 @@ class PriorityProcessor:
"low": ["pose"] # 可選 "low": ["pose"] # 可選
} }
async def process_by_priority(self, video_uuid): async def process_by_priority(self, file_uuid):
# 高優先級：立即處理 # 高優先級：立即處理
for processor in self.PRIORITY["high"]: for processor in self.PRIORITY["high"]:
await self.run(processor, video_uuid) await self.run(processor, file_uuid)
# 中優先級：並行處理 # 中優先級：並行處理
await asyncio.gather(*[ await asyncio.gather(*[
self.run(p, video_uuid) self.run(p, file_uuid)
for p in self.PRIORITY["medium"] for p in self.PRIORITY["medium"]
]) ])
# 低優先級：背景處理 # 低優先級：背景處理
for processor in self.PRIORITY["low"]: for processor in self.PRIORITY["low"]:
asyncio.create_task(self.run(processor, video_uuid)) asyncio.create_task(self.run(processor, file_uuid))
``` ```
### 3. 快取預載入 ### 3. 快取預載入
@@ -706,4 +706,4 @@ class PreloadManager:
- 上傳期間: 快速結果即時顯示 - 上傳期間: 快速結果即時顯示
- 上傳完成: 1-3 分鐘後完整結果 - 上傳完成: 1-3 分鐘後完整結果
- 用戶體驗: 良好（有即時反饋） - 用戶體驗: 良好（有即時反饋）
``` ```

2
docs_v1.0/ARCHITECTURE/PARENT_CHUNK_COVERAGE_ANALYSIS.md
View File

@@ -1,6 +1,6 @@
# Parent Chunk 覆蓋率分析 # Parent Chunk 覆蓋率分析
> **日期**: 2026-04-14 | **影片 UUID**: 384b0ff44aaaa1f1 > **日期**: 2026-04-14 | **影片 UUID**: 384b0ff44aaaa1f14cb2cd63b3fea966
--- ---

2
docs_v1.0/ARCHITECTURE/PERFORMANCE_AND_SCALABILITY.md
View File

@@ -300,4 +300,4 @@ Momentry Core 的效能與可擴展性設計遵循以下原則：
3. **數據驅動**：建立完整的監控體系，基於實際數據進行決策 3. **數據驅動**：建立完整的監控體系，基於實際數據進行決策
4. **平衡策略**：在效能、成本、複雜度之間找到最佳平衡點 4. **平衡策略**：在效能、成本、複雜度之間找到最佳平衡點
通過實施上述策略，Momentry Core 能夠支持從小型部署到大型企業級應用的各種場景，提供穩定、高效、可擴展的視頻內容分析服務。 通過實施上述策略，Momentry Core 能夠支持從小型部署到大型企業級應用的各種場景，提供穩定、高效、可擴展的視頻內容分析服務。

40
docs_v1.0/ARCHITECTURE/PERSON_IDENTITY_INTEGRATION.md
View File

@@ -34,7 +34,7 @@
│ ├─ face_id (外键) │ │ ├─ face_id (外键) │
│ ├─ speaker_id (字符串) │ │ ├─ speaker_id (字符串) │
│ ├─ confidence (关联置信度) │ │ ├─ confidence (关联置信度) │
│ └─ video_uuid (来源视频) │ │ └─ file_uuid (来源视频) │
└─────────────────────────────────────────────┘ └─────────────────────────────────────────────┘
↓ ↓
┌─────────────────────────────────────────────┐ ┌─────────────────────────────────────────────┐
@@ -67,7 +67,7 @@ CREATE TABLE person_identities (
speaker_id VARCHAR(64), -- SPEAKER_00, SPEAKER_01, etc. speaker_id VARCHAR(64), -- SPEAKER_00, SPEAKER_01, etc.
-- 关联信息 -- 关联信息
video_uuid VARCHAR(255) NOT NULL, file_uuid VARCHAR(255) NOT NULL,
confidence DOUBLE PRECISION DEFAULT 0.0, confidence DOUBLE PRECISION DEFAULT 0.0,
-- 元数据 -- 元数据
@@ -86,10 +86,10 @@ CREATE TABLE person_identities (
is_confirmed BOOLEAN DEFAULT FALSE, -- 用户确认的身份 is_confirmed BOOLEAN DEFAULT FALSE, -- 用户确认的身份
-- 约束 -- 约束
CONSTRAINT unique_person_identity UNIQUE (video_uuid, face_identity_id, speaker_id) CONSTRAINT unique_person_identity UNIQUE (file_uuid, face_identity_id, speaker_id)
); );
CREATE INDEX idx_person_identities_video_uuid ON person_identities(video_uuid); CREATE INDEX idx_person_identities_file_uuid ON person_identities(file_uuid);
CREATE INDEX idx_person_identities_face ON person_identities(face_identity_id); CREATE INDEX idx_person_identities_face ON person_identities(face_identity_id);
CREATE INDEX idx_person_identities_speaker ON person_identities(speaker_id); CREATE INDEX idx_person_identities_speaker ON person_identities(speaker_id);
CREATE INDEX idx_person_identities_name ON person_identities(name); CREATE INDEX idx_person_identities_name ON person_identities(name);
@@ -103,7 +103,7 @@ CREATE TABLE person_appearances (
person_id VARCHAR(255) NOT NULL REFERENCES person_identities(person_id) ON DELETE CASCADE, person_id VARCHAR(255) NOT NULL REFERENCES person_identities(person_id) ON DELETE CASCADE,
-- 出场信息 -- 出场信息
video_uuid VARCHAR(255) NOT NULL, file_uuid VARCHAR(255) NOT NULL,
start_time DOUBLE PRECISION NOT NULL, start_time DOUBLE PRECISION NOT NULL,
end_time DOUBLE PRECISION NOT NULL, end_time DOUBLE PRECISION NOT NULL,
duration DOUBLE PRECISION NOT NULL, duration DOUBLE PRECISION NOT NULL,
@@ -120,8 +120,8 @@ CREATE TABLE person_appearances (
); );
CREATE INDEX idx_person_appearances_person ON person_appearances(person_id); CREATE INDEX idx_person_appearances_person ON person_appearances(person_id);
CREATE INDEX idx_person_appearances_video ON person_appearances(video_uuid); CREATE INDEX idx_person_appearances_video ON person_appearances(file_uuid);
CREATE INDEX idx_person_appearances_time ON person_appearances(video_uuid, start_time, end_time); CREATE INDEX idx_person_appearances_time ON person_appearances(file_uuid, start_time, end_time);
``` ```
### 3. 增强 chunks 表 ### 3. 增强 chunks 表
@@ -300,7 +300,7 @@ POST /api/v1/person/identify
Content-Type: application/json Content-Type: application/json
{ {
"video_uuid": "abc123", "file_uuid": "abc123",
"auto_match": true, "auto_match": true,
"match_threshold": 0.5 "match_threshold": 0.5
} }
@@ -325,7 +325,7 @@ Response:
### 2. 查询人物出场时间轴 ### 2. 查询人物出场时间轴
```http ```http
GET /api/v1/person/:person_id/timeline?video_uuid=abc123 GET /api/v1/person/:person_id/timeline?file_uuid=abc123
Response: Response:
{ {
@@ -471,12 +471,12 @@ pub async fn batch_insert_person_appearances(
for appearance in appearances { for appearance in appearances {
sqlx::query(r#" sqlx::query(r#"
INSERT INTO person_appearances ( INSERT INTO person_appearances (
person_id, video_uuid, start_time, end_time, person_id, file_uuid, start_time, end_time,
duration, confidence, metadata duration, confidence, metadata
) VALUES ($1, $2, $3, $4, $5, $6, $7) ) VALUES ($1, $2, $3, $4, $5, $6, $7)
"#) "#)
.bind(&appearance.person_id) .bind(&appearance.person_id)
.bind(&appearance.video_uuid) .bind(&appearance.file_uuid)
.bind(appearance.start_time) .bind(appearance.start_time)
.bind(appearance.end_time) .bind(appearance.end_time)
.bind(appearance.duration) .bind(appearance.duration)
@@ -496,13 +496,13 @@ pub async fn batch_insert_person_appearances(
```sql ```sql
-- 为常用查询添加复合索引 -- 为常用查询添加复合索引
CREATE INDEX idx_person_appearances_video_time CREATE INDEX idx_person_appearances_video_time
ON person_appearances(video_uuid, start_time, end_time); ON person_appearances(file_uuid, start_time, end_time);
CREATE INDEX idx_person_identities_video_face CREATE INDEX idx_person_identities_video_face
ON person_identities(video_uuid, face_identity_id); ON person_identities(file_uuid, face_identity_id);
CREATE INDEX idx_person_identities_video_speaker CREATE INDEX idx_person_identities_video_speaker
ON person_identities(video_uuid, speaker_id); ON person_identities(file_uuid, speaker_id);
``` ```
### 3. 缓存策略 ### 3. 缓存策略
@@ -512,9 +512,9 @@ ON person_identities(video_uuid, speaker_id);
pub async fn get_person_timeline_cached( pub async fn get_person_timeline_cached(
redis: &RedisClient, redis: &RedisClient,
person_id: &str, person_id: &str,
video_uuid: &str, file_uuid: &str,
) -> Result<Vec<PersonAppearance>> { ) -> Result<Vec<PersonAppearance>> {
let cache_key = format!("person_timeline:{}:{}", video_uuid, person_id); let cache_key = format!("person_timeline:{}:{}", file_uuid, person_id);
// 尝试从缓存获取 // 尝试从缓存获取
if let Some(cached) = redis.get(&cache_key).await? { if let Some(cached) = redis.get(&cache_key).await? {
@@ -522,7 +522,7 @@ pub async fn get_person_timeline_cached(
} }
// 从数据库查询 // 从数据库查询
let timeline = query_person_timeline_from_db(person_id, video_uuid).await?; let timeline = query_person_timeline_from_db(person_id, file_uuid).await?;
// 缓存结果（5分钟） // 缓存结果（5分钟）
redis.set_ex(&cache_key, &serde_json::to_string(&timeline)?, 300).await?; redis.set_ex(&cache_key, &serde_json::to_string(&timeline)?, 300).await?;
@@ -552,8 +552,8 @@ if confidence < MIN_MATCH_CONFIDENCE {
// 检查是否已存在相同关联 // 检查是否已存在相同关联
let existing = sqlx::query!( let existing = sqlx::query!(
"SELECT id FROM person_identities "SELECT id FROM person_identities
WHERE video_uuid = $1 AND face_identity_id = $2 AND speaker_id = $3", WHERE file_uuid = $1 AND face_identity_id = $2 AND speaker_id = $3",
video_uuid, face_id, speaker_id file_uuid, face_id, speaker_id
) )
.fetch_optional(db.pool()) .fetch_optional(db.pool())
.await?; .await?;
@@ -616,4 +616,4 @@ lazy_static! {
- [InsightFace Documentation](https://github.com/deepinsight/insightface) - [InsightFace Documentation](https://github.com/deepinsight/insightface)
- [WhisperX Speaker Diarization](https://github.com/m-bain/whisperX) - [WhisperX Speaker Diarization](https://github.com/m-bain/whisperX)
- [PostgreSQL pgvector](https://github.com/pgvector/pgvector) - [PostgreSQL pgvector](https://github.com/pgvector/pgvector)
- [DBSCAN Clustering Algorithm](https://scikit-learn.org/stable/modules/clustering.html#dbscan) - [DBSCAN Clustering Algorithm](https://scikit-learn.org/stable/modules/clustering.html#dbscan)

24
docs_v1.0/ARCHITECTURE/PERSON_IDENTITY_USAGE_GUIDE.md
View File

@@ -31,7 +31,7 @@ curl -X POST http://localhost:3002/api/v1/person/identify \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \ -H "X-API-Key: your_api_key" \
-d '{ -d '{
"video_uuid": "your_video_uuid", "file_uuid": "your_file_uuid",
"auto_match": true, "auto_match": true,
"match_threshold": 0.5 "match_threshold": 0.5
}' }'
@@ -60,7 +60,7 @@ curl -X POST http://localhost:3002/api/v1/person/identify \
查询某个人物在视频中的出场时间： 查询某个人物在视频中的出场时间：
```bash ```bash
curl -X GET "http://localhost:3002/api/v1/person/person_abc123/timeline?video_uuid=your_video_uuid" \ curl -X GET "http://localhost:3002/api/v1/person/person_abc123/timeline?file_uuid=your_file_uuid" \
-H "X-API-Key: your_api_key" -H "X-API-Key: your_api_key"
``` ```
@@ -152,7 +152,7 @@ curl -X GET http://localhost:3002/api/v1/chunks/sentence_0012/persons \
| person_id | VARCHAR(255) | 人物唯一标识 | | person_id | VARCHAR(255) | 人物唯一标识 |
| face_identity_id | INTEGER | 关联的人脸身份 ID | | face_identity_id | INTEGER | 关联的人脸身份 ID |
| speaker_id | VARCHAR(64) | 说话人 ID（SPEAKER_00, SPEAKER_01...） | | speaker_id | VARCHAR(64) | 说话人 ID（SPEAKER_00, SPEAKER_01...） |
| video_uuid | VARCHAR(255) | 来源视频 UUID | | file_uuid | VARCHAR(255) | 来源视频 UUID |
| name | VARCHAR(255) | 人物姓名（手动标注） | | name | VARCHAR(255) | 人物姓名（手动标注） |
| confidence | DOUBLE PRECISION | 关联置信度 | | confidence | DOUBLE PRECISION | 关联置信度 |
| appearance_count | INTEGER | 出场次数 | | appearance_count | INTEGER | 出场次数 |
@@ -164,7 +164,7 @@ curl -X GET http://localhost:3002/api/v1/chunks/sentence_0012/persons \
| 字段 | 类型 | 描述 | | 字段 | 类型 | 描述 |
|------|------|------| |------|------|------|
| person_id | VARCHAR(255) | 关联的人物身份 ID | | person_id | VARCHAR(255) | 关联的人物身份 ID |
| video_uuid | VARCHAR(255) | 视频 UUID | | file_uuid | VARCHAR(255) | 视频 UUID |
| start_time | DOUBLE PRECISION | 开始时间（秒） | | start_time | DOUBLE PRECISION | 开始时间（秒） |
| end_time | DOUBLE PRECISION | 结束时间（秒） | | end_time | DOUBLE PRECISION | 结束时间（秒） |
| duration | DOUBLE PRECISION | 持续时间（秒） | | duration | DOUBLE PRECISION | 持续时间（秒） |
@@ -225,11 +225,11 @@ const MIN_CONFIDENCE: f64 = 0.6;
```sql ```sql
-- 时间范围查询 -- 时间范围查询
CREATE INDEX idx_person_appearances_time CREATE INDEX idx_person_appearances_time
ON person_appearances(video_uuid, start_time, end_time); ON person_appearances(file_uuid, start_time, end_time);
-- 人物查询 -- 人物查询
CREATE INDEX idx_person_identities_video_uuid CREATE INDEX idx_person_identities_file_uuid
ON person_identities(video_uuid); ON person_identities(file_uuid);
-- 说话人查询 -- 说话人查询
CREATE INDEX idx_person_identities_speaker CREATE INDEX idx_person_identities_speaker
@@ -259,7 +259,7 @@ for video in /path/to/videos/*.mp4; do
curl -X POST http://localhost:3002/api/v1/person/identify \ curl -X POST http://localhost:3002/api/v1/person/identify \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \ -H "X-API-Key: your_api_key" \
-d "{\"video_uuid\": \"$uuid\", \"auto_match\": true}" -d "{\"file_uuid\": \"$uuid\", \"auto_match\": true}"
done done
``` ```
@@ -289,7 +289,7 @@ curl -X PATCH http://localhost:3002/api/v1/person/person_xxx \
```bash ```bash
curl -X POST http://localhost:3002/api/v1/person/identify \ curl -X POST http://localhost:3002/api/v1/person/identify \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"video_uuid": "xxx", "match_threshold": 0.3}' -d '{"file_uuid": "xxx", "match_threshold": 0.3}'
``` ```
### 问题 2：人物身份重复 ### 问题 2：人物身份重复
@@ -313,7 +313,7 @@ SELECT merge_person_identities(
**解决**： **解决**：
1. 确认索引已创建：`\d person_appearances` 1. 确认索引已创建：`\d person_appearances`
2. 使用 EXPLAIN 分析查询 2. 使用 EXPLAIN 分析查询
3. 考虑分区表（按 video_uuid） 3. 考虑分区表（按 file_uuid）
## 性能优化 ## 性能优化
@@ -343,7 +343,7 @@ pub async fn batch_insert_appearances(
```rust ```rust
// 使用 Redis 缓存时间轴查询 // 使用 Redis 缓存时间轴查询
let cache_key = format!("person_timeline:{}:{}", video_uuid, person_id); let cache_key = format!("person_timeline:{}:{}", file_uuid, person_id);
if let Some(cached) = redis.get(&cache_key).await? { if let Some(cached) = redis.get(&cache_key).await? {
return Ok(serde_json::from_str(&cached)?); return Ok(serde_json::from_str(&cached)?);
@@ -392,4 +392,4 @@ lazy_static! {
- [InsightFace Documentation](https://github.com/deepinsight/insightface) - [InsightFace Documentation](https://github.com/deepinsight/insightface)
- [WhisperX Speaker Diarization](https://github.com/m-bain/whisperX) - [WhisperX Speaker Diarization](https://github.com/m-bain/whisperX)
- [PostgreSQL pgvector](https://github.com/pgvector/pgvector) - [PostgreSQL pgvector](https://github.com/pgvector/pgvector)
- [完整架构设计文档](./PERSON_IDENTITY_INTEGRATION.md) - [完整架构设计文档](./PERSON_IDENTITY_INTEGRATION.md)

18
docs_v1.0/ARCHITECTURE/PIPELINE_AND_RESOURCE_ARCHITECTURE.md
View File

@@ -112,11 +112,11 @@ CREATE TABLE assets (
``` ```
### 2.2 核心流程 ### 2.2 核心流程
1. **上傳/偵測**: SFTPGo 觸發 Webhook 或用戶透過 API 上傳。 1. **上傳/偵測**: SFTPGo 觸發 Webhook 或用戶透過 API 上傳。
2. **探針分析**: `ffprobe` 提取解析度、幀率、音軌、編碼、時長。 2. **探針分析**: `ffprobe` 提取解析度、幀率、音軌、編碼、時長。
3. **智能預處理**: 呼叫 `Smart Thumbnail` 處理器，跳過片頭黑屏，提取正片首幀。 3. **智能預處理**: 呼叫 `Smart Thumbnail` 處理器，跳過片頭黑屏，提取正片首幀。
4. **分類標記**: 根據探針結果自動標記類型（如 `duration > 300s` 標記為 `long_form`）。 4. **分類標記**: 根據探針結果自動標記類型（如 `duration > 300s` 標記為 `long_form`）。
5. **入隊**: 狀態轉為 `PENDING`，寫入 Redis 任務隊列 `queue:processing`。 5. **入隊**: 狀態轉為 `PENDING`，寫入 Redis 任務隊列 `queue:processing`。
--- ---
@@ -173,10 +173,10 @@ LIMIT 1;
| `chunks.json` | Pre-Chunk | `chunks` + `parent_chunks` | 語意搜尋、父子關聯檢索 | | `chunks.json` | Pre-Chunk | `chunks` + `parent_chunks` | 語意搜尋、父子關聯檢索 |
### 4.3 向量索引建立 ### 4.3 向量索引建立
1. 提取文本內容 (ASR + OCR + Chunk Summary)。 1. 提取文本內容 (ASR + OCR + Chunk Summary)。
2. 呼叫 `embedding_engine` 服務 (`nomic-embed-text-v2-moe`) 生成 768-dim 向量。 2. 呼叫 `embedding_engine` 服務 (`nomic-embed-text-v2-moe`) 生成 768-dim 向量。
3. 寫入 Qdrant Collection (`momentry_rule1`, `rule2`, `rule3`)。 3. 寫入 Qdrant Collection (`momentry_rule1`, `rule2`, `rule3`)。
4. 狀態更新至 `READY`，觸發 Webhook 通知使用者。 4. 狀態更新至 `READY`，觸發 Webhook 通知使用者。
--- ---

392
docs_v1.0/ARCHITECTURE/POSE_BASED_MATCHING_OPTIMIZATION_PLAN.md Normal file
View File

@@ -0,0 +1,392 @@
# Pose-based Identity Matching 优化方案
> 规划日期: 2026-04-28
> 规划版本: V1.0
> 基于实验: Pose-filtered Matching Test
---
## 优化目标
### 核心目标
| 目标 | 当前状态 | 目标状态 |
|------|---------|---------|
| **Match Ratio** | 45.16% (阈值 0.85) | **60%+** |
| **Angle Coverage** | {three_quarter, profile_left, profile_right} | **{frontal, three_quarter, profile_left, profile_right}** |
| **Angle-specific Similarity** | profile_right: 0.08 ❌ | **> 0.85** |
| **自动化程度** | 手动选择参考向量 | **自动多角度注册** |
---
## 问题分析
### 当前实验结果
| Angle | Avg Similarity | Frames | Match Ratio | 问题 |
|-------|----------------|--------|-------------|------|
| **three_quarter** | 0.67 | 27 (87%) | 48% | 主要角度，覆盖良好 |
| **profile_left** | 0.97 ✅ | 3 (10%) | 100% | 参考向量匹配度高 |
| **profile_right** | 0.08 ❌ | 1 (3%) | 0% | **缺少参考向量** |
| **frontal** | - | 0 | - | **未检测到** |
### 问题根因
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| **profile_right 相似度低** | 缺少该角度参考向量 | 自动选择 profile_right 帧注册 |
| **frontal 未检测到** | 视频中没有正面人脸 | 需要补充 frontal 参考向量 |
| **角度分类粗糙** | 仅用 ratio threshold | 增加 landmarks geometry 分析 |
| **手动选择参考向量** | 需人工干预 | 实现自动多角度选择 |
---
## 优化方案设计
### Phase 1: 角度分类算法优化
**目标**: 提高角度分类准确性
**改进点**:
- 当前: 仅用 `nose_to_eye / eye_width` ratio
- 改进: 增加 landmarks geometry 特征
**具体改进**:
| 特征 | 当前 | 新增 |
|------|------|------|
| **Ratio** | ✅ | 保持 |
| **Eye Slope** | ❌ | 眼睛连线斜率（判断仰视/俯视） |
| **Nose Position** | ❌ | 鼻子相对眼睛中心的偏移 |
| **Mouth Symmetry** | ❌ | 嘴角对称性（判断侧脸） |
| **3D Landmarks** | ❌ | 使用 3D_68 landmarks（如有） |
**实施任务**:
1. 实现 `calculate_pose_angle_v2()` 函数
2. 添加多特征综合评分
3. 输出更精确的 angle 分类
---
### Phase 2: 自动多角度参考向量选择
**目标**: 自动选择覆盖所有角度的参考向量
**算法设计**:
```
输入: face.json (所有帧人脸)
输出: 4-10 个高质量参考向量（覆盖所有角度）
步骤:
1. 计算每帧人脸的 pose angle
2. 按 angle 分组
3. 每组按 quality_score 排序
4. 每组选择 Top 1-2 个
5. 总数限制 10 个
```
**角度覆盖策略**:
| Angle | 目标数量 | 选择策略 |
|-------|---------|---------|
| **frontal** | 1-2 | ratio < 0.4, quality > 0.85 |
| **three_quarter** | 2-3 | ratio 0.4-0.6, quality > 0.80 |
| **profile_left** | 1-2 | nose left of center, quality > 0.75 |
| **profile_right** | 1-2 | nose right of center, quality > 0.75 |
**实施任务**:
1. 改进 `select_face_reference_vectors.py`
2. 实现自动角度分组
3. 确保最少 4 个角度覆盖
4. 生成 angle_coverage_report
---
### Phase 3: Identity 注册优化
**目标**: 注册时自动存储 pose angle
**当前问题**: reference_data 中 angle 多为 "unknown"
**改进**:
- 计算 pose angle 并存储到 reference_data
- 存储 pose_ratio 供后续过滤使用
**reference_data 结构优化**:
```json
{
"face_embeddings": [
{
"embedding": [512-dim],
"angle": "three_quarter",
"pose_ratio": 0.542,
"eye_slope": 0.12,
"nose_offset": -5.3,
"quality_score": 0.92,
"source": "video_detection",
"frame": "210",
"created_at": "2026-04-28T..."
}
],
"angle_coverage": {
"frontal": 2,
"three_quarter": 3,
"profile_left": 1,
"profile_right": 1
},
"best_angle": "three_quarter",
"total_references": 7
}
```
**实施任务**:
1. 更新 reference_data JSON schema
2. 注册时计算 pose features
3. 生成 angle_coverage 统计
---
### Phase 4: Pose-filtered Matching 优化
**目标**: 改进匹配策略
**当前问题**:
- 找不到同角度向量时，fallback 不够智能
- 阈值固定，未考虑角度差异
**改进策略**:
| 场景 | 当前策略 | 改进策略 |
|------|---------|---------|
| **有同角度向量** | 使用同角度 | 保持 ✅ |
| **无同角度向量** | 使用 three_quarter | **使用 closest angle** |
| **阈值固定** | 0.85 | **角度自适应阈值** |
**角度自适应阈值**:
| Angle | Threshold | 说明 |
|-------|-----------|------|
| **frontal** | 0.90 | 最高质量 |
| **three_quarter** | 0.85 | 标准 |
| **profile_left/right** | 0.80 | 更宽容（角度差异大） |
**Closest Angle Fallback**:
```python
angle_similarity = {
'frontal': {'frontal': 1.0, 'three_quarter': 0.8, 'profile': 0.5},
'three_quarter': {'frontal': 0.8, 'three_quarter': 1.0, 'profile': 0.7},
'profile': {'frontal': 0.5, 'three_quarter': 0.7, 'profile': 1.0},
}
# Fallback order
if detected_angle == 'profile_right':
fallback_order = ['profile_right', 'profile_left', 'three_quarter', 'frontal']
```
**实施任务**:
1. 实现 `strategy_pose_filtered_v2()`
2. 添加角度自适应阈值
3. 实现 closest angle fallback
4. 添加 angle_similarity 矩阵
---
### Phase 5: 生产流程整合
**目标**: 整合到 Momentry Core 生产流程
**整合点**:
| 流程 | 整合内容 |
|------|---------|
| **Face Processor** | 输出 pose angle 到 face.json |
| **Identity Registration API** | 自动多角度参考向量选择 |
| **Identity Matching API** | Pose-filtered matching |
| **Portal UI** | 显示 angle_coverage |
**API 设计**:
```
POST /api/v1/identities/:id/register-reference-vectors
Body: {
"file_uuid": "xxx",
"face_json_path": "output/xxx.face.json",
"auto_select": true,
"min_angles": 4,
"max_vectors": 10
}
Response: {
"uuid": "xxx",
"reference_count": 7,
"angle_coverage": {...},
"quality_avg": 0.89
}
```
---
## 实施计划
### 阶段划分
| Phase | 任务 | 优先级 | 预计时间 |
|-------|------|--------|---------|
| **Phase 1** | 角度分类算法优化 | 高 | 1天 |
| **Phase 2** | 自动多角度参考向量选择 | 高 | 1天 |
| **Phase 3** | Identity 注册优化 | 中 | 0.5天 |
| **Phase 4** | Pose-filtered Matching 优化 | 中 | 1天 |
| **Phase 5** | 生产流程整合 | 低 | 2天 |
**总计**: 5.5天
---
### Phase 1 详细任务
| 任务 | 说明 | 文件 |
|------|------|------|
| Task 1.1 | 实现 `calculate_pose_angle_v2()` | `scripts/utils/pose_analyzer.py` |
| Task 1.2 | 添加多特征计算 | 同上 |
| Task 1.3 | 单元测试 | `tests/test_pose_analyzer.py` |
| Task 1.4 | 验证角度分类准确性 | 测试脚本 |
**验证指标**:
- Angle 分类准确率 > 90%
- 特征计算速度 < 0.01s/face
---
### Phase 2 详细任务
| 任务 | 说明 | 文件 |
|------|------|------|
| Task 2.1 | 实现角度分组算法 | `scripts/select_face_reference_vectors_v2.py` |
| Task 2.2 | 实现每角度 Top-K 选择 | 同上 |
| Task 2.3 | 确保最少角度覆盖 | 同上 |
| Task 2.4 | 生成 angle_coverage_report | 同上 |
| Task 2.5 | 批量测试（多个视频） | 测试脚本 |
**验证指标**:
- Angle 覆盖 ≥ 4
- 参考向量数量 4-10
- 质量 avg > 0.85
---
### Phase 3 详细任务
| 任务 | 说明 | 文件 |
|------|------|------|
| Task 3.1 | 更新 reference_data schema | 设计文档 |
| Task 3.2 | 注册脚本集成 pose features | `scripts/register_identity_with_pose.py` |
| Task 3.3 | 数据库测试 | 测试脚本 |
**验证指标**:
- reference_data 包含 pose features ✅
- angle_coverage 统计准确 ✅
---
### Phase 4 详细任务
| 任务 | 说明 | 文件 |
|------|------|------|
| Task 4.1 | 实现 `strategy_pose_filtered_v2()` | `scripts/match_face_with_pose_v2.py` |
| Task 4.2 | 实现角度自适应阈值 | 同上 |
| Task 4.3 | 实现 closest angle fallback | 同上 |
| Task 4.4 | 批量测试对比 | 测试脚本 |
**验证指标**:
- Match Ratio > 60% (阈值 0.85)
- profile_right 相似度 > 0.85
- Fallback 有效
---
### Phase 5 详细任务
| 任务 | 说明 | 文件 |
|------|------|------|
| Task 5.1 | Face Processor 输出 pose angle | `scripts/face_processor.py` |
| Task 5.2 | Identity Registration API | `src/api/identity.rs` |
| Task 5.3 | Identity Matching API | 同上 |
| Task 5.4 | Portal UI 组件 | Vue components |
| Task 5.5 | 整合测试 | E2E 测试 |
**验证指标**:
- API 响应正常 ✅
- UI 显示 angle_coverage ✅
- E2E 流程成功 ✅
---
## 预期成果
### 定量指标
| 指标 | 当前 | Phase 4后 | Phase 5后 |
|------|------|----------|----------|
| **Match Ratio (阈值 0.85)** | 45.16% | **60%+** | 65%+ |
| **Angle Coverage** | 2-3 | **4+** | 4+ |
| **profile_right Similarity** | 0.08 | **0.85+** | 0.85+ |
| **自动化程度** | 手动 | 半自动 | **全自动** |
### 定性改进
| 改进 | 说明 |
|------|------|
| **鲁棒性** | 多角度覆盖，减少角度差异影响 |
| **准确性** | 角度分类更精确，匹配更可靠 |
| **自动化** | 从手动选择到自动注册 |
| **可追溯** | pose features 存储可追溯 |
---
## 验证方案
### 单元测试
| 测试 | 说明 |
|------|------|
| `test_pose_analyzer` | 角度分类准确性 |
| `test_reference_selector_v2` | 多角度选择逻辑 |
| `test_pose_filtered_matching_v2` | 匹配策略有效性 |
### 集成测试
| 测试 | 说明 |
|------|------|
| `test_identity_registration_with_pose` | 注册流程 |
| `test_batch_matching` | 批量匹配效果 |
| `test_angle_coverage` | 角度覆盖验证 |
### E2E 测试
| 测试 | 说明 |
|------|------|
| `test_full_pipeline` | 从 Face Processor 到 Matching |
| `test_api_integration` | API 端到端 |
---
## 风险与缓解
| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| **缺少 frontal 帧** | frontal 角度无参考向量 | 使用 closest angle fallback |
| **角度分类错误** | 匹配失败 | 多特征综合评分 |
| **计算成本增加** | 性能下降 | 预计算 pose features |
| **阈值设置不当** | 匹配率波动 | 角度自适应阈值 |
---
## 版本信息
- 规划版本: V1.0
- 规划日期: 2026-04-28
- 规划状态: ✅ 完成
- 下一步: **Phase 1 实施**

58
docs_v1.0/ARCHITECTURE/PROCESSING_PIPELINE.md
View File

@@ -2,8 +2,8 @@
document_type: "architecture_design" document_type: "architecture_design"
service: "MOMENTRY_CORE" service: "MOMENTRY_CORE"
title: "Video Processing Pipeline - 處理流程" title: "Video Processing Pipeline - 處理流程"
date: "2026-03-22" date: "2026-04-27"
version: "V1.0" version: "V1.2"
status: "active" status: "active"
owner: "Warren" owner: "Warren"
created_by: "OpenCode" created_by: "OpenCode"
@@ -12,10 +12,12 @@ tags:
- "video" - "video"
- "pipeline" - "pipeline"
- "處理流程" - "處理流程"
- "processing_status"
ai_query_hints: ai_query_hints:
- "查詢 Video Processing Pipeline - 處理流程 的內容" - "查詢 Video Processing Pipeline - 處理流程 的內容"
- "Video Processing Pipeline - 處理流程 的主要目的是什麼？" - "Video Processing Pipeline - 處理流程 的主要目的是什麼？"
- "如何操作或實施 Video Processing Pipeline - 處理流程？" - "如何操作或實施 Video Processing Pipeline - 處理流程？"
- "processing_status 字段與 status 的關係"
--- ---
# Video Processing Pipeline - 處理流程 # Video Processing Pipeline - 處理流程
@@ -24,7 +26,7 @@ ai_query_hints:
|------|------| |------|------|
| 建立者 | Warren | | 建立者 | Warren |
| 建立時間 | 2026-03-22 | | 建立時間 | 2026-03-22 |
| 文件版本 | V1.1 | | 文件版本 | V1.2 |
--- ---
@@ -34,6 +36,7 @@ ai_query_hints:
|------|------|------|--------|-----------| |------|------|------|--------|-----------|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode | | V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode |
| V1.1 | 2026-03-26 | 更新流程圖文字 (media_url→file_path) | OpenCode | deepseek-reasoner | | V1.1 | 2026-03-26 | 更新流程圖文字 (media_url→file_path) | OpenCode | deepseek-reasoner |
| V1.2 | 2026-04-27 | 添加 processing_status 字段說明 | OpenCode | GLM-5 |
--- ---
@@ -265,9 +268,16 @@ let query_vector = embedder.embed_query("搜索查詢").await?;
### PostgreSQL 狀態欄位 ### PostgreSQL 狀態欄位
```sql ```sql
-- 影片處理狀態 -- 影片處理狀態（基本狀態）
videos.status: 'pending' | 'processing' | 'completed' | 'failed' videos.status: 'pending' | 'processing' | 'completed' | 'failed'
-- 影片處理狀態（詳細狀態）
videos.processing_status: 'REGISTERED' | 'PENDING' | 'PROBING' | 'ASR' | 'OCR' | 'YOLO' | 'FACE' | 'POSE' | 'CUT' | 'ASRX' | 'COMPLETED' | 'FAILED' | 'PAUSED' | 'RESUMING'
-- 說明：
-- status：基本狀態，用於 API 查詢過濾（is_processed=true → status='completed'）
-- processing_status：詳細狀態，用於 Portal 顯示和作業追蹤
-- 檔案處理狀態 -- 檔案處理狀態
videos.fs_json: true/false videos.fs_json: true/false
videos.fs_chunks: true/false videos.fs_chunks: true/false
@@ -307,6 +317,46 @@ curl http://localhost:3002/api/v1/progress/{uuid}
} }
``` ```
### Agent 進度追蹤（V1.2 起）
從 V1.2 起，Agent 任務透過 `processing_status` JSONB 的 `agents` 字段追蹤。
#### Agent 進度字段
| Agent | JSONB 路徑 | 說明 |
|-------|-----------|------|
| 5W1H | `processing_status->agents->5w1h` | 場景摘要 Agent |
| Translation | `processing_status->agents->translation` | 翻譯 Agent |
#### Agent 狀態結構
```json
{
"agents": {
"5w1h": {
"status": "running",
"scenes_processed": 5,
"scenes_total": 1332,
"progress_pct": 0.4,
"started_at": "2026-04-27T05:45:00Z"
}
}
}
```
#### SQL 查詢 Agent 進度
```sql
SELECT
uuid,
processing_status->'agents'->'5w1h'->>'status' as status,
processing_status->'agents'->'5w1h'->>'scenes_processed' as processed
FROM videos
WHERE processing_status->'agents'->'5w1h'->>'status' = 'running';
```
詳細規範請參考: `REFERENCE/PROCESSING_STATUS_JSONB_SPEC.md`
--- ---
## 下一步 ## 下一步

2
docs_v1.0/ARCHITECTURE/QUICK_START_GUIDE.md
View File

@@ -162,4 +162,4 @@ A: 調整 Qdrant 向量索引參數，優化嵌入模型，添加緩存層。
**更新時間**: 2026-04-22 **更新時間**: 2026-04-22
**適用對象**: 新團隊成員、開發者、架構師 **適用對象**: 新團隊成員、開發者、架構師
**建議閱讀時間**: 5 分鐘 **建議閱讀時間**: 5 分鐘

34
docs_v1.0/ARCHITECTURE/RESOURCE_MANAGEMENT/PROCESSOR_LIFECYCLE.md
View File

@@ -64,7 +64,7 @@ ai_query_hints:
### 2.2 開發標準 ### 2.2 開發標準
#### Python 處理器標準： #### Python 處理器標準
```python ```python
# 1. 必要的導入 # 1. 必要的導入
import json import json
@@ -79,7 +79,7 @@ parser.add_argument("--output", required=True, help="Output path")
args = parser.parse_args() args = parser.parse_args()
# 3. 主處理邏輯 # 3. 主處理邏輯
def process_video(video_uuid, output_path): def process_video(file_uuid, output_path):
# 處理邏輯 # 處理邏輯
result = { result = {
"status": "success", "status": "success",
@@ -107,31 +107,31 @@ if __name__ == "__main__":
### 3.1 測試類型 ### 3.1 測試類型
#### 單元測試： #### 單元測試
- 測試處理器核心邏輯 - 測試處理器核心邏輯
- 驗證輸入輸出格式 - 驗證輸入輸出格式
- 測試錯誤處理 - 測試錯誤處理
#### 集成測試： #### 集成測試
- 測試與其他組件的集成 - 測試與其他組件的集成
- 驗證數據流完整 - 驗證數據流完整
- 測試性能表現 - 測試性能表現
#### 回歸測試： #### 回歸測試
- 確保新版本不破壞現有功能 - 確保新版本不破壞現有功能
- 測試兼容性 - 測試兼容性
- 驗證性能改進 - 驗證性能改進
### 3.2 測試數據 ### 3.2 測試數據
#### 測試視頻： #### 測試視頻
| 類型 | 用途 | 示例 | | 類型 | 用途 | 示例 |
|------|------|------| |------|------|------|
| 短視頻（<1分鐘） | 快速測試 | test_video.mp4 | | 短視頻（<1分鐘） | 快速測試 | test_video.mp4 |
| 中等視頻（1-5分鐘） | 功能測試 | demo_video.mp4 | | 中等視頻（1-5分鐘） | 功能測試 | demo_video.mp4 |
| 長視頻（>10分鐘） | 性能測試 | long_video.mp4 | | 長視頻（>10分鐘） | 性能測試 | long_video.mp4 |
#### 測試環境： #### 測試環境
1. **本地開發環境**：快速迭代 1. **本地開發環境**：快速迭代
2. **測試服務器**：集成測試 2. **測試服務器**：集成測試
3. **生產模擬環境**：性能測試 3. **生產模擬環境**：性能測試
@@ -187,25 +187,25 @@ INSERT INTO processors (
### 5.1 調度與執行 ### 5.1 調度與執行
#### 任務調度流程： #### 任務調度流程
``` ```
1. 任務創建 → 2. 處理器選擇 → 3. 資源分配 1. 任務創建 → 2. 處理器選擇 → 3. 資源分配
→ 4. 執行監控 → 5. 結果收集 → 6. 狀態更新 → 4. 執行監控 → 5. 結果收集 → 6. 狀態更新
``` ```
#### 執行監控： #### 執行監控
1. **進程監控**：監控處理器進程狀態 1. **進程監控**：監控處理器進程狀態
2. **資源監控**：監控 CPU、內存、GPU 使用 2. **資源監控**：監控 CPU、內存、GPU 使用
3. **性能監控**：監控處理速度和進度 3. **性能監控**：監控處理速度和進度
### 5.2 錯誤處理與恢復 ### 5.2 錯誤處理與恢復
#### 錯誤類型： #### 錯誤類型
1. **可恢復錯誤**：臨時性問題，可重試 1. **可恢復錯誤**：臨時性問題，可重試
2. **配置錯誤**：配置問題，需要修復 2. **配置錯誤**：配置問題，需要修復
3. **系統錯誤**：系統級問題，需要干預 3. **系統錯誤**：系統級問題，需要干預
#### 重試策略： #### 重試策略
```rust ```rust
// Rust 中的重試機制示例 // Rust 中的重試機制示例
let result = run_with_retry( let result = run_with_retry(
@@ -221,7 +221,7 @@ let result = run_with_retry(
### 5.3 性能優化 ### 5.3 性能優化
#### 優化策略： #### 優化策略
1. **並行處理**：同時處理多個視頻 1. **並行處理**：同時處理多個視頻
2. **批處理**：批量處理相關任務 2. **批處理**：批量處理相關任務
3. **緩存優化**：重用計算結果 3. **緩存優化**：重用計算結果
@@ -233,13 +233,13 @@ let result = run_with_retry(
### 6.1 日常維護 ### 6.1 日常維護
#### 監控項目： #### 監控項目
1. **處理器狀態**：運行狀態、健康狀態 1. **處理器狀態**：運行狀態、健康狀態
2. **性能指標**：處理速度、成功率 2. **性能指標**：處理速度、成功率
3. **資源使用**：CPU、內存、存儲 3. **資源使用**：CPU、內存、存儲
4. **錯誤率**：各種錯誤的發生頻率 4. **錯誤率**：各種錯誤的發生頻率
#### 維護任務： #### 維護任務
1. **日誌分析**：定期分析處理器日誌 1. **日誌分析**：定期分析處理器日誌
2. **性能調優**：根據監控數據進行調優 2. **性能調優**：根據監控數據進行調優
3. **安全更新**：更新依賴庫修復安全漏洞 3. **安全更新**：更新依賴庫修復安全漏洞
@@ -247,13 +247,13 @@ let result = run_with_retry(
### 6.2 版本升級 ### 6.2 版本升級
#### 升級流程： #### 升級流程
1. **兼容性檢查**：檢查新版本與現有系統的兼容性 1. **兼容性檢查**：檢查新版本與現有系統的兼容性
2. **回滾計劃**：制定升級失敗時的回滾計劃 2. **回滾計劃**：制定升級失敗時的回滾計劃
3. **分階段部署**：分階段逐步升級 3. **分階段部署**：分階段逐步升級
4. **驗證測試**：升級後進行全面測試 4. **驗證測試**：升級後進行全面測試
#### 版本兼容性矩陣： #### 版本兼容性矩陣
| 處理器版本 | 系統版本 | 模型版本 | 狀態 | | 處理器版本 | 系統版本 | 模型版本 | 狀態 |
|------------|----------|----------|------| |------------|----------|----------|------|
| v1.0.x | v0.1.0 | insightface==0.7.3 | ✅ 兼容 | | v1.0.x | v0.1.0 | insightface==0.7.3 | ✅ 兼容 |
@@ -361,4 +361,4 @@ let result = run_with_retry(
|------|------|----------|--------| |------|------|----------|--------|
| V1.0 | 2026-04-22 | 創建處理器生命週期管理文檔 | OpenCode | | V1.0 | 2026-04-22 | 創建處理器生命週期管理文檔 | OpenCode |
**最後更新日期**: 2026-04-22 **最後更新日期**: 2026-04-22

8
docs_v1.0/ARCHITECTURE/RESOURCE_MANAGEMENT/PROCESSOR_REGISTRY_ARCHITECTURE.md
View File

@@ -305,10 +305,10 @@ match processor.execution_type.as_str() {
處理器在執行時，需要查詢「服務註冊中心」來獲取依賴資源的配置。 處理器在執行時，需要查詢「服務註冊中心」來獲取依賴資源的配置。
**流程範例**: **流程範例**:
1. 排程器啟動 `asr_processor.py`。 1. 排程器啟動 `asr_processor.py`。
2. Python 腳本查詢本地配置檔 (由排程器生成，內容來自 `services` 表)。 2. Python 腳本查詢本地配置檔 (由排程器生成，內容來自 `services` 表)。
3. 腳本獲取 Ollama 的 `endpoint` 與 `model_name`。 3. 腳本獲取 Ollama 的 `endpoint` 與 `model_name`。
4. 腳本執行 Embedding 任務。 4. 腳本執行 Embedding 任務。
這樣實現了**處理器與基礎設施配置的解耦**。 這樣實現了**處理器與基礎設施配置的解耦**。

22
docs_v1.0/ARCHITECTURE/RESOURCE_MANAGEMENT/RESOURCE_MONITORING_SPEC.md
View File

@@ -22,8 +22,8 @@
所有 Processor (YOLO, ASR...) 和 Agent (Translation, Summary...) 啟動時應主動註冊。 所有 Processor (YOLO, ASR...) 和 Agent (Translation, Summary...) 啟動時應主動註冊。
### 1.1 註冊時機 ### 1.1 註冊時機
* **Processor**: 在 Python 腳本啟動時，呼叫 HTTP Endpoint 註冊。 * **Processor**: 在 Python 腳本啟動時，呼叫 HTTP Endpoint 註冊。
* **Agent**: 在服務啟動時呼叫 HTTP Endpoint 註冊。 * **Agent**: 在服務啟動時呼叫 HTTP Endpoint 註冊。
--- ---
@@ -48,7 +48,7 @@
} }
``` ```
* **resource_id**: 建議格式 `{type}_{name}_{uuid}`，例如 `processor_yolo_a1b2c3`。 * **resource_id**: 建議格式 `{type}_{name}_{uuid}`，例如 `processor_yolo_a1b2c3`。
### 2.3 Response ### 2.3 Response
@@ -74,23 +74,23 @@
```json ```json
{ {
"status": "idle | busy | error", "status": "idle | busy | error",
"job_uuid": "current_video_uuid", "job_uuid": "current_file_uuid",
"progress": 0.45, "progress": 0.45,
"last_frame_index": 12500 "last_frame_index": 12500
} }
``` ```
* **progress**: 0.0 到 1.0 之間的浮點數。 * **progress**: 0.0 到 1.0 之間的浮點數。
* **job_uuid**: 當前正在處理的任務 ID。 * **job_uuid**: 當前正在處理的任務 ID。
--- ---
## 4. 監控用途 ## 4. 監控用途
系統後台 (Portal Dashboard) 可透過查詢 Registry 實現： 系統後台 (Portal Dashboard) 可透過查詢 Registry 實現：
1. **即時儀表板**: 顯示目前有幾個 Processor 在運行 (`busy` 數量)。 1. **即時儀表板**: 顯示目前有幾個 Processor 在運行 (`busy` 數量)。
2. **進度條**: 透過 `last_frame_index` 與影片總幀數計算百分比。 2. **進度條**: 透過 `last_frame_index` 與影片總幀數計算百分比。
3. **健康檢查**: 若資源超過 60 秒未發送心跳，標記為 `offline`。 3. **健康檢查**: 若資源超過 60 秒未發送心跳，標記為 `offline`。
--- ---
@@ -116,5 +116,5 @@ deregister_resource(&resource_id).await;
## 版本資訊 ## 版本資訊
- 版本: V1.0 * 版本: V1.0
- 建立日期: 2026-04-25 * 建立日期: 2026-04-25

54
docs_v1.0/ARCHITECTURE/RESOURCE_MANAGEMENT/UNIFIED_RESOURCE_REGISTRY.md
View File

@@ -67,18 +67,18 @@
## 3. 資源生命週期 (Resource Lifecycle) ## 3. 資源生命週期 (Resource Lifecycle)
1. **註冊 (Registration)**: 1. **註冊 (Registration)**:
* 組件啟動時向 **Resource Registry** 報到，聲明其 ID、類型和能力。 * 組件啟動時向 **Resource Registry** 報到，聲明其 ID、類型和能力。
* *範例*: Agent 啟動，註冊 `resource_type: "agent"`, `capabilities: ["summarize_text"]`。 * *範例*: Agent 啟動，註冊 `resource_type: "agent"`, `capabilities: ["summarize_text"]`。
2. **發現 (Discovery)**: 2. **發現 (Discovery)**:
* 調度器 (Scheduler) 根據任務需求查詢 Registry 尋找合適的資源。 * 調度器 (Scheduler) 根據任務需求查詢 Registry 尋找合適的資源。
* *範例*: 任務需要「語音轉文字」，查詢 `capabilities: ["audio_to_text"]`。 * *範例*: 任務需要「語音轉文字」，查詢 `capabilities: ["audio_to_text"]`。
3. **分配與執行 (Allocation & Execution)**: 3. **分配與執行 (Allocation & Execution)**:
* 狀態變為 `busy`，接收任務並執行。 * 狀態變為 `busy`，接收任務並執行。
4. **健康檢查 (Health Monitoring)**: 4. **健康檢查 (Health Monitoring)**:
* Registry 定期 Ping 資源。若無回應，標記為 `offline`。 * Registry 定期 Ping 資源。若無回應，標記為 `offline`。
5. **登出 (Deregistration)**: 5. **登出 (Deregistration)**:
* 組件關閉或崩潰時從 Registry 移除。 * 組件關閉或崩潰時從 Registry 移除。
--- ---
@@ -127,36 +127,36 @@ CREATE INDEX idx_res_caps ON resources USING GIN(capabilities);
## 5. 實作建議 ## 5. 實作建議
### 5.1 Processor 實作 (確定性) ### 5.1 Processor 實作 (確定性)
* 通常由 Python 腳本或 Rust 二進制執行。 * 通常由 Python 腳本或 Rust 二進制執行。
* 啟動時呼叫 `POST /resources/register`，宣告如 `["video_to_frames", "detect_objects"]`。 * 啟動時呼叫 `POST /resources/register`，宣告如 `["video_to_frames", "detect_objects"]`。
### 5.2 Agent 實作 (機率性) ### 5.2 Agent 實作 (機率性)
* 通常封裝為具備 LLM Context 的服務。 * 通常封裝為具備 LLM Context 的服務。
* 啟動時呼叫 `POST /resources/register`，宣告如 `["summarize_text", "extract_5w1h"]`。 * 啟動時呼叫 `POST /resources/register`，宣告如 `["summarize_text", "extract_5w1h"]`。
* **重點**: 在 `metadata` 中記錄使用的 LLM 模型名稱 (e.g., `gpt-4o`, `llama3`)。 * **重點**: 在 `metadata` 中記錄使用的 LLM 模型名稱 (e.g., `gpt-4o`, `llama3`)。
### 5.3 Service 實作 (基礎設施) ### 5.3 Service 實作 (基礎設施)
* 通常由 Docker Compose 或 Systemd 管理。 * 通常由 Docker Compose 或 Systemd 管理。
* 可透過 Sidecar 或定期腳本進行註冊與心跳更新。 * 可透過 Sidecar 或定期腳本進行註冊與心跳更新。
--- ---
## 6. 與其他架構的關係 ## 6. 與其他架構的關係
* **Job/Task Scheduler**: 任務調度器依賴 Resource Registry 來尋找誰能執行任務。 * **Job/Task Scheduler**: 任務調度器依賴 Resource Registry 來尋找誰能執行任務。
* **Configuration Management**: 資源的詳細參數 (如 API Key, Threshold) 應存在 Config 中心，Registry 僅儲存引用或摘要。 * **Configuration Management**: 資源的詳細參數 (如 API Key, Threshold) 應存在 Config 中心，Registry 僅儲存引用或摘要。
* **Monitoring**: Prometheus/Grafana 應抓取 Registry 狀態來展示系統資源健康度儀表板。 * **Monitoring**: Prometheus/Grafana 應抓取 Registry 狀態來展示系統資源健康度儀表板。
## 7. 關聯文檔 ## 7. 關聯文檔
本目錄整合了原有的 Processor 與 Service 架構，並納入新的 Agent 架構： 本目錄整合了原有的 Processor 與 Service 架構，並納入新的 Agent 架構：
- `PROCESSOR_REGISTRY_ARCHITECTURE.md` - 舊版處理器註冊設計 (已整合)。 * `PROCESSOR_REGISTRY_ARCHITECTURE.md` - 舊版處理器註冊設計 (已整合)。
- `SERVICE_REGISTRY_ARCHITECTURE.md` - 舊版服務註冊設計 (已整合)。 * `SERVICE_REGISTRY_ARCHITECTURE.md` - 舊版服務註冊設計 (已整合)。
- `PROCESSOR_LIFECYCLE.md` - 處理器生命週期 (資源生命週期的子集)。 * `PROCESSOR_LIFECYCLE.md` - 處理器生命週期 (資源生命週期的子集)。
--- ---
## 版本資訊 ## 版本資訊
- 版本: V1.0 * 版本: V1.0
- 建立日期: 2026-04-25 * 建立日期: 2026-04-25

6
docs_v1.0/ARCHITECTURE/ROOT_API_WORKFLOW_WORDPRESS_N8N.md
View File

@@ -134,7 +134,7 @@ const job = await response.json();
// 狀態檢查 // 狀態檢查
if (job.status === 'completed') { if (job.status === 'completed') {
return [{ json: { done: true, video_uuid: job.video_uuid } }]; return [{ json: { done: true, file_uuid: job.file_uuid } }];
} else { } else {
return [{ json: { done: false, status: job.status } }]; return [{ json: { done: false, status: job.status } }];
} }
@@ -385,13 +385,13 @@ add_shortcode('momentry_search', function($atts) {
$html .= '<ul>'; $html .= '<ul>';
foreach ($results['results'] as $result) { foreach ($results['results'] as $result) {
$video_uuid = $result['uuid']; $file_uuid = $result['uuid'];
$start = $result['start_time'] ?? 0; $start = $result['start_time'] ?? 0;
$end = $result['end_time'] ?? 0; $end = $result['end_time'] ?? 0;
$text = $result['text'] ?? '無文字描述'; $text = $result['text'] ?? '無文字描述';
$html .= '<li>'; $html .= '<li>';
$html .= '<a href="/player?uuid=' . esc_attr($video_uuid) . $html .= '<a href="/player?uuid=' . esc_attr($file_uuid) .
'&start=' . esc_attr($start) . '&start=' . esc_attr($start) .
'&end=' . esc_attr($end) . '">'; '&end=' . esc_attr($end) . '">';
$html .= '播放 ' . $start . 's - ' . $end . 's'; $html .= '播放 ' . $start . 's - ' . $end . 's';

2
docs_v1.0/ARCHITECTURE/SECURITY_ARCHITECTURE.md
View File

@@ -162,4 +162,4 @@ Momentry Core 的安全架構設計遵循業界最佳實踐，包括：
3. **持續監控**：實時監控安全事件，快速響應 3. **持續監控**：實時監控安全事件，快速響應
4. **合規要求**：符合 GDPR、CCPA 等隱私法規 4. **合規要求**：符合 GDPR、CCPA 等隱私法規
通過上述安全措施，確保系統在提供強大功能的同時，保持高度的安全性與合規性。 通過上述安全措施，確保系統在提供強大功能的同時，保持高度的安全性與合規性。

76
docs_v1.0/ARCHITECTURE/SEMANTIC_SEARCH_DESIGN.md
View File

@@ -11,9 +11,9 @@
本設計文檔旨在定義 Momentry Core 的**多維度自然語言搜尋 (Multi-Dimensional Semantic Search)** 系統架構與實施規範。該系統旨在突破傳統關鍵詞匹配的限制，通過解析用戶的「人事時地物」(5W1H) 意圖，結合多模態數據 (ASR, YOLO, Pose, Scene, Face)，實現高精度的語義檢索。 本設計文檔旨在定義 Momentry Core 的**多維度自然語言搜尋 (Multi-Dimensional Semantic Search)** 系統架構與實施規範。該系統旨在突破傳統關鍵詞匹配的限制，通過解析用戶的「人事時地物」(5W1H) 意圖，結合多模態數據 (ASR, YOLO, Pose, Scene, Face)，實現高精度的語義檢索。
### 1.1 設計原則 ### 1.1 設計原則
1. **模組化 (Modularity)**: 搜尋功能作為獨立的 `Search Processor` 模塊，依賴但不侵入其他數據生產模塊 (如 Pose, ASR)。 1. **模組化 (Modularity)**: 搜尋功能作為獨立的 `Search Processor` 模塊，依賴但不侵入其他數據生產模塊 (如 Pose, ASR)。
2. **多模態融合 (Multi-Modal Fusion)**: 結合結構化數據 (SQL 過濾) 與非結構化向量數據 (Vector 檢索)。 2. **多模態融合 (Multi-Modal Fusion)**: 結合結構化數據 (SQL 過濾) 與非結構化向量數據 (Vector 檢索)。
3. **本地優先 (Local First)**: 核心解析與檢索邏輯盡可能在本地完成，僅 LLM 意圖解析可調用雲端或本地 LLM。 3. **本地優先 (Local First)**: 核心解析與檢索邏輯盡可能在本地完成，僅 LLM 意圖解析可調用雲端或本地 LLM。
--- ---
@@ -40,26 +40,26 @@
### 2.2 事 (Event / Action / What) ### 2.2 事 (Event / Action / What)
基於 `ASR` (語音語義) 和 `Pose Analyzer` (行為語義)。 基於 `ASR` (語音語義) 和 `Pose Analyzer` (行為語義)。
* **語音內容**: "他在解釋量子力學" -> 向量檢索 ASR 文本。 * **語音內容**: "他在解釋量子力學" -> 向量檢索 ASR 文本。
* **視覺行為**: "他在跑步", "兩人在擁抱" -> 檢索 `pose_analysis` 標籤或向量。 * **視覺行為**: "他在跑步", "兩人在擁抱" -> 檢索 `pose_analysis` 標籤或向量。
### 2.3 時 (Time / When) ### 2.3 時 (Time / When)
基於 `chunks` 的時間戳。 基於 `chunks` 的時間戳。
* **絕對時間**: `10:05 - 10:15`。 * **絕對時間**: `10:05 - 10:15`。
* **相對時間**: "最後 5 分鐘", "剛開始"。 * **相對時間**: "最後 5 分鐘", "剛開始"。
### 2.4 地 (Location / Where) ### 2.4 地 (Location / Where)
基於 `Scene` (Places365) 分類結果。 基於 `Scene` (Places365) 分類結果。
* **標籤**: "beach", "office", "living_room"。 * **標籤**: "beach", "office", "living_room"。
* **映射**: 用戶說 "戶外" -> 映射為 `["beach", "forest", "street", ...]`。 * **映射**: 用戶說 "戶外" -> 映射為 `["beach", "forest", "street", ...]`。
### 2.5 物 (Object / Which) ### 2.5 物 (Object / Which)
基於 `YOLO` (物件檢測) 和 `OCR` (文字識別)。 基於 `YOLO` (物件檢測) 和 `OCR` (文字識別)。
* **物件**: `car`, `dog`, `knife`。 * **物件**: `car`, `dog`, `knife`。
* **文字**: 路牌、標題中的關鍵詞。 * **文字**: 路牌、標題中的關鍵詞。
--- ---
@@ -96,8 +96,8 @@ graph TD
``` ```
### 3.2 模組職責 ### 3.2 模組職責
1. **Pose Analyzer Processor**: 負責讀取 Pose 座標與 YOLO 數據，生成行為標籤 (Tags)，寫入數據庫。 1. **Pose Analyzer Processor**: 負責讀取 Pose 座標與 YOLO 數據，生成行為標籤 (Tags)，寫入數據庫。
2. **Search Processor**: 負責將自然語言轉為查詢語句並執行檢索。 2. **Search Processor**: 負責將自然語言轉為查詢語句並執行檢索。
--- ---
@@ -188,12 +188,12 @@ WHERE
### 6.2 語義檢索 (Vector) ### 6.2 語義檢索 (Vector)
針對模糊描述 (What) 使用向量相似度。 針對模糊描述 (What) 使用向量相似度。
* 將 "shouting at someone" 編碼為向量。 * 將 "shouting at someone" 編碼為向量。
* 在 Qdrant 中檢索與此向量相似的 `chunks` (基於 ASR 語義) 或 `pose_events` (基於動作語義)。 * 在 Qdrant 中檢索與此向量相似的 `chunks` (基於 ASR 語義) 或 `pose_events` (基於動作語義)。
### 6.3 結果融合 (Re-ranking) ### 6.3 結果融合 (Re-ranking)
* 取 SQL 過濾結果與 Vector 檢索結果的交集。 * 取 SQL 過濾結果與 Vector 檢索結果的交集。
* 若無交集，優先展示滿足 Filter (Who/Where) 的結果，按 Vector 分數排序。 * 若無交集，優先展示滿足 Filter (Who/Where) 的結果，按 Vector 分數排序。
--- ---
@@ -202,39 +202,39 @@ WHERE
這是支持「事 (Event)」和「人 (Person Action)」維度的核心前置模塊。 這是支持「事 (Event)」和「人 (Person Action)」維度的核心前置模塊。
### 7.1 處理流程 ### 7.1 處理流程
1. **輸入**: 原始 `pose.json` (座標) + `yolo.json` (物體框)。 1. **輸入**: 原始 `pose.json` (座標) + `yolo.json` (物體框)。
2. **特徵工程**: 2. **特徵工程**:
* 計算關節角度 (Angle): 手肘、膝蓋。 * 計算關節角度 (Angle): 手肘、膝蓋。
* 計算速度 (Velocity): 手腕、身體中心點位移。 * 計算速度 (Velocity): 手腕、身體中心點位移。
* 計算交互 (Interaction): 人手框與 YOLO 物體框 IoU。 * 計算交互 (Interaction): 人手框與 YOLO 物體框 IoU。
3. **規則分類 (Rule-based)**: 3. **規則分類 (Rule-based)**:
* 手部高於頭頂 -> `hands_up`。 * 手部高於頭頂 -> `hands_up`。
* 雙手交叉於胸前 -> `arms_crossed`。 * 雙手交叉於胸前 -> `arms_crossed`。
* 快速靠近另一人 -> `approaching`。 * 快速靠近另一人 -> `approaching`。
4. **輸出**: 更新 `chunks` 表的 `action_tags` 和 `person_identities` 表的 `attributes`。 4. **輸出**: 更新 `chunks` 表的 `action_tags` 和 `person_identities` 表的 `attributes`。
--- ---
## 8. 實施路線圖 ## 8. 實施路線圖
### Phase 1: 基礎設施 (Day 1-2) ### Phase 1: 基礎設施 (Day 1-2)
* [ ] 更新數據庫 Schema (增加 `attributes`, `action_tags` 等字段與索引)。 * [ ] 更新數據庫 Schema (增加 `attributes`, `action_tags` 等字段與索引)。
* [ ] 創建 `scripts/pose_analyzer_processor.py` (基礎規則版：站/坐/臥/手勢)。 * [ ] 創建 `scripts/pose_analyzer_processor.py` (基礎規則版：站/坐/臥/手勢)。
* [ ] 運行 Pose Analyzer 對現有數據進行標記。 * [ ] 運行 Pose Analyzer 對現有數據進行標記。
### Phase 2: 搜尋解析器 (Day 3-4) ### Phase 2: 搜尋解析器 (Day 3-4)
* [ ] 創建 `scripts/search_processor.py`。 * [ ] 創建 `scripts/search_processor.py`。
* [ ] 實現 LLM Intent Parser (Qwen3.6-plus)。 * [ ] 實現 LLM Intent Parser (Qwen3.6-plus)。
* [ ] 實現 Query Translator (生成動態 SQL)。 * [ ] 實現 Query Translator (生成動態 SQL)。
### Phase 3: 執行與整合 (Day 5-6) ### Phase 3: 執行與整合 (Day 5-6)
* [ ] 實現 Search Executor (PostgreSQL 查詢邏輯)。 * [ ] 實現 Search Executor (PostgreSQL 查詢邏輯)。
* [ ] 開發 `POST /api/v1/search/smart` API。 * [ ] 開發 `POST /api/v1/search/smart` API。
* [ ] 前端對接與測試。 * [ ] 前端對接與測試。
### Phase 4: 優化 (Day 7+) ### Phase 4: 優化 (Day 7+)
* [ ] 引入向量檢索 (Vector Search) 支持模糊語義。 * [ ] 引入向量檢索 (Vector Search) 支持模糊語義。
* [ ] 優化 Pose 分析算法 (引入 ST-GCN 等輕量模型)。 * [ ] 優化 Pose 分析算法 (引入 ST-GCN 等輕量模型)。
--- ---

408
docs_v1.0/ARCHITECTURE/SOUND_RECOGNITION_EXTENSION.md Normal file
View File

@@ -0,0 +1,408 @@
---
document_type: "extension_design"
title: "声音识别扩展设计 (Phase 5+)"
service: "MOMENTRY_CORE"
date: "2026-04-28"
status: "planning"
current_state: "draft"
owner: "Warren"
created_by: "OpenCode"
created_at: "2026-04-28"
version: "V1.0"
tags:
- "sound_recognition"
- "audio_embedding"
- "animal_sound"
- "environmental_sound"
- "weapon_sound"
- "musical_instrument"
- "phase_5"
related_documents:
- "IDENTITY_REFERENCE_VECTOR_DESIGN.md"
- "MOMENTRY_CORE_ARCHITECTURE_V2.md"
ai_query_hints:
- "查詢声音识别扩展设计"
- "查詢動物叫聲 embedding"
- "查詢雷雨聲 embedding"
- "查詢槍炮聲 embedding"
- "查詢樂器聲 embedding"
---
# 声音识别扩展设计 (Phase 5+)
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-28 |
| 文件版本 | V1.0 |
| 状态 | Phase 5+ 待辦事項 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-28 | 創建声音识别扩展设计（Phase 5+） | OpenCode | OpenCode |
---
## 概述
本文檔定義 Momentry Core Identity 系統的 **声音识别扩展设计**，屬於 **Phase 5+ 待辦事項**。
核心理念：**将声音作为 Identity 进行识别和注册，支持动物叫聲、雷雨聲、槍炮聲、樂器聲等。**
---
## 设计目标
### 核心目标
| 目標 | 說明 |
|------|------|
| **声音 Identity** | 将声音作为 Identity 进行注册和管理 |
| **声音 Embedding** | 提取声音的 embedding vector |
| **声音匹配** | 在音频中识别特定声音的出现 |
| **1对多参考向量** | 同一声音可存储多个 embedding（不同样本、不同质量） |
| **声音分类** | 支持多種声音类型（动物、环境、武器、樂器） |
### 适用场景
| 场景 | 说明 |
|------|------|
| **电影/视频分析** | 识别电影中的枪声、雷声、狗叫声等 |
| **环境监控** | 监控特定环境声音（雷雨、警报等） |
| **音频搜索** | 搜索包含特定声音的音频片段 |
| **声音数据库** | 建立声音 Identity 数据库（动物叫声库、乐器声音库） |
---
## 声音类型分类
### identity_type 扩展
```sql
-- identities 表 identity_type 字段扩展
identity_type VARCHAR(30) -- 新增类型: sound, animal, environmental
```
### 声音类型定义
| identity_type | 说明 | 子类型 | 示例 |
|---------------|------|--------|------|
| **sound** | 通用声音 | TBD | 各种声音 |
| **animal** | 动物叫声 | animal_dog_bark, animal_cat_meow, animal_bird_chirp | 狗叫声、猫叫声、鸟叫声 |
| **environmental** | 环境音 | environmental_thunder, environmental_rain, environmental_wind | 雷声、雨声、风声 |
| **weapon** | 武器声 | weapon_gunshot, weapon_explosion, weapon_siren | 枪声、爆炸声、警报声 |
| **musical** | 乐器声 | musical_guitar, musical_piano, musical_drums | 吉他声、钢琴声、鼓声 |
---
## reference_data JSONB 结构
### sound_embeddings 结构
```json
{
"sound_embeddings": [
{
"embedding": [0.1, 0.2, ...], // TBD (声音 embedding 维度)
"source": "audio_segment",
"file_uuid": "vid_001",
"timestamp_start": 10.0,
"timestamp_end": 15.0,
"sound_type": "animal_dog_bark",
"quality_score": 0.95,
"sample_rate": 44100,
"duration": 5.0,
"created_at": "2026-04-28T13:00:00Z"
},
{
"embedding": [0.3, 0.4, ...],
"source": "audio_segment",
"file_uuid": "vid_002",
"timestamp_start": 20.0,
"timestamp_end": 25.0,
"sound_type": "animal_dog_bark",
"quality_score": 0.88,
"sample_rate": 44100,
"duration": 5.0,
"created_at": "2026-04-28T14:00:00Z"
}
],
"audio_urls": [
"https://cdn.xxx.com/sounds/dog_bark_001.wav",
"https://cdn.xxx.com/sounds/dog_bark_002.wav"
]
}
```
### 字段说明
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| embedding | Array[TBD] | Yes | 声音 embedding vector（维度 TBD） |
| source | String | Yes | 来源: audio_segment, audio_file, manual_upload |
| file_uuid | String | Yes | 档案 UUID |
| timestamp_start | Float | Yes | 开始时间（秒） |
| timestamp_end | Float | Yes | 结束时间（秒） |
| sound_type | String | Yes | 声音类型（见上表） |
| quality_score | Float | No | 质量评分（0.0-1.0） |
| sample_rate | Integer | No | 音频采样率 |
| duration | Float | No | 音频时长（秒） |
| created_at | String | Yes | 建立时间（ISO 8601） |
---
## 声音 Embedding 模型选择
### 待评估模型
| 模型 | 维度 | 说明 | 适用场景 |
|------|------|------|----------|
| **PANNs** | TBD | AudioSet 预训练模型 | 通用声音识别 |
| **YAMNet** | 1024-dim | TensorFlow 音频分类模型 | 通用声音分类 |
| **VGGish** | 128-dim | YouTube-8M 音频模型 | 音频特征提取 |
| **Audio Spectrogram Transformer** | TBD | 基于 Transformer 的音频模型 | 音频理解 |
| **CLAP** | 512-dim | Contrastive Language-Audio Pretraining | 文本-音频匹配 |
### 模型评估指标
| 指标 | 说明 |
|------|------|
| **Embedding 维度** | 维度大小影响存储和计算效率 |
| **识别准确率** | 声音识别准确率 |
| **提取速度** | Embedding 提取速度 |
| **模型大小** | 模型文件大小 |
| **GPU 支持** | 是否支持 MPS/CUDA |
---
## 声音 Identity 注册流程
### 示例: 注册狗叫声 Identity
```python
def register_animal_sound_identity(sound_name, sound_type, audio_files):
"""
声音 Identity 注册流程:
1. 提取多个音频样本的 embedding
2. 存储到 reference_data JSONB
3. 注册到 identities 表
"""
# Step 1: 提取 embedding
sound_embeddings = []
for audio_file in audio_files:
# 加载音频
audio_data = load_audio(audio_file)
# 提取 embedding
embedding = audio_model.extract_embedding(audio_data)
# 评估质量
quality_score = evaluate_audio_quality(audio_data)
# 存储到 reference_data
sound_embeddings.append({
"embedding": embedding.tolist(),
"source": "audio_file",
"sound_type": sound_type,
"quality_score": quality_score,
"sample_rate": audio_data["sample_rate"],
"duration": audio_data["duration"],
"created_at": datetime.now().isoformat()
})
# Step 2: 注册 Identity
identity = {
"identity_id": generate_uuid(),
"name": sound_name,
"identity_type": "animal",
"source": "manual",
"reference_data": {
"sound_embeddings": sound_embeddings,
"audio_urls": [audio_file.url for audio_file in audio_files]
}
}
# Step 3: 计算 centroid
centroid = calculate_centroid([e["embedding"] for e in sound_embeddings])
identity["sound_embedding"] = centroid
# 存储到資料庫
db.insert_identity(identity)
return identity
```
---
## 声音匹配流程
### 示例: 在视频中识别狗叫声
```python
def detect_animal_sound(file_uuid, sound_identity, threshold=0.85):
"""
声音匹配流程:
1. 提取视频音频段落的 embedding
2. 与 Identity 的 sound_embeddings 进行匹配
3. 返回匹配结果
"""
# Step 1: 提取视频音频段落
audio_segments = extract_audio_segments(file_uuid, segment_duration=5.0)
# Step 2: 匹配
results = []
for segment in audio_segments:
# 提取段落 embedding
segment_embedding = audio_model.extract_embedding(segment)
# 1对多匹配
match_result = combined_match(
detected_embedding=segment_embedding,
reference_embeddings=sound_identity["reference_data"]["sound_embeddings"],
threshold=threshold
)
if match_result["is_match"]:
results.append({
"timestamp_start": segment["timestamp_start"],
"timestamp_end": segment["timestamp_end"],
"match_score": match_result["final_score"],
"sound_type": sound_identity["name"]
})
return results
```
---
## 数据库设计
### identities 表扩展
```sql
-- Migration TBD: identities 表添加 sound_embedding
ALTER TABLE identities ADD COLUMN sound_embedding VECTOR(TBD);
-- 索引配置
CREATE INDEX idx_identities_sound_embedding ON identities
USING ivfflat (sound_embedding vector_cosine_ops)
WITH (lists = 100);
```
### sound_type 分类表（可选）
```sql
CREATE TABLE sound_types (
sound_type_code VARCHAR(50) PRIMARY KEY, -- animal_dog_bark
sound_type_name TEXT NOT NULL, -- 狗叫声
category VARCHAR(20), -- animal, environmental, weapon, musical
description TEXT,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## 实作计划
### Phase 5.1: 模型评估和选择
- [ ] 评估 PANNs、YAMNet、VGGish、CLAP 等模型
- [ ] 确定 embedding 维度
- [ ] 确定 GPU 支持（MPS/CUDA）
- [ ] 性能基准测试
### Phase 5.2: 数据库扩展
- [ ] Migration TBD: identities 表添加 sound_embedding VECTOR(TBD)
- [ ] sound_types 分类表建立
- [ ] 测试数据建立
### Phase 5.3: 声音 Identity 注册
- [ ] 声音 embedding 提取脚本
- [ ] reference_data JSONB 存储
- [ ] Identity 注册 API
### Phase 5.4: 声音匹配
- [ ] 音频段落提取脚本
- [ ] 1对多匹配算法实现
- [ ] 匹配结果存储到 pre_chunks
### Phase 5.5: 前端集成
- [ ] 声音 Identity 管理界面
- [ ] 声音匹配结果展示
- [ ] 声音搜索功能
---
## 待辦事項
| 項目 | 優先級 | 說明 |
|------|--------|------|
| 模型评估和选择 | 高 | Phase 5.1 |
| 数据库扩展 | 高 | Phase 5.2 |
| 声音 Identity 注册 | 中 | Phase 5.3 |
| 声音匹配 | 中 | Phase 5.4 |
| 前端集成 | 低 | Phase 5.5 |
---
## 技术挑战
### 挑战 1: Embedding 维度选择
| 问题 | 说明 |
|------|------|
| **维度过高** | 存储成本高，计算效率低 |
| **维度过低** | 信息损失，识别准确率下降 |
| **解决方案** | 评估不同模型，选择平衡维度（推荐 128-512 dim） |
### 挑战 2: 声音样本质量
| 问题 | 说明 |
|------|------|
| **噪音干扰** | 背景噪音影响 embedding 质量 |
| **采样率不统一** | 不同音频采样率差异 |
| **解决方案** | 1对多参考向量 + 质量评分机制 |
### 挑战 3: 声音重叠识别
| 问题 | 说明 |
|------|------|
| **多声音重叠** | 同时出现多种声音 |
| **解决方案** | 音频分离技术 + 多 Identity 匹配 |
---
## 限制條件
- 本设计为 Phase 5+ 待辦事項，不在当前实作范围
- 声音 embedding 维度 TBD，需模型评估
- 声音识别准确率依赖模型性能
- 需要 GPU 支持（MPS/CUDA）
---
## 相关文件
- `docs_v1.0/ARCHITECTURE/IDENTITY_REFERENCE_VECTOR_DESIGN.md` - 1对多参考向量设计
- `docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md` - 核心架构设计
- `docs_v1.0/IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md` - API 设计
---
## 版本信息
- 版本: V1.0
- 建立日期: 2026-04-28
- 文件更新: 2026-04-28
- 状态: Phase 5+ 待辦事項

179
docs_v1.0/ARCHITECTURE/TECHNICAL_DECISION_RECORDS.md
View File

@@ -174,8 +174,6 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
### TDR-003: 編程語言選擇 ### TDR-003: 編程語言選擇
| 項目 | 內容 | | 項目 | 內容 |
|------|------| |------|------|
| **決策標題** | 使用 Rust 作為核心開發語言 | | **決策標題** | 使用 Rust 作為核心開發語言 |
@@ -188,29 +186,21 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
#### 3.2 評估選項 #### 3.2 評估選項
**選項 A: Python** **選項 A: Python**
- 生態豐富，AI 庫完善 - 生態豐富，AI 庫完善
- 開發速度快 - 開發速度快
- 但性能較低，不適合高並發 - 但性能較低，不適合高並發
**選項 B: Go** **選項 B: Go**
- 性能好，並發支持好 - 性能好，並發支持好
- 簡單易學 - 簡單易學
- 但生態不如 Rust 豐富 - 但生態不如 Rust 豐富
**選項 C: Rust（選擇方案）** **選項 C: Rust（選擇方案）**
- 高性能，接近 C++ 的性能 - 高性能，接近 C++ 的性能
- 內存安全，無 GC - 內存安全，無 GC
- 強大的類型系統和錯誤處理 - 強大的類型系統和錯誤處理
**選項 D: Java/Kotlin** **選項 D: Java/Kotlin**
- 企業級生態 - 企業級生態
- 性能良好 - 性能良好
@@ -241,20 +231,14 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
- ✅ Python 用於 AI 模型處理 - ✅ Python 用於 AI 模型處理
- ✅ 通過子進程調用橋接 Rust 和 Python - ✅ 通過子進程調用橋接 Rust 和 Python
#### 3.6 相關鏈接 #### 3.6 相關鏈接
- 代碼庫：`src/` 目錄 - 代碼庫：`src/` 目錄
- [RUST_DEVELOPMENT.md](../REFERENCE/RUST_DEVELOPMENT.md) - [RUST_DEVELOPMENT.md](../REFERENCE/RUST_DEVELOPMENT.md)
--- ---
### TDR-004: 分片規則分析與未來規劃 ### TDR-004: 分片規則分析與未來規劃
| 項目 | 內容 | | 項目 | 內容 |
|------|------| |------|------|
| **決策標題** | 視覺/場景/摘要分片的設計意義與實現規劃 | | **決策標題** | 視覺/場景/摘要分片的設計意義與實現規劃 |
@@ -264,111 +248,73 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
#### 4.1 視覺分片 (Visual Chunk) 的意義 #### 4.1 視覺分片 (Visual Chunk) 的意義
**核心價值**： **核心價值**：
1. **物件級搜索**：支持「看到了什麼」的搜索 1. **物件級搜索**：支持「看到了什麼」的搜索
2. **跨模態橋接**：連接視覺與語音/文本內容 2. **跨模態橋接**：連接視覺與語音/文本內容
3. **場景理解基礎**：通過物件組合理解場景 3. **場景理解基礎**：通過物件組合理解場景
**好處**： **好處**：
- 實現「視覺第一」的搜索體驗 - 實現「視覺第一」的搜索體驗
- 支持基於物件出現的視頻分析 - 支持基於物件出現的視頻分析
- 為場景分析提供基礎數據 - 為場景分析提供基礎數據
#### 4.2 場景分片 (Scene Chunk) 的意義 #### 4.2 場景分片 (Scene Chunk) 的意義
**核心價值**： **核心價值**：
1. **語義聚合**：將相關句子/物件組成有意義場景 1. **語義聚合**：將相關句子/物件組成有意義場景
2. **上下文保留**：保持對話和行為的連貫性 2. **上下文保留**：保持對話和行為的連貫性
3. **高效檢索**：直接定位到場景而非單句 3. **高效檢索**：直接定位到場景而非單句
**好處**： **好處**：
- 支持語義級搜索（如「會議對話」、「爭吵場景」） - 支持語義級搜索（如「會議對話」、「爭吵場景」）
- 保留完整上下文 - 保留完整上下文
- 為故事摘要提供基礎 - 為故事摘要提供基礎
#### 4.3 摘要分片 (Summary Chunk) 的意義 #### 4.3 摘要分片 (Summary Chunk) 的意義
**核心價值**： **核心價值**：
1. **高層級理解**：提供視頻整體概括 1. **高層級理解**：提供視頻整體概括
2. **5W1H 結構化**：提取關鍵信息 2. **5W1H 結構化**：提取關鍵信息
3. **敘事壓縮**：將長視頻精簡為可快速理解的摘要 3. **敘事壓縮**：將長視頻精簡為可快速理解的摘要
**好處**： **好處**：
- 用戶無需觀看整個視頻即可了解內容 - 用戶無需觀看整個視頻即可了解內容
- 提供清晰的結構化信息 - 提供清晰的結構化信息
- 支持視頻內容快速評估和比較 - 支持視頻內容快速評估和比較
#### 4.4 實現優先級與挑戰 #### 4.4 實現優先級與挑戰
**實現優先級**： **實現優先級**：
1. ✅ **Rule 1 (句子級)** - 已實現 1. ✅ **Rule 1 (句子級)** - 已實現
2. ⚠️ **Rule 3 (場景級)** - 部分實現（基於 CUT 數據） 2. ⚠️ **Rule 3 (場景級)** - 部分實現（基於 CUT 數據）
3. ❌ **Rule 2 (視覺級)** - 待實現 3. ❌ **Rule 2 (視覺級)** - 待實現
4. ❌ **Rule 4 (摘要級)** - 待實現 4. ❌ **Rule 4 (摘要級)** - 待實現
**技術挑戰**： **技術挑戰**：
1. **視覺分片**：物件檢測準確性與性能平衡 1. **視覺分片**：物件檢測準確性與性能平衡
2. **場景分片**：場景邊界智能識別 2. **場景分片**：場景邊界智能識別
3. **摘要分片**：LLM 摘要質量與一致性 3. **摘要分片**：LLM 摘要質量與一致性
4. **數據融合**：多模態信息有效整合 4. **數據融合**：多模態信息有效整合
#### 4.5 遷移計劃 #### 4.5 遷移計劃
**短期 (1-2個月)**： **短期 (1-2個月)**：
- 完善 Rule 3 (場景級分片) - 完善 Rule 3 (場景級分片)
- 集成 Places365 場景分類 - 集成 Places365 場景分類
- 完善基於視覺和語音的場景識別 - 完善基於視覺和語音的場景識別
**中期 (3-6個月)**： **中期 (3-6個月)**：
- 實現 Rule 2 (視覺分片) - 實現 Rule 2 (視覺分片)
- 集成 YOLO 物件檢測 - 集成 YOLO 物件檢測
- 創建物件標籤索引 - 創建物件標籤索引
**長期 (6-12個月)**： **長期 (6-12個月)**：
- 實現 Rule 4 (摘要分片) - 實現 Rule 4 (摘要分片)
- 集成 LLM 摘要生成 - 集成 LLM 摘要生成
- 實現5W1H結構化提取 - 實現5W1H結構化提取
#### 4.6 相關鏈接 #### 4.6 相關鏈接
- [CHUNKING_ARCHITECTURE.md](./chunking/CHUNKING_ARCHITECTURE.md)) - [CHUNKING_ARCHITECTURE.md](./chunking/CHUNKING_ARCHITECTURE.md))
- Rule 1 實現：`src/core/chunk/rule1_ingest.rs` - Rule 1 實現：`src/core/chunk/rule1_ingest.rs`
- Rule 3 實現：`src/core/chunk/rule3_ingest.rs` - Rule 3 實現：`src/core/chunk/rule3_ingest.rs`
@@ -377,12 +323,8 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
## 3. 設計與實現差異分析 ## 3. 設計與實現差異分析
### 設計目標 vs 實際實現 ### 設計目標 vs 實際實現
#### 差異點1: chunk_type 定義 #### 差異點1: chunk_type 定義
| 設計文件 | 實際代碼 | 狀態分析 | | 設計文件 | 實際代碼 | 狀態分析 |
@@ -393,13 +335,8 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
| `summary` | 未實現 | ❌ 缺失設計功能 | | `summary` | 未實現 | ❌ 缺失設計功能 |
| - | `"time"`, `"trace"`, `"story"` | 🔄 代碼中的額外類型 | | - | `"time"`, `"trace"`, `"story"` | 🔄 代碼中的額外類型 |
#### 差異點2: 分片規則實現 #### 差異點2: 分片規則實現
| 規則 | 設計描述 | 實現狀態 | 問題分析 | | 規則 | 設計描述 | 實現狀態 | 問題分析 |
|------|----------|----------|----------| |------|----------|----------|----------|
| Rule 1 | 句子級檢索 | ✅ 已實現 | 完整功能 | | Rule 1 | 句子級檢索 | ✅ 已實現 | 完整功能 |
@@ -407,13 +344,8 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
| Rule 3 | 場景級檢索 | ⚠️ 部分實現 | 僅基於CUT數據，缺少場景分類 | | Rule 3 | 場景級檢索 | ⚠️ 部分實現 | 僅基於CUT數據，缺少場景分類 |
| Rule 4 | 摘要級檢索 | ❌ 未實現 | 缺少LLM集成和結構化摘要 | | Rule 4 | 摘要級檢索 | ❌ 未實現 | 缺少LLM集成和結構化摘要 |
#### 差異點3: 數據庫結構 #### 差異點3: 數據庫結構
| 設計目標 | 實現現狀 | 分析 | | 設計目標 | 實現現狀 | 分析 |
|----------|----------|------| |----------|----------|------|
| 通用分片結構 | 已實現基本結構 | ✅ | | 通用分片結構 | 已實現基本結構 | ✅ |
@@ -421,248 +353,141 @@ Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一
| 場景聚合表 | 部分實現 | ⚠️ | | 場景聚合表 | 部分實現 | ⚠️ |
| 摘要生成表 | 未實現 | ❌ | | 摘要生成表 | 未實現 | ❌ |
--- ---
## 4. 建議實現路徑與計劃 ## 4. 建議實現路徑與計劃
### 優先級1: 完善現有實現 ### 優先級1: 完善現有實現
**短期目標 (1-2週)**： **短期目標 (1-2週)**：
1. **統一 `chunk_type` 枚舉**： 1. **統一 `chunk_type` 枚舉**：
- 更新 `src/core/chunk/types.rs` 中的 `ChunkType` 枚舉 - 更新 `src/core/chunk/types.rs` 中的 `ChunkType` 枚舉
- 確保與數據庫中存儲的字符串值一致 - 確保與數據庫中存儲的字符串值一致
2. **擴展Rule 3實現**： 2. **擴展Rule 3實現**：
- 集成Places365模型進行場景分類 - 集成Places365模型進行場景分類
- 結合視覺和語音數據的場景邊界識別 - 結合視覺和語音數據的場景邊界識別
- 創建 `chunks_rule3` 表的完整結構 - 創建 `chunks_rule3` 表的完整結構
### 優先級2: 實現視覺分片 ### 優先級2: 實現視覺分片
**中期目標 (1-2個月)**： **中期目標 (1-2個月)**：
1. **YOLO集成**： 1. **YOLO集成**：
- 創建 `yolo_processor.py` 腳本 - 創建 `yolo_processor.py` 腳本
- 實現基於關鍵幀的物件檢測 - 實現基於關鍵幀的物件檢測
- 物件標籤標準化和索引建立 - 物件標籤標準化和索引建立
2. **視覺分片生成**： 2. **視覺分片生成**：
- 創建 `visual_ingest.rs` 處理器 - 創建 `visual_ingest.rs` 處理器
- 實現物件聚合和標籤生成 - 實現物件聚合和標籤生成
- 創建 `chunks_rule2` 表結構 - 創建 `chunks_rule2` 表結構
### 優先級3: 實現摘要分片 ### 優先級3: 實現摘要分片
**長期目標 (3-6個月)**： **長期目標 (3-6個月)**：
1. **LLM集成**： 1. **LLM集成**：
- 集成Gemma4或類似LLM - 集成Gemma4或類似LLM
- 實現視頻內容摘要生成 - 實現視頻內容摘要生成
- 5W1H結構化信息提取 - 5W1H結構化信息提取
2. **摘要分片生成**： 2. **摘要分片生成**：
- 創建 `summary_ingest.rs` 處理器 - 創建 `summary_ingest.rs` 處理器
- 實現跨場景的敘事壓縮 - 實現跨場景的敘事壓縮
- 創建 `chunks_rule4` 表結構 - 創建 `chunks_rule4` 表結構
--- ---
## 5. 關鍵決策點總結 ## 5. 關鍵決策點總結
### 決策1: 分層架構設計 ### 決策1: 分層架構設計
**設計目標**： **設計目標**：
- 四層分片架構：句子 → 視覺 → 場景 → 摘要 - 四層分片架構：句子 → 視覺 → 場景 → 摘要
- 多粒度檢索：從細節到整體的不同層次理解 - 多粒度檢索：從細節到整體的不同層次理解
**實現現狀**： **實現現狀**：
- 句子級分片（Rule 1）完整實現 - 句子級分片（Rule 1）完整實現
- 場景級分片（Rule 3）部分實現 - 場景級分片（Rule 3）部分實現
- 視覺和摘要分片未實現 - 視覺和摘要分片未實現
### 決策2: 數據庫混合架構 ### 決策2: 數據庫混合架構
**設計目標**： **設計目標**：
- PostgreSQL: 主數據存儲 - PostgreSQL: 主數據存儲
- Redis: 緩存和隊列 - Redis: 緩存和隊列
- MongoDB: 文檔緩存 - MongoDB: 文檔緩存
- Qdrant: 向量搜索 - Qdrant: 向量搜索
**實現現狀**： **實現現狀**：
- ✅ 所有數據庫均已集成 - ✅ 所有數據庫均已集成
- ✅ 多數據庫協同工作 - ✅ 多數據庫協同工作
- ⚠️ 數據一致性管理需要完善 - ⚠️ 數據一致性管理需要完善
### 決策3: 技術棧選擇 ### 決策3: 技術棧選擇
**設計目標**： **設計目標**：
- Rust: 核心系統語言 - Rust: 核心系統語言
- Python: AI模型處理 - Python: AI模型處理
- Axum: Web框架 - Axum: Web框架
- Tokio: 異步運行時 - Tokio: 異步運行時
**實現現狀**： **實現現狀**：
- ✅ Rust核心系統完整實現 - ✅ Rust核心系統完整實現
- ✅ Python AI模型集成 - ✅ Python AI模型集成
- ✅ Axum + Tokio 穩定運行 - ✅ Axum + Tokio 穩定運行
- ⚠️ Python-Rust 橋接效率需優化 - ⚠️ Python-Rust 橋接效率需優化
--- ---
## 6. 未來改進方向 ## 6. 未來改進方向
### 短期改進 (1-2個月) ### 短期改進 (1-2個月)
1. **統一API設計**： 1. **統一API設計**：
- 標準化所有列表API的分頁參數 - 標準化所有列表API的分頁參數
- 統一回應結構格式 - 統一回應結構格式
- 完善錯誤處理和文檔 - 完善錯誤處理和文檔
2. **優化性能**： 2. **優化性能**：
- 改進數據庫查詢效率 - 改進數據庫查詢效率
- 優化Python子進程調用 - 優化Python子進程調用
- 改善並發處理能力 - 改善並發處理能力
### 中期改進 (3-6個月) ### 中期改進 (3-6個月)
1. **完善分片規則**： 1. **完善分片規則**：
- 實現視覺分片（Rule 2） - 實現視覺分片（Rule 2）
- 實現摘要分片（Rule 4） - 實現摘要分片（Rule 4）
- 完善場景分片（Rule 3） - 完善場景分片（Rule 3）
2. **擴展功能**： 2. **擴展功能**：
- 支持更多視頻格式 - 支持更多視頻格式
- 集成更多AI模型 - 集成更多AI模型
- 提供更多分析維度 - 提供更多分析維度
### 長期改進 (6-12個月) ### 長期改進 (6-12個月)
1. **系統架構升級**： 1. **系統架構升級**：
- 微服務化架構 - 微服務化架構
- 雲原生部署支持 - 雲原生部署支持
- 大規模視頻處理能力 - 大規模視頻處理能力
2. **平台化發展**： 2. **平台化發展**：
- 多租戶支持 - 多租戶支持
- 可擴展插件架構 - 可擴展插件架構
- 雲端協同工作流 - 雲端協同工作流
--- ---
## 7. 最後更新記錄 ## 7. 最後更新記錄
| 版本 | 日期 | 主要變更 | 操作人 | | 版本 | 日期 | 主要變更 | 操作人 |
|------|------|----------|--------| |------|------|----------|--------|
| V1.0 | 2026-04-22 | 創建技術決策記錄文件 | OpenCode | | V1.0 | 2026-04-22 | 創建技術決策記錄文件 | OpenCode |
| V1.1 | 2026-04-22 | 添加設計與實現差異分析 | OpenCode | | V1.1 | 2026-04-22 | 添加設計與實現差異分析 | OpenCode |
| V1.2 | 2026-04-22 | 完善實現計劃和改進方向 | OpenCode | | V1.2 | 2026-04-22 | 完善實現計劃和改進方向 | OpenCode |
**最後更新日期**: 2026-04-22
**最後更新日期**: 2026-04-22

2
docs_v1.0/ARCHITECTURE/TERMINOLOGY_MAPPING.md
View File

@@ -306,4 +306,4 @@ python3 scripts/check_architecture_docs.py --check-terminology
**文件版本**: V1.0 **文件版本**: V1.0
**最後更新**: 2026-04-22 **最後更新**: 2026-04-22
**維護者**: OpenCode **維護者**: OpenCode

6
docs_v1.0/ARCHITECTURE/USER_MANAGEMENT_PLAN.md
View File

@@ -278,17 +278,17 @@ pub async fn register(
} }
// 關聯 user_id 到影片 // 關聯 user_id 到影片
let video_uuid = state.db.create_video(req, Some(ctx.user_id)).await?; let file_uuid = state.db.create_video(req, Some(ctx.user_id)).await?;
// 建立 processing job（帶 user_id） // 建立 processing job（帶 user_id）
state.db.create_monitor_job( state.db.create_monitor_job(
job_type: "auto_ingestion", job_type: "auto_ingestion",
video_uuid, file_uuid,
user_id: Some(ctx.user_id), user_id: Some(ctx.user_id),
processors: vec!["asr", "cut", "yolo", "ocr", "face", "pose"], processors: vec!["asr", "cut", "yolo", "ocr", "face", "pose"],
).await?; ).await?;
Ok(Json(RegisterResponse { uuid: video_uuid })) Ok(Json(RegisterResponse { uuid: file_uuid }))
} }
``` ```

24
docs_v1.0/ARCHITECTURE/_deprecated/SPEAKER_INTEGRATION.md
View File

@@ -96,19 +96,19 @@ ADD COLUMN audio_visual_confidence FLOAT; -- 融合置信度
系統如何精確計算「說話者」與「臉部」的關聯？ 系統如何精確計算「說話者」與「臉部」的關聯？
### 3.1 演算法步驟 ### 3.1 演算法步驟
1. **時間切片**: 將影片以 `1秒` 為單位劃分時間窗。 1. **時間切片**: 將影片以 `1秒` 為單位劃分時間窗。
2. **標籤映射**: 2. **標籤映射**:
- 若該秒有 ASRX 輸出，標記為 `ActiveSpeaker = SPEAKER_XX`。 - 若該秒有 ASRX 輸出，標記為 `ActiveSpeaker = SPEAKER_XX`。
- 若該秒 Face Processor 偵測到臉部，標記為 `ActiveFace = FACE_YY` (取信心值最高且面積最大者)。 - 若該秒 Face Processor 偵測到臉部，標記為 `ActiveFace = FACE_YY` (取信心值最高且面積最大者)。
3. **共現矩陣 (Co-occurrence Matrix)**: 統計每對 `(SPEAKER_XX, FACE_YY)` 同時出現的秒數。 3. **共現矩陣 (Co-occurrence Matrix)**: 統計每對 `(SPEAKER_XX, FACE_YY)` 同時出現的秒數。
4. **計算重疊率**: 4. **計算重疊率**:
```math ```math
Overlap(S_x, F_y) = \frac{\text{Count}(S_x \cap F_y)}{\text{Count}(S_x)} Overlap(S_x, F_y) = \frac{\text{Count}(S_x \cap F_y)}{\text{Count}(S_x)}
``` ```
5. **決策**: 5. **決策**:
- 若 `Overlap > 0.60` → 建立強關聯 (High Confidence)。 - 若 `Overlap > 0.60` → 建立強關聯 (High Confidence)。
- 若 `0.30 <= Overlap <= 0.60` → 建立建議關聯 (Medium Confidence)。 - 若 `0.30 <= Overlap <= 0.60` → 建立建議關聯 (Medium Confidence)。
- 若 `Overlap < 0.30` → 忽略 (可能是畫外音或群體場景)。 - 若 `Overlap < 0.30` → 忽略 (可能是畫外音或群體場景)。
### 3.2 偽代碼範例 ### 3.2 偽代碼範例
```python ```python
@@ -149,10 +149,10 @@ graph TD
``` ```
### 4.1 執行時機 ### 4.1 執行時機
1. `ASRX` 與 `Face` 處理器均完成。 1. `ASRX` 與 `Face` 處理器均完成。
2. 觸發 `audio_visual_binding_worker`。 2. 觸發 `audio_visual_binding_worker`。
3. 產出 `speaker_face_mapping.json`。 3. 產出 `speaker_face_mapping.json`。
4. 寫入資料庫，並更新 `person_identities` 表。 4. 寫入資料庫，並更新 `person_identities` 表。
--- ---

52
docs_v1.0/ARCHITECTURE/_deprecated/TMDB_CHARACTER_INTEGRATION.md
View File

@@ -71,11 +71,11 @@ graph LR
``` ```
### 1.1 關鍵步驟 ### 1.1 關鍵步驟
1. **Metadata 解析**: 從檔名或 `ffprobe` 資訊中提取電影名稱與年份。 1. **Metadata 解析**: 從檔名或 `ffprobe` 資訊中提取電影名稱與年份。
2. **TMDB 查詢**: 呼叫 API 獲取 Top Cast (通常前 10-15 名) 及其照片 URL。 2. **TMDB 查詢**: 呼叫 API 獲取 Top Cast (通常前 10-15 名) 及其照片 URL。
3. **照片下載與特徵提取**: 下載演員照片並生成 Face Embedding (512-dim)。 3. **照片下載與特徵提取**: 下載演員照片並生成 Face Embedding (512-dim)。
4. **向量比對**: 將演員照片向量與影片內偵測到的 **Face Cluster Centroids** 進行相似度比對 (Cosine Similarity)。 4. **向量比對**: 將演員照片向量與影片內偵測到的 **Face Cluster Centroids** 進行相似度比對 (Cosine Similarity)。
5. **身分決議**: 若相似度超過閾值 (如 0.6)，則自動建立全域身分並標記。 5. **身分決議**: 若相似度超過閾值 (如 0.6)，則自動建立全域身分並標記。
--- ---
@@ -148,17 +148,17 @@ CREATE INDEX idx_person_global ON person_identities(global_person_id);
系統如何決定「畫面中的臉」就是「Cary Grant」？ 系統如何決定「畫面中的臉」就是「Cary Grant」？
1. **參考集準備 (Reference Set)**: 1. **參考集準備 (Reference Set)**:
* 從 TMDB 獲取演員照片 URL。 - 從 TMDB 獲取演員照片 URL。
* 下載並使用 InsightFace 提取向量 $V_{actor}$。 - 下載並使用 InsightFace 提取向量 $V_{actor}$。
2. **目標集 (Target Set)**: 2. **目標集 (Target Set)**:
* 從影片 Face Processor 獲取每個 Cluster 的中心向量 $V_{cluster}$。 - 從影片 Face Processor 獲取每個 Cluster 的中心向量 $V_{cluster}$。
3. **計算相似度**: 3. **計算相似度**:
* $Score = 1 - \text{CosineDistance}(V_{actor}, V_{cluster})$ - $Score = 1 - \text{CosineDistance}(V_{actor}, V_{cluster})$
4. **決策閾值**: 4. **決策閾值**:
* **High Confidence (> 0.70)**: 自動確認身分 (Auto-Confirm)。 - **High Confidence (> 0.70)**: 自動確認身分 (Auto-Confirm)。
* **Medium Confidence (0.55 - 0.70)**: 標記為 "Suggestion" (建議)，需人工確認。 - **Medium Confidence (0.55 - 0.70)**: 標記為 "Suggestion" (建議)，需人工確認。
* **Low Confidence (< 0.55)**: 忽略，保持為 "Unknown Cluster"。 - **Low Confidence (< 0.55)**: 忽略，保持為 "Unknown Cluster"。
### 3.3 角色名關聯 (Role Mapping) ### 3.3 角色名關聯 (Role Mapping)
@@ -179,21 +179,21 @@ TMDB 返回的結構包含 `character` 字段：
此流程被打包為一個獨立的 **Post-Face-Processing Job**。 此流程被打包為一個獨立的 **Post-Face-Processing Job**。
1. **Trigger**: `face_processor` 完成，產生 `face_clusters`。 1. **Trigger**: `face_processor` 完成，產生 `face_clusters`。
2. **Action**: 系統檢查 `asset_type == 'movie'` 且 `title` 存在。 2. **Action**: 系統檢查 `asset_type == 'movie'` 且 `title` 存在。
3. **Execution**: 執行 `tmdb_cast_ingestion.py`。 3. **Execution**: 執行 `tmdb_cast_ingestion.py`。
* 查詢 TMDB。 - 查詢 TMDB。
* 下載圖片 -> 計算向量 -> 存入 `global_person_identities` (若不存在)。 - 下載圖片 -> 計算向量 -> 存入 `global_person_identities` (若不存在)。
* 執行比對 -> 更新 `person_identities`。 - 執行比對 -> 更新 `person_identities`。
4. **Output**: 資料庫中充滿了真實姓名與角色名的紀錄，供 Rule 3/4 Chunking 使用。 4. **Output**: 資料庫中充滿了真實姓名與角色名的紀錄，供 Rule 3/4 Chunking 使用。
--- ---
## 5. 容錯與異常處理 (Error Handling) ## 5. 容錯與異常處理 (Error Handling)
- **找不到電影**: 若檔名模糊導致 TMDB 無結果，則跳過此步驟，保留原始 Face Cluster ID。 - **找不到電影**: 若檔名模糊導致 TMDB 無結果，則跳過此步驟，保留原始 Face Cluster ID。
- **無演員照片**: 若某演員在 TMDB 無照片，無法進行向量比對，僅記錄名字 (若 ASR 有提及)。 - **無演員照片**: 若某演員在 TMDB 無照片，無法進行向量比對，僅記錄名字 (若 ASR 有提及)。
- **多人飾演一角**: 若臉部特徵同時匹配多個演員 (極罕見)，取 Confidence 最高者，其餘列入候補。 - **多人飾演一角**: 若臉部特徵同時匹配多個演員 (極罕見)，取 Confidence 最高者，其餘列入候補。
--- ---

362
docs_v1.0/BODY_ACTION_DECODER_CLASSIFICATION.md Normal file
View File

@@ -0,0 +1,362 @@
# Body Action Decoder 完整动作分类文档
> 创建日期: 2026-04-28
> 脚本路径: `scripts/utils/body_action_decoder.py`
---
## 概述
**Body Action Decoder** 支持以下肢体动作检测：
| 类别 | 动作数量 | 数据源 |
|------|----------|--------|
| **Face** | 12 | InsightFace (已有) |
| **Eyes** | 6 | MediaPipe Face Mesh (待安装) |
| **Mouth** | 6 | MediaPipe Face Mesh (待安装) |
| **Arms** | 9 | MediaPipe Pose (待安装) |
| **Hands** | 11 | MediaPipe Hand (待安装) |
| **Legs** | 9 | MediaPipe Pose (待安装) |
| **Feet** | 5 | MediaPipe Pose (待安装) |
| **Combined** | 9 | Multi-source 组合 |
---
## 一、Face Actions (已有 ✅)
### 1.1 Turn Actions (转身)
| Action | Description | Pattern |
|--------|-------------|---------|
| **turn_left** | 向左转 | frontal/three_quarter → profile_left |
| **turn_right** | 向右转 | frontal/three_quarter → profile_right |
| **turn_partial** | 部分转身 | frontal → three_quarter |
| **turn_full** | 完全转身 | profile_left → profile_right (or reverse) |
| **return_frontal** | 回正 | three_quarter/profile → frontal |
| **turn_to_three_quarter** | 转到侧面 | profile → three_quarter |
### 1.2 Pitch Actions (仰俯)
| Action | Description | Pattern |
|--------|-------------|---------|
| **look_up** | 向上看 | neutral → tilted_up |
| **look_down** | 向下看 | neutral → tilted_down |
| **return_neutral** | 回正 | tilted → neutral |
### 1.3 Complex Face Actions (复杂动作)
| Action | Description | Pattern |
|--------|-------------|---------|
| **shake_head** ⭐ | 摇头 | profile_left → profile_right → profile_left (5-30 frames) |
| **nod_head** ⭐ | 点头 | tilted_up → tilted_down → tilted_up (3-20 frames) |
---
## 二、Eye Actions (待安装 MediaPipe)
### 2.1 Basic Eye Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **blink** | 眨眼 | EAR < 0.2 for 1-3 frames |
| **close** | 闭眼 | EAR < 0.15 for > 10 frames |
| **wide_open** | 睁大眼 | EAR > 0.4 |
| **squint** | 眯眼 | EAR 0.15-0.25 |
**EAR (Eye Aspect Ratio)** 计算方式：
```
EAR = (|p2-p6| + |p3-p5|) / (2 × |p1-p4|)
```
### 2.2 Gaze Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **look_left** | 向左看 | iris_position_x < 0.3 |
| **look_right** | 向右看 | iris_position_x > 0.7 |
| **look_center** | 向前看 | iris_position_x 0.3-0.7 |
---
## 三、Mouth Actions (待安装 MediaPipe)
### 3.1 Basic Mouth Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **open** | 张嘴 | MAR > 0.5 |
| **close** | 闭嘴 | MAR < 0.2 |
| **smile** | 微笑 | mouth_corner_distance > threshold |
| **pout** | 嘟嘴 | lip_distance > threshold |
**MAR (Mouth Aspect Ratio)** 计算方式：
```
MAR = mouth_height / mouth_width
```
### 3.2 Dynamic Mouth Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **talk** ⭐ | 说话 | MAR oscillating 0.3-0.6 (min 10 frames) |
| **yawn** ⭐ | 打哈欠 | MAR > 0.7 (min 20 frames) |
---
## 四、Arm Actions (待安装 MediaPipe Pose)
### 4.1 Raise Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **raise_left** | 举起左手 | left_shoulder_y > elbow_y > wrist_y |
| **raise_right** | 举起右手 | right_shoulder_y > elbow_y > wrist_y |
| **raise_both** | 双手举起 | both arms raised |
### 4.2 Angle Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **extend_left** | 伸展左臂 | left_elbow_angle > 150° |
| **extend_right** | 伸展右臂 | right_elbow_angle > 150° |
| **fold_left** | 弯曲左臂 | left_elbow_angle < 90° |
| **fold_right** | 弯曲右臂 | right_elbow_angle < 90° |
### 4.3 Complex Arm Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **cross_arms** ⭐ | 双手交叉 | left_wrist_x > right_wrist_x AND overlapping |
| **wave** ⭐ | 挥手 | wrist_y oscillating ±20px (5-15 frames) |
| **point** | 指向 | index_finger extended, others folded |
---
## 五、Hand Actions (待安装 MediaPipe Hand)
### 5.1 Basic Hand Gestures
| Action | Description | Pattern |
|--------|-------------|---------|
| **open** | 张开手 | all 5 fingers extended |
| **fist** | 握拳 | all fingers folded into palm |
| **grab** | 抓取 | fingers folded, thumb opposing |
### 5.2 Specific Gestures
| Action | Description | Pattern |
|--------|-------------|---------|
| **thumbs_up** ⭐ | 点赞 | thumb extended upward, others folded |
| **peace** ⭐ | 剪刀手 | index + middle extended, others folded |
| **ok** ⭐ | OK 手势 | thumb + index touching |
| **point** | 指向 | index extended, others folded |
### 5.3 Contact Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **touch_face** | 摸脸 | hand near face region |
| **touch_hair** | 摸头发 | hand above head region |
| **pocket_left** | 左手插兜 | left_hand in hip region |
| **pocket_right** | 右手插兜 | right_hand in hip region |
### 5.4 Dynamic Hand Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **clap** ⭐ | 拍手 | hands together → apart (3-10 frames) |
---
## 六、Leg Actions (待安装 MediaPipe Pose)
### 6.1 Basic Leg Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **stand** | 站立 | hip_y < knee_y < ankle_y (vertical) |
| **sit** ⭐ | 姿 | hip_y ≈ knee_y (horizontal thigh) |
| **knee_bend** | 弯膝 | knee_angle < 120° |
### 6.2 Dynamic Leg Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **walk** ⭐ | 行走 | hip-knee-ankle oscillating (min 10 frames) |
| **run** ⭐ | 奔跑 | fast oscillating + knee_bend > 60° (min 10 frames) |
| **jump** ⭐ | 跳跃 | keypoints moving upward → landing (5-20 frames) |
| **kick** ⭐ | 踢腿 | one leg extended forward rapidly (3-15 frames) |
### 6.3 Cross Actions
| Action | Description | Pattern |
|--------|-------------|---------|
| **cross_left** | 左腿交叉 | left_ankle_x > right_ankle_x |
| **cross_right** | 右腿交叉 | right_ankle_x > left_ankle_x |
---
## 七、Feet Actions (待安装 MediaPipe Pose)
| Action | Description | Pattern |
|--------|-------------|---------|
| **tap** ⭐ | 轻踏 | ankle_y oscillating ±10px (3-15 frames) |
| **stomp** ⭐ | 重踏 | ankle_y large downward movement (min 3 frames) |
| **cross** | 交叉脚 | feet_x overlapping |
| **point_left** | 左脚前伸 | left_ankle_y < right_ankle_y |
| **point_right** | 右脚前伸 | right_ankle_y < left_ankle_y |
---
## 八、Combined Actions ⭐ (多源组合)
| Action | Description | Components |
|--------|-------------|------------|
| **thinking** | 思考姿势 | touch_face + look_down |
| **listening** | 倾听姿势 | turn_partial + mouth_open |
| **nodding_agreement** | 点头同意 | nod_head + smile |
| **shaking_disagreement** | 摇头不同意 | shake_head + frown |
| **waving_greeting** | 挥手打招呼 | wave + smile |
| **crossing_arms_defensive** | 双手交叉防御 | cross_arms + frontal_stable |
| **pointing_explaining** | 指向解释 | point + turn_partial |
| **stretching** | 伸展 | raise_both + look_up |
| **sitting_relaxed** | 放松坐姿 | sit + cross_arms |
---
## 九、MediaPipe Keypoint Indices
### 9.1 Pose Keypoints (33 points)
| Index | Keypoint | Description |
|-------|----------|-------------|
| **0** | nose | 鼻尖 |
| **11** | left_shoulder | 左肩 |
| **12** | right_shoulder | 右肩 |
| **13** | left_elbow | 左肘 |
| **14** | right_elbow | 右肘 |
| **15** | left_wrist | 左手腕 |
| **16** | right_wrist | 右手腕 |
| **23** | left_hip | 左髋 |
| **24** | right_hip | 右髋 |
| **25** | left_knee | 左膝 |
| **26** | right_knee | 右膝 |
| **27** | left_ankle | 左踝 |
| **28** | right_ankle | 右踝 |
### 9.2 Hand Keypoints (21 points per hand)
| Index | Keypoint | Description |
|-------|----------|-------------|
| **0** | wrist | 手腕 |
| **1-4** | thumb | 拇指 (CMC → TIP) |
| **5-8** | index | 食指 (MCP → TIP) |
| **9-12** | middle | 中指 (MCP → TIP) |
| **13-16** | ring | 无名指 (MCP → TIP) |
| **17-20** | pinky | 小指 (MCP → TIP) |
### 9.3 Face Mesh Keypoints (468 points)
| Region | Points | Description |
|--------|--------|-------------|
| **Eyes** | 33-133, 362-382 | 眼睛轮廓 + 瞳孔 |
| **Iris** | 468-477 | 虹膜位置 |
| **Mouth** | 61-308 | 嘴唇轮廓 |
| **Nose** | 1-98 | 鼻子 |
---
## 十、安装 MediaPipe
### 10.1 安装命令
```bash
# 安装 MediaPipe
pip install mediapipe==0.10.9
# 或使用 Homebrew Python
/opt/homebrew/bin/python3.11 -m pip install mediapipe==0.10.9
```
### 10.2 模型说明
| Model | Output | Description |
|-------|--------|-------------|
| **Holistic** | pose + face + hands | 全身关键点 (468 face + 33 pose + 42 hands) |
| **Pose** | 33 keypoints | 姿态估计 |
| **Face Mesh** | 468 keypoints | 面部网格 |
| **Hands** | 42 keypoints | 手部关键点 |
---
## 十一、使用方式
### 11.1 当前可用功能（Face）
```bash
# 仅使用 Face 数据（已有）
python3 scripts/utils/body_action_decoder.py \
--face-json video.face_traced.json
```
### 11.2 完整功能（需安装 MediaPipe）
```bash
# 使用 Face + Pose + Hand 数据
python3 scripts/utils/body_action_decoder.py \
--pose-json video.pose.json \
--face-json video.face_traced.json \
--hand-json video.hand.json \
--output-json body_action_data.json
```
---
## 十二、输出结构
```json
{
"face": [
{"action": "turn_right", "description": "向右转"}
],
"eyes": [
{"action": "blink", "description": "眨眼", "ear": 0.18}
],
"mouth": [
{"action": "smile", "description": "微笑", "corner_distance": 12.5}
],
"arms": [
{"action": "raise_right", "description": "举起右手", "angle": 120.5}
],
"hands": [
{"action": "thumbs_up_right", "description": "右手点赞"}
],
"legs": [
{"action": "stand", "description": "站立"}
],
"feet": [],
"combined": [
{"action": "waving_greeting", "description": "挥手打招呼", "components": ["wave", "smile"]}
]
}
```
---
## 十三、未来改进
| Phase | 功能 | 状态 |
|-------|------|------|
| **Phase 1** | Face Actions | ✅ 已完成 |
| **Phase 2** | Eye/Mouth Actions | ⏸ 待安装 MediaPipe Face Mesh |
| **Phase 3** | Arm/Hand Actions | ⏸ 待安装 MediaPipe Hand |
| **Phase 4** | Leg/Feet Actions | ⏸ 待安装 MediaPipe Pose |
| **Phase 5** | Combined Actions | ⏸ 待整合多源数据 |
---
## 版本信息
- 版本: 1.0
- 创建日期: 2026-04-28
- 状态: ✅ Face Actions 完成，其他待安装 MediaPipe

8
docs_v1.0/CHUNKING/CORE/CHUNKING_ARCHITECTURE.md
View File

@@ -112,9 +112,9 @@ ai_query_hints:
### 3.1 數據關聯架構 (Input Aggregation) ### 3.1 數據關聯架構 (Input Aggregation)
針對每一個 Parent Chunk `[start_frame, end_frame]`，系統提取： 針對每一個 Parent Chunk `[start_frame, end_frame]`，系統提取：
1. **子 Chunk (Rule 1)**: 提取對話 (`content`) 與說話者 (`speaker_id`)。 1. **子 Chunk (Rule 1)**: 提取對話 (`content`) 與說話者 (`speaker_id`)。
2. **子 Chunk (Rule 2)**: 提取物件標籤 (`frame_objects`)。 2. **子 Chunk (Rule 2)**: 提取物件標籤 (`frame_objects`)。
3. **身份解析**: 將 `face_id` 解析為真實人名 (e.g., `face_01` -> "Cary Grant")。 3. **身份解析**: 將 `face_id` 解析為真實人名 (e.g., `face_01` -> "Cary Grant")。
### 3.2 LLM 上下文構造 (Context Construction) ### 3.2 LLM 上下文構造 (Context Construction)
@@ -270,4 +270,4 @@ src/core/db/postgres_db.rs
2. **[DESIGN_IMPLEMENTATION_GAP.md](../../DESIGN_IMPLEMENTATION_GAP.md)** - 設計與實現差異分析 2. **[DESIGN_IMPLEMENTATION_GAP.md](../../DESIGN_IMPLEMENTATION_GAP.md)** - 設計與實現差異分析
3. **[ARCHITECTURE_OVERVIEW.md](../../ARCHITECTURE_OVERVIEW.md)** - 架構總覽 3. **[ARCHITECTURE_OVERVIEW.md](../../ARCHITECTURE_OVERVIEW.md)** - 架構總覽
**最後更新**: 2026-04-22 **最後更新**: 2026-04-22

6
docs_v1.0/CHUNKING/CORE/CHUNKING_SCHEMA_SPEC.md
View File

@@ -61,9 +61,9 @@ ai_query_hints:
本規範確保所有資料庫表嚴格遵循 **Chunking Architecture** 定義的通用結構： 本規範確保所有資料庫表嚴格遵循 **Chunking Architecture** 定義的通用結構：
1. **時間權威 (Frame-Based)**：所有時間相關欄位以 `frame` 為核心，`timestamp` 為計算參考。 1. **時間權威 (Frame-Based)**：所有時間相關欄位以 `frame` 為核心，`timestamp` 為計算參考。
2. **內容與元數據分離 (Content vs Metadata)**：`content` 用於全文檢索與向量嵌入，`metadata` (JSONB) 儲存關聯物件、Speaker、Faces 等結構化數據。 2. **內容與元數據分離 (Content vs Metadata)**：`content` 用於全文檢索與向量嵌入，`metadata` (JSONB) 儲存關聯物件、Speaker、Faces 等結構化數據。
3. **路由清晰 (Rule Routing)**：每個 Rule 對應獨立的資料表，透過 `chunk_type` 欄位輔助識別。 3. **路由清晰 (Rule Routing)**：每個 Rule 對應獨立的資料表，透過 `chunk_type` 欄位輔助識別。
--- ---

20
docs_v1.0/CHUNKING/RULES/SCENE_BASED/CHUNK_RULE_3_SCENE.md
View File

@@ -42,8 +42,8 @@ ai_query_hints:
- **核心原則**: 一個鏡頭/場景 (Cut) = 一個 Parent Chunk。 - **核心原則**: 一個鏡頭/場景 (Cut) = 一個 Parent Chunk。
- **結構**: 採用 **Parent-Child (父子)** 架構。 - **結構**: 採用 **Parent-Child (父子)** 架構。
- **Parent (Rule 3)**: 代表整個場景，包含摘要 (Summary) 與聚合向量。 - **Parent (Rule 3)**: 代表整個場景，包含摘要 (Summary) 與聚合向量。
- **Children (Rule 1/2)**: 場景內包含的具體句子與視覺幀。 - **Children (Rule 1/2)**: 場景內包含的具體句子與視覺幀。
- **優勢**: 支援跨句子的長語境搜尋 (例如搜尋整個情節的摘要，而非單一單詞)。 - **優勢**: 支援跨句子的長語境搜尋 (例如搜尋整個情節的摘要，而非單一單詞)。
--- ---
@@ -52,11 +52,11 @@ ai_query_hints:
Rule 3 不直接從原始影片產生，而是依賴 **Rule 1** 與 **Rule 2** 的產出。 Rule 3 不直接從原始影片產生，而是依賴 **Rule 1** 與 **Rule 2** 的產出。
1. **Cut Processor (Primary)**: 提供場景的邊界。 1. **Cut Processor (Primary)**: 提供場景的邊界。
- *定義*: `start_frame`, `end_frame` 為一個完整鏡頭。 - *定義*: `start_frame`, `end_frame` 為一個完整鏡頭。
2. **Rule 1 Chunks (Children)**: 收集該場景內所有的 ASR 語句 (Sentences)。 2. **Rule 1 Chunks (Children)**: 收集該場景內所有的 ASR 語句 (Sentences)。
3. **Rule 2 Chunks (Children)**: 收集該場景內所有的視覺幀數據 (Visual Frames)。 3. **Rule 2 Chunks (Children)**: 收集該場景內所有的視覺幀數據 (Visual Frames)。
4. **Summary Generation**: 4. **Summary Generation**:
- 為了讓 Parent Chunk 具備搜尋能力，系統會將所有子 Chunk 的內容 (ASR 文本 + 物件標籤) 組合成一段「場景描述」，並由 LLM (選用) 或規則生成一段 **Summary**。 - 為了讓 Parent Chunk 具備搜尋能力，系統會將所有子 Chunk 的內容 (ASR 文本 + 物件標籤) 組合成一段「場景描述」，並由 LLM (選用) 或規則生成一段 **Summary**。
--- ---
@@ -138,15 +138,15 @@ Rule 3 的 API 返回應包含聚合後的子項目。
Rule 3 專為**宏觀理解**與**摘要檢索**設計。 Rule 3 專為**宏觀理解**與**摘要檢索**設計。
### 3.1 場景摘要搜尋 (Summary Search) ### 3.1 場景摘要搜尋 (Summary Search)
* **場景**: "尋找他們討論分贓的場景" (可能包含多句對話)。 - **場景**: "尋找他們討論分贓的場景" (可能包含多句對話)。
* **邏輯**: - **邏輯**:
1. Query: "Discussion about splitting the money". 1. Query: "Discussion about splitting the money".
2. Match: 搜尋 `parent_chunks.summary` 的向量。 2. Match: 搜尋 `parent_chunks.summary` 的向量。
3. 結果：直接返回整個場景 (Parent)，而非零碎的句子。 3. 結果：直接返回整個場景 (Parent)，而非零碎的句子。
### 3.2 混合檢索 (Hybrid Retrieval) ### 3.2 混合檢索 (Hybrid Retrieval)
* **場景**: 使用者搜尋 "槍戰"。 - **場景**: 使用者搜尋 "槍戰"。
* **策略**: - **策略**:
1. **Hit**: Rule 2 (Visual) 命中 (偵測到 "gun")。 1. **Hit**: Rule 2 (Visual) 命中 (偵測到 "gun")。
2. **Expand**: 系統自動向上查找該 Rule 2 所屬的 Rule 3 Parent。 2. **Expand**: 系統自動向上查找該 Rule 2 所屬的 Rule 3 Parent。
3. **Return**: 返回該場面的完整上下文 (包含槍戰前後的對話)。 3. **Return**: 返回該場面的完整上下文 (包含槍戰前後的對話)。

24
docs_v1.0/CHUNKING/RULES/TEXT_BASED/CHUNK_RULE_1_SENTENCE.md
View File

@@ -50,10 +50,10 @@ ai_query_hints:
Rule 1 的生成依賴三個上游處理器的產出： Rule 1 的生成依賴三個上游處理器的產出：
1. **ASR (Primary)**: 提供文本內容 (`text`)、起始時間 (`start_time`)、結束時間 (`end_time`)。 1. **ASR (Primary)**: 提供文本內容 (`text`)、起始時間 (`start_time`)、結束時間 (`end_time`)。
2. **ASRX (Speaker)**: 提供說話者 ID (`speaker_id`)。 2. **ASRX (Speaker)**: 提供說話者 ID (`speaker_id`)。
- *聚合策略*: 使用 ASR 的時間區間去對齊 ASRX，取該區間內**佔比最高**的 `speaker_id`。 - *聚合策略*: 使用 ASR 的時間區間去對齊 ASRX，取該區間內**佔比最高**的 `speaker_id`。
3. **Face (Visual)**: 提供幀級別的人物 ID (`face_id`)。 3. **Face (Visual)**: 提供幀級別的人物 ID (`face_id`)。
- *聚合策略*: 在 ASR 的 `[start_frame, end_frame]` 區間內，收集所有出現的 `face_id`。若同一 ID 出現多次，去重後形成 `face_ids` 陣列。 - *聚合策略*: 在 ASR 的 `[start_frame, end_frame]` 區間內，收集所有出現的 `face_id`。若同一 ID 出現多次，去重後形成 `face_ids` 陣列。
--- ---
@@ -120,21 +120,21 @@ CREATE TABLE chunks_rule1 (
Rule 1 支援三種主要搜尋模式： Rule 1 支援三種主要搜尋模式：
### 3.1 語意搜尋 (Vector Search) ### 3.1 語意搜尋 (Vector Search)
* **場景**: "有人提到錢嗎？" (即使影片沒說 "錢"，而是說 "鈔票" 也能搜到)。 - **場景**: "有人提到錢嗎？" (即使影片沒說 "錢"，而是說 "鈔票" 也能搜到)。
* **邏輯**: - **邏輯**:
1. 將 Query 透過 Ollama (`nomic-v2-moe`) 轉為 768-dim 向量。 1. 將 Query 透過 Ollama (`nomic-v2-moe`) 轉為 768-dim 向量。
2. 在 Qdrant (`collection: momentry_rule1`) 中進行 Cosine 相似度比對。 2. 在 Qdrant (`collection: momentry_rule1`) 中進行 Cosine 相似度比對。
3. **Filter**: 可加入 `metadata.speaker == "SPEAKER_00"`。 3. **Filter**: 可加入 `metadata.speaker == "SPEAKER_00"`。
### 3.2 關鍵字搜尋 (BM25 Search) ### 3.2 關鍵字搜尋 (BM25 Search)
* **場景**: "搜尋確切字串 'Charade 1963'"。 - **場景**: "搜尋確切字串 'Charade 1963'"。
* **邏輯**: - **邏輯**:
1. 使用 PostgreSQL `tsvector` 進行全文檢索。 1. 使用 PostgreSQL `tsvector` 進行全文檢索。
2. 適合精確匹配專有名詞。 2. 適合精確匹配專有名詞。
### 3.3 過濾搜尋 (Faceted Search) ### 3.3 過濾搜尋 (Faceted Search)
* **場景**: "找出 **Audrey Hepburn (Face)** 說話的所有片段"。 - **場景**: "找出 **Audrey Hepburn (Face)** 說話的所有片段"。
* **邏輯**: - **邏輯**:
1. `face_ids` 包含 "Audrey Hepburn" 的 ID。 1. `face_ids` 包含 "Audrey Hepburn" 的 ID。
2. `speaker_id` 不為空 (代表她在說話)。 2. `speaker_id` 不為空 (代表她在說話)。
3. 檢索符合條件的 Chunks。 3. 檢索符合條件的 Chunks。
@@ -181,9 +181,9 @@ for seg in asr_segments:
## 5. 向量嵌入策略 ## 5. 向量嵌入策略
* **嵌入模型**: `nomic-embed-text-v2-moe` (768-dim)。 - **嵌入模型**: `nomic-embed-text-v2-moe` (768-dim)。
* **嵌入內容**: 僅使用 `content` (句子文字)。 - **嵌入內容**: 僅使用 `content` (句子文字)。
* *原因*: 避免 speaker 或 face 的 metadata 干擾語意向量空間，確保語意純淨。Metadata 僅用於過濾 (Filter)。 - *原因*: 避免 speaker 或 face 的 metadata 干擾語意向量空間，確保語意純淨。Metadata 僅用於過濾 (Filter)。
--- ---

30
docs_v1.0/CHUNKING/RULES/VISUAL_BASED/CHUNK_RULE_2_VISUAL.md
View File

@@ -50,12 +50,12 @@ ai_query_hints:
Rule 2 的生成主要依賴視覺處理器產出，並輔助以音訊元數據。 Rule 2 的生成主要依賴視覺處理器產出，並輔助以音訊元數據。
1. **YOLO (Primary)**: 提供幀級別的物件檢測。 1. **YOLO (Primary)**: 提供幀級別的物件檢測。
- *過濾*: 僅保留 `confidence > 0.8` 的物件。 - *過濾*: 僅保留 `confidence > 0.8` 的物件。
- *格式*: 轉換為描述性字串，如 "a person", "a car", "a cup"。 - *格式*: 轉換為描述性字串，如 "a person", "a car", "a cup"。
2. **Face (Secondary)**: 提供幀級別的人物 ID。 2. **Face (Secondary)**: 提供幀級別的人物 ID。
- *策略*: 記錄當前幀所有可見的 `face_id`。 - *策略*: 記錄當前幀所有可見的 `face_id`。
3. **ASRX (Audio Overlay)**: 提供當前時間點的說話者。 3. **ASRX (Audio Overlay)**: 提供當前時間點的說話者。
- *策略*: 取時間重疊的 `speaker_id`，若無則為空。 - *策略*: 取時間重疊的 `speaker_id`，若無則為空。
### 聚合策略 (Time-Windowing) ### 聚合策略 (Time-Windowing)
@@ -130,23 +130,23 @@ CREATE TABLE chunks_rule2 (
Rule 2 專為**視覺語意 (Visual Semantics)** 設計。 Rule 2 專為**視覺語意 (Visual Semantics)** 設計。
### 3.1 視覺關鍵字搜尋 (Visual Keyword Search) ### 3.1 視覺關鍵字搜尋 (Visual Keyword Search)
* **場景**: "找出有車子的畫面"、"搜尋開車場景"。 - **場景**: "找出有車子的畫面"、"搜尋開車場景"。
* **邏輯**: - **邏輯**:
1. Query: "driving a car"。 1. Query: "driving a car"。
2. Embedding: 將 "driving a car" 轉為向量。 2. Embedding: 將 "driving a car" 轉為向量。
3. Match: 與 `content` ("car, person...") 的向量進行比對。 3. Match: 與 `content` ("car, person...") 的向量進行比對。
- *注意*: 雖然使用者搜尋是自然語言，但 Rule 2 的底層索引是物件標籤。由於 `nomic-v2-moe` 具有強大的語意對齊能力，"driving a car" 會高度匹配 "car" 標籤。 - *注意*: 雖然使用者搜尋是自然語言，但 Rule 2 的底層索引是物件標籤。由於 `nomic-v2-moe` 具有強大的語意對齊能力，"driving a car" 會高度匹配 "car" 標籤。
### 3.2 高信心值過濾 (Confidence Filtering) ### 3.2 高信心值過濾 (Confidence Filtering)
* **場景**: "找出 100% 確定有槍的畫面"。 - **場景**: "找出 100% 確定有槍的畫面"。
* **邏輯**: - **邏輯**:
- 直接查詢 `frame_objects` JSONB 欄位，要求 `confidence > 0.95`。 - 直接查詢 `frame_objects` JSONB 欄位，要求 `confidence > 0.95`。
### 3.3 跨模態搜尋 ### 3.3 跨模態搜尋
* **場景**: "找出 Cary Grant 說話且背景有車的畫面"。 - **場景**: "找出 Cary Grant 說話且背景有車的畫面"。
* **邏輯**: - **邏輯**:
- `face_ids` 包含 "Cary Grant" **AND** - `face_ids` 包含 "Cary Grant" **AND**
- `frame_objects` 包含 "car"。 - `frame_objects` 包含 "car"。
--- ---
@@ -196,8 +196,8 @@ for i in range(0, total_frames, WINDOW):
### 4.2 嵌入策略 (Embedding Strategy) ### 4.2 嵌入策略 (Embedding Strategy)
* **輸入文本**: 僅使用 `content` (物件標籤字串)。 - **輸入文本**: 僅使用 `content` (物件標籤字串)。
* **原因**: 確保向量空間專注於**視覺語意**。若混入 Audio (ASR) 文本，會導致搜尋 "車" 時意外匹配到只提到車但未出現車的畫面。 - **原因**: 確保向量空間專注於**視覺語意**。若混入 Audio (ASR) 文本，會導致搜尋 "車" 時意外匹配到只提到車但未出現車的畫面。
--- ---

196
docs_v1.0/EXPERIMENT_REPORTS/FACE_PROCESSOR_PERFORMANCE_2026-04-28.md Normal file
View File

@@ -0,0 +1,196 @@
# Face Processor 性能评估报告
> 测试日期: 2026-04-28
> 测试视频: preview.mp4 (15秒, 329帧)
> 测试版本: face_processor.py (InsightFace REQUIRED)
---
## 测试环境
| 配置 | 值 |
|------|-----|
| **视频文件** | preview.mp4 |
| **视频时长** | 15秒 |
| **总帧数** | 329 |
| **FPS** | 22 |
| **分辨率** | 640x360 |
| **采样间隔** | 10 (每10帧检测一次) |
---
## 对比测试: OLD vs NEW
### OLD (Haar Cascade fallback)
| 指标 | 结果 |
|------|------|
| **Frames 处理** | 8 |
| **Faces 检测** | 8 |
| **Embeddings** | 0 ❌ |
| **Embedding dim** | NULL |
| **Attributes** | NULL |
| **Detection method** | haar_cascade |
**问题**: Haar Cascade 无法生成 embedding，导致全链路失败。
### NEW (InsightFace REQUIRED)
| 指标 | 结果 |
|------|------|
| **Frames 处理** | 31 |
| **Faces 检测** | 31 |
| **Embeddings** | 31 ✅ |
| **Embedding dim** | 512 ✅ |
| **Attributes** | {age, gender} ✅ |
| **Detection method** | insightface |
**改进**: 所有检测的人脸都成功生成 512-dim embedding。
---
## Embedding 质量分析
### Embedding 统计
| 指标 | 结果 | 说明 |
|------|------|------|
| **Embeddings 提取** | 31 | ✅ 全部成功 |
| **Embedding 维度** | 512 | ✅ ArcFace |
| **Embedding norms** | 23.18 (avg) | 未归一化 |
| **Norms std** | 1.01 | 标准差小，质量稳定 |
### Intra-person Similarity (同人脸相似度)
| 指标 | 结果 | 说明 |
|------|------|------|
| **平均相似度** | 0.7764 | ✅ 正常（阈值: 0.85） |
| **最小相似度** | 0.0902 | ⚠️ 过低（可能角度变化） |
| **最大相似度** | 0.9960 | ✅ 很高 |
| **相似度范围** | 0.09 - 0.99 | ⚠️ 波动大 |
### 问题分析
⚠️ **相似度波动大 (0.09 - 0.99)**
**原因**:
1. 人脸角度变化（正面 vs 侧面）
2. 人脸表情变化
3. 光线变化
4. 人脸大小变化
**解决方案**: **1对多参考向量架构**
- 同一 Identity 存储多个 embedding（不同角度）
- 使用投票机制 + 加权平均匹配
- 提高识别鲁棒性
---
## Attributes 检测质量
### 年龄检测
| Frame | Age | Confidence |
|-------|-----|------------|
| 10 | 37 | 0.81 |
| 20 | 36 | 0.81 |
| 30 | 39 | 0.82 |
| 40 | 36 | 0.84 |
| 50 | 43 | 0.85 |
**分析**: 年龄波动 36-43，平均约 38岁。
### 性别检测
| Frame | Gender | Confidence |
|-------|--------|------------|
| All | male | 0.81-0.85 |
**分析**: 性别一致，检测稳定。
---
## 性能指标
### 处理速度
| 指标 | 结果 |
|------|------|
| **视频时长** | 15秒 |
| **处理帧数** | 31 |
| **采样间隔** | 10 |
| **InsightFace 模型** | buffalo_l (5个模型) |
**模型加载**:
- `det_10g.onnx` - 人脸检测
- `w600k_r50.onnx` - Recognition (512-dim)
- `genderage.onnx` - 年龄/性别
- `landmark_3d_68.onnx` - 3D关键点
- `landmark_2d_106.onnx` - 2D关键点
---
## 关键改进总结
| 改进项 | OLD (Haar) | NEW (InsightFace) |
|--------|-----------|------------------|
| **Embeddings** | 0 | 31 ✅ |
| **Embedding dim** | NULL | 512 ✅ |
| **Attributes** | NULL | {age, gender} ✅ |
| **Landmarks** | NULL | 3D + 2D ✅ |
| **Recognition** | ❌ | ✅ |
| **Identity Matching** | ❌ | ✅ |
---
## 下一步建议
### 1. 归一化 Embedding
```python
# 当前 norms = 23.18，建议归一化到 1.0
embedding_normalized = embedding / np.linalg.norm(embedding)
```
### 2. 1对多参考向量
```json
{
"face_embeddings": [
{"embedding": [...], "angle": "frontal", "quality": 0.95},
{"embedding": [...], "angle": "profile_left", "quality": 0.88},
{"embedding": [...], "angle": "three_quarter", "quality": 0.92}
]
}
```
### 3. 匹配算法优化
- **投票机制**: 统计超过阈值的参考向量数量
- **加权平均**: 根据质量评分加权计算相似度
- **综合评分**: 50% 最佳匹配 + 30% 投票 + 20% 加权
---
## 结论
✅ **Face Processor 修复成功**
- 所有检测的人脸都成功生成 512-dim embedding
- 年龄/性别检测正常
- 嵌入质量稳定
⚠️ **需要改进**
- Embedding 需要归一化
- 相似度波动大，需要 1对多参考向量架构
- 建议实现投票机制匹配算法
---
## 版本信息
- 测试版本: V1.0
- 测试日期: 2026-04-28
- 测试状态: ✅ 成功

206
docs_v1.0/EXPERIMENT_REPORTS/FACE_TRACKER_INTEGRATION_REPORT_2026-04-28.md Normal file
View File

@@ -0,0 +1,206 @@
# Face Tracker 整合 Identity Registration 完成报告
> 实验日期: 2026-04-28
> 实验版本: V3.0 (Face Tracker + Reference Vector Selection)
---
## 实验概述
将 **Face Tracker** 整合到 **Identity Registration** 流程：
1. **Face Tracker**: 追踪人脸跨帧连续性，分配 `trace_id`
2. **Reference Vector Selection V3**: 从特定 trace 选择参考向量
3. **Identity Registration**: 注册带 trace statistics 的 identity
---
## 创建的文件
| 文件 | 说明 |
|------|------|
| `scripts/utils/face_tracker.py` | 人脸追踪脚本 |
| `scripts/utils/face_trace_visualizer.py` | 可视化脚本 |
| `scripts/select_face_reference_vectors_v3.py` | Trace-based 参考向量选择 |
| `docs_v1.0/FACE_TRACKER_GUIDE.md` | Face Tracker 功能文档 |
---
## 测试结果
### 1. Face Tracking
| Trace | Frames | Duration | Appearances | Avg Confidence | Pose Distribution |
|-------|--------|----------|-------------|----------------|-------------------|
| **0** | 1-146 | 6.64s | 146 | **0.76** | three_quarter (144), profile_left (2) |
| **2** | 155-297 | 6.50s | 143 | **0.86** ✅ | profile_right (125), three_quarter (18) |
| **3** | 298-329 | 1.45s | 32 | **0.69** | profile_left (32) |
**关键发现**:
- Trace 2 置信度最高 (0.862)，适合作为 Identity 参考向量来源
- Trace 3 置信度较低 (0.69)，可能不适合注册
---
### 2. Reference Vector Selection V3
| 参数 | Trace 0 | Trace 2 |
|------|---------|---------|
| **Vectors Selected** | 4 | 4 |
| **Angles Covered** | three_quarter, profile_left | profile_right, three_quarter |
| **Quality Avg** | 0.774 | **0.875** ✅ |
**Trace 2 Vector Details**:
```
Vector 1: profile_right (frame 220), quality: 0.889
Vector 2: profile_right (frame 212), quality: 0.889
Vector 3: three_quarter (frame 180), quality: 0.861
Vector 4: three_quarter (frame 181), quality: 0.861
```
---
### 3. Identity Matching
| 指标 | Trace 2 Identity | Trace 0 Identity |
|------|-------------------|------------------|
| **Match Ratio** | **33.54%** (108/322) | 未测试 |
| **profile_right Similarity** | **0.8361** ✅ | 未测试 |
| **three_quarter Similarity** | 0.4398 | 未测试 |
| **Angle Match Types** | exact (288), fallback (34) | 未测试 |
**对比之前的单一向量匹配**:
| 匹配策略 | Match Ratio | profile_right Similarity |
|----------|-------------|--------------------------|
| Best Match (单向量) | 48.39% | 0.08 ❌ |
| Pose-filtered V2 | 41.94% | 0.8547 ✅ |
| **Trace-based V3** | **33.54%** | **0.8361** ✅ |
**说明**:
- Trace-based V3 Match Ratio 较低 (33.54% vs 41.94%)
- 原因: Trace 2 仅覆盖 frames 155-297，不包括 Trace 0 和 Trace 3
- 优势: 高置信度匹配（仅匹配 Trace 2 frames），相似度高 (0.8361)
---
### 4. trace_stats 存储
```json
{
"trace_id": 2,
"trace_stats": {
"start_frame": 155,
"end_frame": 297,
"duration_frames": 143,
"duration_seconds": 6.5,
"total_appearances": 143,
"avg_confidence": 0.8624,
"pose_distribution": {
"profile_right": 125,
"three_quarter": 18
}
}
}
```
---
## 完整流程
### 建议使用方式
```bash
# Step 1: Face detection (所有帧)
python3 scripts/face_processor.py video.mp4 video.face.json \
--sample-interval 1
# Step 2: Face tracking
python3 scripts/utils/face_tracker.py \
--face-json video.face.json \
--output video.face_traced.json
# Step 3: 分析 traces，选择最佳 trace
python3 scripts/utils/face_tracker.py \
--face-json video.face_traced.json \
--analyze-only
# Step 4: 从最佳 trace 选择参考向量
python3 scripts/select_face_reference_vectors_v3.py \
--face-json video.face_traced.json \
--trace-id-filter 2 \
--identity-name "Person Name" \
--register
# 或自动选择最长 trace
python3 scripts/select_face_reference_vectors_v3.py \
--face-json video.face_traced.json \
--use-longest-trace \
--identity-name "Person Name" \
--register
# Step 5: Matching (可选，验证 identity)
python3 scripts/match_face_with_pose_filtering.py \
--identity-name "Person Name" \
--face-json video.face_traced.json \
--strategy pose_filtered_v2 \
--batch
```
---
## trace_id 选择建议
| 场景 | 建议 |
|------|------|
| **单人视频** | 使用 `--use-longest-trace` |
| **多人视频** | 使用 `--trace-id-filter 2`（指定最佳 trace） |
| **高质量 Identity** | 选择 avg_confidence > 0.85 的 trace |
| **低质量视频** | 检查 trace confidence，低于 0.7 不建议注册 |
---
## reference_data 结构对比
### V2 vs V3
| 字段 | V2 | V3 |
|------|----|----|
| **face_embeddings** | ✅ | ✅ (相同格式) |
| **angle_coverage** | ✅ | ✅ |
| **trace_id** | ❌ | ✅ |
| **trace_stats** | ❌ | ✅ |
| **selection_method** | `v2_auto_multi_angle` | `trace_filtered_v3` |
**V3 优势**:
- 包含 trace 统计信息（duration, confidence, pose distribution）
- 确保参考向量来自同一人物（同 trace_id）
- 更好的质量控制（选择高置信度 trace）
---
## 未来改进
| Phase | 功能 | 优先级 |
|-------|------|--------|
| **Phase 1** | Trace-based Registration (已完成) | ✅ |
| **Phase 2** | Multi-trace Identity（合并多个 trace） | 中 |
| **Phase 3** | Trace quality scoring（自动选择最佳 trace） | 中 |
| **Phase 4** | Real-time tracking API | 低 |
---
## 版本信息
- 版本: 3.0
- 创建日期: 2026-04-28
- 状态: ✅ Face Tracker + Reference Vector Selection V3 完成
---
## 参考文档
- `scripts/utils/face_tracker.py`: 人脸追踪脚本
- `scripts/utils/face_trace_visualizer.py`: 可视化脚本
- `scripts/select_face_reference_vectors_v3.py`: Trace-based 参考向量选择
- `docs_v1.0/FACE_TRACKER_GUIDE.md`: Face Tracker 功能文档
- `docs_v1.0/EXPERIMENT_REPORTS/POSE_BASED_MATCHING_FINAL_REPORT_2026-04-28.md`: Pose Optimization 报告

204
docs_v1.0/EXPERIMENT_REPORTS/IDENTITY_SYSTEM_EXPERIMENT_2026-04-28.md Normal file
View File

@@ -0,0 +1,204 @@
# 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
- 实验状态: ✅ 全部成功

309
docs_v1.0/EXPERIMENT_REPORTS/LANDMARKS_SOURCE_ANALYSIS_2026-04-28.md Normal file
View File

@@ -0,0 +1,309 @@
# Landmarks 来源分析报告
> 分析日期: 2026-04-28
> 分析目标: face.json 中的 landmarks 字段
---
## 概述
`face.json` 中的 `landmarks` 字段用于 **Pose-based Identity Matching**。本报告分析：
1. **Landmarks 来源**: InsightFace buffalo_l 模型
2. **数据结构**: 5-point keypoints (kps)
3. **可靠性评估**: 模型精度 vs 实际测试
---
## 1. 数据流程
### 1.1 InsightFace buffalo_l 模型链
```
det_10g.onnx (RetinaFace) → Face detection + kps (5-point)
↓
1k3d68.onnx (Landmark3D) → landmark_3d_68 (68-point 3D)
↓
2d106det.onnx (Landmark2D) → landmark_2d_106 (106-point 2D)
↓
w600k_r50.onnx (ArcFace) → embedding (512-dim)
↓
genderage.onnx (Attribute) → age, gender
```
### 1.2 kps (5-point) 来源
**关键发现**: `kps` 来自 **RetinaFace 检测器**，而非 landmark_3d_68。
**代码路径**:
```
FaceAnalysis.get() → det_model.detect() → bboxes, kpss
→ Face(bbox, kps=kpss[i], det_score)
```
**文件**: `/opt/homebrew/lib/python3.11/site-packages/insightface/app/face_analysis.py:83-96`
```python
def get(self, img, max_num=0):
bboxes, kpss = self.det_model.detect(img, max_num=max_num, metric='default')
if bboxes.shape[0] == 0:
return []
ret = []
for i in range(bboxes.shape[0]):
bbox = bboxes[i, 0:4]
det_score = bboxes[i, 4]
kps = None
if kpss is not None:
kps = kpss[i]
face = Face(bbox=bbox, kps=kps, det_score=det_score)
for taskname, model in self.models.items():
if taskname=='detection':
continue
model.get(img, face)
ret.append(face)
return ret
```
---
## 2. kps 结构分析
### 2.1 数据格式
```json
{
"landmarks": [
[236.50, 106.82], // 0: left eye
[266.01, 107.21], // 1: right eye
[256.68, 123.23], // 2: nose
[241.10, 139.31], // 3: left mouth corner
[263.37, 139.54] // 4: right mouth corner
]
}
```
**维度**: `(5, 2)` - 5 个点，每个点 2D 坐标 (x, y)
### 2.2 点定义
| Index | Point | 说明 |
|-------|-------|------|
| 0 | left_eye | 左眼中心 |
| 1 | right_eye | 右眼中心 |
| 2 | nose | 鼻尖 |
| 3 | left_mouth | 左嘴角 |
| 4 | right_mouth | 右嘴角 |
---
## 3. kps vs landmark_3d_68 对比
### 3.1 理论来源
| Feature | kps | landmark_3d_68 |
|---------|-----|----------------|
| **来源模型** | RetinaFace (det_10g.onnx) | Landmark3D (1k3d68.onnx) |
| **点数** | 5 | 68 |
| **维度** | 2D (x, y) | 3D (x, y, z) |
| **用途** | Face alignment | Detailed geometry |
| **计算顺序** | Detection phase | Post-detection |
### 3.2 实际对比测试
**测试帧**: Frame 210 (preview.mp4)
```
=== kps from RetinaFace ===
left_eye: [236.45, 106.68]
right_eye: [265.98, 107.18]
nose: [256.51, 123.42]
left_mouth: [240.99, 139.40]
right_mouth: [263.23, 139.72]
=== landmark_3d_68 from Landmark3D ===
Eye centroids (36-41, 42-48):
left_eye centroid: [236.52, 107.16] diff: 0.49 pixel
right_eye centroid: [264.90, 107.68] diff: 1.19 pixel
Single points:
nose (30): [255.90, 119.21] diff: 4.25 pixel ⚠️
left_mouth (48): [241.40, 139.31] diff: 0.42 pixel
right_mouth (54): [263.42, 140.20] diff: 0.51 pixel
```
**关键发现**:
- **眼睛**: kps 与 landmark_3d_68 centroid 差异 < 1 pixel ✅
- **鼻子**: kps 与 landmark_3d_68 差异 4.25 pixel ⚠️
- **嘴角**: kps 与 landmark_3d_68 差异 < 1 pixel ✅
### 3.3 差异原因分析
**RetinaFace kps**:
- 在 detection phase 计算
- 使用 `distance2kps()` 函数从 anchor centers 解码
- 基于检测网络的回归输出
**Landmark3D landmark_3d_68**:
- 在 post-detection phase 计算
- 使用专门的 landmark 模型
- 更精细的面部几何
**差异原因**:
1. **不同模型**: RetinaFace vs Landmark3D
2. **不同精度**: kps 用于快速 alignment，landmark_3d_68 用于精细 alignment
3. **鼻子的特殊性**: RetinaFace kps 可能预测鼻尖位置不准确（4.25 pixel）
---
## 4. 可靠性评估
### 4.1 RetinaFace kps 可靠性
| 场景 | 可靠性 | 说明 |
|------|--------|------|
| **正面人脸** | ✅ 高 | det_score > 0.8，kps 精确 |
| **侧面人脸** | ✅ 高 | det_score > 0.8，kps 仍可靠 |
| **小脸检测** | ⚠️ 中 | det_size=320，小脸可能降低精度 |
| **低质量图像** | ⚠️ 中 | blur, low resolution 降低精度 |
### 4.2 Pose Analyzer 使用 kps 的可靠性
**计算特征**:
- `nose_to_eye_ratio`: nose 到 eye center 的距离比例
- `eye_slope`: 眼睛连线斜率（pitch detection）
- `nose_offset`: nose 相对 eye center 的偏移
- `mouth_symmetry`: 嘴角对称性
**可靠性分析**:
| Feature | 依赖点 | 可靠性 | 说明 |
|---------|--------|--------|------|
| nose_to_eye_ratio | nose (2), eyes (0,1) | ⚠️ 中 | nose 位置差异 4.25 pixel |
| eye_slope | eyes (0,1) | ✅ 高 | eyes 精确 (< 1 pixel) |
| nose_offset | nose (2), eye center | ⚠️ 中 | nose 位置差异 |
| mouth_symmetry | mouth corners (3,4) | ✅ 高 | mouth 精确 (< 1 pixel) |
**整体评估**: ✅ **可靠合理**
原因:
1. **多特征综合**: 使用 5 个特征，单一特征误差不影响整体
2. **眼睛主导**: eye_slope 和 eye center 最精确
3. **confidence score**: Pose Analyzer 输出 confidence，低 confidence 可过滤
4. **实际测试**: 31帧人脸，confidence avg = 0.87 ✅
---
## 5. 改进建议
### 5.1 短期改进
| 改进 | 说明 | 优先级 |
|------|------|--------|
| **使用 landmark_3d_68** | 替代 kps，更精确 | 高 |
| **鼻子点校准** | 使用 landmark_3d_68[30] 替代 kps[2] | 中 |
| **confidence threshold** | 添加 confidence 过滤（< 0.75 reject） | 低 |
### 5.2 实施方案
**方案 A: 使用 landmark_3d_68**
修改 `face_processor.py`:
```python
# Before
if hasattr(face, 'kps'):
landmarks = face.kps.tolist()
elif hasattr(face, 'landmark_3d_68'):
landmarks = face.landmark_3d_68.tolist()
# After (推荐)
if hasattr(face, 'landmark_3d_68'):
# Extract 5-point from landmark_3d_68
lm3d = face.landmark_3d_68
landmarks = [
np.mean(lm3d[36:42][:, :2], axis=0).tolist(), # left eye centroid
np.mean(lm3d[42:48][:, :2], axis=0).tolist(), # right eye centroid
lm3d[30][:2].tolist(), # nose tip
lm3d[48][:2].tolist(), # left mouth
lm3d[54][:2].tolist(), # right mouth
]
elif hasattr(face, 'kps'):
landmarks = face.kps.tolist() # Fallback
```
**预期效果**:
- nose 位置精度提升 (4.25 → 0 pixel)
- confidence 提升 (0.87 → 0.90+)
---
## 6. 结论
### 6.1 Landmarks 来源总结
| 问题 | 回答 |
|------|------|
| **来源模型** | RetinaFace (det_10g.onnx) - detection phase |
| **数据结构** | 5-point 2D keypoints (left_eye, right_eye, nose, left_mouth, right_mouth) |
| **精度** | eyes/mouth: < 1 pixel ✅, nose: ~4 pixel ⚠️ |
| **是否可靠** | ✅ **可靠合理** - 多特征综合降低单一误差影响 |
### 6.2 推荐行动
| 优先级 | 行动 |
|--------|------|
| **高** | 使用 landmark_3d_68 替代 kps |
| **中** | 测试改进后的 pose confidence |
| **低** | 添加 confidence threshold 过滤 |
---
## 7. 参考文档
- [InsightFace GitHub](https://github.com/deepinsight/insightface)
- [RetinaFace Paper](https://arxiv.org/abs/1905.00641)
- [buffalo_l Models](https://github.com/deepinsight/insightface/tree/master/model_zoo)
- `pose_analyzer.py`: 多特征 Pose 分类
- `face_processor.py`: Face detection + Pose 输出
---
## 附录: 实测数据
### Frame 210 (preview.mp4)
```json
{
"landmarks": [
[236.50, 106.82],
[266.01, 107.21],
[256.68, 123.23],
[241.10, 139.31],
[263.37, 139.54]
],
"pose_angle": {
"angle": "profile_right",
"confidence": 0.9,
"pitch": "neutral",
"features": {
"nose_to_eye_ratio": 0.5793,
"eye_width": 29.52,
"eye_slope": 0.0134,
"nose_offset_x": 5.42,
"mouth_symmetry": 0.7874
}
}
}
```
### 31帧统计
```
Total faces: 31
Pose distribution: {
three_quarter: 17 (55%),
profile_right: 11 (35%),
profile_left: 3 (10%)
}
Confidence avg: 0.87 ✅
```

184
docs_v1.0/EXPERIMENT_REPORTS/ONE_TO_MANY_MATCHING_OPTIMIZATION_2026-04-28.md Normal file
View File

@@ -0,0 +1,184 @@
# 1对多参考向量架构优化报告
> 测试日期: 2026-04-28
> 测试版本: V1.0
> 测试对象: Preview Test Person Identity
---
## 实验概述
本实验验证 **1对多参考向量架构** 的匹配效果，对比不同策略和阈值：
1. **Combined 策略权重优化**: 从 {0.5, 0.3, 0.2} → {0.7, 0.2, 0.1}
2. **阈值对比测试**: 0.85, 0.80, 0.75
3. **策略对比**: Best Match vs Combined
---
## 测试环境
| 配置 | 值 |
|------|-----|
| **Identity UUID** | 5ae2a1a2-0cd6-4007-971d-12b8e04be9be |
| **Identity Name** | Preview Test Person |
| **Reference Vectors** | 6 个 (质量 0.85-0.94) |
| **Angles Covered** | {unknown, profile_right} |
| **Faces to Match** | 31 (from preview.mp4) |
---
## 权重优化对比
### 原始权重 (V1)
```
final_score = best_match * 0.5 + vote_ratio * 0.3 + weighted_sim * 0.2
```
| 阈值 | Match Ratio |
|------|-------------|
| 0.85 | 0% ❌ |
| 0.80 | - |
| 0.75 | - |
**问题**: vote_ratio 和 weighted_sim 拉低了 final_score。
---
### 优化权重 (V2)
```
final_score = best_match * 0.7 + vote_ratio * 0.2 + weighted_sim * 0.1
```
| 阈值 | Match Ratio | 说明 |
|------|-------------|------|
| **0.85** | 9.68% (3/31) | 高精度 |
| **0.80** | 35.48% (11/31) | 平衡 |
| **0.75** | **45.16% (14/31)** ✅ | 接近 Best Match |
**改进**: 优化权重后，阈值 0.75 时 Match Ratio 达到 45.16%，接近 Best Match (48.39%)。
---
## 策略对比
| 策略 | 阈值 | Match Ratio | Final Score Range |
|------|------|-------------|------------------|
| **Best Match** | 0.85 | 48.39% (15/31) ✅ | 0.30 - 1.00 |
| **Combined (V2)** | 0.75 | 45.16% (14/31) ✅ | 0.24 - 0.94 |
| **Combined (V1)** | 0.85 | 0% ❌ | - |
---
## 详细分析
### Best Match 策略特点
| 特点 | 说明 |
|------|------|
| **优势** | 简单快速，Match Ratio 最高 |
| **劣势** | 单一参考向量匹配，鲁棒性低 |
| **适用场景** | 高质量参考向量 + 正面人脸 |
### Combined 策略特点
| 特点 | 说明 |
|------|------|
| **优势** | 多参考向量投票，鲁棒性高 |
| **劣势** | 计算成本稍高，阈值敏感 |
| **适用场景** | 多角度参考向量 + 变化人脸 |
---
## Top 5 Match Details (阈值 0.75)
| Match | Frame | Final Score | Best Match | Vote Ratio | Weighted Sim |
|-------|-------|-------------|-----------|-----------|--------------|
| 1 | 210 | 0.9427 | 1.0000 | 83.33% | 0.7602 |
| 2 | 190 | 0.9422 | 1.0000 | 83.33% | 0.7548 |
| 3 | 220 | 0.9419 | 1.0000 | 83.33% | 0.7525 |
| 4 | 260 | 0.9415 | 1.0000 | 83.33% | 0.7483 |
| 5 | 180 | 0.9392 | 1.0000 | 83.33% | 0.7256 |
---
## 推荐配置
### 高精度匹配
| 参数 | 值 |
|------|-----|
| **策略** | Best Match |
| **阈值** | 0.85 |
| **Match Ratio** | 48.39% |
### 平衡匹配
| 参数 | 值 |
|------|-----|
| **策略** | Combined |
| **权重** | {best_match: 0.7, vote_ratio: 0.2, weighted_sim: 0.1} |
| **阈值** | 0.80 |
| **Match Ratio** | 35.48% |
### 高鲁棒性匹配
| 参数 | 值 |
|------|-----|
| **策略** | Combined |
| **权重** | {best_match: 0.7, vote_ratio: 0.2, weighted_sim: 0.1} |
| **阈值** | 0.75 |
| **Match Ratio** | 45.16% ✅ |
---
## 使用方式
### 高精度匹配 (Best Match)
```bash
python3 scripts/match_face_identity.py \
--identity-name "Person Name" \
--face-json output/video.face.json \
--strategy best_match \
--threshold 0.85 \
--batch
```
### 高鲁棒性匹配 (Combined)
```bash
python3 scripts/match_face_identity.py \
--identity-name "Person Name" \
--face-json output/video.face.json \
--strategy combined \
--threshold 0.75 \
--weights "0.7,0.2,0.1" \
--batch
```
---
## 结论
✅ **1对多参考向量架构验证成功**
| 改进项 | 结果 |
|--------|------|
| **权重优化** | 从 0% → 45.16% (阈值 0.75) |
| **阈值调整** | 0.85 → 0.75 (Match Ratio 提升 36%) |
| **策略对比** | Combined 接近 Best Match |
**推荐配置**:
- **高精度**: Best Match + 阈值 0.85
- **高鲁棒性**: Combined + 权重 {0.7, 0.2, 0.1} + 阈值 0.75
---
## 版本信息
- 报告版本: V1.0
- 测试日期: 2026-04-28
- 测试状态: ✅ 成功

231
docs_v1.0/EXPERIMENT_REPORTS/POSE_BASED_MATCHING_FINAL_REPORT_2026-04-28.md Normal file
View File

@@ -0,0 +1,231 @@
# Pose-based Identity Matching 完整实验报告
> 实验日期: 2026-04-28
> 实验版本: V2.0 (Phase 1-4)
> 测试视频: preview.mp4 (15秒, 31帧人脸)
---
## 实验概述
本实验完整验证 **Pose-based Identity Matching 系统**，包括：
1. **Phase 1**: 角度分类算法优化 (多特征综合)
2. **Phase 2**: 自动多角度参考向量选择
3. **Phase 3**: Identity 注册优化
4. **Phase 4**: Pose-filtered Matching v2 (自适应阈值 + fallback)
---
## 实验结果对比
### 总体对比
| Strategy | Match Ratio | Confidence Avg | profile_right Similarity |
|----------|-------------|----------------|--------------------------|
| **Best Match** | 48.39% (15/31) | - | 0.08 ❌ |
| **Combined (优化权重)** | 9.68% (3/31) | - | - |
| **Pose-filtered V1** | 35.48% (11/31) | 0.87 | 0.08 ❌ |
| **Pose-filtered V2** | **41.94% (13/31)** ✅ | **0.87** | **0.8547** ✅ |
---
### Phase 1: Pose 分析器对比
| 指标 | V1 (单特征) | V2 (多特征) | 改进 |
|------|------------|------------|------|
| **Confidence Avg** | 0.70 | **0.87** | +0.17 ✅ |
| **profile_right 检测** | 1 帧 (3%) | **11 帧 (35%)** | +10 帧 ✅ |
| **three_quarter 分布** | 27 帧 (87%) | **17 帧 (55%)** | 更准确 ✅ |
**V2 多特征**:
- `nose_to_eye_ratio`
- `eye_slope` (仰视/俯视)
- `nose_offset_norm` (左/右侧脸)
- `mouth_symmetry`
- `jaw_visibility_hint`
---
### Phase 2: 参考向量选择对比
| Identity | Vectors | Angles Covered | Quality Avg | profile_right References |
|----------|---------|----------------|-------------|-------------------------|
| **V1** | 6 | {three_quarter, profile_left, profile_right} | - | **0** ❌ |
| **V2** | 6 | {three_quarter: 2, profile_left: 2, profile_right: 2} | **0.88** | **2** ✅ |
**关键改进**: V2 自动选择 2 个 profile_right 参考向量（质量 0.91）。
---
### Phase 4: 匹配策略对比
| Angle | V1 Similarity | V1 Threshold | V2 Similarity | V2 Threshold | V2 Match |
|-------|--------------|--------------|--------------|--------------|----------|
| **three_quarter** | 0.5154 | 0.85 | 0.5154 | **0.85** | 4/17 ✅ |
| **profile_right** | 0.0854 ❌ | 0.85 | **0.8547** ✅ | **0.80** | 7/11 ✅ |
| **profile_left** | 0.9987 | 0.85 | 0.9987 | **0.80** | 2/3 ✅ |
**自适应阈值**:
- `frontal`: 0.90 (最高精度)
- `three_quarter`: 0.85 (标准)
- `profile_left/right`: **0.80** (更宽容)
---
## 详细分析
### profile_right 改进 (关键成果)
| 指标 | Before | After | 改进 |
|------|--------|-------|------|
| **Reference Vectors** | 0 | **2** | +2 |
| **Avg Similarity** | 0.08 ❌ | **0.8547** | **+0.77** 🎉 |
| **Match Count** | 0 | **7/11** | +7 |
**原因**:
1. V2 Pose 分析器正确检测 11 个 profile_right 帧
2. 自动选择 2 个高质量 profile_right 参考向量
3. 自适应阈值 0.80 (更宽容)
---
### Angle Match Types
| Type | Count | 说明 |
|------|-------|------|
| **exact** | 31 (100%) | 所有匹配使用 exact angle |
| **fallback** | 0 | 无需 fallback ✅ |
**说明**: V2 参考向量覆盖了所有检测到的角度，无需 fallback。
---
## Top 5 Matches
| Match | Frame | Pose Angle | Similarity | Threshold | Match |
|-------|-------|-----------|-----------|-----------|-------|
| 1 | 220 | profile_right | **1.0000** | 0.80 | ✅ |
| 2 | 210 | profile_right | **1.0000** | 0.80 | ✅ |
| 3 | 260 | three_quarter | **1.0000** | 0.85 | ✅ |
| 4 | 270 | three_quarter | **1.0000** | 0.85 | ✅ |
| 5 | 310 | profile_left | **1.0000** | 0.80 | ✅ |
---
## 实施成果
### 创建的文件
| 文件 | 说明 | 功能 |
|------|------|------|
| `scripts/utils/pose_analyzer.py` | Pose 分析器 V2 | 多特征综合分类 |
| `scripts/select_face_reference_vectors_v2.py` | 自动参考向量选择 | 确保角度覆盖 |
| `scripts/match_face_with_pose_filtering.py` | Pose-filtered Matching V2 | 自适应阈值 + fallback |
| `docs/POSE_BASED_MATCHING_OPTIMIZATION_PLAN.md` | 优化方案规划 | 完整实施计划 |
---
### 数据库注册
| Identity | UUID | Angles | Quality Avg |
|----------|------|--------|-------------|
| **Preview Test Person V1** | `5ae2a1a2-...` | 3 angles | - |
| **Preview Test Person V2** | `4ce396fc-...` | **3 angles (balanced)** | **0.88** |
---
## 关键发现
### 1. Pose 分析关键
**V1 问题**: 仅用 nose-to-eye ratio，profile_right 检测 1 帧 (3%)
**V2 解决**: 多特征综合，profile_right 检测 11 帧 (35%)
### 2. 参考向量覆盖关键
**V1 问题**: profile_right 无参考向量 → similarity = 0.08
**V2 解决**: 自动选择 2 个 profile_right 参考向量 → similarity = 0.8547
### 3. 自适应阈值关键
**V1 问题**: 所有角度使用 0.85 → profile_right 匹配失败
**V2 解决**: profile 使用 0.80 → 7/11 匹配成功
---
## 推荐配置
### 高精度匹配 (推荐)
| 参数 | 值 |
|------|-----|
| **Pose Analyzer** | V2 (多特征) |
| **Reference Selection** | V2 (自动多角度) |
| **Matching Strategy** | pose_filtered_v2 |
| **Adaptive Threshold** | frontal=0.90, three_quarter=0.85, profile=0.80 |
### 使用方式
```bash
# Step 1: Pose 分析
python3 scripts/utils/pose_analyzer.py --face-json output/video.face.json
# Step 2: 自动选择参考向量
python3 scripts/select_face_reference_vectors_v2.py \
--face-json output/video.face.json \
--identity-name "Person Name" \
--register
# Step 3: Pose-filtered 匹配
python3 scripts/match_face_with_pose_filtering.py \
--identity-name "Person Name" \
--face-json output/video.face.json \
--strategy pose_filtered_v2 \
--batch
```
---
## 未来优化
| Phase | 任务 | 优先级 |
|-------|------|--------|
| **Phase 5** | 整合到生产流程 | 高 |
| **Phase 5.1** | Face Processor 输出 pose angle | 高 |
| **Phase 5.2** | Identity Registration API | 中 |
| **Phase 5.3** | Portal UI 显示 angle_coverage | 低 |
| **Phase 6** | Frontal 角度补充 | 中 |
---
## 结论
✅ **Pose-based Identity Matching 完整实施成功**
### 定量改进
| 指标 | Before | After | 改进 |
|------|--------|-------|------|
| **Match Ratio** | 35.48% | **41.94%** | +6.46% ✅ |
| **profile_right Similarity** | 0.08 | **0.8547** | **+0.77** 🎉 |
| **Pose Confidence** | 0.70 | **0.87** | +0.17 ✅ |
### 定性改进
- ✅ **多特征 Pose 分类**: 更准确的角度检测
- ✅ **自动多角度覆盖**: 确保 3-4 个角度覆盖
- ✅ **自适应阈值**: 不同角度使用不同阈值
- ✅ **Fallback 机制**: 支持无同角度向量时的 fallback
---
## 版本信息
- 实验版本: V2.0
- 实验日期: 2026-04-28
- 实验状态: ✅ Phase 1-4 完成
- 下一步: Phase 5 (生产流程整合)

351
docs_v1.0/FACE_THUMBNAIL_IMPLEMENTATION.md Normal file
View File

@@ -0,0 +1,351 @@
# Face Thumbnail API 完整实现报告
> Date: 2026-04-28 21:50
> Status: ✅ 完成
---
## 实现内容
### 后端 API
**新增 Endpoint**: `/api/v1/faces/:face_id/thumbnail`
**功能**:
- 从 `face_detections` 表读取 bbox 和 frame_number
- 从 `videos` 表读取 file_path 和 fps
- 使用 ffmpeg 提取指定帧的人脸区域
- 返回 JPEG 图片（约 6KB）
---
## API 实现细节
### 路径参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `face_id` | i32 | face_detections.id |
### Response Headers
```
Content-Type: image/jpeg
Cache-Control: public, max-age=3600
Content-Length: ~6000 bytes
```
### ffmpeg 命令
```bash
ffmpeg -ss {timestamp} -i {video_path} \
-vf "crop={width}:{height}:{x}:{y}" \
-frames:v 1 -f image2pipe -vcodec mjpeg -
```
**参数说明**:
- `-ss`: 时间戳（frame_number / fps）
- `-i`: 视频路径（原始视频文件）
- `-vf crop`: 从 bbox 提取人脸区域
- `-frames:v 1`: 只提取一帧
- `-f image2pipe`: 输出到管道
- `-vcodec mjpeg`: JPEG 编码
---
## 代码变更
### identities.rs
**新增内容**:
1. **路由定义** (line 55):
```rust
.route("/api/v1/faces/:face_id/thumbnail", get(get_face_thumbnail))
```
1. **Handler 函数** (line 683-752):
```rust
async fn get_face_thumbnail(
Path(face_id): Path<i32>,
) -> Result<impl IntoResponse, (StatusCode, String)>
```
1. **Bbox 结构** (line 754-759):
```rust
#[derive(Debug, Deserialize)]
struct Bbox {
x: i32,
y: i32,
width: i32,
height: i32,
}
```
---
## 前端更新
### FaceCandidatesView.vue
**变更内容**:
1. **导入函数** (line 118):
```typescript
import { listFaceCandidates, getCurrentConfig } from '@/api/client'
```
1. **Thumbnail URL 函数** (line 138-142):
```typescript
const getThumbnailUrl = (faceId: number): string => {
const config = getCurrentConfig()
return `${config.api_base_url}/api/v1/faces/${faceId}/thumbnail`
}
```
1. **Error Handler** (line 144-150):
```typescript
const onThumbnailError = (event: Event) => {
const img = event.target as HTMLImageElement
img.style.display = 'none'
const parent = img.parentElement
if (parent) {
parent.innerHTML = '<div class="text-center p-4"><div class="text-2xl">👤</div></div>'
}
}
```
1. **Image 元素** (line 66-72):
```vue
<img
:src="getThumbnailUrl(face.id)"
alt="Face thumbnail"
class="w-full h-full object-cover"
loading="lazy"
@error="onThumbnailError"
/>
```
---
## 测试验证
### API 测试
**请求**:
```bash
curl -i "http://localhost:3003/api/v1/faces/11/thumbnail" \
-H "X-API-Key: muser_test_001"
```
**响应**:
```
HTTP/1.1 200 OK
content-type: image/jpeg
cache-control: public, max-age=3600
content-length: 5991
[JPEG binary data]
```
### 图片验证
| 属性 | 值 |
|------|-----|
| **文件大小** | 5991 bytes (约 6KB) |
| **格式** | JPEG (JFIF) |
| **编码器** | Lavc62.28.100 |
| **缓存时间** | 1 小时 |
---
## 数据流
```
FaceCandidatesView.vue
↓
getThumbnailUrl(11)
↓
http://localhost:3003/api/v1/faces/11/thumbnail
↓
get_face_thumbnail handler
↓
Query face_detections (id=11)
↓
Query videos (file_uuid=384b0ff44aaaa1f14cb2cd63b3fea966)
↓
frame_number: 1798, fps: 59.94
↓
timestamp: 1798 / 59.94 = 30.04 seconds
↓
bbox: {x:945, y:113, width:179, height:263}
↓
ffmpeg -ss 30.04 -i video.mov \
-vf "crop=179:263:945:113" \
-frames:v 1 -f image2pipe -vcodec mjpeg -
↓
JPEG output (5991 bytes)
↓
Return to frontend
↓
Display thumbnail
```
---
## 性能优化
### Caching
**Browser Cache**: `Cache-Control: public, max-age=3600`
- 浏览器缓存 1 小时
- 减少重复请求
**Lazy Loading**: `loading="lazy"`
- 延迟加载非可见图片
- 减少初始加载时间
### 图片大小
**平均大小**: 6KB per thumbnail
**41 candidates**: 约 246KB total
**加载时间**: < 2 seconds (parallel loading)
---
## 错误处理
### Thumbnail 加载失败
**前端处理**:
```typescript
@error="onThumbnailError"
```
**显示**: 👤 placeholder icon
### API 错误
| 错误类型 | HTTP Status | 处理 |
|----------|-------------|------|
| Face not found | 404 | 显示 placeholder |
| ffmpeg failed | 500 | 显示 placeholder |
| DB error | 500 | 显示 placeholder |
---
## 文件清单
| 文件 | 修改内容 |
|------|----------|
| `src/api/identities.rs` | Thumbnail API 实现 |
| `portal/src/views/FaceCandidatesView.vue` | 前端显示 |
| `portal/src/api/client.ts` | 已有 getCurrentConfig |
---
## 访问方式
### 浏览器直接访问
```
http://localhost:1420/faces/candidates
```
页面会显示：
- 41 个 face candidates
- 每个显示真实人脸缩略图
- Confidence, Gender, Age 属性
### API 直接测试
```
http://localhost:3003/api/v1/faces/11/thumbnail
```
返回 JPEG 图片
---
## 对比：Before vs After
### Before (Placeholder)
```vue
<div class="text-center p-4">
<div class="text-2xl mb-2">👤</div>
<div class="text-xs text-gray-500">Frame 1798</div>
</div>
```
### After (Real Thumbnail)
```vue
<img
:src="getThumbnailUrl(face.id)"
alt="Face thumbnail"
class="w-full h-full object-cover"
loading="lazy"
/>
```
---
## 今日完整工作清单
| 任务 | 状态 |
|------|------|
| **V4.0 Migration Phase 3** | ✅ |
| **UUID 清理** | ✅ |
| **Face Candidates API** | ✅ |
| **Identity Faces API** | ✅ |
| **Face Thumbnail API** | ✅ |
| **前端 UI 实现** | ✅ |
| **缩略图显示** | ✅ |
---
## 实现时间
| 模块 | 时间 |
|------|------|
| **后端 API** (3 个) | 20 分钟 |
| **前端 UI** | 15 分钟 |
| **Thumbnail 实现** | 15 分钟 |
| **验证测试** | 5 分钟 |
| **总计** | 55 分钟 |
---
## 下一步建议
### 演示流程
1. 刷新 Portal 页面
2. 点击导航栏 "Face Candidates"
3. 查看 41 个真实人脸缩略图
4. 选择 5 个高质量 candidates
5. 点击 "Register Identity"
### 待实现功能
| 功能 | 优先级 |
|------|--------|
| **Register Modal** | 高 |
| **Identity Faces Tab** | 高 |
| **Batch Select** | 中 |
| **Pose Filter** | 中 |
---
## 总结
✅ **Portal Face 演示功能完整实现**
- 41 个 candidates 显示真实缩略图
- API 响应时间 < 50ms
- 图片大小 ~6KB
- 浏览器缓存 1 小时
- Lazy loading 优化
**访问**: `http://localhost:1420/faces/candidates`

620
docs_v1.0/FACE_TRACKER_DATA_STRUCTURE.md Normal file
View File

@@ -0,0 +1,620 @@
# Face Tracker 记录内容详解
> 文件: face_traced.json
> 创建日期: 2026-04-28
> 更新: 2026-04-28 (添加 Pose Trace)
---
## 文件结构
```
face_traced.json
├── metadata # 元数据（新增 trace_stats）
│ ├── video_path
│ ├── fps
│ ├── width/height
│ ├── total_frames
│ ├── trace_stats # 新增：追踪统计
│ │ ├── total_traces
│ │ ├── active_traces
│ │ └── long_traces
│ └── ...
├── frames # 所有帧的人脸数据
│ ├── "30": { # 帧 30
│ │ ├── frame_number
│ │ ├── time_seconds
│ │ ├── faces # 该帧的人脸列表
│ │ │ ├── face[0]
│ │ │ │ ├── x, y, width, height
│ │ │ │ ├── confidence
│ │ │ │ ├── embedding
│ │ │ │ ├── landmarks
│ │ │ │ ├── pose_angle
│ │ │ │ ├── attributes
│ │ │ │ └── trace_id # 新增：追踪 ID
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── traces # 新增：所有 trace 的汇总
├── "0": { # Trace 0
│ ├── trace_id
│ ├── start_frame
│ ├── end_frame
│ ├── duration_frames
│ ├── duration_seconds
│ ├── total_appearances
│ ├── avg_confidence
│ ├── pose_angles # Pose 变化序列（简化）
│ ├── pose_trace # 新增：完整 Pose 信息
│ ├── pose_statistics # 新增：Pose 统计
│ ├── pose_transitions # 新增：Pose 变化事件
│ └── path # 详细路径
├── "2": { ... }
└── "3": { ... }
```
---
## 一、frames 中的新增字段
### 1.1 trace_id
**位置**: `frames[frame_num].faces[i].trace_id`
**说明**: 每个人脸新增 `trace_id` 字段，标识该人脸属于哪个追踪轨迹。
**示例**:
```json
{
"faces": [
{
"x": 209,
"y": 71,
"width": 70,
"height": 89,
"confidence": 0.8778,
"embedding": [512-dim vector],
"landmarks": [[x1, y1], ...],
"pose_angle": {"angle": "profile_right", ...},
"attributes": {"age": 31, "gender": "male"},
"trace_id": 2 // 新增字段
}
]
}
```
**用途**:
- 区分视频中不同人物的人脸
- 从特定 trace_id 选择参考向量
- 分析人物在不同帧的连续性
---
## 二、metadata.trace_stats
**位置**: `metadata.trace_stats`
**说明**: 追踪统计摘要。
**结构**:
```json
{
"total_traces": 4, // 总共分配的 trace_id 数量
"active_traces": 4, // 活跃 trace 数量
"long_traces": 3 // 长追踪数量（>= 2 帧）
}
```
**示例（preview.mp4）**:
```
Total traces: 4
- Trace 0: frames 1-146
- Trace 1: frame 147 (单帧)
- Trace 2: frames 155-297
- Trace 3: frames 298-329
Long traces: 3 (Trace 0, 2, 3)
Short trace: 1 (Trace 1, 仅 1 帧)
```
---
## 三、traces 结构
### 3.1 Trace 基础字段
| 字段 | 类型 | 说明 |
|------|------|------|
| **trace_id** | int | 唯一追踪 ID |
| **start_frame** | int | 首次出现帧号 |
| **end_frame** | int | 最后出现帧号 |
| **duration_frames** | int | 持续帧数 |
| **duration_seconds** | float | 持续时间（秒） |
| **total_appearances** | int | 总出现次数 |
| **avg_confidence** | float | 平均检测置信度 |
**示例**:
```json
{
"trace_id": 2,
"start_frame": 155,
"end_frame": 297,
"duration_frames": 143,
"duration_seconds": 6.5,
"total_appearances": 143,
"avg_confidence": 0.8624
}
```
---
### 3.2 pose_angles（Pose 变化序列 - 简化）
**类型**: `list[string]`
**说明**: 该 trace 所有帧的 pose_angle 字符串序列（简化版本）。
**示例（Trace 2 前 10 帧）**:
```json
{
"pose_angles": [
"profile_right", // frame 155
"profile_right", // frame 156
"profile_right", // frame 157
"profile_right", // frame 158
"profile_right", // frame 159
"profile_right", // frame 160
"profile_right", // frame 161
"profile_right", // frame 162
"profile_right", // frame 163
"profile_right", // frame 164
... // 共 143 个
]
}
```
**用途**:
- 快速查看 pose 变化趋势
- 统计 pose distribution
---
### 3.3 pose_trace（完整 Pose 信息）⭐ 新增
**类型**: `list[dict]`
**说明**: 该 trace 每一帧的完整 pose 信息（包含 confidence, pitch, features）。
**结构**:
```json
{
"pose_trace": [
{
"frame": 155, // 帧号
"angle": "profile_right", // Pose 类型
"confidence": 0.75, // Pose 置信度
"pitch": "neutral", // Pitch 类型（tilted_up/tilted_down/neutral）
"features": { // Pose 特征（10 个）
"nose_to_eye_ratio": 0.5924,
"eye_width": 29.52,
"nose_to_eye_dist": 17.13,
"eye_slope": 0.0292,
"eye_angle_deg": 1.67,
"nose_offset_x": 5.75,
"nose_offset_norm": 0.1956,
"mouth_symmetry": 0.7839,
"mouth_width": 22.67,
"jaw_visibility_hint": 1.0
}
},
{
"frame": 156,
"angle": "profile_right",
"confidence": 0.75,
"pitch": "neutral",
"features": {...}
},
... // 共 143 个
]
}
```
**用途**:
- 详细分析 pose confidence 变化
- 分析 pitch 变化（仰视/俯视）
- 提取 pose features 进行深度分析
---
### 3.4 pose_statistics（Pose 统计）⭐ 新增
**类型**: `dict`
**说明**: 该 trace 的 pose 统计信息。
**结构**:
```json
{
"pose_statistics": {
"distribution": { // Pose 分布
"profile_right": 125,
"three_quarter": 18
},
"avg_confidence_by_angle": { // 各 pose 平均置信度
"profile_right": 0.895,
"three_quarter": 0.85
},
"dominant_angle": "profile_right", // 主导 pose
"pose_count": 2 // pose 类型数量
}
}
```
**示例分析（Trace 2）**:
```
Dominant Angle: profile_right (87%)
Avg Confidence:
profile_right: 0.895 ✅ (高质量)
three_quarter: 0.85 ✅ (高质量)
Pose Count: 2 (仅 2 种 pose)
```
**用途**:
- 快速了解 pose 分布
- 评估 pose 稳定性（pose_count 少 = 更稳定）
- 选择高质量 pose 的参考向量
---
### 3.5 pose_transitions（Pose 变化事件）⭐ 新增
**类型**: `list[dict]`
**说明**: 该 trace 中 pose 类型变化的事件列表。
**结构**:
```json
{
"pose_transitions": [
{
"frame": 173, // 变化发生的帧号
"from_angle": "profile_right", // 原 pose
"to_angle": "three_quarter", // 新 pose
"transition_index": 1 // 变化序号
},
{
"frame": 174,
"from_angle": "three_quarter",
"to_angle": "profile_right",
"transition_index": 2
},
... // 共 8 个
]
}
```
**示例（Trace 2）**:
```
Frame 173: profile_right → three_quarter
Frame 174: three_quarter → profile_right (立即恢复)
Frame 177: profile_right → three_quarter
Frame 188: three_quarter → profile_right
...
共 8 个 transitions
```
**用途**:
- 分析 pose 变化时机
- 计算 transition frequency
- 评估 pose stability
---
### 3.6 path（详细路径）
**类型**: `list[dict]`
**说明**: 该 trace 每一帧的详细信息（bbox, confidence, pose_full）。
**结构**:
```json
{
"path": [
{
"frame": 155, // 帧号
"face_index": 0, // 人脸索引
"bbox": { // 边界框
"x": 196,
"y": 79,
"width": 64,
"height": 82
},
"confidence": 0.8067, // 检测置信度
"pose_angle": "profile_right", // Pose 类型（简化）
"pose_full": {...} // 完整 pose 信息（新增）
},
{
"frame": 156,
"face_index": 0,
"bbox": {"x": 206, "y": 77, "width": 65, "height": 83},
"confidence": 0.8280,
"pose_angle": "profile_right",
"pose_full": {...}
},
... // 共 143 个
]
}
```
**用途**:
- 追踪人脸移动轨迹（bbox 变化）
- 分析置信度变化
- 绘制 trace path 可视化
---
## 四、完整示例
### 4.1 Trace 2 完整数据
```json
{
"2": {
"trace_id": 2,
"start_frame": 155,
"end_frame": 297,
"duration_frames": 143,
"duration_seconds": 6.5,
"total_appearances": 143,
"avg_confidence": 0.8624,
"pose_angles": [
"profile_right", "profile_right", ..., // 125 个 profile_right
"three_quarter", "three_quarter", ... // 18 个 three_quarter
],
"path": [
{"frame": 155, "bbox": {...}, "confidence": 0.8067, "pose_angle": "profile_right"},
{"frame": 156, "bbox": {...}, "confidence": 0.8280, "pose_angle": "profile_right"},
... // 143 个路径点
]
}
}
```
---
### 4.2 Face 数据对比
| 字段 | face.json (无 trace) | face_traced.json (有 trace) |
|------|----------------------|----------------------------|
| **trace_id** | ❌ 无 | ✅ 添加 `trace_id: 2` |
| **pose_angle** | ✅ 有 | ✅ 有（不变） |
| **embedding** | ✅ 有 | ✅ 有（不变） |
| **confidence** | ✅ 有 | ✅ 有（不变） |
**新增字段**: 仅添加 `trace_id`，其他字段不变。
---
## 五、数据用途
### 5.1 Trace 统计分析
| 分析维度 | 数据来源 |
|----------|----------|
| **人物持续时间** | `duration_seconds` |
| **人物置信度** | `avg_confidence` |
| **Pose 分布** | `pose_angles` → 统计 |
| **轨迹移动** | `path` → bbox 变化 |
**示例分析**:
```
Trace 2:
Duration: 6.5 seconds
Confidence: 0.862 ✅ (高质量)
Pose: profile_right (87%), three_quarter (13%)
Movement: x 196→209, y 79→72 (稳定)
```
---
### 5.2 参考向量选择
**使用 trace_id 过滤**:
```python
# 仅选择 Trace 2 的人脸
for face in faces:
if face["trace_id"] == 2:
selected_vectors.append(face["embedding"])
```
**优势**:
- 确保参考向量来自同一人物
- 避免 embedding 混合（不同人物）
- 选择高质量 trace（avg_confidence > 0.85）
---
### 5.3 可视化
**路径可视化** (`face_trace_visualizer.py`):
- X Position vs Frame
- Y Position vs Frame
- Confidence vs Frame
- Pose Distribution
**输出**:
- PNG: `face_trace_visualization.png`
- CSV: `face_trace_stats.csv`
---
## 六、数据大小估算
### 6.1 文件大小
| 内容 | 大小估算 |
|------|----------|
| **embedding (512-dim)** | 512 × 4 bytes = 2 KB per face |
| **landmarks (5 × 2)** | 10 × 8 bytes = 80 bytes per face |
| **path (简化)** | ~100 bytes per path entry |
| **trace (汇总)** | ~200 bytes per trace |
**示例（preview.mp4）**:
```
Frames: 322
Faces per frame: 1
Total faces: 322
face.json size: ~650 KB
face_traced.json size: ~750 KB (+ trace data)
```
---
### 6.2 内存占用
| Trace ID | Path Entries | Pose Angles | 占用 |
|----------|--------------|-------------|------|
| **0** | 146 | 146 | ~30 KB |
| **2** | 143 | 143 | ~30 KB |
| **3** | 32 | 32 | ~7 KB |
| **Total** | 321 | 321 | ~67 KB |
---
## 七、数据完整性检查
### 7.1 Trace Gap 检测
```python
# 检查 trace 之间的 gap
for i in range(len(traces) - 1):
gap = next_trace.start - curr_trace.end - 1
if gap > 0:
print(f"Gap: {gap} frames (无人脸检测)")
```
**示例**:
```
Gap between Trace 1 and 2: 7 frames (frames 148-154)
```
**说明**: frames 148-154 无人脸检测（可能人物离开画面）。
---
### 7.2 Trace Quality 评估
| Trace | Avg Confidence | Quality |
|-------|----------------|---------|
| **0** | 0.76 | ⚠️ 中等 |
| **2** | 0.86 | ✅ 高质量 |
| **3** | 0.69 | ⚠️ 较低 |
**建议**:
- 选择 avg_confidence > 0.85 的 trace
- 过滤 avg_confidence < 0.7 的 trace
---
## 九、Pose Transition Analysis ⭐ 新增
### 9.1 功能说明
**脚本**: `scripts/utils/pose_transition_analyzer.py`
**功能**:
1. 分析 pose 变化频率（transition_frequency）
2. 计算 pose 稳定性分数（stability_score）
3. 识别 pose segments（连续 pose 区段）
4. 可视化 pose timeline
---
### 9.2 Stability Score
**定义**: `stability_score = 1.0 - min(transition_frequency / 2.0, 1.0)`
| Stability Score | 说明 |
|-----------------|------|
| **0.8-1.0** | ✅ 高稳定性（< 0.4 transitions/second） |
| **0.5-0.8** | ⚠️ 中稳定性（0.4-1.0 transitions/second） |
| **0-0.5** | ❌ 低稳定性（> 1.0 transitions/second） |
---
### 9.3 Trace Stability 对比
| Trace | Transitions | Frequency | Stability Score | 评价 |
|-------|-------------|-----------|-----------------|------|
| **0** | 2 | 0.301/s | **0.849** | ✅ 高稳定 |
| **2** | 8 | 1.231/s | **0.385** | ⚠️ 低稳定 |
| **3** | 0 | 0.0/s | **1.0** | ✅ 完全稳定 |
**分析**:
- **Trace 0**: 仅 2 次变化（frame 122, 124），高稳定
- **Trace 2**: 8 次变化，频繁切换 pose，低稳定
- **Trace 3**: 无变化，完全稳定（单一 pose）
---
### 9.4 Pose Segments
**说明**: 将连续相同 pose 的帧合并为一个 segment。
**示例（Trace 2）**:
```
Segment 1: profile_right (frames 155-172, 18 frames, avg_confidence: 0.883)
Segment 2: three_quarter (frames 173-173, 1 frame, avg_confidence: 0.85) ← 短暂变化
Segment 3: profile_right (frames 174-176, 3 frames, avg_confidence: 0.90)
Segment 4: three_quarter (frames 177-187, 11 frames, avg_confidence: 0.85)
Segment 5: profile_right (frames 188-258, 71 frames, avg_confidence: 0.90) ← 最长稳定
...
共 9 个 segments
```
**用途**:
- 识别最长稳定 pose 区段
- 选择高质量 segment 的参考向量
- 分析 pose 持续时间
---
### 9.5 使用方式
```bash
# 分析 pose transitions
python3 scripts/utils/pose_transition_analyzer.py \
--face-json video.face_traced.json \
--output-plot pose_transition_visualization.png \
--output-json pose_transition_analysis.json
```
---
### 9.6 输出文件
| 文件 | 内容 |
|------|------|
| **PNG** | Pose timeline 可视化（每个 trace 一行） |
| **JSON** | Transition analysis 结果（stability_score, segments, etc.） |
---
## 十、参考文档
| 文件 | 说明 |
|------|------|
| `scripts/utils/face_tracker.py` | 追踪脚本 |
| `scripts/utils/face_trace_visualizer.py` | 可视化脚本 |
| `scripts/select_face_reference_vectors_v3.py` | Trace-based 选择 |
| `docs_v1.0/FACE_TRACKER_GUIDE.md` | 使用指南 |
---
## 版本信息
- 版本: 1.0
- 创建日期: 2026-04-28
- 状态: ✅ Face Tracker 记录说明完成

261
docs_v1.0/FACE_TRACKER_GUIDE.md Normal file
View File

@@ -0,0 +1,261 @@
# Face Tracker 功能文档
> 创建日期: 2026-04-28
> 脚本路径: `scripts/utils/face_tracker.py`
---
## 功能概述
**Face Tracker** 追踪视频中同一人脸在不同帧之间的连续性，为每个人脸分配唯一的 `trace_id`。
---
## 核心功能
### 1. 人脸追踪
| 功能 | 说明 |
|------|------|
| **trace_id 分配** | 每个追踪的人脸获得唯一 ID |
| **跨帧匹配** | 使用 bbox IoU + embedding similarity |
| **路径记录** | 记录人脸位置、置信度、pose 变化 |
### 2. 匹配算法
```
匹配条件（优先级）:
1. bbox IoU > 0.3 AND embedding similarity > 0.7 → 最佳匹配
2. bbox IoU > 0.5 → 位置匹配
3. embedding similarity > 0.85 → 高置信度匹配
4. distance < 100 AND similarity > 0.6 → fallback 匹配
```
---
## 使用方式
### 基础用法
```bash
# 追踪人脸
python3 scripts/utils/face_tracker.py \
--face-json output/video.face.json \
--output output/video.face_traced.json
# 仅分析（不输出）
python3 scripts/utils/face_tracker.py \
--face-json output/video.face.json \
--analyze-only
```
### 参数调整
```bash
# 调整匹配阈值
python3 scripts/utils/face_tracker.py \
--face-json output/video.face.json \
--iou-threshold 0.4 \
--similarity-threshold 0.75 \
--distance-threshold 80
# 禁用 embedding 匹配（仅使用位置）
python3 scripts/utils/face_tracker.py \
--face-json output/video.face.json \
--no-embedding
```
---
## 输出结构
### 1. face.json 结构变化
**Before**:
```json
{
"frames": {
"210": {
"faces": [
{"x": 208, "y": 71, "embedding": [...], "pose_angle": {...}}
]
}
}
}
```
**After**:
```json
{
"frames": {
"210": {
"faces": [
{
"x": 208,
"y": 71,
"embedding": [...],
"pose_angle": {...},
"trace_id": 2 // 新增
}
]
}
},
"traces": { // 新增
"2": {
"trace_id": 2,
"start_frame": 155,
"end_frame": 297,
"duration_frames": 143,
"duration_seconds": 6.5,
"total_appearances": 143,
"avg_confidence": 0.862,
"pose_angles": ["profile_right", ...],
"path": [
{"frame": 155, "bbox": {...}, "confidence": 0.87, "pose_angle": "profile_right"},
...
]
}
},
"metadata": { // 新增统计
"trace_stats": {
"total_traces": 4,
"active_traces": 4,
"long_traces": 3
}
}
}
```
### 2. traces 结构详解
| 字段 | 说明 |
|------|------|
| **trace_id** | 唯一追踪 ID |
| **start_frame** | 首次出现帧号 |
| **end_frame** | 最后出现帧号 |
| **duration_frames** | 持续帧数 |
| **duration_seconds** | 持续时间（秒） |
| **total_appearances** | 总出现次数 |
| **avg_confidence** | 平均检测置信度 |
| **pose_angles** | Pose 变化序列 |
| **path** | 详细路径（bbox, confidence, pose） |
---
## 可视化工具
### face_trace_visualizer.py
```bash
# 生成可视化图表 + CSV
python3 scripts/utils/face_trace_visualizer.py \
--face-json output/video.face_traced.json \
--output-plot output/face_trace_visualization.png \
--output-csv output/face_trace_stats.csv
```
### 输出图表
| 图表 | 说明 |
|------|------|
| **X Position** | 人脸 X 坐标随时间变化 |
| **Y Position** | 人脸 Y 坐标随时间变化 |
| **Confidence** | 检测置信度随时间变化 |
| **Pose Distribution** | 各 trace 的 pose 分布 |
---
## 实测案例
### preview.mp4 (15秒, 329帧)
| Trace | Frames | Duration | Appearances | Avg Confidence | Pose Distribution |
|-------|--------|----------|-------------|----------------|-------------------|
| **0** | 1-146 | 6.64s | 146 | 0.76 | three_quarter (144), profile_left (2) |
| **1** | 147 | 0.05s | 1 | - | single appearance |
| **2** | 155-297 | 6.50s | 143 | 0.86 | profile_right (125), three_quarter (18) |
| **3** | 298-329 | 1.45s | 32 | 0.69 | profile_left (32) |
**分析结论**:
- Trace 0: 主要人物 A（前半段）
- Trace 2: 主要人物 B（后半段，高置信度）
- Trace 3: 主要人物 C（结尾，侧脸）
- Gap: frames 148-154 (7帧无人脸检测)
---
## 应用场景
| 场景 | 用途 |
|------|------|
| **Identity Registration** | 从 longest trace 选择参考向量 |
| **Person Tracking** | 追踪视频中的人物轨迹 |
| **Scene Analysis** | 分析人物在不同场景的出现 |
| **Quality Control** | 识别低置信度 trace（需重新处理） |
---
## 与 Identity Registration 整合
### 建议流程
```bash
# Step 1: Face detection + pose
python3 scripts/face_processor.py video.mp4 video.face.json --sample-interval 1
# Step 2: Face tracking
python3 scripts/utils/face_tracker.py --face-json video.face.json --output video.face_traced.json
# Step 3: Select reference vectors from longest trace
python3 scripts/select_face_reference_vectors_v2.py \
--face-json video.face_traced.json \
--trace-id-filter 2 \
--identity-name "Person Name" \
--register
```
### trace-id-filter 逻辑
仅从指定 trace_id 的人脸中选择参考向量：
- 确保同一人物的多角度参考
- 避免不同人物的 embedding 混合
- 选择 longest trace 作为主要 identity
---
## 参数优化建议
| 场景 | 参数调整 |
|------|---------|
| **快速移动人脸** | `--distance-threshold 150` (更宽容) |
| **低质量视频** | `--similarity-threshold 0.65` (降低阈值) |
| **多人场景** | `--iou-threshold 0.5` (更严格位置匹配) |
| **稳定人脸** | 默认参数即可 |
---
## 未来改进
| Phase | 功能 | 优先级 |
|-------|------|--------|
| **Phase 1** | 基础追踪（已完成） | ✅ |
| **Phase 2** | 3D pose estimation | 中 |
| **Phase 3** | Multi-face interaction tracking | 低 |
| **Phase 4** | Real-time tracking API | 低 |
---
## 参考文档
- `scripts/utils/face_tracker.py`: 人脸追踪脚本
- `scripts/utils/face_trace_visualizer.py`: 可视化脚本
- `scripts/face_processor.py`: 人脸检测脚本
- `scripts/select_face_reference_vectors_v2.py`: 参考向量选择
---
## 版本信息
- 版本: 1.0
- 创建日期: 2026-04-28
- 状态: ✅ 已完成基础功能

208
docs_v1.0/FILE_UUID_SPEC.md Normal file
View File

@@ -0,0 +1,208 @@
# file_uuid 設計理念與規格
> Version: 1.0 | Date: 2026-04-30
> Architecture: Birth Identity Model (戶籍制度模型)
---
## 1. 核心概念
系統將每個媒體檔案視為一個「自然人」，擁有一個**終身不變的身份證字號** (`file_uuid`)。
| 戶籍概念 | 系統對應 | 說明 |
| :--- | :--- | :--- |
| **身分證字號** | `file_uuid` | 檔案的終身唯一標識，出生後永不變更 |
| **出生登記** | 首次 `register` | 檔案首次被系統納管，觸發分析處理 (ASR, Face, etc.) |
| **戶籍地** | `file_path` | 檔案當前存放位置，可隨搬家而變更 |
| **主管單位** | `MAC Address` | 核發身份的伺服器/機器，確保跨機器的管轄獨立 |
| **居住證申請時間** | `registration_time` | 檔案在該管轄單位登記的時間戳記 |
---
## 2. file_uuid 生成公式
```text
file_uuid = SHA256( MAC_Address | Birthday | Canonical_Path | Filename )[0:32]
```
### 設計原則
| 原則 | 說明 |
| :--- | :--- |
| **唯一性** | 同一台機器上，相同路徑與檔名只會產生一個 UUID |
| **穩定性** | **生日 (Birthday)** 是身份錨點。如果檔案在原地重新註冊，系統會找回原始生日，確保 UUID 不變 |
| **管轄獨立** | 不同機器的 MAC 不同，確保跨伺服器身份獨立 |
| **路徑綁定** | **Canonical Path** 參與計算。檔案移動到新路徑會產生新 UUID（視為新環境下的註冊） |
| **隱私保護** | 所有元素經 Hash 處理，無法反推出原始資訊 |
### 關鍵元素
| 元素 | 說明 |
| :--- | :--- |
| `Birthday` | 首次註冊的時間戳記。系統會透過檔名查詢資料庫，找回原始生日，確保身份連續 |
| `Canonical Path` | 檔案的絕對路徑。確保位置的唯一性 |
| `Filename` | 檔案名稱 |
---
## 3. 生命週期
### 3.1 出生 (Birth / 首次納管)
當檔案首次被系統發現並執行 `register` 時：
```
1. 取得本机 MAC Address
2. 讀取 Filename
3. 查詢資料庫：是否有同檔名 (Filename) 的紀錄？
├─ 有紀錄 → 取出其 registration_time 作為「生日 (Birthday)」
└─ 無紀錄 → 使用 NOW() 作為「生日 (Birthday)」
4. 計算 file_uuid = SHA256(MAC | Birthday | Canonical_Path | Filename)[0:32]
5. 檢查 DB 是否已存在該 UUID
├─ 已存在 → 拒絕重複登記 (已有出生紀錄)
└─ 不存在 → 建立新生紀錄
6. 記錄 registration_time (居住證申請時間)
```
**出生後**：`file_uuid` 即成為該檔案的終身身份，不可更改。
### 3.2 搬家 (Move / 路徑變更)
當檔案從 `/data/demo/` 移動到 `/archive/2024/` 時：
```
1. 檔案路徑變更 (Canonical Path 改變)
2. 系統以新 Path 計算 UUID → 產生新 UUID
3. 查詢 DB → 找不到該 UUID (視為新身份)
4. 但若檔名相同，會查詢到舊的「生日 (Birthday)」
5. 執行動作：
├─ 建立新紀錄 (新 UUID，新路徑)
├─ 使用原始的 Birthday (保持血緣關係)
└─ 可選擇是否繼承舊紀錄的分析結果
```
**關鍵邏輯**：
- 路徑改變 = 新環境 = 新 UUID
- 但透過 **Birthday 查詢機制**，系統知道這是同一個「人」搬到了新家
### 3.3 跨機器遷移 (Cross-Machine)
當檔案從 Server-A 複製到 Server-B 時：
```
Server-A (MAC: aa:bb:cc:dd:ee:ff):
file_uuid = SHA256("aa:bb:cc:dd:ee:ff|Birthday|/path|video.mp4") → "abc123..."
Server-B (MAC: 11:22:33:44:55:66):
file_uuid = SHA256("11:22:33:44:55:66|Birthday|/path|video.mp4") → "def456..."
```
- **結果**：兩台伺服器各自擁有獨立管轄權
- **意義**：各管各的戶口，互不干擾
---
## 4. 資料庫欄位定義
### videos 表
| 欄位 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| `file_uuid` | VARCHAR(32) | **身分證字號** (不可變) | `384b0ff44aaaa1f1...` |
| `file_path` | TEXT | **戶籍地址** (可變) | `/data/demo/video.mp4` |
| `file_name` | VARCHAR(255) | 原始檔名 | `video.mp4` |
| `registration_time` | TIMESTAMPTZ | **居住證申請時間** | `2026-04-30T02:00:00+08` |
| `birth_registration` | JSONB | 出生登記詳情 | 見下方結構 |
### birth_registration JSONB 結構
```json
{
"registration_source": {
"mac_address": "ba:f5:ee:bc:45:78",
"original_path": "/Users/accusys/momentry/var/sftpgo/data/demo",
"original_filename": "Old_Time_Movie_Show_-_Charade_1963.HD.mov",
"timestamp": "2026-04-29T02:25:14+08:00"
}
}
```
---
## 5. 代碼實作
### 5.1 UUID 計算 (`src/core/storage/uuid.rs`)
```rust
pub fn compute_birth_uuid(
mac_address: &str,
birthday: &str,
path: &str,
filename: &str,
) -> String {
let key = format!("{}|{}|{}|{}", mac_address, birthday, path, filename);
let hash = Sha256::digest(key.as_bytes());
hex::encode(hash)[0..32].to_string()
}
```
### 5.2 註冊流程 (`src/api/server.rs`)
```rust
// 1. 取得 MAC、路徑與檔名
let mac_address = get_mac_address();
let canonical_path = path.canonicalize()...;
let filename = path.file_name()...;
// 2. 查詢生日 (Identity Anchor)
// 以檔名查詢 DB，若有紀錄則使用原始生日，否則使用 NOW()
let birthday = db.find_birthday_by_filename(&filename).await.unwrap_or(now());
// 3. 計算穩定身份
let file_uuid = compute_birth_uuid(&mac_address, &birthday, &canonical_path, &filename);
// 4. 檢查是否已出生
if let Some(existing) = db.get_video_by_uuid(&file_uuid).await? {
if existing.registration_time.is_some() {
return Ok(already_exists_response);
}
}
// 5. 新生登記 + 觸發分析
db.register_video(&record).await?;
```
---
## 6. 情境對照表
| 情境 | file_uuid | file_path | Birthday | 觸發分析? | 說明 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **首次註冊** | 新生成 | 記錄當前路徑 | NOW() | ✅ 是 | 出生登記，全面納管 |
| **同一檔案再次註冊** | 相同 | 不變 | 原始 | ❌ 否 | 已有戶籍，拒絕重複 |
| **檔案移動到同機另一目錄** | **不同** | 新路徑 | 原始 | ✅ 是 | 新位置視為新環境 |
| **檔案複製到另一台伺服器** | 不同 | 記錄新路徑 | ✅ 是 | 新管轄區，獨立登記 |
| **檔名變更** | 不同 | 記錄新路徑 | ✅ 是 | 視為不同身份 |
| **檔案刪除後重新加入** | 相同 | 記錄新路徑 | ⚠️ 視情況 | 若 DB 紀錄仍存在，可恢復關聯 |
---
## 7. 設計優勢
1. **身份錨點**：透過 Birthday 機制，即使路徑改變，系統仍能識別檔案的歷史血緣
2. **路徑綁定**：UUID 包含 Canonical Path，確保每個位置的檔案都有獨立身份，避免混淆
3. **管轄清晰**：MAC Address 確保每台伺服器的數據獨立
4. **可追溯性**：`birth_registration` 記錄原始出處與 Birthday，便於審計
5. **防止重複**：系統以 UUID 為準，同一位置同一檔案絕不會重複登記
---
## 8. 相關文件
| 文件 | 說明 |
| :--- | :--- |
| `src/core/storage/uuid.rs` | UUID 生成實作 |
| `src/api/server.rs` | 註冊端點與流程 |
| `src/core/ingestion.rs` | Watcher 自動 ingestion 邏輯 |
| `docs_v1.0/UUID_LENGTH_ISSUE.md` | 舊版 UUID 長度問題分析 |
| `docs_v1.0/UUID_CLEANUP_PLAN.md` | 歷史數據清理方案 |

811
docs_v1.0/IDENTITY_API_SPEC.md Normal file
View File

@@ -0,0 +1,811 @@
# Identity API Specification
> Version: V4.0 | Date: 2026-04-28
> Architecture: Two-layer (Face → Identity)
> Base URL: `http://localhost:3003/api/v1`
---
## Overview
| Category | Count | Description |
|----------|-------|-------------|
| **List API** | 6 | One-to-many queries |
| **Candidates API** | 2 | Unregistered face candidates |
| **Suggest API** | 2 | AI clustering suggestions |
| **Detail API** | 2 | Single item detail |
| **Register/Bind API** | 3 | Identity management operations |
| **Total** | **15** | Core endpoints |
---
## Terminology
| Term | Type | Description |
|------|------|-------------|
| **file_uuid** | UUID | Video file identifier |
| **identity_uuid** | UUID | Global identity identifier |
| **face_id** | string | Single face detection |
| **trace_id** | int | Face tracking ID |
| **chunk_id** | string | Sentence chunk ID |
---
## Pagination Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | 1 | Page number (>=1) |
| `page_size` | int | 15 | Items per page (1-100) |
| `limit` | int | null | Total items limit |
| `search` | string | null | Search query |
| `sort` | string | created_at | Sort field |
| `order` | string | DESC | Sort direction (ASC/DESC) |
---
## Response Format
### List API Response
```json
{
"success": true,
"data": {
"[items]": [...],
"pagination": {
"page": 1,
"page_size": 15,
"total": 100,
"total_pages": 7,
"limit": null
}
}
}
```
### Detail API Response
```json
{
"success": true,
"data": {
"[item]": {...}
}
}
```
### Error Response
```json
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Identity not found",
"details": {}
}
}
```
---
## 1. List API (One-to-Many)
---
### 1.1 GET /api/v1/files
List all files.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `limit` | int | No | null |
| `search` | string | No | null |
| `status` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files?page=1&page_size=15" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"files": [
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"duration": 6879.33,
"status": "completed",
"total_identities": 5,
"total_faces": 800,
"created_at": "2026-04-28T10:00:00Z"
}
],
"pagination": {
"page": 1,
"page_size": 15,
"total": 100,
"total_pages": 7
}
}
}
```
---
### 1.2 GET /api/v1/identities
List all identities.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `limit` | int | No | null |
| `search` | string | No | null |
| `source` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities?page=1&page_size=15" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identities": [
{
"identity_uuid": "a9a90105-6d6b-...",
"name": "Audrey Hepburn",
"source": "manual",
"total_files": 3,
"total_faces": 1500,
"reference_vectors": {
"total": 4,
"angles": ["frontal", "profile_right"]
},
"created_at": "2026-04-28T10:00:00Z"
}
],
"pagination": {
"page": 1,
"page_size": 15,
"total": 50,
"total_pages": 4
}
}
}
```
---
### 1.3 GET /api/v1/identities/:identity_uuid/files
List files where identity appears (N:N relationship).
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `identity_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `status` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../files" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"files": [
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"face_count": 500,
"speaker_count": 10,
"first_appearance": 5.2,
"last_appearance": 180.5,
"confidence": 0.86
}
],
"total_files": 2
}
}
```
---
### 1.4 GET /api/v1/files/:file_uuid/identities
List identities in a file (N:N relationship).
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `file_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `status` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/identities" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"identities": [
{
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"face_count": 500,
"speaker_count": 10,
"confidence": 0.86
}
],
"total_identities": 5
}
}
```
---
### 1.5 GET /api/v1/identities/:identity_uuid/faces
List faces bound to an identity.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `identity_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 100 |
| `limit` | int | No | 1000 |
| `pose_angle` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../faces?page_size=100" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"faces": [
{
"face_id": "face_100",
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"frame": 100,
"timestamp": 5.2,
"pose_angle": "frontal",
"confidence": 0.92,
"trace_id": 2
}
],
"total_faces": 1500,
"pose_distribution": {
"frontal": 400,
"profile_right": 300
}
}
}
```
---
### 1.6 GET /api/v1/identities/:identity_uuid/chunks
List chunks bound to an identity.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `identity_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 50 |
| `limit` | int | No | 500 |
| `speaker_id` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../chunks" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"chunks": [
{
"chunk_id": "chunk_1",
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"text": "Hello, how are you?",
"start_time": 5.2,
"end_time": 8.5,
"speaker_id": "SPEAKER_0"
}
],
"total_chunks": 30,
"speaker_ids": ["SPEAKER_0"],
"total_duration": 45.5
}
}
```
---
## 2. Candidates API (Unregistered)
---
### 2.1 GET /api/v1/faces/candidates
List unregistered faces (identity_id = NULL).
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `file_uuid` | UUID | No | null |
| `min_confidence` | float | No | 0.5 |
| `pose_angle` | string | No | null |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `limit` | int | No | 100 |
**Request**:
```bash
curl "http://localhost:3003/api/v1/faces/candidates?min_confidence=0.8&pose_angle=frontal" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"candidates": [
{
"face_id": "face_100",
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"frame": 100,
"timestamp": 5.2,
"pose_angle": "frontal",
"confidence": 0.92,
"trace_id": 2,
"embedding_quality": 0.88
}
],
"statistics": {
"total_candidates": 78,
"pose_distribution": {
"frontal": 20,
"profile_right": 30
},
"avg_confidence": 0.85
},
"pagination": {
"page": 1,
"page_size": 15,
"total": 78,
"total_pages": 6
}
}
}
```
---
### 2.2 GET /api/v1/files/:file_uuid/faces/candidates
List unregistered faces in a specific file.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `file_uuid` | UUID | Yes | - |
| `min_confidence` | float | No | 0.5 |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/faces/candidates" \
-H "X-API-Key: YOUR_KEY"
```
---
## 3. Suggest API (AI Agent)
---
### 3.1 POST /api/v1/agents/suggest/clustering
AI clustering suggestions for unregistered faces.
**Request Body**:
```json
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"min_confidence": 0.8,
"pose_angles": ["frontal"],
"clustering_threshold": 0.85,
"max_suggestions": 5
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/agents/suggest/clustering" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"min_confidence": 0.8, "max_suggestions": 5}'
```
**Response**:
```json
{
"success": true,
"data": {
"suggestions": [
{
"suggestion_id": "suggest_1",
"cluster_type": "high_confidence",
"confidence": 0.92,
"recommended_faces": [
{
"face_id": "face_100",
"pose_angle": "frontal",
"confidence": 0.95,
"is_primary": true
}
],
"cluster_stats": {
"total_faces": 50,
"avg_similarity": 0.89,
"trace_ids": [2, 3]
},
"reason": "High confidence frontal faces from same trace",
"action": "register"
}
],
"analysis_summary": {
"total_candidates": 78,
"potential_clusters": 5,
"suggested_actions": {
"register": 3,
"bind": 2
}
}
}
}
```
---
### 3.2 POST /api/v1/agents/suggest/merge
AI merge suggestions for identities.
**Request Body**:
```json
{
"identity_uuids": ["a9a90105...", "b8b80206..."],
"threshold": 0.85
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/agents/suggest/merge" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"identity_uuids": ["a9a90105...", "b8b80206..."]}'
```
**Response**:
```json
{
"success": true,
"data": {
"suggestions": [
{
"suggestion_type": "merge",
"confidence": 0.88,
"identities": [
{"identity_uuid": "a9a90105...", "name": "Person A", "face_count": 500},
{"identity_uuid": "b8b80206...", "name": "Person B", "face_count": 300}
],
"reason": "High embedding similarity (0.88)",
"recommended_action": {
"merge_target": "a9a90105...",
"merge_sources": ["b8b80206..."]
}
}
]
}
}
```
---
## 4. Detail API (One-to-One)
---
### 4.1 GET /api/v1/identities/:identity_uuid
Identity detail.
**Parameters**:
| Parameter | Type | Required |
|-----------|------|----------|
| `identity_uuid` | UUID | Yes |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105..." \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"source": "manual",
"identity_type": "person",
"global_stats": {
"total_files": 3,
"total_faces": 1500,
"total_speaker_segments": 30
},
"reference_vectors": {
"total": 4,
"angles": ["frontal", "profile_right"],
"quality_avg": 0.875
},
"created_at": "2026-04-28T10:00:00Z"
}
}
```
---
### 4.2 GET /api/v1/files/:file_uuid
File detail.
**Parameters**:
| Parameter | Type | Required |
|-----------|------|----------|
| `file_uuid` | UUID | Yes |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"duration": 6879.33,
"status": "completed",
"identity_stats": {
"total_identities": 5,
"identities": [
{"identity_uuid": "a9a90105...", "name": "Audrey Hepburn", "face_count": 500}
]
}
}
}
```
---
## 5. Register/Bind API
---
### 5.1 POST /api/v1/identities/register
Register new identity from faces.
**Request Body**:
```json
{
"face_ids": ["face_100", "face_150", "face_200"],
"name": "Audrey Hepburn",
"source": "manual",
"auto_bind_chunks": true
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/identities/register" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
"face_ids": ["face_100"],
"name": "Audrey Hepburn",
"auto_bind_chunks": true
}'
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105-...",
"name": "Audrey Hepburn",
"faces_bound": 3,
"chunks_bound": 10,
"speaker_ids": ["SPEAKER_0"],
"reference_vectors": {
"total": 3,
"angles": ["frontal"]
}
}
}
```
---
### 5.2 POST /api/v1/identities/:identity_uuid/bind
Bind additional faces to existing identity.
**Request Body**:
```json
{
"face_ids": ["face_300", "face_400"],
"auto_bind_chunks": true
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/identities/a9a90105.../bind" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"face_ids": ["face_300"]}'
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"faces_bound": 1,
"chunks_bound": 3
}
}
```
---
### 5.3 POST /api/v1/identities/:identity_uuid/unbind
Unbind faces from identity.
**Request Body**:
```json
{
"face_ids": ["face_400"]
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/identities/a9a90105.../unbind" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"face_ids": ["face_400"]}'
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"faces_unbound": 1
}
}
```
---
## 6. Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| `NOT_FOUND` | 404 | Resource not found |
| `BAD_REQUEST` | 400 | Invalid request |
| `UNAUTHORIZED` | 401 | Invalid API key |
| `INTERNAL_ERROR` | 500 | Server error |
| `VALIDATION_ERROR` | 422 | Validation failed |
---
## 7. Authentication
All endpoints require API key in header:
```bash
-H "X-API-Key: YOUR_API_KEY"
```
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Two-layer architecture, 15 core endpoints |
| V3.x | 2026-04-10 | 33 endpoints (many deprecated) |
---
## Deprecated Endpoints (V3.x → V4.0)
| Endpoint | Status | Replacement |
|----------|--------|--------------|
| `/api/v1/person/list` | ❌ Removed | `/api/v1/faces/candidates` |
| `/api/v1/person/:id` | ❌ Removed | `/api/v1/identities/:uuid` |
| `/api/v1/person/merge` | ❌ Removed | `/api/v1/agents/suggest/merge` |
| `/api/v1/person/:id/split` | ❌ Removed | Manual face re-binding |
| `/api/v1/chunks/candidates` | ❌ Removed | Chunks auto-bind |
| **26 more person APIs** | ❌ Removed | See above replacements |

2
docs_v1.0/IMPLEMENTATION/AI_AGENT_DOCUMENTATION_GUIDE.md
View File

@@ -446,4 +446,4 @@ def test_search_documents():
**版本**: V1.0 **版本**: V1.0
**適用對象**: 所有 AI Agent 和自動化工具 **適用對象**: 所有 AI Agent 和自動化工具
**注意**: 本文檔應與實際模板文件結合使用，定期更新以反映系統變更。 **注意**: 本文檔應與實際模板文件結合使用，定期更新以反映系統變更。

2
docs_v1.0/IMPLEMENTATION/API_CURL_EXAMPLES.md
View File

@@ -46,7 +46,7 @@ ai_query_hints:
## 目錄 ## 目錄
1. [已實作端點](#1-已實作端點) 1. [已實作端點](#1-已實作端點)
2. [API Key 管理](#2-api-key-管理-規劃中) 2. [API Key 管理](#2-api-key-管理)
3. [影片管理](#3-影片管理) 3. [影片管理](#3-影片管理)
4. [查詢與搜索](#4-查詢與搜索) 4. [查詢與搜索](#4-查詢與搜索)
5. [系統狀態](#5-系統狀態) 5. [系統狀態](#5-系統狀態)

2
docs_v1.0/IMPLEMENTATION/API_TRAINING_MARCOM.md
View File

@@ -196,7 +196,7 @@ n8n 專用搜尋（包含完整影片檔案路徑 file_path）
```json ```json
{ {
"uuid": "9760d0820f0cf9a7", "uuid": "9760d0820f0cf9a7",
"video_uuid": "5dea6618a606e7c7", "file_uuid": "5dea6618a606e7c7",
"status": "completed", "status": "completed",
"progress": 100, "progress": 100,
"created_at": "2026-03-25T10:00:00Z", "created_at": "2026-03-25T10:00:00Z",

2
docs_v1.0/IMPLEMENTATION/CONTINUOUS_DEMO_GUIDE.md
View File

@@ -368,4 +368,4 @@ Q - 退出
**更新日期**: 2026-04-02 **更新日期**: 2026-04-02
**版本**: 2.0.0 **版本**: 2.0.0
**作者**: Momentry Team **作者**: Momentry Team

2
docs_v1.0/IMPLEMENTATION/DEMO_GUIDE.md
View File

@@ -394,4 +394,4 @@ brew install ffmpeg
**創建日期**: 2026-04-02 **創建日期**: 2026-04-02
**版本**: 1.1.0 **版本**: 1.1.0
**作者**: Momentry Team **作者**: Momentry Team

2
docs_v1.0/IMPLEMENTATION/DEMO_MODES.md
View File

@@ -219,4 +219,4 @@ A: 兩種模式都按實際時長播放。說話人演示有 2 秒暫停。
**更新日期**: 2026-04-02 **更新日期**: 2026-04-02
**版本**: 2.1.0 **版本**: 2.1.0
**作者**: Momentry Team **作者**: Momentry Team

2
docs_v1.0/IMPLEMENTATION/DEMO_VIDEO_MODE.md
View File

@@ -219,4 +219,4 @@ A:
**更新日期**: 2026-04-02 **更新日期**: 2026-04-02
**版本**: 1.2.0 **版本**: 1.2.0
**作者**: Momentry Team **作者**: Momentry Team

199
docs_v1.0/IMPLEMENTATION/DEV_3003_REFACTOR.md Normal file
View File

@@ -0,0 +1,199 @@
# Dev 3003 改造記錄
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-04-30 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-30 | Dev 3003 全面改造 | Warren | OpenCode |
---
## 1. 改造目標
- 將 Dev 3003 (Playground) 與 Public 3002 完全隔離
- 統一術語：`video_uuid` → `file_uuid`
- 修復資料庫結構問題（probe_json 類型、timestamp 類型）
- Python 腳本和 output 目錄隔離
---
## 2. PostgreSQL Schema 修復
### 2.1 probe_json 類型修復
**問題**: `dev.videos.probe_json` 類型為 `TEXT`，但 Rust 期望 `JSONB`
**修復**:
```sql
ALTER TABLE dev.videos ALTER COLUMN probe_json TYPE jsonb USING probe_json::jsonb;
```
### 2.2 video_uuid → file_uuid 重命名 (10 張表)
| 表 | 狀態 |
|----|------|
| `dev.backup_registry` | ✅ 已重命名 |
| `dev.castings` | ✅ 已重命名 |
| `dev.characters` | ✅ 已重命名 |
| `dev.face_identities` | ✅ 已重命名 |
| `dev.face_recognition_results` | ✅ 已重命名 |
| `dev.file_lifecycle` | ✅ 已重命名 |
| `dev.file_registry` | ✅ 已重命名 |
| `dev.processor_results` | ✅ 已重命名 |
| `dev.video_events` | ✅ 已重命名 |
| `dev.video_identities` | ✅ 已重命名 |
**修復 SQL**:
```sql
ALTER TABLE dev.backup_registry RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.castings RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.characters RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.face_identities RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.face_recognition_results RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.file_lifecycle RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.file_registry RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.processor_results RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.video_events RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.video_identities RENAME COLUMN video_uuid TO file_uuid;
-- 重建 constraint
ALTER TABLE dev.face_recognition_results
DROP CONSTRAINT face_recognition_results_video_uuid_key;
ALTER TABLE dev.face_recognition_results
ADD CONSTRAINT face_recognition_results_file_uuid_key UNIQUE (file_uuid);
```
### 2.3 timestamp 類型修復
**問題**: `dev.videos.created_at`, `updated_at`, `registered_at` 為 `TIMESTAMP` (without time zone)，但 Rust 期望 `TIMESTAMPTZ`
**修復**:
```sql
ALTER TABLE dev.videos ALTER COLUMN created_at TYPE timestamptz USING created_at AT TIME ZONE 'UTC';
ALTER TABLE dev.videos ALTER COLUMN updated_at TYPE timestamptz USING updated_at AT TIME ZONE 'UTC';
ALTER TABLE dev.videos ALTER COLUMN registered_at TYPE timestamptz USING registered_at AT TIME ZONE 'UTC';
```
---
## 3. Rust 代碼修改
### 3.1 `src/api/server.rs`
| 行號 | 修改前 | 修改後 |
|------|--------|--------|
| 3982 | `DELETE FROM {} WHERE video_uuid = $1` | `DELETE FROM {} WHERE file_uuid = $1` |
### 3.2 `src/api/face_recognition.rs`
| 行號 | 修改前 | 修改後 |
|------|--------|--------|
| 721 | `WHERE video_uuid = $1` | `WHERE file_uuid = $1` |
| 764 | `"video_uuid": file_uuid` | `"file_uuid": file_uuid` |
| 786 | `video_uuid: &str` (參數) | `file_uuid: &str` (參數) |
| 807 | `ON CONFLICT (video_uuid)` | `ON CONFLICT (file_uuid)` |
| 818 | `.bind(video_uuid)` | `.bind(file_uuid)` |
| 877 | `.bind(video_uuid)` | `.bind(file_uuid)` |
| 926 | `.bind(video_uuid)` | `.bind(file_uuid)` |
### 3.3 測試修復
| 檔案 | 修改 |
|------|------|
| `src/core/db/postgres_db.rs:4550` | 添加 `file_type: None` 到 `VideoRecord` 測試 |
---
## 4. Python 腳本隔離
### 4.1 更新預設 DATABASE_URL (7 個腳本)
| 腳本 | 修改 |
|------|------|
| `scripts/clip_logo_integration.py` | `?options=-c%20search_path=dev` |
| `scripts/match_face_with_pose_filtering.py` | `?options=-c%20search_path=dev` |
| `scripts/select_face_reference_vectors_v2.py` | `?options=-c%20search_path=dev` |
| `scripts/match_face_identity.py` | `?options=-c%20search_path=dev` |
| `scripts/tmdb_identity_integration.py` | `?options=-c%20search_path=dev` |
| `scripts/select_face_reference_vectors.py` | `?options=-c%20search_path=dev` |
| `scripts/test_identity_db.py` | `?options=-c%20search_path=dev` |
### 4.2 output 目錄隔離
| 腳本 | 修改 |
|------|------|
| `scripts/identity_agent.py` | 預設 output 改為 `/Users/accusys/momentry/output_dev` |
### 4.3 環境變數配置
`.env.development` 已配置：
```bash
MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output_dev
DATABASE_SCHEMA=dev
MONGODB_DATABASE=momentry_dev
QDRANT_COLLECTION=momentry_dev_rule1
REDIS_PREFIX=momentry_dev:
```
---
## 5. 隔離狀態總覽
| 資源 | 配置 | 狀態 |
|------|------|------|
| PostgreSQL | `DATABASE_SCHEMA=dev` | ✅ 隔離 |
| MongoDB | `momentry_dev` | ✅ 隔離 |
| Qdrant | `momentry_dev_rule1` | ✅ 隔離 |
| Redis | `momentry_dev:` | ✅ 隔離 |
| Output Dir | `/Users/accusys/momentry/output_dev` | ✅ 隔離 |
---
## 6. 驗證結果
### 6.1 Build 驗證
- `cargo build --bins`: ✅ 成功
- `cargo clippy --lib`: ✅ 通過 (119 warnings, 0 errors)
- `cargo test --lib`: ✅ 178 tests passed
### 6.2 API 驗證
- `GET /api/v1/files`: ✅ 返回 200 (之前返回 500)
- 測試數據: 6 個檔案已註冊
---
## 7. 待辦事項
| 任務 | 優先級 | 狀態 |
|------|--------|------|
| 設計 Dev 3003 API 結構 (v1.0 aligned) | Medium | ⬜ |
| 實作 `GET /api/v1/files/{uuid}/identities` | Medium | ⬜ |
| 實作 `GET /api/v1/identities/{uuid}` | Medium | ⬜ |
| 實作 `GET /api/v1/identities/{uuid}/files` | Medium | ⬜ |
| 實作 AI Agent API (clustering/merge suggestions) | Medium | ⬜ |
---
## 8. 注意事項
### 8.1 Public 3002 不受影響
- 所有修改僅限於 `dev` schema
- `public` schema 保持原狀
- Rust 代碼修改適用於兩者，但 SQL 中的 column name 已統一為 `file_uuid`
### 8.2 Python 腳本注意事項
- 仍有其他 Python 腳本使用 `DB_CONFIG`、`POSTGRES_CONFIG` 等模式
- 這些腳本需單獨檢查和更新
- 建議逐步遷移至使用環境變數
### 8.3 已知限制
- Player module 仍使用 `video_uuid` 變數名（內部使用，不影響 API）
- 部分 Python 腳本的 output 路徑仍需手動指定

198
docs_v1.0/IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md
View File

@@ -2,13 +2,13 @@
document_type: "design" document_type: "design"
title: "File / Identity API 架構設計" title: "File / Identity API 架構設計"
service: "MOMENTRY_CORE" service: "MOMENTRY_CORE"
date: "2026-04-25" date: "2026-04-28"
status: "active" status: "active"
current_state: "finalized" current_state: "finalized"
owner: "Warren" owner: "Warren"
created_by: "OpenCode" created_by: "OpenCode"
created_at: "2026-04-25" created_at: "2026-04-25"
version: "V1.1" version: "V1.2"
tags: tags:
- "api" - "api"
- "file" - "file"
@@ -16,6 +16,9 @@ tags:
- "face" - "face"
- "candidate" - "candidate"
- "pre_chunk" - "pre_chunk"
- "reference_data"
- "identity_embedding"
- "clip"
related_documents: related_documents:
- "DOCS_STANDARD.md" - "DOCS_STANDARD.md"
- "AI_AGENT_DOCUMENTATION_GUIDE.md" - "AI_AGENT_DOCUMENTATION_GUIDE.md"
@@ -24,11 +27,14 @@ related_documents:
- "_deprecated/IDENTITY_SYSTEM_DESIGN.md" - "_deprecated/IDENTITY_SYSTEM_DESIGN.md"
- "PROCESSORS/_CORE/RULE_SPECIFICATION.md" - "PROCESSORS/_CORE/RULE_SPECIFICATION.md"
- "REFERENCE/API_ERROR_CODES.md" - "REFERENCE/API_ERROR_CODES.md"
- "IDENTITY_REFERENCE_VECTOR_DESIGN.md"
ai_query_hints: ai_query_hints:
- "查詢 File/Identity 核心架構設計" - "查詢 File/Identity 核心架構設計"
- "查詢 People API 端點定義" - "查詢 People API 端點定義"
- "查詢 Candidate 狀態轉換流程" - "查詢 Candidate 狀態轉換流程"
- "查詢資料庫 Schema 定義 (含 pre_chunks)" - "查詢資料庫 Schema 定義 (含 pre_chunks)"
- "查詢 reference_data JSONB 結構"
- "查詢 identity_embedding (CLIP ViT-L/14)"
--- ---
# File / Identity API 架構設計文件 # File / Identity API 架構設計文件
@@ -45,6 +51,7 @@ ai_query_hints:
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 | | 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------| |------|------|------|--------|-----------|
| V1.2 | 2026-04-28 | **重大更新**: 添加 face_embedding(512), voice_embedding(192), identity_embedding(768), reference_data JSONB 結構詳解, identity_type 扩展 (logo/symbol/sound/animal/environmental) | OpenCode | OpenCode |
| V1.1 | 2026-04-25 | **重大更新**: 移除 faces 表 (方案 A), 新增 pre_chunks 表, 統一命名為 file_uuid, 更新 Response 格式 | OpenCode | OpenCode | | V1.1 | 2026-04-25 | **重大更新**: 移除 faces 表 (方案 A), 新增 pre_chunks 表, 統一命名為 file_uuid, 更新 Response 格式 | OpenCode | OpenCode |
| V1.0 | 2026-04-25 | 創建 File/Identity API 架構設計 | OpenCode | OpenCode | | V1.0 | 2026-04-25 | 創建 File/Identity API 架構設計 | OpenCode | OpenCode |
@@ -91,9 +98,9 @@ Identity ──[出現在]──→ File (通過 Pre-chunk 或 file_identities
``` ```
**Candidate 狀態轉換**: **Candidate 狀態轉換**:
* **定義**: Candidate 不是獨立表格，而是 `pre_chunks` 中 `identity_id IS NULL` 的 Face 數據。 * **定義**: Candidate 不是獨立表格，而是 `pre_chunks` 中 `identity_id IS NULL` 的 Face 數據。
* **確認**: 更新 `identity_id` → 成為已確認身份。 * **確認**: 更新 `identity_id` → 成為已確認身份。
* **剔除**: 將 `identity_id` 設回 `NULL` → 重新成為 Candidate。 * **剔除**: 將 `identity_id` 設回 `NULL` → 重新成為 Candidate。
--- ---
@@ -132,8 +139,8 @@ CREATE TABLE files (
### Pre-chunks 表 (處理器原始數據) ### Pre-chunks 表 (處理器原始數據)
**說明**: 所有 Processor (YOLO, Face, ASR...) 產出的數據皆存於此表。 **說明**: 所有 Processor (YOLO, Face, ASR...) 產出的數據皆存於此表。
* **Video File**: 最小單位為 **Frame (幀)** (`coordinate_type = 'frame'`)。 * **Video File**: 最小單位為 **Frame (幀)** (`coordinate_type = 'frame'`)。
* **Text File**: 最小單位為 Word/Sentence (`coordinate_type = 'text'`)。 * **Text File**: 最小單位為 Word/Sentence (`coordinate_type = 'text'`)。
| 欄位 | 類型 | 必填 | 說明 | | 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------| |------|------|------|------|
@@ -174,10 +181,13 @@ CREATE INDEX idx_pre_chunks_identity ON pre_chunks(identity_id) WHERE identity_i
|------|------|------|------| |------|------|------|------|
| identity_id | UUID | Yes | 唯一識別 (自動產生) | | identity_id | UUID | Yes | 唯一識別 (自動產生) |
| name | TEXT | Yes | 顯示名稱 | | name | TEXT | Yes | 顯示名稱 |
| identity_type | VARCHAR(30) | Yes | people, brand, object, concept, logo... | | identity_type | VARCHAR(30) | Yes | people, brand, object, concept, logo, symbol, sound, animal, environmental... |
| source | VARCHAR(20) | No | manual, tmdb, agent_suggested, ai_detection | | source | VARCHAR(20) | No | manual, tmdb, agent_suggested, ai_detection |
| status | VARCHAR(20) | No | pending, confirmed, skipped | | status | VARCHAR(20) | No | pending, confirmed, skipped |
| reference_data | JSONB | No | 參考數據 (face_embedding, voice_embedding, image_url...) | | face_embedding | VECTOR(512) | No | 參考臉向量 (ArcFace) - 用於人臉比對 |
| voice_embedding | VECTOR(192) | No | 參考聲紋向量 (ECAPA-TDNN) - 用於聲音比對 |
| identity_embedding | VECTOR(768) | No | 身份向量 (CLIP ViT-L/14) - 用於 logo/symbol/object 搜索 |
| reference_data | JSONB | No | 1對多參考向量存儲 (多角度/多場景/多版本 embedding) |
| metadata | JSONB | No | 擴展屬性 | | metadata | JSONB | No | 擴展屬性 |
| created_at | TIMESTAMPTZ | Yes | 建立時間 | | created_at | TIMESTAMPTZ | Yes | 建立時間 |
| updated_at | TIMESTAMPTZ | Yes | 更新時間 | | updated_at | TIMESTAMPTZ | Yes | 更新時間 |
@@ -189,13 +199,115 @@ CREATE TABLE identities (
identity_type VARCHAR(30) NOT NULL, identity_type VARCHAR(30) NOT NULL,
source VARCHAR(20) DEFAULT 'manual', source VARCHAR(20) DEFAULT 'manual',
status VARCHAR(20) DEFAULT 'pending', status VARCHAR(20) DEFAULT 'pending',
reference_data JSONB DEFAULT '{}',
-- 參考向量 (用於自動比對)
face_embedding VECTOR(512), -- 參考臉向量 (ArcFace)
voice_embedding VECTOR(192), -- 參考聲紋向量 (ECAPA-TDNN)
identity_embedding VECTOR(768), -- 身份向量 (CLIP ViT-L/14)
-- 1對多參考向量存儲
reference_data JSONB DEFAULT '{}', -- 多角度/多場景/多版本 embedding
metadata JSONB DEFAULT '{}', metadata JSONB DEFAULT '{}',
created_at TIMESTAMPTZ DEFAULT NOW(), created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW() updated_at TIMESTAMPTZ DEFAULT NOW()
); );
``` ```
#### reference_data JSONB 結構詳解
`reference_data` 用於存儲同一 Identity 的多個參考向量，支援 1對多匹配，提高識別鲁棒性。
**完整結構範例**:
```json
{
"face_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "tmdb_images",
"image_url": "https://image.tmdb.org/t/p/original/xxx.jpg",
"angle": "frontal",
"quality_score": 0.95,
"created_at": "2026-04-28T10:00:00Z"
},
{
"embedding": [0.3, 0.4, ...],
"source": "tmdb_images",
"image_url": "https://image.tmdb.org/t/p/original/yyy.jpg",
"angle": "profile_left",
"quality_score": 0.88,
"created_at": "2026-04-28T10:05:00Z"
}
],
"voice_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "video_segment",
"file_uuid": "vid_001",
"timestamp_start": 120.5,
"timestamp_end": 135.2,
"quality_score": 0.88,
"created_at": "2026-04-28T11:00:00Z"
}
],
"identity_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "logo_image",
"image_url": "https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png",
"context": "brand_logo",
"created_at": "2026-04-28T12:00:00Z"
}
],
"sound_embeddings": [
{
"embedding": [0.1, 0.2, ...],
"source": "audio_segment",
"file_uuid": "vid_001",
"timestamp_start": 10.0,
"timestamp_end": 15.0,
"sound_type": "animal_dog_bark",
"created_at": "2026-04-28T13:00:00Z"
}
],
"image_urls": [
"https://image.tmdb.org/t/p/original/xxx.jpg",
"https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png"
]
}
```
**欄位說明**:
| 欄位 | 類型 | 說明 |
|------|------|------|
| face_embeddings | Array | 多個 512-dim ArcFace embedding (不同角度/定妝造型) |
| voice_embeddings | Array | 多個 192-dim ECAPA-TDNN embedding (不同音質片段) |
| identity_embeddings | Array | 多個 768-dim CLIP ViT-L/14 embedding (logo/symbol/object) |
| sound_embeddings | Array | TBD - 動物叫聲、雷雨、槍炮、樂器 (Phase 5+) |
| image_urls | Array | 參考圖片 URL 列表 |
**子欄位說明**:
| 欄位 | 類型 | 說明 |
|------|------|------|
| embedding | Array | 向量值 |
| source | String | 來源: tmdb_profile, tmdb_images, manual_upload, auto_detection, logo_image, audio_segment |
| image_url | String | 圖片 URL (face/identity) |
| file_uuid | UUID | 檔案 UUID (voice/sound) |
| timestamp_start/end | Float | 時間範圍 (voice/sound) |
| angle | String | 人臉角度: frontal, profile_left, profile_right, three_quarter |
| quality_score | Float | 質量評分 (0.0-1.0) |
| context | String | 識別場景: brand_logo, symbol, object, concept |
| sound_type | String | 聲音類型: animal_dog_bark, environmental_thunder, weapon_gunshot, musical_guitar |
| created_at | String | 建立時間 |
**設計理念**:
1. **1對多匹配**: 同一 Identity 可有多個參考向量，提高識別鲁棒性
2. **多角度覆蓋**: 人臉正面、側面、三側角度，覆蓋不同拍攝角度
3. **多場景覆蓋**: Logo/Symbol 在不同場景（白底、黑底、複雜背景）的 embedding
4. **質量評分**: 記錄每個參考向量的質量，用於加權匹配
5. **來源追溯**: 記錄每個 embedding 的來源，方便追溯和更新
### File-Identities 表 (關聯表 - 用於記錄聚合後的結果或特定角色資訊) ### File-Identities 表 (關聯表 - 用於記錄聚合後的結果或特定角色資訊)
**說明**: 用於記錄 Identity 在 File 中的**整體出現資訊** (如：角色名、定妝造型描述)。 **說明**: 用於記錄 Identity 在 File 中的**整體出現資訊** (如：角色名、定妝造型描述)。
@@ -471,43 +583,43 @@ WHERE id = 1001;
### Phase 0: 系統備份 (立即執行) ### Phase 0: 系統備份 (立即執行)
- [ ] 備份現有 PostgreSQL 資料庫 * [ ] 備份現有 PostgreSQL 資料庫
- [ ] 備份現有程式碼 * [ ] 備份現有程式碼
- [ ] 記錄現有版本 * [ ] 記錄現有版本
### Phase 1: 建立新資料庫 Schema ### Phase 1: 建立新資料庫 Schema
- [ ] 建立 `files`, `identities`, `pre_chunks` 表 * [ ] 建立 `files`, `identities`, `pre_chunks` 表
- [ ] 建立 `file_identities`, `categories` 表 * [ ] 建立 `file_identities`, `categories` 表
- [ ] 建立索引 * [ ] 建立索引
- [ ] 建立測試資料 * [ ] 建立測試資料
### Phase 2: 核心 API 實作 ### Phase 2: 核心 API 實作
- [ ] Candidates API (`GET /people/candidates`) - 查詢 `identity_id IS NULL` * [ ] Candidates API (`GET /people/candidates`) - 查詢 `identity_id IS NULL`
- [ ] Identity CRUD API (`GET/POST/PATCH /people`) * [ ] Identity CRUD API (`GET/POST/PATCH /people`)
- [ ] Identity Search API (`POST /people/search`) * [ ] Identity Search API (`POST /people/search`)
- [ ] Identity Resolve API (`GET /people/{id}/resolve`) * [ ] Identity Resolve API (`GET /people/{id}/resolve`)
- [ ] Candidate Management (`POST /people/{id}/confirm-candidate`, `remove-candidate`) * [ ] Candidate Management (`POST /people/{id}/confirm-candidate`, `remove-candidate`)
- [ ] Status API (`GET /people/status`) * [ ] Status API (`GET /people/status`)
### Phase 3: Processor 整合 (Pre-chunk 寫入) ### Phase 3: Processor 整合 (Pre-chunk 寫入)
- [ ] 修改 YOLO, Face, OCR 處理器，改寫入 `pre_chunks` 表 * [ ] 修改 YOLO, Face, OCR 處理器，改寫入 `pre_chunks` 表
- [ ] 實作 `PROCESSOR_RESUME_STRATEGY.md` 中的 Checkpoint 邏輯 * [ ] 實作 `PROCESSOR_RESUME_STRATEGY.md` 中的 Checkpoint 邏輯
- [ ] probe Processor 整合 (ffprobe → File 分類) * [ ] probe Processor 整合 (ffprobe → File 分類)
### Phase 4: Portal 前端 ### Phase 4: Portal 前端
- [ ] Candidates 介面 * [ ] Candidates 介面
- [ ] Identity 管理介面 * [ ] Identity 管理介面
- [ ] File 管理介面 * [ ] File 管理介面
### Phase 5: 非 People Identity (待辦事項) ### Phase 5: 非 People Identity (待辦事項)
- [ ] Brand Identity 支援 * [ ] Brand Identity 支援
- [ ] Object Identity 支援 * [ ] Object Identity 支援
- [ ] Concept Identity 支援 * [ ] Concept Identity 支援
--- ---
@@ -526,24 +638,24 @@ WHERE id = 1001;
## 限制條件 ## 限制條件
- 本設計為全新架構，不與現有系統共用資料 * 本設計為全新架構，不與現有系統共用資料
- 需要做新的處理器版本產生新的輸出 (寫入 `pre_chunks` 而非 `chunks`) * 需要做新的處理器版本產生新的輸出 (寫入 `pre_chunks` 而非 `chunks`)
- 非 People Identity 列入待辦事項，不在本次實作範圍 * 非 People Identity 列入待辦事項，不在本次實作範圍
- Face 的唯一識別為 `file_uuid` + `coordinate_index` (Frame Number) * Face 的唯一識別為 `file_uuid` + `coordinate_index` (Frame Number)
--- ---
## 相關文件 ## 相關文件
- `docs_v1.0/STANDARDS/DOCS_STANDARD.md` - 文件創建規範 * `docs_v1.0/STANDARDS/DOCS_STANDARD.md` - 文件創建規範
- `docs_v1.0/ARCHITECTURE/` - 架構相關文件 * `docs_v1.0/ARCHITECTURE/` - 架構相關文件
- `docs_v1.0/PROCESSORS/_CORE/PROCESSOR_RESUME_STRATEGY.md` - 處理器續傳機制 * `docs_v1.0/PROCESSORS/_CORE/PROCESSOR_RESUME_STRATEGY.md` - 處理器續傳機制
- `docs_v1.0/PROCESSORS/_CORE/RULE_SPECIFICATION.md` - Rule 依賴與數據流定義 * `docs_v1.0/PROCESSORS/_CORE/RULE_SPECIFICATION.md` - Rule 依賴與數據流定義
--- ---
## 版本資訊 ## 版本資訊
- 版本: V1.1 * 版本: V1.2
- 建立日期: 2026-04-25 * 建立日期: 2026-04-25
- 文件更新: 2026-04-25 * 文件更新: 2026-04-28

2
docs_v1.0/IMPLEMENTATION/INSTALL_SYNONYM_FOREST.md
View File

@@ -1312,4 +1312,4 @@ cargo run --bin test_synonym_expansion
3. **技術支援**：Momentry Core 僅提供技術框架和格式支援，不提供同義詞資料。 3. **技術支援**：Momentry Core 僅提供技術框架和格式支援，不提供同義詞資料。
4. **更新維護**：客戶需自行維護和更新同義詞資源。 4. **更新維護**：客戶需自行維護和更新同義詞資源。
**使用前請務必確認您擁有合法使用同義詞林資源的權利。** **使用前請務必確認您擁有合法使用同義詞林資源的權利。**

7
docs_v1.0/IMPLEMENTATION/N8N_SEARCH_API_COMPARISON.md
View File

@@ -33,7 +33,7 @@ Momentry 提供四種搜尋 API，針對不同的情境進行優化。選擇正
"hits": [ "hits": [
{ {
"id": "sentence_0790", "id": "sentence_0790",
"vid": "384b0ff44aaaa1f1", "vid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"chunk_type": "sentence", "chunk_type": "sentence",
"start_frame": 187296, "start_frame": 187296,
"end_frame": 187356, "end_frame": 187356,
@@ -60,7 +60,7 @@ Momentry 提供四種搜尋 API，針對不同的情境進行優化。選擇正
"hits": [ "hits": [
{ {
"id": "sentence_0790", "id": "sentence_0790",
"vid": "384b0ff44aaaa1f1", "vid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"chunk_type": "sentence", "chunk_type": "sentence",
"start_frame": 187296, "start_frame": 187296,
"end_frame": 187356, "end_frame": 187356,
@@ -102,7 +102,7 @@ Momentry 提供四種搜尋 API，針對不同的情境進行優化。選擇正
"hits": [ "hits": [
{ {
"id": "sentence_0790", "id": "sentence_0790",
"vid": "384b0ff44aaaa1f1", "vid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"chunk_type": "sentence", "chunk_type": "sentence",
"start_frame": 187296, "start_frame": 187296,
"end_frame": 187356, "end_frame": 187356,
@@ -136,7 +136,6 @@ Momentry 提供四種搜尋 API，針對不同的情境進行優化。選擇正
| **快取機制** | MongoDB | MongoDB | MongoDB | MongoDB | | **快取機制** | MongoDB | MongoDB | MongoDB | MongoDB |
> **提示**: 如果 n8n 流程只需要知道「出現在哪裡」，不需要播放影片或詳細摘要，使用 `/api/v1/search/bm25` 會比向量搜尋更省資源且更快。 > **提示**: 如果 n8n 流程只需要知道「出現在哪裡」，不需要播放影片或詳細摘要，使用 `/api/v1/search/bm25` 會比向量搜尋更省資源且更快。
> **新增**: 所有向量搜尋 API 現在支援多維度搜尋 (Multi-Modal)，同時查詢 ASR、Face、Object (YOLO)、Scene 四個 Collection，自動合併去重後回傳。 > **新增**: 所有向量搜尋 API 現在支援多維度搜尋 (Multi-Modal)，同時查詢 ASR、Face、Object (YOLO)、Scene 四個 Collection，自動合併去重後回傳。
--- ---

56
docs_v1.0/IMPLEMENTATION/N8N_SEARCH_API_TECHNICAL_SPEC.md
View File

@@ -44,7 +44,7 @@ X-API-Key: muser_68600856036340bcafc01930eb4bd839
```json ```json
{ {
"query": "主角開車離開的場景", "query": "主角開車離開的場景",
"uuid": "384b0ff44aaaa1f1", "uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"limit": 5 "limit": 5
} }
``` ```
@@ -60,7 +60,7 @@ X-API-Key: muser_68600856036340bcafc01930eb4bd839
"hits": [ "hits": [
{ {
"id": "sentence_0790", "id": "sentence_0790",
"vid": "384b0ff44aaaa1f1", "vid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"start_frame": 187296, "start_frame": 187296,
"end_frame": 187356, "end_frame": 187356,
"fps": 59.94, "fps": 59.94,
@@ -103,36 +103,36 @@ X-API-Key: muser_68600856036340bcafc01930eb4bd839
為了讓開發者理解效能與資料來源，以下是 `/api/v1/n8n/search` (Vector) 的完整執行流程： 為了讓開發者理解效能與資料來源，以下是 `/api/v1/n8n/search` (Vector) 的完整執行流程：
### 步驟 1: 認證與快取 (Auth & Cache) ### 步驟 1: 認證與快取 (Auth & Cache)
1. **API Key 驗證**: 檢查 Header 中的 `X-API-Key`。 1. **API Key 驗證**: 檢查 Header 中的 `X-API-Key`。
2. **Query Hash**: 計算 `SHA256(query + uuid + limit)` 作為快取 Key。 2. **Query Hash**: 計算 `SHA256(query + uuid + limit)` 作為快取 Key。
3. **MongoDB Cache 檢查**: 3. **MongoDB Cache 檢查**:
* 若命中快取：直接返回 JSON，**跳過**後續繁重的向量運算。 * 若命中快取：直接返回 JSON，**跳過**後續繁重的向量運算。
* 若未命中：進入步驟 2。 * 若未命中：進入步驟 2。
### 步驟 2: 向量化與搜尋 (Embedding & Search) ### 步驟 2: 向量化與搜尋 (Embedding & Search)
1. **Embedding**: 呼叫 Ollama (Nomic-Embed-Text) 將 Query 轉換為向量 (Vector)。 1. **Embedding**: 呼叫 Ollama (Nomic-Embed-Text) 將 Query 轉換為向量 (Vector)。
2. **Qdrant 搜尋**: 2. **Qdrant 搜尋**:
* 若有 `uuid`: 在該影片的 Collection 中搜尋最相似的 Chunk。 * 若有 `uuid`: 在該影片的 Collection 中搜尋最相似的 Chunk。
* 若無 `uuid`: 進行全域搜尋。 * 若無 `uuid`: 進行全域搜尋。
* 返回 Top-N 個包含 `chunk_id` 與 `uuid` 的候选結果。 * 返回 Top-N 個包含 `chunk_id` 與 `uuid` 的候选結果。
### 步驟 3: 資料豐富化 (Enrichment via PostgreSQL) ### 步驟 3: 資料豐富化 (Enrichment via PostgreSQL)
拿到 Qdrant 結果後，系統會**逐筆**向 PostgreSQL 查詢詳細資訊： 拿到 Qdrant 結果後，系統會**逐筆**向 PostgreSQL 查詢詳細資訊：
1. **取得 Chunk 內容**: 1. **取得 Chunk 內容**:
* 查詢 `chunks` 表格，獲取原始 JSON 內容、時間、幀號等。 * 查詢 `chunks` 表格，獲取原始 JSON 內容、時間、幀號等。
2. **取得影片路徑**: 2. **取得影片路徑**:
* 利用 `uuid` 查詢 `videos` 表格，獲取 `file_path`。 * 利用 `uuid` 查詢 `videos` 表格，獲取 `file_path`。
3. **取得 5W1H 摘要**: 3. **取得 5W1H 摘要**:
* 檢查 Chunk 是否有 `parent_chunk_id` (所屬的故事段落)。 * 檢查 Chunk 是否有 `parent_chunk_id` (所屬的故事段落)。
* 若有，查詢 `parent_chunks` 表格的 `metadata` 欄位。 * 若有，查詢 `parent_chunks` 表格的 `metadata` 欄位。
* 該欄位包含由 Gemma4 LLM 生成的結構化摘要 (Who, What, Where, When, Why, Key Events)。 * 該欄位包含由 Gemma4 LLM 生成的結構化摘要 (Who, What, Where, When, Why, Key Events)。
### 步驟 4: 格式化與回傳 (Formatting) ### 步驟 4: 格式化與回傳 (Formatting)
1. **Text Processing**: 將 Chunk 原始內容中的文字提取，並進行繁簡轉換與分詞處理 (Tokenization)。 1. **Text Processing**: 將 Chunk 原始內容中的文字提取，並進行繁簡轉換與分詞處理 (Tokenization)。
2. **建構 Hit 物件**: 組合上述所有資料為 `N8nSearchHit`。 2. **建構 Hit 物件**: 組合上述所有資料為 `N8nSearchHit`。
3. **寫入快取**: 將最終結果寫入 MongoDB 以便下次秒回。 3. **寫入快取**: 將最終結果寫入 MongoDB 以便下次秒回。
4. **回應 JSON**: 返回給 n8n。 4. **回應 JSON**: 返回給 n8n。
--- ---
@@ -141,12 +141,12 @@ X-API-Key: muser_68600856036340bcafc01930eb4bd839
除了標準的 Vector Search，還有兩種變體： 除了標準的 Vector Search，還有兩種變體：
### 5.1 BM25 Keyword Search ### 5.1 BM25 Keyword Search
- **Endpoint**: `/api/v1/n8n/search/bm25` * **Endpoint**: `/api/v1/n8n/search/bm25`
- **邏輯**: 跳過向量運算，直接使用 PostgreSQL 的全文檢索 (Full Text Search) 功能。適合精確匹配專有名詞或關鍵字。 * **邏輯**: 跳過向量運算，直接使用 PostgreSQL 的全文檢索 (Full Text Search) 功能。適合精確匹配專有名詞或關鍵字。
### 5.2 Smart Search (LLM 分析) ### 5.2 Smart Search (LLM 分析)
- **Endpoint**: `/api/v1/n8n/search/smart` * **Endpoint**: `/api/v1/n8n/search/smart`
- **邏輯**: * **邏輯**:
1. 將 Query 送至 Llama-server (Port 8081) 進行意圖分析 (5W1H)。 1. 將 Query 送至 Llama-server (Port 8081) 進行意圖分析 (5W1H)。
2. 提取出關鍵實體 (人名、地點、動作)。 2. 提取出關鍵實體 (人名、地點、動作)。
3. 將提取出的實體轉換為更精確的 BM25 查詢語句進行搜尋。 3. 將提取出的實體轉換為更精確的 BM25 查詢語句進行搜尋。

267
docs_v1.0/IMPLEMENTATION/PORTAL_BIRTH_UUID_ADAPTATION.md Normal file
View File

@@ -0,0 +1,267 @@
# Portal 适配 Birth UUID 完成报告
## 修改日期
2026-04-28
---
## 背景
Birth UUID Phase 1 MVP 实施后，需要确认 Portal 是否需要修改以适配新的 UUID 格式。
---
## Birth UUID 规格
| 项目 | 内容 |
|------|------|
| **格式** | SHA256[mac|timestamp|username|filename](0:32) |
| **长度** | 32字符（比旧UUID的16字符更长） |
| **唯一性** | MAC + Timestamp确保全球唯一 |
| **隐私保护** | MAC不直接暴露（哈希在UUID内） |
| **不可变** | 文件迁移不影响UUID |
---
## Portal 分析结果
### ✅ 前端无需强制修改
**原因**：
1. UUID显示使用CSS `truncate`，可自动截断长文本
2. API调用使用`uuid`参数，无长度限制
3. 路由`/videos/:uuid`可接受任意长度字符串
4. 向后兼容：16字符旧UUID和32字符新UUID都能正常工作
### 🔧 后端需要修改
**原因**：
- API返回的`VideoRecord`缺少`birth_registration`字段
- 需要在API响应中包含注册来源信息
---
## 实施修改
### 后端修改（Rust）
#### 1. VideoRecord 添加字段
```rust
// src/core/db/postgres_db.rs Line 158-177
pub struct VideoRecord {
pub birth_registration: Option<serde_json::Value>,
// ... 其他字段
}
```
#### 2. VideoRow 添加字段
```rust
// src/core/db/postgres_db.rs Line 99-124
pub struct VideoRow {
pub birth_registration: Option<serde_json::Value>,
// ... 其他字段
}
```
#### 3. VideoInfoResponse 添加字段
```rust
// src/api/server.rs Line 361-375
struct VideoInfoResponse {
birth_registration: Option<serde_json::Value>,
// ... 其他字段
}
```
#### 4. SELECT 查询修改
```sql
-- Line 770, 838, 920
SELECT id, uuid, ..., birth_registration, ..., total_frames FROM videos
```
#### 5. 构造函数修改
- `From<VideoRow> for VideoRecord`（Line 125-155）
- `ingestion.rs` VideoRecord构造（Line 146-164）
- `server.rs` VideoRecord构造（Line 802-820）
- 测试代码（Line 4489-4514）
---
### 前端修改（Vue）
#### 1. UUID显示优化
```vue
<!-- VideoDetailView.vue Line 17-20 -->
<div>
<span class="text-xs text-gray-500 uppercase">UUID</span>
<p class="text-sm font-mono text-gray-300 truncate">{{ video.uuid }}</p>
<p class="text-xs text-gray-600 mt-1">長度: {{ video.uuid.length }} 字符</p>
</div>
```
#### 2. Birth Registration 显示区域
```vue
<!-- VideoDetailView.vue Line 33-48 -->
<div v-if="video.birth_registration" class="mt-4 bg-gray-850 p-3 rounded border border-gray-600">
<h4 class="text-xs font-semibold text-gray-400 mb-2 uppercase">註冊來源資訊</h4>
<div class="grid grid-cols-2 md:grid-cols-4 gap-3">
<div>
<span class="text-xs text-gray-600">用戶名:</span>
<p class="text-sm text-gray-300">{{ video.birth_registration.registration_source?.username }}</p>
</div>
<div>
<span class="text-xs text-gray-600">註冊時間:</span>
<p class="text-sm text-gray-300">{{ formatTimestamp(video.birth_registration.registration_source?.timestamp) }}</p>
</div>
<div>
<span class="text-xs text-gray-600">原始檔名:</span>
<p class="text-sm text-gray-300 truncate">{{ video.birth_registration.registration_source?.original_filename }}</p>
</div>
<div>
<span class="text-xs text-gray-600">UUID類型:</span>
<p class="text-sm text-gray-300">{{ video.uuid.length === 32 ? 'Birth UUID' : 'Legacy UUID' }}</p>
</div>
</div>
</div>
```
#### 3. 时间格式化函数
```typescript
function formatTimestamp(timestamp: string | undefined): string {
if (!timestamp) return '-'
try {
const date = new Date(timestamp)
return date.toLocaleString('zh-TW', {
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit'
})
} catch {
return timestamp
}
}
```
---
## birth_registration JSONB 结构
```json
{
"registration_source": {
"mac_address": "ba:f5:ee:bc:45:78",
"username": "demo",
"timestamp": "2026-04-27T22:00:00+08:00",
"original_path": "/Users/.../demo",
"original_filename": "video.mp4"
}
}
```
---
## API 响应示例
### 旧UUID视频（16字符）
```json
{
"uuid": "ac625815183a21e1",
"birth_registration": null,
"file_name": "video.mp4",
...
}
```
### 新UUID视频（32字符）
```json
{
"uuid": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"birth_registration": {
"registration_source": {
"mac_address": "ba:f5:ee:bc:45:78",
"username": "demo",
"timestamp": "2026-04-27T22:00:00+08:00",
"original_filename": "video.mp4"
}
},
"file_name": "video.mp4",
...
}
```
---
## 向后兼容性
| UUID类型 | 长度 | birth_registration | Portal显示 |
|---------|------|-------------------|-----------|
| **旧UUID** | 16字符 | null | 显示UUID，隐藏birth_registration区域 |
| **新UUID** | 32字符 | 有数据 | 显示UUID，显示birth_registration区域 |
---
## 测试验证计划
### 步骤 1: 编译测试
```bash
# 检查编译（birth_registration相关错误已修复）
cargo check --lib
```
### 步骤 2: 注册新视频
```bash
# 使用Birth UUID注册
cargo run -- register /path/to/new_video.mp4
```
### 步骤 3: 检查数据库
```sql
SELECT uuid, LENGTH(uuid), birth_registration
FROM dev.videos
WHERE birth_registration IS NOT NULL;
```
### 步骤 4: API测试
```bash
# 查询新UUID视频
curl http://localhost:3003/api/v1/videos?uuid=<32字符UUID>
```
### 步骤 5: Portal显示测试
- 打开Portal `/videos/<32字符UUID>`
- 确认UUID显示为32字符
- 确认birth_registration区域显示注册信息
---
## 修改文件清单
| 文件 | 修改内容 |
|------|---------|
| `/src/core/db/postgres_db.rs` | VideoRecord/VideoRow添加字段，SELECT查询修改 |
| `/src/api/server.rs` | VideoInfoResponse添加字段，构造函数修改 |
| `/src/core/ingestion.rs` | VideoRecord构造添加birth_registration: None |
| `/portal/src/views/VideoDetailView.vue` | UUID显示优化，birth_registration显示区域 |
---
## 总结
✅ **Portal已完全适配Birth UUID**
### 关键成果
1. ✅ 后端API返回`birth_registration`字段
2. ✅ 前端显示Birth UUID长度和注册来源信息
3. ✅ 向后兼容16字符旧UUID
4. ✅ 新视频注册时自动记录`birth_registration`
### 下一步
1. 修复遗留编译错误（redis、SCRIPTS_DIR、PYTHON_PATH）
2. 实际注册新视频验证Birth UUID流程
3. Portal端到端测试
---
**完成日期**: 2026-04-28
**状态**: 后端+前端修改完成，待测试验证

12
docs_v1.0/IMPLEMENTATION/SEARCH_ACCEPTANCE_CRITERIA.md
View File

@@ -81,11 +81,11 @@
為了達成上述所有標準，我們必須完成以下開發： 為了達成上述所有標準，我們必須完成以下開發：
1. [ ] **語義索引建置 (Semantic Indexing)**: 使用 Ollama (Gemma 4) 離線分析全片對話，填入 `chunk_semantics` 表。 1. [ ] **語義索引建置 (Semantic Indexing)**: 使用 Ollama (Gemma 4) 離線分析全片對話，填入 `chunk_semantics` 表。
2. [ ] **場景聚合邏輯 (Scene Aggregation)**: 將零碎的 ASR/CUT 聚合成有意義的「場景 (Scene)」。 2. [ ] **場景聚合邏輯 (Scene Aggregation)**: 將零碎的 ASR/CUT 聚合成有意義的「場景 (Scene)」。
3. [ ] **互動計數器 (Interaction Counter)**: 統計角色同框次數，支援「第 X 次見面」查詢。 3. [ ] **互動計數器 (Interaction Counter)**: 統計角色同框次數，支援「第 X 次見面」查詢。
4. [ ] **事件時間軸 (Event Timeline)**: 將 Gunshot, Death, Fight 等事件結構化，支援「...之後」查詢。 4. [ ] **事件時間軸 (Event Timeline)**: 將 Gunshot, Death, Fight 等事件結構化，支援「...之後」查詢。
5. [ ] **關係圖譜 (Relationship Graph)**: 建立角色關係網，支援「主持人/來賓」等角色定義。 5. [ ] **關係圖譜 (Relationship Graph)**: 建立角色關係網，支援「主持人/來賓」等角色定義。
--- ---
@@ -190,4 +190,4 @@ curl -X POST http://localhost:3002/api/v1/search \
--- ---
**這份文檔已建立於 `docs/SEARCH_ACCEPTANCE_CRITERIA.md`，我們將以此為目標持續推進系統開發。** **這份文檔已建立於 `docs/SEARCH_ACCEPTANCE_CRITERIA.md`，我們將以此為目標持續推進系統開發。**

12
docs_v1.0/IMPLEMENTATION/STAMP_SEARCH_PROGRESS.md
View File

@@ -1,6 +1,6 @@
# Stamp Search Progress # Stamp Search Progress
**UUID**: `384b0ff44aaaa1f1` **UUID**: `384b0ff44aaaa1f14cb2cd63b3fea966`
**Video**: Charade (1963) - ~115 min **Video**: Charade (1963) - ~115 min
**Status**: ⏸️ Paused - User review needed **Status**: ⏸️ Paused - User review needed
@@ -31,26 +31,26 @@
### 1. Color-Based Detection (Blue + Red for Inverted Jenny) ### 1. Color-Based Detection (Blue + Red for Inverted Jenny)
- **Script**: `scripts/filter_stamp_colors.py` - **Script**: `scripts/filter_stamp_colors.py`
- **Candidates**: 21 images - **Candidates**: 21 images
- **Location**: `output/384b0ff44aaaa1f1/florence2_results/STAMP_CANDIDATE_*.jpg` - **Location**: `output/384b0ff44aaaa1f14cb2cd63b3fea966/florence2_results/STAMP_CANDIDATE_*.jpg`
- **Result**: ❌ Not a match - **Result**: ❌ Not a match
### 2. Balanced Blue+Red Shape Detection ### 2. Balanced Blue+Red Shape Detection
- **Script**: `scripts/filter_stamp_colors.py` (refined) - **Script**: `scripts/filter_stamp_colors.py` (refined)
- **Candidates**: 13 images - **Candidates**: 13 images
- **Location**: `output/384b0ff44aaaa1f1/florence2_results/BALANCED_STAMP_*.jpg` - **Location**: `output/384b0ff44aaaa1f14cb2cd63b3fea966/florence2_results/BALANCED_STAMP_*.jpg`
- **Result**: ❌ Not a match - **Result**: ❌ Not a match
### 3. Rectangle Shape + Color Detection (Full Frames) ### 3. Rectangle Shape + Color Detection (Full Frames)
- **Script**: `scripts/detect_stamp_shapes.py` - **Script**: `scripts/detect_stamp_shapes.py`
- **Candidates**: 22 crops from 8 scan frames - **Candidates**: 22 crops from 8 scan frames
- **Location**: `output/384b0ff44aaaa1f1/florence2_results/STAMP_CROP_*.jpg` - **Location**: `output/384b0ff44aaaa1f14cb2cd63b3fea966/florence2_results/STAMP_CROP_*.jpg`
- **Result**: ❌ Not a match - **Result**: ❌ Not a match
### 4. Full Video Scan (every 60 seconds) ### 4. Full Video Scan (every 60 seconds)
- **Script**: `scripts/scan_full_video_stamps.py` - **Script**: `scripts/scan_full_video_stamps.py`
- **Frames scanned**: 115 - **Frames scanned**: 115
- **Candidates**: 27 images - **Candidates**: 27 images
- **Location**: `output/384b0ff44aaaa1f1/stamp_candidates_full/` - **Location**: `output/384b0ff44aaaa1f14cb2cd63b3fea966/stamp_candidates_full/`
- **Result**: ❌ Not a match - **Result**: ❌ Not a match
### 5. Florence-2 AI Vision ### 5. Florence-2 AI Vision
@@ -61,7 +61,7 @@
- **Script**: `scripts/scan_charade_stamps.py` - **Script**: `scripts/scan_charade_stamps.py`
- **Frames scanned**: 67 (from key stamp dialogue timestamps) - **Frames scanned**: 67 (from key stamp dialogue timestamps)
- **Candidates**: 60+ paper-like rectangular crops - **Candidates**: 60+ paper-like rectangular crops
- **Location**: `output/384b0ff44aaaa1f1/stamp_scenes_crops/` - **Location**: `output/384b0ff44aaaa1f14cb2cd63b3fea966/stamp_scenes_crops/`
- **Result**: ❌ Not a match (or user hasn't reviewed yet) - **Result**: ❌ Not a match (or user hasn't reviewed yet)
## Key Timestamps for Visual Inspection ## Key Timestamps for Visual Inspection

2
docs_v1.0/IMPLEMENTATION/SYNONYM_CONFIGURATION.md
View File

@@ -184,4 +184,4 @@ println!("擴展 '電腦 工作': {}", expander.expand_query("電腦 工作"));
- 同義詞擴展器：`src/core/text/synonym_expander.rs` - 同義詞擴展器：`src/core/text/synonym_expander.rs`
- 繁簡轉換：`src/core/text/synonym.rs` - 繁簡轉換：`src/core/text/synonym.rs`
- 分詞器：`src/core/text/tokenizer.rs` - 分詞器：`src/core/text/tokenizer.rs`
- PostgreSQL 整合：`src/core/db/postgres_db.rs` - PostgreSQL 整合：`src/core/db/postgres_db.rs`

2
docs_v1.0/IMPLEMENTATION/SYNONYM_FOREST_README.md
View File

@@ -206,4 +206,4 @@ python3 -m json.tool config/synonyms/custom_synonyms.json
--- ---
**注意**: 本系統僅提供技術框架和工具，客戶需自行負責同義詞資源的合法性、準確性和維護工作。 **注意**: 本系統僅提供技術框架和工具，客戶需自行負責同義詞資源的合法性、準確性和維護工作。

6
docs_v1.0/IMPLEMENTATION/USER_MANAGEMENT_PLAN.md
View File

@@ -260,17 +260,17 @@ pub async fn register(
} }
// 關聯 user_id 到影片 // 關聯 user_id 到影片
let video_uuid = state.db.create_video(req, Some(ctx.user_id)).await?; let file_uuid = state.db.create_video(req, Some(ctx.user_id)).await?;
// 建立 processing job（帶 user_id） // 建立 processing job（帶 user_id）
state.db.create_monitor_job( state.db.create_monitor_job(
job_type: "auto_ingestion", job_type: "auto_ingestion",
video_uuid, file_uuid,
user_id: Some(ctx.user_id), user_id: Some(ctx.user_id),
processors: vec!["asr", "cut", "yolo", "ocr", "face", "pose"], processors: vec!["asr", "cut", "yolo", "ocr", "face", "pose"],
).await?; ).await?;
Ok(Json(RegisterResponse { uuid: video_uuid })) Ok(Json(RegisterResponse { uuid: file_uuid }))
} }
``` ```

370
docs_v1.0/MEDIAPIPE_HOLISTIC_INTEGRATION_REPORT.md Normal file
View File

@@ -0,0 +1,370 @@
# MediaPipe Holistic 整合完成报告
> 整合日期: 2026-04-28
> 测试视频: preview.mp4 (15秒, 329帧)
---
## 整合架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ Integrated Body Action Decoder │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ InsightFace │ │ MediaPipe │ │
│ │ face.json │ │ holistic.json │ │
│ │ │ │ │ │
│ │ - embedding │ │ - face_mesh │ (478 landmarks) │
│ │ - pose_angle │ │ - pose │ (33 keypoints) │
│ │ - landmarks │ │ - hands │ (21 × 2 keypoints) │
│ └───────────────┘ └───────────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ Frame Matcher │ (按 frame_num 合并) │
│ └───────┬───────┘ │
│ │ │
│ ┌───────────────▼───────────────┐ │
│ │ Integrated Action Decoder │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Face │ │ Eyes │ │ │
│ │ │ Actions │ │ Actions │ │ │
│ │ └─────────┘ └─────────┘ │ │
│ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Mouth │ │ Arms │ │ │
│ │ │ Actions │ │ Actions │ │ │
│ │ └─────────┘ └─────────┘ │ │
│ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Hands │ │ Legs │ │ │
│ │ │ Actions │ │ Actions │ │ │
│ │ └─────────┘ └─────────┘ │ │
│ │ ┌───────────────────┐ │ │
│ │ │ Combined Actions │ │ │
│ │ └───────────────────┘ │ │
│ └─────────────────────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ Output JSON │ │
│ └───────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 数据来源
### InsightFace (face.json)
| 字段 | 说明 |
|------|------|
| **embedding** | 512-dim ArcFace embedding |
| **pose_angle** | Face pose (frontal, three_quarter, profile_left, profile_right) |
| **landmarks** | 5-point keypoints |
### MediaPipe Holistic (holistic.json)
| 字段 | 说明 |
|------|------|
| **face_mesh.landmarks** | 478 3D landmarks |
| **face_mesh.eye_features** | EAR, iris position, eye_action |
| **face_mesh.mouth_features** | MAR, mouth_action |
| **pose.landmarks** | 33 keypoints with visibility |
| **pose.arm_features** | Elbow angles, arm actions |
| **pose.leg_features** | Knee angles, leg actions |
| **hands.left/right** | 21 keypoints, gesture detection |
---
## 动作检测能力
### Face Actions (InsightFace)
| Action | Description | Example |
|--------|-------------|---------|
| **pose_frontal** | 正面 pose | frontal (confidence: 0.9) |
| **pose_three_quarter** | 侧面 pose | three_quarter (confidence: 0.85) |
| **pose_profile_left** | 左侧面 | profile_left (confidence: 0.9) |
| **pose_profile_right** | 右侧面 | profile_right (confidence: 0.9) |
---
### Eye Actions (MediaPipe Face Mesh)
| Action | Threshold | Description |
|--------|-----------|-------------|
| **eye_closed** | EAR < 0.15 | 闭眼 |
| **eye_squint** | EAR 0.15-0.25 | 眯眼 |
| **eye_normal** | EAR 0.25-0.4 | 正常 |
| **eye_wide_open** | EAR > 0.4 | 睁大眼 |
| **gaze_left** | iris_x < -0.2 | 向左看 |
| **gaze_right** | iris_x > 0.2 | 向右看 |
**示例输出**:
```json
{
"eye_features": {
"left_ear": 0.1902,
"right_ear": 0.1902,
"avg_ear": 0.1902,
"eye_action": "squint",
"gaze_direction": "center"
}
}
```
---
### Mouth Actions (MediaPipe Face Mesh)
| Action | Threshold | Description |
|--------|-----------|-------------|
| **mouth_closed** | MAR < 0.2 | 闭嘴 |
| **mouth_slightly_open** | MAR 0.2-0.3 | 微张 |
| **mouth_open** | MAR > 0.5 | 张嘴 |
| **mouth_yawn** | MAR > 0.7 | 打哈欠 |
| **mouth_smile** | corner_lift > 0.02 | 微笑 |
**示例输出**:
```json
{
"mouth_features": {
"mar": 0.3319,
"mouth_action": "slightly_open"
}
}
```
---
### Arm Actions (MediaPipe Pose)
| Action | Angle Threshold | Description |
|--------|-----------------|-------------|
| **left_arm_raise_left** | wrist_y < elbow_y < shoulder_y | 举起左臂 |
| **left_arm_extend_left** | elbow_angle > 150° | 伸展左臂 |
| **left_arm_fold_left** | elbow_angle < 90° | 弯曲左臂 |
| **right_arm_raise_right** | wrist_y < elbow_y < shoulder_y | 举起右臂 |
| **right_arm_extend_right** | elbow_angle > 150° | 伸展右臂 |
| **right_arm_fold_right** | elbow_angle < 90° | 弯曲右臂 |
| **cross_arms** | wrists_x overlapping | 双手交叉 |
**示例输出**:
```json
{
"arm_features": {
"left_elbow_angle": 161.29,
"right_elbow_angle": 161.95,
"left_arm_action": "extend_left",
"right_arm_action": "extend_right",
"cross_arms": true
}
}
```
---
### Hand Actions (MediaPipe Hands)
| Gesture | Fingers Extended | Description |
|---------|-----------------|-------------|
| **open_hand** | 5 | 张开手 |
| **fist** | 0 | 握拳 |
| **thumbs_up** | thumb only | 点赞 |
| **peace_sign** | index + middle | 剪刀手 |
| **pointing** | index only | 指向 |
| **ok_sign** | thumb + index touching | OK 手势 |
| **grab** | thumb + index | 抓取 |
**示例输出**:
```json
{
"left_hand": {
"gesture": "thumbs_up",
"num_fingers_extended": 1
},
"right_hand": {
"gesture": "open_hand",
"num_fingers_extended": 5
}
}
```
---
### Leg Actions (MediaPipe Pose)
| Action | Condition | Description |
|--------|-----------|-------------|
| **leg_stand** | hip < knee < ankle (vertical) | 站立 |
| **leg_sit** | hip ≈ knee height | 坐姿 |
| **leg_knee_bend** | knee_angle < 120° | 弯膝 |
**示例输出**:
```json
{
"leg_features": {
"left_knee_angle": 175.2,
"right_knee_angle": 174.8,
"standing": true,
"sitting": false,
"leg_action": "stand"
}
}
```
---
## 实测结果 (preview.mp4)
### 动作统计
| 类别 | 动作 | 次数 |
|------|------|------|
| **Face** | pose_three_quarter | 6 |
| **Face** | pose_profile_right | 2 |
| **Eyes** | eye_squint | 8 |
| **Mouth** | mouth_closed | 6 |
| **Mouth** | mouth_slightly_open | 2 |
| **Arms** | cross_arms | 8 |
| **Arms** | left_arm_extend_left | 4 |
| **Arms** | left_arm_fold_left | 3 |
| **Arms** | right_arm_extend_right | 4 |
| **Arms** | right_arm_fold_right | 2 |
| **Hands** | left_hand_open_hand | 2 |
| **Hands** | left_hand_thumbs_up | 1 |
| **Hands** | right_hand_open_hand | 3 |
| **Legs** | leg_stand | 8 |
---
### 典型帧示例
#### Frame 30
```
Face: pose_three_quarter
Eyes: eye_squint
Mouth: mouth_closed
Arms: left_arm_fold_left, right_arm_neutral_right, cross_arms
Hands: left_hand_thumbs_up, right_hand_open_hand
Legs: leg_stand
```
**解读**: 站姿，左手握拳（fingers=1），右手张开（fingers=5），双臂交叉。
#### Frame 180
```
Face: pose_three_quarter
Eyes: eye_squint (EAR: 0.190)
Mouth: mouth_slightly_open (MAR: 0.332)
Arms: left_arm_extend_left (161.3°), right_arm_extend_right (161.9°), cross_arms
Legs: leg_stand
```
**解读**: 站姿，双臂伸展（角度161°），双手交叉，眼睛眯起，嘴巴微张。
---
## 创建的文件
| 文件 | 说明 |
|------|------|
| `scripts/mediapipe_holistic_processor.py` | MediaPipe Holistic 处理器 |
| `scripts/integrated_body_action_decoder.py` | 整合 Body Action Decoder |
| `scripts/utils/test_mediapipe.py` | MediaPipe 测试脚本 |
---
## 输出文件
| 文件 | 说明 |
|------|------|
| `preview.holistic.json` | MediaPipe Holistic 输出 (8 frames) |
| `integrated_body_actions.json` | 整合动作数据 (8 frames) |
---
## 使用方式
### Step 1: MediaPipe Holistic 处理
```bash
# 处理视频
python3 scripts/mediapipe_holistic_processor.py \
--video video.mp4 \
--output video.holistic.json \
--sample-interval 30
# 测试单帧
python3 scripts/mediapipe_holistic_processor.py \
--video video.mp4 \
--output test.json \
--test-frame 180
```
---
### Step 2: 整合 InsightFace + MediaPipe
```bash
# 整合并解码
python3 scripts/integrated_body_action_decoder.py \
--face-json video.face_traced.json \
--holistic-json video.holistic.json \
--output-json integrated_body_actions.json
# 测试单帧
python3 scripts/integrated_body_action_decoder.py \
--face-json video.face_traced.json \
--holistic-json video.holistic.json \
--frame 180
```
---
### Step 3: 查看输出
```json
{
"frames": {
"180": {
"actions": {
"face": [{"action": "pose_three_quarter"}],
"eyes": [{"action": "eye_squint", "ear": 0.190}],
"mouth": [{"action": "mouth_slightly_open", "mar": 0.332}],
"arms": [
{"action": "left_arm_extend_left", "angle": 161.29},
{"action": "cross_arms"}
],
"legs": [{"action": "leg_stand"}]
}
}
}
}
```
---
## MediaPipe 模型信息
| Model | Keypoints | Purpose |
|-------|-----------|---------|
| **Face Mesh** | 478 | 面部网格 (eyes, mouth, iris) |
| **Pose** | 33 | 全身姿态 (arms, legs, torso) |
| **Hands** | 21 × 2 | 手部关键点 (fingers, wrist) |
| **Holistic** | 478 + 33 + 42 | 整合模型 |
---
## 版本信息
- MediaPipe: 0.9.2.1 (mediapipe-silicon)
- InsightFace: buffalo_l
- 整合状态: ✅ 完成
- 测试状态: ✅ 通过

96
docs_v1.0/OPERATIONS/ARCHITECTURE_REVIEW_REPORT.md
View File

@@ -35,25 +35,25 @@
#### 🚨 H1: `faces` 表與 `file_identities` 表的關係不清 #### 🚨 H1: `faces` 表與 `file_identities` 表的關係不清
**問題**: **問題**:
* `FILE_IDENTITY_API_DESIGN.md` 同時定義了 `faces` 表和 `file_identities` 表。 * `FILE_IDENTITY_API_DESIGN.md` 同時定義了 `faces` 表和 `file_identities` 表。
* `faces` 表有 `identity_id` (表示 Face 可直接歸屬 Identity)。 * `faces` 表有 `identity_id` (表示 Face 可直接歸屬 Identity)。
* `file_identities` 表也有身份關聯資訊。 * `file_identities` 表也有身份關聯資訊。
* **兩者的職責重疊**，開發者會困惑該寫入哪張表。 * **兩者的職責重疊**，開發者會困惑該寫入哪張表。
**建議**: **建議**:
* **方案 A**: 移除 `faces` 表，將 Face 視為 `pre_chunk` 的一種類型，Face 與 Identity 的關聯僅通過 `file_identities` 管理。 * **方案 A**: 移除 `faces` 表，將 Face 視為 `pre_chunk` 的一種類型，Face 與 Identity 的關聯僅通過 `file_identities` 管理。
* **方案 B**: 保留 `faces` 表，但明確定義其為「Face 檢測原始數據表」，`file_identities` 僅作為「Face 與 Identity 的多對多關聯橋接表」。 * **方案 B**: 保留 `faces` 表，但明確定義其為「Face 檢測原始數據表」，`file_identities` 僅作為「Face 與 Identity 的多對多關聯橋接表」。
* **推薦方案 A**：符合「Frame = Pre-chunk」的設計理念，減少冗餘。 * **推薦方案 A**：符合「Frame = Pre-chunk」的設計理念，減少冗餘。
#### 🚨 H2: 缺少 `pre_chunks` 表的 Schema 定義 #### 🚨 H2: 缺少 `pre_chunks` 表的 Schema 定義
**問題**: **問題**:
* `FILE_IDENTITY_API_DESIGN.md` 中**未定義** `pre_chunks` 表結構。 * `FILE_IDENTITY_API_DESIGN.md` 中**未定義** `pre_chunks` 表結構。
* 但 `PROCESSOR_RESUME_STRATEGY.md` 明確指出 Processor 應產出 `pre_chunks`。 * 但 `PROCESSOR_RESUME_STRATEGY.md` 明確指出 Processor 應產出 `pre_chunks`。
* 實作時將無參考標準。 * 實作時將無參考標準。
**建議**: **建議**:
* 在設計文件中補充 `pre_chunks` 表定義，至少包含： * 在設計文件中補充 `pre_chunks` 表定義，至少包含：
```sql ```sql
pre_chunks ( pre_chunks (
pre_chunk_id UUID PK, pre_chunk_id UUID PK,
@@ -69,13 +69,13 @@
#### 🚨 H3: Candidate 與 Face 的關係未明確定義 #### 🚨 H3: Candidate 與 Face 的關係未明確定義
**問題**: **問題**:
* 設計說「Candidate 是未被確認歸屬 Identity 的 face」。 * 設計說「Candidate 是未被確認歸屬 Identity 的 face」。
* 但資料庫中沒有 `candidates` 表。 * 但資料庫中沒有 `candidates` 表。
* Candidate 是邏輯狀態還是物理表？ * Candidate 是邏輯狀態還是物理表？
**建議**: **建議**:
* **方案 A (推薦)**: Candidate 不需要獨立表。`faces.identity_id IS NULL` 即代表該 Face 是 Candidate。 * **方案 A (推薦)**: Candidate 不需要獨立表。`faces.identity_id IS NULL` 即代表該 Face 是 Candidate。
* 在 API 設計中明確說明：`GET /people/candidates` = `SELECT * FROM faces WHERE identity_id IS NULL`。 * 在 API 設計中明確說明：`GET /people/candidates` = `SELECT * FROM faces WHERE identity_id IS NULL`。
--- ---
@@ -84,38 +84,38 @@
#### ⚠️ M1: 缺少 Chunk 聚合規則的輸入輸出定義 #### ⚠️ M1: 缺少 Chunk 聚合規則的輸入輸出定義
**問題**: **問題**:
* Rule 1/2/3 如何讀取 `pre_chunks` 並產出 `chunks`？ * Rule 1/2/3 如何讀取 `pre_chunks` 並產出 `chunks`？
* 沒有明確的數據流說明。 * 沒有明確的數據流說明。
**建議**: **建議**:
* 補充 `CHUNKING` 目錄下的規則文件，定義每個 Rule 的： * 補充 `CHUNKING` 目錄下的規則文件，定義每個 Rule 的：
* **Input**: 從哪些 `pre_chunks` 讀取？ * **Input**: 從哪些 `pre_chunks` 讀取？
* **Logic**: 聚合邏輯是什麼？ * **Logic**: 聚合邏輯是什麼？
* **Output**: 產出什麼樣的 `chunk`？ * **Output**: 產出什麼樣的 `chunk`？
#### ⚠️ M2: Resource Registry 與現有 Job Worker 的整合 #### ⚠️ M2: Resource Registry 與現有 Job Worker 的整合
**問題**: **問題**:
* `UNIFIED_RESOURCE_REGISTRY.md` 定義了統一的資源註冊機制。 * `UNIFIED_RESOURCE_REGISTRY.md` 定義了統一的資源註冊機制。
* 但現有的 `src/worker/job_worker.rs` 是硬編碼調度 (`ProcessorType::all()`)。 * 但現有的 `src/worker/job_worker.rs` 是硬編碼調度 (`ProcessorType::all()`)。
* 如何過渡？ * 如何過渡？
**建議**: **建議**:
* 定義過渡路徑： * 定義過渡路徑：
1. **Phase 1**: Worker 仍使用硬編碼，但 Processor 啟動時額外註冊到 Registry（僅用於監控）。 1. **Phase 1**: Worker 仍使用硬編碼，但 Processor 啟動時額外註冊到 Registry（僅用於監控）。
2. **Phase 2**: Worker 改為從 Registry 動態發現資源。 2. **Phase 2**: Worker 改為從 Registry 動態發現資源。
#### ⚠️ M3: 檔案類型限制與欄位設計 #### ⚠️ M3: 檔案類型限制與欄位設計
**問題**: **問題**:
* `files` 表定義了 `file_type` (video, pdf...) 但現階段僅處理 Video。 * `files` 表定義了 `file_type` (video, pdf...) 但現階段僅處理 Video。
* `pre_chunks` 和 `chunks` 表若設計時未考慮擴充性，未來加 PDF 時需大改。 * `pre_chunks` 和 `chunks` 表若設計時未考慮擴充性，未來加 PDF 時需大改。
**建議**: **建議**:
* 在 `pre_chunks` 表加入 `coordinate_type` 欄位： * 在 `pre_chunks` 表加入 `coordinate_type` 欄位：
* Video: 使用 `frame_index` (幀號) * Video: 使用 `frame_index` (幀號)
* Text: 使用 `page_number` + `paragraph_index` * Text: 使用 `page_number` + `paragraph_index`
* 確保 Schema 可容納未來的檔案類型。 * 確保 Schema 可容納未來的檔案類型。
--- ---
@@ -126,7 +126,7 @@
| 文件 | 使用的術語 | 建議統一為 | | 文件 | 使用的術語 | 建議統一為 |
|------|-----------|-----------| |------|-----------|-----------|
| `FILE_IDENTITY_API_DESIGN.md` | `file_id` | `file_id` | | `FILE_IDENTITY_API_DESIGN.md` | `file_id` | `file_id` |
| `PROCESSOR_RESUME_STRATEGY.md` | `video_uuid` | `file_id` | | `PROCESSOR_RESUME_STRATEGY.md` | `file_uuid` | `file_id` |
| 現有程式碼 | `uuid` | `file_id` | | 現有程式碼 | `uuid` | `file_id` |
**建議**: 全文統一使用 `file_id` 或 `file_uuid`，避免混用。 **建議**: 全文統一使用 `file_id` 或 `file_uuid`，避免混用。
@@ -165,17 +165,17 @@ API 設計中定義了 `{"ok": false, "error": "..."}` 但未列出標準錯誤
## 4. 建議的行動計畫 ## 4. 建議的行動計畫
### Phase 0: 文檔修正 (立即) ### Phase 0: 文檔修正 (立即)
- [ ] 在 `FILE_IDENTITY_API_DESIGN.md` 中補充 `pre_chunks` 表 Schema (解決 H2) * [ ] 在 `FILE_IDENTITY_API_DESIGN.md` 中補充 `pre_chunks` 表 Schema (解決 H2)
- [ ] 明確定義 `faces` vs `file_identities` 的職責分工 (解決 H1) * [ ] 明確定義 `faces` vs `file_identities` 的職責分工 (解決 H1)
- [ ] 統一術語 (`file_id` vs `video_uuid`) (解決 L1) * [ ] 統一術語 (`file_id` vs `file_uuid`) (解決 L1)
### Phase 1: 補充缺失文檔 ### Phase 1: 補充缺失文檔
- [ ] 撰寫 `CHUNKING/RULES/RULE_SPEC.md` (解決 M1) * [ ] 撰寫 `CHUNKING/RULES/RULE_SPEC.md` (解決 M1)
- [ ] 撰寫 `MIGRATION_GUIDE.md` (從舊系統過渡) * [ ] 撰寫 `MIGRATION_GUIDE.md` (從舊系統過渡)
- [ ] 撰寫 `API_ERROR_CODES.md` (解決 L3) * [ ] 撰寫 `API_ERROR_CODES.md` (解決 L3)
### Phase 2: 架構對齊 ### Phase 2: 架構對齊
- [ ] 確認 Resource Registry 與現有 Job Worker 的整合路徑 (解決 M2) * [ ] 確認 Resource Registry 與現有 Job Worker 的整合路徑 (解決 M2)
--- ---
@@ -183,9 +183,9 @@ API 設計中定義了 `{"ok": false, "error": "..."}` 但未列出標準錯誤
目前的架構設計在**核心概念** (File + Identity + Pre-chunk + Chunk) 上是正確的，方向明確。 目前的架構設計在**核心概念** (File + Identity + Pre-chunk + Chunk) 上是正確的，方向明確。
主要缺失在於： 主要缺失在於：
1. **`pre_chunks` 表未定義** (最關鍵，影響實作) 1. **`pre_chunks` 表未定義** (最關鍵，影響實作)
2. **Face/Candidate 的關係需要更清晰的表述** 2. **Face/Candidate 的關係需要更清晰的表述**
3. **缺少舊系統遷移策略** 3. **缺少舊系統遷移策略**
建議在進入 Implementation Phase 前，先完成 Phase 0 的文檔修正。 建議在進入 Implementation Phase 前，先完成 Phase 0 的文檔修正。
@@ -193,6 +193,6 @@ API 設計中定義了 `{"ok": false, "error": "..."}` 但未列出標準錯誤
## 版本資訊 ## 版本資訊
- 版本: V1.0 * 版本: V1.0
- 審查日期: 2026-04-25 * 審查日期: 2026-04-25
- 審查者: OpenCode * 審查者: OpenCode

14
docs_v1.0/OPERATIONS/DOCUMENT_AUDIT_REPORT.md
View File

@@ -12,14 +12,14 @@ created_by: "OpenCode"
created_at: "2026-04-25" created_at: "2026-04-25"
version: "V1.0" version: "V1.0"
tags: tags:
- "documentation" - "documentation"
- "ai-agent" - "ai-agent"
- "analysis" - "analysis"
- "docs_v1.0" - "docs_v1.0"
ai_query_hints: ai_query_hints:
- "docs_v1.0 文件規範有哪些缺失？" - "docs_v1.0 文件規範有哪些缺失？"
- "如何改進文件的 AI Agent 友好性？" - "如何改進文件的 AI Agent 友好性？"
- "哪些文件需要補充 YAML Frontmatter？" - "哪些文件需要補充 YAML Frontmatter？"
--- ---
| 項目 | 內容 | | 項目 | 內容 |

8
docs_v1.0/OPERATIONS/IMPLEMENTATION_COMPATIBILITY_ANALYSIS.md
View File

@@ -71,12 +71,12 @@
### 3.1 立即刪除 (已失效) ### 3.1 立即刪除 (已失效)
以下文件因架構被完全推翻，建議直接刪除： 以下文件因架構被完全推翻，建議直接刪除：
1. `docs_v1.0/ARCHITECTURE/TMDB_CHARACTER_INTEGRATION.md` 1. `docs_v1.0/ARCHITECTURE/TMDB_CHARACTER_INTEGRATION.md`
2. `docs_v1.0/ARCHITECTURE/SPEAKER_INTEGRATION.md` 2. `docs_v1.0/ARCHITECTURE/SPEAKER_INTEGRATION.md`
3. `docs_v1.0/ARCHITECTURE/IDENTITY_SYSTEM_DESIGN.md` 3. `docs_v1.0/ARCHITECTURE/IDENTITY_SYSTEM_DESIGN.md`
### 3.2 建立新文件 (Design Phase 2) ### 3.2 建立新文件 (Design Phase 2)
1. 將上述刪除文件中有價值的業務邏輯 (如: 聲紋提取邏輯、TMDB 角色映射邏輯) 遷移至 `FILE_IDENTITY_API_DESIGN.md` 或新的 `PROCESSOR_DESIGN.md`。 1. 將上述刪除文件中有價值的業務邏輯 (如: 聲紋提取邏輯、TMDB 角色映射邏輯) 遷移至 `FILE_IDENTITY_API_DESIGN.md` 或新的 `PROCESSOR_DESIGN.md`。
### 3.3 批量名詞替換 ### 3.3 批量名詞替換
在 `docs_v1.0` 中執行全局替換 (需謹慎)： 在 `docs_v1.0` 中執行全局替換 (需謹慎)：

12
docs_v1.0/OPERATIONS/INCIDENT_RESPONSE_PROCEDURE.md
View File

@@ -70,31 +70,31 @@ ai_query_hints:
### 2.2 等級評估準則 ### 2.2 等級評估準則
#### P0 緊急事件（符合任一條件）： #### P0 緊急事件（符合任一條件）
- 核心服務完全不可用（網站無法訪問、API 完全無響應） - 核心服務完全不可用（網站無法訪問、API 完全無響應）
- 數據庫完全無法連接 - 數據庫完全無法連接
- 安全事件導致系統被入侵 - 安全事件導致系統被入侵
- 影響所有用戶的關鍵功能故障 - 影響所有用戶的關鍵功能故障
#### P1 高級事件（符合任一條件）： #### P1 高級事件（符合任一條件）
- 主要功能模塊不可用（如視頻處理、搜索功能失效） - 主要功能模塊不可用（如視頻處理、搜索功能失效）
- 影響超過 50% 用戶的功能問題 - 影響超過 50% 用戶的功能問題
- 性能嚴重下降（響應時間 > 10秒） - 性能嚴重下降（響應時間 > 10秒）
- 數據丟失或損壞風險 - 數據丟失或損壞風險
#### P2 中級事件（符合任一條件）： #### P2 中級事件（符合任一條件）
- 次要功能問題（如報告生成、特定查詢失敗） - 次要功能問題（如報告生成、特定查詢失敗）
- 影響部分用戶（< 50%）的功能問題 - 影響部分用戶（< 50%）的功能問題
- 中等性能問題（響應時間 3-10秒） - 中等性能問題（響應時間 3-10秒）
- 配置錯誤但不影響核心功能 - 配置錯誤但不影響核心功能
#### P3 低級事件： #### P3 低級事件
- 界面顯示問題（錯別字、格式不正確） - 界面顯示問題（錯別字、格式不正確）
- 輕微性能問題（響應時間 1-3秒） - 輕微性能問題（響應時間 1-3秒）
- 功能建議或改進請求 - 功能建議或改進請求
- 不影響功能的日誌警告 - 不影響功能的日誌警告
#### P4 資訊事件： #### P4 資訊事件
- 一般諮詢問題 - 一般諮詢問題
- 功能使用方法詢問 - 功能使用方法詢問
- 非緊急的建議 - 非緊急的建議
@@ -454,4 +454,4 @@ echo "事件報告已創建：$FILENAME"
| 運維負責人 | Warren | | | | | 運維負責人 | Warren | | | |
| 最終批准 | Warren | | | | | 最終批准 | Warren | | | |
> **注意**：本文檔需經技術負責人和運維負責人審核後正式生效。 > **注意**：本文檔需經技術負責人和運維負責人審核後正式生效。

Some files were not shown because too many files have changed in this diff Show More