next-plaid 0.1.0

CPU-based PLAID implementation for multi-vector search using ndarray
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# next-plaid

A CPU-based Rust implementation of the PLAID algorithm for efficient multi-vector search (late interaction retrieval).

[![Crates.io](https://img.shields.io/crates/v/next-plaid.svg)](https://crates.io/crates/next-plaid)
[![Documentation](https://docs.rs/next-plaid/badge.svg)](https://docs.rs/next-plaid)
[![License](https://img.shields.io/crates/l/next-plaid.svg)](https://github.com/lightonai/next-plaid/blob/main/LICENSE)

## Features

- **Pure Rust**: No Python or GPU dependencies required
- **CPU Optimized**: Uses ndarray with rayon for parallel processing
- **BLAS Acceleration**: Optional Accelerate (macOS) or OpenBLAS backends for 3.6x faster indexing
- **Metadata Filtering**: Optional SQLite-based metadata storage for filtered search

## Installation

```toml
[dependencies]
next-plaid = "0.1"
```

For NPY file support (required for index persistence):

```toml
[dependencies]
next-plaid = { version = "0.1", features = ["npy"] }
```

### BLAS Acceleration (Recommended)

**macOS (Apple Accelerate framework):**

```toml
[dependencies]
next-plaid = { version = "0.1", features = ["npy", "accelerate"] }
```

**Linux (OpenBLAS):**

```toml
[dependencies]
next-plaid = { version = "0.1", features = ["npy", "openblas"] }
```

Note: OpenBLAS requires the system library (`apt install libopenblas-dev` on Ubuntu).

### Metadata Filtering (Optional)

```toml
[dependencies]
next-plaid = { version = "0.1", features = ["npy", "filtering"] }
```

## Quick Start

### Creating an Index

```rust
use next_plaid::{Index, IndexConfig};
use ndarray::Array2;

// Your document embeddings (list of [num_tokens, dim] arrays)
let embeddings: Vec<Array2<f32>> = load_embeddings();

// Create index with automatic centroid computation
let config = IndexConfig::default();
let index = Index::create_with_kmeans(&embeddings, "path/to/index", &config)?;
```

### Searching

```rust
use next_plaid::{Index, SearchParameters};

// Load the index
let index = Index::load("path/to/index")?;

// Search parameters
let params = SearchParameters {
    batch_size: 128,
    n_full_scores: 1024,
    top_k: 10,
    n_ivf_probe: 32,
};

// Single query
let query: Array2<f32> = get_query_embeddings();
let result = index.search(&query, &params, None)?;

println!("Top results: {:?}", result.passage_ids);
println!("Scores: {:?}", result.scores);
```

### Filtered Search with Metadata

```rust
use next_plaid::{Index, SearchParameters, filtering};
use serde_json::json;

// Create metadata database
let metadata = vec![
    json!({"title": "Doc 1", "category": "science", "year": 2023}),
    json!({"title": "Doc 2", "category": "history", "year": 2022}),
];
filtering::create("path/to/index", &metadata)?;

// Query metadata to get document subset
let subset = filtering::where_condition(
    "path/to/index",
    "category = ? AND year >= ?",
    &[json!("science"), json!(2023)],
)?;

// Search only within the filtered subset
let result = index.search(&query, &params, Some(&subset))?;
```

## Performance

### SciFact Benchmark (5,183 documents, 1.2M tokens)

| Operation | next-plaid | FastPlaid | Speedup |
|-----------|------------|-----------|---------|
| Index + Update | **12.19s** | 19.46s | **1.60x faster** |
| Search (300 queries) | **16.38s** | 85.85s | **5.2x faster** |
| **Total** | **28.57s** | 105.31s | **3.7x faster** |

### Memory Usage

| Operation | next-plaid | FastPlaid | Savings |
|-----------|------------|-----------|---------|
| **Peak** | **480 MB** | 3,361 MB | **86% less** |

## Feature Flags

| Feature | Description |
|---------|-------------|
| `npy` | NPY file support for index persistence |
| `filtering` | SQLite-based metadata filtering |
| `accelerate` | macOS Accelerate framework for BLAS |
| `openblas` | OpenBLAS for BLAS acceleration |

## License

Apache-2.0