> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-es/rag/data-loader.md).

# Cargador de datos

Aprende cómo crear canales de carga de datos para alimentar tus aplicaciones RAG.

Para construir una aplicación de IA estructurada necesitas la capacidad de convertir toda la información que tienes en texto, para que puedas generar embeddings, guardarlos en un almacén vectorial y luego alimentar a tu Agente para responder a las preguntas del usuario.

<figure><img src="https://content.gitbook.com/content/GHx4l2LknIex7vFIUg1R/blobs/3At80JRFJJTpnz9st9wF/neuron-ai-data-loader-rag.png" alt=""><figcaption></figcaption></figure>

Neuron te ofrece varias herramientas (cargadores de datos) para simplificar este proceso.

```php
use App\Neuron\MyRAG;
use NeuronAI\RAG\DataLoader\FileDataLoader;

MyRAG::make()->addDocuments(
    // Usa el componente cargador de datos de archivos para procesar un archivo de texto
    FileDataLoader::for(__DIR__.'/my-article.md')->getDocuments()
);
```

Usando el kit de herramientas de Neuron puedes crear pipelines de carga de datos con las ventajas de interfaces unificadas para facilitar las interacciones entre componentes, como proveedores de embeddings, el almacén vectorial y los lectores de archivos.

## FileDataLoader

Si necesitas extraer texto de archivos, el `FileDataLoader` te permite procesar cualquier documento de texto sencillo.

```php
use NeuronAI\RAG\DataLoader\FileDataLoader;

// Lee un archivo y obtiene "documentos"
$documents = FileDataLoader::for(__DIR__.'/my-article.md')->getDocuments();

// Pasa un directorio para procesar todos los archivos
$documents = FileDataLoader::for(__DIR__)->getDocuments();
```

Por defecto `FileDataLoader` lee el contenido de un archivo tal como está en el sistema de archivos, pero no todos los tipos de archivo están listos para tratarse como texto simple. Neuron te proporciona ReaderInterface y varios componentes lectores predefinidos para los formatos de archivo más comunes.

Observa que cada lector de archivos está asociado a una extensión de archivo. Así que, según la extensión del archivo de entrada, el cargador de datos usará automáticamente el lector apropiado.

### Lector PDF

{% hint style="warning" %}
Para usar `PdfReader` necesitas instalar la [**poppler**](https://en.wikipedia.org/wiki/Pdftotext) utilidad.
{% endhint %}

```php
use NeuronAI\RAG\DataLoader\FileDataLoader;
use NeuronAI\RAG\DataLoader\PdfReader;

// Registra el lector de PDF
$documents = FileDataLoader::for(__DIR__)
    ->addReader('pdf', new PdfReader())
    ->getDocuments();
```

### Lector de HTML a Markdown

{% hint style="warning" %}
Para usar `HtmlReader` necesitas instalar la [**html2text**](https://github.com/mtibben/html2text) paquete de Composer.
{% endhint %}

```php
use NeuronAI\RAG\DataLoader\FileDataLoader;
use NeuronAI\RAG\DataLoader\HtmlReader;

// Registra el lector de PDF
$documents = FileDataLoader::for(__DIR__)
    ->addReader(['html', 'xhtml'], new HtmlReader())
    ->getDocuments();
```

### Lectores personalizados

Puedes crear libremente lectores de documentos personalizados; solo implementa la siguiente pequeña interfaz. Una vez que tu clase implemente este contrato, puedes pasársela a los cargadores de datos para transformar automáticamente tus documentos.

```php
interface ReaderInterface
{
    public function read(string $filePath): string;
}
```

### StringDataLoader

Si ya obtienes texto de tu base de datos u otras fuentes, puedes usar StringDataLoader para convertir este texto en documentos, listos para ser incrustados y almacenados por los otros componentes de Neuron en la cadena:

```php
use App\Neuron\MyRAG;
use NeuronAI\RAG\DataLoader\StringDataLoader;

$contents = [
    // lista de cadenas (texto que quieres incrustar)
];

foreach ($contents as $text) {
    $documents = StringDataLoader::for($text)->getDocuments(); 
    
    MyRAG::make()->addDocuments($documents);
}
```

### Metadatos del documento

Después de obtener el array de documentos de un cargador de datos, eventualmente puedes adjuntar metadatos personalizados al documento que se guardará en el almacén vectorial junto con otros campos predeterminados del documento:

```php
$documents = FileDataLoader::for($directory)->getDocuments(); 

foreach($documents as $document) {
    $document->addMetadata('user_id', 1234);
}

MyRAG::make()->addDocuments($documents);
```

Una vez que tienes estos campos personalizados en el almacén vectorial puedes usar búsqueda híbrida para bases de datos que admitan esta función.

{% hint style="info" %}
La búsqueda híbrida te permite acotar el alcance de una consulta de búsqueda semántica sobre registros que coinciden con ciertos criterios en otros campos del documento, en lugar de comparar solo los embeddings vectoriales. Explora la [sección Almacén vectorial](https://docs.neuron-ai.dev/neuron-v3-es/rag/vector-store.md) para saber qué bases de datos admiten la búsqueda híbrida.
{% endhint %}

## Divisor de texto

Los cargadores de datos de Neuron reciben archivos o texto como entrada y generan un array de `\NeuronAI\RAG\Document` objetos. Estos documentos son unidades que se pueden incrustar. El texto original se divide en fragmentos más pequeños para convertirse en embeddings y guardarse en el almacén vectorial.

La lógica que usan los cargadores de datos para dividir un texto largo en fragmentos puede personalizarse usando distintas estrategias. Neuron tiene un componente dedicado para este propósito llamado "Splitter", y puede adjuntarse al cargador de datos según la estrategia que prefieras o necesites:

```php
$documents = FileDataLoader::for($directory)
    ->withSplitter(
        new DelimiterTextSplitter()
    )
    ->getDocuments();
```

### DelimiterTextSplitter (predeterminado)

Este es el divisor predeterminado para todos los cargadores de datos.

```php
$documents = FileDataLoader::for($directory)
    ->withSplitter(
        new DelimiterTextSplitter(
            maxLength: 1000,
            separator: '.',
            wordOverlap: 0
        )
    )
    ->getDocuments();
```

Cada uno de estos parámetros tiene un impacto en el rendimiento y la precisión de tu agente RAG.

#### Longitud máxima

Cada fragmento no será más largo que este valor, y eventualmente se dividirá en documentos más pequeños. La longitud puede afectar la precisión de las representaciones de embeddings. Cuanto más largos sean tus fragmentos de texto, menos precisa será la representación de embeddings.

#### Separador

El texto se divide primero en fragmentos según un separador. Por defecto, el componente usa el carácter de punto. Eventualmente puedes personalizar este separador usando cualquier delimitador para tu texto.

#### Solapamiento

A veces puede ser útil incorporar palabras del fragmento anterior y siguiente en un documento para aumentar la conexión semántica entre secciones adyacentes del texto. Por defecto no se aplica solapamiento.

### SentenceTextSplitter

Divide el texto en oraciones, agrupa en fragmentos basados en palabras y, opcionalmente, aplica solapamiento en términos de palabras.

```php
$documents = FileDataLoader::for($directory)
    ->withSplitter(
        new SentenceTextSplitter(
            maxWords: 200,
            overlapWords: 0
        )
    )
    ->getDocuments();
```

**MaxWords**: número máximo de palabras por fragmento

**OverlapWords**: número de palabras superpuestas entre fragmentos

### Implementar divisores personalizados

Puedes implementar una lógica de división personalizada implementando la `SplitterInterface`:

```php
namespace NeuronAI\RAG\Splitter;

use NeuronAI\RAG\Document;

interface SplitterInterface
{
    /**
     * @return Document[]
     */
    public function splitDocument(Document $document): array;

    /**
     * @param  Document[]  $documents
     * @return Document[]
     */
    public function splitDocuments(array $documents): array;
}
```

Puedes interactuar con un servicio externo o crear tu propia lógica para dividir un texto largo en fragmentos más pequeños. Una vez que hayas creado tu implementación personalizada, puedes usarla con los cargadores de datos:

```php
class CustomSplitter implements SplitterInterface
{
    public function splitDocument(Document $document): array
    {
        // Tu lógica aquí...
    }
    
    public function splitDocuments(array $documents): array
    {
        // Tu lógica aquí...
    }
}

// Usa el divisor personalizado dentro del pipeline del cargador de datos
$documents = FileDataLoader::for($directory)
    ->withSplitter(
        new CustomSplitter()
    )
    ->getDocuments();
```

## Cargar documentos en un RAG

Cada documento lleva el texto que se va a incrustar, su fuente y cualquier metadato requerido por el esquema RAG. El esquema se configura al definir el RAG. Consulta [Configurar documentos y esquemas en un RAG](https://docs.neuron-ai.dev/neuron-v3-es/rag/rag.md#documents-and-schemas-in-rag).

### Añadir metadatos del esquema antes de la ingesta

El almacén vectorial valida cada documento frente al esquema. Añade los metadatos requeridos y filtrables después de cargar y antes de llamar a `addDocuments()`.

```php
foreach ($documents as $document) {
    $document
        ->addMetadata('tenant', 'acme')
        ->addMetadata('status', 'published')
        ->addMetadata('published_at', 1767225600)
        ->addMetadata('tags', ['php', 'ai']);
}
```

Usa el tipo declarado en el esquema. Por ejemplo, un campo entero requiere `2026`, no `'2026'`.

Los metadatos no declarados en el esquema también están permitidos. Deben contener valores seguros para JSON: cadenas, enteros, flotantes, booleanos, null o arrays que contengan esos valores.

```php
foreach ($documents as $document) {
    $document->addMetadata('ui_hint', [
        'color' => 'blue',
        'icon' => 'book',
    ]);
}
```

{% hint style="warning" %}
Los metadatos no declarados se almacenan y se devuelven, pero no pueden usarse en filtros.
{% endhint %}

### Crear documentos manualmente

Crea una `Documento` directamente cuando no se necesita un cargador. Establecer la fuente hace predecible su posterior reemplazo o eliminación.

```php
use NeuronAI\RAG\Document;

$document = (new Document('Neuron is an agentic PHP framework.'))
    ->setSourceType('article')
    ->setSourceName('introduction.md')
    ->setMetadata([
        'tenant' => 'acme',
        'status' => 'published',
        'published_at' => 1767225600,
        'tags' => ['php', 'ai'],
    ]);

$documents = [$document];
```

### Dividir un documento después de añadir metadatos

Al crear un documento manualmente, los metadatos pueden añadirse antes de dividirlo. Los divisores integrados copian la fuente y los metadatos a cada fragmento resultante.

```php
use NeuronAI\RAG\Document;
use NeuronAI\RAG\Splitter\SentenceTextSplitter;

$document = (new Document($content))
    ->setSourceType('cms')
    ->setSourceName('article-42')
    ->setMetadata([
        'tenant' => 'acme',
        'status' => 'published',
    ]);

$documents = (new SentenceTextSplitter(
    maxWords: 200,
    overlapWords: 20,
))->splitDocument($document);
```

### Incrustar y almacenar los documentos

`RAG::addDocuments()` completa la ingesta. Valida cada documento, crea su embedding y lo almacena en la base de datos vectorial configurada.

```php
KnowledgeBase::make()->addDocuments($documents);
```

Los documentos se procesan en lotes de 50 por defecto. Cambia el tamaño del lote cuando lo requiera el proveedor de embeddings:

```php
$rag->addDocuments($documents, chunkSize: 100);
```

La validación del esquema ocurre antes de la solicitud de embeddings. Por lo tanto, la ausencia de metadatos requeridos o un tipo incorrecto falla antes de consumir tokens de embeddings o escribir datos parciales para ese lote.

### Errores de validación comunes

Neuron rechaza documentos inválidos antes de la E/S de base de datos. Las causas más comunes son:

* falta un campo requerido o es null;
* un valor de metadato tiene un tipo distinto al del esquema;
* los metadatos contienen un objeto u otro valor no seguro para JSON;
* una aplicación intenta usar una propiedad reservada del documento como metadato.

## Reindexar la fuente de conocimiento

La reindexación es un tema candente en el diseño de sistemas RAG porque la práctica de dividir el texto en fragmentos dificulta actualizar piezas individuales de información cuando cambia el contenido del conocimiento original.

En Neuron, la `Documento` clase está diseñada para llevar algunos metadatos que te ayuden a identificar la fuente de cada pieza de conocimiento almacenada en la base de datos vectorial, como `sourceType` y `sourceName` campos. Con esta información puedes actualizar fácilmente el almacén vectorial con la versión actualizada del contenido de un archivo previamente utilizado como fuente de conocimiento.

{% hint style="warning" %}
La nueva versión del archivo **debe tener la misma ruta y nombre** que usaste originalmente, de lo contrario, los documentos se añadirán como nuevos.
{% endhint %}

```php
$documents = FileDataLoader::for("/path/to/directory")
    ->withSplitter(
        new SentenceTextSplitter(
            maxWords: 200,
            overlapWords: 0
        )
    )
    ->getDocuments();

// Reindexa por sourceType y sourceName
MyRAG::make()->reindexBySource($documents);
```

Si `sourceType` y `sourceName` de los Documentos ya están presentes en el almacén vectorial, se eliminarán y se guardarán los Documentos de la nueva versión. Los otros documentos se almacenarán como de costumbre en la base de datos vectorial.

## Usar componentes independientes

En los ejemplos de abajo usamos la instancia del agente RAG para procesar la parte final del pipeline de ingesta: generar embeddings para fragmentos de documento y almacenarlos en la base de datos vectorial.

Como alternativa, en lugar de aprovechar la instancia del agente RAG, puedes usar el proveedor de embeddings y el almacén vectorial como componentes independientes. Recuerda que el almacén vectorial aquí debe ser el mismo conectado al agente RAG.

```php
use App\Neuron\MyRAG;
use NeuronAI\RAG\DataLoader\FileDataLoader;
use NeuronAI\RAG\DataLoader\StringDataLoader;
use NeuronAI\RAG\DataLoader\PdfReader;
use NeuronAI\RAG\EmbeddingProvider\OpenAIEmbeddingProvider;
use NeuronAI\RAG\VectorStore\FileVectorStore;

$embedder = new OpenAIEmbeddingProvider(
    key: 'OPENAI_API_KEY',
    model: 'OPENAI_MODEL'
);

$store = new FileVectoreStore(
    directory: __DIR__,
    key: 'demo'
);

// Procesa archivos y contenidos
$documents = FileDataLoader::for(__DIR__.'/documents');
    ->addReader('pdf', new PdfReader())
    ->getDocuments(); 

// Genera embeddings y almacena los documentos en la base de datos vectorial
$store->addDocuments(
    $embedder->embedDocuments($documents)
);

```

Con este proceso sencillo puedes ingerir GB de datos en tu almacén vectorial para alimentar a tu agente RAG.
