Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Genereer embeddings voor uw gegevens

Les 3 van 22 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Doelstellingen
  2. Bereid uw gegevens voor
  3. Genereer embeddings in batches
  4. Sla embeddings op
  5. Volledige pipeline: van tekstbestanden naar embeddings
  6. Schat de kosten
  7. Belangrijkste punten

Doelstellingen

  • Bereid uw tekstgegevens voor op embedding
  • Genereer efficiënt embeddings op grote schaal
  • Sla vectoren op voor later gebruik

Bereid uw gegevens voor

De kwaliteit van uw embedding hangt direct af van de kwaliteit van uw gegevens. Tekst die bezaaid is met overbodige spaties, besturingstekens door een verkeerd geconfigureerde export, of onregelmatige regeleinden, produceert een licht afwijkende vector. Die afwijking stapelt zich op bij elke zoekopdracht. Schoonmaken is geen cosmetische ingreep: het is de eerste en goedkoopste optimalisatie voor relevantie.

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"

Context verrijken

Een geïsoleerd fragment uit documentatie verliest zonder titel een deel van zijn betekenis. Neem een alinea die begint met “Download het pakket van de officiële site”: zonder context is niets duidelijk over PostgreSQL, en de resulterende vector zal nooit overeenkomen met een query over PostgreSQL. Door de inhoud te voorzien van de titel en sectie, injecteert u die informatie opnieuw in de tekst die het model ziet.

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..."
)

Genereer embeddings in batches

Bij een echt corpus van honderden of duizenden documenten moet de verwerking in chunks gebeuren en bestand zijn tegen netwerkhiccup. De onderstaande functie doorloopt teksten in segmenten, sorteert het antwoord systematisch op index om zeker te stellen dat vector #7 overeenkomt met document #7, en probeert het na een pauze opnieuw als er een fout optreedt.

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

Sorteren op index is een voorzorgsmaatregel die u nooit mag overslaan. Een stille verschuiving van één rij volstaat om elk document te koppelen aan de vector van zijn buurman. Het symptoom dat u zult waarnemen is “zoekresultaten leveren onzin op”, zonder technische fout die u de juiste richting wijst.

Sla embeddings op

Voor een klein corpus van enkele duizenden documenten werkt een eenvoudig JSON-bestand met teksten, metadata en vectoren perfect. Het voordeel is dat het leesbaar is voor mensen wanneer u een vreemd resultaat moet debuggen.

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)

Boven die schaal wordt JSON een flessenhals: elk getal wordt volledig uitgeschreven, wat het bestand opblaast en bij elke laadbeurt kostbare parsing vereist. NumPy slaat dezelfde waarden binair op in 4 bytes en laadt ze direct opnieuw.

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")

Volledige pipeline: van tekstbestanden naar embeddings

Laten we deze elementen samenvoegen in een functie die een map leest, elk bestand schoonmaakt, vectoren genereert en de opslag in tweeën splitst: metadata in JSON (leesbaar en bewerkbaar) en de matrix in NumPy (compact en snel).

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/")

Let op de sorted() op de glob: zonder deze hangt de bestandsvolgorde af van het bestandssysteem, en lopen uw twee uitvoerbestanden het risico na een simpele machinewijziging niet meer synchroon te lopen.

Schat de kosten

Tel voordat u een massale taak start lokaal tokens met tiktoken. De bewerking duurt enkele seconden en voorkomt dat u te laat ontdekt dat een slecht gefilterd corpus tien keer het verwachte volume bevatte.

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

De prijzen in het woordenboek zijn indicatief en verouderen snel: controleer altijd de actuele tarieven voordat u een offerte aan een klant presenteert.

Belangrijkste punten

  • Maak uw teksten schoon en verrijk ze voordat u embeddings genereert
  • Gebruik batchverwerking voor grote corpora
  • Sla metadata op in JSON en vectoren in NumPy
  • Schat uw kosten voordat u een massale taak start