Cargador de datos

Aprende a crear canalizaciones de carga de datos para alimentar tus aplicaciones RAG.

PRERREQUISITOS

Esta guía asume que ya estás familiarizado con RAG. Consulta la documentación dedicada: https://docs.neuron-ai.dev/rag

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

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

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

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

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

FileDataLoader

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

use NeuronAI\RAG\DataLoader\FileDataLoader;

// Lee un archivo y obtén "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 ser tratados como texto simple. Neuron te proporciona la ReaderInterface y varios componentes de lectura predefinidos para los formatos de archivo más comunes.

Ten en cuenta que cada lector de archivos está asociado a una extensión de archivo. Así que, en función de la extensión del archivo de entrada, el cargador de datos usará automáticamente el lector adecuado.

Lector de PDF

Para usar PdfReader necesitas instalar la utilidad poppler .

use NeuronAI\RAG\DataLoader\FileDataLoader;

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

Lector de HTML a Markdown

Para usar HtmlReader necesitas instalar la utilidad html2text paquete de composer.

use NeuronAI\RAG\DataLoader\FileDataLoader;

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

StringDataLoader

Si ya estás obteniendo texto de tu base de datos u otras fuentes, puedes usar StringDataLoader para convertir este texto en documentos, listos para ser convertidos en embeddings y almacenados por los otros componentes de Neuron en la cadena:

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

$contents = [
    // lista de cadenas (texto que quieres convertir en embeddings)
];

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:

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

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

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

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

La búsqueda híbrida te permite acotar el alcance de una consulta de búsqueda semántica contra registros que coinciden con ciertos criterios en otros campos del documento, en lugar de comparar solo los embeddings vectoriales. Explora la sección Vector Store para saber qué bases de datos admiten la búsqueda híbrida.

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 pueden convertirse en embeddings. El texto original se divide en partes más pequeñas para convertirse en embeddings y almacenarse en el almacén vectorial.

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

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

DelimiterTextSplitter (predeterminado)

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

$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 unidades de texto, menos precisa será la representación de los embeddings.

Separador

El texto primero se divide 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 del 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.

$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:

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:

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 en el pipeline del cargador de datos
$documents = FileDataLoader::for($directory)
    ->withSplitter(
        new CustomSplitter()
    )
    ->getDocuments();

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 texto en fragmentos dificulta actualizar piezas individuales de información cuando cambia el contenido del conocimiento original.

En Neuron, la Document class 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. Usando esta información puedes actualizar fácilmente el almacén vectorial con la versión actualizada del contenido de un archivo previamente usado como fuente de conocimiento.

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.

$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 algunos 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.

Usa componentes independientes

En los ejemplos siguientes usamos la instancia del agente RAG para procesar la parte final de la canalización de ingesta: generar embeddings para fragmentos de documentos y almacenarlos en la base de datos vectorial.

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

use App\Neuron\MyRAG;
use NeuronAI\RAG\DataLoader\FileDataLoader;
use NeuronAI\RAG\DataLoader\StringDataLoader;
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 \NeuronAI\RAG\DataLoader\PdfReader())
    ->getDocuments(); 

// Genera embeddings y almacena 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.