Generați embedding-uri pentru datele dumneavoastră
Pe această pagină
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ă