---
title: "plugin RAG"
description: "Ingresa el texto, embebelo, recupera los top-K y responde preguntas basadas en hechos — todo en una sola clase de PHP."
---

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
```php
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]`.
```php
$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
```php
$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`:
```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](/en/ai/module/agent/) 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 →](/es/ai/modulo/agente/) para herramientas, no recuperación.
- [Entrenamiento nibiru-coder →](/es/ai/modulo/entrenamiento/) para que el chat responda a la mitad en voz del marco.
