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

# Recuperación

Implementa estrategias de recuperación personalizadas

### Introducción

El módulo RAG tiene un componente de recuperación separado que te permite implementar diferentes estrategias para lograr la recuperación de contexto desde fuentes de datos externas. De forma predeterminada, RAG usa `SimilarityRetrieval` que simplemente consulta el almacén vectorial para recuperar documentos:

```php
namespace App\Neuron;

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\RAG\Retrieval\RetrievalInterface;
use NeuronAI\RAG\RAG\Retrieval\SimilarityRetrieval;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class WorkoutTipsAgent extends RAG
{
    protected function retrieval(): RetrievalInterface
    {
        return new SimilarityRetrieval(
            $this->resolveVectorStore(),
            $this->resolveEmbeddingsProvider()
        );
    }
    
    protected function provider(): AIProviderInterface
    {
        // Devuelve una instancia de un proveedor de IA...
    }
    
    protected function embeddings(): EmbeddingsProviderInterface
    {
        // Devuelve una instancia de un proveedor de embeddings...
    }
    
    protected function vectorStore(): VectorStoreInterface
    {
        // Devuelve una instancia de un almacén vectorial...
    }
}
```

Implementando `RetrievalInterface` eres libre de crear cualquier comportamiento de recuperación personalizado para tu RAG.

```php
interface RetrievalInterface
{
    /**
     * Recupera los documentos relevantes para la consulta dada.
     *
     * @return Document[]
     */
    public function retrieve(Message $query): array;
}
```

Si estás implementando un flujo de trabajo personalizado, puedes usar la recuperación como un componente independiente para recuperar dinámicamente datos de contexto para su uso en tus sistemas agénticos.

### Filtros

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

class WorkoutTipsAgent extends RAG
{
    protected function retrieval(): RetrievalInterface
    {
        return new SimilarityRetrieval(
            $this->resolveVectorStore(),
            $this->resolveEmbeddingsProvider(),
            filters: FilterGroup::and(Filter::eq('tenant', $tenantId)),  // opcional
        );
    }
}
```

<a href="https://docs.neuron-ai.dev/neuron-v3-es/rag/rag.md#filters" class="button primary" data-icon="arrow-right-long">Más sobre filtros</a>

### Recuperación como herramienta

Neuron te proporciona una `RetrievalTool` herramienta integrada que permite a los agentes de IA realizar recuperación de contexto desde almacenes vectoriales si el modelo cree que necesita más contexto para responder a la pregunta actual del usuario. Está basada en `RetrievalInterface` lo que hace posible construir agentes con capacidades de RAG (Generación Aumentada por Recuperación) bajo demanda en lugar de la inyección automática de contexto proporcionada por el componente RAG.

Aquí tienes un ejemplo usando la `SimilarityRetrieval`:

```php
use NeuronAI\Tools\Toolkits\RetrievalTool;
use NeuronAI\RAG\Retrieval\SimilarityRetrieval;

class AgenticRAG extends Agent
{
    protected function provider(): AIProviderInterface
    {...}
    
    protected function instructions(): string
    {...}
    
    protected function tools(): array
    {
        return [
            RetrievalTool::make(
                new SimilarityRetrieval(
                    $this->vectorStore(), 
                    $this->embeddings()
                )
            ),
        ];
    }
    
    protected function vectorStore(): VectorStoreInterface
    {
        return new FileVectorStore(__DIR__);
    }
    
    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new OllamaEmbeddingsProvider(
            model: 'OLLAMA_EMBEDDINGS_MODEL'
        );
    }
}
```

Como puedes notar en este ejemplo no extendemos RAG sino el Agent básico. En esta implementación dejamos que el modelo decida si es el caso de buscar una fuente externa para responder a la pregunta del usuario.

Siempre puedes usar todos los métodos de herramienta y agente para personalizar la descripción, las instrucciones y los prompts en general para hacer que el modelo se comporte según tu caso de uso.

### Memoria semántica

Usando RAG puedes activar la recuperación de memoria entre hilos. Los usuarios con múltiples hilos activos pueden ver cómo el agente recuerda sus conversaciones y preferencias pasadas.

```php
use NeuronAI\RAG\Retrieval\SemanticMemoryRetrieval;

class MyAgent extends RAG
{
    // Define los hooks habituales provider(), vectorStore() y embeddings().
    
    protected function retrieval(): RetrievalInterface
    {
        return new SemanticMemoryRetrieval(
            vectorStore: $this->resolveVectorStore(),
            embeddingProvider: $this->resolveEmbeddingProvider(),
            threadIds: $threadIds,
        );
    }
}
```

El argumento `threadIds` es la lista de hilos de los que quieres recuperar memoria. Puede ser la lista completa de hilos activos del usuario o un subconjunto de ellos según las preferencias de tu aplicación.

{% hint style="warning" %}
Recuerda excluir el **`threadId`** actual de la lista de recuperación, de lo contrario los mensajes de la misma conversación se duplicarán en las instrucciones del sistema del agente.
{% endhint %}

Para activar la creación de memoria para la conversación actual necesitas adjuntar el `ConversationIngestionNode` como nodo de salida, para que RAG pueda almacenar automáticamente los mensajes en el almacén vectorial asignado.

```php
use NeuronAI\RAG\Nodes\ConversationIngestionNode;

class MyAgent extends RAG
{
    // Define los hooks habituales provider(), vectorStore() y embeddings().
    
    protected function retrieval(): RetrievalInterface
    {
        return new SemanticMemoryRetrieval(
            vectorStore: $this->resolveVectorStore(),
            embeddingProvider: $this->resolveEmbeddingProvider(),
            threadIds: $threadIds,
        );
    }
    
    protected function exitNodes(): array
    {
        return [
            // Almacena el último par usuario/asistente en el almacén de memoria
            new ConversationIngestionNode(
                vectorStore: $this->resolveVectorStore(),
                embeddingProvider: $this->resolveEmbeddingsProvider(),
                chatHistory: $this->getChatHistory(),
            )
        ];
    }
}
```

### Recuperación compuesta

`CompositeRetrieval` te permite concatenar múltiples tareas de recuperación en una canalización. Llama a sus hijos en orden y combina sus resultados. Cada hijo recibe la misma consulta preprocesada y los filtros obligatorios por ejecución.

Coloca los filtros específicos de la colección en ese hijo en lugar de en el ámbito compartido de recuperación. Los filtros compartidos deben ser compatibles con cada hijo y nunca se eliminan. Luego, RAG deduplica por contenido y ejecuta los posprocesadores comunes.

```php
use NeuronAI\RAG\Retrieval\CompositeRetrieval;

class MyAgent extends RAG
{
    // Define los hooks habituales provider(), vectorStore() y embeddings().
    
    protected function retrieval(): RetrievalInterface
    {
        return new CompositeRetrieval([
            new SemanticMemoryRetrieval(
                vectorStore: $this->resolveVectorStore(),
                embeddingProvider: $this->resolveEmbeddingsProvider(),
                threadIds: $authorizedThreadIds,
            ),
            new SimilarityRetrieval(
                vectorStore: $this->resolveVectorStore(),
                embeddingProvider: $this->resolveEmbeddingsProvider(),
            ),
        ]);
    }
}
```

El código anterior usa el mismo almacén vectorial para ambas estrategias de recuperación, pero probablemente tendrías dos almacenes separados. Eres libre de combinar componentes para reflejar las necesidades y la arquitectura de tu aplicación.

### Recuperación RAPTOR

La mayoría de los modelos aumentados con recuperación funcionan dividiendo los documentos en fragmentos pequeños y recuperando solo los más relevantes. Sin embargo, este enfoque tiene algunas limitaciones:

* **Pérdida de contexto**: Recuperar solo fragmentos pequeños e aislados puede perder la visión general, especialmente en documentos con contextos largos.
* **Dificultad en el razonamiento de varios pasos**: Algunas preguntas requieren información de varias secciones de un documento.

**Usa RAPTOR cuando:**

* Los usuarios hacen preguntas abiertas que requieren una cobertura completa
* Tu dominio involucra temas complejos donde el contexto importa tanto como los hechos
* Necesitas manejar consultas sobre temas, tendencias o relaciones entre documentos

**Quédate con RAG tradicional cuando:**

* Los usuarios necesitan principalmente una recuperación rápida y específica de hechos
* La velocidad de procesamiento y la eficiencia de tokens son restricciones críticas

Obtén más información sobre RAPTOR en el repositorio dedicado:

{% embed url="<https://github.com/neuron-core/raptor-retrieval>" %}
