Skip to main content

Crate hnsw_vector_search

Crate hnsw_vector_search 

Source
Expand description

A high-performance semantic search engine using Hierarchical Navigable Small World (HNSW) graphs and ONNX transformer embeddings.

§Features

  • Fast search: O(log N) approximate nearest neighbor search
  • SIMD optimizations: 3-4x speedup using ARM NEON on Apple Silicon
  • Real embeddings: Integration with ONNX Runtime for transformer models
  • Persistent storage: Memory-mapped indices for instant loading
  • CLI tool: Easy-to-use command-line interface

§Quick Start

use hnsw_vector_search::{HnswGraph, OnnxEmbedder};

// Load embedding model
let mut embedder = OnnxEmbedder::new(
    "models/all-MiniLM-L6-v2.onnx",
    "models/tokenizer.json"
).unwrap();

// Create index
let mut index = HnswGraph::new(16, 200);

// Add documents
let docs = vec!["Rust is fast", "Python is popular"];
for doc in docs {
    let embedding = embedder.embed(doc).unwrap();
    index.insert(embedding);
}

// Search
let query = embedder.embed("programming languages").unwrap();
let results = index.search(&query, 5, 50);

§Architecture

The library is organized into several modules:

  • simd - SIMD-optimized vector operations (NEON on ARM)
  • hnsw - HNSW graph structure and algorithms
  • embeddings - ONNX Runtime integration for embeddings
  • persistence - Serialization and memory-mapped storage
  • cli - Command-line interface

§Performance

On Apple M4 Pro (typical 1000 vectors, 384 dimensions):

  • Search: ~10-20 µs per query
  • Insertion: ~50-100 µs per vector
  • Embedding: ~15-25 ms per text
  • Load (mmap): ~1-5 ms

§Algorithm Details

HNSW creates a multi-layer graph where:

  • Layer 0: All vectors (dense connections)
  • Higher layers: Exponentially fewer vectors (sparse, for navigation)

Search proceeds top-down:

  1. Start at entry point in highest layer
  2. Greedily navigate to nearest neighbor
  3. Drop to next layer
  4. Repeat until layer 0
  5. Return k nearest neighbors

Time complexity: O(log N) expected

Re-exports§

pub use config::Config;
pub use config::EmbeddingConfig;
pub use config::HnswConfig;
pub use embeddings::OnnxEmbedder;
pub use error::Error;
pub use error::Result;
pub use hnsw::HnswGraph;
pub use persistence::load_index;
pub use persistence::load_index_mmap;
pub use persistence::save_index;
pub use simd::cosine_similarity;
pub use simd::dot_product;
pub use simd::normalize;

Modules§

cli
config
Configuration management for HNSW index
embeddings
error
Error types for the HNSW vector search library
hnsw
Hierarchical Navigable Small World (HNSW) graph implementation
persistence
simd
SIMD-optimized vector operations

Macros§

debug
Logs a message at the debug level.
error
Logs a message at the error level.
info
Logs a message at the info level.
trace
Logs a message at the trace level.
warn
Logs a message at the warn level.