Ευρετηρίαση ενός σώματος εγγράφων
Σε αυτήν τη σελίδα
Στόχοι
- Δημιουργία ενός πλήρους ευρετηρίου σημασιολογικής αναζήτησης
- Διαχείριση διαφορετικών μορφών εγγράφων (κείμενο, PDF, Markdown)
- Ενημέρωση του ευρετηρίου με αυξητικό τρόπο
Αρχιτεκτονική ενός σημασιολογικού ευρετηρίου
Ένα σημασιολογικό ευρετήριο βασίζεται σε τρία στοιχεία που πρέπει να παραμένουν συγχρονισμένα: τα πρωτότυπα έγγραφα αποθηκευμένα με τα μεταδεδομένα τους, τα ενσωματώματα (embeddings) που υπολογίζονται από το κείμενό τους και τη χαρτογράφηση που συνδέει κάθε διάνυσμα με το πηγαίο έγγραφό του. Αυτό το τρίτο στοιχείο είναι το πιο ευάλωτο· σχεδόν πάντα εκεί συμβαίνει η φθορά των ευρετηρίων, όταν μια διαγραφή μετατοπίζει τους δείκτες στη μία πλευρά αλλά όχι στην άλλη.
Η κλάση Document παρακάτω προσθέτει ένα hash MD5 που υπολογίζεται αυτόματα κατά τη δημιουργία. Θα το χρησιμοποιήσουμε αργότερα για να εντοπίσουμε τι έχει ήδη ευρετηριαστεί.
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()
Ροή ευρετηρίασης
Βήμα 1: Φόρτωση εγγράφων
Η φόρτωση εξαρτάται από τη μορφή, και η μορφή καθορίζει τον βαθμό κοκκοποίησης (granularity). Ένα απλό αρχείο κειμένου γίνεται ένα ενιαίο έγγραφο· ένα αρχείο Markdown, ωστόσο, συχνά περιέχει πολλά διακριτά θέματα, και η ευρετηρίασή του ως ένα ενιαίο μπλοκ θα «έπνιγε» κάθε θέμα στον μέσο όρο των υπολοίπων. Ο δεύτερος φορτωτής, επομένως, διαχωρίζει με βάση τις επικεφαλίδες επιπέδου 2 και επανεισάγει τον τίτλο της ενότητας στο ευρετηριασμένο κείμενο· αυτή είναι η τεχνική εμπλουτισμού που καλύφθηκε στο μάθημα 3.
from pathlib import Path
def charger_fichiers_texte(dossier: str) -> list[Document]:
"""Φόρτωση όλων των αρχείων κειμένου από έναν φάκελο."""
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]:
"""Φόρτωση αρχείων Markdown, με διαχωρισμό ανά ενότητες."""
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: Δημιουργία του ευρετηρίου
Η κλάση IndexSemantique συνδυάζει τη δημιουργία κατά παρτίδες, την αναζήτηση βάσει κατωφλίου και την επιμονή στον δίσκο. Η παράμετρος seuil (κατώφλι) στη μέθοδο rechercher αξίζει προσοχής: χωρίς αυτήν, ένα ερώτημα εκτός θέματος επιστρέφει παρ’ όλα αυτά τα πέντε λιγότερο κακά έγγραφα, με βαθμολογίες γύρω στο 0,15 που ένας αφελής καλών θα τις θεωρήσει έγκυρες απαντήσεις. Ο φιλτράρισμα οτιδήποτε βρίσκεται κάτω από μια ελάχιστη βαθμολογία σάς επιτρέπει να απαντήσετε ειλικρινά: «Δεν βρήκα τίποτα».
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):
"""Δημιουργία του ευρετηρίου από μια λίστα εγγράφων."""
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]:
"""Αναζήτηση για τα k πιο σχετικά έγγραφα."""
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):
"""Αποθήκευση του ευρετηρίου στον δίσκο."""
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):
"""Φόρτωση ενός ευρετηρίου από τον δίσκο."""
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
]
Οι μέθοδοι sauvegarder και charger γράφουν δύο αρχεία που μοιράζονται το ίδιο πρόθεμα. Θεωρήστε τα ως ένα αξεχώριστο ζεύγος: η αντιγραφή του ενός χωρίς το άλλο, ή η επαναφορά ενός μερικού αντιγράφου ασφαλείας, παράγει ένα ευρετήριο όπου τα διανύσματα δεν αντιστοιχούν πλέον στα έγγραφα· μια σιωπηρή αστοχία που θα εμφανιστεί μόνο ως παράλογα αποτελέσματα.
Αυξητικές ενημερώσεις
Ένα σώμα εγγράφων εξελίσσεται: τρία έγγραφα τροποποιούνται τη Δευτέρα, δέκα προστίθενται την Τετάρτη. Ο επανυπολογισμός δεκαπέντε χιλιάδων διανυσμάτων για κάθε αλλαγή σπαταλά χρόνο και χρήμα. Εδώ είναι που χρησιμεύει το hash MD5: αναγνωρίζει το περιεχόμενο, όχι το αρχείο, οπότε ένα έγγραφο που μετονομάστηκε αλλά δεν άλλαξε δεν θα ευρετηριαστεί εκ νέου, ενώ ένα τροποποιημένο έγγραφο θα παράγει διαφορετικό hash.
def mettre_a_jour(self, nouveaux_docs: list[Document]):
"""Προσθήκη εγγράφων στο υπάρχον ευρετήριο."""
# Φιλτράρισμα ήδη ευρετηριασμένων εγγράφων
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 στοιβάζει τα νέα διανύσματα κάτω από τα παλιά, με την ίδια σειρά όπως το extend στη λίστα εγγράφων: αυτή η συμμετρία διατηρεί τη χαρτογράφηση. Σημειώστε, ωστόσο, τον περιορισμό αυτής της υλοποίησης: προσθέτει, αλλά δεν διαγράφει ούτε αντικαθιστά. Ένα τροποποιημένο έγγραφο, επομένως, καταλήγει να υπάρχει δύο φορές, στην παλιά και στη νέα του εκδοχή. Η διαχείριση διαγραφών απαιτεί την αφαίρεση της αντίστοιχης γραμμής από τον πίνακα, μια δαπανηρή λειτουργία στο NumPy, και αυτός είναι ένας από τους λόγους που ωθούν τις ομάδες προς μια κατάλληλη βάση δεδομένων διανυσμάτων.
Χρήση από άκρη σε άκρη
Από άκρη σε άκρη, η δημιουργία ενός ευρετηρίου πάνω από τεκμηρίωση απαιτεί μόνο λίγες γραμμές κώδικα.
# Δημιουργία και συμπλήρωση του ευρετηρίου
index = IndexSemantique()
docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")
index.construire(docs)
index.sauvegarder("mon_index")
# Αναζήτηση
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]}...")
Εκτελέστε το στη δική σας τεκμηρίωση και κάντε τρεις ερωτήσεις των οποίων γνωρίζετε τις απαντήσεις. Αν το σωστό έγγραφο δεν κατατάσσεται πρώτο, ο ένοχος είναι σχεδόν πάντα η τμηματοποίηση (chunking) — ενότητες πολύ μεγάλες ή τίτλοι που δεν επανεισάγονται — και όχι το μοντέλο ενσωμάτωσης.
Βασικά σημεία
- Ένα σημασιολογικό ευρετήριο συνδέει έγγραφα, ενσωματώματα και μεταδεδομένα
- Φορτώστε έγγραφα από διαφορετικές μορφές (κείμενο, Markdown κ.λπ.)
- Δημιουργήστε το ευρετήριο κατά παρτίδες για τη διαχείριση μεγάλων σωμάτων εγγράφων
- Αποθηκεύστε και ενημερώστε με αυξητικό τρόπο για να αποφύγετε τον επανυπολογισμό των πάντων