Gemini Embedding 2 API: Anleitung zur Nutzung

Die Gemini Embedding 2 API von Google ermöglicht Ihnen die Generierung von Embeddings für Text, Bilder, Videos, Audio und PDFs. Dieser Leitfaden zeigt Ihnen, wie Sie sie verwenden, mit realen Codebeispielen, die Sie noch heute ausführen können.

Hinweis: Dieser Leitfaden behandelt die öffentliche Vorschauversion (gemini-embedding-2-preview). Die API kann sich vor der allgemeinen Verfügbarkeit noch ändern.

Möchten Sie zuerst verstehen, was Gemini Embedding 2 ist? Lesen Sie unsere Übersicht: Was ist Gemini Embedding 2?

Voraussetzungen

Sie benötigen:

• Einen Google AI API-Schlüssel
• Python 3.7 oder höher
• Das Google Generative AI SDK

Installation

Installieren Sie das SDK:

pip install google-generativeai

Grundlegende Einrichtung

Richten Sie Ihren API-Schlüssel ein:

import google.generativeai as genai

# Richten Sie Ihren API-Schlüssel ein
genai.configure(api_key='YOUR_API_KEY')

Für die Produktion verwenden Sie Umgebungsvariablen:

import os
import google.generativeai as genai

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

Testen mit Apidog

Bevor Sie in den Code eintauchen, können Sie die Gemini Embedding API direkt in Apidog testen:

1. Erstellen Sie eine neue Anfrage in Apidog
2. Setzen Sie die Methode auf POST
3. URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
4. Fügen Sie den Header hinzu: x-goog-api-key: YOUR_API_KEY
5. Body (JSON):

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

Damit können Sie überprüfen, ob Ihr API-Schlüssel funktioniert und die Antwortstruktur sehen, bevor Sie Code schreiben. Sie können dies als Testfall speichern und Embedding-Antworten in Ihrer CI/CD-Pipeline validieren.

Text-Embeddings generieren

Der einfachste Anwendungsfall – Text einbetten:

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Embedding generieren
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='What is the meaning of life?'
)

# Den Embedding-Vektor abrufen
embedding = result['embedding']
print(f"Embedding dimensions: {len(embedding)}")
print(f"First 5 values: {embedding[:5]}")

Output:

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

Hinweis: Die Antwortstruktur ist result['embedding'], das eine Liste von Gleitkommazahlen zurückgibt. Jede Gleitkommazahl repräsentiert eine Dimension des Embedding-Vektors.

Verwenden von Aufgabenanweisungen

Aufgabenanweisungen optimieren Embeddings für spezifische Anwendungsfälle:

# Für Suchanfragen
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='best API testing tools',
    task_type='RETRIEVAL_QUERY'
)

# Für Dokumente, die Sie indizieren
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog is an API testing platform...',
    task_type='RETRIEVAL_DOCUMENT'
)

Verfügbare Aufgabentypen:

• RETRIEVAL_QUERY - Für Suchanfragen verwenden
• RETRIEVAL_DOCUMENT - Für zu indizierende Dokumente verwenden
• SEMANTIC_SIMILARITY - Zum Vergleich der Inhaltsähnlichkeit verwenden
• CLASSIFICATION - Für Kategorisierungsaufgaben verwenden
• CLUSTERING - Zum Gruppieren ähnlicher Inhalte verwenden

Ausgabedimensionen steuern

Reduzieren Sie Speicherkosten durch die Verwendung kleinerer Dimensionen:

# Produktionsoptimiert: 768 Dimensionen
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Ihr Text hier',
    output_dimensionality=768
)

# Ausgewogen: 1536 Dimensionen
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Ihr Text hier',
    output_dimensionality=1536
)

# Maximale Qualität: 3072 Dimensionen (Standard)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Ihr Text hier',
    output_dimensionality=3072
)

Für die meisten Anwendungen bieten 768 Dimensionen eine nahezu maximale Qualität bei 75% weniger Speicherplatz.

Bilder einbetten

Bilder für die visuelle Suche einbetten:

import PIL.Image

# Bild laden
image = PIL.Image.open('product-photo.jpg')

# Embedding generieren
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=image
)

embedding = result['embedding']

Sie können bis zu 6 Bilder pro Anfrage einbetten:

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
)

Videos einbetten

Videoinhalte für die Videosuche einbetten:

# Videodatei zuerst hochladen
video_file = genai.upload_file(path='demo-video.mp4')

# Auf Verarbeitung warten
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

# Embedding generieren
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=video_file
)

embedding = result['embedding']

Videolimits:

• Maximal 128 Sekunden pro Anfrage
• Formate: MP4, MOV
• Codecs: H264, H265, AV1, VP9

Audio einbetten

Audio ohne Transkription einbetten:

# Audiodatei hochladen
audio_file = genai.upload_file(path='podcast-episode.mp3')

# Auf Verarbeitung warten
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

# Embedding generieren
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=audio_file
)

embedding = result['embedding']

Audiolimits:

• Maximal 80 Sekunden pro Anfrage
• Formate: MP3, WAV

PDF-Dokumente einbetten

PDF-Seiten für die Dokumentensuche einbetten:

# PDF hochladen
pdf_file = genai.upload_file(path='user-manual.pdf')

# Auf Verarbeitung warten
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

# Embedding generieren
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=pdf_file
)

embedding = result['embedding']

PDF-Limits:

• Maximal 6 Seiten pro Anfrage
• Verarbeitet sowohl Text- als auch visuellen Inhalt

Multimodale Embeddings (Text + Bild)

Kombinieren Sie mehrere Inhaltstypen in einem Embedding:

import PIL.Image

image = PIL.Image.open('product.jpg')
text = "Hochwertige kabellose Kopfhörer mit Geräuschunterdrückung"

# Beide zusammen einbetten
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=[text, image]
)

embedding = result['embedding']

Dies erfasst Beziehungen zwischen Text und Bild in einem einzigen Embedding.

Stapelverarbeitung

Verarbeiten Sie mehrere Elemente effizient:

texts = [
    "Erstes Dokument über API-Tests",
    "Zweites Dokument über Automatisierung",
    "Drittes Dokument über Leistung"
]

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"Generated {len(embeddings)} embeddings")

Für große Batches verwenden Sie die Batch-API für 50% Kosteneinsparungen.

Aufbau eines Semantischen Suchsystems

Hier ist ein vollständiges Beispiel für die Verwendung von Gemini Embedding 2 für die semantische Suche.

Schritt 1: Abhängigkeiten installieren

pip install google-generativeai numpy scikit-learn

Schritt 2: Ihre Dokumente einbetten

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

genai.configure(api_key='YOUR_API_KEY')

# Beispiel-Dokumente
documents = [
    "Apidog ist eine API-Testplattform für Entwickler",
    "REST-APIs verwenden HTTP-Methoden wie GET, POST, PUT, DELETE",
    "GraphQL bietet eine Abfragesprache für APIs",
    "API-Dokumentation hilft Entwicklern, Endpunkte zu verstehen",
    "Postman ist ein beliebtes API-Testtool"
]

# Embeddings für alle Dokumente generieren
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'])

# In Numpy-Array konvertieren
doc_embeddings = np.array(doc_embeddings)

Schritt 3: Suchfunktion erstellen

def search(query, top_k=3):
    # Die Anfrage einbetten
    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']])

    # Ähnlichkeiten berechnen
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # Top-Ergebnisse abrufen
    top_indices = np.argsort(similarities)[::-1][:top_k]

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

    return results

Schritt 4: Suche

# Die Suche testen
results = search("Welche Tools kann ich für API-Tests verwenden?")

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

Output:

1. Score: 0.8234
   Apidog ist eine API-Testplattform für Entwickler

2. Score: 0.7891
   Postman ist ein beliebtes API-Testtool

3. Score: 0.6543
   API-Dokumentation hilft Entwicklern, Endpunkte zu verstehen

Aufbau eines RAG-Systems

Verwenden Sie Gemini Embedding 2 für Retrieval-Augmented Generation.

Schritt 1: Wissensdatenbank einrichten

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

genai.configure(api_key='YOUR_API_KEY')

# Wissensdatenbank
knowledge_base = [
    "Apidog unterstützt REST-, GraphQL- und WebSocket-APIs",
    "Sie können Testfälle erstellen und diese automatisch ausführen",
    "Apidog generiert API-Dokumentation aus Ihren Anfragen",
    "Mock-Server helfen Ihnen beim Testen, bevor das Backend bereit ist",
    "Team-Kollaborationsfunktionen umfassen gemeinsame Arbeitsbereiche"
]

# Wissensdatenbank einbetten
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)

Schritt 2: RAG-Abfragefunktion erstellen

def rag_query(question):
    # 1. Die Frage einbetten
    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. Relevanten Kontext finden
    similarities = cosine_similarity(query_embedding, kb_embeddings)[0]
    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # 3. Antwort mit Kontext generieren
    prompt = f"""Kontext: {context}

Frage: {question}

Beantworten Sie die Frage basierend auf dem bereitgestellten Kontext."""

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

    return response.text

Schritt 3: Ihr RAG-System abfragen

# RAG testen
answer = rag_query("Kann Apidog Dokumentation generieren?")
print(answer)

Dies ruft den relevantesten Kontext aus Ihrer Wissensdatenbank ab und verwendet ihn, um präzise Antworten zu generieren.

Embeddings in einer Vektordatenbank speichern

Verwenden Sie ChromaDB, um Embeddings zu speichern und abzufragen:

import chromadb
import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# ChromaDB initialisieren
client = chromadb.Client()
collection = client.create_collection(name="my_documents")

# Zu indizierende Dokumente
documents = [
    "API-Tests stellen sicher, dass Ihre Endpunkte korrekt funktionieren",
    "REST-APIs folgen zustandslosen Architekturprinzipien",
    "GraphQL ermöglicht Clients, spezifische Daten anzufordern"
]

# Embeddings generieren und speichern
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}"]
    )

# Die Kollektion abfragen
query = "Wie teste ich meine API?"
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("Top-Ergebnisse:")
for doc in results['documents'][0]:
    print(f"- {doc}")

Fehlerbehandlung

Behandeln Sie API-Fehler elegant:

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"Ungültige Eingabe: {e}")
        # Beispiel: Inhalt zu lang oder nicht unterstütztes Format
        return None

    except exceptions.ResourceExhausted as e:
        print(f"Kontingent überschritten: {e}")
        # Beispiel: Ratenlimit erreicht oder Kontingent erschöpft
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"Anfrage-Timeout: {e}")
        # Beispiel: Netzwerkprobleme oder langsame Antwort
        return None

    except Exception as e:
        print(f"Unerwarteter Fehler: {e}")
        return None

# Verwenden Sie es
embedding = safe_embed("Ihr Text hier")
if embedding:
    print("Embedding erfolgreich generiert")
else:
    print("Embedding konnte nicht generiert werden")

Häufige Fehlermeldungen:

• InvalidArgument: Content exceeds maximum length - Eingabegröße reduzieren
• ResourceExhausted: Quota exceeded - Warten oder Plan upgraden
• Unauthenticated: API key not valid - Überprüfen Sie Ihren API-Schlüssel
• PermissionDenied: Model not available - Modellnamen überprüfen

Ratenbegrenzung und Best Practices

Ratenbegrenzungen:

• Kostenloser Tarif: 60 Anfragen pro Minute
• Kostenpflichtiger Tarif: Höhere Limits basierend auf Ihrem Plan

Best Practices:

Verwenden Sie geeignete Dimensionen: 768 für die Produktion, 3072 nur wenn Sie maximale Qualität benötigen

Stapelanfragen: Verarbeiten Sie nach Möglichkeit mehrere Elemente zusammen

Embeddings cachen: Betten Sie denselben Inhalt nicht erneut ein

Verwenden Sie Aufgabenanweisungen: Sie verbessern die Genauigkeit für spezifische Anwendungsfälle

Fehler behandeln: Implementieren Sie eine Wiederholungslogik mit exponentiellem Backoff

Kosten überwachen: Verfolgen Sie Ihre Token-Nutzung

Kostenoptimierung

Reduzieren Sie Kosten mit diesen Strategien:

1. Kleinere Dimensionen verwenden:

# 768 Dimensionen = 75% weniger Speicherplatz
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=text,
    output_dimensionality=768
)

2. Batch-API für nicht dringende Aufgaben verwenden:

# 50% Kosteneinsparungen bei der Stapelverarbeitung
# (Batch-API-Implementierung hängt von Ihrer Einrichtung ab)

3. Embeddings cachen:

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # Cache-Schlüssel erstellen
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # Cache prüfen
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    # Embedding generieren
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=content,
        output_dimensionality=768
    )

    # Im Cache speichern
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

Häufige Probleme und Lösungen

Problem: „Ungültiger API-Schlüssel“

# Lösung: Überprüfen Sie Ihren API-Schlüssel
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("API key not set!")

Problem: „Inhalt zu lang“

# Lösung: Teilen Sie lange Texte in Abschnitte auf
def chunk_text(text, max_tokens=8000):
    # Einfache wortbasierte Aufteilung
    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

# Jeden Abschnitt einbetten
for chunk in chunk_text(long_text):
    embedding = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=chunk
    )

Problem: „Dateiverarbeitung-Timeout“

# Lösung: Wartezeit für große Dateien erhöhen
import time

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

max_wait = 300  # 5 Minuten
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("Dateiverarbeitung-Timeout")
else:
    # Embedding generieren
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

Nächste Schritte

Jetzt wissen Sie, wie Sie die Gemini Embedding 2 API verwenden. Hier sind die nächsten Schritte, die Sie ausprobieren können:

1. Erstellen Sie ein semantisches Suchsystem für Ihre Dokumentation
2. Erstellen Sie eine RAG-Anwendung mit multimodalen Kontext
3. Implementieren Sie eine visuelle Suche für Produktkataloge
4. Richten Sie eine Audiosuche ein für Podcast- oder Videoinhalte
5. Experimentieren Sie mit verschiedenen Dimensionen, um Kosten zu optimieren

Die API ist unkompliziert, aber die Möglichkeiten sind riesig. Beginnen Sie mit Text-Embeddings und fügen Sie dann Bilder, Videos oder Audio hinzu, je nach Ihrem Anwendungsfall.

Testen Sie Ihre Implementierung? Verwenden Sie Apidog, um die Gemini API-Endpunkte zu testen, Antworten zu validieren und Ihre Embedding-Pipeline-Tests zu automatisieren.