Comment Utiliser l'API Gemini Embedding 2 ?

L'API Gemini Embedding 2 de Google vous permet de générer des embeddings (représentations vectorielles) pour le texte, les images, la vidéo, l'audio et les PDF. Ce guide vous montre comment l'utiliser, avec de vrais exemples de code que vous pouvez exécuter dès aujourd'hui.

Remarque : Ce guide couvre la version d'aperçu public (gemini-embedding-2-preview). L'API peut changer avant sa disponibilité générale.

Vous voulez d'abord comprendre ce qu'est Gemini Embedding 2 ? Lisez notre aperçu : Qu'est-ce que Gemini Embedding 2 ?

Prérequis

Vous avez besoin de :

Une clé API Google AI
Python 3.7 ou version ultérieure
Le SDK Google Generative AI

Installation

Installez le SDK :

pip install google-generativeai

Configuration de base

Configurez votre clé API :

import google.generativeai as genai

# Définissez votre clé API
genai.configure(api_key='VOTRE_CLÉ_API')

Pour la production, utilisez des variables d'environnement :

import os
import google.generativeai as genai

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

Test avec Apidog

Avant de plonger dans le code, vous pouvez tester l'API Gemini Embedding directement dans Apidog :

Capture d'écran de l'interface Apidog montrant comment configurer une requête POST pour l'API Gemini Embedding 2.

Créez une nouvelle requête dans Apidog
Définissez la méthode sur POST
URL : https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
Ajoutez l'en-tête : x-goog-api-key: VOTRE_CLÉ_API
Corps (JSON) :

{
  "content": {
    "parts": [{
      "text": "Qu'est-ce que le test d'API ?"
    }]
  }
}

Cela vous permet de vérifier que votre clé API fonctionne et de voir la structure de la réponse avant d'écrire du code. Vous pouvez l'enregistrer comme cas de test et valider les réponses d'embedding dans votre pipeline CI/CD.

Génération d'embeddings de texte

Le cas d'utilisation le plus simple - embarquer du texte :

import google.generativeai as genai

genai.configure(api_key='VOTRE_CLÉ_API')

# Générer l'embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Quel est le sens de la vie ?'
)

# Obtenir le vecteur d'embedding
embedding = result['embedding']
print(f"Dimensions de l'embedding : {len(embedding)}")
print(f"5 premières valeurs : {embedding[:5]}")

Sortie :

Dimensions de l'embedding : 3072
5 premières valeurs : [0.0234, -0.0156, 0.0891, -0.0423, 0.0567]

Remarque : La structure de la réponse est result['embedding'] qui renvoie une liste de floats. Chaque float représente une dimension du vecteur d'embedding.

Utilisation des instructions de tâche

Les instructions de tâche optimisent les embeddings pour des cas d'utilisation spécifiques :

# Pour les requêtes de recherche
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='meilleurs outils de test d\'API',
    task_type='RETRIEVAL_QUERY'
)

# Pour les documents que vous indexez
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog est une plateforme de test d\'API...',
    task_type='RETRIEVAL_DOCUMENT'
)

Types de tâches disponibles :

RETRIEVAL_QUERY - À utiliser pour les requêtes de recherche
RETRIEVAL_DOCUMENT - À utiliser pour les documents que vous indexez
SEMANTIC_SIMILARITY - À utiliser pour comparer la similarité de contenu
CLASSIFICATION - À utiliser pour les tâches de catégorisation
CLUSTERING - À utiliser pour regrouper du contenu similaire

Contrôle des dimensions de sortie

Réduisez les coûts de stockage en utilisant des dimensions plus petites :

# Optimisé pour la production : 768 dimensions
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Votre texte ici',
    output_dimensionality=768
)

# Équilibré : 1536 dimensions
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Votre texte ici',
    output_dimensionality=1536
)

# Qualité maximale : 3072 dimensions (par défaut)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Votre texte ici',
    output_dimensionality=3072
)

Pour la plupart des applications, 768 dimensions offrent une qualité quasi maximale avec 75 % moins de stockage.

Embedding d'images

Embarquez des images pour la recherche visuelle :

import PIL.Image

# Charger l'image
image = PIL.Image.open('product-photo.jpg')

# Générer l'embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=image
)

embedding = result['embedding']

Vous pouvez embarquer jusqu'à 6 images par requête :

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
)

Embedding de vidéo

Embarquez du contenu vidéo pour la recherche vidéo :

# Télécharger d'abord le fichier vidéo
video_file = genai.upload_file(path='demo-video.mp4')

# Attendre le traitement
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

# Générer l'embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=video_file
)

embedding = result['embedding']

Limites vidéo :

Maximum 128 secondes par requête
Formats : MP4, MOV
Codecs : H264, H265, AV1, VP9

Embedding audio

Embarquez de l'audio sans transcription :

# Télécharger le fichier audio
audio_file = genai.upload_file(path='podcast-episode.mp3')

# Attendre le traitement
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

# Générer l'embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=audio_file
)

embedding = result['embedding']

Limites audio :

Maximum 80 secondes par requête
Formats : MP3, WAV

Embedding de documents PDF

Embarquez des pages PDF pour la recherche de documents :

# Télécharger le PDF
pdf_file = genai.upload_file(path='user-manual.pdf')

# Attendre le traitement
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

# Générer l'embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=pdf_file
)

embedding = result['embedding']

Limites PDF :

Maximum 6 pages par requête
Traite le contenu textuel et visuel

Embeddings multimodaux (Texte + Image)

Combinez plusieurs types de contenu dans un seul embedding :

import PIL.Image

image = PIL.Image.open('product.jpg')
text = "Casque sans fil de haute qualité avec suppression de bruit"

# Embarquez les deux ensemble
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=[text, image]
)

embedding = result['embedding']

Ceci capture les relations entre le texte et l'image dans un seul embedding.

Traitement par lots

Traitez efficacement plusieurs éléments :

texts = [
    "Premier document sur le test d'API",
    "Deuxième document sur l'automatisation",
    "Troisième document sur la performance"
]

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"Généré {len(embeddings)} embeddings")

Pour les grands lots, utilisez l'API de lot pour économiser 50 % des coûts.

Construction d'un système de recherche sémantique

Voici un exemple complet utilisant Gemini Embedding 2 pour la recherche sémantique.

Étape 1 : Installer les dépendances

pip install google-generativeai numpy scikit-learn

Étape 2 : Embarquez vos documents

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

genai.configure(api_key='VOTRE_CLÉ_API')

# Exemples de documents
documents = [
    "Apidog est une plateforme de test d'API pour les développeurs",
    "Les API REST utilisent des méthodes HTTP comme GET, POST, PUT, DELETE",
    "GraphQL fournit un langage de requête pour les API",
    "La documentation API aide les développeurs à comprendre les endpoints",
    "Postman est un outil populaire de test d'API"
]

# Générer les embeddings pour tous les documents
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'])

# Convertir en tableau numpy
doc_embeddings = np.array(doc_embeddings)

Étape 3 : Créer une fonction de recherche

def search(query, top_k=3):
    # Embarquez la requête
    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']])

    # Calculer les similarités
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # Obtenir les meilleurs résultats
    top_indices = np.argsort(similarities)[::-1][:top_k]

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

    return results

Étape 4 : Rechercher

# Tester la recherche
results = search("Quels outils puis-je utiliser pour le test d'API ?")

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

Sortie :

1. Score : 0.8234
   Apidog est une plateforme de test d'API pour les développeurs

2. Score : 0.7891
   Postman est un outil populaire de test d'API

3. Score : 0.6543
   La documentation API aide les développeurs à comprendre les endpoints

Construction d'un système RAG

Utilisez Gemini Embedding 2 pour la Génération Augmentée par Récupération (RAG).

Étape 1 : Configurer la base de connaissances

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

genai.configure(api_key='VOTRE_CLÉ_API')

# Base de connaissances
knowledge_base = [
    "Apidog supporte les API REST, GraphQL et WebSocket",
    "Vous pouvez créer des cas de test et les exécuter automatiquement",
    "Apidog génère la documentation API à partir de vos requêtes",
    "Les serveurs mock vous aident à tester avant que le backend ne soit prêt",
    "Les fonctionnalités de collaboration en équipe incluent des espaces de travail partagés"
]

# Embarquez la base de connaissances
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)

Étape 2 : Créer une fonction de requête RAG

def rag_query(question):
    # 1. Embarquez la question
    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. Trouvez le contexte pertinent
    similarities = cosine_similarity(query_embedding, kb_embeddings)[0]
    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # 3. Générer une réponse avec le contexte
    prompt = f"""Contexte : {context}

Question : {question}

Répondez à la question en fonction du contexte fourni."""

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

    return response.text

Étape 3 : Interroger votre système RAG

# Tester RAG
answer = rag_query("Apidog peut-il générer de la documentation ?")
print(answer)

Ceci récupère le contexte le plus pertinent de votre base de connaissances et l'utilise pour générer des réponses précises.

Stockage des embeddings dans une base de données vectorielle

Utilisez ChromaDB pour stocker et interroger les embeddings :

import chromadb
import google.generativeai as genai

genai.configure(api_key='VOTRE_CLÉ_API')

# Initialiser ChromaDB
client = chromadb.Client()
collection = client.create_collection(name="mes_documents")

# Documents à indexer
documents = [
    "Le test d'API garantit le bon fonctionnement de vos endpoints",
    "Les API REST suivent les principes d'architecture sans état",
    "GraphQL permet aux clients de demander des données spécifiques"
]

# Générer et stocker les embeddings
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}"]
    )

# Interroger la collection
query = "Comment tester mon 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("Meilleurs résultats :")
for doc in results['documents'][0]:
    print(f"- {doc}")

Gestion des erreurs

Gérez les erreurs d'API avec élégance :

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

genai.configure(api_key='VOTRE_CLÉ_API')

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"Entrée invalide : {e}")
        # Exemple : Contenu trop long ou format non supporté
        return None

    except exceptions.ResourceExhausted as e:
        print(f"Quota dépassé : {e}")
        # Exemple : Limite de débit atteinte ou quota épuisé
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"Délai d'attente de la requête dépassé : {e}")
        # Exemple : Problèmes réseau ou réponse lente
        return None

    except Exception as e:
        print(f"Erreur inattendue : {e}")
        return None

# Utilisation
embedding = safe_embed("Votre texte ici")
if embedding:
    print("Embedding généré avec succès")
else:
    print("Échec de la génération de l'embedding")

Messages d'erreur courants :

InvalidArgument: Content exceeds maximum length - Réduisez la taille de l'entrée
ResourceExhausted: Quota exceeded - Attendez ou améliorez votre plan
Unauthenticated: API key not valid - Vérifiez votre clé API
PermissionDenied: Model not available - Vérifiez le nom du modèle

Limitation de débit et meilleures pratiques

Limites de débit :

Niveau gratuit : 60 requêtes par minute
Niveau payant : Limites plus élevées en fonction de votre plan

Meilleures pratiques :

Utilisez des dimensions appropriées : 768 pour la production, 3072 uniquement lorsque vous avez besoin de la qualité maximale

Requêtes par lots : Traitez plusieurs éléments ensemble si possible

Mettez en cache les embeddings : Ne ré-embarquez pas le même contenu

Utilisez les instructions de tâche : Elles améliorent la précision pour des cas d'utilisation spécifiques

Gérez les erreurs : Implémentez une logique de réessai avec un backoff exponentiel

Surveillez les coûts : Suivez votre consommation de jetons

Optimisation des coûts

Réduisez les coûts avec ces stratégies :

1. Utilisez des dimensions plus petites :

# 768 dimensions = 75% de stockage en moins
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=text,
    output_dimensionality=768
)

2. Utilisez l'API de lot pour les tâches non urgentes :

# 50 % d'économies pour le traitement par lots
# (L'implémentation de l'API de lot dépend de votre configuration)

3. Mettez en cache les embeddings :

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # Créer la clé de cache
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # Vérifier le cache
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    # Générer l'embedding
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=content,
        output_dimensionality=768
    )

    # Stocker dans le cache
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

Problèmes courants et solutions

Problème : "Clé API invalide"

# Solution : Vérifiez votre clé API
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("Clé API non définie !")

Problème : "Contenu trop long"

# Solution : Diviser le texte long en morceaux
def chunk_text(text, max_tokens=8000):
    # Simple découpage par mots
    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

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

Problème : "Délai d'attente de traitement de fichier"

# Solution : Augmenter le temps d'attente pour les fichiers volumineux
import time

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

max_wait = 300  # 5 minutes
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("Délai d'attente de traitement de fichier dépassé")
else:
    # Générer l'embedding
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

Prochaines étapes

Vous savez maintenant comment utiliser l'API Gemini Embedding 2. Voici ce que vous pouvez essayer ensuite :

Construisez un système de recherche sémantique pour votre documentation
Créez une application RAG avec un contexte multimodal
Implémentez une recherche visuelle pour les catalogues de produits
Mettez en place une recherche audio pour le contenu de podcasts ou de vidéos
Expérimentez avec différentes dimensions pour optimiser les coûts

L'API est simple, mais les possibilités sont énormes. Commencez par les embeddings de texte, puis ajoutez des images, de la vidéo ou de l'audio selon les besoins de votre cas d'utilisation.

Vous testez votre implémentation ? Utilisez Apidog pour tester les endpoints de l'API Gemini, valider les réponses et automatiser vos tests de pipeline d'embedding.