# Embedding 模型選型記錄

## 歷程

### 第一版：mxbai-embed-large（2026-05-07 上午）

- 選用理由：ANE CoreML 加速（8.5ms），1024D
- 已實作：CoreML 轉換（669MB）、ANE server（port 11435）、Rust Embedder 整合
- **發現問題**：mxbai 是 English only，無法處理中文等多語內容

### 第二版：EmbeddingGemma 300M（2026-05-07 下午）

- 選用理由：Google 官方出品，多語支援
- 嘗試 CoreML 轉換失敗：Gemma3 架構的 attention masking 太複雜，`torch.jit.trace` / `torch.onnx.export` 皆無法處理
- 改採 Python MPS server（Metal GPU）：`scripts/embeddinggemma_server.py`（port 11436）
- 維度：768D（僅有此版本，Google 未出更大 variant）
- 速度：~10ms per call

### 候選方案：bge-m3

| 項目 | 值 |
|------|-----|
| 維度 | **1024D** |
| 多語 | ✅ 中英日韓 100+ 語言 |
| 大小 | 605MB（Q8_0） |
| ANE | ❌ 不支援 |
| 部署 | llama.cpp（port 11437）或 Ollama |

### 候選方案：nomic-embed-text-v2-moe

| 項目 | 值 |
|------|-----|
| 維度 | 768D |
| 多語 | ✅ |
| ANE | ❌ MoE 架構，無法轉 CoreML |
| 部署 | Ollama 原生支援，M4 零配置 |
| MTEB | ~62-64（略優於 EmbeddingGemma） |

## 最終決定（v1.0 Release）

採用 **EmbeddingGemma 300M**（768D）作為 v1.0 release 的 embedding 模型。

理由：
1. 多語支援（中英）
2. Google 官方模型，品質有保障
3. Python MPS server 可在 M4/M5 一致部署
4. 已經上線運行，不需再更動

## 未來方向

- **bge-m3（1024D）** 留待下一版評估 —— 若要 1024D + 多語，這是唯一選項
- ANE 加速：目前無多語 embedding 模型可走 ANE。若未來有新的 multilingual CoreML embedding 模型可考慮

## 相關檔案

| 檔案 | 說明 |
|------|------|
| `scripts/embeddinggemma_server.py` | Python MPS embedding server（port 11436） |
| `scripts/coreml_embed_server.py` | mxbai ANE CoreML server（port 11435，已棄用） |
| `src/core/embedding/comic_embed.rs` | Rust Embedder（支援 Ollama + OpenAI 兩種 API 格式） |
| `.env.development` | `MOMENTRY_EMBED_URL=http://localhost:11436` |
