EmbeddingGemma 2’yi Yerelde Çalıştırma: Geçiş Riskleri Rehberi

EmbeddingGemma 2’yi yerelde çalıştırmak, mevcut embedding servisinin otomatik olarak birebir alternatifi olduğu anlamına gelmez. Uygulama tarafında çok az değişiklikle çalışma zamanını değiştirebilirsiniz; ancak vektörlerin temsil sözleşmesi değişiyorsa çoğu durumda tüm vektörleri yeniden oluşturmanız gerekir. En güvenli yaklaşım, üç kararı birbirinden ayırmaktır: modelin nasıl çalışacağı, mevcut vektörlerin uyumlu kalıp kalmadığı ve karma modaliteli aramanın veri kümeniz için yeterince iyi sonuç verip vermediği.

Geçiş kararını tek bakışta verin

Tek bir model ailesi içinde yerel metin, kod, görsel, video ve ses embedding’lerine ihtiyacınız varsa ve kontrollü bir geri doldurma sürecini göze alabiliyorsanız EmbeddingGemma 2 mantıklı bir tercih. Üretimde önce sorgu kodlayıcıyı değiştirip belgeleri daha sonra “yetiştirmeye” çalışmayın. Embedding modeli, vektör boyutu tanıdık görünse bile indeks şemasının bir parçasıdır.

Google’ın model kartına göre 768 boyutta MTEB multilingual v2 skoru 61.36, MTEB code v1 skoru 78.68, görsel belge aramada NDCG@5 skoru 67.84, video aramada Hit@1 skoru 50.67 ve ses aramada MRR@10 skoru 69.54. Bunlar yararlı referans değerlerdir; kendi sorgularınızla yapacağınız testlerin yerini tutmaz.

EmbeddingGemma 2’ye geçince ne değişir, ne aynı kalır?

EmbeddingGemma 2; metin, kod, görsel, video ve sesi ortak bir 768 boyutlu uzaya taşır. Checkpoint modülerdir: resmî geliştirici rehberinde yalnızca metin için 270M, metin ve görsel için 440M, metin ve ses için 570M, tüm özelliklerin etkin olduğu yapı içinse 740M parametreli konfigürasyonlar açıklanıyor. Bir kodlayıcıyı devre dışı bırakmak yüklenen ağırlıkları ve tepe bellek kullanımını azaltır; tek başına yeni bir anlamsal uzay oluşturmaz.

Geçiş sırasında kritik nokta bu ayrım. Google, bu konfigürasyonların uyumlu bir vektör uzayını paylaştığını belirttiği için 270M konfigürasyonuyla üretilmiş bir metin sorgusu, tam konfigürasyonla oluşturulmuş bir EmbeddingGemma 2 belge embedding’iyle karşılaştırılabilir. Ancak bu durum, eski bir EmbeddingGemma 1, Qwen, Nomic veya API sağlayıcısına ait vektörün yalnızca 768 koordinata sahip olduğu için EmbeddingGemma 2 ile güvenle sorgulanabileceği anlamına gelmez.

Görev biçimlendirmesi de sözleşmenin parçasıdır. Asimetrik aramada EmbeddingGemma 2, task: search result | query: ... gibi bir arama sorgusu talimatı ve title: ... | text: ... biçiminde bir belge yapısı bekler. Kod aramanın kendine ait görev talimatı vardır. Eski hattınız farklı ön ekler, parçalama kuralları, normalizasyon veya farklı alanlar kullanıyorsa bunları yeni bir temsil sürümü olarak kaydedin ve geçiş kapsamında doğrulayın.

Çalışma zamanı seçimi: yerelde en dar kapsamlı yoldan başlayın

Doğruluk için önce Sentence Transformers

Resmî model kartında google/embeddinggemma-2 için Sentence Transformers ve Transformers kullanımı belgeleniyor. Medya desteğine ihtiyacınız varsa multimodal ek paketleri kurun:

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

Bu, geçiş için en güvenilir başlangıç yoludur; prompt adları, kırpma, normalizasyon ve multimodal girdi davranışı resmî örneklerle uyumludur. En düşük gecikmeli servis seçeneği olmayabilir, ancak optimizasyona geçmeden önce güvenilir bir temel sonuç sunar.

Yalnızca metin kullanan en basit duman testi şöyle görünebilir:

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())

Sunucu, quantization veya vektör veritabanı eklemeden önce bu testi çalıştırın. Böylece checkpoint’in, görev prompt’larının, boyut ayarının ve normalizasyon adımının birlikte doğru çalıştığını doğrulayabilirsiniz.

Ekosistem çalışma zamanlarına özellik eşitliğini kontrol ettikten sonra geçin

Google’ın geliştirici rehberinde vLLM, Hugging Face Transformers, Sentence Transformers, SGLang, MLX, Ollama, LM Studio ve LiteRT desteklenen geliştirme veya dağıtım araçları arasında listeleniyor. Bu listeyi her çalışma zamanının metin, görsel, video, ses, iç içe girdi, görev ön ekleri, kırpma ve batch işlemlerinin aynı kombinasyonunu sunduğuna dair kanıt olarak değil, kullanılabilirlik göstergesi olarak değerlendirin.

Aday çalışma zamanlarının her biri için gerçek bir istekle şu beş noktayı doğrulayın: kullanılan checkpoint revizyonu, ihtiyaç duyduğunuz modalite girdileri, çıktı boyutları, kırpma sonrası normalizasyon ve sorgu/belge ön eklerinin davranışı. Metni hızlıca sunan ancak görsel belge hattınızı desteklemeyen bir çalışma zamanı, tam modelle eşdeğer değildir.

Kompakt yerel sunucu optimizasyondur, geçiş planı değil

Herkese açık embeddinggemma.c deposu, EmbeddingGemma 300M için özelleştirilmiş, C11/Metal tarzı bir sunucu sunuyor. CPU, Metal, CUDA, ROCm ve Intel XPU varyantları bulunuyor. README dosyasında OpenAI uyumlu /v1/embeddings uç noktası, 768/512/256/128 boyut seçenekleri ve 278 MB boyutunda Q4_0 model indirmesi belgeleniyor. Proje, Apple M5 Max üzerinde llama.cpp build b8981’e karşı 54 hücrelik kontrollü bir karşılaştırmada geometrik ortalama açısından 1.25× avantaj bildirmiş durumda. Bunlar projeye özel aktarım hızı sonuçlarıdır; kalite karşılaştırması veya 740M checkpoint’iyle multimodal özellik eşitliğinin kanıtı değildir.

Geçiş açısından asıl faydalı özellik API biçimi. Uygulamanız zaten OpenAI tarzı embedding’lerle konuşuyorsa uç nokta uyumlu yerel bir sunucu adaptör işini azaltabilir. Yine de sunucunun modalite ve ön ek davranışı üretim hattınızla eşleşene kadar Sentence Transformers çıktısını doğruluk referansı olarak saklayın.

İndeks yeniden oluşturma riski: boyut, geçiş eksenlerinden yalnızca biri

Kaynaktan vektöre giden işlev değişiyorsa yeniden embedding oluşturun

Model ailesi, model sürümü, görev ön eki, normalizasyon, parçalama, kırpma politikası, embedding’e dahil edilen alanlar veya benzerlik semantiği değiştiğinde tam bir yeniden oluşturma süreci planlayın. Qdrant’ın geçiş rehberiyle Nalar tarafından yayımlanan model geçişi analizi aynı operasyonel noktaya dikkat çekiyor: belge ve sorgu vektörleri aynı temsil sürümüne ait olmalı. Boyutların eşit olması anlamsal uyumluluğu kanıtlamaz.

Eski 768 boyutlu bir vektörü kesip bunu 256 boyutlu EmbeddingGemma 2 vektörü olarak kullanmayın. EmbeddingGemma 2’nin Matryoshka çıktıları, desteklenen kırpma boyutları için eğitilmiştir ve kırpma sonrasında yeniden normalize edilmelidir. Model kartındaki resmî referans skorları şöyle:

Resmî model kartı ayrıca 768 boyutta görsel belge arama için 67.84 NDCG@5 ve video arama için 50.67 Hit@1 bildiriyor. Bunları tam boyutlu temel değerler olarak kullanın; düşük boyutlar için değer uydurmayın. Güvenilir çıkarım şu yönde: 256d, tam kaliteye 128d’den belirgin biçimde daha yakındır ve multimodal skorlar 128d’de daha sert düşer. Başka bir modelin vektörlerini kırpmak yerine seçtiğiniz boyutta tüm vektörleri resmî checkpoint’i kullanarak yeniden üretin.

Paylaşılan EmbeddingGemma 2 uzayı gereksiz işi azaltabilir

Burada önemli bir istisna var. Mevcut veri kümeniz zaten EmbeddingGemma 2 ile oluşturulduysa ve yalnızca farklı bir encoder alt kümesi yüklemeye geçiyorsanız Google’ın geliştirici rehberine göre bu konfigürasyonlar aynı vektör uzayını paylaşıyor. Yalnızca metin kullanan bir sorgu, tam modelle oluşturulmuş bir belge vektörüyle eşleşebilir. Bu durumda yalnızca servis süreci artık görsel veya ses desteği yüklediği için mevcut metin vektörlerini yeniden üretmeniz gerekmeyebilir.

Ancak medya içeren yeni kayıtlar için yine yeni vektörler oluşturmanız gerekir. Hiç embedding’i oluşturulmamış bir görsel, video veya ses öğesi yalnızca metinlerden oluşan bir indekste aranamaz. Dolayısıyla model checkpoint’i değişmese bile multimodal aramaya geçiş, veri kümesi açısından kademeli bir geçiş sürecidir.

Blue-green veya named-vector geçişi kullanın

Canlı bir sistem için Qdrant’ın geçiş modeli net bir şablon sunuyor: yeni bir koleksiyon oluşturun, yeni kayıtları iki tarafa birden yazın, yetkili kaynak verilerinden geri doldurun, Recall@10/MRR/nDCG@10 değerlerini karşılaştırın, bir alias’ı değiştirin ve geri dönüş için eski koleksiyonu koruyun. Qdrant’ın rehberinde version 1.19.0, 512 boyutlu bir örnek ve 100 puanlık batch’ler kullanılıyor; bunlar EmbeddingGemma 2 için zorunlu değerler değil, örnek ayarlardır.

Named-vector yaklaşımı, veritabanınız destekliyorsa ve güncelleme hattınız her iki temsili de tutarlı biçimde yazıyorsa eski ve yeni temsilleri aynı koleksiyonda tutabilir. Weaviate’ın vectorizer geçiş rehberi, üretimde koleksiyon alias’larını öneriyor; böylece doğrulama tamamlanana kadar eski koleksiyon korunabilir ve gerektiğinde anında geri dönülebilir. Alternatif olarak mevcut koleksiyona yeni bir vektör eklemek mümkündür; ancak bu kalıcı biçimde depolama kullanımını artırabilir ve temiz bir nihai durumdan çok karşılaştırma amacıyla daha uygundur.

Karma modalite kalitesi: modelin değiştirdiği dilimleri ayrı ayrı doğrulayın

EmbeddingGemma 2’nin ortak uzayı ancak arama davranışı verilerinizle örtüşüyorsa değerlidir. Yalnızca metin benchmark’ı, metin aramasının bozulmadığını gösterebilir; ancak PDF sayfaları, grafikler, görsel açıklamaları, video kareleri, ses klipleri veya iç içe geçmiş kayıtlarındaki sorunları gözden kaçırabilir.

Etiketlenmiş ayrı dilimlerle başlayın:

1. Metin sorgusu → metin parçası.
2. Kod sorgusu → kod parçası.
3. Metin sorgusu → görsel veya görsel belge.
4. Metin sorgusu → video karesi veya ses bölümü.
5. Karma metin ve medya sorgusu → karma belge.
6. Diller arası sorgu → hizmet verdiğiniz dillerdeki belge.

İlk multimodal temel değer olarak 768d veya 512d kullanın. Resmî model kartına göre ortak 8.192 token bağlamında her görsel için 280 token, her video karesi için 140 token ve sesin her saniyesi için 25 token ayrılıyor. Karma girdiler aynı bütçeyi paylaşır; bu nedenle metin, görsel ve video içeren bir kayıtta her bileşene, yalnızca tek modaliteli bir girdiye kıyasla daha az alan kalır.

Model kartı, 128d’nin multimodal görevlerde kaliteyi metin görevlerine kıyasla daha fazla düşürdüğünü de belirtiyor. Bu nedenle 128d, büyük bir metin indeksi için ilk aşamada değerlendirilebilecek bir aday olabilir; ancak karma medya arşivleri için varsayılan tercih değildir. Depolama tasarrufunu kabul etmeden önce 256d’yi gerçek görsel belge ve modaliteler arası sorgularınızla test edin.

Birleşik EmbeddingGemma 2 hattını mevcut ayrı metin/görsel hattınızla aynı sorgular üzerinde karşılaştırın; multimodal kaliteyi yalnızca modelin ortak uzay mimarisine bakarak varsaymayın.

Mevcut bir RAG sistemi için aşamalı dağıtım planı

1. Mevcut sözleşmeyi çıkarın. Model kimliğini, checkpoint revizyonunu, ön ekleri, parçalama yöntemini, boyutları, metriği, normalizasyonu, kaynak alanlarını ve hâlihazırda indekslenen tüm modaliteleri kaydedin.
2. Temsili bir değerlendirme kümesi oluşturun. Recall@k, MRR veya nDCG hedeflerinin yanı sıra metin, kod, görsel belge, ses, video, dil ve uzun sorgu dilimlerini ayrı ayrı ekleyin.
3. Yerel temel değeri belirleyin. Aynı veri kümesini önce Sentence Transformers üzerinden çalıştırın. Embedding gecikmesini, arama gecikmesini, bellek kullanımını, indeks boyutunu, hataları ve skor dağılımlarını kaydedin.
4. Sürümlendirilmiş aday indeksi oluşturun. Geri doldurmanın tekrarlanabilir olması için sabit belge kimliklerini ve yetkili kaynak metin/medya verilerini vektör deposunun dışında tutun.
5. Geri doldurma sırasında yazma işlemlerini eşitleyin. Bir kaynak snapshot’ı ve değişikliklerin yeniden oynatılmasını kullanın veya yeni ve güncellenen kayıtları her iki temsil sürümüne de yazın.
6. Üretim sorgularını gölgede çalıştırın. Kullanıcıya gösterilen yanıtları değiştirmeden sıralanmış sonuçları, boş sonuç oranlarını, gecikmeyi ve etiketlenmiş alaka düzeyini karşılaştırın.
7. Atomik geçiş yapın. EmbeddingGemma 2 sorgu kodlayıcısını ve onunla eşleşen indeksi tek bir sürüm veya alias altında birlikte etkinleştirin. Yeni sorgu kodlayıcıyı ara aşama olarak eski indeksle kesinlikle çalıştırmayın.
8. Geri dönüş seçeneğini koruyun. Temsili trafik kabul eşiklerini geçene kadar eski indeksi ve sorgu hattını saklayın; ardından çift yazmayı durdurup depolama alanını geri kazanın.

Sık sorulan sorular

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

Evet, CPU destekli bir çalışma zamanıyla çalışabilir. Model kartı, bfloat16 kullanılamadığında float32 öneriyor; yalnızca metin konfigürasyonu 270M parametre içeriyor. CPU aktarım hızı çalışma zamanına, hassasiyet ayarına, batch boyutuna ve donanıma bağlıdır. Bu nedenle GPU değerlerini referans almak yerine kendi veri kümeniz üzerinde ölçüm yapın.

Çalışma zamanı seçimi; referans doğruluğu, özellik eşitliği, servis verimliliği ve yeni bir arama sürümünü doğrulamanın maliyeti arasında yapılan bir tercihtir.