Salt la conținutul principal
Română— Alege o limbă
Meniu

Generați embedding-uri pentru datele dumneavoastră

Lecția 3 din 22 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Obiective
  2. Pregătirea datelor
  3. Generarea embedding-urilor în loturi
  4. Stocarea embedding-urilor
  5. Flux complet: de la fișiere text la embedding-uri
  6. Estimarea costurilor
  7. Puncte cheie

Obiective

  • Pregătiți datele textuale pentru generarea de embedding-uri
  • Generați embedding-uri eficient, la scară largă
  • Stocați vectorii pentru utilizare ulterioară

Pregătirea datelor

Calitatea embedding-urilor dumneavoastră depinde direct de calitatea datelor. Un text plin de spații inutile, caractere de control provenite dintr-un export configurat greșit sau rânduri neregulate produce un vector ușor eronat. Această abatere se cumulează la fiecare căutare. Curățarea nu este doar cosmetică: este prima și cea mai ieftină optimizare a relevanței.

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"

Îmbogățirea contextului

Un extras izolat din documentație își pierde o parte din sens fără titlul său. Luați un paragraf care începe cu „Descărcați pachetul de pe site-ul oficial“: fără context, nimic nu indică faptul că se referă la PostgreSQL, iar vectorul rezultat nu va corespunde niciodată unei interogări despre PostgreSQL. Prin adăugarea titlului și a secțiunii înaintea conținutului, reintroduceți aceste informații în textul pe care modelul îl procesează.

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

Generarea embedding-urilor în loturi

Pe un corpus real de sute sau mii de documente, procesarea trebuie fragmentată și rezistentă la problemele de rețea. Funcția de mai jos parcurge textele în felii, sortează sistematic răspunsul după index pentru a se asigura că vectorul #7 corespunde documentului #7 și reîncearcă o dată după o pauză dacă apare o eroare.

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

Sortarea după index este o măsură de precauție pe care nu trebuie să o omiteți niciodată. O simplă deplasare tacită cu un rând este suficientă pentru a asocia fiecare document cu vectorul vecinului său. Simptomul pe care îl veți observa este „rezultatele căutării sunt incoerente“, fără nicio eroare tehnică care să vă indice direcția corectă.

Stocarea embedding-urilor

Pentru un corpus mic de câteva mii de documente, un fișier JSON simplu care conține texte, metadate și vectori funcționează perfect. Are avantajul de a fi lizibil de om atunci când trebuie să depanați un rezultat ciudat.

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)

Dincolo de această scară, JSON devine un gât de sticlă: fiecare număr este scris integral, umflând fișierul și impunând o analiză costisitoare la fiecare încărcare. NumPy stochează aceleași valori în format binar pe 4 octeți și se reîncarcă instantaneu.

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

Flux complet: de la fișiere text la embedding-uri

Să reunim aceste elemente într-o funcție care citește un dosar, curăță fiecare fișier, generează vectorii și împarte stocarea în două: metadatele în JSON (lizibil și editabil) și matricea în NumPy (compact și rapid).

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

Rețineți utilizarea lui sorted() pe glob: fără aceasta, ordinea fișierelor depinde de sistemul de fișiere, iar cele două fișiere de ieșire riscă să se desincronizeze după o simplă schimbare a mașinii.

Estimarea costurilor

Înainte de a lansa o sarcină masivă, numărați tokenii local cu tiktoken. Operațiunea durează câteva secunde și vă scutește de a descoperi prea târziu că un corpus filtrat necorespunzător conținea de zece ori volumul așteptat.

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

Prețurile din dicționar sunt indicative și se învechesc rapid: verificați întotdeauna tarifele actuale înainte de a prezenta o ofertă unui client.

Puncte cheie

  • Curățați și îmbogățiți textele înainte de a genera embedding-uri
  • Utilizați procesarea în loturi pentru corpusuri mari
  • Stocați metadatele în JSON și vectorii în NumPy
  • Estimați-vă costurile înainte de a lansa o sarcină masivă