Arquitectura (Guía para Vibe Coders)

1. Parseo

El contenido se parsea desde diversas fuentes a texto plano:

• Notion: Parseo bloque por bloque preservando la jerarquía
• DOCX: Extraído mediante mammoth.js
• Markdown: Parseado con remark/unified
• Website: Sitio web: Rastreado y limpiado de navegación/pie de página

2. Fragmentación

El texto se divide en fragmentos con solapamiento para una recuperación óptima:

{
  targetSize: 400,    // tokens per chunk
  overlap: 50,        // token overlap between chunks
  preserveHeadings: true,  // keep heading context
  minChunkSize: 100   // minimum viable chunk
}

Cada fragmento preserva la jerarquía de encabezados de su elemento padre para mantener el contexto.

3. Embedding

Los fragmentos se convierten en vectores de 1536 dimensiones:

Model: text-embedding-3-small
Dimensions: 1536
Provider: OpenAI (via OpenRouter)

4. Almacenamiento

Los vectores se almacenan en PostgreSQL con la extensión pgvector:

-- content_chunks table
id: uuid
knowledge_base_id: uuid
page_id: string
page_title: string
content: text
embedding: vector(1536)
parent_heading: string

Búsqueda híbrida

Utilizamos un proceso de recuperación en dos etapas:

1. Vector Search: Búsqueda vectorial: Similitud coseno usando el operador <=> de pgvector
2. Keyword Fallback: Respaldo por palabras clave: Si los resultados vectoriales tienen baja similitud, agregamos fragmentos coincidentes por palabras clave

Puntuación de similitud

-- Vector similarity query
SELECT *, 1 - (embedding <=> query_embedding) as similarity
FROM content_chunks
WHERE knowledge_base_id = $1
ORDER BY embedding <=> query_embedding
LIMIT 5

Puntuación de confianza

Antes de generar, calculamos una puntuación de confianza:

confidence = bestSimilarity + (hasMultipleChunks ? 0.1 : 0) + 0.2
// Capped at 1.0

if (confidence < threshold) {
  return refusalMessage;  // Don't hallucinate
}

Extracción de citas

Se instruye al LLM para usar el formato [Fuente N]. Parseamos estas citas y las enlazamos a las páginas originales:

// Extract citations from answer
const citationPattern = /\[Source (\d+)\]/g;
const matches = answer.matchAll(citationPattern);

// Map to original pages
citations = matches.map(m => chunks[m[1] - 1])