---
document_type: "spec"
service: "MOMENTRY_CORE"
title: "向量化規範 V1.0.0"
date: "2026-05-02"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "core"
  - "vector-embedding"
  - "qdrant"
  - "v1.0.0"
  - "face-embedding"
  - "voice-embedding"
  - "text-embedding"
ai_query_hints:
  - "向量化規範的向量類型與維度說明"
  - "Face/Voice/Text 三種 embedding 的處理流程"
  - "Qdrant collection 的名稱與 payload 結構"
  - "Face embedding 的 512-D 向量規格（InsightFace ArcFace）"
  - "Voice embedding 的 192-D 向量規格（ECAPA-TDNN）"
  - "Text embedding 的 768-D 向量規格（EmbeddingGemma 300M）"
  - "Qdrant Payload 中 face 與 voice 的欄位定義"
  - "向量化流程中 child chunk 與 parent chunk 的 collection 區別"
related_documents:
  - "PROCESSORS/FACE_EMBEDDING_FLOW_V1.0.0.md"
  - "PROCESSORS/VOICE_EMBEDDING_FLOW_V1.0.0.md"
  - "CHUNK_DEFINITION_V1.0.0.md"
  - "PROCESSORS/FACE_V1.0.0.md"
  - "PROCESSORS/ASRX_V1.0.0.md"
---

# 向量化規範 V1.0.0

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

## Collection 命名隔離原則

不同機器、不同環境的向量資料**完全隔離**，命名格式：

```
{machine}_{env}_{type}
```

| 機器 | 環境 | prefix | 用途 |
|------|------|--------|------|
| M5 | dev | `m5_dev_` | M5 開發測試 |
| M5 | prod | `m5_prod_` | M5 正式（未來） |
| M4 | dev | `m4_dev_` | M4 開發測試 |
| M4 | prod | `m4_prod_` | M4 正式 |

### 完整 Collection 列表

| 名稱 | 機器 | 維度 | 用途 |
|------|------|------|------|
| `m5_dev_rule1` | M5 | 768D | Sentence chunks |
| `m5_dev_face` | M5 | 512D | Face embeddings |
| `m5_dev_voice` | M5 | 192D | Voice embeddings（未來） |
| `m4_dev_rule1` | M4 | 768D | Sentence chunks |
| `m4_dev_face` | M4 | 512D | Face embeddings |
| `m4_prod_rule1` | M4 | 768D | 正式環境 sentence |
| `m4_prod_face` | M4 | 512D | 正式環境 face |

### 設定方式

透過 `.env.development` 控制：

```bash
# M5 dev
QDRANT_COLLECTION=m5_dev_rule1

# M4 dev
QDRANT_COLLECTION=m4_dev_rule1

# M4 prod
QDRANT_COLLECTION=m4_prod_rule1
```

Face/voice collection 也遵循同樣規則（`m5_dev_face`、`m4_prod_face` 等）。

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| embedding | 向量嵌入，將非結構化資料轉換為數值向量 |
| Qdrant | 向量資料庫，用於儲存與檢索 embedding |
| collection | Qdrant 中的向量集合，類似資料庫中的資料表 |
| 768-D | Text embedding 的維度，由 EmbeddingGemma 300M 產出 |
| 512-D | Face embedding 的維度，由 InsightFace ArcFace 產出 |
| 192-D | Voice embedding 的維度，由 SpeechBrain ECAPA-TDNN 產出 |

## 向量類型

| 類型 | 來源 | 維度 | Collection | 用途 |
|------|------|------|------------|------|
| Text (child) | sentence chunk | 768-D | `momentry_dev_rule1` | 語意搜尋 |
| Text (parent) | scene chunk summary | 768-D | `momentry_dev_chunk_summaries` | 場景語意搜尋 |
| **Face** | Face processor (InsightFace) | **512-D** | `momentry_dev_face` | 人臉比對 |
| **Voice** | ASRX processor (ECAPA-TDNN) | **192-D** | `momentry_dev_voice` | 說話人比對 |

## 向量化流程

### Text Embedding

```
chunk (sentence / scene)
  → text_content / summary_text
  → EmbeddingGemma 300M (Python MPS, port 11436, OpenAI-compatible API)
  → 768-D vector
  → Qdrant momentry_dev_rule1 / momentry_dev_chunk_summaries
```

### Face Embedding

```
Face processor (InsightFace buffalo_l)
  → face_detections.embedding (512-D)
  → Qdrant momentry_dev_face
  → 用於 1:N 人臉比對
```

### Voice Embedding

```
ASRX processor (ECAPA-TDNN)
  → speaker embedding (192-D)
  → Qdrant momentry_dev_voice
  → 用於跨影片說話人辨識
```

## Qdrant Payload 結構

### Face Payload

```json
{
  "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
  "face_id": "face_42",
  "frame": 1260,
  "timestamp": 42.0,
  "x": 328,
  "y": 88,
  "width": 63,
  "height": 75,
  "confidence": 0.83
}
```

### Voice Payload

```json
{
  "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
  "speaker_id": "SPEAKER_0",
  "start_frame": 9,
  "end_frame": 441,
  "start_time": 0.3,
  "end_time": 14.7
}
```

## 已棄用模型

### mxbai-embed-large

| 項目 | 內容 |
|------|------|
| 維度 | 1024-D |
| 部署方式 | ANE CoreML Server（port 11435） |
| API | `/api/embeddings`（Ollama 相容） |
| 語言 | English only |
| 狀態 | ❌ 已棄用（v1.0 前） |
| 棄用原因 | 無法處理中文等多語內容 |
| 相關檔案 | `scripts/coreml_embed_server.py` |

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
| V1.1 | 2026-05-07 | EmbeddingGemma 300M 取代 nomic-embed-text-v2-moe；新增已棄用模型章節 | OpenCode | deepseek-chat |
