Oħloq l-Embeddings
F'din il-paġna
Ikkodifika l-Biċċiet f’Vetturi
Id-dokumenti tiegħek issa huma maqsuma f’biċċiet nodfa. Il-pass li jmiss huwa li ttrasformahom f’embeddings bl-użu tal-API mistral-embed, u mbagħad taħżen dawn il-vetturi f’maħżen vettorjali li se jservi bħala magna tat-tiftix tiegħek. Dan huwa l-mument fejn il-korpus tiegħek jieqaf ikun test sempliċi u jsir ġeometrija li tista’ tiġi interrogata. Ftakar li xi prekawzjonijiet tal-inġinerija—bħall-ipproċessar bil-lottijiet (batching), it-tentattivi mill-ġdid (retries), u l-persistenza—huma d-differenza bejn prototip fraġli u indiċi affidabbli.
Għal korpus żgħir, ngħidu aħna inqas minn mitt biċċa, sejħa waħda diretta tkun biżżejjed. Estraj it-test mid-dizzjunarji tal-biċċiet tiegħek, għaddihom hekk kif inhuma lill-API, u rkupra l-matriċi sħiħa. Il-forma (87, 1024) murija fl-aħħar tal-eżekuzzjoni hija l-ewwel verifika tas-saħħa tiegħek: daqshekk ringieli kemm hemm biċċiet, u 1024 kolonna għax dik hija d-dimensjoni ta’ mistral-embed. Jekk in-numru ta’ ringieli ma jaqbilx, biċċa vojta daħlet fil-lott.
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
Ikkodifikar bil-Lottijiet (Batch Encoding)
Wara ftit għexieren ta’ biċċiet, sejħa waħda tilħaq il-limiti tal-API. Is-soluzzjoni hija li taqsam il-lista f’lottijiet u tgħaqqad ir-riżultati. Il-funzjoni hawn taħt tipproċessa sezzjonijiet ta’ 25 u turi l-progress. Dan mhuwiex biss estetiku: fuq korpus ta’ diversi eluf ta’ biċċiet, l-ikkodifikar jieħu diversi minuti, u trid tkun taf fejn qiegħed il-proċess minflok ma tħares lejn terminal sieket. L-ordni tinżamm, allura kull vettur jibqa’ allinjat mal-biċċa korrispondenti tiegħu fil-lista oriġinali tiegħek.
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")
Issopravvivi għall-Żbalji tan-Netwerk
Fil-produzzjoni, sejħa tal-API eventwalment se tfalli: waqgħa fin-netwerk, limitu ta’ rata milħuq, jew ħsara temporanja. Mingħajr protezzjoni, l-indiċjar tiegħek jieqaf fil-lott 180 minn 400, u terġa’ lura għall-bidu nett. Il-verżjoni robusta ddawwar kull lott f’ċiklu ta’ tentattiv mill-ġdid b’backoff esponenzjali—sekonda waħda, imbagħad tnejn, imbagħad erbgħa. Dan l-ispazjar li jiżdied huwa importanti: li tipprova mill-ġdid immedjatament wara ċaħda ta’ kwota biss tagħmel l-affarijiet agħar. Wara tliet fallimenti konsekuttivi, il-funzjoni tgħolli eċċezzjoni espliċita li tsemmi l-lott difettuż, minflok ma tirritorna matriċi mqassra fejn issib il-vojt biss waqt it-tiftix.
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)
Aħżen l-Indiċi fuq id-Disk
Kull ġirja ta’ kkodifikar tispiċċa ħin u sejħiet tal-API li jitħallsu. Li terġa’ tikkalkula l-vetturi kull darba li l-applikazzjoni tiegħek tibda huwa ħela pura, speċjalment peress li l-korpus innifsu ma nbidilx. Is-salvataġġ iseħħ f’żewġ fajls komplementari: il-vetturi jmorru f’NumPy, format binarju kompatt li jitgħabba minnufih, filwaqt li l-metadejta—test, sors, pożizzjoni—tmur f’JSON li tista’ taqra li tista’ tiftaħ biex tispezzjona biċċa suspettuża. Iż-żewġ fajls huma interdipendenti, marbuta bl-ordni tal-linji: qatt ma tiġġenera wieħed mingħajr l-ieħor, inkella r-riżultati tat-tiftix tiegħek jippuntaw għat-testijiet żbaljati.
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()
Ivverifika Qabel ma Tkompli
Indiċi korrott silenzjuż jidher tard, ġeneralment meta utent jirrapporta tweġiba assurda. Ftakar li ftit verifiki offline jieħdu tletin sekonda u jiffrankawlek dik l-iskoperta. Il-funzjoni ta’ verifika l-ewwel turi metrika bażika—numru ta’ biċċiet, dimensjoni, norma medja—imbagħad tkejjel is-similarità bejn biċċiet ġirien: peress li ġejjin mill-istess dokument, għandhom juru valuri sinifikantament ogħla minn żewġ passiġġi każwali. L-aħħar test huwa l-aktar sempliċi u l-aktar rivelatur: biċċa mqabbla magħha nnifisha trid tagħti eżattament 1.0. Kwalunkwe valur ieħor jissinjala problema ta’ allinjament jew problema ta’ konverżjoni numerika.
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)
Meta tingħaqdu, il-fluss tax-xogħol jinġabar f’erba’ linji utli. Tħejji l-biċċiet bil-pajplajn mil-lezzjoni ta’ qabel, tikkodifika fil-modalità robusta, tivverifika, u taħżen. Dan huwa l-iskript li se terġa’ tħaddem kull darba li l-korpus jiġi aġġornat.
# 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!")
Punti Ewlenin
- Uża l-ipproċessar bil-lottijiet biex tikkodifika korpus kbar (lottijiet ta’ 25–50 biċċa)
- Żid loġika ta’ tentattiv mill-ġdid b’backoff esponenzjali għar-robustezza
- Aħżen l-embeddings fuq id-disk (NumPy) biex tevita l-kalkolu mill-ġdid
- Żomm il-metadejta (test, sors, pożizzjoni) f’fajl JSON separat
- Ivverifika l-kwalità tal-embeddings qabel ma tużahom fil-produzzjoni