Ai Vektor Store Laravel Package

Getting Started

Minimal Steps for Laravel Developers

1. Install Dependencies

   composer require symfony/ai centamiv/vektor
   

   Ensure your Laravel app uses Symfony 6.4+ (or Laravel 10+ with Symfony components).

2. Configure Vektor Backend Choose either Redis or PostgreSQL for Vektor. Example for Redis:

   docker run -p 6379:6379 redis/redis-stack-server:latest
   

   Or for PostgreSQL with pgvector:

   docker run --name pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d centos/pgvector
   

3. Set Up Symfony AI in Laravel Register the Vektor store in config/ai.php:

   'stores' => [
       'vektor' => [
           'type' => 'vektor',
           'options' => [
               'connection' => 'redis', // or 'postgresql'
               'index_name' => 'laravel_ai',
               'dimensions' => 384, // Adjust based on your embedding model
           ],
       ],
   ],
   

4. First Query: Embed and Retrieve Use the store in a Laravel service:

   use Symfony\Component\AI\Store\VectorStoreInterface;
   
   class AiSearchService {
       public function __construct(
           private VectorStoreInterface $vectorStore
       ) {}
   
       public function findSimilarDocuments(string $query, int $limit = 3) {
           $embedding = $this->vectorStore->embed($query);
           $results = $this->vectorStore->findNearest($embedding, $limit);
           return $results;
       }
   }
   

   Bind the store in AppServiceProvider:

   public function register() {
       $this->app->bind(VectorStoreInterface::class, function ($app) {
           return new \Symfony\Component\AI\Store\VektorStore(
               $app['config']['ai.stores.vektor.options']
           );
       });
   }
   

5. Test with a Simple Example Add a test document and query it:

   $this->vectorStore->add(
       'doc1',
       [0.1, 0.2, ..., 0.384] // Replace with a real embedding
   );
   
   $results = $this->findSimilarDocuments("What is Laravel?");
   

Implementation Patterns

Core Workflows

1. Embedding and Storage

   • Generate embeddings using Symfony AI’s EmbeddingGenerator (e.g., all-MiniLM-L6-v2):

     $embedding = $embeddingGenerator->generate($text);
     $this->vectorStore->add('doc_id', $embedding);
     

   • Batch operations for efficiency:

     $this->vectorStore->addMany([
         'doc1' => $embedding1,
         'doc2' => $embedding2,
     ]);
     

2. Semantic Search

   • Query vectors with cosine similarity:

     $queryEmbedding = $embeddingGenerator->generate($query);
     $results = $this->vectorStore->findNearest($queryEmbedding, 5);
     

   • Filter results by metadata (if using Vektor’s advanced features):

     $results = $this->vectorStore->findNearest(
         $queryEmbedding,
         5,
         ['tags' => ['laravel', 'ai']]
     );
     

3. Hybrid Search (Keyword + Vector) Combine with Laravel Scout or Algolia:

   // Pseudocode: Merge keyword and vector results
   $keywordResults = Scout::search($query);
   $vectorResults = $this->findSimilarDocuments($query);
   $merged = $this->mergeResults($keywordResults, $vectorResults);
   

4. Background Processing Use Laravel Queues for heavy operations (e.g., batch embeddings):

   Queue::push(new ProcessEmbeddings($documents));
   

   Job example:

   class ProcessEmbeddings implements ShouldQueue {
       public function handle() {
           $embeddings = $this->generateEmbeddings($this->documents);
           $this->vectorStore->addMany($embeddings);
       }
   }
   

Integration Tips

• Laravel Caching: Use Redis for Vektor’s backend to avoid separate connections:

  'options' => [
      'connection' => env('REDIS_VECTOR_CONNECTION', 'default'),
  ],
  

• Model Observers: Auto-generate embeddings when models are saved:

  class DocumentObserver {
      public function saved(Document $document) {
          $embedding = $embeddingGenerator->generate($document->content);
          $this->vectorStore->add($document->id, $embedding);
      }
  }
  

• API Endpoints: Expose search via Laravel routes:

  Route::get('/search', function (AiSearchService $service) {
      return $service->findSimilarDocuments(request('q'));
  });
  

Gotchas and Tips

Pitfalls

1. Embedding Dimensions Mismatch

   • Vektor requires consistent vector dimensions. If your embedding model outputs 384 dimensions but you configure dimensions: 768, queries will fail.
   • Fix: Validate dimensions before adding vectors:

     if (count($embedding) !== $this->vectorStore->getDimensions()) {
         throw new \InvalidArgumentException('Embedding dimension mismatch');
     }
     

2. Redis Memory Limits

   • Storing millions of vectors in Redis can exhaust memory. Monitor with:

     redis-cli info memory
     

   • Fix: Use PostgreSQL for large datasets or configure Redis eviction policies.

3. PostgreSQL pgvector Setup

   • Ensure pgvector is installed and the index is created:

     CREATE EXTENSION vector;
     CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);
     

   • Fix: Check Vektor’s logs for connection errors.

4. Symfony AI Version Conflicts

   • This package may lag behind Symfony AI updates. Test with:

     composer require symfony/ai:^0.8.0 --dev
     

   • Fix: Pin versions in composer.json:

     "symfony/ai": "^0.8.0",
     "symfony/ai-vektor-store": "^0.7.0"
     

5. No Native Laravel Support

   • The package is Symfony-first. Workarounds:
     • Use Laravel’s Symfony bridge (symfony/flex).
     • Wrap the store in a Laravel service (as shown in Getting Started).

Debugging Tips

• Enable Vektor Logging Configure in config/ai.php:

  'options' => [
      'debug' => true,
  ],
  

  Check logs for connection/query issues.

• Validate Embeddings Sanity-check embeddings before storage:

  $embedding = $embeddingGenerator->generate($text);
  if (is_null($embedding) || !is_array($embedding)) {
      throw new \RuntimeException('Invalid embedding generated');
  }
  

• Query Performance Profile slow queries with:

  $start = microtime(true);
  $results = $this->vectorStore->findNearest($embedding, 10);
  $time = microtime(true) - $start;
  logger()->info("Query took {$time}s");
  

  Optimize: Adjust Vektor’s ef (search efficiency) and M (max neighbors) parameters.

Extension Points

1. Custom Vektor Client Extend the bridge to support custom Vektor configurations:

   class CustomVektorStore extends \Symfony\Component\AI\Store\VektorStore {
       public function __construct(array $options) {
           $options['custom_param'] = 'value';
           parent::__construct($options);
       }
   }
   

2. Metadata Filtering Add metadata support if Vektor’s backend allows it:

   $this->vectorStore->findNearest($embedding, 5, ['author' => 'Taylor Otwell']);
   

3. Hybrid Search Logic Combine keyword and vector results in a custom service:

   class HybridSearchService {
       public function search(string $query) {
           $vectorResults = $this->vectorStore->findNearest(...);
           $keywordResults = Scout::search($query);
           return $this->merge($vectorResults, $keywordResults);
       }
   }
   

4. Fallback Store Implement a fallback for when Vektor is unavailable:

   class ResilientVectorStore {
       public function __construct(
           private VectorStoreInterface $primary,
           private VectorStoreInterface $fallback
       ) {}
   
       public function findNearest