# bp-embedding 階段成果報告

日期：2026-03-23

## 1. 報告目的

本報告整理本階段在 `bp-embedding` 專案中完成的 embedding baseline 比較、Taiwan.md 領域微調結果、正式 index 建置狀態，以及目前可作為後續部署與延伸實驗的推薦模型。

本報告特別列出：

- 基底模型（base models）評測結果
- 各版本 finetune 結果
- 評測內容與分數意義
- 目前最佳模型與建議

---

## 2. 評測內容說明

### 2.1 評測資料集

本階段主要採用：

- `data/processed/val_pairs_mixed.jsonl`

其格式為 JSONL，每筆資料包含：

- `text_a`
- `text_b`
- `score`

其中 `score` 是人工或既有流程定義的相似度標註，用來衡量模型對兩段文字語意相近程度的判斷能力。

### 2.2 評測流程

評測程式為：

- `src/eval/bench.py`

流程如下：

1. 讀入 `text_a`、`text_b`、`score`
2. 使用指定 embedding model 分別將 `text_a` 與 `text_b` 轉為向量
3. 計算兩向量的相似度
4. 將模型算出的相似度與標註分數做統計相關性比較

### 2.3 評測指標

本專案目前主要看兩個指標：

- `Spearman`
- `Pearson`

#### Spearman

- 代表排序相關性（ranking correlation）
- 重點是模型有沒有把「應該更相近」的 pair 排在更前面
- 對檢索 / retrieval 任務特別重要

#### Pearson

- 代表線性相關性（linear correlation）
- 重點是模型輸出的相似度數值，是否與標註分數整體呈現穩定線性關係
- 如果希望模型分數本身也能反映相似程度強弱，Pearson 很重要

### 2.4 如何解讀

- 分數越接近 `1` 越好
- 越接近 `0` 表示幾乎沒有對應關係
- 在本專案情境下：
  - `Spearman` 更偏向看「排序品質」
  - `Pearson` 更偏向看「分數本身的可解釋性」

---

## 3. 基底模型評測結果

以下基底模型皆以 `data/processed/val_pairs_mixed.jsonl` 為準。

| 類型 | Model config | Base model | Spearman | Pearson | 備註 |
| --- | --- | --- | ---: | ---: | --- |
| Base | `configs/model_e5.yaml` | `intfloat/multilingual-e5-large` | 0.3359806924 | 0.3595734325 | 本階段最強 base model 之一 |
| Base | `configs/model_nomic.yaml` | nomic 系列 | 0.1846740775 | 0.2112566591 | 本專案中表現偏弱 |
| Base | `configs/model_text2vec_rag.yaml` | `Mike0307/text2vec-base-chinese-rag` | 0.1971679989 | 0.2160776374 | 優於 nomic，但明顯落後 E5 |
| Base | `configs/model_bge_m3.yaml` | `BAAI/bge-m3` | 0.3629068298 | 0.3782295476 | 比 E5 base 更好 |
| Base | `configs/model_qwen3_embedding_0_6b.yaml` | `Qwen/Qwen3-Embedding-0.6B` | 0.3601716384 | 0.3923130251 | Spearman 接近 bge-m3，Pearson 更高 |
| Base | `configs/model_embeddinggemma_300m.yaml` | `google/embeddinggemma-300m` | 0.3584409147 | 0.3652447872 | Base 表現穩定，具備 finetune 潛力 |

### 3.1 基底模型觀察

- 在本次 base model 比較中，`bge-m3`、`Qwen3-Embedding-0.6B`、`EmbeddingGemma-300m` 都優於 `E5 base` 或非常接近其等級。
- 若只看 base model：
  - `bge-m3` 的 `Spearman` 最佳
  - `Qwen3-Embedding-0.6B` 的 `Pearson` 較佳
- `nomic` 與 `text2vec-rag` 在這份驗證集上表現較弱。

---

## 4. Finetune 模型結果

### 4.1 歷史 finetune 結果

| 類型 | Model config | 說明 | Spearman | Pearson | 備註 |
| --- | --- | --- | ---: | ---: | --- |
| Finetune | `configs/model_finetuned_v3.yaml` | 舊版 finetuned 模型（mixed set） | 0.0808868238 | 0.1622061609 | 在 mixed set 上表現不佳 |
| Finetune | `configs/model_finetuned_taiwan_md.yaml` | 舊版 Taiwan.md finetune | 0.3093988493 | 0.3085321953 | 明顯優於舊版 v3 |
| Finetune | `configs/model_finetuned_taiwan_md_e5_scratch_ckpt5500.yaml` | E5 scratch 訓練最佳 checkpoint | 0.4195534734 | 0.4537983404 | 本階段最佳結果來源 |
| Finetune | `configs/model_finetuned_taiwan_md_e5_best5500.yaml` | 固化後正式模型 | 0.4195534734 | 0.4537983404 | 目前推薦部署模型 |

### 4.2 EmbeddingGemma Taiwan.md finetune 結果

EmbeddingGemma 的完整訓練是後續新增的實驗，其最佳結果目前來自訓練 log：

- log: `outputs/logs/train_taiwan_md_embeddinggemma_300m_20260320.log`
- 最佳 eval 出現在約 `epoch = 1.653`（約 step 9000）

| 類型 | 訓練 config | Base model | Spearman | Pearson | 備註 |
| --- | --- | --- | ---: | ---: | --- |
| Finetune | `configs/train_contrastive_taiwan_md_embeddinggemma_300m.yaml` | `google/embeddinggemma-300m` | 0.3860 | 0.4109 | 由訓練中 evaluator 記錄的最佳值 |

### 4.3 Finetune 結果觀察

- `E5 + Taiwan.md finetune` 目前仍是全專案最佳結果。
- `EmbeddingGemma-300m` 經 Taiwan.md finetune 後，也比自己的 base model 有明顯進步：
  - Base：`0.3584 / 0.3652`
  - Finetuned best：`0.3860 / 0.4109`
- 雖然 `EmbeddingGemma` finetune 仍未超過 `E5 best5500`，但已證明此基底具備可訓練性。

---

## 5. 最佳模型比較

| 排名 | 模型 | 類型 | Spearman | Pearson | 結論 |
| --- | --- | --- | ---: | ---: | --- |
| 1 | `configs/model_finetuned_taiwan_md_e5_best5500.yaml` | Finetuned | 0.4195534734 | 0.4537983404 | 目前最佳，建議正式部署 |
| 2 | `EmbeddingGemma-300m` Taiwan.md finetune | Finetuned | 0.3860 | 0.4109 | 值得保留，具備後續優化空間 |
| 3 | `configs/model_qwen3_embedding_0_6b.yaml` | Base | 0.3601716384 | 0.3923130251 | Base 中表現強 |
| 4 | `configs/model_bge_m3.yaml` | Base | 0.3629068298 | 0.3782295476 | Base 中 Spearman 最佳 |
| 5 | `configs/model_embeddinggemma_300m.yaml` | Base | 0.3584409147 | 0.3652447872 | Base 表現穩定 |
| 6 | `configs/model_e5.yaml` | Base | 0.3359806924 | 0.3595734325 | 原本主要 baseline |
| 7 | `configs/model_finetuned_taiwan_md.yaml` | Finetuned | 0.3093988493 | 0.3085321953 | 舊版台灣語料 finetune |
| 8 | `configs/model_text2vec_rag.yaml` | Base | 0.1971679989 | 0.2160776374 | 效果有限 |
| 9 | `configs/model_nomic.yaml` | Base | 0.1846740775 | 0.2112566591 | 效果偏弱 |
| 10 | `configs/model_finetuned_v3.yaml` | Finetuned | 0.0808868238 | 0.1622061609 | 不建議再使用 |

---

## 6. 目前正式建議

### 6.1 正式部署 / 正式檢索

目前建議使用：

- 模型 config：`configs/model_finetuned_taiwan_md_e5_best5500.yaml`
- 模型目錄：`outputs/zh_trad_contrastive_taiwan_md_e5_best5500`
- 正式 index：`outputs/index/hnsw_taiwan_md_e5_best5500_taiwan_md.index`

理由：

- 在 `val_pairs_mixed` 上表現最佳
- 已完成 checkpoint 固化
- 已完成正式 index 建置
- 已實際做過 query 測試，結果合理

### 6.2 值得保留的第二候選

- `EmbeddingGemma-300m` Taiwan.md finetune

理由：

- base model 表現本身不錯
- finetune 後明顯提升
- 有機會在參數、訓練步數、checkpoint 選擇上再進一步優化

---

## 7. 本階段結論

1. `E5` 目前仍是本專案中最有效的主幹模型。
2. `E5 best5500` 是本階段最成熟、最適合正式部署的模型。
3. 新加入的開源模型比較中：
   - `bge-m3`
   - `Qwen3-Embedding-0.6B`
   - `EmbeddingGemma-300m`
   都展現出不錯的 base model 能力。
4. `EmbeddingGemma-300m` 經 Taiwan.md finetune 後已能逼近更高等級結果，值得做第二梯隊持續實驗。
5. 目前整體排序建議：
   - 第一優先：`E5 best5500`
   - 第二優先：`EmbeddingGemma-300m` finetune
   - 第三優先：`Qwen3` / `bge-m3` 作為新基底延伸實驗

---

## 8. 建議後續工作

1. 固化 `EmbeddingGemma-300m` 的最佳 checkpoint（建議從 step 9000 附近開始）
2. 對 `EmbeddingGemma` 跑一次正式獨立評測並補寫入 `eval_history.jsonl`
3. 對 `Qwen3` 與 `bge-m3` 也各做一版 Taiwan.md finetune，建立完整比較矩陣
4. 規劃正式 benchmark query set，補足純相關係數之外的 retrieval 實測品質

---

## 9. 主要資料來源

- `outputs/eval_history.jsonl`
- `outputs/logs/train_taiwan_md_embeddinggemma_300m_20260320.log`
- `configs/` 內各模型與訓練設定檔
- `src/eval/bench.py`