People API¶

Version: 2.1
Date: 2026-08-12
Base URL: http://localhost:3002
Auth: Requires API key header (Authorization: Bearer <api_key>)
Doc Path: /Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/19_people_api.md

資料架構¶

trace_profiles（PostgreSQL — People Search 專用）¶

每筆 file_uuid + trace_id 對應一個 face trace profile：

欄位	類型	說明
`file_uuid`	string	影片 UUID
`trace_id`	integer	Face trace ID（8Hz 取樣追蹤）
`name`	string	FS name（Face 頁面顯示 + People Search 搜尋）
`start_frame`	integer	起始 frame
`end_frame`	integer	結束 frame
`frame_count`	integer	追蹤 frame 數（8Hz 取樣，多數 > 1）
`key_frame`	string	關鍵幀圖片路徑
`key_face`	string	關鍵人臉裁切路徑
`avg_confidence`	float	平均偵測信心值
`status`	string	狀態（pending/confirmed）

可搜尋註記（metadata / VLM 欄位）¶

trace_profiles 包含 VLM 產生的註記，可用於進階搜尋和統計：

欄位	類型	說明
`vlm_description`	text	VLM 人物外貌描述
`vlm_clothing`	text	VLM 衣著描述
`vlm_tags`	text[]	VLM 標籤陣列
`vlm_location`	string	VLM 地點
`vlm_setting`	string	VLM 場景設定
`vlm_lighting`	string	VLM 光線
`vlm_weather`	string	VLM 天氣
`vlm_background`	text	VLM 背景描述
`vlm_bg_tags`	text[]	VLM 背景標籤

tkg_nodes（PostgreSQL — TKG 圖譜專用，與 profile 獨立）¶

欄位	說明
`external_id`	如 "trace_9"，對應 `trace_profiles.trace_id`
`label`	TKG 圖譜節點標籤（與 `trace_profiles.name` 獨立）
`properties`	TKG 節點屬性

_faces（Qdrant — Face 向量比對）¶

Face embedding 向量存在 Qdrant _faces collection，可用作 seed 比對：

Payload 欄位	類型	說明
`file_uuid`	string	影片 UUID
`trace_id`	integer	Face trace ID
`identity_id`	integer \| null	已綁定的 identity ID
`frame`	integer	Frame 編號
`embedding`	vector[512]	FaceNet 512-d embedding
`bbox`	object	人臉 bbox（x, y, width, height）
`confidence`	float	偵測信心值

1. GET /api/v1/search/people¶

搜尋已命名的 face trace profiles。回傳符合 name 的卡片列表。

Query Parameters¶

Parameter	Type	Required	Description
`query`	string	✅ Yes	搜尋關鍵字（ILIKE 模糊比對 `trace_profiles.name`）
`file_uuid`	string	❌ Optional	限制搜尋範圍
`limit`	integer	❌ Optional	回傳筆數上限（預設 10）

Example Request¶

# 搜尋名字
curl -X GET "http://localhost:3002/api/v1/search/people?query=Susan"

# 搜尋 VLM 註記（衣著、地點、標籤）
curl -X GET "http://localhost:3002/api/v1/search/people?query=blue+shirt"

# 限定影片
curl -X GET "http://localhost:3002/api/v1/search/people?file_uuid=abc123&query=Tom"

搜尋範圍¶

People Search 會搜尋以下欄位（ILIKE 模糊比對）：

欄位	說明
`name`	FS name
`vlm_description`	VLM 人物外貌描述
`vlm_clothing`	VLM 衣著描述
`vlm_tags`	VLM 標籤陣列
`vlm_location`	VLM 地點
`vlm_setting`	VLM 場景設定

Response¶

{
  "people": [
    {
      "file_uuid": "4655a0ab3c077e30c12b2298c2750650",
      "file_name": "",
      "trace_id": 9,
      "external_id": "trace_9",
      "name": "Susan",
      "start_frame": 118,
      "end_frame": 384,
      "frame_count": 39,
      "start_time": null,
      "end_time": null,
      "key_frame": "key_frame.jpg",
      "key_face": null,
      "avg_confidence": 0.694,
      "avg_capture_quality": 0.512,
      "best_capture_quality": 0.733
    }
  ],
  "total": 18
}

Response Fields¶

Field	Type	Description
`file_uuid`	string	影片 UUID
`trace_id`	integer	Face trace ID
`external_id`	string \| null	TKG node external_id（如 "trace_9"）
`name`	string \| null	使用者命名的 FS name
`start_frame`	integer \| null	起始 frame
`end_frame`	integer \| null	結束 frame
`frame_count`	integer \| null	追蹤 frame 數（8Hz 取樣）
`start_time`	float \| null	起始時間（秒）
`end_time`	float \| null	結束時間（秒）
`key_frame`	string \| null	關鍵幀圖片路徑
`key_face`	string \| null	關鍵人臉裁切路徑
`avg_confidence`	float \| null	平均偵測信心值
`avg_capture_quality`	float \| null	平均畫面品質分數（清晰度，0~1）
`best_capture_quality`	float \| null	該 trace 最佳畫面品質分數

2. POST /api/v1/search/universal¶

統一搜尋。設定 types: ["people"] 搜尋人物，或組合 "chunk"、"frame"。

People Search 會搜尋 trace_profiles 的 name + vlm_* 欄位： - name — FS name - vlm_description — VLM 人物外貌描述 - vlm_clothing — VLM 衣著描述 - vlm_tags — VLM 標籤陣列 - vlm_location — VLM 地點 - vlm_setting — VLM 場景設定

Request Body¶

{
  "query": "Susan",
  "file_uuid": "abc123",
  "types": ["people"],
  "page": 1,
  "page_size": 20
}

Request Fields¶

Field	Type	Required	Description
`query`	string	✅ Yes	搜尋關鍵字
`file_uuid`	string	❌ Optional	限制搜尋範圍
`types`	string[]	❌ Optional	`["chunk", "frame", "people"]` — 預設全部
`page`	integer	❌ Optional	頁碼（預設 1）
`page_size`	integer	❌ Optional	每頁筆數（預設 20，最大 200）

Response¶

{
  "query": "Susan",
  "results": [
    {
      "type": "person",
      "file_uuid": "4655a0ab3c077e30c12b2298c2750650",
      "trace_id": 9,
      "external_id": "trace_9",
      "name": "Susan",
      "frame_count": 39,
      "score": 0.95,
      "start_time": null,
      "end_time": null,
      "key_frame": "key_frame.jpg",
      "key_face": null
    }
  ],
  "total": 18,
  "page": 1,
  "page_size": 20,
  "has_more": false
}

3. PUT /api/v1/trace-profile（單筆改名）¶

更新單一 face trace profile 的 name 和 metadata。

Request Body¶

{
  "file_uuid": "4655a0ab3c077e30c12b2298c2750650",
  "trace_id": 9,
  "name": "Susan",
  "properties": { "custom_key": "custom_value" },
  "key_frame": "path/to/key_frame.jpg",
  "key_face": "path/to/key_face.jpg",
  "aliases": ["Susie", "Sue"]
}

Request Fields¶

Field	Type	Required	Description
`file_uuid`	string	✅ Yes	影片 UUID
`trace_id`	integer	✅ Yes	Face trace ID
`name`	string	❌ Optional	新的 FS name
`properties`	object	❌ Optional	自訂屬性（合併更新）
`key_frame`	string	❌ Optional	關鍵幀路徑
`key_face`	string	❌ Optional	關鍵人臉路徑
`aliases`	string[]	❌ Optional	別名列表

4. PUT /api/v1/trace-profile/group（批次改名）¶

批次更新多個 face trace profiles 的 name。

Request Body¶

{
  "file_uuid": "4655a0ab3c077e30c12b2298c2750650",
  "trace_ids": [9, 22, 5],
  "name": "Susan"
}

5. POST /api/v1/groups/merge（合併群組）¶

將多個 group 的 traces 合併為一個 group name。

Request Body¶

{
  "file_uuid": "4655a0ab3c077e30c12b2298c2750650",
  "source_groups": ["Person_0", "Person_1"],
  "target_group_name": "Susan"
}

Error Responses¶

400 Bad Request¶

{ "error": "name is required" }

401 Unauthorized¶

HTTP 401 (no body) — Missing or invalid API key

404 Not Found¶

{ "error": "Profile not found" }

500 Internal Server Error¶

{ "error": "DB error: connection refused" }

如何命名 Face Trace¶

使用 profile API 為 face trace 命名：

curl -X PUT "http://localhost:3002/api/v1/trace-profile" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_uuid": "4655a0ab3c077e30c12b2298c2750650",
    "trace_id": 9,
    "name": "Susan"
  }'

命名後即可透過 People Search API 搜尋：

curl "http://localhost:3002/api/v1/search/people?query=Susan" \
  -H "Authorization: Bearer <api_key>"

Pipeline 狀態定義¶

所有檔案的 status 由 /api/v1/file/{file_uuid}/sync-status 自動更新，依據 processor outputs 和功能就緒狀態判定。

Status	前端顯示	條件	啟用功能
`registered`	📋 已註冊	0 processor outputs	檔案註冊
`scanning`	🔍 掃描中	1-4/5 processor outputs	—
`keyword_ready`	🔎 關鍵字可用	sentence chunks > 0	Smart Search
`semantic_ready`	🧠 語意可用	embedded chunks > 0	Semantic Search
`face_mgmt_ready`	🎭 臉部管理可用	face_trace + trace_profiles + tkg_nodes(face_track)	People Search, Face Profile 讀寫, Face Group
`agent_ready`	🤖 Agent 可用	face_mgmt_ready + tkg_edges	Agent TKG Tools
`completed`	✅ 完成	5/5 processors + 全部功能就緒	—

Face Management Ready 明確定義¶

face_mgmt_ready 表示檔案已具備完整臉部管理功能，需同時滿足以下四個條件：

依賴項	檢查條件	說明	提供功能
Face Qdrant Ready	`_faces` collection 有 face points	Face embeddings 已存入 Qdrant	臉部比對、相似度搜尋
Face Trace Ready	`face_traced.json` 存在且有 traces	Face tracking 已完成	人臉軌跡資料
Face Profile Ready	`trace_profiles` 有紀錄	Profile 資料已建立	名字、VLM 註記、key_frame/key_face
Face TKG Node Ready	`tkg_nodes` 有 `face_track` nodes	TKG 圖譜節點已建立	臉部群組合併、關係查詢

檢查 SQL¶

-- Face Qdrant Ready
SELECT COUNT(*) FROM _faces WHERE file_uuid = $1;  -- > 0

-- Face Trace Ready
-- 檢查 face_traced.json 檔案存在且有 traces

-- Face Profile Ready
SELECT COUNT(*) FROM trace_profiles WHERE file_uuid = $1;  -- > 0

-- Face TKG Node Ready
SELECT COUNT(*) FROM tkg_nodes WHERE file_uuid = $1 AND node_type = 'face_track';  -- > 0

啟用功能清單¶

功能	API Endpoint	說明
People Search	`GET /api/v1/search/people`	搜尋已命名人臉
Face Profile 讀寫	`PUT /api/v1/trace-profile`	更新名字、VLM 註記
Face Group 合併	`POST /api/v1/groups/merge`	合併多個群組
Face Trace 改名	`PUT /api/v1/trace-profile`	為單個 trace 命名
Agent Face Search	Agent Tool: `face_profile_search`	Agent 搜尋人臉

狀態依賴關係¶

registered → scanning → keyword_ready → semantic_ready
                                         ↓
                              face_mgmt_ready → agent_ready → completed

每個階段對應的 Processor¶

階段	必要 Processor	產出
`keyword_ready`	ASR, ASRX	sentence chunks
`semantic_ready`	keyword_ready + Vectorize	embedded chunks
`face_mgmt_ready`	Face, FaceCluster	trace_profiles (People Search + Face Management)
`agent_ready`	face_mgmt_ready + TKG Edges	tkg_edges

Version History¶

Version	Date	Changes
1.0	2026-10-24	Initial documentation