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

Indiċjar ta' korp ta' dokumenti

Lezzjoni 7 / 22 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Għanijiet
  2. Arkitettura ta’ indiċi semantiku
  3. Pipeline tal-indiċjar
  4. Aġġornamenti inkrementali
  5. Użu minn tarf għal tarf
  6. Punti Ewlenin

Għanijiet

  • Tibni indiċi sħiħ ta’ tfittxija semantika
  • Timmaniġġja formati differenti ta’ dokumenti (test, PDF, Markdown)
  • Taġġorna l-indiċi b’mod inkrementali

Arkitettura ta’ indiċi semantiku

Indiċi semantiku jiddependi fuq tliet elementi li jridu jibqgħu sinkronizzati: id-dokumenti oriġinali maħżuna mal-metadejta tagħhom, l-embeddings ikkalkolati mit-test tagħhom, u l-mappatura li tgħaqqad kull vettur mad-dokument sors tiegħu. Din it-tielet biċċa hija l-aktar waħda fraġli—hija kważi dejjem fejn l-indiċi jikkorrompu, meta tħassira tbiddel l-indiċi fuq naħa waħda iżda mhux fuq l-oħra.

Il-klassi Document hawn taħt iżżid hash MD5 ikkalkolat awtomatikament fil-ħolqien. Nużawha aktar tard biex nindunaw b’x’inhu diġà ġie indiċjat.

from dataclasses import dataclass, field
from openai import OpenAI
import numpy as np
import json
import hashlib

@dataclass
class Document:
    id: str
    texte: str
    metadata: dict = field(default_factory=dict)
    hash: str = ""

    def __post_init__(self):
        self.hash = hashlib.md5(self.texte.encode()).hexdigest()

Pipeline tal-indiċjar

Pass 1: Ittagħbija tad-dokumenti

L-ittagħbija tiddependi mill-format, u l-format jiddetermina l-granularità. Fajl ta’ test sempliċi jsir dokument wieħed; fajl Markdown, madankollu, spiss ikun fih diversi suġġetti distinti, u li tindikjah bħala blokk wieħed igħarraq kull suġġett fil-medja tal-oħrajn. Għalhekk, it-tieni loader jaqsam skont l-intestaturi ta’ livell 2 u jerġa’ jdaħħal it-titolu tas-sezzjoni fit-test indiċjat—din hija t-teknika ta’ arrikkiment koperta fil-lezzjoni 3.

from pathlib import Path

def charger_fichiers_texte(dossier: str) -> list[Document]:
    """Load all text files from a folder."""
    documents = []
    for fichier in Path(dossier).rglob("*.txt"):
        contenu = fichier.read_text(encoding="utf-8").strip()
        if contenu:
            documents.append(Document(
                id=fichier.stem,
                texte=contenu,
                metadata={
                    "fichier": str(fichier),
                    "type": "txt",
                    "taille": len(contenu)
                }
            ))
    return documents

def charger_fichiers_markdown(dossier: str) -> list[Document]:
    """Load Markdown files, splitting by sections."""
    documents = []
    for fichier in Path(dossier).rglob("*.md"):
        contenu = fichier.read_text(encoding="utf-8")
        sections = contenu.split("\n## ")

        for i, section in enumerate(sections):
            if not section.strip():
                continue
            titre = section.split("\n")[0].strip("# ")
            corps = "\n".join(section.split("\n")[1:]).strip()
            if corps:
                documents.append(Document(
                    id=f"{fichier.stem}_section_{i}",
                    texte=f"{titre}\n\n{corps}",
                    metadata={
                        "fichier": str(fichier),
                        "section": titre,
                        "type": "markdown"
                    }
                ))
    return documents

Pass 2: Il-bini tal-indiċi

Il-klassi IndexSemantique tiġbor flimkien il-kostruzzjoni bil-lottijiet, it-tfittxija bbażata fuq limitu (threshold), u l-persistenza fuq id-diska. Il-parametru seuil (limitu) fil-metodu rechercher jistħoqqilu attenzjoni: mingħajru, mistoqsija barra mit-tema xorta tirritorna l-ħames dokumenti l-inqas ħżiena, b’punteġġi madwar 0.15 li sejjaħ naiv jittratta bħala tweġibiet validi. Li tiffiltra kull ħaġa taħt punteġġ minimu jħallik tirrispondi b’mod onest, “Ma sibt xejn.”

class IndexSemantique:
    def __init__(self, model: str = "text-embedding-3-large"):
        self.client = OpenAI()
        self.model = model
        self.documents: list[Document] = []
        self.embeddings: np.ndarray | None = None

    def construire(self, documents: list[Document], batch_size: int = 100):
        """Build the index from a list of documents."""
        self.documents = documents
        textes = [d.texte for d in documents]
        tous_embeddings = []

        for i in range(0, len(textes), batch_size):
            batch = textes[i:i + batch_size]
            response = self.client.embeddings.create(
                input=batch,
                model=self.model
            )
            batch_sorted = sorted(response.data, key=lambda x: x.index)
            tous_embeddings.extend([e.embedding for e in batch_sorted])
            print(f"  Batch {i // batch_size + 1} processed "
                  f"({min(i + batch_size, len(textes))}/{len(textes)})")

        self.embeddings = np.array(tous_embeddings, dtype=np.float32)
        print(f"Index built: {len(self.documents)} documents, "
              f"{self.embeddings.shape[1]} dimensions")

    def rechercher(self, requete: str, k: int = 5,
                   seuil: float = 0.0) -> list[dict]:
        """Search for the k most relevant documents."""
        query_emb = self.client.embeddings.create(
            input=requete,
            model=self.model
        ).data[0].embedding

        scores = self.embeddings @ np.array(query_emb)
        top_indices = np.argsort(scores)[-k:][::-1]

        resultats = []
        for idx in top_indices:
            score = float(scores[idx])
            if score >= seuil:
                doc = self.documents[idx]
                resultats.append({
                    "id": doc.id,
                    "texte": doc.texte[:200],
                    "score": score,
                    "metadata": doc.metadata
                })
        return resultats

    def sauvegarder(self, chemin: str):
        """Save the index to disk."""
        np.save(f"{chemin}_embeddings.npy", self.embeddings)
        docs_serialisables = [
            {"id": d.id, "texte": d.texte,
             "metadata": d.metadata, "hash": d.hash}
            for d in self.documents
        ]
        with open(f"{chemin}_documents.json", "w") as f:
            json.dump(docs_serialisables, f, ensure_ascii=False)

    def charger(self, chemin: str):
        """Load an index from disk."""
        self.embeddings = np.load(f"{chemin}_embeddings.npy")
        with open(f"{chemin}_documents.json") as f:
            docs = json.load(f)
        self.documents = [
            Document(id=d["id"], texte=d["texte"],
                     metadata=d["metadata"])
            for d in docs
        ]

Il-metodi sauvegarder u charger jiktbu żewġ fajlijiet li jaqsmu l-istess prefiss. Itrattahom bħala par inseparabbli: li tikkopja wieħed mingħajr l-ieħor, jew li tirrestawra backup parzjali, jipproduċi indiċi fejn il-vetturi ma jaqblux aktar mad-dokumenti—falliment silenzjuż li jidher biss bħala riżultati assurdi.

Aġġornamenti inkrementali

Korp ta’ dokumenti jevolvi: tliet dokumenti mmodifikati nhar it-Tnejn, għaxra miżjuda nhar l-Erbgħa. Li terġa’ tikkalkula ħmistax-il elf vettur għal kull bidla tiħli ħin u flus. Hawnhekk tidħol il-hash MD5: tidentifika l-kontenut, mhux il-fajl, allura dokument li nbidel ismu iżda mhux il-kontenut tiegħu ma jerġax jiġi indiċjat, filwaqt li dokument immodifikat jipproduċi hash differenti.

def mettre_a_jour(self, nouveaux_docs: list[Document]):
    """Add documents to the existing index."""
    # Filter out already indexed documents
    hashes_existants = {d.hash for d in self.documents}
    docs_a_ajouter = [
        d for d in nouveaux_docs if d.hash not in hashes_existants
    ]

    if not docs_a_ajouter:
        print("No new documents to index")
        return

    textes = [d.texte for d in docs_a_ajouter]
    response = self.client.embeddings.create(
        input=textes,
        model=self.model
    )

    nouveaux_vecteurs = np.array(
        [e.embedding for e in sorted(response.data, key=lambda x: x.index)],
        dtype=np.float32
    )

    self.documents.extend(docs_a_ajouter)
    self.embeddings = np.vstack([self.embeddings, nouveaux_vecteurs])
    print(f"{len(docs_a_ajouter)} documents added. "
          f"Total: {len(self.documents)}")

L-np.vstack jimpila l-vetturi l-ġodda taħt dawk antiki bl-istess ordni tal-extend fuq il-lista tad-dokumenti: din is-simetrija tippreserva l-mappatura. Innota, madankollu, il-limitazzjoni ta’ din l-implimentazzjoni—tżid, iżda ma tħassarx jew tibdilx. Għalhekk, dokument immodifikat jispiċċa preżenti darbtejn, fil-verżjoni antika u l-ġdida tiegħu. Li timmaniġġja t-tħassir jeħtieġ li tneħħi r-ringiela korrispondenti mill-matriċi, operazzjoni għalja f’NumPy, u din hija waħda mir-raġunijiet li timbotta t-timijiet lejn database tal-vetturi xierqa.

Użu minn tarf għal tarf

Minn tarf għal tarf, il-bini ta’ indiċi fuq dokumentazzjoni jieħu biss ftit linji.

# Create and populate the index
index = IndexSemantique()

docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")

index.construire(docs)
index.sauvegarder("mon_index")

# Search
resultats = index.rechercher("how to configure authentication", k=3)
for r in resultats:
    print(f"[{r['score']:.3f}] {r['id']}")
    print(f"  {r['texte'][:100]}...")

Iġġribha fuq id-dokumentazzjoni tiegħek stess u agħmel tliet mistoqsijiet li taf it-tweġibiet tagħhom. Jekk id-dokument it-tajjeb ma jkunx l-ewwel fil-klassifika, il-ħati kważi dejjem ikun il-qtugħ (chunking)—sezzjonijiet twal wisq jew titoli mhux imdaħħla lura—aktar milli l-mudell tal-embedding.

Punti Ewlenin

  • Indiċi semantiku jgħaqqad dokumenti, embeddings u metadejta
  • Ittagħbija ta’ dokumenti minn formati differenti (test, Markdown, eċċ.)
  • Bini tal-indiċi bil-lottijiet biex jiġu ttrattati korpi kbar ta’ dokumenti
  • Ħażna u aġġornament inkrementali biex tiġi evitata l-kalkolazzjoni mill-ġdid ta’ kollox