> 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/rag.md).

# Primeros pasos

Guía paso a paso sobre cómo implementar Generación Aumentada por Recuperación con el marco Neuron.

{% hint style="info" %}

#### PRERREQUISITOS

Esta guía asume que ya estás familiarizado con los siguientes conceptos:

* [Agente](https://docs.neuron-ai.dev/neuron-v3-es/agente/agent.md)
* [Llamada a herramientas y funciones](https://docs.neuron-ai.dev/neuron-v3-es/agente/tools.md)
  {% endhint %}

{% hint style="warning" %}

#### Habilidad del agente de programación

Usa `/neuron-rag` para enseñarle a tu agente de programación cómo implementar un sistema RAG completo en tu aplicación con canalización de datos y estrategias de recuperación.

[Desarrollo asistido por IA](https://docs.neuron-ai.dev/neuron-v3-es/resumen/agentic-development.md)
{% endhint %}

La Generación Aumentada por Recuperación (RAG) es el proceso de proporcionar referencias a una base de conocimiento fuera de las fuentes de datos de entrenamiento del LLM antes de generar una respuesta.

Los Modelos de Lenguaje Grandes (LLM) se entrenan con enormes volúmenes de datos para poder generar resultados originales en tareas como responder preguntas, traducir idiomas y completar oraciones. RAG amplía las ya potentes capacidades de los LLM a dominios específicos o a la base de conocimiento interna de una organización, todo ello sin necesidad de volver a entrenar el modelo.

Es un enfoque rentable para mejorar la salida del LLM, de modo que siga siendo relevante, precisa y útil, y además funcione con tus propios datos privados.

{% embed url="<https://www.youtube.com/watch?v=ymSUOIxjoeM>" %}

## Por qué los sistemas RAG son relevantes

Construir un sistema RAG es la forma de usar las potentes capacidades de los LLM sobre tus propios datos privados. Puedes crear aplicaciones capaces de responder con precisión preguntas sobre la documentación interna de una empresa. O un chatbot para atender a clientes externos con las normas internas de una organización.

Si no se trata del uso de datos privados, puedes pensar en RAG como una forma de proporcionar a los modelos generativos las últimas investigaciones, estadísticas o noticias.

## Cómo crear un sistema RAG

Sin RAG, el LLM toma la entrada del usuario y crea una respuesta basada en la información con la que fue entrenado (lo que ya sabe).

Con RAG, se introduce un componente de recuperación de información. Utiliza la entrada del usuario para extraer primero información de una nueva fuente de datos. La consulta del usuario y la información relevante recuperada se entregan ambas al LLM. El LLM usa el nuevo conocimiento y sus datos de entrenamiento para crear respuestas precisas. Las siguientes secciones ofrecen una visión general del proceso.

Aunque pueda parecer un poco complicado, no te preocupes, esto solo es para que conozcas el proceso. La mayoría de estas cosas son gestionadas automáticamente por el agente RAG de Neuron.

Hay tres pasos más importantes para crear un sistema RAG.

#### 1) Procesar datos externos

Los datos externos que quieras usar para ampliar el conocimiento predeterminado del LLM pueden existir en varios formatos, como archivos, registros de bases de datos o texto extenso.

Antes de poder enviar estos datos al LLM, debes convertirlos a un formato específico llamado "[Embeddings](https://inspector.dev/vector-store-ai-agents-beyond-the-traditional-data-storage/)".

#### 2) Recuperación

Los embeddings que has generado al procesar documentos y datos deben almacenarse en bases de datos específicas capaces de manejar este formato particular. Estas bases de datos se llaman "[Almacén de vectores](https://inspector.dev/vector-store-ai-agents-beyond-the-traditional-data-storage/)".

Los almacenes de vectores no solo son capaces de almacenar estos datos, sino también de realizar una forma particular de búsqueda: la "búsqueda por similitud" entre los datos existentes en la base de datos y una consulta que proporcionamos.

#### 3) Aumentar el prompt del LLM

A continuación, el agente RAG amplía tu entrada (o prompt) añadiendo los datos relevantes recuperados en el contexto para hacer que el LLM conozca los datos personalizados antes de generar la respuesta.

Solo necesitas ocuparte del primer paso, "Procesar datos externos", y Neuron te proporciona las herramientas para hacerlo sencillo. Los otros pasos son gestionados automáticamente por el agente RAG de Neuron.

## Crear un agente RAG

Para crear un RAG necesitas adjuntar algunos componentes adicionales además del proveedor de IA, como un `almacén de vectores`, y un `proveedor de embeddings`.

Primero, creemos la clase RAG:

{% tabs %}
{% tab title="Unix" %}

```bash
vendor/bin/neuron make:rag App\\Neuron\\MyChatBot
```

{% endtab %}

{% tab title="Windows" %}

```powershell
.\vendor\bin\neuron make:rag App\Neuron\MyChatBot
```

{% endtab %}
{% endtabs %}

Aquí tienes un ejemplo de implementación de RAG:

```php
namespace App\Neuron;

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddingsProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new OpenAIEmbeddingsProvider(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL'
        );
    }
    
    protected function vectorStore(): VectorStoreInterface
    {
        return new FileVectorStore(
            directory: __DIR__,
            nombre: 'demo'
        );
    }
}
```

{% hint style="warning" %}
Explorar [**Cargadores de datos**](https://docs.neuron-ai.dev/neuron-v3-es/rag/data-loader.md) para aprender cómo poblar el almacén de vectores con embeddings que representen el conocimiento que quieres integrar como conocimiento adicional.
{% endhint %}

### Hablar con el agente RAG

Imagina que ya has poblado previamente el almacén de vectores con la base de conocimiento a la que quieres conectar el agente RAG, y ahora quieres hacer preguntas. Echa un vistazo a [**Cargadores de datos**](https://docs.neuron-ai.dev/neuron-v3-es/rag/data-loader.md) para aprender sobre la carga de datos en RAG.

Para iniciar la ejecución de un RAG, llamas a la `chat()` método:

```php
use App\Neuron\MyChatBot;
use NeuronAI\Chat\Messages\UserMessage;

$message = MyChatBot::make()
    ->setThreadId('chat_id')
    ->chat(
        new UserMessage('Quiero saber más sobre Inspector AI Bug Fix.')
    )
    ->getMessage();
    
echo $message->getContent();

// Claro, Inspector AI Bug Fix es una herramienta de monitorización agéntica 
// que proporciona propuestas de corrección de errores en tiempo real a medida que ocurre un error 
// en tu aplicación.
```

## Alimentar tu RAG con documentos

Una vez que hayas definido los componentes de tu sistema RAG, es hora de alimentar la base de datos vectorial con fragmentos de texto incrustados.

Neuron te proporciona [Cargadores de datos](https://docs.neuron-ai.dev/neuron-v3-es/rag/data-loader.md) para ayudarte a configurar una canalización de carga de datos con solo unas pocas líneas de código. Puedes ver un ejemplo abajo. Para aprender más sobre el cargador de datos, deberías consultar la [documentación dedicada](https://docs.neuron-ai.dev/neuron-v3-es/rag/data-loader.md):

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

MyChatBot::make()->addDocuments(
    // Usa el componente cargador de archivos para cargar un archivo de texto en el almacén de vectores
    FileDataLoader::for(__DIR__.'/my-article.md')->getDocuments()
);
```

## RAG + Herramientas

La clase RAG de Neuron extiende la básica `\NeuronAI\Agent` clase. Esto significa que tu RAG es siempre un agente y también puedes adjuntar herramientas y definir instrucciones del sistema en tu implementación.

Imagina que queremos implementar un agente capaz de dar consejos de entrenamiento basados en los datos del usuario. Aquí tienes un ejemplo de implementación completa:

```php
namespace App\Neuron;

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddingsProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;
use NeuronAI\Tools\Toolkits\Calculator\CalculatorToolkit;

class WorkoutTipsAgent extends RAG
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    public function instructions(): string
    {
        return (string) new SystemPrompt(
            background: ["Eres un agente de IA especializado en proporcionar consejos de entrenamiento."],
        );
    }
    
    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new OpenAIEmbeddingsProvider(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL'
        );
    }
    
    protected function vectorStore(): VectorStoreInterface
    {
        return new FileVectorStore(
            directory: __DIR__,
            nombre: 'demo'
        );
    }
    
    protected function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}
```

En el ejemplo anterior creamos un agente RAG que es capaz de dar consejos de entrenamiento al usuario. Podemos cargar en el almacén de vectores el conocimiento sobre los entrenamientos específicos que proporciones, de modo que el agente tenga el conocimiento para ofrecer consejos basados en el estado actual del entrenamiento del usuario recuperado de la base de datos con la herramienta que adjuntamos.

### Flujo de trabajo de RAG

En la siguiente imagen puedes ver la representación completa del flujo de trabajo que Neuron ejecuta para una aplicación RAG. Aprender esta estructura puede ayudarte a comprender mejor el proceso de ejecución subyacente para conectar el sistema mediante middleware:

<figure><img src="https://4076695836-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2FmCRL8w7ld1TMMBPv8uFN%2Frag-workflow.png?alt=media&amp;token=72de1793-a3aa-4e57-bece-425a70329fef" alt=""><figcaption></figcaption></figure>

Una vez que el `UserMessage` entra en el sistema, se ejecuta en este orden:

* `PreProcessQueryNode`: Ejecuta la [canalización de preprocesadores](https://docs.neuron-ai.dev/neuron-v3-es/rag/pre-post-processor.md#pre-processors) como `QueryTransformationPreProcessor` para reforzar el prompt de entrada.
* `RetrieveDocumentsNode`: Ejecuta la [estrategia de recuperación](https://docs.neuron-ai.dev/neuron-v3-es/rag/retrieval.md) desde el almacén de vectores o fuentes de datos externas
* `PostProcessDocumentsNode`: Ejecuta la [posprocesadores](https://docs.neuron-ai.dev/neuron-v3-es/rag/pre-post-processor.md#post-processors) canalización como el reranking
* `EnrichInstructionsNode`: Añade los documentos finales al prompt del sistema del agente
* `ChatNode`: Ejecuta la inferencia y recopila la respuesta del LLM
* `ToolNode`: Si el agente tiene herramientas adjuntas, el modelo puede solicitar su ejecución eventualmente.

Finalmente, el RAG te devolverá el mensaje del LLM.

## Documentos y esquemas en RAG

Una base de datos vectorial necesita conocer el tipo de un campo de metadatos antes de poder indexarlo o compararlo correctamente. Sin esta información, una base de datos podría almacenar `2026` como un número mientras otra lo almacena como texto.

Una `DocumentSchema` da a cada almacén de vectores la misma comprensión de tus documentos. Pertenece al almacén de vectores porque cada documento en un índice o colección debe seguir el mismo contrato.

La carga e ingesta de documentos se tratan por separado en Cargar documentos en un RAG.

### Definir el contrato del documento

Declara los campos que necesitan un tipo conocido, son obligatorios o se usarán en filtros.

```php
use NeuronAI\RAG\Schema\DocumentField;
use NeuronAI\RAG\Schema\DocumentSchema;

$schema = DocumentSchema::of(
    DocumentField::string('tenant')->required()->filterable(),
    DocumentField::string('status')->required()->filterable(),
    DocumentField::integer('published_at')->filterable(),
    DocumentField::float('price')->filterable(),
    DocumentField::boolean('published')->filterable(),
    DocumentField::strings('tags'),
);
```

Usa `required()` cuando cada documento debe contener un valor no nulo. Usa `filterable()` cuando el campo vaya a aparecer en un filtro portable.

| Valor de metadato   | Declaración                       |
| ------------------- | --------------------------------- |
| Cadena              | `DocumentField::string('name')`   |
| Entero              | `DocumentField::integer('name')`  |
| Flotante            | `DocumentField::float('name')`    |
| Boolean             | `DocumentField::boolean('name')`  |
| Matriz de cadenas   | `DocumentField::strings('name')`  |
| Matriz de enteros   | `DocumentField::integers('name')` |
| Matriz de flotantes | `DocumentField::floats('name')`   |
| Matriz de booleanos | `DocumentField::booleans('name')` |

Los enteros también son valores válidos para campos flotantes. Las matrices deben contener valores de un solo tipo.

### Adjuntar el esquema al almacén de vectores de RAG

Define el esquema donde RAG define su almacén de vectores. Esto mantiene el contrato de datos junto a la configuración de la base de datos de la que depende.

```php
use NeuronAI\RAG\Schema\DocumentField;
use NeuronAI\RAG\Schema\DocumentSchema;
use NeuronAI\RAG\VectorStore\PineconeVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

protected function vectorStore(): VectorStoreInterface
{
    return new PineconeVectorStore(
        key: $_ENV['PINECONE_API_KEY'],
        indexUrl: $_ENV['PINECONE_INDEX_URL'],
        schema: DocumentSchema::of(
            DocumentField::string('tenant')->required()->filterable(),
            DocumentField::string('status')->required()->filterable(),
            DocumentField::integer('published_at')->filterable(),
            DocumentField::float('price')->filterable(),
            DocumentField::strings('tags'),
        ),
    );
}
```

Cada almacén de vectores integrado acepta el argumento opcional `schema` . El mismo esquema puede usarse al cambiar de backend:

```php
use NeuronAI\RAG\VectorStore\MemoryVectorStore;

$store = new MemoryVectorStore(schema: $schema);
```

Crea el esquema antes de crear un nuevo índice o colección de base de datos. Si un índice existente tiene asignaciones de campos incompatibles, recréalo y vuelve a indexar sus documentos.

### Declara solo lo que la base de datos necesita

Un esquema no elimina la naturaleza flexible de un documento. Los metadatos JSON seguros no declarados todavía se almacenan y se devuelven.

Declara un campo cuando necesites al menos una de estas garantías:

* cada documento debe contenerlo;
* su valor debe tener un tipo conocido;
* debe funcionar en filtros portables.

Un campo no declarado no puede usarse en un filtro portable porque se desconoce su tipo de base de datos.

`sourceType` y `sourceName` son campos de cadena integrados. Siempre son filtrables y no deben declararse en el esquema.

### Definir filtros

La búsqueda semántica encuentra contenido similar. Los filtros deciden qué documentos tienen permitido participar. Un filtro de recuperación estático es útil cuando cada solicitud debe permanecer dentro de un único tenant, espacio de trabajo o base de conocimiento.

El campo filtrado debe declararse como filtrable en el esquema del almacén de vectores.

```php
use NeuronAI\RAG\Retrieval\RetrievalInterface;
use NeuronAI\RAG\Retrieval\SimilarityRetrieval;
use NeuronAI\RAG\VectorStore\Filter\Filter;
use NeuronAI\RAG\VectorStore\Filter\FilterGroup;

protected function retrieval(): RetrievalInterface
{
    return new SimilarityRetrieval(
        $this->resolveVectorStore(),
        $this->resolveEmbeddingsProvider(),
        filters: FilterGroup::and(
            Filter::eq('tenant', 'acme'),
            Filter::eq('status', 'published'),
        ),
    );
}
```

Los filtros añadidos por middleware o por otro paso del flujo de trabajo se combinan con este alcance usando AND. Pueden acotar el resultado, pero no pueden eliminar el alcance permanente.

### Comparaciones

Los filtros portables tienen el mismo significado en todas las bases de datos vectoriales compatibles.

```php
Filter::eq('status', 'published');
Filter::neq('status', 'draft');
Filter::in('status', ['published', 'reviewed']);
Filter::gt('price', 10);
Filter::gte('price', 10);
Filter::lt('price', 100);
Filter::lte('price', 100);
```

Las siguientes reglas evitan que distintas bases de datos devuelvan resultados diferentes:

* las comparaciones de rango solo funcionan con campos enteros y flotantes;
* las fechas deben almacenarse como marcas de tiempo Unix cuando necesiten filtros de rango;
* `neq()` requiere un campo declarado con `required()`;
* los campos de matriz se validan y almacenan, pero no admiten filtros portables;
* todas las condiciones en `FilterGroup::and()` deben coincidir;
* `in()` significa que un campo puede coincidir con cualquier valor de una lista.

Los campos, valores y operadores inválidos fallan antes de que una solicitud llegue a la base de datos.

### Buscar o eliminar con filtros

Usa el mismo modelo de filtro cuando trabajes con el almacén de vectores fuera del flujo de recuperación de RAG.

```php
use NeuronAI\RAG\VectorStore\Filter\Filter;
use NeuronAI\RAG\VectorStore\Filter\FilterGroup;
use NeuronAI\RAG\VectorStore\SearchRequest;

$documents = $store->search(new SearchRequest(
    embedding: $queryEmbedding,
    filters: FilterGroup::and(
        Filter::eq('tenant', 'acme'),
        Filter::gte('published_at', 1767225600),
    ),
    topK: 8,
));

$store->delete(FilterGroup::and(
    Filter::eq('tenant', 'acme'),
    Filter::eq('sourceType', 'files'),
));
```

### Usa un filtro específico del backend

La API portable contiene solo operaciones con comportamiento coherente entre bases de datos. Usa `Filter::raw()` para una función disponible solo en un backend.

```php
use NeuronAI\RAG\VectorStore\MeilisearchVectorStore;

$filters = FilterGroup::and(
    Filter::eq('tenant', 'acme'),
    Filter::raw(
        MeilisearchVectorStore::class,
        ' _geoRadius(45.4, 9.1, 2000)',
    ),
);
```

El filtro en bruto está etiquetado con la clase de su almacén de vectores. Otro almacén lo rechaza en lugar de cambiar silenciosamente su significado.
