Spring AI Embeddings

Spring AI - Embeddings API

Description

Complete guide for text embeddings in Spring AI. Covers embedding model configuration, batch processing strategies, supported providers, and integration with vector stores for similarity search and semantic operations.

When to Use

• Converting text to vector representations
• Semantic search implementation
• Building embedding pipelines
• Batch processing documents
• Comparing text similarity
• Preparing data for RAG systems
• Clustering and classification tasks

Topics Covered

1. Supported Embedding Providers

• OpenAI: text-embedding-3-small, text-embedding-3-large
• Azure OpenAI: Full deployment support
• Google Vertex AI: Embedding Gen and Text Embedding models
• Bedrock: Titan, Cohere models
• Hugging Face: Sentence-transformers and community models
• Ollama: Local embeddings (nomic-embed-text, etc.)
• Mistral AI: Embed models
• Neo4j: Vector similarity
• Anthropic Claude: Embeds endpoint
• Voyage AI: Specialized embedding models

2. EmbeddingModel API

• embed(String text) - Single embedding
• embed(List<String> texts) - Batch embeddings
• Response format: List<Float> vectors
• Dimension varies by model (384 to 3072)
• Distance metric support (cosine, euclidean)

3. Embedding Configuration

• Model selection and deployment
• Vector dimensions
• Token limits per request
• Rate limiting and retry policies
• Timeout configuration
• Batch size optimization

4. Batching Strategy

• MetadataMode: Controls what metadata fields are embedded
  • Automatic token counting
  • Chunk aggregation before embedding
  • Cost optimization
• Token Counting: Accurate usage reporting
• Document Processing: Splitting, chunking, formatting

5. Vector Store Integration

• Storing embeddings with metadata
• Similarity search operations
• Hybrid search (vector + keyword)
• Batch add/update operations
• Filtering during retrieval

6. Multi-Embedding Strategy

• Using different embedding models
• Model-specific tuning
• Ensemble embeddings
• Re-embedding when model changes

Code Patterns

Basic Embedding

@Configuration
public class EmbeddingConfig {
    @Bean
    public EmbeddingModel embeddingModel(OpenAiApi openAiApi) {
        return new OpenAiEmbeddingModel(openAiApi,
            OpenAiEmbeddingOptions.builder()
                .withModel("text-embedding-3-small")
                .build());
    }
}

Batch Processing

List<String> texts = Arrays.asList(
    "The quick brown fox",
    "Jumps over the lazy dog",
    "Spring AI is awesome"
);

EmbeddingResponse response = embeddingModel.embedForResponse(texts);
List<List<Double>> embeddings = response.getResults()
    .stream()
    .map(Embedding::getOutput)
    .collect(toList());

Document Embedding with VectorStore

Document doc = new Document("Content here", Map.of("source", "file.txt"));
vectorStore.add(Collections.singletonList(doc));

// Query similar documents
List<Document> results = vectorStore.similaritySearch(
    SearchRequest.query("search term").withTopK(5)
);

Batch Embedding Configuration

EmbeddingBatchingStrategyImpl batchingStrategy =
    new EmbeddingBatchingStrategyImpl(
        embeddingModel,
        new TokenCounterManager(/* config */),
        1000  // max tokens per batch
    );

Configuration via Properties

spring.ai.openai.embedding.options.model=text-embedding-3-small
spring.ai.embedding.batch-size=100
spring.ai.embedding.batch-mode=TOKEN_COUNT

Performance Considerations

• Batch vs single embedding trade-offs
• Caching strategies
• Token counting overhead
• Model-specific rate limits
• Re-embedding strategies

Related Skills

• vector-stores/SKILL.md - Storage and retrieval
• rag-retrieval/SKILL.md - RAG implementation
• document-processing/SKILL.md - Document chunking
• chat-models/SKILL.md - Chat integration

References

• API: /pages/api/embeddings.adoc
• Vector DB: /pages/api/vectordbs.adoc
• Usage: /pages/api/usage-handling.adoc
• Providers: Multiple provider-specific docs