xz-embed

Vector embedding and vector store abstraction layer for the XiaoZhu AI ecosystem.

xz-embed provides a unified trait-based interface for generating text embeddings and storing/searching vectors. It decouples your application from any specific embedding provider or vector database backend, making it easy to swap implementations without changing business logic.

Features

• Trait-based abstraction: EmbeddingModel for embedding providers, VectorStore for storage backends. Swap OpenAI for a mock or local model with one type change.
• OpenAI integration (feature openai): OpenAiEmbedder supports text-embedding-3-small / text-embedding-3-large with configurable dimensions (512, 1536, 3072).
• Mock embedder: MockEmbedder for deterministic testing without network calls or API keys.
• Vector stores: InMemoryVectorStore for testing and lightweight use, SqliteVecStore (feature sqlite-vec) for persistent storage.
• Metadata filtering: Rich filter expressions (Eq, Ne, In, Range, And/Or/Not) for precise vector search.
• Dimension reduction: Native (API-side) or truncation-based reduction via DimensionReducer.
• Batch management: ConcurrentBatchManager for high-throughput embedding with configurable concurrency.
• Indexing: IndexBuilder for background index construction with configurable rebuild triggers (count-based, interval-based, manual).
• Quantization: ProductQuantizer and ScalarQuantizer for reducing vector storage footprint.
• Fusion: RRF (Reciprocal Rank Fusion) for combining results from multiple searches.
• No unsafe code: forbid(unsafe_code) enforced workspace-wide.

Quick Start

use xz_embed::{MockEmbedder, InMemoryVectorStore, EmbeddingModel, VectorStore, VectorEntry};
use std::collections::HashMap;

// 1. Create a mock embedder that returns 4-dimensional vectors
let embedder = MockEmbedder::new(4, 16);

// 2. Generate embeddings
let texts = vec!["hello world", "rust is awesome", "vector search"];
let vectors = embedder.embed(&texts).await?;

// 3. Store vectors in memory
let store = InMemoryVectorStore::new(4);
for (i, vec) in vectors.iter().enumerate() {
    let mut metadata = HashMap::new();
    metadata.insert("source".into(), "demo".into());
    store.insert(VectorEntry {
        id: format!("doc-{i}"),
        vector: vec.clone(),
        metadata,
        content: Some(texts[i].into()),
        created_at: 1000,
        expires_at: None,
        channel: Some("demo".into()),
    }).await?;
}

// 4. Search
let query = embedder.embed_single("rust").await?;
let results = store.search(&query, 5).await?;
for r in &results {
    println!("  score={:.4} content={:?}", r.score, r.content);
}

Usage with OpenAI

use xz_embed::{OpenAiEmbedder, InMemoryVectorStore, EmbeddingModel};

// Create from environment (OPENAI_API_KEY, OPENAI_EMBED_MODEL)
let embedder = OpenAiEmbedder::from_env()?;

// Or configure dimensions explicitly
let embedder = OpenAiEmbedder::from_env()?
    .with_dimensions(512)?;

// Embed and search (same VectorStore interface)
let vec = embedder.embed_single("What is Rust?").await?;

Key Traits

Feature Flags

Crate Status

Part of the xz-modules workspace. Dual-licensed under MIT OR Apache-2.0.