Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Génère des embeddings pour tes données

Lekcija 3 od 22 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Objectifs
  2. Prépare tes données
  3. Génère des embeddings par lots
  4. Stocke les embeddings
  5. Pipeline complet : des fichiers texte aux embeddings
  6. Estime les coûts
  7. Ključne točke

Objectifs

  • Prépare tes données textuelles pour l’embedding
  • Génère des embeddings efficacement à grande échelle
  • Stocke 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 truffé 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 se cumule à 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"

Enrichis 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ère des embeddings par lots

Sur un corpus réel de centaines ou de milliers de documents, le traitement doit être découpé en lots et résilient aux aléas du réseau. La fonction ci-dessous itère sur les textes par tranches, trie systématiquement la réponse par index pour garantir que le vecteur n°7 corresponde 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.

Stocke 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 parsing 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 sépare 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.

Estime 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.

Ključne točke

  • 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