Générez des embeddings pour vos données
Šajā lapā
Objectifs
- Préparer tes données textuelles pour l’embedding
- Générer des embeddings efficacement à grande échelle
- Stocker les vecteurs pour une utilisation ultérieure
Prépare tes données
La qualité de tes embeddings dépend directement de la qualité de tes données. Un texte rempli d’espaces superflus, de caractères de contrôle issus d’une exportation mal configurée ou de sauts de ligne erratiques produit un vecteur légèrement décalé. Ce décalage s’accumule à chaque recherche. Le nettoyage n’est pas cosmétique : c’est la première et la moins coûteuse des optimisations de pertinence.
import re
def nettoyer_texte(texte: str) -> str:
"""Prepares text for embedding."""
# Remove multiple spaces
texte = re.sub(r"\s+", " ", texte)
# Remove control characters
texte = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", texte)
# Trim
texte = texte.strip()
return texte
# Example
brut = " Texte avec des espaces\n\n\nen trop "
propre = nettoyer_texte(brut)
print(propre) # "Texte avec des espaces en trop"
Enrichir le contexte
Un extrait de documentation isolé perd une partie de son sens sans son titre. Prends un paragraphe qui commence par « Téléchargez le paquet depuis le site officiel » : hors contexte, rien n’indique qu’il fait référence à PostgreSQL, et le vecteur résultant ne correspondra jamais à une requête concernant PostgreSQL. En préfixant le contenu avec son titre et sa section, tu réinjectes cette information dans le texte que le modèle voit.
def enrichir_document(titre: str, section: str, contenu: str) -> str:
"""Creates enriched text for better embedding."""
return f"Titre : {titre}\nSection : {section}\n\n{contenu}"
texte_enrichi = enrichir_document(
titre="Installation de PostgreSQL",
section="Getting Started Guide",
contenu="Download the package from the official site..."
)
Générer des embeddings par lots
Sur un corpus réel de centaines ou de milliers de documents, le traitement doit être découpé en tranches et résilient aux aléas du réseau. La fonction ci-dessous parcourt les textes par tranches, trie systématiquement la réponse par index pour garantir que le vecteur n°7 correspond au document n°7, et réessaie une fois après une pause en cas d’erreur.
from openai import OpenAI
import time
import json
client = OpenAI()
def generer_embeddings(
textes: list[str],
model: str = "text-embedding-3-large",
batch_size: int = 100
) -> list[list[float]]:
"""Generates embeddings in batches with error handling."""
tous_les_embeddings = []
for i in range(0, len(textes), batch_size):
batch = textes[i:i + batch_size]
print(f"Processing batch {i // batch_size + 1}/"
f"{(len(textes) - 1) // batch_size + 1}")
try:
response = client.embeddings.create(
input=batch,
model=model
)
# Sort by index to guarantee order
batch_embeddings = sorted(
response.data, key=lambda x: x.index
)
tous_les_embeddings.extend(
[item.embedding for item in batch_embeddings]
)
except Exception as e:
print(f"Error on batch {i}: {e}")
# Retry after a pause
time.sleep(5)
response = client.embeddings.create(
input=batch,
model=model
)
batch_embeddings = sorted(
response.data, key=lambda x: x.index
)
tous_les_embeddings.extend(
[item.embedding for item in batch_embeddings]
)
return tous_les_embeddings
Le tri par index est une précaution que tu ne dois jamais négliger. Un décalage silencieux d’une seule ligne suffit à associer chaque document au vecteur de son voisin. Le symptôme que tu observeras est « la recherche renvoie n’importe quoi », sans aucune erreur technique pour t’orienter dans la bonne direction.
Stocker les embeddings
Pour un petit corpus de quelques milliers de documents, un simple fichier JSON contenant les textes, les métadonnées et les vecteurs fonctionne parfaitement. Il a l’avantage d’être lisible par un humain lorsque tu dois déboguer un résultat étrange.
import json
documents = [
{"id": 1, "texte": "Premier document...", "metadata": {"source": "faq"}},
{"id": 2, "texte": "Deuxième document...", "metadata": {"source": "docs"}},
]
# Generate embeddings
textes = [d["texte"] for d in documents]
embeddings = generer_embeddings(textes)
# Add vectors to documents
for doc, emb in zip(documents, embeddings):
doc["embedding"] = emb
# Save
with open("corpus_embeddings.json", "w") as f:
json.dump(documents, f)
Au-delà de cette échelle, le JSON devient un goulot d’étranglement : chaque nombre est écrit en toutes lettres, gonflant le fichier et imposant un analyse syntaxique coûteux à chaque chargement. NumPy stocke les mêmes valeurs en binaire sur 4 octets et se recharge instantanément.
import numpy as np
# Convert to NumPy matrix
matrice = np.array(embeddings, dtype=np.float32)
print(f"Shape : {matrice.shape}") # (n_docs, 3072)
# Save in binary format
np.save("embeddings.npy", matrice)
# Load
matrice_chargee = np.load("embeddings.npy")
Pipeline complet : des fichiers texte aux embeddings
Assemblons ces éléments dans une fonction qui lit un dossier, nettoie chaque fichier, génère les vecteurs et divise le stockage en deux : les métadonnées en JSON (lisibles et modifiables) et la matrice en NumPy (compacte et rapide).
from openai import OpenAI
from pathlib import Path
import json
import numpy as np
client = OpenAI()
def pipeline_embeddings(dossier: str, model: str = "text-embedding-3-large"):
"""Complete pipeline: files → embeddings → storage."""
dossier_path = Path(dossier)
# 1. Read files
documents = []
for fichier in sorted(dossier_path.glob("*.txt")):
contenu = fichier.read_text(encoding="utf-8")
contenu = nettoyer_texte(contenu)
if contenu:
documents.append({
"id": fichier.stem,
"fichier": fichier.name,
"texte": contenu
})
print(f"{len(documents)} documents found")
# 2. Generate embeddings
textes = [d["texte"] for d in documents]
embeddings = generer_embeddings(textes, model=model)
# 3. Save
# Metadata in JSON
meta = [{"id": d["id"], "fichier": d["fichier"]} for d in documents]
with open("metadata.json", "w") as f:
json.dump(meta, f, ensure_ascii=False, indent=2)
# Vectors in NumPy
np.save("embeddings.npy", np.array(embeddings, dtype=np.float32))
print(f"Embeddings saved: {len(embeddings)} vectors "
f"of {len(embeddings[0])} dimensions")
return documents, embeddings
# Usage
documents, embeddings = pipeline_embeddings("./mes_documents/")
Note l’utilisation de sorted() sur le glob : sans cela, l’ordre des fichiers dépend du système de fichiers, et tes deux fichiers de sortie risquent de se désynchroniser après un simple changement de machine.
Estimer les coûts
Avant de lancer un travail massif, compte les tokens localement avec tiktoken. L’opération prend quelques secondes et t’évite de découvrir trop tard qu’un corpus mal filtré contenait dix fois le volume attendu.
import tiktoken
encoder = tiktoken.get_encoding("cl100k_base")
def estimer_cout(textes: list[str], model: str = "text-embedding-3-large"):
"""Estimates embedding cost for a list of texts."""
total_tokens = sum(len(encoder.encode(t)) for t in textes)
# Approximate prices per million tokens (check current rates)
prix = {
"text-embedding-3-large": 0.13,
"text-embedding-3-small": 0.02,
}
cout = total_tokens / 1_000_000 * prix.get(model, 0.13)
print(f"Estimated tokens: {total_tokens:,}")
print(f"Estimated cost: ${cout:.4f}")
return total_tokens, cout
Les prix dans le dictionnaire sont indicatifs et vieillissent vite : vérifie toujours les tarifs actuels avant de présenter un devis à un client.
Galvenās atziņas
- Nettoie et enrichis tes textes avant de générer des embeddings
- Utilise le traitement par lots pour les grands corpus
- Stocke les métadonnées en JSON et les vecteurs en NumPy
- Estime tes coûts avant de lancer un travail massif