plugin RAG

El complemento RAG es la característica clave del módulo de IA para los constructores de productos. Convierte cualquier montón de texto — tus documentos de ayuda, tus registros de errores, tus facturas de Stripe, tus tickets de soporte al cliente — en una base de conocimientos consultable en aproximadamente cuatro líneas de PHP.

Tres minutos, de principio a fin

use Nibiru\Module\Ai\Ai;

$ai  = new Ai();
$rag = $ai->rag('product-help');     / a named collection

$rag->ingestDir(__DIR__ . '/help/'); / walks .md/.txt/.php under help/
$rag->ingestText('FAQ entry…', ['source' => 'faq-12']);

echo $rag->ask('How do I cancel my subscription?');
// → grounded answer, citing chunks like [1] [2] [3]

Eso es todo. Sin base de datos vectorial. Sin SDK. Sin sidecar de Python.

¿Cómo funciona

ingestText / ingestFile / ingestDir
        ↓
   chunk → embed (Ollama nomic-embed-text)
        ↓
   pack vectors → JSON file at cache/rag/<collection>.json
        ↓
ask(question) → embed question → cosine top-K → chat with chunks as context

El almacenamiento consta de un archivo JSON por colección. Cada fragmento es un objeto con texto + metadatos; los vectores están empaquetados en base64 como Float32Array — aproximadamente 3 KB por fragmento. Aproximadamente 10k fragmentos caben cómodamente en memoria.

Colecciones múltiples

Puedes tener cualquier número de colecciones en la misma aplicación. Cada una tiene su propio archivo JSON. Comparten el modelo de incrustación y el modelo de chat desde la configuración de [AI].

$docs    = $ai->rag('docs');
$tickets = $ai->rag('support-tickets');
$logs    = $ai->rag('error-logs');

$docs->ingestDir(__DIR__ . '/help/');
$tickets->ingestText($ticket->body, ['ticket_id' => $ticket->id]);
$logs->ingestText($exception->__toString(), ['ts' => time()]);

Referencia de la API

$rag = $ai->rag('name');                    / get/create a named collection

// --- Ingestion ---
$rag->ingestText($text, $metadata = []);    / single chunk
$count = $rag->ingestFile('path');          / returns chunks added
$count = $rag->ingestDir('dir', ['md','txt','php']); / recursive

// --- Querying ---
$hits = $rag->search('query', $k = null);   / [{score, text, metadata}, …]
$answer = $rag->ask('question', $k = null); / top-K → chat call

// --- Maintenance ---
$rag->reset();                              / forget everything (deletes file)
$n = $rag->size();                          / number of chunks

Perillas de ajuste

En application/module/ai/settings/ai.ini:

[AI]
embed.model        = "nomic-embed-text"   ; or mxbai-embed-large for higher quality
rag.top_k          = 6                    ; chunks injected into the chat call
rag.chunk_target   = 600                  ; tokens per chunk (target)
rag.chunk_min      = 120                  ; smaller chunks merged
rag.chunk_max      = 900                  ; larger paragraphs split on sentences
rag.storage_path   = "/../../application/module/ai/cache/rag/"

Cuando usarlo

• Ayuda / FAQ chat — ingesta tus artículos de ayuda, expón un punto final /ask.
• Búsqueda de código en la aplicación — ingesta application/module/, pregunta “¿Dónde calculamos el IVA?”
• Asistente de documentos internos — ingesta la volcada de tu wiki de equipo.
• Búsquedas de historial de clientes — ingesta los tickets, pregunta “¿Hemos visto este error antes?”

Cuándo NO usarlo

• Datos en tiempo real, de alta escritura — RAG es una instantánea. Para datos en vivo, escriba un Tool que el agente pueda llamar.
• Corpus masivos (> 100k fragmentos) — El almacenamiento en archivos JSON empieza a fallar. Pase a Qdrant / pgvector / Weaviate; publicaremos un adaptador una vez que nosotros mismos lo necesitemos.
• Cualquier cosa donde necesites respuestas exactas, no probables. RAG es probabilístico. No lo uses como capa de consulta de base de datos.

Trucos comunes

• nomic-embed-text no se ha extraído. La primera llamada a ingestText fallará con un error claro que te indicará el comando de extracción.
• Modelo de incrustación no coincidente. No mezcles fragmentos de nomic-embed-text con consultas de mxbai-embed-large — espacios vectoriales diferentes. Si cambias embed.model, ejecuta primero $rag->reset().
• Colecciones obsoletas. Volver a ejecutar ingestDir no elimina duplicados. Usa reset() y luego vuelve a ingestar, o mantén tú mismo una verificación de hash de contenido.
• Fragmentos pequeños. Por debajo de ~80 tokens, las incrustaciones se vuelven ruidosas. El valor predeterminado rag.chunk_min = 120 fusiona fragmentos pequeños adyacentes.

¿Qué sigue?

• Plugin de agente → para herramientas, no recuperación.
• Entrenamiento nibiru-coder → para que el chat responda a la mitad en voz del marco.