Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Innéacsú corpais doiciméad

Ceacht 7 as 22 Nuashonraithe 29 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Cuspóirí
  2. Ailtireacht innéacs seimintigh
  3. Píblíne innéacsaithe
  4. Nuashonruithe incriminteacha
  5. Úsáid ó thús go deireadh
  6. Príomhphointí

Cuspóirí

  • Innéacs cuardaigh sheimintigh iomlán a thógáil
  • Formáidí éagsúla doiciméad a láimhseáil (téacs, PDF, Markdown)
  • An t-innéacs a nuashonrú go hintéarálach

Ailtireacht innéacs seimintigh

Braitheann innéacs seimeantach ar thrí ghné a chaithfidh fanacht sioncronaithe: na bun-doiciméid stóráilte lena meiteashonraí, na leabaithe ríomhaithe óna dtéacs, agus an mhapáil a nascann gach veicteoir lena bhun-doiciméad. Is é an tríú píosa seo an ceann is leochailí—is ann a thruaillítear innéacsanna beagnach i gcónaí, nuair a athraíonn scriosadh innéacsanna ar thaobh amháin ach ní ar an taobh eile.

Cuireann an rang Document thíos hais MD5 leis a ríomhtar go huathoibríoch ag an am cruthaithe. Úsáidfimid é seo níos déanaí chun a bhrath cad atá innéacsaithe cheana féin.

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()

Píblíne innéacsaithe

Céim 1: Doiciméid a lódáil

Braitheann an lódáil ar an bhformáid, agus cinneann an fhormáid an ghránúlacht. Aon chomhad téacs simplí, déantar doiciméad amháin de; áfach, bíonn roinnt ábhar ar leith i gcomhad Markdown go minic, agus dá ndéanfá innéacsú air mar bhloc amháin, bháfaí gach ábhar i meán na n-ábhar eile. Dá bhrí sin, roinneann an dara lódóir de réir ceannlínte leibhéal 2 agus ath-insíonn sé teideal na rannóige isteach sa téacs innéacsaithe—is é seo an teicníc saibhrithe a clúdaíodh i gceacht 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

Céim 2: An t-innéacs a thógáil

Tugann an rang IndexSemantique le chéile tógáil bhaisc, cuardach bunaithe ar throscán, agus marthanacht diosca. Tá an paraiméadar seuil (troscán) sa mhodh rechercher tuillte aird: gan é, fágfaidh fiosrúchán as ábhar fós na cúig doiciméad is lú mí-oiriúnach, le scóir timpeall 0.15 a mheasfaidh glaoiteoir naïoch mar fhreagraí bailí. Tríd aon rud faoi scór urláir a scagadh amach, is féidir leat freagra macánta a thabhairt: “Níor aimsíodh aon rud.”

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
        ]

Scríobhann na modhanna sauvegarder agus charger dhá chomhad a roinneann an réimír céanna. Déileáil leo mar phéire doscartha: má chóipeálann tú ceann amháin gan an ceann eile, nó má athchóiríonn tú cúltaca páirteach, cruthófar innéacs nach meaitseálann na veicteoirí na doiciméid a thuilleadh—teip chiota a nochtar mar thorthaí absurd amháin.

Nuashonruithe incriminteacha

Athraíonn corpus: trí dhoiciméad athraithe Dé Luain, deich gceann curtha leis Dé Céadaoin. Cuirtear am agus airgead amú ag athríomh cúig mhíle veicteoir déag do gach athrú. Anseo a thagann an hais MD5 isteach: aithníonn sé ábhar, ní an comhad, mar sin ní dhéanfar ath-innéacsú ar dhoiciméad a athainmníodh ach nár athraigh, ach cruthóidh doiciméad modhnaithe hais difriúil.

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)}")

Cruachnaíonn np.vstack na veicteoirí nua faoi bhun na seanveicteoirí san ord céanna leis an extend ar an liosta doiciméad: coinníonn an tsiméadracht seo an mhapáil slán. Tabhair faoi deara, áfach, teorainn an chur chuige seo—cuireann sé leis, ach ní scriosann sé ná ní athsholáthraíonn sé. Mar sin, bíonn doiciméad modhnaithe i láthair faoi dhó, ina sheanleagan agus ina leagan nua. Éilíonn láimhseáil scriosadh an tsraith chomhfhreagrach a bhaint den mhaitrís, oibríocht costasach i NumPy, agus is é seo ceann de na cúiseanna a mbíonn foirne ag brú i dtreo bunachar sonraí veicteoireach cuí.

Úsáid ó thús go deireadh

Ó thús go deireadh, ní ghlacann tógáil innéacs thar doiciméadú ach cúpla líne.

# 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]}...")

Rith é ar do dhoiciméadú féin agus cuir trí cheist ar eolas duit na freagraí orthu. Mura bhfuil an doiciméad ceart rangaithe ar dtús, is é an mírú (chunking) an locht beagnach i gcónaí—rannóga ró-fhada nó teidil nach ndearnadh ath-insíobhadh orthu—seachas an tsamhail leabaithe.

Príomhphointí

  • Nascann innéacs seimeantach doiciméid, leabaithe, agus meiteashonraí
  • Lódáil doiciméid ó fhormáidí éagsúla (téacs, Markdown, srl.)
  • Tóg an t-innéacs i mbaisc chun corpais mhóra a láimhseáil
  • Sábháil agus nuashonraigh go hintéarálach chun athríomh gach rud a sheachaint