Skip to main content

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 your Cargo.toml:

2. Environment Configuration

For OpenAI embeddings, create an openai.env file:

Basic Implementation

Step 1: Initialize Services

Step 2: Store Memories with Embeddings

Advanced Features

Batch Processing

Process multiple texts efficiently:
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)

Results:
  • Fast generation (~50μs)
  • Low similarity scores
  • Good for testing logic

Production (OpenAI)

Results:
  • Slower generation (~310ms)
  • High-quality semantic matching
  • Meaningful similarity scores

Complete Example

See the full working example at:
Run it with:

Troubleshooting

OpenAI API Issues

  1. API Key Not Found
    Solution: Create openai.env file with your API key
  2. Rate Limiting
    Solution: Implement exponential backoff or reduce batch size
  3. Model Not Found
    Solution: Use a valid embedding model (not chat models)

Storage Issues

  1. Database Locked
    Solution: Ensure only one writer at a time, or use WAL mode
  2. Embedding Dimension Mismatch
    Solution: Ensure consistent embedding dimensions across providers

Next Steps

Change Log

  • 2025-06-13: Initial tutorial created
  • 2025-06-13: Added complete working examples
  • 2025-06-13: Added troubleshooting section