EmbeddingGemma 2 API: Yerel Dağıtım ve Multimodal Kullanım Alanları

EmbeddingGemma 2 API araması yaparken önce önemli bir ayrımı netleştirmek gerekiyor: Google’ın barındırılan embedding API’si Gemini Embedding 2 olarak sunuluyor. EmbeddingGemma 2 ise esas olarak yerel ve uç cihazlarda çıkarım için tasarlanmış açık bir model. Bu yapı, özel ve multimodal arama senaryoları için cazip; ancak modeli sunacak katmanı sizin seçip işletmeniz gerekiyor.

EmbeddingGemma 2, Google API olarak sunuluyor mu?

EmbeddingGemma 2 resmî olarak yayımlandı; ancak Google’ın güncel yönetilen Gemini API belgelerinde embeddinggemma-2 yerine gemini-embedding-2 adı yer alıyor. EmbeddingGemma 2 model kartı ve Google’ın geliştirici rehberi, Sentence Transformers gibi yerel kütüphanelerle kullanılan indirilebilir bir model tarif ediyor.

Yerel bir /v1/embeddings uç noktası Google Cloud tarafından değil, dağıttığınız çalışma zamanı tarafından sunulur. Aradığınız şey yönetilen hizmetse Gemini Embedding 2 belgelerinde bulut SDK’sı ve istek formatları açıklanıyor. Bu durumda embeddinggemma-2 değil, gemini-embedding-2 kullanmalısınız.

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)

Yönetilen çağrı Google’ın barındırdığı API üzerinden yapılır. Yerel modelde ise geçerli kimlik bilgilerini ve limitleri, kurduğunuz çalışma zamanı belirler.

Yerel modelin içeriğinde ne var?

EmbeddingGemma 2, 740 milyon parametreli multimodal bir embedding modelidir. Tasarımda 270 milyon parametreli metin çekirdeği, isteğe bağlı görüntü ve ses kodlayıcılarından ayrılıyor. Böylece dağıtım sırasında yalnızca ihtiyaç duyulan modaliteler yüklenebiliyor. Google ve DeepMind bu modeli metin üretiminden çok metin, kod, görüntü, video ve ses retrieval işlemleri için konumlandırıyor.

Model kartında farklı modaliteler arasında karşılaştırma yapılabilen ortak bir vektör uzayından bahsediliyor. 740M değeri modelin tamamını ifade ediyor. Google’ın geliştirici rehberinde ise yalnızca gerekli kodlayıcıların kullanılabildiği gösteriliyor. Bu nedenle görüntü ve sesi devre dışı bırakan yalnızca metin odaklı senaryolarda çalışma zamanı belleği ve aktif hesaplama yükü daha düşük olabilir.

Dağıtım hedefinize göre sunum yöntemini seçin

Python uygulaması için Sentence Transformers

Python servisi kuracaksanız resmî olarak belgelenen yol, Sentence Transformers üzerinden google/embeddinggemma-2 kontrol noktasını kullanmak. Bu yöntem; batch işlemleri, cihaz yerleşimi, prompt’lar, normalizasyon ve vektör kırpma üzerinde doğrudan kontrol sağlıyor.

Bir retrieval akışında sorgu ve doküman talimatlarını ayrı tutmak gerekiyor. Google’ın örneklerinde sorgu için arama sorgusu ön eki, dokümanlar içinse title: none | text: ... gibi bir format kullanılıyor. En güvenli yaklaşım, her iki tarafı genel bir çağrıyla embed etmek yerine model.encode içinde ilgili prompt adını belirtmek.

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 seviyesinde kontrol istiyorsanız bu yolu tercih edin. Birden fazla servisin sabit bir sözleşmeye ihtiyaç duyduğu yapılarda ise HTTP sunumu yapan bir çalışma zamanı daha uygun olacaktır.

Hızlı bir yerel REST uç noktası için Ollama

Ollama’nın EmbeddingGemma 2 sayfası, http://localhost:11434/api/embed adresinde basit bir yerel API sunuyor:

ollama pull embeddinggemma-2

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

Ollama; 270m, 440m, 570m ve 740m gibi model etiketleri listeliyor. Görünen paket boyutları yaklaşık 378 MB ile 1,3 GB arasında değişiyor. Bunları tam 740M kontrol noktası için birbirinin yerine kullanılabilen etiketler değil, ayrı paketlenmiş model varyantları olarak değerlendirin. Üretim sözleşmesi oluşturmadan önce kurulu etiketi ve desteklenen giriş modalitelerini doğrulayın. Aile tanımı multimodal olsa da görünen varyant listelerinde her modalite aynı açıklıkta belgelenmiyor.

Ayrıca görev ön eklerinin, model ve boyut eşleşmesinin tutarlı olması gerekiyor. Model değiştirirseniz dizini de yeniden oluşturmalısınız.

Cihaz dağıtımı için uç çalışma zamanları

Google AI Edge, Universal Embedder rehberinde EmbeddingGemma V2’yi belgeliyor. LiteRT-LM embedding modeli belgelerinde ise yerel ve OpenAI uyumlu bir /v1/embeddings sunum modeli açıklanıyor. Çevrimdışı çalışma ve cihaz tarafındaki gizlilik, geleneksel bulut dağıtımının kolaylığından daha önemliyse bu yolu tercih edin.

Sıradan donanım üzerinde çalışan bir sunucu için Sentence Transformers veya Ollama ile başlayın. Çevrimdışı kullanım, gizlilik, düşük başlangıç ayak izi ya da cihaz entegrasyonu temel gereksinim hâline geldiğinde uç cihazlara özel bir çalışma zamanına geçin.

Daha büyük modeli anlamlı kılan multimodal kullanım alanları

EmbeddingGemma 2’nin asıl avantajı, farklı medya türlerini tek bir retrieval uzayında buluşturmanız gereken projelerde ortaya çıkıyor.

Kod arama ve geliştirici odaklı retrieval

Yayımlanan değerlendirme tablosu, belirtilen kod benchmark’ında EmbeddingGemma 2 için 78.68 MTEB Code puanı, EmbeddingGemma 1 içinse 68.76 puan bildiriyor. Bu sonuç; depo araması, API dokümanı retrieval’ı ve kod odaklı RAG için modeli test etmek adına güçlü bir gerekçe. Yine de kullandığınız dil karışımı veya kod tabanı için aynı sonucu garanti etmiyor.

Daha büyük modele geçmek ne zaman mantıklı değil?

Pipeline’ınız yalnızca standart OCR metni alıyorsa multimodal destek, retrieval kalitesini artırmadan karmaşıklık ekleyebilir. Paperless-ngx kullanıcılarından biri bu dengeyi şöyle özetliyor:

“I'm not sure embeddinggemma-2 is any better than regular embeddinggemma for the plain OCR that paperless-ngx sends to the model. seems like a lot more work for the same results.” — u/Great-Cow7256, Reddit

Bu bir benchmark sonucu değil; ancak geçiş kararında doğru testi işaret ediyor: Çalışan, yalnızca metin kullanan dizini yeniden oluşturmadan önce gerçek veri kümeniz üzerindeki retrieval kalitesini karşılaştırın.

Boyut seçimi: 768d, 512d, 256d veya 128d

Google’ın embedding belgelerinde EmbeddingGemma 2 için Matryoshka tarzı kırpma destekleniyor. Yani embedding üretildikten sonra daha küçük bir temsil seçebilirsiniz. Küçük vektörler dizin depolama ve veri aktarım maliyetini azaltır; ancak en agresif ayarda kalite düşer.

Bu değerler Ollama’nın model sayfasındaki yayımlanmış değerlendirme tablosundan alınmıştır. Yeni bir multimodal dizin için 768d ile başlayın. Depolama önemliyse 512d veya 256d tercih edilebilir. 128d seçeneğini ise ancak metin ağırlıklı bir iş yükünde test ettikten sonra kullanın.

Aynı vektör dizininde farklı boyutları karıştırmayın. Mevcut veritabanınız 768 boyutlu vektörler saklıyorsa 256d’ye geçmek, dizindeki dokümanları yeniden embed etmeyi ve dizini baştan oluşturmayı gerektirir. Sorgu vektörleri ile doküman vektörleri aynı model, prompt’lar, normalizasyon ve boyutla üretilmelidir.

Kararı model boyutuna göre değil, iş akışına göre verin

Yönetilen bir Google uç noktası istiyorsanız Gemini Embedding 2 kullanın. Python seviyesinde kontrol için Sentence Transformers, hızlı bir yerel HTTP servisi için Ollama, çevrimdışı cihaz dağıtımı önemliyse AI Edge/LiteRT-LM daha uygun seçeneklerdir.

Veri kümeniz düz OCR metninden oluşuyor ve mevcut dizinin alaka düzeyi hedefini karşılıyorsa daha küçük, yalnızca metin odaklı bir modelle devam edin. EmbeddingGemma 2 multimodal bir mimariyi sadeleştirebilir; ancak yalnızca metin kullanan bir sistemi otomatik olarak iyileştirmez.

EmbeddingGemma 2 API SSS

EmbeddingGemma 2, Gemini API üzerinden kullanılabilir mi?

Google’ın yönetilen Gemini API belgelerinde şu anda gemini-embedding-2 tanımlanıyor. EmbeddingGemma 2 ise öncelikle yerel çıkarım için sunulan açık bir model olarak belgeleniyor. Bununla birlikte yerel çalışma zamanları API uyumlu uç noktalar açabiliyor.

EmbeddingGemma 2 CPU üzerinde çalışabilir mi?

CPU çıkarımı, açıkça CPU arka ucu sunan yerel çalışma zamanlarıyla kullanılabilir. İlgili çalışma zamanı referansı Google’ın AI Edge embedding belgeleri. Performans yine de donanıma, kuantizasyona, batch boyutuna ve kullanılan modaliteye bağlıdır.

Mevcut vektörleri yeniden oluşturmak gerekir mi?

Embedding modelini, görev formatını, normalizasyon politikasını veya vektör boyutunu değiştiriyorsanız genellikle evet. Geçişin yeniden üretilebilir olması için model tanımlayıcısını, boyutu ve ön işleme metadatasını dizinle birlikte saklayın.