Embedding Search Tutorial
Learn how to implement semantic search using Soul Kernel’s embedding and storage systems.Overview
This tutorial demonstrates how to:- Generate embeddings for text content
- Store memories with vector embeddings
- Perform semantic similarity search
- Use caching for efficiency
- Switch between embedding providers
Prerequisites
- Rust 1.79 or later
- Basic understanding of vector embeddings
- (Optional) OpenAI API key for production embeddings
Setup
1. Add Dependencies
Add the required crates to yourCargo.toml:
2. Environment Configuration
For OpenAI embeddings, create anopenai.env file:
Basic Implementation
Step 1: Initialize Services
Step 2: Store Memories with Embeddings
Step 3: Perform Semantic Search
Advanced Features
Batch Processing
Process multiple texts efficiently:Filtered Search
Search with specific criteria:Similarity Threshold
Only return results above a certain similarity:Performance Tips
1. Use Caching Effectively
2. Batch Operations
3. Optimize Storage
Switching Providers
Development (Mock)
- Fast generation (~50μs)
- Low similarity scores
- Good for testing logic
Production (OpenAI)
- Slower generation (~310ms)
- High-quality semantic matching
- Meaningful similarity scores
Complete Example
See the full working example at:Troubleshooting
OpenAI API Issues
-
API Key Not Found
Solution: Create
openai.envfile with your API key -
Rate Limiting
Solution: Implement exponential backoff or reduce batch size
-
Model Not Found
Solution: Use a valid embedding model (not chat models)
Storage Issues
-
Database Locked
Solution: Ensure only one writer at a time, or use WAL mode
-
Embedding Dimension Mismatch
Solution: Ensure consistent embedding dimensions across providers
Next Steps
- Implement Memory Sync for cross-device search
- Add Custom Embeddings for domain-specific models
- Explore Advanced Search techniques
- Build a Conversational Memory system
Change Log
- 2025-06-13: Initial tutorial created
- 2025-06-13: Added complete working examples
- 2025-06-13: Added troubleshooting section