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

Crearea Embedding-urilor

Lecția 11 din 18 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Codificarea fragmentelor în vectori
  2. Codificarea pe loturi
  3. Gestionarea erorilor de rețea
  4. Salvarea indexului pe disc
  5. Verificare înainte de a continua
  6. Puncte cheie

Codificarea fragmentelor în vectori

Documentele dumneavoastră sunt acum divizate în fragmente curate. Următorul pas este transformarea acestora în embedding-uri folosind API-ul mistral-embed, urmată de stocarea vectorilor rezultați într-un magazin vectorial care va funcționa ca motorul dumneavoastră de căutare. Acesta este momentul în care corpusul dumneavoastră încetează să mai fie text simplu și devine o geometrie interogabilă. Câteva precauții de inginerie—lotizare (batching), reîncercări și persistență—fac diferența dintre un prototip fragil și un index fiabil.

Pentru un corpus mic, să zicem mai puțin de o sută de fragmente, un singur apel direct este suficient. Extrageți textul din dicționarele fragmentelor, transmiteți-le așa cum sunt către API și recuperați matricea completă. Forma (87, 1024) afișată la finalul execuției reprezintă prima dumneavoastră verificare de sanity: atâtea rânduri câte fragmente există și 1024 de coloane, deoarece aceasta este dimensiunea modelului mistral-embed. Dacă numărul de rânduri nu corespunde, înseamnă că un fragment gol s-a strecurat în lot.

import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

# Presupunem că chunks este lista fragmentelor noastre pregătite
chunk_texts = [c["text"] for c in chunks]

# Codificare într-un singur apel
response = client.embeddings.create(
    model="mistral-embed",
    inputs=chunk_texts,
)

embeddings = np.array([d.embedding for d in response.data])
print(f"Embeddings: {embeddings.shape}")
# Embeddings: (87, 1024) de exemplu

Codificarea pe loturi

Dincolo de câteva zeci de fragmente, un singur apel atinge limitele API-ului. Soluția constă în divizarea listei în loturi și concatenarea rezultatelor. Funcția de mai jos procesează felii de câte 25 și afișează progresul. Acest lucru nu este doar cosmetic: pentru un corpus de câteva mii de fragmente, codificarea durează câteva minute, iar dumneavoastră veți dori să știți unde se află procesul, în loc să priviți un terminal mut. Ordinea este păstrată, astfel încât fiecare vector rămâne aliniat cu fragmentul său corespunzător din lista originală.

def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
    """Codifică o listă de fragmente în loturi."""
    texts = [c["text"] for c in chunks]
    all_embeddings = []

    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        print(f"  Se codifică lotul {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
              f"({len(batch)} fragmente)...")

        response = client.embeddings.create(
            model=model,
            inputs=batch,
        )
        all_embeddings.extend([d.embedding for d in response.data])

    return np.array(all_embeddings)

# Codifică toate fragmentele
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Total: {embeddings.shape[0]} vectori de {embeddings.shape[1]} dimensiuni")

Gestionarea erorilor de rețea

În producție, un apel API va eșua inevitabil la un moment dat: cădere de rețea, atingerea limitei de rată (rate limit) sau pană temporară. Fără protecție, indexarea dumneavoastră se oprește la lotul 180 din 400, iar dumneavoastră reveniți la punctul de plecare. Versiunea robustă învelește fiecare lot într-o buclă de reîncercare cu backoff exponențial—o secundă, apoi două, apoi patru. Acest spațiere crescândă contează: reîncercarea imediată după un refuz de cotă nu face decât să înrăutățească lucrurile. După trei eșecuri consecutive, funcția aruncă o excepție explicită care numește lotul defect, în loc să returneze o matrice trunchiată unde ați descoperi decalajul abia în timpul căutării.

import time

def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
    """Codificare robustă cu gestionarea erorilor."""
    texts = [c["text"] for c in chunks]
    all_embeddings = []

    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]

        for attempt in range(max_retries):
            try:
                response = client.embeddings.create(
                    model="mistral-embed",
                    inputs=batch,
                )
                all_embeddings.extend([d.embedding for d in response.data])
                break  # Succes, ieșire din bucla de reîncercare

            except Exception as e:
                wait_time = 2 ** attempt  # Backoff exponențial: 1s, 2s, 4s
                print(f"  Eroare în lotul {i // batch_size + 1}, "
                      f"încercarea {attempt + 1}/{max_retries}: {e}")
                if attempt < max_retries - 1:
                    print(f"  Se așteaptă {wait_time}s înainte de reîncercare...")
                    time.sleep(wait_time)
                else:
                    raise RuntimeError(
                        f"Eșec după {max_retries} încercări pentru lotul {i // batch_size + 1}"
                    )

    return np.array(all_embeddings)

Salvarea indexului pe disc

Fiecare rulare de codificare costă timp și apeluri API facturate. Recalcularea vectorilor de fiecare dată când aplicația dumneavoastră pornește este o risipă pură, mai ales că corpusul în sine nu s-a schimbat. Salvarea se face în două fișiere complementare: vectorii merg în NumPy, un format binar compact care se încarcă instantaneu, în timp ce metadatele—text, sursă, poziție—merg în JSON, lizibil, pe care îl puteți deschide pentru a inspecta un fragment suspect. Cele două fișiere sunt interdependente, legate prin ordinea liniilor: nu regenerați niciodată unul fără celălalt, altfel rezultatele căutării vor indica texte greșite.

import json

def save_index(chunks, embeddings, filepath="rag_index"):
    """Salvează fragmentele și embedding-urile."""
    # Salvează embedding-urile (NumPy)
    np.save(f"{filepath}_embeddings.npy", embeddings)

    # Salvează metadatele (JSON)
    metadata = []
    for c in chunks:
        metadata.append({
            "text": c["text"],
            "source": c.get("source", ""),
            "chunk_index": c.get("chunk_index", 0),
        })
    with open(f"{filepath}_metadata.json", "w", encoding="utf-8") as f:
        json.dump(metadata, f, ensure_ascii=False, indent=2)

    print(f"Index salvat: {len(chunks)} fragmente, {embeddings.shape}")


def load_index(filepath="rag_index"):
    """Încarcă fragmentele și embedding-urile de pe disc."""
    embeddings = np.load(f"{filepath}_embeddings.npy")

    with open(f"{filepath}_metadata.json", "r", encoding="utf-8") as f:
        metadata = json.load(f)

    print(f"Index încărcat: {len(metadata)} fragmente, {embeddings.shape}")
    return metadata, embeddings

# Salvare
save_index(chunks, embeddings)

# Încărcare (la următoarea pornire)
chunks_loaded, embeddings_loaded = load_index()

Verificare înainte de a continua

Un index corupt în mod silențios apare târziu, de obicei când un utilizator semnalează un răspuns absurd. Câteva verificări offline durează treizeci de secunde și vă scutesc de acea descoperire neplăcută. Funcția de verificare afișează mai întâi metrici de bază—numărul de fragmente, dimensiunea, norma medie—apoi măsoară similaritatea dintre fragmentele vecine: deoarece provin din același document, acestea ar trebui să arate valori semnificativ mai mari decât două pasaje aleatoare. Ultimul test este cel mai simplu și cel mai revelator: un fragment comparat cu sine însuși trebuie să yield exact 1.0. Orice altă valoare semnalează o problemă de aliniere sau de conversie numerică.

from sklearn.metrics.pairwise import cosine_similarity

def verify_embeddings(chunks, embeddings, n_tests=5):
    """Verifică calitatea embedding-urilor cu teste simple."""
    print("=== Verificare embedding-uri ===")
    print(f"Număr de fragmente: {len(chunks)}")
    print(f"Dimensiuni: {embeddings.shape[1]}")
    print(f"Norma medie: {np.linalg.norm(embeddings, axis=1).mean():.4f}")

    # Test: fragmentele din același document ar trebui să fie mai apropiate
    for i in range(min(n_tests, len(chunks) - 1)):
        sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
        print(f"  Similaritate fragment {i} <-> {i+1}: {sim:.4f}")

    # Test: un fragment comparat cu sine însuși = 1.0
    self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
    print(f"  Auto-similaritate (trebuie să fie 1.0): {self_sim:.6f}")

verify_embeddings(chunks, embeddings)

Puse cap la cap, fluxul de lucru se reduce la patru linii utile. Pregătiți fragmentele cu pipeline-ul din lecția anterioară, codificați în mod robust, verificați și salvați. Acesta este scriptul pe care îl veți rula din nou de fiecare dată când corpusul se actualizează.

# 1. Pregătirea fragmentelor (lecția anterioară)
chunks = prepare_documents(raw_docs)

# 2. Codificare
embeddings = encode_chunks_robust(chunks, batch_size=25)

# 3. Verificare
verify_embeddings(chunks, embeddings)

# 4. Salvare
save_index(chunks, embeddings)

print("Index pregătit pentru căutare!")

Puncte cheie

  • Utilizați lotizarea pentru a codifica corpusuri mari (loturi de 25–50 de fragmente)
  • Adăugați logica de reîncercare cu backoff exponențial pentru robustețe
  • Salvați embedding-urile pe disc (NumPy) pentru a evita recalcularea
  • Păstrați metadatele (text, sursă, poziție) într-un fișier JSON separat
  • Verificați calitatea embedding-urilor înainte de a le utiliza în producție