Премини към основното съдържание
Български— Изберете език
Меню

Индексиране на корпус от документи

Урок 7 от 22 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Цели
  2. Архитектура на семантичен индекс
  3. Конвейер за индексиране
  4. Инкрементални актуализации
  5. Използване от край до край
  6. Ключови изводи

Цели

  • Изграждане на пълен индекс за семантично търсене
  • Обработка на различни формати документи (текст, PDF, Markdown)
  • Актуализиране на индекса инкрементално

Архитектура на семантичен индекс

Семантичният индекс разчита на три елемента, които трябва да останат синхронизирани: оригиналните документи, съхранени заедно с техните метаданни; вгражданията (embeddings), изчислени от техния текст; и съпоставянето, което свързва всеки вектор с неговия изходен документ. Третият елемент е най-крехкият – почти винаги там се повреждат индексите, когато изтриване измести индексите от едната страна, но не и от другата.

Класът Document по-долу добавя 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: Зареждане на документи

Зареждането зависи от формата, а форматът определя гранулярността. Обикновен текстов файл става един документ; файлът с Markdown обаче често съдържа няколко различни теми и индексирането му като един блок би удавило всяка тема в средното аритметично на останалите. Вторият зареждач затова разделя текста по заглавия от второ ниво и reinject-ва заглавието на секцията в индексирания текст – това е техниката за обогатяване, разгледана в урок 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

Стъпка 2: Изграждане на индекса

Класът IndexSemantique обединява пакетното изграждане, търсенето на базата на праг и постоянството на диска. Параметърът seuil (праг) в метода rechercher заслужава внимание: без него заявка извън темата все пак връща петте най-малко лоши документа с резултати около 0,15, които наивният caller ще приеме за валидни отговори. Филтрирането на всичко под определен минимален резултат Ви позволява честно да отговорите: „Не открих нищо“.

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
        ]

Методите sauvegarder и charger записват два файла, споделящи един и същ префикс. Третирайте ги като неразделна двойка: копирането на единия без другия или възстановяването на частично резервно копие води до индекс, при който векторите вече не съвпадат с документите – тиха грешка, която ще се прояви единствено чрез абсурдни резултати.

Инкрементални актуализации

Един корпус еволюира: три документа са модифицирани в понеделник, десет са добавени в сряда. Преизчисляването на петнадесет хиляди вектора за всяка промяна губи време и пари. Тук идва ред на MD5 хеша: той идентифицира съдържанието, а не файла, така че преименуван, но непроменен документ няма да бъде реиндексиран, докато модифициран документ ще генерира различен хеш.

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 поставя новите вектори под старите в същия ред, в който extend действа върху списъка с документи: тази симетрия запазва съпоставянето. Отбележете обаче ограничението на тази реализация – тя добавя, но не изтрива и не замества. Модифициран документ следователно присъства два пъти: в старата и в новата си версия. Обработката на изтривания изисква премахване на съответния ред от матрицата, което е скъпа операция в NumPy, и това е една от причините, които тласкат екипите към използването на истинска векторна база данни.

Използване от край до край

От начало до край, изграждането на индекс върху документация отнема само няколко реда.

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

Стартирайте го върху собствената си документация и задайте три въпроса, чиито отговори знаете. Ако правилният документ не се класира първи, виновникът почти винаги е разделянето на части (chunking) – секциите са твърде дълги или заглавията не са reinject-нати, – а не моделът за вграждане.

Ключови изводи

  • Семантичният индекс свързва документи, вграждания и метаданни
  • Зареждайте документи от различни формати (текст, Markdown и др.)
  • Изграждайте индекса на пакети, за да обработвате големи корпуси
  • Запазвайте и актуализирайте инкрементално, за да избегнете преизчисляването на всичко