Indekseeri dokumentide kogu
Sellel lehel
Eesmärgid
- Ehita terviklik semantiline otsinguindeks
- Käitle erinevaid dokumendivorminguid (tekst, PDF, Markdown)
- Uuenda indeksit inkrementaalselt
Semantilise indeksi arhitektuur
Semantiline indeks tugineb kolmele elemendile, mis peavad jääma sünkrooni: algupärased dokumendid koos oma metaandmetega, nende tekstist arvutatud manused (embeddings) ja seos, mis ühendab iga vektori selle allikadokumendiga. See kolmas osa on kõige habras – just siin lähevad indeksid kõige sagedamini katki, kui kustutamine nihutab indekseid ühel pool, kuid mitte teisel.
Allpool olev Document klass lisab MD5 räsi, mis arvutatakse loomisel automaatselt. Kasutame seda hiljem tuvastamaks, mis on juba indekseeritud.
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()
Indekseerimise torustik
1. samm: laadi dokumendid
Laadimine sõltub vormingust ja vorming määrab granulaarsuse. Lihtne tekstifail muutub üheks dokumendiks; Markdown-fail sisaldab aga sageli mitut erinevat teemat ja selle indekseerimine ühe plokina uputaks iga teema teiste keskmisesse. Teine laadija jagab faili seetõttu teise taseme pealkirjade järgi ja süstib jaotise pealkirja indekseeritavasse teksti tagasi – see on rikastamise tehnika, mida käsitlesime 3. tunnis.
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
2. samm: ehita indeks
Klass IndexSemantique ühendab partiihaaval ehitamise, lävendipõhise otsingu ja püsiva salvestamise kettale. Meetodi rechercher parameeter seuil (lävend) väärib tähelepanu: ilma selleta tagastab teemaväline päring ikkagi viis kõige vähem halba dokumenti, skooridega umbes 0,15, mida naiivne kasutaja käsitleb kehtivate vastustena. Kõigi alla miinimumskoori jäävate tulemuste filtreerimine võimaldab sul ausalt vastata: „Ma ei leidnud midagi.“
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
]
Meetodid sauvegarder ja charger kirjutavad kaks faili, millel on sama eesliide. Kohtle neid lahutamatu paarina: ühe kopieerimine ilma teiseta või osalise varukoopia taastamine tekitab indeksi, kus vektorid ei vasta enam dokumentidele – see on vaikne tõrge, mis avaldub alles absurdsete tulemustena.
Inkrementaalsed uuendused
Dokumentide kogu areneb: kolm dokumenti muudeti esmaspäeval, kümme lisati kolmapäeval. Viieteistkümne tuhande vektori ümberarvutamine iga muudatuse jaoks raiskab aega ja raha. Siin tulebki mängu MD5 räsi: see tuvastab sisu, mitte faili, nii et ümber nimetatud, kuid muutumata dokumenti ei indekseerita uuesti, samas muudetud dokument annab erineva räsi.
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)}")
np.vstack asetab uued vektorid vanade alla samas järjekorras, nagu dokumentide loendis toimub extend: see sümmeetria säilitab vastavuse. Pane tähele aga selle teostuse piirangut – see ainult lisab, kuid ei kustuta ega asenda. Muudetud dokument lõpeb seega topelt: nii vanas kui ka uues versioonis. Kustutamiste käsitlemine nõuab vastava rea eemaldamist maatriksist, mis on NumPys kulukas operatsioon, ja see on üks põhjusi, miks meeskonnad liiguvad korraliku vektorandmebaasi poole.
Kasutamine otsast otsani
Otsast otsani võtab dokumentatsiooni üle indeksi loomine vaid mõned read.
# 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]}...")
Käivita see oma dokumentatsioonil ja esita kolm küsimust, mille vastuseid sa tead. Kui õige dokument ei ole esikohal, on süüdlane peaaegu alati tükeldamine – jaotised on liiga pikad või pealkirju ei süstitud tagasi – mitte manuste mudel.
Peamised punktid
- Semantiline indeks seob omavahel dokumendid, manused ja metaandmed
- Laadi dokumente erinevatest vormingutest (tekst, Markdown jne)
- Ehita indeks partiihaaval, et hallata suuri kogusid
- Salvesta ja uuenda inkrementaalselt, et vältida kõige ümberarvutamist