Przejdź do głównej treści
Polski— Wybierz język
Menu

Indeksowanie korpusu dokumentów

Lekcja 7 z 22 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Cele
  2. Architektura indeksu semantycznego
  3. Potok indeksowania
  4. Aktualizacje przyrostowe
  5. Użycie end-to-end
  6. Kluczowe wnioski

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