Индексиране на корпус от документи
На тази страница
Цели
- Изграждане на пълен индекс за семантично търсене
- Обработка на различни формати документи (текст, 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 и др.)
- Изграждайте индекса на пакети, за да обработвате големи корпуси
- Запазвайте и актуализирайте инкрементално, за да избегнете преизчисляването на всичко