Gemini Embedding 2 API Nasıl Kullanılır?

Google'ın Gemini Embedding 2 API'si metin, resim, video, ses ve PDF'ler için gömülü veriler (embeddings) oluşturmanıza olanak tanır. Bu kılavuz, bugün çalıştırabileceğiniz gerçek kod örnekleriyle birlikte API'yi nasıl kullanacağınızı gösterir.

Not: Bu kılavuz, herkese açık önizleme sürümünü (gemini-embedding-2-preview) kapsamaktadır. API genel kullanıma sunulmadan önce değişebilir.

Gemini Embedding 2'nin ne olduğunu önce anlamak ister misiniz? Genel bakışımızı okuyun: Gemini Embedding 2 Nedir?

Ön Koşullar

İhtiyaçlarınız:

• Bir Google AI API anahtarı
• Python 3.7 veya üstü
• Google Generative AI SDK'sı

Kurulum

SDK'yı kurun:

pip install google-generativeai

Temel Kurulum

API anahtarınızı ayarlayın:

import google.generativeai as genai

# API anahtarınızı ayarlayın
genai.configure(api_key='YOUR_API_KEY')

Üretim ortamı için ortam değişkenlerini kullanın:

import os
import google.generativeai as genai

api_key = os.getenv('GEMINI_API_KEY')
genai.configure(api_key=api_key)

Apidog ile Test Etme

Koda dalmadan önce Gemini Embedding API'yi doğrudan Apidog'da test edebilirsiniz:

1. Apidog'da yeni bir istek oluşturun
2. Yöntemi POST olarak ayarlayın
3. URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
4. Başlık ekleyin: x-goog-api-key: YOUR_API_KEY
5. Gövde (JSON):

{
  "content": {
    "parts": [{
      "text": "What is API testing?"
    }]
  }
}

Bu, API anahtarınızın çalıştığını doğrulamanıza ve kod yazmadan önce yanıt yapısını görmenize olanak tanır. Bunu bir test durumu olarak kaydedebilir ve CI/CD hattınızdaki gömülü yanıtları doğrulayabilirsiniz.

Metin Gömülü Verileri Oluşturma

En basit kullanım durumu - metin gömme:

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Gömülü veri oluştur
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='What is the meaning of life?'
)

# Gömülü vektörü al
embedding = result['embedding']
print(f"Gömülü veri boyutları: {len(embedding)}")
print(f"İlk 5 değer: {embedding[:5]}")

Çıktı:

Embedding dimensions: 3072
First 5 values: [0.0234, -0.0156, 0.0891, -0.0423, 0.0567]

Not: Yanıt yapısı, bir float listesi döndüren result['embedding'] şeklindedir. Her float, gömülü vektörün bir boyutunu temsil eder.

Görev Talimatlarını Kullanma

Görev talimatları, gömülü verileri belirli kullanım durumları için optimize eder:

# Arama sorguları için
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='en iyi API test araçları',
    task_type='RETRIEVAL_QUERY'
)

# Dizinlediğiniz belgeler için
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog bir API test platformudur...',
    task_type='RETRIEVAL_DOCUMENT'
)

Mevcut görev türleri:

• RETRIEVAL_QUERY - Arama sorguları için kullanın
• RETRIEVAL_DOCUMENT - Dizinlediğiniz belgeler için kullanın
• SEMANTIC_SIMILARITY - İçerik benzerliğini karşılaştırmak için kullanın
• CLASSIFICATION - Kategorizasyon görevleri için kullanın
• CLUSTERING - Benzer içeriği gruplandırmak için kullanın

Çıkış Boyutlarını Kontrol Etme

Daha küçük boyutlar kullanarak depolama maliyetlerini azaltın:

# Üretim için optimize edildi: 768 boyut
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Metniniz burada',
    output_dimensionality=768
)

# Dengeli: 1536 boyut
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Metniniz burada',
    output_dimensionality=1536
)

# Maksimum kalite: 3072 boyut (varsayılan)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Metniniz burada',
    output_dimensionality=3072
)

Çoğu uygulama için 768 boyut, %75 daha az depolama ile neredeyse en yüksek kaliteyi sunar.

Görselleri Gömme

Görsel arama için görselleri gömün:

import PIL.Image

# Görseli yükle
image = PIL.Image.open('product-photo.jpg')

# Gömülü veri oluştur
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=image
)

embedding = result['embedding']

İstek başına 6 adede kadar görsel gömebilirsiniz:

images = [
    PIL.Image.open('image1.jpg'),
    PIL.Image.open('image2.jpg'),
    PIL.Image.open('image3.jpg')
]

result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=images
)

Videoyu Gömme

Video arama için video içeriğini gömün:

# Önce video dosyasını yükle
video_file = genai.upload_file(path='demo-video.mp4')

# İşlemin bitmesini bekle
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

# Gömülü veri oluştur
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=video_file
)

embedding = result['embedding']

Video limitleri:

• İstek başına maksimum 128 saniye
• Biçimler: MP4, MOV
• Kodekler: H264, H265, AV1, VP9

Sesi Gömme

Transkripsiyon olmadan ses gömme:

# Ses dosyasını yükle
audio_file = genai.upload_file(path='podcast-episode.mp3')

# İşlemin bitmesini bekle
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

# Gömülü veri oluştur
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=audio_file
)

embedding = result['embedding']

Ses limitleri:

• İstek başına maksimum 80 saniye
• Biçimler: MP3, WAV

PDF Belgelerini Gömme

Belge arama için PDF sayfalarını gömün:

# PDF'i yükle
pdf_file = genai.upload_file(path='user-manual.pdf')

# İşlemin bitmesini bekle
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

# Gömülü veri oluştur
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=pdf_file
)

embedding = result['embedding']

PDF limitleri:

• İstek başına maksimum 6 sayfa
• Hem metin hem de görsel içeriği işler

Çok Modlu Gömülü Veriler (Metin + Görsel)

Tek bir gömülü veri içinde birden çok içerik türünü birleştirin:

import PIL.Image

image = PIL.Image.open('product.jpg')
text = "Gürültü engelleme özellikli yüksek kaliteli kablosuz kulaklıklar"

# İkisini birlikte göm
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=[text, image]
)

embedding = result['embedding']

Bu, metin ve görsel arasındaki ilişkileri tek bir gömülü veri içinde yakalar.

Toplu İşleme

Birden çok öğeyi verimli bir şekilde işleyin:

texts = [
    "API testi hakkında ilk belge",
    "Otomasyon hakkında ikinci belge",
    "Performans hakkında üçüncü belge"
]

embeddings = []
for text in texts:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=text,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    embeddings.append(result['embedding'])

print(f"Oluşturulan gömülü veri sayısı: {len(embeddings)}")

Büyük partiler için %50 maliyet tasarrufu sağlayan toplu API'yi kullanın.

Anlamsal Arama Sistemi Oluşturma

İşte anlamsal arama için Gemini Embedding 2 kullanan eksiksiz bir örnek.

Adım 1: Bağımlılıkları Yükleyin

pip install google-generativeai numpy scikit-learn

Adım 2: Belgelerinizi Gömün

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure(api_key='YOUR_API_KEY')

# Örnek belgeler
documents = [
    "Apidog, geliştiriciler için bir API test platformudur",
    "REST API'ler GET, POST, PUT, DELETE gibi HTTP yöntemlerini kullanır",
    "GraphQL, API'ler için bir sorgu dili sağlar",
    "API dokümantasyonu geliştiricilerin uç noktaları anlamasına yardımcı olur",
    "Postman, popüler bir API test aracıdır"
]

# Tüm belgeler için gömülü veri oluştur
doc_embeddings = []
for doc in documents:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    doc_embeddings.append(result['embedding'])

# Numpy dizisine dönüştür
doc_embeddings = np.array(doc_embeddings)

Adım 3: Arama Fonksiyonu Oluşturun

def search(query, top_k=3):
    # Sorguyu göm
    query_result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=query,
        task_type='RETRIEVAL_QUERY',
        output_dimensionality=768
    )
    query_embedding = np.array([query_result['embedding']])

    # Benzerlikleri hesapla
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # En iyi sonuçları al
    top_indices = np.argsort(similarities)[::-1][:top_k]

    results = []
    for idx in top_indices:
        results.append({
            'document': documents[idx],
            'score': similarities[idx]
        })

    return results

Adım 4: Arama Yapın

# Aramayı test et
results = search("API testi için hangi araçları kullanabilirim?")

for i, result in enumerate(results, 1):
    print(f"{i}. Puan: {result['score']:.4f}")
    print(f"   {result['document']}\n")

Çıktı:

1. Score: 0.8234
   Apidog is an API testing platform for developers

2. Score: 0.7891
   Postman is a popular API testing tool

3. Score: 0.6543
   API documentation helps developers understand endpoints

Bir RAG Sistemi Oluşturma

Retrieval-Augmented Generation (Geri Getirme Destekli Üretim) için Gemini Embedding 2 kullanın.

Adım 1: Bilgi Tabanını Kurun

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure(api_key='YOUR_API_KEY')

# Bilgi tabanı
knowledge_base = [
    "Apidog, REST, GraphQL ve WebSocket API'lerini destekler",
    "Test durumları oluşturabilir ve bunları otomatik olarak çalıştırabilirsiniz",
    "Apidog, isteklerinizden API dokümantasyonu oluşturur",
    "Mock sunucuları, arka uç hazır olmadan önce test etmenize yardımcı olur",
    "Ekip işbirliği özellikleri paylaşılan çalışma alanlarını içerir"
]

# Bilgi tabanını göm
kb_embeddings = []
for doc in knowledge_base:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    kb_embeddings.append(result['embedding'])

kb_embeddings = np.array(kb_embeddings)

Adım 2: RAG Sorgu Fonksiyonu Oluşturun

def rag_query(question):
    # 1. Soruyu göm
    query_result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=question,
        task_type='RETRIEVAL_QUERY',
        output_dimensionality=768
    )
    query_embedding = np.array([query_result['embedding']])

    # 2. İlgili bağlamı bul
    similarities = cosine_similarity(query_embedding, kb_embeddings)[0]
    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # 3. Bağlamla birlikte yanıt oluştur
    prompt = f"""Bağlam: {context}

Soru: {question}

Soruyu verilen bağlama göre yanıtlayın."""

    model = genai.GenerativeModel('gemini-2.0-flash-exp')
    response = model.generate_content(prompt)

    return response.text

Adım 3: RAG Sisteminizi Sorgulayın

# RAG'yi test et
answer = rag_query("Apidog dokümantasyon oluşturabilir mi?")
print(answer)

Bu, bilgi tabanınızdan en alakalı bağlamı alır ve doğru yanıtlar oluşturmak için kullanır.

Gömülü Verileri Bir Vektör Veritabanında Saklama

Gömülü verileri depolamak ve sorgulamak için ChromaDB kullanın:

import chromadb
import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# ChromaDB'yi başlat
client = chromadb.Client()
collection = client.create_collection(name="belgelerim")

# Dizinlenecek belgeler
documents = [
    "API testi, uç noktalarınızın doğru çalıştığını garantiler",
    "REST API'ler durum bilgisi olmayan mimari prensiplerini takip eder",
    "GraphQL, istemcilerin belirli verileri istemesine olanak tanır"
]

# Gömülü verileri oluştur ve sakla
for i, doc in enumerate(documents):
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )

    collection.add(
        embeddings=[result['embedding']],
        documents=[doc],
        ids=[f"doc_{i}"]
    )

# Koleksiyonu sorgula
query = "API'mi nasıl test ederim?"
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=query,
    task_type='RETRIEVAL_QUERY',
    output_dimensionality=768
)

results = collection.query(
    query_embeddings=[query_result['embedding']],
    n_results=2
)

print("En iyi sonuçlar:")
for doc in results['documents'][0]:
    print(f"- {doc}")

Hata Yönetimi

API hatalarını sorunsuz bir şekilde ele alın:

import google.generativeai as genai
from google.api_core import exceptions

genai.configure(api_key='YOUR_API_KEY')

def safe_embed(content):
    try:
        result = genai.embed_content(
            model='models/gemini-embedding-2-preview',
            content=content,
            output_dimensionality=768
        )
        return result['embedding']

    except exceptions.InvalidArgument as e:
        print(f"Geçersiz giriş: {e}")
        # Örnek: İçerik çok uzun veya desteklenmeyen format
        return None

    except exceptions.ResourceExhausted as e:
        print(f"Kota aşıldı: {e}")
        # Örnek: Hız limiti aşıldı veya kota tükendi
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"İstek zaman aşımına uğradı: {e}")
        # Örnek: Ağ sorunları veya yavaş yanıt
        return None

    except Exception as e:
        print(f"Beklenmeyen hata: {e}")
        return None

# Kullanımı
embedding = safe_embed("Metniniz burada")
if embedding:
    print("Gömülü veri başarıyla oluşturuldu")
else:
    print("Gömülü veri oluşturulamadı")

Yaygın Hata Mesajları:

• InvalidArgument: Content exceeds maximum length - Giriş boyutunu küçültün
• ResourceExhausted: Quota exceeded - Bekleyin veya planınızı yükseltin
• Unauthenticated: API key not valid - API anahtarınızı kontrol edin
• PermissionDenied: Model not available - Model adını doğrulayın

Hız Sınırlamaları ve En İyi Uygulamalar

Hız Sınırlamaları:

• Ücretsiz katman: Dakikada 60 istek
• Ücretli katman: Planınıza göre daha yüksek limitler

En İyi Uygulamalar:

Uygun boyutları kullanın: Üretim için 768, yalnızca maksimum kaliteye ihtiyacınız olduğunda 3072

Toplu istekler: Mümkün olduğunda birden çok öğeyi birlikte işleyin

Gömülü verileri önbelleğe alın: Aynı içeriği tekrar gömmeyin

Görev talimatlarını kullanın: Belirli kullanım durumları için doğruluğu artırırlar

Hataları yönetin: Üstel geri çekilme ile yeniden deneme mantığını uygulayın

Maliyetleri izleyin: Token kullanımınızı takip edin

Maliyet Optimizasyonu

Bu stratejilerle maliyetleri azaltın:

1. Daha küçük boyutlar kullanın:

# 768 boyut = %75 daha az depolama
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=text,
    output_dimensionality=768
)

2. Acil olmayan görevler için toplu API kullanın:

# Toplu işleme için %50 maliyet tasarrufu
# (Toplu API uygulaması kurulumunuza bağlıdır)

3. Gömülü verileri önbelleğe alın:

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # Önbellek anahtarı oluştur
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # Önbelleği kontrol et
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    # Gömülü veri oluştur
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=content,
        output_dimensionality=768
    )

    # Önbelleğe kaydet
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

Yaygın Sorunlar ve Çözümler

Sorun: "Geçersiz API anahtarı"

# Çözüm: API anahtarınızı kontrol edin
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("API anahtarı ayarlanmadı!")

Sorun: "İçerik çok uzun"

# Çözüm: Uzun metni parçalara ayırın
def chunk_text(text, max_tokens=8000):
    # Basit kelime tabanlı parçalama
    words = text.split()
    chunks = []
    current_chunk = []

    for word in words:
        current_chunk.append(word)
        if len(current_chunk) >= max_tokens:
            chunks.append(' '.join(current_chunk))
            current_chunk = []

    if current_chunk:
        chunks.append(' '.join(current_chunk))

    return chunks

# Her bir parçayı göm
for chunk in chunk_text(long_text):
    embedding = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=chunk
    )

Sorun: "Dosya işleme zaman aşımı"

# Çözüm: Büyük dosyalar için bekleme süresini artırın
import time

video_file = genai.upload_file(path='large-video.mp4')

max_wait = 300  # 5 dakika
waited = 0
while video_file.state.name == 'PROCESSING' and waited < max_wait:
    time.sleep(5)
    waited += 5
    video_file = genai.get_file(video_file.name)

if video_file.state.name == 'PROCESSING':
    print("Dosya işleme zaman aşımına uğradı")
else:
    # Gömülü veri oluştur
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

Sonraki Adımlar

Artık Gemini Embedding 2 API'sini nasıl kullanacağınızı biliyorsunuz. İşte deneyebileceğiniz sonraki adımlar:

1. Dokümantasyonunuz için anlamsal bir arama sistemi oluşturun
2. Çok modlu bağlamla bir RAG uygulaması oluşturun
3. Ürün katalogları için görsel arama uygulayın
4. Podcast veya video içeriği için sesli arama kurun
5. Maliyetleri optimize etmek için farklı boyutlarla deney yapın

API basit olsa da, olasılıklar çok büyük. Metin gömülü verileriyle başlayın, ardından kullanım durumunuz gerektirdiğinde görseller, videolar veya ses ekleyin.

Uygulamanızı test mi ediyorsunuz? Gemini API uç noktalarını test etmek, yanıtları doğrulamak ve gömülü veri hattı testlerinizi otomatikleştirmek için Apidog'u kullanın.