Ai Milvus Store Laravel Package

Getting Started

Minimal Setup

1. Install the Package:

   composer require symfony/ai-milvus-store
   

2. Configure Symfony AI: Add Milvus store configuration to config/packages/ai.yaml:

   framework:
       ai:
           stores:
               milvus:
                   type: MilvusStore
                   uri: "http://your-milvus-server:19530"  # Replace with your Milvus endpoint
                   collection: "your_collection_name"    # Pre-created collection
                   options:
                       consistency_level: "Strong"
   

3. First Use Case - Inserting Vectors:

   use Symfony\AI\Store\StoreInterface;
   use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;
   
   #[AutoconfigureTag('ai.store')]
   class MyService {
       public function __construct(
           private StoreInterface $milvusStore
       ) {}
   
       public function addVector(array $vector, array $metadata): void {
           $this->milvusStore->add($vector, $metadata);
       }
   }
   

4. First Use Case - Searching Vectors:

   public function searchVectors(array $queryVector, int $limit = 5): array {
       return $this->milvusStore->nearest(
           $queryVector,
           $limit,
           filter: ['category' => 'tech'] // Example filter
       );
   }
   

Where to Look First

• Symfony AI Documentation: symfony/ai for store interface details.
• Milvus REST API Docs: Milvus Collection API for schema and collection management.
• Package Source: symfony/ai-milvus-store on GitHub for advanced usage and edge cases.

Implementation Patterns

Core Workflows

1. Vector CRUD Operations

• Insertion:

  $this->milvusStore->add($vector, ['metadata' => 'value']);
  

  • Use for embedding storage (e.g., from symfony/ai's EmbeddingGenerator).
  • Batch inserts for efficiency:

    $this->milvusStore->addMany([[$vector1, $metadata1], [$vector2, $metadata2]]);
    

• Deletion:

  $this->milvusStore->remove($vectorId); // By primary key
  $this->milvusStore->removeMany([$id1, $id2]); // Bulk delete
  

  • Use for dynamic datasets (e.g., user-generated content).

2. Search Patterns

• Basic Nearest Neighbors:

  $results = $this->milvusStore->nearest($queryVector, 10);
  

  • Returns sorted vectors with distances.

• Filtered Search:

  $results = $this->milvusStore->nearest(
      $queryVector,
      5,
      filter: ['AND' => [
          ['category' => 'books'],
          ['rating' => ['$gt' => 4]]
      ]]
  );
  

  • Leverage Milvus’s Boolean filter expressions.

• Hybrid Search: Combine vector similarity with metadata:

  $results = $this->milvusStore->nearest(
      $queryVector,
      5,
      filter: ['OR' => [
          ['author' => 'J.K. Rowling'],
          ['genre' => 'fantasy']
      ]]
  );
  

3. Collection Management

• Dynamic Collection Handling:

  // Check if collection exists (manual step; not in package)
  if (!$this->milvusStore->collectionExists('dynamic_collection')) {
      $this->createCollection('dynamic_collection', 768); // 768-dim vectors
  }
  

  • Use for multi-tenant apps or per-user collections.

4. Integration with Symfony AI Components

• Embedding Pipeline:

  use Symfony\AI\EmbeddingGeneratorInterface;
  
  public function generateAndStoreEmbedding(string $text): void {
      $embedding = $this->embeddingGenerator->generate($text);
      $this->milvusStore->add($embedding, ['text' => $text, 'source' => 'user']);
  }
  

• Retriever Integration:

  use Symfony\AI\RetrieverInterface;
  
  class MilvusRetriever implements RetrieverInterface {
      public function __construct(private StoreInterface $milvusStore) {}
  
      public function retrieve(string $query, int $limit = 3): array {
          $vector = $this->embeddingGenerator->generate($query);
          return $this->milvusStore->nearest($vector, $limit);
      }
  }
  

Advanced Patterns

1. Async Operations with Messenger

• Offload heavy operations (e.g., bulk inserts) to Symfony’s Messenger:

use Symfony\Component\Messenger\MessageBusInterface;

public function __construct(
    private StoreInterface $milvusStore,
    private MessageBusInterface $bus
) {}

public function asyncBatchInsert(array $vectors): void {
    $this->bus->dispatch(new BatchInsertMessage($vectors));
}

• Create a handler:

#[AsMessageHandler]
public function handle(BatchInsertMessage $message): void {
    $this->milvusStore->addMany($message->getVectors());
}

2. Caching Layer

• Cache frequent queries with Redis:

use Symfony\Contracts\Cache\CacheInterface;

public function __construct(
    private StoreInterface $milvusStore,
    private CacheInterface $cache
) {}

public function cachedSearch(array $queryVector, string $cacheKey): array {
    return $this->cache->get($cacheKey, fn() =>
        $this->milvusStore->nearest($queryVector, 10)
    );
}

3. Schema Migrations

• Handle schema changes (e.g., adding metadata fields):

public function migrateCollection(string $collection, array $newSchema): void {
    // Drop and recreate collection (Milvus REST API)
    $this->milvusStore->dropCollection($collection);
    $this->milvusStore->createCollection($collection, $newSchema);
    // Reinsert data
}

4. Error Handling and Retries

• Decorate the store with retry logic:

use Symfony\Component\Retry\Retry;

public function safeNearest(array $vector, int $limit): array {
    return Retry::create()
        ->withMaxRetries(3)
        ->withDelay(100)
        ->execute(fn() => $this->milvusStore->nearest($vector, $limit));
}

Gotchas and Tips

Pitfalls

1. Collection Management

• Gotcha: The package does not handle collection creation. You must:

  • Create collections via Milvus REST API before first use.
  • Example schema mismatch errors:

    "code": 400, "message": "Schema mismatch: expected 384 dim, got 768"
    

  • Fix: Validate dimensions and fields before insertion.

• Tip: Use a migration script to ensure collections exist:

  if (!$this->milvusStore->collectionExists('my_collection')) {
      $this->milvusStore->createCollection('my_collection', [
          'dimension' => 768,
          'fields' => [
              ['name' => 'id', 'type' => 'INT64', 'is_primary' => true],
              ['name' => 'vector', 'type' => 'FLOAT_VECTOR', 'dim' => 768],
              ['name' => 'metadata', 'type' => 'JSON'],
          ],
      ]);
  }
  

2. Filter Syntax

• Gotcha: Boolean filters use Milvus’s syntax, which differs from SQL:
  • Correct:

    ['AND' => [['field' => 'value'], ['field' => ['$gt' => 10]]]]
    

  • Incorrect (SQL-style):

    ['field > 10 AND field2 = "value"'] // Will fail
    

  • Fix: Refer to Milvus Boolean Operators.

3. Consistency Levels

• Gotcha: Milvus offers Strong, Eventual, and Bounded consistency. Default is Strong, which may impact performance.
  • Tip: Use Eventual for read-heavy workloads:

    options:
        consistency_level: "