S3 Vectors Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require async-aws/s3-vectors
   

   Add AWS SDK PHP v3+ as a dependency if not already present:

   composer require aws/aws-sdk-php
   

2. Configuration Publish the package config (if available) or set AWS credentials via Laravel's .env:

   AWS_ACCESS_KEY_ID=your_access_key
   AWS_SECRET_ACCESS_KEY=your_secret_key
   AWS_DEFAULT_REGION=us-east-1
   AWS_S3_VECTORS_BUCKET=your-bucket-name
   

3. First Use Case: Store a Vector

   use AsyncAws\S3Vectors\S3VectorsClient;
   use AsyncAws\Core\Exception\SdkException;
   
   $client = new S3VectorsClient();
   try {
       $result = $client->putVector([
           'Bucket' => env('AWS_S3_VECTORS_BUCKET'),
           'Key'    => 'user_123_embedding.bin',
           'Vector' => [0.1, 0.5, -0.3, 0.7], // Example float32 vector
           'Dimensions' => 4, // Required for S3Vectors
       ]);
       Log::info('Vector stored successfully', ['key' => 'user_123_embedding.bin']);
   } catch (SdkException $e) {
       Log::error('Failed to store vector', ['error' => $e->getMessage()]);
   }
   

4. Retrieve a Vector

   try {
       $result = $client->getVector([
           'Bucket' => env('AWS_S3_VECTORS_BUCKET'),
           'Key'    => 'user_123_embedding.bin',
       ]);
       $vector = $result->get('Vector');
       Log::info('Retrieved vector', ['vector' => $vector]);
   } catch (SdkException $e) {
       Log::error('Failed to retrieve vector', ['error' => $e->getMessage()]);
   }
   

5. Query Vectors (Basic)

   try {
       $result = $client->queryVectors([
           'Bucket' => env('AWS_S3_VECTORS_BUCKET'),
           'Vector' => [0.2, 0.6, -0.4, 0.8], // Query vector
           'Dimensions' => 4,
           'Limit' => 5, // Number of results to return
       ]);
       $matches = $result->get('Matches');
       Log::info('Query results', ['matches' => $matches]);
   } catch (SdkException $e) {
       Log::error('Query failed', ['error' => $e->getMessage()]);
   }
   

Implementation Patterns

Async Workflows with Laravel Queues

Leverage Laravel's queue system to offload vector operations to background jobs, improving API response times.

1. Create a Job for Storing Vectors

   namespace App\Jobs;
   
   use AsyncAws\S3Vectors\S3VectorsClient;
   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   use Illuminate\Foundation\Bus\Dispatchable;
   use Illuminate\Queue\InteractsWithQueue;
   use Illuminate\Queue\SerializesModels;
   
   class StoreVectorJob implements ShouldQueue
   {
       use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
   
       public function __construct(
           public string $bucket,
           public string $key,
           public array $vector,
           public int $dimensions
       ) {}
   
       public function handle(S3VectorsClient $client)
       {
           $client->putVector([
               'Bucket' => $this->bucket,
               'Key' => $this->key,
               'Vector' => $this->vector,
               'Dimensions' => $this->dimensions,
           ]);
       }
   }
   

2. Dispatch the Job

   StoreVectorJob::dispatch(
       bucket: env('AWS_S3_VECTORS_BUCKET'),
       key: 'user_123_embedding.bin',
       vector: [0.1, 0.5, -0.3, 0.7],
       dimensions: 4
   )->onQueue('s3-vectors');
   

3. Batch Processing Use Laravel's batch method to process multiple vectors efficiently:

   VectorBatch::dispatch($vectors)->onQueue('s3-vectors');
   

Integration with Laravel Services

Wrap the S3Vectors client in a Laravel service for cleaner integration.

1. Create a Vector Service

   namespace App\Services;
   
   use AsyncAws\S3Vectors\S3VectorsClient;
   use Illuminate\Support\Facades\Log;
   
   class VectorService
   {
       public function __construct(
           protected S3VectorsClient $client
       ) {}
   
       public function storeVector(array $vector, string $key, int $dimensions): void
       {
           try {
               $this->client->putVector([
                   'Bucket' => env('AWS_S3_VECTORS_BUCKET'),
                   'Key' => $key,
                   'Vector' => $vector,
                   'Dimensions' => $dimensions,
               ]);
           } catch (\Exception $e) {
               Log::error('Failed to store vector', ['error' => $e->getMessage()]);
               throw $e;
           }
       }
   
       public function queryVectors(array $queryVector, int $limit = 10): array
       {
           try {
               $result = $this->client->queryVectors([
                   'Bucket' => env('AWS_S3_VECTORS_BUCKET'),
                   'Vector' => $queryVector,
                   'Dimensions' => count($queryVector),
                   'Limit' => $limit,
               ]);
               return $result->get('Matches');
           } catch (\Exception $e) {
               Log::error('Query failed', ['error' => $e->getMessage()]);
               throw $e;
           }
       }
   }
   

2. Bind the Service in AppServiceProvider

   public function register()
   {
       $this->app->bind(VectorService::class, function ($app) {
           return new VectorService(new S3VectorsClient());
       });
   }
   

3. Use the Service in Controllers

   use App\Services\VectorService;
   
   class VectorController extends Controller
   {
       public function __construct(
           protected VectorService $vectorService
       ) {}
   
       public function store(Request $request)
       {
           $this->vectorService->storeVector(
               $request->vector,
               'user_' . $request->user_id . '_embedding.bin',
               count($request->vector)
           );
           return response()->json(['status' => 'success']);
       }
   
       public function search(Request $request)
       {
           $matches = $this->vectorService->queryVectors(
               $request->query_vector,
               $request->limit ?? 10
           );
           return response()->json($matches);
       }
   }
   

Paginated Queries

S3Vectors supports paginated QueryVectors requests (up to 10,000 results per query). Implement pagination in Laravel:

1. Query with Pagination

   public function queryVectorsPaginated(array $queryVector, int $limit = 10, int $page = 1): array
   {
       $nextToken = null;
       if ($page > 1) {
           $nextToken = $this->getNextTokenFromCache($page); // Implement caching logic
       }
   
       $result = $this->client->queryVectors([
           'Bucket' => env('AWS_S3_VECTORS_BUCKET'),
           'Vector' => $queryVector,
           'Dimensions' => count($queryVector),
           'Limit' => $limit,
           'NextToken' => $nextToken,
       ]);
   
       $matches = $result->get('Matches');
       $nextToken = $result->get('NextToken');
   
       if ($nextToken) {
           $this->cacheNextToken($page + 1, $nextToken); // Implement caching logic
       }
   
       return $matches;
   }
   

2. Use in Controller

   public function search(Request $request)
   {
       $matches = $this->vectorService->queryVectorsPaginated(
           $request->query_vector,
           $request->limit ?? 10,
           $request->page ?? 1
       );
       return response()->json($matches);
   }
   

Error Handling and Retries

Implement robust error handling and retries for S3 operations.

1. Job Retry Logic

   namespace App\Jobs;
   
   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   use Illuminate\Foundation\Bus\Dispatchable;
   use Illuminate\Queue\InteractsWithQueue;
   use Illuminate\Queue\SerializesModels;
   use AsyncAws\Core\Exception\SdkException;
   use Illuminate\Support\Facades\Log;
   
   class StoreVectorJob implements Should