Embeddings genereren
Op deze pagina
Chunks omzetten in vectoren
Uw documenten zijn nu opgesplitst in schone chunks. De volgende stap is het omzetten hiervan in embeddings met behulp van de mistral-embed API, waarna u deze vectoren opslaat in een vectorstore die als uw zoekmachine fungeert. Dit is het moment waarop uw corpus stopt met platte tekst te zijn en verandert in doorzoekbare geometrie. Enkele engineering-voorzorgsmaatregelen—batching, retry-logica en persistentie—maken het verschil tussen een fragiel prototype en een betrouwbare index.
Voor een klein corpus, zeg minder dan honderd chunks, volstaat één enkele directe aanroep. Haal de tekst uit uw chunk-woordenboeken, geef ze als zodanig door aan de API en haal de volledige matrix op. De vorm (87, 1024) die aan het einde van de uitvoering wordt weergegeven, is uw eerste sanity check: evenveel rijen als chunks, en 1024 kolommen omdat dat de dimensie van mistral-embed is. Als het aantal rijen niet overeenkomt, is er een lege chunk in de batch geslopen.
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
# Assume chunks is the list of our prepared chunks
chunk_texts = [c["text"] for c in chunks]
# Encode in a single call
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) for example
Batch-gewijs encoderen
Bij meer dan een paar dozijn chunks botst een enkele aanroep tegen de API-limieten. De oplossing is de lijst in batches splitsen en de resultaten samen te voegen. De onderstaande functie verwerkt segmenten van 25 en toont de voortgang. Dit is niet louter cosmetisch: bij een corpus van enkele duizenden chunks duurt het encoderen enkele minuten, en u wilt weten waar het proces staat in plaats van naar een stille terminal te staren. De volgorde blijft behouden, zodat elke vector uitgelijnd blijft met de bijbehorende chunk in uw oorspronkelijke lijst.
def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
"""Encode a list of chunks in batches."""
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" Encoding batch {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
f"({len(batch)} chunks)...")
response = client.embeddings.create(
model=model,
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
return np.array(all_embeddings)
# Encode all chunks
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Total: {embeddings.shape[0]} vectors of {embeddings.shape[1]} dimensions")
Omgaan met netwerkfouten
In productie zal een API-aanroep uiteindelijk falen: een netwerkonderbreking, een bereikte rate limit of een tijdelijke storing. Zonder bescherming stopt uw indexering bij batch 180 van de 400, en staat u weer met lege handen. De robuuste versie omwikkelt elke batch met een retry-lus met exponentiële backoff—één seconde, dan twee, dan vier. Deze toenemende tussenpoos is belangrijk: direct opnieuw proberen na een quota-weigering verergert het probleem alleen maar. Na drie opeenvolgende mislukkingen gooit de functie een expliciete uitzondering met de naam van de foutieve batch, in plaats van een ingekorte matrix terug te geven waarbij u de lacune pas tijdens het zoeken ontdekt.
import time
def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
"""Robust encoding with error handling."""
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 # Success, exit retry loop
except Exception as e:
wait_time = 2 ** attempt # Exponential backoff: 1s, 2s, 4s
print(f" Error in batch {i // batch_size + 1}, "
f"attempt {attempt + 1}/{max_retries}: {e}")
if attempt < max_retries - 1:
print(f" Waiting {wait_time}s before retry...")
time.sleep(wait_time)
else:
raise RuntimeError(
f"Failed after {max_retries} attempts for batch {i // batch_size + 1}"
)
return np.array(all_embeddings)
De index op schijf opslaan
Elke encoderingsrun kost tijd en gefactureerde API-aanroepen. Het bij elke start van uw applicatie opnieuw berekenen van vectoren is pure verspilling, zeker omdat het corpus zelf niet is veranderd. Het opslaan gebeurt in twee complementaire bestanden: vectoren gaan naar NumPy, een compact binair formaat dat direct laadt, terwijl metadata—tekst, bron, positie—naar leesbare JSON gaat die u kunt openen om een verdachte chunk te inspecteren. De twee bestanden zijn onderling afhankelijk, gekoppeld via de regelvolgorde: genereer nooit het ene bestand opnieuw zonder het andere, anders wijzen uw zoekresultaten naar de verkeerde teksten.
import json
def save_index(chunks, embeddings, filepath="rag_index"):
"""Save chunks and embeddings."""
# Save embeddings (NumPy)
np.save(f"{filepath}_embeddings.npy", embeddings)
# Save metadata (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 saved: {len(chunks)} chunks, {embeddings.shape}")
def load_index(filepath="rag_index"):
"""Load chunks and embeddings from disk."""
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 loaded: {len(metadata)} chunks, {embeddings.shape}")
return metadata, embeddings
# Save
save_index(chunks, embeddings)
# Load (on next startup)
chunks_loaded, embeddings_loaded = load_index()
Verificatie voordat u verdergaat
Een stilletjes beschadigde index komt laat aan het licht, meestal wanneer een gebruiker een absurd antwoord meldt. Enkele offline checks duren dertig seconden en besparen u deze ontdekking. De verificatiefunctie toont eerst basisstatistieken—aantal chunks, dimensie, gemiddelde norm—en meet vervolgens de gelijkenis tussen aangrenzende chunks: omdat ze uit hetzelfde document komen, moeten ze significant hogere waarden vertonen dan twee willekeurige passages. De laatste test is de simpelste en meest onthullende: een chunk vergeleken met zichzelf moet exact 1,0 opleveren. Elke andere waarde wijst op een uitlijnprobleem of een numeriek conversieprobleem.
from sklearn.metrics.pairwise import cosine_similarity
def verify_embeddings(chunks, embeddings, n_tests=5):
"""Verify embedding quality with simple tests."""
print("=== Verifying embeddings ===")
print(f"Number of chunks: {len(chunks)}")
print(f"Dimensions: {embeddings.shape[1]}")
print(f"Average norm: {np.linalg.norm(embeddings, axis=1).mean():.4f}")
# Test: chunks from the same document should be closer
for i in range(min(n_tests, len(chunks) - 1)):
sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
print(f" Similarity chunk {i} <-> {i+1}: {sim:.4f}")
# Test: a chunk compared to itself = 1.0
self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
print(f" Self-similarity (must be 1.0): {self_sim:.6f}")
verify_embeddings(chunks, embeddings)
Samengevoegd komt de workflow neer op vier nuttige regels. U bereidt chunks voor met de pipeline uit de vorige les, encodeert in robuuste modus, verifieert en slaat op. Dit is het script dat u opnieuw uitvoert telkens wanneer het corpus wordt bijgewerkt.
# 1. Prepare chunks (previous lesson)
chunks = prepare_documents(raw_docs)
# 2. Encode
embeddings = encode_chunks_robust(chunks, batch_size=25)
# 3. Verify
verify_embeddings(chunks, embeddings)
# 4. Save
save_index(chunks, embeddings)
print("Index ready for search!")
Belangrijkste punten
- Gebruik batching om grote corpora te encoderen (batches van 25–50 chunks)
- Voeg retry-logica toe met exponentiële backoff voor robuustheid
- Sla embeddings op schijf op (NumPy) om herberekening te voorkomen
- Bewaar metadata (tekst, bron, positie) in een apart JSON-bestand
- Verifieer de kwaliteit van de embeddings voordat u ze in productie gebruikt