# Spring AI Embeddings

> A complete guide for text embeddings in Spring AI, covering model configuration, batch processing, and integration with vector stores.

- Skill: `mat-garcia/spring-ai-embeddings` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mat-garcia/spring-ai-embeddings`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mat-garcia/spring-ai-embeddings/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Complete terms in LICENSE.txt
- Author: mat-garcia (https://skillmd.com/u/mat-garcia)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/mat-garcia/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

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

### Batch Processing

```java
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

```java
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

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

## Configuration via Properties

```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