Ir al contenido principal
Español— Elegir un idioma
Menú

Indexar un corpus de documentos

Lección 7 de 22 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Objetivos
  2. Arquitectura de un índice semántico
  3. Canalización de indexación
  4. Actualizaciones incrementales
  5. Uso de extremo a extremo
  6. Resumen

Objetivos

  • Construir un índice de búsqueda semántica completo
  • Gestionar diferentes formatos de documento (texto, PDF, Markdown)
  • Actualizar el índice de forma incremental

Arquitectura de un índice semántico

Un índice semántico se basa en tres elementos que deben mantenerse sincronizados: los documentos originales almacenados con sus metadatos, las incrustaciones (embeddings) calculadas a partir de su texto y la correspondencia que vincula cada vector con su documento fuente. Esta tercera pieza es la más frágil; casi siempre es donde los índices se corrompen, cuando una eliminación desplaza los índices en un lado pero no en el otro.

La clase Document que aparece a continuación añade un hash MD5 calculado automáticamente durante la creación. Lo utilizaremos más adelante para detectar qué contenido ya ha sido indexado.

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()

Canalización de indexación

Paso 1: Cargar documentos

La carga depende del formato, y el formato determina la granularidad. Un archivo de texto plano se convierte en un único documento; un archivo Markdown, sin embargo, suele contener varios temas distintos, e indexarlo como un solo bloque ahogaría cada tema en el promedio de los demás. El segundo cargador divide por tanto por encabezados de nivel 2 y reinyecta el título de la sección en el texto indexado: esta es la técnica de enriquecimiento tratada en la lección 3.

from pathlib import Path

def charger_fichiers_texte(dossier: str) -> list[Document]:
    """Cargar todos los archivos de texto de una carpeta."""
    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]:
    """Cargar archivos Markdown, dividiéndolos por secciones."""
    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

Paso 2: Construir el índice

La clase IndexSemantique agrupa la construcción por lotes, la búsqueda basada en umbrales y la persistencia en disco. El parámetro seuil (umbral) del método rechercher merece atención: sin él, una consulta fuera de tema seguiría devolviendo los cinco documentos «menos malos», con puntuaciones alrededor de 0,15 que un llamador ingenuo trataría como respuestas válidas. Filtrar cualquier resultado por debajo de una puntuación mínima te permite responder con honestidad: «No he encontrado nada».

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):
        """Construir el índice a partir de una lista de documentos."""
        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"  Lote {i // batch_size + 1} procesado "
                  f"({min(i + batch_size, len(textes))}/{len(textes)})")

        self.embeddings = np.array(tous_embeddings, dtype=np.float32)
        print(f"Índice construido: {len(self.documents)} documentos, "
              f"{self.embeddings.shape[1]} dimensiones")

    def rechercher(self, requete: str, k: int = 5,
                   seuil: float = 0.0) -> list[dict]:
        """Buscar los k documentos más relevantes."""
        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):
        """Guardar el índice en disco."""
        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):
        """Cargar un índice desde disco."""
        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
        ]

Los métodos sauvegarder y charger escriben dos archivos que comparten el mismo prefijo. Trátalos como un par inseparable: copiar uno sin el otro, o restaurar una copia de seguridad parcial, produce un índice donde los vectores ya no coinciden con los documentos; un fallo silencioso que solo se manifestará con resultados absurdos.

Actualizaciones incrementales

Un corpus evoluciona: tres documentos modificados el lunes, diez añadidos el miércoles. Recalcular quince mil vectores por cada cambio desperdicia tiempo y dinero. Aquí es donde entra el hash MD5: identifica el contenido, no el archivo, de modo que un documento renombrado pero no modificado no se volverá a indexar, mientras que un documento modificado producirá un hash diferente.

def mettre_a_jour(self, nouveaux_docs: list[Document]):
    """Añadir documentos al índice existente."""
    # Filtrar documentos ya indexados
    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 hay nuevos documentos que indexar")
        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)} documentos añadidos. "
          f"Total: {len(self.documents)}")

El np.vstack apila los nuevos vectores debajo de los antiguos en el mismo orden que el extend sobre la lista de documentos: esta simetría preserva la correspondencia. Observa, no obstante, la limitación de esta implementación: añade, pero no elimina ni reemplaza. Un documento modificado acaba, por tanto, presente dos veces, en su versión antigua y en la nueva. Gestionar eliminaciones requiere borrar la fila correspondiente de la matriz, una operación costosa en NumPy, y esta es una de las razones que empujan a los equipos hacia una base de datos vectorial adecuada.

Uso de extremo a extremo

De extremo a extremo, construir un índice sobre documentación requiere apenas unas pocas líneas.

# Crear y poblar el índice
index = IndexSemantique()

docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} secciones cargadas")

index.construire(docs)
index.sauvegarder("mon_index")

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

Ejecútalo con tu propia documentación y formula tres preguntas cuyas respuestas conozcas. Si el documento correcto no ocupa el primer puesto, el culpable es casi siempre la fragmentación (secciones demasiado largas o títulos no reinyectados), más que el modelo de incrustación.

Resumen

  • Un índice semántico vincula documentos, incrustaciones y metadatos
  • Carga documentos desde diferentes formatos (texto, Markdown, etc.)
  • Construye el índice por lotes para manejar corpus grandes
  • Guarda y actualiza de forma incremental para evitar recalcularlo todo