https://github.com/wesleyscholl/vectro-plus
โก๐ง Vectro+ โ High-Performance Embedding Engine in Rust ๐ฆ๐พ Compress, quantize, and accelerate vector search ๐ Boost retrieval speed, cut memory, keep semantic precision ๐ฏ๐ฅ
https://github.com/wesleyscholl/vectro-plus
ai ai-infrastructure ai-tooling embedding-quantization high-performance-computing llm-acceleration machine-learning memory-optimization mojo-alternative neural-compression opensource-ai performance-engineering retrieval-optimization rust rust-lang semantic-search simd similarity-search vector-database vector-embeddings
Last synced: 3 months ago
JSON representation
โก๐ง Vectro+ โ High-Performance Embedding Engine in Rust ๐ฆ๐พ Compress, quantize, and accelerate vector search ๐ Boost retrieval speed, cut memory, keep semantic precision ๐ฏ๐ฅ
- Host: GitHub
- URL: https://github.com/wesleyscholl/vectro-plus
- Owner: wesleyscholl
- License: mit
- Created: 2025-10-23T16:11:39.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-10-23T17:01:18.000Z (3 months ago)
- Last Synced: 2025-10-23T18:27:20.630Z (3 months ago)
- Topics: ai, ai-infrastructure, ai-tooling, embedding-quantization, high-performance-computing, llm-acceleration, machine-learning, memory-optimization, mojo-alternative, neural-compression, opensource-ai, performance-engineering, retrieval-optimization, rust, rust-lang, semantic-search, simd, similarity-search, vector-database, vector-embeddings
- Language: Rust
- Homepage: https://github.com/wesleyscholl/vectro-plus
- Size: 33.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ๐ Vectro+
> **High-performance embedding compression and search in Rust**
Vectro+ is a fast, memory-efficient toolkit for working with large embedding datasets. Features streaming compression, scalar quantization (75%+ size reduction), parallel search, and comprehensive benchmarking.
[]()
[]()
[]()
## โจ Features
- **๐๏ธ Streaming Compression**: Process datasets larger than RAM
- **๐ฆ Quantization**: Reduce size by 75-90% with minimal accuracy loss
- **โก Fast Search**: Parallel cosine similarity with optimized indexing
- **๐ Benchmarking**: Criterion integration with HTML reports and delta tracking
- **๐ Multiple Formats**: STREAM1 (f32) and QSTREAM1 (u8 quantized)
- **๐จ Beautiful CLI**: Progress bars, colored output, and streaming logs
## ๐ฌ Quick Demo
```bash
# Clone and run the interactive demo
git clone https://github.com/yourorg/vectro-plus
cd vectro-plus
./demo.sh
```
**What you'll see:**
```
๐ Vectro+ Interactive Demo
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Step 1: Creating sample embeddings...
โ Created 10 sample embeddings (5 dimensions each)
Step 2: Compressing to binary format...
โ compressing (streaming bincode)...
โ Compressed: dataset.bin (245 bytes)
Step 3: Compressing with quantization...
โ parsing and computing quant tables...
โ Compressed: dataset_q.bin (67 bytes)
๐พ Space savings: 73%
Step 4: Testing semantic search...
Query: Search for 'apple' (0.9, 0.1, 0.2, 0.3, 0.4)
1. apple -> 1.000000
2. orange -> 0.987234
3. banana -> 0.956789
```
## ๐ฆ Installation
```bash
# Clone the repository
git clone https://github.com/yourorg/vectro-plus
cd vectro-plus
# Build (release mode for performance)
cargo build --release
# Run tests
cargo test --workspace
# Run benchmarks
cargo bench -p vectro_lib
```
## ๐ฏ Usage Examples
### Compress Embeddings
```bash
# Regular streaming format
vectro compress embeddings.jsonl dataset.bin
# With quantization (75%+ smaller)
vectro compress embeddings.jsonl dataset_q.bin --quantize
```
### Search
```bash
# Find top-10 most similar vectors
vectro search "0.1,0.2,0.3,0.4,0.5" --top-k 10 --dataset dataset.bin
```
### Benchmarks
```bash
# Run with summary and HTML report
vectro bench --summary --open-report
# Run specific benchmarks
vectro bench --bench-args "--bench cosine"
# Save report for sharing
vectro bench --save-report ./reports --summary
```
## ๐ Benchmark Output Example
```
Benchmark summaries:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโฌโโโโโโโโโโโโโฌโโโโโโโฌโโโโโโโโโ
โ benchmark โ median โ mean โ unit โ delta โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโผโโโโโโโโโค
โ cosine_search/top_k_10 โ 123.456 โ 125.789 โ ns โ -2.3% โ
โ cosine_search/top_k_100 โ 1234.567 โ 1256.890 โ ns โ +1.8% โ
โ quantize/dataset_1000 โ 45678.901 โ 46789.012 โ ns โ - โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโโดโโโโโโโดโโโโโโโโโ
๐ HTML summary saved to: target/criterion/vectro_summary.html
```
## ๐๏ธ Architecture
```
vectro-plus/
โโโ vectro_lib/ # Core library (embeddings, search, quantization)
โ โโโ src/
โ โ โโโ lib.rs # Embedding, Dataset, SearchIndex, QuantizedIndex
โ โโโ benches/ # Criterion benchmarks
โโโ vectro_cli/ # CLI application
โ โโโ src/
โ โ โโโ lib.rs # compress_stream() with parallel pipeline
โ โ โโโ main.rs # CLI: compress, search, bench, serve
โ โโโ tests/ # Integration tests
โโโ DEMO.md # Comprehensive usage examples
โโโ QSTREAM.md # Binary format documentation
โโโ demo.sh # Interactive demo script
```
## ๐ฌ Performance
| Dataset | Size | Compress | Quantize | Search (top-10) | Search (top-100) |
|---------|------|----------|----------|-----------------|------------------|
| 10K ร 128d | 5 MB | 180ms | 220ms | 45ฮผs | 420ฮผs |
| 100K ร 768d | 300 MB | 3.2s | 4.1s | 123ฮผs | 1.2ms |
| 1M ร 768d | 3 GB | 34s | 43s | 156ฮผs | 1.8ms |
*Benchmarked on M1 Max (10-core), parallel workers enabled*
## ๐ Format Documentation
### STREAM1 (Regular)
```
Header: "VECTRO+STREAM1\n"
Records: [u32 length][bincode(Embedding)] ร N
```
### QSTREAM1 (Quantized)
```
Header: "VECTRO+QSTREAM1\n"
Tables: [u32 count][u32 dim][u32 len][bincode(Vec)]
Records: [u32 length][bincode((id, Vec))] ร N
```
See [QSTREAM.md](./QSTREAM.md) for complete specification.
## ๐งช Testing
```bash
# All tests
cargo test --workspace
# Specific crate
cargo test -p vectro_lib
cargo test -p vectro_cli
# Integration tests
cargo test -p vectro_cli --test integration_quantize
# With output
cargo test -- --nocapture
```
## ๐ค Contributing
Contributions welcome! Please:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing`)
3. Add tests for new functionality
4. Run `cargo fmt` and `cargo clippy`
5. Submit a PR
## ๐ Resources
- [DEMO.md](./DEMO.md) - Comprehensive examples and tutorials
- [QSTREAM.md](./QSTREAM.md) - Binary format specification
- [Criterion Reports](./target/criterion/) - Detailed benchmark results (after running benches)
## ๐ License
MIT License - see [LICENSE](./LICENSE) for details
## ๐ Acknowledgments
Built with:
- [Rust](https://www.rust-lang.org/) - Systems programming language
- [Criterion](https://github.com/bheisler/criterion.rs) - Statistical benchmarking
- [Rayon](https://github.com/rayon-rs/rayon) - Data parallelism
- [Bincode](https://github.com/bincode-org/bincode) - Binary serialization
- [Clap](https://github.com/clap-rs/clap) - Command-line parsing
---
**Ready to optimize your embeddings?** Run `./demo.sh` to get started! ๐
This repository contains a workspace with two crates:
- `vectro_lib` โ core library
- `vectro_cli` โ command-line tool
See `docs/architecture.md` for design notes.