Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Oħloq l-Embeddings

Lezzjoni 11 / 18 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ikkodifika l-Biċċiet f’Vetturi
  2. Ikkodifikar bil-Lottijiet (Batch Encoding)
  3. Issopravvivi għall-Żbalji tan-Netwerk
  4. Aħżen l-Indiċi fuq id-Disk
  5. Ivverifika Qabel ma Tkompli
  6. Punti Ewlenin

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