L'API Embeddings : modèles et dimensions

Objectifs

• Maîtriser l’appel client.embeddings.create()
• Comprendre les différences entre les modèles d’embedding
• Utiliser la réduction de dimensions

L’appel de base

L’API Embeddings d’OpenAI s’utilise via la méthode client.embeddings.create() :

from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    input="Bonjour, comment allez-vous ?",
    model="text-embedding-3-large"
)

embedding = response.data[0].embedding
print(f"Type : {type(embedding)}")        # list
print(f"Longueur : {len(embedding)}")      # 3072
print(f"Extrait : {embedding[:3]}")        # [0.023, -0.041, 0.012]

Structure de la réponse

La réponse contient :

• data : liste d’objets avec le champ embedding (le vecteur) et index (position dans le batch)
• model : le modèle utilisé
• usage.prompt_tokens : nombre de tokens facturés

Les deux modèles disponibles

text-embedding-3-large

Le modèle haute performance. Ses 3 072 dimensions capturent les nuances sémantiques les plus fines. Utilisez-le pour :

• La recherche sémantique sur de grands corpus
• Les pipelines RAG exigeants
• Les cas où la précision prime sur le coût

text-embedding-3-small

Plus compact avec 1 536 dimensions. Il offre un excellent rapport qualité/prix pour :

• La classification de texte
• Les recommandations
• Le prototypage rapide
• Les applications à fort volume

# Comparer les deux modèles
for model_name in ["text-embedding-3-small", "text-embedding-3-large"]:
    resp = client.embeddings.create(
        input="Intelligence artificielle",
        model=model_name
    )
    vec = resp.data[0].embedding
    print(f"{model_name}: {len(vec)} dimensions")

Embeddings par lots

Vous pouvez envoyer jusqu’à 2 048 textes en un seul appel. C’est bien plus efficace que des appels individuels :

textes = [
    "L'apprentissage automatique progresse rapidement",
    "Le deep learning révolutionne la vision par ordinateur",
    "Les bases de données vectorielles stockent des embeddings",
    "Python est le langage préféré des data scientists"
]

response = client.embeddings.create(
    input=textes,
    model="text-embedding-3-large"
)

for item in response.data:
    print(f"Texte {item.index}: vecteur de {len(item.embedding)} dimensions")

print(f"Tokens consommés : {response.usage.prompt_tokens}")

Bonnes pratiques pour les lots

• Regroupez vos textes par lots de 100 à 2 048 selon votre volume
• Surveillez usage.prompt_tokens pour estimer les coûts
• Gérez les erreurs de rate limit avec un retry exponentiel

Réduction de dimensions

Les modèles text-embedding-3-* supportent le paramètre dimensions pour obtenir des vecteurs plus courts :

# Vecteur complet : 3072 dimensions
full = client.embeddings.create(
    input="Test de réduction",
    model="text-embedding-3-large"
)

# Vecteur réduit : 256 dimensions
reduced = client.embeddings.create(
    input="Test de réduction",
    model="text-embedding-3-large",
    dimensions=256
)

print(f"Complet : {len(full.data[0].embedding)} dim")    # 3072
print(f"Réduit : {len(reduced.data[0].embedding)} dim")  # 256

Quand réduire les dimensions ?

La réduction tronque le vecteur puis le re-normalise. Les premières dimensions portent le plus d’information :

Gestion des tokens

Les modèles d’embedding ont une limite de 8 191 tokens par texte. Au-delà, l’API retourne une erreur :

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

texte = "Un texte potentiellement long..."
tokens = encoder.encode(texte)

if len(tokens) > 8191:
    # Tronquer
    texte_tronque = encoder.decode(tokens[:8191])
    print(f"Texte tronqué de {len(tokens)} à 8191 tokens")

Résumé

• client.embeddings.create() accepte un texte ou une liste de textes
• text-embedding-3-large (3 072 dim) pour la précision, text-embedding-3-small (1 536 dim) pour le coût
• Le paramètre dimensions permet de réduire la taille des vecteurs
• Les lots (batch) de textes sont plus efficaces que les appels individuels
• Limite de 8 191 tokens par texte