Add a Hash to Vector embedding sources to detect if source and embedding are out of sync

[bsbodden]

See https://github.com/redis/redis-om-spring/blob/main/redis-om-spring/src/main/java/com/redis/om/spring/annotations/Vectorize.java

Ideally a new annotation on the Hash field with connect it to the Vectorize annotation 'source' something like:

@Document
public class DocWithCustomModelOpenAIEmbedding {
  @Id
  private String id;

  @Indexed
  @NonNull
  private String name;

  @Indexed( //
            schemaFieldType = SchemaFieldType.VECTOR, //
            algorithm = VectorAlgorithm.HNSW, //
            type = VectorType.FLOAT32, //
            dimension = 3072, //
            distanceMetric = DistanceMetric.COSINE, //
            initialCapacity = 10
  )
  private float[] textEmbedding;

  @Vectorize( //
              destination = "textEmbedding", //
              embeddingType = EmbeddingType.SENTENCE, //
              provider = EmbeddingProvider.OPENAI, //
              openAiEmbeddingModel = EmbeddingModel.TEXT_EMBEDDING_3_LARGE, //
              trackChanges = true // <==== This will tell OM to hash the field into a private JSON or Hash field like `_text_hash` matching the name of the field below
  )
  @NonNull
  private String text;
}

[jeremyplichta]

@bsbodden Can you provide more context or an example here? Is the idea if you update the text after you have already saved the object using OM (and the embedder is called) that the text will get revectorized at that point? Once you call save again wouldn't it re-embed it anyway?

[bsbodden]

@bsbodden Can you provide more context or an example here? Is the idea if you update the text after you have already saved the object using OM (and the embedder is called) that the text will get revectorized at that point? Once you call save again wouldn't it re-embed it anyway?

Exactly!

[bsbodden]

Design Proposal: Hash Tracking for Vector Embeddings

Overview

The feature would add automatic change detection for source text fields used in vector embeddings, preventing unnecessary re-embedding when the source content hasn't changed.

Core Components

1. Enhanced @vectorize Annotation

Add a new trackChanges parameter to the existing @vectorize annotation:

  @Vectorize(
      destination = "textEmbedding",
      embeddingType = EmbeddingType.SENTENCE,
      provider = EmbeddingProvider.OPENAI,
      trackChanges = true  // NEW: Enable change tracking
  )
  private String text;

2. Hash Algorithm Configuration

Add configurable hash algorithm support:

  @Vectorize(
      destination = "textEmbedding",
      embeddingType = EmbeddingType.SENTENCE,
      provider = EmbeddingProvider.OPENAI,
      trackChanges = true,
      hashAlgorithm = HashAlgorithm.SHA256  // Default: SHA256
  )
  private String text;

3. Hash Field Generation Strategy

When trackChanges = true, automatically generate a hash field with the pattern _{sourceFieldName}_hash:

• Source field: text → Hash field: _text_hash
• Source field: description → Hash field: _description_hash

4. Implementation

Modified Annotation:

  // redis-om-spring-ai/src/main/java/com/redis/om/spring/annotations/Vectorize.java
  public @interface Vectorize {
      // ... existing parameters ...

      /**
       * Enable tracking of source field changes to avoid unnecessary re-embedding.
       * When enabled, creates a hash field to detect content changes.
       * 
       * @return true if change tracking should be enabled
       */
      boolean trackChanges() default false;

      /**
       * Hash algorithm to use for change tracking.
       * 
       * @return the hash algorithm to use
       */
      HashAlgorithm hashAlgorithm() default HashAlgorithm.SHA256;
  }

  New Hash Algorithm Enum:
  // redis-om-spring-ai/src/main/java/com/redis/om/spring/annotations/HashAlgorithm.java
  public enum HashAlgorithm {
      MD5("MD5"),
      SHA1("SHA-1"),
      SHA256("SHA-256"),
      SHA512("SHA-512");

      private final String algorithmName;

      HashAlgorithm(String algorithmName) {
          this.algorithmName = algorithmName;
      }

      public String getAlgorithmName() {
          return algorithmName;
      }
  }

Enhanced DefaultEmbedder:
The DefaultEmbedder class would be modified to:

1. Check for existing hash before processing embeddings
2. Generate hash of current source content
3. Compare hashes to determine if re-embedding is needed
4. Update hash field after successful embedding generation

Key changes in processEntity method:

  // In DefaultEmbedder.processEntity()
  private boolean shouldReembed(PropertyAccessor accessor, Vectorize vectorize, String fieldName, Object fieldValue) {
      if (!vectorize.trackChanges()) {
          return true; // Always embed if tracking disabled
      }

      String hashFieldName = "_" + fieldName + "_hash";
      String currentHash = generateHash(fieldValue.toString(), vectorize.hashAlgorithm());
      String existingHash = (String) accessor.getPropertyValue(hashFieldName);

      return !currentHash.equals(existingHash);
  }

  private void updateHash(PropertyAccessor accessor, Vectorize vectorize, String fieldName, Object fieldValue) {
      if (vectorize.trackChanges()) {
          String hashFieldName = "_" + fieldName + "_hash";
          String currentHash = generateHash(fieldValue.toString(), vectorize.hashAlgorithm());
          accessor.setPropertyValue(hashFieldName, currentHash);
      }
  }

5. Metamodel Integration

The hash fields would be automatically included in the metamodel generation for proper indexing and storage.

6. Usage Examples

Basic usage:

  @Document
  public class Product {
      @Id
      private String id;

      @Vectorize(
          destination = "descriptionEmbedding",
          trackChanges = true
      )
      private String description;

      @VectorIndexed(algorithm = VectorAlgorithm.HNSW)
      private float[] descriptionEmbedding;

      // Hash field automatically generated: _description_hash
  }

Advanced usage with custom hash algorithm:

  @Document
  public class Document {
      @Id
      private String id;

      @Vectorize(
          destination = "contentEmbedding",
          embeddingType = EmbeddingType.SENTENCE,
          provider = EmbeddingProvider.OPENAI,
          trackChanges = true,
          hashAlgorithm = HashAlgorithm.SHA512
      )
      private String content;

      @VectorIndexed(algorithm = VectorAlgorithm.HNSW, dimension = 1536)
      private float[] contentEmbedding;
  }

Benefits

1. Performance: Avoids costly re-embedding when content hasn't changed
2. Cost Efficiency: Reduces API calls to paid embedding services (OpenAI, etc.)
3. Backward Compatibility: Existing code continues to work unchanged
4. Configurable: Users can choose hash algorithms based on their security/performance needs
5. Automatic: No manual hash management required

[raphaeldelio]

I think it makes sense given that the embedding process may add significant latency.

The semantics of the parameter is not intentional to me though. Maybe onChangeOnly would be clearer