EmbeddingGemma 2 本機部署：遷移風險指南

把 EmbeddingGemma 2 搬到本機，並不代表可以直接取代現有的 embedding 服務。執行環境通常只需要少量應用程式調整，但只要向量表示的契約改變，往往就得重新產生整批向量。最穩妥的做法，是把問題拆成三件事：模型要怎麼執行、現有向量是否仍然相容，以及混合模態檢索是否適合你的資料集。

先用一頁看懂遷移決策

如果你需要在同一個模型家族中處理本機文字、程式碼、圖片、影片或音訊 embedding，而且能接受受控的回填流程，EmbeddingGemma 2 就值得考慮。但不要先把正式環境的 query encoder 換掉，再慢慢補文件向量：embedding 模型本身就是索引 schema 的一部分，即使向量維度看起來一樣也不例外。

Google 的 model card 顯示，在 768 維設定下，MTEB multilingual v2 為 61.36、MTEB code v1 為 78.68、視覺文件檢索的 NDCG@5 為 67.84、影片檢索的 Hit@1 為 50.67，音訊檢索的 MRR@10 則為 69.54。這些數字適合作為參考基準，但不能取代對自家查詢的實測。

切換到 EmbeddingGemma 2，哪些會變、哪些不會？

EmbeddingGemma 2 會把文字、程式碼、圖片、影片與音訊映射到共用的 768 維空間。這個 checkpoint 採用模組化設計；官方開發者指南列出 270M 的純文字設定、440M 的文字加視覺設定、570M 的文字加音訊設定，以及 740M 的完整設定。停用某個 encoder 會減少載入的權重與尖峰記憶體用量，但不會因此自動建立另一個語意空間。

這個差異在遷移時非常關鍵。使用 270M 設定產生的文字 query，可以拿來比對使用完整設定產生的 EmbeddingGemma 2 文件向量，因為 Google 表示這些設定共用相容的向量空間。但這不代表舊有的 EmbeddingGemma 1、Qwen、Nomic 或 API 服務商向量，只因為同樣有 768 個座標，就能安全地拿來搭配 EmbeddingGemma 2 查詢。

任務格式也是契約的一部分。對非對稱檢索而言，EmbeddingGemma 2 預期使用類似 task: search result | query: ... 的搜尋查詢指令，以及 title: ... | text: ... 的文件格式。程式碼檢索也有專用的任務指令。如果舊有 pipeline 使用了不同的前綴、切 chunk 方式、正規化設定或嵌入欄位，就應該把這些變動記錄為新的表示版本，並以遷移流程來驗證。

執行環境怎麼選：先走最單純的本機路徑

先用 Sentence Transformers 確認正確性

官方 model card提供了使用 Sentence Transformers 與 Transformers 執行 google/embeddinggemma-2 的說明。如果需要媒體支援，請安裝多模態 extras：

pip install -U "sentence-transformers[image,audio,video]" transformers

對遷移工作來說，這是最適合拿來當參考基準的路徑，因為 prompt 名稱、截斷、正規化與多模態輸入行為都遵循官方範例。它未必是延遲最低的服務方案，但在開始最佳化之前，能先提供一個可信的基準結果。

最基本的純文字 smoke test 可以這樣寫：

from sentence_transformers import SentenceTransformer

model = SentenceTransformer(
    "google/embeddinggemma-2",
    config_kwargs={"vision_config": None, "audio_config": None},
)
query = model.encode(
    "embedding model migration",
    prompt_name="SearchQuery",
    truncate_dim=256,
    normalize_embeddings=True,
)
document = model.encode(
    "Rebuild vectors when the embedding representation changes.",
    prompt_name="Document",
    truncate_dim=256,
    normalize_embeddings=True,
)
print(model.similarity(query, document).item())

在導入伺服器、量化或向量資料庫之前，先執行這段測試。它可以確認 checkpoint、任務 prompt、向量維度與正規化流程能否正確配合。

確認功能對等後，再考慮生態系執行環境

Google 的開發者指南列出 vLLM、Hugging Face Transformers、Sentence Transformers、SGLang、MLX、Ollama、LM Studio 與 LiteRT，作為支援的開發或部署工具。但這份清單只能代表「可以使用」，不能證明每個執行環境都能提供完全相同的文字、圖片、影片、音訊、交錯輸入、任務前綴、截斷與批次處理組合。

評估每個候選執行環境時，請用真實請求確認五件事：確切的 checkpoint revision、你實際使用的模態輸入、輸出維度、截斷後的正規化，以及 query／document 前綴的處理方式。能快速服務文字，卻無法處理你的視覺文件流程，就不能視為完整模型的等價方案。

精簡原生伺服器是最佳化手段，不是遷移策略

公開的 embeddinggemma.c repository提供專為 EmbeddingGemma 300M 打造的 C11／Metal 風格伺服器，並支援 CPU、Metal、CUDA、ROCm 與 Intel XPU 版本。README 說明了相容 OpenAI 的 /v1/embeddings endpoint、768／512／256／128 維度，以及 278 MB 的 Q4_0 模型下載。該專案公布了一項在 Apple M5 Max 上，針對 llama.cpp build b8981、涵蓋 54 個測試組合的受控比較，幾何平均效能優勢為 1.25 倍；這是專案特定的吞吐量結果，不代表品質比較，也不能證明它與 740M checkpoint 具備多模態功能對等性。

它對遷移最有價值的地方，在於 API 形狀。如果你的應用程式原本就使用 OpenAI 風格的 embeddings，相容 endpoint 的本機伺服器可以減少介面轉接工作。不過，在伺服器的模態支援與前綴行為都符合正式 pipeline 之前，仍應把 Sentence Transformers 的結果保留為正確性基準。

索引重建風險：維度只是其中一條遷移軸線

只要來源到向量的函數改變，就應重新 embedding

只要變更模型家族、模型版本、任務前綴、正規化、切 chunk 方式、截斷策略、嵌入欄位或相似度語意，就應預設需要完整重建。Qdrant 的遷移指南，以及 Nalar 的模型遷移分析，都指出同一個實務重點：文件向量與查詢向量必須屬於同一個表示版本。維度相同，並不能證明語意相容。

不要把舊的 768 維向量直接切成 256 維，就當成 EmbeddingGemma 2 的 256 維向量。EmbeddingGemma 2 的 Matryoshka 輸出是針對支援的截斷尺寸訓練而成，截斷後還必須重新正規化。Model card 提供了以下官方參考分數：

官方 model card 也指出，在 768 維下，視覺文件檢索的 NDCG@5 為 67.84，影片檢索的 Hit@1 為 50.67；應把它們視為完整維度的基準，不要自行推導不存在的低維分數。可靠的判斷方向是：256d 的品質明顯更接近完整維度，而多模態分數在 128d 時下降得更劇烈。請使用官方 checkpoint，按照選定維度重新產生所有向量，不要截取其他模型的向量來代替。

共用的 EmbeddingGemma 2 空間，可能省下不必要的工作

這裡有一個重要例外。如果現有資料集本來就是用 EmbeddingGemma 2 產生向量，而你只是改成載入不同子集的 encoder，Google 的開發者指南表示這些設定共用同一個向量空間。純文字 query 可以匹配完整模型產生的文件向量。換句話說，若只是因為服務程序現在加入了視覺或音訊支援，不一定需要重新產生現有的文字向量。

但新的媒體資料仍然需要產生新向量。純文字索引不可能檢索到從未被 embedding 的圖片、影片或音訊項目。因此，即使 checkpoint 沒有改變，只要要加入多模態檢索，仍然代表資料集需要進行增量遷移。

用藍綠部署或 named vectors 進行切換

對線上系統而言，Qdrant 的遷移模式是很清楚的範本：建立新的 collection、對新資料進行雙寫、從權威來源資料回填、比較 Recall@10／MRR／nDCG@10、切換 alias，並保留舊 collection 以便回滾。Qdrant 指南使用 1.19.0、512 維範例與每批 100 個 points；這些都是範例，不是 EmbeddingGemma 2 的必要設定。

如果向量資料庫支援 named vectors，而且更新流程能一致地寫入兩種表示，就可以把新舊向量放在同一個 collection。不過，Weaviate 的 vectorizer 遷移指南建議正式環境採用 collection alias，因為可以保留舊 collection 以便立即回滾，驗證完成後再刪除。另一種做法是在現有 collection 中加入新的向量，雖然適合拿來比較，但可能永久增加儲存需求，不太適合作為乾淨的最終狀態。

混合模態品質：驗證模型真正改變的那些資料切片

EmbeddingGemma 2 的共用空間只有在檢索行為符合你的資料時才有價值。純文字 benchmark 可以確認文字搜尋沒有因遷移而失效，卻可能完全漏掉 PDF 頁面、圖表、圖片說明、影片畫格、音訊片段或交錯資料的問題。

先分別建立有標註的資料切片：

1. 文字 query → 文字 chunk。
2. 程式碼 query → 程式碼 chunk。
3. 文字 query → 圖片或視覺文件。
4. 文字 query → 影片畫格或音訊片段。
5. 文字加媒體的混合 query → 混合文件。
6. 跨語言 query → 你實際服務語言中的文件。

第一次做多模態基準時，建議保留 768d 或 512d。官方 model card 將每張圖片、每個影片畫格與每秒音訊分別配置為 280、140 與 25 個 tokens，共用 8,192 tokens 的 context。混合輸入會消耗同一份預算，因此同時包含文字、圖片與影片的資料，比單一模態輸入更少可分配給各個元件的空間。

Model card 也指出，128d 對多模態任務造成的品質下降，比純文字任務更明顯。因此，128d 可以作為大型文字索引的第一階段候選設定，但不應直接當成混合媒體資料庫的預設值。在接受它帶來的儲存節省之前，先用實際的視覺文件與跨模態查詢測試 256d。

請在完全相同的查詢上，將統一的 EmbeddingGemma 2 pipeline 與目前分開處理文字／圖片的 pipeline 進行比較；不要只因為模型採用共用空間，就推斷它的混合模態品質。

既有 RAG 系統的分階段部署方案

1. 盤點目前的契約。記錄模型 ID、checkpoint revision、前綴、切 chunk 方式、維度、距離計算指標、正規化、來源欄位，以及目前已建立索引的所有模態。
2. 建立具代表性的評估集。除了 Recall@k、MRR 或 nDCG 目標，也要分別涵蓋文字、程式碼、視覺文件、音訊、影片、語言與長查詢切片。
3. 建立本機基準。先用 Sentence Transformers 處理同一份資料集。記錄 embedding 延遲、搜尋延遲、記憶體、索引大小、錯誤，以及分數分布。
4. 建立版本化的候選索引。保留穩定的文件 ID，並把權威來源的文字／媒體資料放在向量儲存之外，確保回填流程可重現。
5. 在回填期間對齊寫入。使用來源快照加上變更重播，或把新的與更新後的資料同時寫入兩個表示版本。
6. 對正式環境查詢做 shadow test。比較排序結果、空結果率、延遲與標註相關性，但不要改變使用者實際看到的答案。
7. 原子式切換。將 EmbeddingGemma 2 query encoder 與相符的索引，綁定在同一個版本或 alias 下。絕對不要讓新的 query encoder 在中間狀態搭配舊索引上線。
8. 保留回滾能力。在代表性流量通過驗收門檻前，保留舊索引與查詢路徑；確認完成後，再停止雙寫並回收儲存空間。

FAQ

EmbeddingGemma 2 可以只用 CPU 執行嗎？

可以，只要使用支援 CPU 的執行環境。Model card 建議在無法使用 bfloat16 時改用 float32，而純文字設定的規模為 270M 參數。CPU 吞吐量會受到執行環境、精度、批次大小與硬體影響，因此應該用自己的資料集測量，不要直接套用 GPU 數據。

執行環境的選擇，本質上是在參考實作的正確性、功能對等性、服務效率，以及驗證新檢索版本的成本之間取捨。