EmbeddingGemma 2 多平台與多資料庫架構設計與實作指南

建立日期：2026-10-07
適用專案：MockExam-CCNA
核心技術：Google DeepMind EmbeddingGemma 2、MRL 降維技術、pgvector、PowerSync Local-First、Flutter Multiplatform

一、 背景與核心價值

2026 年 10 月 Google DeepMind 正式發表了基於 Gemma 4 架構打造的開放模型 EmbeddingGemma 2（採商業友善的 Apache 2.0 授權）。其核心亮點在於：

1. 極致輕量化（Sub-1B on-device）：
   • 純文字與程式碼模組僅 270M 參數，全多模態模組（含 170M 影像、300M 音訊編碼器）僅 740M 參數。
   • 經 8-bit 量化後，於行動裝置上僅需 ~191MB 作用中 RAM，全模態約 ~567MB RAM。
2. 原生跨模態統一向量空間（Natively Multimodal）：
   • 首次將文字、程式碼（Code）、拓撲圖片（Image）與音訊映射至同一向量維度空間。
   • 在 MTEB Code 評測高達 78.68（提升 +9.92 分），對思科 IOS CLI 指令與網路配置檔語意理解極為精準。
3. MRL 動態維度截斷（Matryoshka Representation Learning）：
   • 原生 768 維向量可無損截斷至 512、256 或 128 維，經 L2 歐幾里得正規化後，可降低向量資料庫與本地儲存開銷高達 6 倍！
4. 與 Gemma 4 端側 AI 助教協同：
   • 共享 Tokenizer 與架構，可建構 100% 離線端側 RAG，杜絕端側小模型的幻覺問題。

二、 多平台支援架構 (Flutter Multi-Platform)

本專案支援 Web、Android、iOS、MacOS、Linux、Windows 六大平台，在架構上落實以下分層設計：

flowchart TD
    UserQuery["考生自然語言輸入 / 拓撲圖截圖"] --> ES["EmbeddingService 統一門面"]
    
    subgraph MultiPlatformExecution ["多平台安全執行環境"]
        ES --> Isolate["Background Isolate (Android / iOS / Desktop)<br/>防止 Samsung GC Pause & 主執行緒 ANR"]
        ES --> WebWorker["Async Microtasks (Web 瀏覽器端)<br/>避免阻塞瀏覽器繪製迴圈"]
    end
    
    subgraph MultiDbRouter ["多資料庫語意路由層"]
        Isolate --> Supabase["Supabase (A) & (B)<br/>PostgreSQL pgvector (768 維)"]
        Isolate --> PowerSync["PowerSync 本地端 SQLite / SQLCipher<br/>100% 離線本地 MRL 向量 (128 維)"]
        Isolate --> MongoDB["MongoDB Atlas<br/>Atlas Vector Search 管道"]
        Isolate --> Firebase["Firebase Realtime Database<br/>輕量節點 /questionEmbeddings (防 OOM)"]
    end

    MultiDbRouter --> Results["統一語意搜尋結果 (SemanticSearchResult)"]

1. 執行安全性與防 ANR 規範

• 主執行緒禁令：向量相似度運算（Cosine Similarity）嚴格封裝於 compute(_computeCosineSimilarityIsolate, params) 背景 Isolate 中執行，禁止在 UI 主執行緒進行大矩陣相乘與點積計算。
• Web 端相容：在 kIsWeb 條件下透過非同步微任務（Microtask）執行，並支援 Web 上的 Supabase RPC 與 Cloudflare Worker 呼叫。

2. 多模態拓撲圖檢索（以圖搜題）

• 考生在 QuestionSearchScreen 點擊相機/相簿圖示，選取網路拓撲圖或 Cisco CLI 輸出截圖。
• 客戶端透過 EmbeddingService.getImageEmbedding(bytes) 提取影像的特徵向量，隨即跨模態檢索出最具相關性的 CCNA 題目與官方詳解。

三、 多資料庫架構與整合對照表

本系統支援五大資料庫體系的語意向量檢索，各資料庫的定位與防禦機制如下：

四、 MRL 降維演算法實作

在 EmbeddingService 與 scripts/sync_multidb_embeddings.py 中，全面導入標準 Matryoshka 截斷與 L2 歐幾里得正規化：

$$\mathbf{v}{\text{compact}} = \frac{\mathbf{v}{1:d}}{|\mathbf{v}{1:d}|2} = \frac{\mathbf{v}{1:d}}{\sqrt{\sum{i=1}^{d} v_i^2}}$$

• 768 維：供 Supabase A/B 與雲端 Atlas 進行最高精度向量比對。
• 128 維：截取前 128 個分量並進行單位化，提供給 PowerSync 本地端 SQLite 與 Firebase RTDB，使 1,000+ 道考題的整體向量包體積縮減至僅 ~500 KB，可在手機端瞬時載入並於 5ms 內完成全考庫餘弦相似度掃描！

五、 DevOps 批次同步腳本 (sync_multidb_embeddings.py)

為了維持多資料庫向量一致性，專案提供 scripts/sync_multidb_embeddings.py 批次同步工具。

指令用法

# 1. 測試單一查詢語意比對 (測試 Supabase pgvector RPC)
python scripts/sync_multidb_embeddings.py --limit 5 --test-query "Spanning Tree Protocol loop prevention"

# 2. 全量生成考題向量並同步至所有資料庫 (Supabase + Firebase RTDB + 本地離線包)
python scripts/sync_multidb_embeddings.py --all --sync-all --mrl-dim 128

# 3. 指定特定考科 (如 300-420 或 300-610)
python scripts/sync_multidb_embeddings.py --exam cisco-300-420 --limit 50

輸出產物

• 雲端更新：更新 Supabase questions.embedding 與 Firebase /questionEmbeddings。
• 離線資源打包：自動產出 assets/data/powersync_embeddings_cache.json，並隨 App 編譯打包至 APK / Web / IPA / Desktop 二進位中，實現真正的出廠即離線語意檢索。

六、 安全與隱私規範 (Security & Strict BYOK)

1. 絕不內嵌開發者金鑰：App 二進位與 Git 儲存庫中完全不含任何金鑰，所有 API 呼叫均依賴 ApiKeyService 使用者自備金鑰（BYOK）。
2. 多金鑰輪詢 (Round-Robin)：在呼叫 Google Gemini / EmbeddingGemma API 時，自動在使用者儲存的多把金鑰中進行輪詢與指數回退（Exponential Backoff）重試。
3. 離線隱私保護：當處於離線狀態時，所有考題搜尋均完全在考生本機裝置（PowerSync Local SQLite / Isolate）上運行，無任何網路封包傳輸，符合企業高規格隱私保護。