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

# Almacén de vectores

Neuron te proporciona componentes listos para usar para conectar tu agente a bases de datos vectoriales.

Actualmente ofrecemos soporte oficial para el siguiente almacén vectorial:

### Memoria

Esta es una implementación de un almacén vectorial volátil que mantiene tus embeddings en la memoria de la máquina durante la sesión actual. Es útil cuando no necesitas almacenar los embeddings generados para uso a largo plazo, sino solo durante las sesiones de interacción actuales (o para uso local).

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\MemoryVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new MemoryVectorStore();
    }
}
```

### Archivo

El almacenamiento en archivos podría ser útil para casos de uso de bajo volumen o para entornos locales y de staging. Los documentos incrustados se almacenarán en el sistema de archivos y se procesarán durante la búsqueda por similitud.

`FileVectorStore` usa generadores de PHP para leer los documentos incrustados desde el sistema de archivos. Nunca mantendrá más de `topK` elementos en memoria mientras itera muy rápido. Puedes almacenar miles de documentos en tu sistema de archivos local solo teniendo en cuenta el tiempo máximo que puedes aceptar para realizar la búsqueda por similitud.

También puedes usar este componente para liberar agentes con cierto conocimiento ya incorporado en un archivo.

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new FileVectorStore(
            directory: storage_path(),
            topK: 4
        );
    }
}
```

### PHPVector

Adaptador PHPVector sobre [`ezimuel/phpvector`](https://github.com/ezimuel/PHPVector). Es una base de datos vectorial escrita íntegramente en PHP que implementa **HNSW** (Hierarchical Navigable Small World) para búsqueda aproximada de vecinos más cercanos y **BM25** para recuperación de texto completo. Ambos motores pueden combinarse en una única **búsqueda híbrida** canalización.

Puedes instalar el componente con composer:

```shellscript
composer require ezimuel/phpvector
```

Úsalo en un contexto RAG:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\PHPVector\PHPVector;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyRAG extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new PHPVector(
            path: '/var/data/mydb',
            topK: 5,
        );
    }
}
```

### MariaDB

MariaDB admite el tipo de columna VECTOR a partir de la versión 11.7. Para que este componente funcione, necesitas crear la tabla para almacenar documentos y los vectores relacionados. Aquí tienes el script SQL que puedes usar para hacerlo:

```sql
CREATE TABLE IF NOT EXISTS rag_documents (
    id UUID NOT NULL PRIMARY KEY,
    content TEXT,
    sourceType VARCHAR(255),
    sourceName VARCHAR(255),
    metadata JSON,
    embedding VECTOR(1536) NOT NULL,
    VECTOR INDEX (embedding)
)
```

Así es como usar el componente en tu RAG:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\MariaDBVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new MariaDBVectorStore(
            new \PDO(...), // O bien obtiene la instancia de PDO desde el ORM
        );
    }
}
```

### Pinecone

Pinecone facilita proporcionar memoria a largo plazo para aplicaciones de IA de alto rendimiento. Es una base de datos vectorial administrada y nativa de la nube, con una API sencilla y sin complicaciones de infraestructura. Pinecone ofrece resultados de consulta frescos y filtrados con baja latencia a escala de miles de millones de vectores.

Así es como usar Pinecone en tu agente:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\PineconeVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new PineconeVectorStore(
            key: 'PINECONE_API_KEY',
            indexUrl: 'PINECONE_INDEX_URL'
        );
    }
}
```

### Weaviate

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\WeaviateVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new WeaviateVectorStore(
            collection: 'WEAVIATE_COLLECTION_NAME',
            host: 'http://localhost:8080', // URL local o en la nube
            key: 'WEAVIATE_KEY' // opcional para implementación local
        );
    }
}
```

### Elasticsearch

La base de datos vectorial de código abierto de Elasticsearch ofrece una forma eficiente de crear, almacenar y buscar embeddings vectoriales. Para usar Elasticseach como almacén vectorial en la implementación de tus agentes, debes importar el cliente oficial:

```bash
composer require elasticsearch/elasticsearch
```

Aquí tienes cómo crear un RAG que use Elasticsearch:

```php
namespace App\Neuron;

use Elastic\Elasticsearch\ClientBuilder;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\ElasticsearchVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        $elasticsearch = ClientBuilder::create()
           ->setHosts(['<elasticsearch-endpoint>'])
           ->setApiKey('<api-key>')
           ->build();
       
        return new ElasticsearchVectorStore(
            client: $elasticsearch,
            index: 'neuron-ai'
        );
    }
}
```

### OpenSearch

Opensearch es la alternativa de código abierto puro a Elasticsearch. Para usar Opensearch en tus agentes necesitas instalar su cliente oficial:

```bash
composer require opensearch-project/opensearch-php
```

Una vez que hayas instalado el cliente oficial en tu aplicación, puedes devolver una instancia de `OpenSearchVectorStore` en tu agente RAG:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\OpenSearchVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;
use OpenSearch\GuzzleClientFactory;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        $opensearch = new GuzzleClientFactory()->create([
            'base_uri' => 'http://localhost:9200',
        ]);
        
        return new OpenSearchVectorStore(
            client: $opensearch,
            index: 'neuron-ai',
        );
    }
}
```

### Typesense

[Typesense](https://typesense.org/) es una alternativa de código abierto a las opciones anteriores. Para usar Typesense en tus agentes necesitas instalar su cliente oficial:

```bash
composer require typesense/typesense-php
```

Una vez que hayas instalado el cliente oficial en tu aplicación, puedes devolver una instancia de TypesenseVectorStore en tu agente RAG:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\TypesenseVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        $typesense = new \Typesense\Client([
            'api_key' => 'TYPESENSE_API_KEY',
            'nodes' => [
                [
                    'host' => 'TYPESENSE_NODE_HOST',
                    'port' => 'TYPESENSE_NODE_PORT',
                    'protocol' => 'TYPESENSE_NODE_PROTOCOL'
                ],
            ]
        ]);
        
        return new TypesenseVectorStore(
            client: $typesense,
            collection: 'neuron-ai',
            vectorDimension: 1024
        );
    }
}
```

### Qdrant

[Qdrant](https://qdrant.tech/) es una base de datos vectorial de código abierto con sólidas capacidades de búsqueda por similitud. Para usar Qdrant en tus agentes tienes que proporcionar un `collectionUrl`. Esto significa que primero tendrás que crear una colección en Qdrant con sus atributos, como: nombre, algoritmo de búsqueda por similitud, dimensión del vector, etc.

Una vez que tengas la URL de la colección, puedes adjuntar la `QdrantVectorStore` instancia a tu agente.

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\QdrantVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new QdrantVectorStore(
            collectionUrl: 'http://localhost:6333/collections/neuron-ai/',
            key: 'QDRANT_API_KEY'
        );
    }
}
```

### ChromaDB

[Chroma](https://trychroma.com/) es una base de datos de código abierto diseñada para ser una fuente de datos para aplicaciones de IA. Para usar ChromaDB en tus agentes tienes que proporcionar el nombre de una colección interna donde quieras almacenar los embeddings.

Una vez que hayas creado la colección en tu instancia de Chroma, puedes adjuntar la `ChromaVectorStore` instancia al agente:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\ChromaVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new ChromaVectorStore(
            collection: 'neuron-ai',
            //host: 'http://localhost:8000', <-- Esto es por defecto
            topK: 5
        );
    }
}
```

### Meilisearch

[Meilisearch](https://www.meilisearch.com/) es un motor de búsqueda híbrido, pero la implementación de Neuron lo usa exclusivamente como almacén vectorial para embeddings y búsqueda por similitud.

El `indexUid` el parámetro debe ser el identificador de un índice de Meilisearch que hayas creado y configurado. Asegúrate de que este índice defina un campo vectorial cuya dimensión coincida con el tamaño del embedding producido por el embedder que estés usando. El `embedder` valor (por ejemplo, `default`) debe corresponder a un embedder con nombre configurado en tu entorno Neuron para que los vectores almacenados y la configuración del índice permanezcan alineados. Añade el componente a tu RAG:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\MeilisearchVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        return new MeilisearchVectorStore(
            indexUid: 'MEILISEARCH_INDEXUID',
            host: 'http://localhost:8000', // O usa la URL en la nube
            key: 'MEILISEARCH_API_KEY',
            embedder: 'default',
            topK: 5
        );
    }
}
```

### MongoDB

Para usar este componente necesitas instalar el cliente oficial de MongoDB:

```shellscript
composer require mongodb/mongodb
```

Usa el componente en tu RAG o script:

```php
namespace App\Neuron;

use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\MongoDBVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    ...

    protected function vectorStore(): VectorStoreInterface
    {
        $uri = 'mongodb://localhost:27017';
        $uriOptions = ['serverSelectionTimeoutMS' => 10000];
        $client = new MongoDB\Client($uri, $uriOptions);
        
        return new MongoDBVectorStore(
            client: $client,
            database: 'MONGODB_DATABASE',
            collectionName: 'MONGO_DB_COLLECTION',
            topK: 4
        );
    }
}
```

### Extender almacenes vectoriales

Si quieres dar soporte a un nuevo almacén vectorial, tienes que implementar `VectorStoreInterface`:

```php
interface VectorStoreInterface
{
    public function addDocument(Document $document): VectorStoreInterface;

    /**
     * @param  Document[]  $documents
     */
    public function addDocuments(array $documents): VectorStoreInterface;

    /**
     * Elimina todos los documentos que coincidan con los filtros.
     */
    public function delete(FilterGroup $filters): VectorStoreInterface;

    /**
     * Devuelve los documentos más similares al embedding de la solicitud.
     *
     * @return Document[]
     */
    public function search(SearchRequest $request): iterable;
}
```

Existen dos métodos diferentes para añadir un solo documento o una colección de documentos porque muchas bases de datos proporcionan APIs distintas para estos casos de uso. Si la base de datos con la que quieres interactuar no maneja estas solicitudes de forma diferente, puedes implementar `addDocuments()` como un marcador de posición o `addDocument()`.

El `search()` el método debe devolver la lista de documentos con una puntuación de similitud, no una distancia de similitud. Si la base de datos subyacente devuelve una distancia, puedes convertirla en una puntuación usando la clase de utilidad `VectorSimilarity`:

```php
namespace App\Neuron\VectorStore;

use NeuronAI\RAG\Document;
use NeuronAI\RAG\VectorSimilarity;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyVectorStore implements VectorStoreInterface
{
    ...


    /**
     * @param float[] $embeddings
     */
    public function search(SearchRequest $request): iterable
    {
        $documents = // obtener documentos del almacén vectorial

        return \array_map(function (Document $document) {
            return $document->setScore(
                VectorSimilarity::similarityFromDistance($similarity)
            );
        }, $documents);
    }
}
```

Después de crear tu propia implementación, puedes usarla en el agente como cualquier otro almacén:

```php
namespace App\Neuron;

use App\Neuron\VectorStore\MyVectorStore;
use NeuronAI\Agent;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyAgent extends Agent
{
    protected function vectorStore(): VectorStoreInterface
    {
        return new MyVectorStore(
            key: 'VECTORSTORE_API_KEY',
            index: 'neuron-ai',
        );
    }
}
```

## Filtros

### DocumentSchema

`Documento` es el objeto de procesamiento unificado entre carga, división, embedding, almacenamiento, recuperación, middleware y reranking. Sus campos se acceden mediante métodos. Embedding y score son valores en tiempo de ejecución anulables; las comprobaciones estrictas indican si una etapa los produjo ( `null` sigue siendo una puntuación válida).`0.0` sigue siendo una puntuación válida).

Los metadatos personalizados permanecen sin esquema para el almacenamiento y la ida y vuelta. El filtrado portable requiere un esquema a nivel de colección pasado al almacén vectorial:

```php
$schema = DocumentSchema::of(
    DocumentField::string('tenant')->required()->filterable(),
    DocumentField::integer('year')->filterable(),
    DocumentField::strings('tags')->filterable(),
);

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

Los almacenes validan localmente los valores declarados y los filtros. Solo `sourceType`, `sourceName`, y los campos de metadatos declarados como filtrables son objetivos de filtro portables. Los campos de matriz se admiten para validación/almacenamiento, pero necesitan filtros nativos del backend, excepto las matrices portables de cadenas filtrables, que admiten `containsAny` y `containsAll`. Las matrices declaradas deben ser listas homogéneas no vacías. Un `DocumentField` puede pasarse directamente a las fábricas de filtros para una construcción consciente del esquema. `neq` requiere un campo obligatorio, de modo que el comportamiento ante campos faltantes no pueda divergir entre bases de datos. RAG valida los documentos antes de hacer el embedding.

### Expresión de filtro

Una vez que hayas definido campos filtrables con `DocumentSchema`, puedes pasar una expresión de filtrado a la estrategia de recuperación en tiempo de ejecución.

Los filtros son un árbol de expresiones portátil e independiente del backend, compilado a la sintaxis nativa de cada almacén. Esto es **búsqueda por similitud filtrada**: los filtros de metadatos restringen los resultados de similitud vectorial. Reserva **búsqueda híbrida** para estrategias que combinan clasificación vectorial y léxica.

```php
class MyRAG extends RAG
{
    ...,
    
    protected function retrieval(): RetrievalInterface
    {
        return new SimilarityRetrieval(
            vectorStore: $this->resolveVectorStore(),
            embeddingProvider: $this->resolveEmbeddingsProvider(),
            filters: Filter::gt('year', 2020)
                ->lt('year', date('Y'))
                ->eq('tenant', Tenant::id())
        );
    }
}
```

### Filtros disponibles

**`Filter::eq/neq/in/gt/gte/lt/lte(field, value)`** — fábricas de comparación de bajo nivel.

**`Filter::where(field, value)`** inicia un `Criteria` fluido inmutable `con métodos` where\*`null` para el camino común. Los valores solo pueden ser escalares ( `lanza: no hay semántica portable de ausente frente a nulo); los valores de rango se normalizan a` int|float `(los rangos de cadenas no son portables). Los enums respaldados se normalizan a su valor y` DateTimeInterface

**`los valores se normalizan a marcas de tiempo Unix.` / `anyOf(...)`** — expresiones booleanas anidadas; `and(...)` / `or(...)` siguen siendo alias breves. Los grupos con el mismo operador se aplanan, mientras que los operadores mixtos conservan sus límites.

**`Filter::containsAny/containsAll(field, values)`** — filtrado portable para `string[]` campos. Otros tipos de matriz siguen siendo nativos del backend.

**`Filter::raw(StoreClass::class, $fragment)`** — vía de escape nativa del backend, etiquetada con su almacén de destino. El almacén etiquetado pasa el fragmento literalmente; el compilador de cualquier otro almacén lanza una excepción (fallo ruidoso al cambiar de almacén, nunca un filtrado incorrecto silencioso). Los fragmentos raw deben ser sintaxis confiable y escrita por el desarrollador; nunca interpoles valores de solicitud en ellos.

**`FilterScope::merge(...)`** — combina ámbitos obligatorios suministrados de forma independiente con un AND raíz. La expresividad de consulta y la seguridad del ámbito son cosas separadas.

**`los valores se normalizan a marcas de tiempo Unix.` / `anyOf(...)`** — expresiones booleanas anidadas; `and(...)` / `or(...)` siguen siendo alias breves. Los grupos con el mismo operador se aplanan, mientras que los operadores mixtos conservan sus límites.
