Indeksowanie korpusu dokumentów
Na tej stronie
Cele
- Zbuduj kompletny indeks wyszukiwania semantycznego
- Obsłuż różne formaty dokumentów (tekst, PDF, Markdown)
- Aktualizuj indeks przyrostowo
Architektura indeksu semantycznego
Indeks semantyczny opiera się na trzech elementach, które muszą pozostać zsynchronizowane: oryginalne dokumenty przechowywane wraz z ich metadanymi, embeddingi obliczone na podstawie ich treści oraz mapowanie łączące każdy wektor z jego dokumentem źródłowym. Ten trzeci element jest najbardziej kruchy – to właśnie tutaj indeksy ulegają uszkodzeniu, gdy usunięcie przesunie indeksy po jednej stronie, a nie po drugiej.
Poniższa klasa Document dodaje hash MD5 obliczany automatycznie podczas tworzenia obiektu. Wykorzystamy go później do wykrycia tego, co zostało już zaindeksowane.
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()
Potok indeksowania
Krok 1: Ładowanie dokumentów
Ładowanie zależy od formatu, a format determinuje ziarnistość. Zwykły plik tekstowy staje się pojedynczym dokumentem; plik Markdown często zawiera jednak kilka odrębnych tematów, a zaindeksowanie go jako jednego bloku utopiłoby każdy temat w uśrednieniu pozostałych. Drugi loader dzieli więc tekst według nagłówków poziomu drugiego i wstrzykuje tytuł sekcji z powrotem do indeksowanego tekstu – jest to technika wzbogacania omówiona w lekcji 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
Krok 2: Budowa indeksu
Klasa IndexSemantique łączy w sobie budowę wsadową, wyszukiwanie oparte na progu oraz trwałość na dysku. Parametr seuil (próg) w metodzie rechercher zasługuje na uwagę: bez niego zapytanie niezwiązane z tematem nadal zwraca pięć „najmniej złych“ dokumentów z wynikami około 0,15, które naiwny wywołujący potraktuje jako poprawne odpowiedzi. Odfiltrowanie wszystkiego poniżej minimalnego wyniku pozwala szczerze odpowiedzieć: „Nic nie znalazłem“.
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
]
Metody sauvegarder i charger zapisują dwa pliki dzielące ten sam prefiks. Traktuj je jako nierozłączną parę: skopiowanie jednego bez drugiego lub przywrócenie częściowej kopii zapasowej tworzy indeks, w którym wektory nie pasują już do dokumentów – jest to cicha awaria, która ujawni się jedynie jako absurdalne wyniki.
Aktualizacje przyrostowe
Korpus ewoluuje: trzy dokumenty zmodyfikowane w poniedziałek, dziesięć dodanych w środę. Ponowne obliczanie piętnastu tysięcy wektorów dla każdej zmiany to strata czasu i pieniędzy. Tutaj przydaje się hash MD5: identyfikuje on treść, a nie plik, więc dokument o zmienionej nazwie, ale niezmienionej zawartości, nie zostanie ponownie zaindeksowany, podczas gdy zmodyfikowany dokument wygeneruje inny hash.
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)}")
Funkcja np.vstack układa nowe wektory poniżej starych w tej samej kolejności, co operacja extend na liście dokumentów: ta symetria zachowuje mapowanie. Zauważ jednak ograniczenie tej implementacji – dodaje ona dokumenty, ale ich nie usuwa ani nie zastępuje. Zmodyfikowany dokument pojawia się więc dwukrotnie: w starej i nowej wersji. Obsługa usuwania wymaga usunięcia odpowiedniego wiersza z macierzy, co jest kosztowną operacją w NumPy, i jest to jeden z powodów, dla których zespoły przechodzą na odpowiednie bazy danych wektorowych.
Użycie end-to-end
Kompleksowa budowa indeksu nad dokumentacją zajmuje zaledwie kilka linii kodu.
# 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]}...")
Uruchom to na własnej dokumentacji i zadaj trzy pytania, na które znasz odpowiedzi. Jeśli właściwy dokument nie znajdzie się na pierwszym miejscu, winowajcą jest prawie zawsze chunking – sekcje zbyt długie lub niewstrzyknięte tytuły – a nie model embeddingów.
Kluczowe wnioski
- Indeks semantyczny łączy dokumenty, embeddingi i metadane
- Ładuj dokumenty z różnych formatów (tekst, Markdown itp.)
- Buduj indeks wsadowo, aby obsłużyć duże korpusy
- Zapisuj i aktualizuj przyrostowo, aby uniknąć ponownego obliczania wszystkiego