Ai Redis Store Laravel Package

Getting Started

Minimal Setup

1. Install the Package:

   composer require symfony/ai-redis-store
   

   (For Laravel, ensure Symfony’s RedisClientInterface is compatible; see Implementation Patterns.)

2. Configure Redis: Ensure your Redis server (7.0+) has the AI modules enabled. Verify with:

   redis-cli MODULE LIST
   

   (Should list RedisJSON, RedisSearch, and RedisTimeSeries modules.)

3. Define a Vector Index: Create a Redis index via CLI or code. Example CLI command:

   redis-cli FT.CREATE ai_vectors ON HASH PREFIX 1 "vector:" SCHEMA vector FIELD HASH $ DIM 1536
   

   (Replace DIM with your embedding dimension, e.g., 1536 for text-embedding-ada-002.)

4. Integrate with Symfony AI: Configure the store in config/packages/ai.yaml:

   framework:
       ai:
           store:
               redis:
                   url: '%env(REDIS_DSN)%'
                   index_name: 'ai_vectors'
   

5. First Use Case: Insert and query vectors in a controller:

   use Symfony\AI\Store\StoreInterface;
   
   class VectorController {
       public function __construct(private StoreInterface $store) {}
   
       public function addVector(string $id, array $embedding): void {
           $this->store->insert($id, $embedding);
       }
   
       public function findSimilar(string $queryEmbedding, int $limit = 5) {
           return $this->store->search($queryEmbedding, $limit);
       }
   }
   

Implementation Patterns

Core Workflows

1. Vector CRUD Operations

• Insert:

  $this->store->insert('user_123', [0.1, 0.5, ..., 0.9]); // 1536-dim vector
  

• Batch Insert:

  $this->store->insertMany([
      'user_123' => [0.1, 0.5, ...],
      'user_456' => [0.2, 0.6, ...],
  ]);
  

• Delete:

  $this->store->remove('user_123');
  

2. Similarity Search

• K-Nearest Neighbors (KNN):

  $results = $this->store->search([0.3, 0.7, ...], 3); // Top 3 matches
  

• With Filters:

  $results = $this->store->search(
      [0.3, 0.7, ...],
      3,
      ['@tag': ['recommendation']] // RedisSearch filter syntax
  );
  

3. Hybrid Search

Combine vector similarity with Redis full-text search:

$results = $this->store->search(
    [0.3, 0.7, ...],
    5,
    ['@text': 'machine learning'] // Full-text query
);

Laravel-Specific Patterns

Adapter Layer for Symfony AI

Create a Laravel-compatible store by implementing Symfony\AI\Store\StoreInterface:

// app/Services/AiRedisStore.php
use Symfony\Component\Redis\ClientInterface;
use Symfony\AI\Store\StoreInterface;

class AiRedisStore implements StoreInterface {
    public function __construct(private ClientInterface $redis) {}

    public function insert(string $id, array $vector): void {
        $this->redis->hSet('vector:' . $id, 'vector', json_encode($vector));
        $this->redis->ftCreate('ai_vectors', 'ON HASH PREFIX 1 "vector:"');
    }

    // Implement other StoreInterface methods...
}

Service Provider Binding

// app/Providers/AiServiceProvider.php
use Symfony\Component\Redis\ClientInterface;

public function register() {
    $this->app->bind(StoreInterface::class, function ($app) {
        return new AiRedisStore($app->make(ClientInterface::class));
    });
}

Redis Client Compatibility

Use symfony/redis with Laravel’s Redis:

composer require symfony/redis

Configure in config/services.php:

'redis' => [
    'client' => Symfony\Component\Redis\Client::class,
    'dsn' => env('REDIS_DSN'),
],

Advanced Patterns

Dynamic Index Management

Recreate indices on schema changes:

public function recreateIndex(): void {
    $this->redis->ftDropIndex('ai_vectors');
    $this->redis->ftCreate('ai_vectors', 'ON HASH PREFIX 1 "vector:" SCHEMA vector FIELD HASH $ DIM 1536');
}

Query Optimization

Use RedisSearch parameters for performance:

$results = $this->store->search(
    $queryVector,
    10,
    [],
    ['DIALECT' => 2, 'LIMIT' => 10, 'SORTBY' => 'vector:>score'] // DIALECT 2 for KNN
);

Caching Layer

Cache frequent queries to reduce Redis load:

use Symfony\Component\Cache\Adapter\RedisAdapter;

public function __construct(
    private StoreInterface $store,
    private RedisAdapter $cache
) {}

public function getCachedSimilarVectors(string $query, int $limit): array {
    $cacheKey = "similarity:{$query}:{$limit}";
    return $this->cache->get($cacheKey, function () use ($query, $limit) {
        return $this->store->search($query, $limit);
    }, 300); // Cache for 5 minutes
}

Gotchas and Tips

Pitfalls

1. Redis Version Mismatch:

   • Error: RedisSearch commands not supported.
   • Fix: Ensure Redis 7.0+ with AI modules enabled. Verify with:

     redis-cli MODULE LIST
     

2. Index Schema Mismatch:

   • Error: WRONGTYPE Operation against a key holding the wrong kind of value.
   • Fix: Recreate the index with the correct SCHEMA and DIM:

     redis-cli FT.CREATE ai_vectors ON HASH PREFIX 1 "vector:" SCHEMA vector FIELD HASH $ DIM 1536
     

3. Memory Limits:

   • Error: Redis evicts vectors due to maxmemory policy.
   • Fix: Monitor memory usage and adjust:

     redis-cli INFO memory
     

     Configure MAXENTRIES in the index:

     redis-cli FT.CREATE ai_vectors ON HASH PREFIX 1 "vector:" MAXENTRIES 1000000
     

4. Vector Dimension Mismatch:

   • Error: ERR Wrong number of arguments for 'FT.SEARCH' command.
   • Fix: Ensure all inserted vectors match the index’s DIM (e.g., 1536 for OpenAI embeddings).

5. Laravel-Symfony Redis Client Conflict:

   • Error: Class 'Symfony\Component\Redis\ClientInterface' not found.
   • Fix: Install symfony/redis and bind it to Laravel’s Redis:

     $this->app->bind(\Symfony\Component\Redis\ClientInterface::class, function ($app) {
         return new \Symfony\Component\Redis\Client($app['redis.client']);
     });
     

Debugging Tips

1. Inspect Redis Index:

   redis-cli FT._LIST
   redis-cli FT.INFO ai_vectors
   

2. Log Raw Redis Commands: Enable Symfony’s Redis debug mode:

   # config/packages/redis.yaml
   framework.redis:
       client:
           logging: true
   

3. Validate Vectors: Check vector dimensions before insertion:

   if (count($vector) !== 1536) {
       throw new \InvalidArgumentException('Vector dimension must be 1536.');
   }
   

4. Query Profiling: Use Redis’s FT.SEARCH with PROFILE:

   redis-cli FT.SEARCH ai_vectors "vector:[0.3 0.7 ...]" PROFILE
   

Extension Points

1. Custom Scoring: Extend the store to support custom scoring functions:

   public function searchWithCustomScore(array $queryVector, int $limit, callable $scorer) {
       $results = $this->redis->ftSearch('ai_vectors', '*=>[KNN 3 @vector:$queryVector AS score]');
       return array_map($scorer, $results);
   }