EmbeddingGemma 2 API：本機部署與多模態應用場景

搜尋 EmbeddingGemma 2 API 時，最先要釐清的是：Google 提供的託管嵌入 API 叫做 Gemini Embedding 2，而 EmbeddingGemma 2 則是以本機與邊緣推論為主的開放模型。這讓它很適合用來打造重視隱私的多模態搜尋系統，但代價是你必須自行選擇並維運模型服務層。

EmbeddingGemma 2 有 Google API 可以直接呼叫嗎？

EmbeddingGemma 2 已正式發布，不過 Google 目前的 Gemini API 託管文件列出的是 gemini-embedding-2，而不是 embeddinggemma-2。EmbeddingGemma 2 模型卡與 Google 開發者指南介紹的是可下載、搭配 Sentence Transformers 等本機函式庫使用的模型。

本機的 /v1/embeddings 端點，是由你部署的執行環境提供，而不是 Google Cloud 提供。如果你要找的是託管服務，請參考 Gemini Embedding 2 文件中的雲端 SDK 與請求格式；模型名稱應使用 gemini-embedding-2，不是 embeddinggemma-2。

from google import genai

client = genai.Client()
result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="A private semantic search service",
)
print(result.embeddings)

上述託管呼叫使用的是 Google 提供的雲端 API；本機模型則會受到你所部署之執行環境的認證方式與限制影響。

EmbeddingGemma 2 的模型組成與規格

EmbeddingGemma 2 是一款擁有 740M 參數的多模態嵌入模型。它將 270M 的文字核心與可選用的視覺、音訊編碼器分開設計，因此部署時可以只載入實際需要的模態。Google 與 DeepMind 將它定位在文字、程式碼、圖片、影片與音訊檢索，而不是文字生成。

模型卡指出，EmbeddingGemma 2 使用共享向量空間來進行跨模態比較。740M 是完整模型的參數量；Google 的開發者指南則展示了選擇性載入編碼器的方式。因此，在只處理文字、排除視覺與音訊的情況下，執行期間的記憶體用量與實際運算量都可能更低。

依照部署目標選擇服務方式

Python 應用程式：使用 Sentence Transformers

如果你要建立 Python 服務，官方文件所記載的做法，是透過 Sentence Transformers 載入 google/embeddinggemma-2 checkpoint。這條路線可以直接控制批次處理、裝置配置、提示詞、正規化與向量截斷。

檢索流程應該為查詢與文件使用不同指令。Google 的範例會在查詢前加上搜尋查詢前綴，文件則採用類似 title: none | text: ... 的格式。比較穩妥的做法，是在 model.encode 中指定對應的 prompt name，而不是用一個泛用呼叫來處理兩邊的內容。

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("google/embeddinggemma-2")

query_vector = model.encode(
    "How do I rotate an API key?",
    prompt_name="query",
    normalize_embeddings=True,
)
document_vectors = model.encode(
    [
        "title: API keys | text: Rotate keys from the security settings page.",
        "title: Billing | text: Download invoices from the billing page.",
    ],
    prompt_name="document",
    normalize_embeddings=True,
)

如果你需要 Python 層級的細緻控制，選 Sentence Transformers；若有多個服務需要穩定一致的介面，則應改用提供 HTTP 服務的執行環境。

Ollama：快速建立本機 REST 端點

Ollama 的 EmbeddingGemma 2 頁面提供簡單的本機 API，端點是 http://localhost:11434/api/embed：

ollama pull embeddinggemma-2

curl http://localhost:11434/api/embed \\
  -d '{
    "model": "embeddinggemma-2",
    "input": "A private semantic search service"
  }'

Ollama 列出的模型標籤包括 270m、440m、570m 與 740m；可見套件大小約介於 378 MB 到 1.3 GB。這些應視為分開封裝的模型版本，不要把它們當成完整 740M checkpoint 的可互換標籤。建立正式環境的服務契約前，請先確認實際安裝的標籤與支援的輸入模態：整個模型家族雖然主打多模態，但目前可見的版本列表並未同樣清楚地說明每一種模態。

此外，任務前綴、模型與向量維度必須保持一致；一旦更換模型，也要重建索引。

邊緣執行環境：部署到裝置端

Google AI Edge 在Universal Embedder 指南中介紹 EmbeddingGemma V2，而 LiteRT-LM 嵌入模型文件則說明了本機、相容 OpenAI 的 /v1/embeddings 服務模式。如果你更重視離線運作與裝置端隱私，而不是傳統雲端部署的便利性，這條路線會更合適。

若是在一般硬體上架設伺服器，建議先從 Sentence Transformers 或 Ollama 開始。只有在離線運作、隱私、啟動資源占用或裝置整合屬於首要需求時，才進一步採用邊緣專用執行環境。

哪些多模態應用值得採用更大的模型？

當專案需要讓不同媒體類型共用同一個檢索空間時，EmbeddingGemma 2 的優勢才最明顯。

程式碼搜尋與開發者檢索

已公開的評測表顯示，在引用的程式碼基準測試中，EmbeddingGemma 2 的 MTEB Code 分數為 78.68，EmbeddingGemma 1 則為 68.76。這是值得測試它用於程式碼庫搜尋、API 文件檢索與程式碼導向 RAG 的理由，但不代表它一定適合你的語言組合或程式碼庫。

什麼情況下不值得換成更大的模型？

如果你的流程只會接收一般 OCR 文字，多模態支援可能只會增加複雜度，卻不會帶來更好的檢索品質。一位 Paperless-ngx 使用者如此形容這項取捨：

「我不確定 embeddinggemma-2 處理 paperless-ngx 傳給模型的純 OCR 文字時，是否真的比一般的 embeddinggemma 好。感覺只是多做了很多工作，結果卻一樣。」— u/Great-Cow7256，Reddit

這不是基準測試結果，但它點出了正確的遷移判斷方式：在重建現有的純文字索引前，先用實際資料集比較兩者的檢索品質。

向量維度怎麼選：768d、512d、256d 還是 128d？

Google 的嵌入文件說明，EmbeddingGemma 2 支援類 Matryoshka 的截斷方式，因此可以在編碼後選擇較小的向量表示。向量越小，索引儲存空間與傳輸量就越低，但在最激進的設定下，品質也會明顯下降。

以上數據整理自 Ollama 模型頁面公開的評測表。建立新的多模態索引時，建議先從 768d 開始；若儲存空間是主要考量，可選 512d 或 256d；至於 128d，則應等到文字占比較高的工作負載完成測試後再考慮。

同一個向量索引中不能混用不同維度。如果現有資料庫儲存的是 768 維向量，改成 256d 就必須重新嵌入已建立索引的文件並重建索引。查詢向量與文件向量必須使用相同的模型、提示詞、正規化方式與維度。

別只看模型大小，應該依照工作流程做決定

需要 Google 託管端點時，選 Gemini Embedding 2。需要 Python 層級控制時，選 Sentence Transformers；想快速建立本機 HTTP 服務，選 Ollama；若重點是離線裝置部署，則選 AI Edge/LiteRT-LM。

如果資料集只是一般 OCR 文字，而現有索引已達到相關性目標，就保留較小的純文字模型。EmbeddingGemma 2 可以簡化多模態架構，但不會自動讓純文字架構變得更好。

EmbeddingGemma 2 API 常見問題

EmbeddingGemma 2 可以透過 Gemini API 使用嗎？

Google 目前的 Gemini API 託管文件列出的是 gemini-embedding-2。EmbeddingGemma 2 主要被文件定位為可在本機推論的開放模型，不過本機執行環境可以提供相容 API 的端點。

EmbeddingGemma 2 可以在 CPU 上執行嗎？

只要本機執行環境明確提供 CPU backend，就可以使用 CPU 推論；Google 的 AI Edge 嵌入文件是相關的執行環境參考。實際效能仍取決於硬體、量化方式、批次大小與使用的模態。

現有向量需要重新建立嗎？

通常需要，尤其是在更換嵌入模型、任務格式、正規化策略或向量維度時。請將模型識別名稱、維度與前處理中繼資料一併保存，讓日後的索引遷移可以重現。