Ai S3Vectors Store Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require symfony/ai-s3vectors-store
   

2. Enable S3 Vectors in Your Bucket: Ensure your S3 bucket has the S3 Vectors feature enabled via AWS CLI or Console:

   aws s3api put-bucket-vector --bucket your-bucket-name --region us-east-1
   

3. Configure Symfony AI: Add the store configuration to your config/packages/ai.yaml:

   framework:
       ai:
           stores:
               s3_vectors:
                   type: 'S3VectorsStore'
                   bucket: 'your-bucket-name'
                   region: 'us-east-1'
                   # Optional: Custom AWS credentials/config
                   aws:
                       credentials:
                           key: '%env(AWS_ACCESS_KEY_ID)%'
                           secret: '%env(AWS_SECRET_ACCESS_KEY)%'
                       region: 'us-east-1'
   

4. First Use Case: Inject and use the store in a service or controller:

   use Symfony\AI\Store\StoreInterface;
   
   class VectorService {
       public function __construct(private StoreInterface $s3VectorsStore) {}
   
       public function storeVector(array $vector): void {
           $this->s3VectorsStore->putVectors([$vector]);
       }
   
       public function queryVectors(array $queryVector, int $limit = 10): array {
           return $this->s3VectorsStore->queryVectors($queryVector, $limit);
       }
   }
   

5. Register the Service: Bind the store to Symfony’s DI container in services.yaml:

   services:
       App\Service\VectorService:
           arguments:
               $s3VectorsStore: '@ai.store.s3_vectors'
   

Implementation Patterns

Usage Patterns

1. Vector Ingestion: Batch vectors for efficient uploads to S3:

   $batch = [];
   foreach ($rawVectors as $vector) {
       $batch[] = [
           'id' => $vector['id'],
           'vector' => $vector['embedding'],
           'metadata' => $vector['metadata'] ?? null,
       ];
       if (count($batch) >= 100) { // Optimal batch size
           $store->putVectors($batch);
           $batch = [];
       }
   }
   if (!empty($batch)) {
       $store->putVectors($batch);
   }
   

2. Querying Vectors: Use queryVectors for similarity search with optional filters:

   $results = $store->queryVectors(
       $queryVector,
       limit: 5,
       filter: ['category' => 'electronics'] // If using metadata
   );
   

3. Hybrid Workflows: Combine with other Symfony AI components (e.g., embeddings):

   $embedding = $ai->embedding->create($text);
   $similarItems = $store->queryVectors($embedding->getEmbedding());
   

Workflows

1. RAG (Retrieval-Augmented Generation):

   • Store document embeddings in S3 Vectors.
   • Query for relevant context before generating responses:

     $context = $store->queryVectors($queryEmbedding, 3);
     $response = $ai->llm->generate($prompt . "\nContext: " . $context);
     

2. Recommendation Systems:

   • Index user/item vectors for similarity-based recommendations:

     $recommendations = $store->queryVectors($userProfileEmbedding, 10);
     

3. Semantic Search:

   • Replace keyword search with vector-based retrieval:

     $searchResults = $store->queryVectors($searchQueryEmbedding);
     

Integration Tips

1. Error Handling: Wrap S3 operations in try-catch blocks to handle AWS-specific exceptions:

   try {
       $store->putVectors($vectors);
   } catch (AwsException $e) {
       // Log and retry or fallback
       $this->logger->error('S3 Vectors error: ' . $e->getMessage());
   }
   

2. Metadata Management: Use the metadata field in vectors for filtering (if supported by your S3 Vectors setup):

   $vector = [
       'id' => 'doc123',
       'vector' => $embedding,
       'metadata' => ['category' => 'tech', 'source' => 'blog'],
   ];
   

3. Testing: Use a dedicated test bucket and mock AWS credentials in tests:

   $store = new S3VectorsStore('test-bucket', 'us-west-2', [
       'credentials' => [
           'key' => 'test-key',
           'secret' => 'test-secret',
       ],
       'region' => 'us-west-2',
       'version' => 'latest',
   ]);
   

4. Performance Optimization:

   • Batching: Group vectors into batches of 100–1000 for PutVectors.
   • Parallel Queries: Use Symfony’s Messenger or parallel processing for high-throughput queries.
   • Caching: Cache frequent query results in Redis or OPcache.

5. Monitoring: Track S3 Vectors metrics via AWS CloudWatch:

   • PutVectors latency and success rates.
   • QueryVectors throughput and errors.
   • Storage costs (monitor S3 usage).

Gotchas and Tips

Pitfalls

1. S3 Vectors Feature Not Enabled:

   • Error: InvalidArgumentException or AWS API errors.
   • Fix: Explicitly enable S3 Vectors on the bucket via AWS Console or CLI.

2. Vector Size Limits:

   • Error: Vectors exceeding 1MB will fail.
   • Fix: Compress vectors or split into multiple objects.

3. AWS Credentials:

   • Error: AccessDenied or UnauthorizedOperation.
   • Fix: Ensure IAM roles/policies include s3:PutBucketVector, s3:GetBucketVector, and s3:PutObject.

4. Region Mismatch:

   • Error: Latency issues or InvalidBucketName errors.
   • Fix: Use the same region for the bucket and store configuration.

5. Metadata Limitations:

   • Error: Metadata filtering may not work as expected.
   • Fix: Use a separate metadata store (e.g., DynamoDB) if complex filtering is needed.

6. Cold Starts:

   • Issue: First query after inactivity may be slower.
   • Fix: Implement a warm-up query or use S3’s lifecycle policies to keep data hot.

Debugging

1. Enable AWS SDK Debugging: Add this to your config/packages/dev/ai.yaml:

   framework:
       ai:
           stores:
               s3_vectors:
                   aws:
                       debug: true
   

   Logs will appear in var/log/dev.log.

2. Check S3 Vectors API Calls: Use AWS CloudTrail to audit PutVectors and QueryVectors calls.

3. Validate Vector Format: Ensure vectors are in the correct format (e.g., float arrays):

   $validVector = [0.1, 0.5, ..., 0.9]; // Must be numeric and consistent length
   

Config Quirks

1. Default Credentials: The package uses Symfony’s AWS messenger configuration by default. Override if needed:

   framework:
       ai:
           stores:
               s3_vectors:
                   aws:
                       credentials:
                           key: '%env(AWS_ACCESS_KEY_ID)%'
                           secret: '%env(AWS_SECRET_ACCESS_KEY)%'
   

2. Bucket Ownership: Ensure your IAM user/role owns the bucket or has full S3 permissions.

3. CORS Issues: If accessing S3 from a browser, configure CORS on the bucket:

   aws s3api put-bucket-cors --bucket your-bucket-name --cors-configuration '{
       "CORSRules": [
           {
               "AllowedHeaders": ["*"],
               "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
               "AllowedOrigins": ["*"],
               "ExposeHeaders": []
           }
       ]
   }'
   

Extension Points

1. Custom Vector Serialization: Extend the store to handle custom vector formats:

   use Symfony\AI\Store\S3VectorsStore;
   
   class CustomS3VectorsStore extends S3VectorsStore {
       protected function serializeVector(array $vector): string {
           // Custom logic (e.g., base64 encoding)
           return base64_encode(serialize($vector));
       }
   
       protected function deserializeVector(string $data): array {
           return unserialize(base64_decode($data));
       }
   }
   

2. Query Augmentation: Add pre/post-processing to queryVectors:

   $store->queryVectors($query