Embeddings API Reference
Complete API documentation for the Soul Kernel embeddings crate.Module Overview
Core Trait
EmbeddingService
The main trait that all embedding providers implement.
Configuration
EmbeddingConfig
Configuration for embedding services.
EmbeddingProvider
Supported embedding providers.
Caching
EmbeddingCache
LRU cache for embeddings to reduce API calls.
Error Types
EmbeddingError
Error types for embedding operations.
Factory Function
create_embedding_service
Create an embedding service from configuration.
Provider Implementations
MockEmbeddingService
Mock provider for testing.
- Deterministic output based on text hash
- Configurable dimensions (default: 384)
- ~50μs generation time
- Normalized vectors
OpenAIEmbeddingService
OpenAI API integration.
text-embedding-3-small(1536 dimensions)text-embedding-3-large(3072 dimensions)text-embedding-ada-002(1536 dimensions)
- Batch processing (up to 100 texts)
- Automatic retry with exponential backoff
- Rate limit handling
- Conditional compilation with
openaifeature
Usage Examples
Basic Usage
With OpenAI
With Caching
Feature Flags
openai- Enable OpenAI provider (addsureq,urldependencies)local- Enable local models (addscandledependencies) [planned]
Environment Variables
When using OpenAI provider:OPENAI_API_KEY- Required API keyOPENAI_EMBEDDING_MODEL- Model name (default: “text-embedding-3-small”)EMBEDDING_CACHE_SIZE- Cache capacity (default: 1000)
Performance Considerations
- Batch Operations - Process multiple texts together for better throughput
- Caching - Use
EmbeddingCacheto avoid redundant API calls - Model Selection - Choose appropriate model for quality/cost tradeoff
- Connection Pooling - OpenAI provider reuses HTTP connections
Thread Safety
All types are thread-safe:EmbeddingServicetrait requiresSend + SyncEmbeddingCacheusesArc<Mutex<_>>internally- Providers can be shared across threads
Error Handling
Change Log
- 2025-06-13: Initial API documentation
- 2025-06-13: Added OpenAI provider details
- 2025-06-13: Documented caching and error handling