Skip to main content

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.
Characteristics:
  • Deterministic output based on text hash
  • Configurable dimensions (default: 384)
  • ~50μs generation time
  • Normalized vectors

OpenAIEmbeddingService

OpenAI API integration.
Supported Models:
  • text-embedding-3-small (1536 dimensions)
  • text-embedding-3-large (3072 dimensions)
  • text-embedding-ada-002 (1536 dimensions)
Features:
  • Batch processing (up to 100 texts)
  • Automatic retry with exponential backoff
  • Rate limit handling
  • Conditional compilation with openai feature

Usage Examples

Basic Usage

With OpenAI

With Caching

Feature Flags

Available features:
  • openai - Enable OpenAI provider (adds ureq, url dependencies)
  • local - Enable local models (adds candle dependencies) [planned]

Environment Variables

When using OpenAI provider:
  • OPENAI_API_KEY - Required API key
  • OPENAI_EMBEDDING_MODEL - Model name (default: “text-embedding-3-small”)
  • EMBEDDING_CACHE_SIZE - Cache capacity (default: 1000)

Performance Considerations

  1. Batch Operations - Process multiple texts together for better throughput
  2. Caching - Use EmbeddingCache to avoid redundant API calls
  3. Model Selection - Choose appropriate model for quality/cost tradeoff
  4. Connection Pooling - OpenAI provider reuses HTTP connections

Thread Safety

All types are thread-safe:
  • EmbeddingService trait requires Send + Sync
  • EmbeddingCache uses Arc<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