Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat: add cuVS vector search backend (#2974)

Yuanqing ZHAO39c778c953f5
diff --git a/benchmark/cuvs/PRELIMINARY_RESULTS.md b/benchmark/cuvs/PRELIMINARY_RESULTS.md
new file mode 100644
index 000000000..0373ca011
--- /dev/null
+++ b/benchmark/cuvs/PRELIMINARY_RESULTS.md
@@ -0,0 +1,479 @@
+# Preliminary cuVS index results
+
+These results are an engineering checkpoint for the OpenViking cuVS
+integration. They are not a final performance claim. The measurements use one
+GPU, one public ANN dataset, and deterministic synthetic vectors for exact
+high-dimensional scaling. Every reported row aggregates five independent
+processes as median +/- median absolute deviation (MAD).
+
+## Public-dataset setup
+
+- Harness revision: `5dbc6a570404c9d1e2c8b584f6447919d0fee62a`
+- Dataset: [ann-benchmarks](https://github.com/erikbern/ann-benchmarks)
+ `glove-100-angular`
+- Source SHA-256:
+ `544af1d5e84e112cd4749571dcfd8ca109818a572f850af75a3a09e093a953c4`
+- Base vectors: 1,183,514 x 100D float32
+- Queries: 10,000; K=10; cosine ranking via normalized inner product
+- Ground truth: exact neighbors supplied by ann-benchmarks
+- GPU: NVIDIA H20
+- Software: cuVS 26.06, CuPy 14.1.1, CUDA runtime 12.9
+
+The native backend is the existing OpenViking CPU flat-index call path. In
+this document, **cuVS GPU exact** specifically means cuVS brute-force on the
+GPU. It does not mean CAGRA. CAGRA is the approximate GPU index and uses
+`graph_degree=64` and `intermediate_graph_degree=128` for the high-recall
+results. Each public-dataset process times all 10,000 queries after ten
+warm-up batches.
+
+The index-only harness uses float32 for both native and cuVS exact search. The
+collection and service sections intentionally preserve normal application
+behavior instead: native keeps its default per-vector-scale int8 index and
+cuVS keeps a float32 GPU shadow. Opting into cuVS does not rewrite the native
+index. Those later sections are therefore not equal-dtype or equal-memory
+comparisons and report native Recall@K against cuVS brute-force.
+
+## GPU memory footprint
+
+The current cuVS shadow stores float32 vectors. The brute-force payload is
+therefore `N * dimension * 4` bytes. CAGRA also retains a uint32 neighbor graph
+of approximately `N * graph_degree * 4` bytes and may require an intermediate
+graph during build. A cached filter bitset adds approximately `N / 8` bytes.
+
+The harness records `cudaMemGetInfo` immediately before and after index build.
+The following retained-build deltas are medians from five clean processes:
+
+| Dataset | Backend | GPU memory delta |
+| --- | --- | ---: |
+| 100K x 768D synthetic | cuVS brute-force | 294 MiB |
+| 1M x 768D synthetic | cuVS brute-force | 2.9 GiB |
+| 100K x 1024D synthetic | cuVS brute-force | 392 MiB |
+| 1M x 1024D synthetic | cuVS brute-force | 3.9 GiB |
+| 1,183,514 x 100D GloVe | cuVS brute-force | 452 MiB |
+| 1,183,514 x 100D GloVe | cuVS CAGRA | 872 MiB |
+
+These are not peak-VRAM measurements. Allocator state, CAGRA build parameters,
+query batch size, and concurrent GPU use can add transient memory. The deltas
+also exclude the approximately 327 MiB CUDA runtime/context baseline observed
+before build in these processes. The opt-in memory-aware auto mode initializes
+that runtime first, then estimates the float32 payload, CAGRA retained and
+intermediate graphs, and filter cache; multiplies the result by a 2.0 default
+safety factor; and preserves 1 GiB of free memory. Insufficient budget keeps
+the native path for that query and allows a later retry.
+
+## Batch size 1
+
+This is the closest index-level approximation of the current OpenViking
+single-query integration. It includes Python dispatch, host-to-device query
+copy, GPU execution, and result copy back to host. It excludes embedding,
+HTTP, record lookup, reranking, and LLM work.
+
+| Backend | Recall@10 | warm p50 (ms/query) | warm p95 (ms/query) | warm QPS |
+| --- | ---: | ---: | ---: | ---: |
+| OpenViking native exact | 1.0000 +/- 0.0000 | 40.209 +/- 0.071 | 40.798 +/- 0.043 | 24.7 +/- 0.1 |
+| cuVS GPU brute-force exact | 1.0000 +/- 0.0000 | 0.796 +/- 0.005 | 0.815 +/- 0.005 | 1,254.5 +/- 7.1 |
+| cuVS CAGRA ANN, `itopk_size=512` | 0.9633 +/- 0.0003 | 1.730 +/- 0.016 | 1.995 +/- 0.008 | 562.8 +/- 1.7 |
+| cuVS CAGRA ANN, `itopk_size=2048` | 0.9944 +/- 0.0002 | 1.797 +/- 0.019 | 2.036 +/- 0.006 | 549.0 +/- 0.9 |
+
+In this low-batch regime, cuVS GPU brute-force exact delivers a 50.5x median
+warm-p50 speedup and 50.7x higher median QPS than the current native CPU exact
+call path. CAGRA is slower than GPU brute-force exact even before requiring
+0.99 recall, so CAGRA should not be selected for this dataset and query shape
+solely because it is approximate.
+
+Before warm-up, the first batch=1 search was 85.7 +/- 9.6 ms for native exact
+and 104.0 +/- 2.9 ms for cuVS GPU brute-force exact. The observed ranges were
+76.2--122.9 ms and 101.1--157.3 ms, respectively. Cold-start latency therefore
+remains a separate integration concern; the warm comparison above must not be
+read as startup latency.
+
+## Batch size 128
+
+This measures vector-index throughput capacity. It is not current OpenViking
+server throughput because the integration currently submits one query at a
+time.
+
+| Backend | Recall@10 | QPS | Relative to GPU exact |
+| --- | ---: | ---: | ---: |
+| cuVS GPU brute-force exact | 1.0000 +/- 0.0000 | 35,495 +/- 34 | 1.00x |
+| cuVS CAGRA ANN, `itopk_size=512` | 0.9628 +/- 0.0004 | 43,595 +/- 280 | 1.23x |
+| cuVS CAGRA ANN, `itopk_size=2048` | 0.9943 +/- 0.0002 | 21,711 +/- 79 | 0.61x |
+
+CAGRA shows a throughput benefit only at the lower recall point in this
+initial run. At approximately 0.99 recall, GPU exact remains faster.
+
+## High-dimensional exact scaling
+
+To approximate common embedding dimensions without making unsupported ANN
+quality claims, this matrix uses deterministic normalized Gaussian vectors and
+compares only the two exact paths. The batch=1 crossover runs time 1,000
+queries per process through 10K vectors and 200 queries per process at 100K
+and 1M vectors. All rows have Recall@10=1.0.
+
+The speedup column is native warm p50 divided by cuVS GPU brute-force warm
+p50. Values above 1.0 mean GPU exact is faster.
+
+| Dim | Vectors | Native p50 (ms) | GPU exact p50 (ms) | Speedup |
+| ---: | ---: | ---: | ---: | ---: |
+| 768 | 100 | 0.031 +/- 0.000 | 0.243 +/- 0.003 | 0.13x |
+| 768 | 1K | 0.122 +/- 0.001 | 0.248 +/- 0.001 | 0.49x |
+| 768 | 2K | 0.219 +/- 0.001 | 0.249 +/- 0.000 | 0.88x |
+| 768 | 5K | 0.487 +/- 0.013 | 0.245 +/- 0.002 | 1.99x |
+| 768 | 10K | 0.915 +/- 0.014 | 0.248 +/- 0.001 | 3.69x |
+| 768 | 100K | 21.991 +/- 0.177 | 0.341 +/- 0.003 | 64.5x |
+| 768 | 1M | 229.728 +/- 0.580 | 1.435 +/- 0.002 | 160.1x |
+| 1024 | 100 | 0.039 +/- 0.000 | 0.244 +/- 0.002 | 0.16x |
+| 1024 | 1K | 0.159 +/- 0.005 | 0.247 +/- 0.001 | 0.64x |
+| 1024 | 2K | 0.285 +/- 0.002 | 0.250 +/- 0.002 | 1.14x |
+| 1024 | 5K | 0.633 +/- 0.000 | 0.253 +/- 0.004 | 2.50x |
+| 1024 | 10K | 1.234 +/- 0.048 | 0.252 +/- 0.001 | 4.90x |
+| 1024 | 100K | 28.443 +/- 0.262 | 0.376 +/- 0.001 | 75.7x |
+| 1024 | 1M | 306.730 +/- 0.838 | 1.708 +/- 0.002 | 179.6x |
+
+On this integration path, native CPU exact remains faster through 2K vectors
+at 768D, while GPU exact is faster by 5K. At 1024D, the observed crossover is
+between 1K and 2K vectors. These are hardware- and implementation-specific
+boundaries, not universal algorithm thresholds.
+
+This is a warm crossover. The first cuVS search remained approximately
+99--110 ms across the synthetic shapes, while native first-search latency was
+below 1 ms at 2K vectors and below. Short-lived or rarely queried collections
+therefore need a separate residency/cold-start policy even when their warm
+vector count is above the crossover.
+
+For a stable GPU capacity measurement, batch=128 runs use 50 search
+repetitions, or 10,000 timed queries per process:
+
+| Dim | Vectors | cuVS GPU exact QPS |
+| ---: | ---: | ---: |
+| 768 | 100K | 67,650 +/- 160 |
+| 768 | 1M | 12,479 +/- 2 |
+| 1024 | 100K | 57,385 +/- 10 |
+| 1024 | 1M | 9,880 +/- 0.3 |
+
+These capacity numbers do not represent current OpenViking server throughput;
+the integration still submits one query at a time.
+
+## Build scope
+
+| Backend | Build time (s) | Scope |
+| --- | ---: | --- |
+| OpenViking native exact | 10.537 +/- 0.099 | Python `DeltaRecord` creation plus native upsert |
+| cuVS GPU brute-force exact | 0.219 +/- 0.001 | host-to-device matrix copy plus index wrapper |
+| cuVS CAGRA high-recall graph | 4.719 +/- 0.085 | matrix copy plus graph construction |
+
+These build times do not isolate equivalent kernels. In particular, the native
+path includes the current row-oriented OpenViking ingestion interface while
+the cuVS paths accept the full matrix. They should be treated as integration
+costs, not as a pure CPU-versus-GPU algorithm comparison.
+
+The same caveat applies to high-dimensional exact build time and GPU-memory
+delta:
+
+| Dim | Vectors | Native build (s) | GPU exact build (s) | GPU delta (GiB) |
+| ---: | ---: | ---: | ---: | ---: |
+| 768 | 100K | 4.488 +/- 0.029 | 0.203 +/- 0.000 | 0.29 |
+| 768 | 1M | 44.294 +/- 0.146 | 1.597 +/- 0.006 | 2.87 |
+| 1024 | 100K | 6.165 +/- 0.030 | 0.210 +/- 0.001 | 0.38 |
+| 1024 | 1M | 60.990 +/- 0.281 | 1.697 +/- 0.011 | 3.82 |
+
+## Collection adapter, filter, and lifecycle
+
+This matrix moves one level above the index microbenchmark. It calls
+`CollectionAdapter.query()` and therefore includes OpenViking filter handling,
+label-to-record lookup, result normalization, persistence, and lazy index
+rebuild. The initial uncached-filter run uses revision
+`84f79c5f52b553561299d42730949b612f3fe29c`; the prepared-filter-cache follow-up
+uses revision `087f2a280dc06031665a0bbdb1ef26a9fa2735da`. Each result aggregates
+five independent processes on the same H20/software setup as the exact-scaling
+runs.
+
+- Dataset: 100,000 deterministic normalized Gaussian vectors, 768D float32
+- Queries: 50 per scenario; K=10; three warm-up queries
+- Filters: 10%, 1%, and 0.1% target selectivity, with both uniformly
+ distributed and contiguous matching records
+- Mutations: upsert 1, 100, 1,000, and 10,000 records; delete 100 records;
+ close and reopen the persistent collection
+
+This comparison deliberately uses the normal collection defaults. The native
+flat index uses its default int8 quantization, while cuVS brute-force retains
+float32 vectors. Consequently, the native path is not the float exact baseline
+from the index microbenchmark. Its Recall@10 against cuVS GPU brute-force was
+0.982 without a filter and 0.978--0.994 with filters. This is both a quality
+and memory semantic that the integration must make explicit.
+
+### Initial uncached-filter result
+
+| Scenario | Native p50 (ms) | cuVS p50 (ms) | Native Recall@10 | cuVS Recall@10 | Relative p50 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Unfiltered | 9.413 +/- 0.238 | 0.970 +/- 0.006 | 0.982 | 1.000 | cuVS 9.7x faster |
+| Uniform 10% | 1.871 +/- 0.041 | 106.306 +/- 2.204 | 0.988 | 1.000 | cuVS 56.8x slower |
+| Uniform 1% | 0.509 +/- 0.003 | 105.816 +/- 2.022 | 0.986 | 1.000 | cuVS 207.8x slower |
+| Uniform 0.1% | 0.319 +/- 0.002 | 105.292 +/- 2.721 | 0.994 | 1.000 | cuVS 330.2x slower |
+| Clustered 10% | 1.374 +/- 0.002 | 106.706 +/- 1.297 | 0.978 | 1.000 | cuVS 77.7x slower |
+| Clustered 1% | 0.468 +/- 0.001 | 104.634 +/- 1.308 | 0.982 | 1.000 | cuVS 223.3x slower |
+| Clustered 0.1% | 0.321 +/- 0.004 | 104.219 +/- 1.748 | 0.994 | 1.000 | cuVS 324.9x slower |
+
+Unfiltered collection lookup preserves a material GPU benefit: median QPS was
+967.3 +/- 2.5 for cuVS and 106.4 +/- 3.4 for native, a 9.1x throughput ratio.
+That is smaller than the index-only 100K x 768D result because collection
+lookup adds fixed host-side work and the native collection path uses int8
+quantization.
+
+The initial filtered result identified an integration blocker, not an inherent
+cuVS limitation. That revision evaluated the predicate against every Python
+record and rebuilt the GPU prefilter mask on every query. All six cuVS filter
+scenarios remained near 104--106 ms regardless of selectivity or record
+distribution.
+
+### Prepared-filter-cache follow-up
+
+The follow-up adds a bounded LRU of prepared GPU bitsets and invalidates it on
+upsert or delete. The first query for each new filter still performs the host
+predicate scan; subsequent searches with the same filter reuse the device
+bitset.
+
+| Scenario | First cuVS query (ms) | Cached cuVS p50 (ms) | Native p50 (ms) | Cached relative p50 |
+| --- | ---: | ---: | ---: | ---: |
+| Uniform 10% | 141.022 +/- 1.248 | 1.077 +/- 0.014 | 1.832 +/- 0.066 | cuVS 1.70x faster |
+| Uniform 1% | 133.535 +/- 0.772 | 0.989 +/- 0.011 | 0.520 +/- 0.002 | cuVS 1.90x slower |
+| Uniform 0.1% | 123.198 +/- 0.699 | 0.948 +/- 0.002 | 0.330 +/- 0.003 | cuVS 2.88x slower |
+| Clustered 10% | 121.070 +/- 0.637 | 1.090 +/- 0.003 | 1.389 +/- 0.011 | cuVS 1.27x faster |
+| Clustered 1% | 119.758 +/- 1.763 | 0.987 +/- 0.004 | 0.470 +/- 0.003 | cuVS 2.10x slower |
+| Clustered 0.1% | 119.441 +/- 1.175 | 0.960 +/- 0.006 | 0.325 +/- 0.002 | cuVS 2.95x slower |
+
+Repeated-filter cuVS p50 improves by 97.9--111.0x over the uncached revision.
+The 10% scenarios now favor cuVS, while the native scalar index remains faster
+for 1% and 0.1% selectivity. Unfiltered p50 on the follow-up was 0.965 +/- 0.019
+ms for cuVS and 8.643 +/- 0.151 ms for native, an approximately 9.0x ratio.
+
+The cache addresses repeated filters but not first-use or high-cardinality
+filters: a new predicate still costs approximately 119--141 ms at 100K records.
+Reusing OpenViking's scalar-index candidate labels is still worth evaluating
+for those cases. The cache's configured size is 16 prepared filters, and data
+mutation clears it before rebuilding the dense index.
+
+### Native bitmap bridge and auto-routing follow-up
+
+The next follow-up removes that Python predicate scan. Each GPU rebuild now
+registers its label order with the native engine once. A new filter is evaluated
+by OpenViking's existing scalar/path index and projected through the registered
+native-offset layout into a cuVS-row bitset. Repeated filters retain the device
+bitset; mutations invalidate both the layout and filter cache.
+
+Auto mode also caches a routing decision. The measured defaults send scalar
+filters with at most 2,000 candidates to native vector recall, keep wider scalar
+filters on cuVS, and use a lower 200-candidate threshold for URI filters. The
+lower URI threshold avoids repeatedly paying native Trie/subtree-bitmap work for
+medium-sized path scopes. Both thresholds are configurable and apply only to
+auto mode; explicit `backend=cuvs` continues to use the GPU dense path.
+
+The following values aggregate five independent processes over the same 100K x
+768D, 50-query collection workload. The URI rows add unique hierarchical paths
+whose prefixes select 10%, 1%, and 0.1% of records.
+
+| Scenario | First query (ms) | Auto warm p50 (ms) | Route |
+| --- | ---: | ---: | --- |
+| Unfiltered | 1,902.930 +/- 6.045 | 0.972 +/- 0.015 | cuVS; first query includes lazy GPU build |
+| Uniform scalar 10% | 2.984 +/- 0.034 | 1.119 +/- 0.029 | cuVS |
+| Uniform scalar 1% | 2.096 +/- 0.019 | 0.643 +/- 0.018 | native |
+| Uniform scalar 0.1% | 1.486 +/- 0.014 | 0.404 +/- 0.009 | native |
+| Clustered scalar 10% | 1.853 +/- 0.012 | 1.133 +/- 0.018 | cuVS |
+| Clustered scalar 1% | 1.994 +/- 0.061 | 0.578 +/- 0.006 | native |
+| Clustered scalar 0.1% | 1.384 +/- 0.020 | 0.399 +/- 0.002 | native |
+| URI path 10% | 12.860 +/- 0.569 | 1.126 +/- 0.024 | cuVS |
+| URI path 1% | 3.087 +/- 0.031 | 1.020 +/- 0.027 | cuVS |
+| URI path 0.1% | 1.635 +/- 0.014 | 0.455 +/- 0.010 | native |
+
+For the six scalar rows, first-use latency is now 1.38--2.98 ms instead of the
+previous 119--141 ms, a 47--86x reduction. Cached 10% filters retain the GPU
+advantage, while 1% and 0.1% scalar filters recover the native candidate-pruning
+advantage. URI first-use cost depends on subtree width: the 10% prefix still
+spends about 12.9 ms traversing and unioning the native path bitmaps, but that
+work is avoided after its cuVS bitset is cached. The 1% URI case remains on GPU
+because repeatedly rebuilding its native path bitmap was slower than cached
+cuVS search; only the 0.1% URI case crosses the more conservative path threshold.
+
+These auto-mode rows can execute over either the native int8 representation or
+the cuVS float32 representation. They are latency-routing results, not an
+equal-dtype comparison; applications requiring one fixed numerical
+representation should select an explicit backend or disable the native-routing
+thresholds.
+
+### Dirty-index selective-first follow-up
+
+Review of the auto-routing path found that the first implementation decided
+`route_native` only after `_rebuild_if_needed()`. Results remained correct, but
+a selective filtered query could still pay the full GPU rebuild before falling
+back to native. Revision `d2a74c1af026da0a482955ed2498c03f5f44654c`
+moves native filter resolution and the candidate-count decision before GPU
+memory admission and rebuild.
+
+A targeted follow-up runs a 0.1% scalar filter as the first query while the
+100K x 768D auto index is dirty. Five independent clean processes produced:
+
+| Metric | Median +/- MAD |
+| --- | ---: |
+| Selective-first query latency | 11.670 +/- 0.156 ms |
+| Selective-first GPU-memory delta | 0 +/- 0 bytes |
+| Subsequent unfiltered first query | 1,889.281 +/- 11.155 ms |
+| Unfiltered query after a one-record mutation | 1,632.840 +/- 81.424 ms |
+
+All five selective-first runs recorded exactly zero GPU-memory delta. The
+following unfiltered query still paid the lazy build, demonstrating that the
+native route neither allocated the GPU dataset nor accidentally cleared dirty
+state. The 11.7 ms selective-first value is higher than a new filter on an
+already-built index because it includes one-time registration of the current
+100K-label native-to-cuVS layout. It nevertheless avoids roughly 1.9 seconds
+of unnecessary GPU construction for this query shape.
+
+### Ingestion, mutation, and restart
+
+| Operation | Native median | cuVS median |
+| --- | ---: | ---: |
+| Ingest 100K records | 29.849 s | 38.545 s |
+| First unfiltered query after ingest | 23.108 ms | 1,811.843 ms |
+| Upsert 1: next query | 12.167 ms | 1,410.397 ms |
+| Upsert 100: next query | 12.835 ms | 1,402.790 ms |
+| Upsert 1K: next query | 13.915 ms | 1,438.549 ms |
+| Upsert 10K: next query | 14.578 ms | 1,535.870 ms |
+| Delete 100: next query | 13.574 ms | 1,405.846 ms |
+| First query after close/reopen | 5.338 s | 15.315 s |
+| Warm query after reopen | 10.551 ms | 1.118 ms |
+
+Every cuVS mutation marks the index dirty, and the next query synchronously
+rebuilds the full 100K-vector GPU index. The rebuild cost is therefore almost
+independent of whether one or 10,000 records were updated. The write API itself
+remains comparatively cheap; the cost is shifted onto the next reader. A
+production integration should rebuild in the background, coalesce mutations,
+and atomically swap the completed index while the prior snapshot continues to
+serve queries.
+
+Persistent collection loading is lazy, so the reopen time appears in the
+first query rather than adapter construction. The cuVS first query includes
+store recovery, rebuilding Python-side records, and building the GPU index.
+After that work, the reopened cuVS collection returns to approximately 1.1 ms.
+
+Median host RSS increase during ingestion was 0.93 GiB for native and 2.71 GiB
+for cuVS; cuVS additionally used a 0.29 GiB GPU-memory delta after search. The
+cuVS host overhead is dominated by the current per-vector Python tuple mirror.
+These RSS deltas are directional rather than an allocator-isolated memory
+benchmark because both backends run sequentially in each process.
+
+## Async service-facade concurrency
+
+This level calls `VikingVectorIndexBackend.query()` through OpenViking's normal
+`asyncio.to_thread` boundary. It includes tenant-filter injection and async
+request scheduling, but deliberately uses precomputed query vectors: HTTP,
+authentication, embedding, reranking, and LLM work are still excluded.
+
+- Harness revision: `e7af4e0c26c82eb58dbb47c07dcaa54b402fbaab`
+- Dataset: 100,000 normalized Gaussian vectors, 768D; K=10
+- Concurrency: 1, 4, 16, 32, and 64; default thread-pool limit 32
+- Cached scenarios: 200 requests per concurrency level
+- New-filter scenario: 32 requests per concurrency level, each with a distinct
+ 100-record range in addition to the automatic tenant filter
+- Post-mutation scenario: one full-record upsert, followed by a simultaneous
+ read burst whose size equals the concurrency level
+
+Results aggregate five independent clean processes on H20. Values written with
+`+/-` include median absolute deviation; the compact paired-latency tables show
+process medians where dispersion is omitted. The native collection continues
+to use its default int8 vector quantization, while cuVS brute-force retains
+float32 vectors.
+
+### Cached tenant filter
+
+Every service-facade request is automatically scoped by `account_id`; this
+scenario warms and reuses that prepared filter.
+
+| Concurrency | Native p50 (ms) | Native QPS | cuVS p50 (ms) | cuVS p99 (ms) | cuVS QPS | cuVS/native QPS |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 1 | 14.136 +/- 0.066 | 71.3 +/- 2.3 | 1.492 +/- 0.011 | 2.175 +/- 0.030 | 614.8 +/- 8.2 | 8.63x |
+| 4 | 16.311 +/- 0.177 | 238.0 +/- 1.7 | 6.094 +/- 0.027 | 9.912 +/- 0.176 | 632.6 +/- 5.1 | 2.66x |
+| 16 | 16.504 +/- 0.240 | 907.8 +/- 25.1 | 24.820 +/- 0.084 | 29.885 +/- 1.351 | 636.0 +/- 3.9 | 0.70x |
+| 32 | 30.050 +/- 1.618 | 982.7 +/- 21.8 | 47.998 +/- 0.585 | 54.204 +/- 0.330 | 651.8 +/- 6.8 | 0.66x |
+| 64 | 54.251 +/- 1.059 | 1,056.8 +/- 4.6 | 92.641 +/- 0.531 | 99.232 +/- 1.133 | 677.2 +/- 7.0 | 0.64x |
+
+cuVS keeps a strong low-concurrency advantage, but its throughput remains near
+615--677 QPS as concurrency increases. Native CPU search scales across the
+thread pool and crosses cuVS between concurrency 4 and 16. cuVS p50 rises from
+1.5 ms to 92.6 ms at concurrency 64 because requests queue behind the current
+index-wide lock; this integration does not yet use concurrent CUDA streams or
+micro-batching.
+
+### Cached 10% filter
+
+| Concurrency | Native p50 (ms) | Native QPS | cuVS p50 (ms) | cuVS QPS | cuVS/native QPS |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 1 | 2.452 +/- 0.011 | 385.5 +/- 3.5 | 1.564 +/- 0.006 | 582.7 +/- 10.5 | 1.51x |
+| 4 | 2.937 +/- 0.038 | 1,165.6 +/- 14.7 | 6.473 +/- 0.091 | 591.6 +/- 5.4 | 0.51x |
+| 16 | 12.860 +/- 0.227 | 1,151.7 +/- 7.0 | 27.400 +/- 0.257 | 576.0 +/- 5.7 | 0.50x |
+| 64 | 48.681 +/- 0.502 | 1,215.1 +/- 19.6 | 103.497 +/- 0.930 | 604.3 +/- 4.1 | 0.50x |
+
+The more selective native scalar path crosses cuVS between concurrency 1 and
+4. Prepared-mask reuse removes predicate construction from this scenario, so
+the remaining cuVS plateau is the search serialization and service overhead.
+
+### New filter per request
+
+| Concurrency | Native p50 / p99 (ms) | Native QPS | cuVS p50 / p99 (ms) | cuVS QPS |
+| ---: | ---: | ---: | ---: | ---: |
+| 1 | 0.807 / 2.939 | 1,034.6 | 280.607 / 308.068 | 3.5 |
+| 4 | 3.088 / 5.848 | 1,132.7 | 1,104.427 / 1,159.414 | 3.6 |
+| 16 | 12.009 / 19.690 | 1,104.6 | 4,365.132 / 4,429.893 | 3.6 |
+| 32 | 20.632 / 27.288 | 1,133.0 | 4,581.936 / 8,734.404 | 3.6 |
+
+The native scalar index resolves each distinct 100-record range efficiently.
+cuVS still scans all host-side records for every LRU miss, and the index lock
+serializes those scans. At concurrency 32, half the requests complete around
+4.6 seconds while the tail approaches 8.7 seconds. The concurrency-64 case is
+not separately reported because this scenario has only 32 total requests.
+
+### Read burst after one mutation
+
+| Concurrency | Native p50 / p99 (ms) | cuVS p50 / p99 (ms) | cuVS burst wall time (s) |
+| ---: | ---: | ---: | ---: |
+| 1 | 21.467 / 21.467 | 1,827.384 / 1,827.384 | 1.828 +/- 0.170 |
+| 4 | 23.436 / 23.860 | 1,563.884 / 1,565.954 | 1.566 +/- 0.008 |
+| 16 | 24.621 / 28.031 | 1,701.266 / 1,711.689 | 1.712 +/- 0.118 |
+| 32 | 36.285 / 40.417 | 1,612.954 / 1,633.418 | 1.635 +/- 0.046 |
+| 64 | 49.734 / 69.858 | 1,849.853 / 1,894.171 | 1.896 +/- 0.022 |
+
+The cuVS write call itself takes only approximately 3.0--3.6 ms; the next
+reader rebuilds the full index while every concurrent reader waits on the same
+lock. Higher apparent burst QPS is therefore not steady-state capacity: it is
+the same rebuild delay amortized across more requests released together.
+
+## Current conclusion and next checks
+
+1. Native CPU exact remains preferable for very small collections. On this
+ setup, cuVS GPU brute-force exact crosses over between 2K--5K vectors at
+ 768D and 1K--2K vectors at 1024D.
+2. CAGRA requires recall-matched tuning; an approximate label alone does not
+ imply better performance.
+3. CAGRA can improve batched capacity around Recall@10=0.96, but this benefit
+ requires batching that the current OpenViking integration does not expose.
+4. Collection-level unfiltered lookup retains an approximately 9.0x warm-p50
+ benefit at 100K x 768D, but native int8 versus cuVS float32 is not an
+ equal-memory or equal-quality comparison.
+5. Caching prepared filter bitsets improves repeated-filter cuVS p50 by
+ 98--111x. Repeated 10% filters now favor cuVS, while native remains
+ 1.9--3.0x faster at 1% and 0.1% selectivity. A new filter still pays a
+ 119--141 ms host scan, so scalar-index candidate reuse remains relevant.
+6. Synchronous lazy rebuild shifts approximately 1.4--1.7 seconds onto the
+ first reader after any mutation at 100K x 768D. Background snapshot rebuild
+ and atomic swap should be evaluated before enabling cuVS for write-active
+ collections.
+7. Independent process results are stable for this hardware and dataset, but
+ cross-node and cross-day variance are not yet measured.
+8. GloVe-100 and normalized Gaussian vectors are engineering datasets, not a
+ representative agent-memory corpus.
+9. At the async service facade, cuVS wins cached tenant search through
+ concurrency 4, but native crosses it by concurrency 16. The current cuVS
+ lock holds throughput near 600--680 QPS and turns concurrency into queueing
+ latency rather than GPU parallelism.
+10. The next engineering step is to evaluate a read-safe immutable snapshot
+ with concurrent searches or micro-batching, plus background rebuild. A
+ later end-to-end matrix should then add HTTP, embedding, reranking, and a
+ real agent-memory workload.
diff --git a/benchmark/cuvs/README.md b/benchmark/cuvs/README.md
new file mode 100644
index 000000000..333bf4159
--- /dev/null
+++ b/benchmark/cuvs/README.md
@@ -0,0 +1,264 @@
+# OpenViking cuVS index benchmark
+
+This benchmark compares the existing OpenViking native flat index with cuVS
+brute-force and CAGRA. It is intentionally limited to vector-index work and
+does not include embedding, HTTP, record lookup, reranking, or LLM inference.
+
+The output contains:
+
+- index build time and first-search batch/per-query latency;
+- warm p50/p95/p99 latency and QPS;
+- Recall@K against the first exact backend;
+- current process RSS and GPU-memory deltas;
+- raw per-batch latency samples and runtime metadata.
+
+GPU-memory fields are `cudaMemGetInfo` snapshots around build. The delta
+excludes the CUDA runtime/context already present in the pre-build snapshot and
+is a retained-build measurement, not a sampled peak. Report that distinction
+when using the values for capacity planning.
+
+See [PRELIMINARY_RESULTS.md](PRELIMINARY_RESULTS.md) for the first public-data
+engineering checkpoint and its limitations.
+
+## Quick smoke test
+
+Run from the repository root in the cuVS development image:
+
+```bash
+python benchmark/cuvs/run_index_benchmark.py \
+ --vector-count 10000 \
+ --dimension 128 \
+ --query-count 100 \
+ --k 10 \
+ --query-batch-size 1 \
+ --backends native,cuvs_brute_force,cuvs_cagra
+```
+
+For large query batches, use `--search-repetitions` so percentile and QPS
+statistics contain multiple timed batches without generating another base
+dataset. Neighbor/recall output is retained from the first repetition.
+
+Do not use within-process repetitions as a substitute for independent runs.
+After producing result files from separate processes, aggregate their medians
+and median absolute deviations with:
+
+```bash
+python benchmark/cuvs/summarize_index_runs.py \
+ /data/results/run-{1,2,3,4,5}.json \
+ --output /data/results/summary.json
+```
+
+The summarizer requires matching dataset metadata, parameters, and
+backend/search variants. It records input basenames rather than local paths.
+
+Large datasets are generated as NumPy memory maps. Put `--data-root` on a
+volume with enough capacity rather than in the Git worktree:
+
+```bash
+python benchmark/cuvs/run_index_benchmark.py \
+ --data-root /shared/benchmark-data/openviking-cuvs \
+ --vector-count 1000000 \
+ --dimension 1024 \
+ --query-count 1000 \
+ --k 10 \
+ --query-batch-size 1
+```
+
+The generated dataset is deterministic for a given shape, metric, and seed and
+is reused by later runs. Pass `--force-generate` to replace it.
+
+By default the harness reads the complete memory-mapped dataset once before
+timing any backend build. This removes page-cache order bias when several
+backends run in one process. Use `--no-preload-dataset` only when intentionally
+measuring cold storage reads.
+
+## Backend interpretation
+
+- `native` is OpenViking's C++ flat index and is exact within its configured
+ representation.
+- `cuvs_brute_force` is GPU exact search over its retained representation.
+- `cuvs_cagra` is approximate; the result reports Recall@K against an exact
+ backend from the same run.
+
+The index-only harness constructs the native index without an explicit
+`Quant`, so both native and cuVS brute-force use float32 there. The collection
+and async service harnesses deliberately retain normal application behavior:
+the native CPU index uses its default per-vector-scale int8 quantization while
+the cuVS GPU shadow uses float32. Enabling cuVS does not mutate the native
+index metadata. Collection/service results are therefore application-path
+comparisons, not equal-dtype or equal-memory comparisons, and must be reported
+with Recall@K and the dtype caveat.
+
+The native measurement uses the current OpenViking single-query call path; it
+is not a claim about the maximum throughput of a separately tuned,
+multi-threaded CPU ANN library. Record CPU and GPU hardware with every result
+and describe this scope when publishing comparisons.
+
+For CAGRA parameter sweeps, pass JSON objects:
+
+```bash
+python benchmark/cuvs/run_index_benchmark.py \
+ --backends cuvs_brute_force,cuvs_cagra \
+ --cagra-build-params '{"graph_degree":64,"intermediate_graph_degree":96}' \
+ --cagra-search-params '{"itopk_size":128}'
+```
+
+To scan the main CAGRA search-quality knob without rebuilding the graph for
+every value, use `--cagra-itopk-sizes`. Other search parameters are shared by
+all variants:
+
+```bash
+python benchmark/cuvs/run_index_benchmark.py \
+ --backends cuvs_brute_force,cuvs_cagra \
+ --cagra-search-params '{"search_width":1}' \
+ --cagra-itopk-sizes 32,64,128,256
+```
+
+If `itopk_size` alone does not reach the target recall, add a `search_width`
+sweep. The harness evaluates the Cartesian product while still building CAGRA
+only once:
+
+```bash
+python benchmark/cuvs/run_index_benchmark.py \
+ --backends cuvs_cagra \
+ --ann-benchmarks-hdf5 /data/glove-100-angular.hdf5 \
+ --metric cosine \
+ --cagra-itopk-sizes 64,128,256,512 \
+ --cagra-search-widths 1,2,4,8
+```
+
+## Public ANN datasets
+
+Random Gaussian vectors are useful for exact-search scaling, but CAGRA recall
+should be measured on a public dataset with ground truth. The harness accepts
+the HDF5 format published by
+[ann-benchmarks](https://github.com/erikbern/ann-benchmarks):
+
+```bash
+curl -fL \
+ https://ann-benchmarks.com/glove-100-angular.hdf5 \
+ -o /data/glove-100-angular.hdf5
+
+python benchmark/cuvs/run_index_benchmark.py \
+ --data-root /data/openviking-cuvs \
+ --ann-benchmarks-hdf5 /data/glove-100-angular.hdf5 \
+ --metric cosine \
+ --backends cuvs_brute_force,cuvs_cagra \
+ --query-batch-size 1 \
+ --search-repetitions 5 \
+ --cagra-itopk-sizes 32,64,128,256 \
+ --cagra-search-widths 1,2,4
+```
+
+The first run converts `train`, `test`, and `neighbors` into reusable NumPy
+memory maps. Angular datasets are normalized once so inner product has cosine
+ranking. The result records the source SHA-256 but not the local source path.
+
+`--ann-vector-limit` and `--ann-query-limit` can shorten exploratory runs. A
+vector limit disables the supplied ground truth because neighbor IDs may refer
+to omitted rows; include `native` or `cuvs_brute_force` in that case. A query
+limit retains the corresponding prefix of supplied ground truth.
+
+`query_batch_size=1` reflects the current OpenViking integration most closely.
+Larger batches measure the vector-index capacity: cuVS executes the batch on
+the GPU, while the current native wrapper processes each query sequentially.
+Do not present batch results as current server throughput without also running
+the collection/server benchmarks.
+
+## First comparison matrix
+
+Start with 1024-dimensional cosine vectors at 100K and 1M rows:
+
+1. batch size 1, K=10, all three backends;
+2. batch size 128, K=10, all three backends;
+3. CAGRA `itopk_size` 32/64/128, reporting QPS only at matched Recall@10;
+4. five independent timed runs after one dataset-generation pass.
+
+Add 5M only after the harness and memory measurements are stable.
+
+Random high-dimensional Gaussian vectors are useful for exact-search scaling,
+but are not representative enough for CAGRA quality claims. Use a public ANN
+dataset or real embedding corpus before reporting a CAGRA recall/QPS frontier.
+
+## Collection, filter, and lifecycle benchmark
+
+`run_collection_benchmark.py` exercises the OpenViking collection adapter
+rather than calling cuVS directly. It includes scalar-filter evaluation,
+label-to-record lookup, result normalization, and lazy rebuild after mutation
+or restart:
+
+```bash
+python benchmark/cuvs/run_collection_benchmark.py \
+ --vector-count 100000 \
+ --dimension 768 \
+ --query-count 50 \
+ --backends native,cuvs_brute_force,auto_cuvs \
+ --mutation-sizes 1,100,1000,10000 \
+ --filter-cache-size 16 \
+ --auto-filter-native-threshold 2000 \
+ --auto-path-filter-native-threshold 200 \
+ --data-root /data/openviking-cuvs
+```
+
+The filter matrix covers unfiltered, 10%, 1%, and 0.1% selectivity with both
+uniform and clustered scalar fields, plus hierarchical URI prefixes with the
+same target selectivities. Lifecycle output keeps write latency, the
+write-after first query, warm query, and restart first query separate so a lazy
+rebuild is not hidden in steady-state search latency.
+
+`--filter-cache-size` controls the cuVS LRU of prepared GPU bitsets. The
+per-scenario `first_query_ms` includes construction of a new filter mask;
+timed warm latency reuses the cached mask. Set it to zero to reproduce the
+uncached path.
+
+`auto_cuvs` additionally measures the memory-aware backend's per-query routing.
+It keeps unfiltered and wider filters on cuVS while routing small scalar and
+path candidate sets to native recall according to the two configurable
+thresholds. Set a threshold to zero to disable that part of the policy.
+Before the normal scenario matrix, the auto backend also records
+`prebuild_selective_query` with a 0.1% scalar filter. This query runs while the
+GPU index is still dirty, so its latency and GPU-memory delta verify that
+native routing happens before GPU admission and rebuild. The subsequent
+unfiltered scenario remains responsible for measuring the lazy GPU build.
+
+Aggregate independent process runs with median and median absolute deviation:
+
+```bash
+python benchmark/cuvs/summarize_collection_runs.py \
+ results/collection-run-{1,2,3,4,5}.json \
+ --output results/collection-summary.json
+```
+
+## Async service concurrency benchmark
+
+`run_service_concurrency_benchmark.py` uses OpenViking's
+`VikingVectorIndexBackend` and its `asyncio.to_thread` scheduling boundary. It
+keeps query vectors precomputed, so this is a service-facade benchmark rather
+than an embedding or HTTP benchmark. It covers repeated tenant filters, a
+repeated 10% filter, a new filter per request, and concurrent readers after a
+single-record mutation:
+
+```bash
+python benchmark/cuvs/run_service_concurrency_benchmark.py \
+ --vector-count 100000 \
+ --dimension 768 \
+ --query-count 64 \
+ --concurrency 1,4,16,32,64 \
+ --cached-request-count 200 \
+ --unique-request-count 32 \
+ --data-root /data/openviking-cuvs
+```
+
+The normal tenant scope means every public service-facade query includes an
+`account_id` filter. The benchmark reports p50/p95/p99, QPS, errors, and the
+post-mutation burst separately. A later end-to-end server benchmark should add
+HTTP, authentication, embedding, and reranking rather than folding those costs
+into this vector scheduling result.
+
+Aggregate independent service processes with:
+
+```bash
+python benchmark/cuvs/summarize_service_runs.py \
+ results/service-run-{1,2,3,4,5}.json \
+ --output results/service-summary.json
+```
diff --git a/benchmark/cuvs/run_collection_benchmark.py b/benchmark/cuvs/run_collection_benchmark.py
new file mode 100644
index 000000000..f0388af02
--- /dev/null
+++ b/benchmark/cuvs/run_collection_benchmark.py
@@ -0,0 +1,760 @@
+#!/usr/bin/env python3
+"""Benchmark OpenViking collection-level native and cuVS vector search.
+
+Unlike the index microbenchmark, this harness goes through CollectionAdapter
+and therefore includes filter compilation, label mapping, record lookup, and
+result normalization. It also measures the lazy rebuild paid by the first
+query after upsert, delete, and process restart.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gc
+import json
+import shutil
+import statistics
+import sys
+import tempfile
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+import numpy as np
+
+BENCHMARK_DIR = Path(__file__).resolve().parent
+if str(BENCHMARK_DIR) not in sys.path:
+ sys.path.insert(0, str(BENCHMARK_DIR))
+
+from run_index_benchmark import ( # noqa: E402
+ current_rss_bytes,
+ percentile,
+ prepare_dataset,
+ runtime_metadata,
+)
+
+from openviking.storage.vectordb_adapters.local_adapter import ( # noqa: E402
+ CuVSCollectionAdapter,
+ LocalCollectionAdapter,
+)
+
+SUPPORTED_BACKENDS = ("native", "cuvs_brute_force", "auto_cuvs")
+
+
+@dataclass(frozen=True)
+class FilterScenario:
+ name: str
+ filter: dict[str, Any] | None
+ distribution: str
+ selectivity: float
+
+
+def parse_positive_int_list(value: str, option: str) -> list[int]:
+ try:
+ parsed = [int(item.strip()) for item in value.split(",") if item.strip()]
+ except ValueError as exc:
+ raise argparse.ArgumentTypeError(f"{option} must contain integers") from exc
+ if not parsed or any(item <= 0 for item in parsed):
+ raise argparse.ArgumentTypeError(f"{option} must contain positive integers")
+ if len(parsed) != len(set(parsed)):
+ raise argparse.ArgumentTypeError(f"{option} cannot contain duplicates")
+ return parsed
+
+
+def filter_scenarios() -> list[FilterScenario]:
+ scenarios = [FilterScenario("unfiltered", None, "none", 1.0)]
+ for distribution, field in (
+ ("uniform", "uniform_bucket"),
+ ("clustered", "cluster_bucket"),
+ ):
+ for label, upper_bound, selectivity in (
+ ("10pct", 100, 0.10),
+ ("1pct", 10, 0.01),
+ ("0_1pct", 1, 0.001),
+ ):
+ scenarios.append(
+ FilterScenario(
+ name=f"{distribution}_{label}",
+ filter={"op": "range", "field": field, "lt": upper_bound},
+ distribution=distribution,
+ selectivity=selectivity,
+ )
+ )
+ for label, prefix, selectivity in (
+ ("10pct", "/docs/g0", 0.10),
+ ("1pct", "/docs/g0/h0", 0.01),
+ ("0_1pct", "/docs/g0/h0/i0", 0.001),
+ ):
+ scenarios.append(
+ FilterScenario(
+ name=f"path_{label}",
+ filter={
+ "op": "must",
+ "field": "uri",
+ "conds": [prefix],
+ "para": "-d=-1",
+ },
+ distribution="path",
+ selectivity=selectivity,
+ )
+ )
+ return scenarios
+
+
+def prebuild_selective_scenario(vector_count: int, native_threshold: int) -> FilterScenario | None:
+ """Return a filter that should route native before the first GPU build."""
+
+ eligible_count = (vector_count + 999) // 1000
+ if native_threshold <= 0 or eligible_count > native_threshold:
+ return None
+ return FilterScenario(
+ name="prebuild_selective_0_1pct",
+ filter={"op": "must", "field": "uniform_bucket", "conds": [0]},
+ distribution="uniform",
+ selectivity=eligible_count / vector_count,
+ )
+
+
+def scalar_fields(row_index: int, vector_count: int) -> tuple[int, int]:
+ uniform_bucket = row_index % 1000
+ cluster_bucket = min(999, (row_index * 1000) // vector_count)
+ return uniform_bucket, cluster_bucket
+
+
+def make_record(
+ row_index: int,
+ vector: Sequence[float],
+ vector_count: int,
+) -> dict[str, Any]:
+ uniform_bucket, cluster_bucket = scalar_fields(row_index, vector_count)
+ return {
+ "id": row_index + 1,
+ "vector": list(vector),
+ "uniform_bucket": uniform_bucket,
+ "cluster_bucket": cluster_bucket,
+ "uri": (
+ f"/docs/g{row_index % 10}/h{(row_index // 10) % 10}/"
+ f"i{(row_index // 100) % 10}/item-{row_index}"
+ ),
+ }
+
+
+def make_adapter(
+ backend: str,
+ project_path: Path,
+ collection_name: str,
+ *,
+ filter_cache_size: int,
+ auto_filter_native_threshold: int,
+ auto_path_filter_native_threshold: int,
+):
+ if backend == "native":
+ return LocalCollectionAdapter(
+ collection_name=collection_name,
+ project_path=str(project_path),
+ index_name="default",
+ )
+ if backend == "cuvs_brute_force":
+ return CuVSCollectionAdapter(
+ collection_name=collection_name,
+ project_path=str(project_path),
+ index_name="default",
+ cuvs_config={
+ "algorithm": "brute_force",
+ "fallback_to_native": False,
+ "filter_cache_size": filter_cache_size,
+ },
+ )
+ if backend == "auto_cuvs":
+ return LocalCollectionAdapter(
+ collection_name=collection_name,
+ project_path=str(project_path),
+ index_name="default",
+ collection_config={
+ "dense_search": {
+ "backend": "auto_cuvs",
+ "algorithm": "brute_force",
+ "fallback_to_native": True,
+ "filter_cache_size": filter_cache_size,
+ "auto_filter_native_threshold": auto_filter_native_threshold,
+ "auto_path_filter_native_threshold": auto_path_filter_native_threshold,
+ }
+ },
+ )
+ raise ValueError(f"Unsupported backend: {backend}")
+
+
+def collection_schema(collection_name: str, dimension: int) -> dict[str, Any]:
+ return {
+ "CollectionName": collection_name,
+ "Fields": [
+ {"FieldName": "id", "FieldType": "int64", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": dimension},
+ {"FieldName": "uniform_bucket", "FieldType": "int64"},
+ {"FieldName": "cluster_bucket", "FieldType": "int64"},
+ {"FieldName": "uri", "FieldType": "path"},
+ ],
+ "ScalarIndex": ["uniform_bucket", "cluster_bucket", "uri"],
+ }
+
+
+def gpu_memory_used_bytes() -> int | None:
+ try:
+ import cupy as cp
+
+ free, total = cp.cuda.runtime.memGetInfo()
+ return int(total - free)
+ except Exception:
+ return None
+
+
+def summarize_latency(latencies_ms: Sequence[float], query_count: int) -> dict[str, Any]:
+ total_seconds = sum(latencies_ms) / 1000.0
+ return {
+ "query_count": query_count,
+ "total_seconds": total_seconds,
+ "qps": query_count / total_seconds if total_seconds else 0.0,
+ "latency_ms": {
+ "mean": statistics.fmean(latencies_ms),
+ "p50": percentile(latencies_ms, 0.50),
+ "p95": percentile(latencies_ms, 0.95),
+ "p99": percentile(latencies_ms, 0.99),
+ },
+ "raw_latency_ms": list(latencies_ms),
+ }
+
+
+def result_ids(records: Sequence[dict[str, Any]]) -> list[int]:
+ return [int(record["id"]) for record in records]
+
+
+def run_search_scenario(
+ adapter: Any,
+ queries: np.ndarray,
+ *,
+ scenario: FilterScenario,
+ k: int,
+ warmup_queries: int,
+) -> dict[str, Any]:
+ query_lists = [row.tolist() for row in queries]
+ first_started = time.perf_counter()
+ first_records = adapter.query(
+ query_vector=query_lists[0],
+ filter=scenario.filter,
+ limit=k,
+ output_fields=["id"],
+ )
+ first_query_ms = (time.perf_counter() - first_started) * 1000.0
+
+ for index in range(warmup_queries):
+ adapter.query(
+ query_vector=query_lists[index % len(query_lists)],
+ filter=scenario.filter,
+ limit=k,
+ output_fields=["id"],
+ )
+
+ latencies_ms: list[float] = []
+ neighbors: list[list[int]] = []
+ for query in query_lists:
+ started = time.perf_counter()
+ records = adapter.query(
+ query_vector=query,
+ filter=scenario.filter,
+ limit=k,
+ output_fields=["id"],
+ )
+ latencies_ms.append((time.perf_counter() - started) * 1000.0)
+ neighbors.append(result_ids(records))
+
+ return {
+ "name": scenario.name,
+ "filter": scenario.filter,
+ "distribution": scenario.distribution,
+ "target_selectivity": scenario.selectivity,
+ "first_query_ms": first_query_ms,
+ "first_result_count": len(first_records),
+ "neighbors": neighbors,
+ "search": summarize_latency(latencies_ms, len(query_lists)),
+ }
+
+
+def run_single_query_scenario(
+ adapter: Any,
+ query: Sequence[float],
+ *,
+ scenario: FilterScenario,
+ k: int,
+) -> dict[str, Any]:
+ gpu_before = gpu_memory_used_bytes()
+ started = time.perf_counter()
+ records = adapter.query(
+ query_vector=list(query),
+ filter=scenario.filter,
+ limit=k,
+ output_fields=["id"],
+ )
+ latency_ms = (time.perf_counter() - started) * 1000.0
+ gpu_after = gpu_memory_used_bytes()
+ return {
+ "name": scenario.name,
+ "filter": scenario.filter,
+ "distribution": scenario.distribution,
+ "target_selectivity": scenario.selectivity,
+ "latency_ms": latency_ms,
+ "result_count": len(records),
+ "gpu_before_bytes": gpu_before,
+ "gpu_after_bytes": gpu_after,
+ "gpu_delta_bytes": (
+ gpu_after - gpu_before if gpu_before is not None and gpu_after is not None else None
+ ),
+ }
+
+
+def recall_at_k(
+ actual: Sequence[Sequence[int]], expected: Sequence[Sequence[int]], k: int
+) -> float:
+ if len(actual) != len(expected):
+ raise ValueError("Actual and expected query counts differ")
+ per_query: list[float] = []
+ for actual_row, expected_row in zip(actual, expected, strict=True):
+ denominator = min(k, len(expected_row))
+ if denominator == 0:
+ per_query.append(1.0 if not actual_row else 0.0)
+ continue
+ overlap = len(set(actual_row[:k]).intersection(expected_row[:k]))
+ per_query.append(overlap / denominator)
+ return statistics.fmean(per_query) if per_query else 1.0
+
+
+def batched_upsert(adapter: Any, records: Sequence[dict[str, Any]], batch_size: int) -> float:
+ api_seconds = 0.0
+ for start in range(0, len(records), batch_size):
+ started = time.perf_counter()
+ adapter.upsert(list(records[start : start + batch_size]))
+ api_seconds += time.perf_counter() - started
+ return api_seconds
+
+
+def ingest_dataset(
+ adapter: Any,
+ dataset: np.ndarray,
+ *,
+ batch_size: int,
+) -> dict[str, Any]:
+ started = time.perf_counter()
+ api_seconds = 0.0
+ for start in range(0, dataset.shape[0], batch_size):
+ stop = min(start + batch_size, dataset.shape[0])
+ records = [
+ make_record(index, dataset[index].tolist(), dataset.shape[0])
+ for index in range(start, stop)
+ ]
+ api_seconds += batched_upsert(adapter, records, batch_size)
+ total_seconds = time.perf_counter() - started
+ return {
+ "api_seconds": api_seconds,
+ "total_seconds": total_seconds,
+ "records_per_second": dataset.shape[0] / total_seconds if total_seconds else 0.0,
+ }
+
+
+def mutation_records(
+ dataset: np.ndarray,
+ queries: np.ndarray,
+ count: int,
+) -> list[dict[str, Any]]:
+ records = []
+ for index in range(count):
+ # Reuse normalized query vectors so the update changes dense ranking.
+ vector = queries[index % queries.shape[0]].tolist()
+ records.append(make_record(index, vector, dataset.shape[0]))
+ return records
+
+
+def time_query(adapter: Any, query: Sequence[float], k: int) -> tuple[float, list[int]]:
+ started = time.perf_counter()
+ records = adapter.query(query_vector=list(query), limit=k, output_fields=["id"])
+ return (time.perf_counter() - started) * 1000.0, result_ids(records)
+
+
+def run_mutation_lifecycle(
+ adapter: Any,
+ dataset: np.ndarray,
+ queries: np.ndarray,
+ *,
+ mutation_sizes: Sequence[int],
+ delete_count: int,
+ batch_size: int,
+ k: int,
+) -> dict[str, Any]:
+ updates = []
+ for count in mutation_sizes:
+ if count > dataset.shape[0]:
+ continue
+ records = mutation_records(dataset, queries, count)
+ wall_started = time.perf_counter()
+ api_seconds = batched_upsert(adapter, records, batch_size)
+ write_seconds = time.perf_counter() - wall_started
+ next_query_ms, next_ids = time_query(adapter, queries[0], k)
+ warm_query_ms, _ = time_query(adapter, queries[0], k)
+ updates.append(
+ {
+ "count": count,
+ "write_api_seconds": api_seconds,
+ "write_wall_seconds": write_seconds,
+ "next_query_ms": next_query_ms,
+ "warm_query_ms": warm_query_ms,
+ "next_result_count": len(next_ids),
+ }
+ )
+ del records
+ gc.collect()
+
+ actual_delete_count = min(delete_count, dataset.shape[0])
+ delete_ids = list(range(1, actual_delete_count + 1))
+ delete_started = time.perf_counter()
+ deleted = adapter.delete(ids=delete_ids)
+ delete_seconds = time.perf_counter() - delete_started
+ delete_next_query_ms, delete_next_ids = time_query(adapter, queries[0], k)
+ delete_warm_query_ms, _ = time_query(adapter, queries[0], k)
+ return {
+ "updates": updates,
+ "delete": {
+ "count": deleted,
+ "write_seconds": delete_seconds,
+ "next_query_ms": delete_next_query_ms,
+ "warm_query_ms": delete_warm_query_ms,
+ "next_result_count": len(delete_next_ids),
+ },
+ }
+
+
+def run_backend(
+ backend: str,
+ dataset: np.ndarray,
+ queries: np.ndarray,
+ *,
+ run_root: Path,
+ ingest_batch_size: int,
+ warmup_queries: int,
+ k: int,
+ mutation_sizes: Sequence[int],
+ delete_count: int,
+ filter_cache_size: int,
+ auto_filter_native_threshold: int,
+ auto_path_filter_native_threshold: int,
+) -> dict[str, Any]:
+ collection_name = f"collection_benchmark_{backend}"
+ project_path = run_root / backend
+ adapter = make_adapter(
+ backend,
+ project_path,
+ collection_name,
+ filter_cache_size=filter_cache_size,
+ auto_filter_native_threshold=auto_filter_native_threshold,
+ auto_path_filter_native_threshold=auto_path_filter_native_threshold,
+ )
+ reopened = None
+ rss_before = current_rss_bytes()
+ gpu_before = gpu_memory_used_bytes()
+ try:
+ created = adapter.create_collection(
+ collection_name,
+ collection_schema(collection_name, dataset.shape[1]),
+ distance="cosine",
+ sparse_weight=0.0,
+ index_name="default",
+ )
+ if not created:
+ raise RuntimeError(f"Collection already exists for backend {backend}")
+
+ ingest = ingest_dataset(adapter, dataset, batch_size=ingest_batch_size)
+ record_count = adapter.count()
+ if record_count != dataset.shape[0]:
+ raise RuntimeError(
+ f"Collection count mismatch for {backend}: {record_count} != {dataset.shape[0]}"
+ )
+ rss_after_ingest = current_rss_bytes()
+ gpu_after_ingest = gpu_memory_used_bytes()
+
+ prebuild_selective_query = None
+ if backend == "auto_cuvs":
+ scenario = prebuild_selective_scenario(dataset.shape[0], auto_filter_native_threshold)
+ if scenario is not None:
+ prebuild_selective_query = run_single_query_scenario(
+ adapter,
+ queries[0],
+ scenario=scenario,
+ k=k,
+ )
+
+ searches = [
+ run_search_scenario(
+ adapter,
+ queries,
+ scenario=scenario,
+ k=k,
+ warmup_queries=warmup_queries,
+ )
+ for scenario in filter_scenarios()
+ ]
+ rss_after_search = current_rss_bytes()
+ gpu_after_search = gpu_memory_used_bytes()
+
+ lifecycle = run_mutation_lifecycle(
+ adapter,
+ dataset,
+ queries,
+ mutation_sizes=mutation_sizes,
+ delete_count=delete_count,
+ batch_size=ingest_batch_size,
+ k=k,
+ )
+
+ close_started = time.perf_counter()
+ adapter.close()
+ close_seconds = time.perf_counter() - close_started
+ adapter = None
+
+ construct_started = time.perf_counter()
+ reopened = make_adapter(
+ backend,
+ project_path,
+ collection_name,
+ filter_cache_size=filter_cache_size,
+ auto_filter_native_threshold=auto_filter_native_threshold,
+ auto_path_filter_native_threshold=auto_path_filter_native_threshold,
+ )
+ construct_seconds = time.perf_counter() - construct_started
+ reopen_query_ms, reopen_ids = time_query(reopened, queries[0], k)
+ reopen_warm_query_ms, _ = time_query(reopened, queries[0], k)
+ lifecycle["restart"] = {
+ "close_seconds": close_seconds,
+ "adapter_construct_seconds": construct_seconds,
+ "first_query_ms": reopen_query_ms,
+ "warm_query_ms": reopen_warm_query_ms,
+ "first_result_count": len(reopen_ids),
+ }
+
+ return {
+ "backend": backend,
+ "ingest": ingest,
+ "record_count": record_count,
+ "rss_before_bytes": rss_before,
+ "rss_after_ingest_bytes": rss_after_ingest,
+ "rss_after_search_bytes": rss_after_search,
+ "rss_ingest_delta_bytes": (
+ rss_after_ingest - rss_before
+ if rss_before is not None and rss_after_ingest is not None
+ else None
+ ),
+ "gpu_before_bytes": gpu_before,
+ "gpu_after_ingest_bytes": gpu_after_ingest,
+ "gpu_after_search_bytes": gpu_after_search,
+ "gpu_search_delta_bytes": (
+ gpu_after_search - gpu_before
+ if gpu_before is not None and gpu_after_search is not None
+ else None
+ ),
+ "prebuild_selective_query": prebuild_selective_query,
+ "searches": searches,
+ "lifecycle": lifecycle,
+ }
+ finally:
+ if adapter is not None:
+ adapter.close()
+ if reopened is not None:
+ reopened.close()
+ gc.collect()
+
+
+def attach_recall(results: Sequence[dict[str, Any]], k: int) -> None:
+ by_backend = {result["backend"]: result for result in results}
+ reference = by_backend.get("cuvs_brute_force")
+ if reference is None:
+ return
+ reference_searches = {item["name"]: item for item in reference["searches"]}
+ for result in results:
+ for search in result["searches"]:
+ expected = reference_searches[search["name"]]["neighbors"]
+ search["recall_at_k"] = recall_at_k(search["neighbors"], expected, k)
+ search["ground_truth_backend"] = "cuvs_brute_force"
+
+
+def strip_neighbors(results: Iterable[dict[str, Any]]) -> None:
+ for result in results:
+ for search in result["searches"]:
+ search.pop("neighbors", None)
+
+
+def print_summary(results: Sequence[dict[str, Any]]) -> None:
+ print("\nbackend scenario p50_ms p95_ms qps recall")
+ print("---------------------- -------------------- ------- ------- -------- -------")
+ for result in results:
+ for search in result["searches"]:
+ latency = search["search"]["latency_ms"]
+ print(
+ f"{result['backend']:<22} {search['name']:<20} "
+ f"{latency['p50']:>7.3f} {latency['p95']:>7.3f} "
+ f"{search['search']['qps']:>8.1f} "
+ f"{search.get('recall_at_k', 1.0):>7.4f}"
+ )
+ print("\nbackend mutation write_s next_query_ms warm_query_ms")
+ print("---------------------- --------- ------- ------------- -------------")
+ for result in results:
+ for update in result["lifecycle"]["updates"]:
+ print(
+ f"{result['backend']:<22} {update['count']:>9} "
+ f"{update['write_wall_seconds']:>7.3f} "
+ f"{update['next_query_ms']:>13.3f} {update['warm_query_ms']:>13.3f}"
+ )
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--backends", default="native,cuvs_brute_force")
+ parser.add_argument("--vector-count", type=int, default=10_000)
+ parser.add_argument("--dimension", type=int, default=128)
+ parser.add_argument("--query-count", type=int, default=20)
+ parser.add_argument("--k", type=int, default=10)
+ parser.add_argument("--seed", type=int, default=42)
+ parser.add_argument("--warmup-queries", type=int, default=3)
+ parser.add_argument("--ingest-batch-size", type=int, default=256)
+ parser.add_argument(
+ "--mutation-sizes",
+ type=lambda value: parse_positive_int_list(value, "--mutation-sizes"),
+ default=[1, 100, 1_000, 10_000],
+ )
+ parser.add_argument("--delete-count", type=int, default=100)
+ parser.add_argument("--filter-cache-size", type=int, default=16)
+ parser.add_argument("--auto-filter-native-threshold", type=int, default=2000)
+ parser.add_argument("--auto-path-filter-native-threshold", type=int, default=200)
+ parser.add_argument("--data-root", type=Path, default=Path("/tmp/openviking-cuvs-benchmark"))
+ parser.add_argument("--output", type=Path)
+ parser.add_argument("--keep-collections", action="store_true")
+ return parser
+
+
+def validate_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> list[str]:
+ for name in (
+ "vector_count",
+ "dimension",
+ "query_count",
+ "k",
+ "warmup_queries",
+ "ingest_batch_size",
+ "delete_count",
+ ):
+ if getattr(args, name) <= 0:
+ parser.error(f"--{name.replace('_', '-')} must be positive")
+ if args.k > args.vector_count:
+ parser.error("--k cannot exceed --vector-count")
+ if args.filter_cache_size < 0:
+ parser.error("--filter-cache-size cannot be negative")
+ if args.auto_filter_native_threshold < 0:
+ parser.error("--auto-filter-native-threshold cannot be negative")
+ if args.auto_path_filter_native_threshold < 0:
+ parser.error("--auto-path-filter-native-threshold cannot be negative")
+ backends = [item.strip() for item in args.backends.split(",") if item.strip()]
+ unknown = sorted(set(backends).difference(SUPPORTED_BACKENDS))
+ if unknown:
+ parser.error(f"Unsupported backends: {', '.join(unknown)}")
+ if len(backends) != len(set(backends)):
+ parser.error("--backends cannot contain duplicates")
+ return backends
+
+
+def main() -> None:
+ parser = build_parser()
+ args = parser.parse_args()
+ backends = validate_args(parser, args)
+ backends.sort(key=SUPPORTED_BACKENDS.index)
+
+ files = prepare_dataset(
+ args.data_root,
+ vector_count=args.vector_count,
+ dimension=args.dimension,
+ query_count=args.query_count,
+ metric="cosine",
+ seed=args.seed,
+ generation_chunk_size=16_384,
+ force=False,
+ )
+ dataset = np.load(files.dataset, mmap_mode="r", allow_pickle=False)
+ queries = np.load(files.queries, mmap_mode="r", allow_pickle=False)
+
+ collection_root = args.data_root / "collection-runs"
+ collection_root.mkdir(parents=True, exist_ok=True)
+ run_root = Path(tempfile.mkdtemp(prefix="run-", dir=collection_root))
+ results: list[dict[str, Any]] = []
+ try:
+ for backend in backends:
+ print(f"Running collection benchmark for {backend} ...", flush=True)
+ results.append(
+ run_backend(
+ backend,
+ dataset,
+ queries,
+ run_root=run_root,
+ ingest_batch_size=args.ingest_batch_size,
+ warmup_queries=args.warmup_queries,
+ k=args.k,
+ mutation_sizes=args.mutation_sizes,
+ delete_count=args.delete_count,
+ filter_cache_size=args.filter_cache_size,
+ auto_filter_native_threshold=args.auto_filter_native_threshold,
+ auto_path_filter_native_threshold=(args.auto_path_filter_native_threshold),
+ )
+ )
+ attach_recall(results, args.k)
+ strip_neighbors(results)
+
+ output_document = {
+ "format_version": 1,
+ "runtime": runtime_metadata(),
+ "dataset": {
+ "kind": "random",
+ "vector_count": int(dataset.shape[0]),
+ "dimension": int(dataset.shape[1]),
+ "query_count": int(queries.shape[0]),
+ "metric": "cosine",
+ "seed": args.seed,
+ "reused": files.reused,
+ "generated_seconds": files.generated_seconds,
+ },
+ "parameters": {
+ "k": args.k,
+ "warmup_queries": args.warmup_queries,
+ "ingest_batch_size": args.ingest_batch_size,
+ "mutation_sizes": args.mutation_sizes,
+ "delete_count": args.delete_count,
+ "filter_cache_size": args.filter_cache_size,
+ "auto_filter_native_threshold": args.auto_filter_native_threshold,
+ "auto_path_filter_native_threshold": (args.auto_path_filter_native_threshold),
+ "filter_scenarios": [scenario.name for scenario in filter_scenarios()],
+ },
+ "results": results,
+ }
+ output = args.output
+ if output is None:
+ result_dir = args.data_root / "results"
+ result_dir.mkdir(parents=True, exist_ok=True)
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+ output = result_dir / (
+ f"collection-n{dataset.shape[0]}-d{dataset.shape[1]}-"
+ f"q{queries.shape[0]}-{stamp}.json"
+ )
+ output.parent.mkdir(parents=True, exist_ok=True)
+ output.write_text(json.dumps(output_document, indent=2, sort_keys=True) + "\n")
+ print_summary(results)
+ print(f"\nWrote {output}")
+ finally:
+ if not args.keep_collections:
+ shutil.rmtree(run_root, ignore_errors=True)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/benchmark/cuvs/run_index_benchmark.py b/benchmark/cuvs/run_index_benchmark.py
new file mode 100644
index 000000000..0ad0623fe
--- /dev/null
+++ b/benchmark/cuvs/run_index_benchmark.py
@@ -0,0 +1,1034 @@
+#!/usr/bin/env python3
+"""Benchmark OpenViking native flat search against cuVS indexes.
+
+This is an index-level benchmark: it deliberately excludes embedding, HTTP,
+record lookup, and LLM work. Datasets are generated as NumPy memory maps so a
+large run does not need a second full host-memory copy.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gc
+import hashlib
+import json
+import math
+import os
+import platform
+import re
+import statistics
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable, Protocol, Sequence
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(REPO_ROOT) not in sys.path:
+ sys.path.insert(0, str(REPO_ROOT))
+
+import numpy as np # noqa: E402
+
+from openviking.storage.vectordb.index.local_index import LocalIndex # noqa: E402
+from openviking.storage.vectordb.meta.collection_meta import ( # noqa: E402
+ create_collection_meta,
+)
+from openviking.storage.vectordb.meta.index_meta import create_index_meta # noqa: E402
+from openviking.storage.vectordb.store.data import DeltaRecord # noqa: E402
+
+EXACT_BACKENDS = {"native", "cuvs_brute_force"}
+SUPPORTED_BACKENDS = (*sorted(EXACT_BACKENDS), "cuvs_cagra")
+
+
+def utc_now() -> str:
+ return datetime.now(timezone.utc).isoformat()
+
+
+def current_rss_bytes() -> int | None:
+ try:
+ for line in Path("/proc/self/status").read_text().splitlines():
+ if line.startswith("VmRSS:"):
+ return int(line.split()[1]) * 1024
+ except (OSError, ValueError, IndexError):
+ return None
+ return None
+
+
+def cpu_model() -> str | None:
+ try:
+ for line in Path("/proc/cpuinfo").read_text().splitlines():
+ if line.startswith("model name"):
+ return line.split(":", 1)[1].strip()
+ except (OSError, IndexError):
+ return None
+ return None
+
+
+def percentile(values: Sequence[float], quantile: float) -> float:
+ if not values:
+ return 0.0
+ ordered = sorted(float(value) for value in values)
+ position = (len(ordered) - 1) * quantile
+ lower = math.floor(position)
+ upper = math.ceil(position)
+ if lower == upper:
+ return ordered[lower]
+ fraction = position - lower
+ return ordered[lower] * (1.0 - fraction) + ordered[upper] * fraction
+
+
+def recall_at_k(actual: np.ndarray, expected: np.ndarray, k: int) -> float:
+ if actual.shape[0] != expected.shape[0]:
+ raise ValueError("Actual and expected query counts differ")
+ effective_k = min(k, actual.shape[1], expected.shape[1])
+ if effective_k <= 0 or actual.shape[0] == 0:
+ return 1.0
+ recalls = []
+ for actual_row, expected_row in zip(actual, expected, strict=True):
+ recalls.append(
+ len(set(actual_row[:effective_k]).intersection(expected_row[:effective_k]))
+ / effective_k
+ )
+ return statistics.fmean(recalls)
+
+
+def normalize_rows(values: np.ndarray) -> None:
+ norms = np.linalg.norm(values, axis=1, keepdims=True)
+ np.divide(values, norms, out=values, where=norms != 0)
+
+
+def preload_dataset(values: np.ndarray, chunk_size: int) -> tuple[float, float]:
+ """Read every dataset page before backend build timing starts."""
+
+ started = time.perf_counter()
+ checksum = 0.0
+ for start in range(0, values.shape[0], chunk_size):
+ checksum += float(np.sum(values[start : start + chunk_size], dtype=np.float64))
+ return time.perf_counter() - started, checksum
+
+
+@dataclass(frozen=True)
+class DatasetFiles:
+ dataset: Path
+ queries: Path
+ metadata: Path
+ generated_seconds: float
+ reused: bool
+ ground_truth: Path | None = None
+
+
+def sha256_file(path: Path, chunk_size: int = 8 * 1024 * 1024) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as source:
+ while True:
+ chunk = source.read(chunk_size)
+ if not chunk:
+ break
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def _safe_dataset_name(value: str) -> str:
+ normalized = re.sub(r"[^A-Za-z0-9_.-]+", "-", value).strip("-.")
+ return normalized or "dataset"
+
+
+def _copy_float_matrix(
+ source: Any,
+ destination: np.ndarray,
+ *,
+ chunk_size: int,
+ normalize: bool,
+) -> None:
+ for start in range(0, destination.shape[0], chunk_size):
+ stop = min(start + chunk_size, destination.shape[0])
+ chunk = np.asarray(source[start:stop], dtype=np.float32)
+ if normalize:
+ normalize_rows(chunk)
+ destination[start:stop] = chunk
+ if hasattr(destination, "flush"):
+ destination.flush()
+
+
+def prepare_ann_benchmarks_dataset(
+ root: Path,
+ *,
+ source: Path,
+ metric: str,
+ vector_limit: int | None,
+ query_limit: int | None,
+ generation_chunk_size: int,
+ force: bool,
+) -> DatasetFiles:
+ """Convert an ann-benchmarks HDF5 dataset into reusable NumPy memmaps."""
+
+ try:
+ import h5py
+ except ImportError as exc:
+ raise RuntimeError(
+ "Reading ann-benchmarks HDF5 files requires h5py; install h5py or use the "
+ "cuVS development image"
+ ) from exc
+
+ source = source.expanduser().resolve()
+ if not source.is_file():
+ raise FileNotFoundError(f"ann-benchmarks dataset not found: {source}")
+
+ started = time.perf_counter()
+ source_digest = sha256_file(source)
+ with h5py.File(source, "r") as hdf5:
+ missing = sorted({"train", "test"}.difference(hdf5.keys()))
+ if missing:
+ raise ValueError(f"ann-benchmarks dataset is missing HDF5 keys: {', '.join(missing)}")
+ train = hdf5["train"]
+ test = hdf5["test"]
+ if len(train.shape) != 2 or len(test.shape) != 2 or train.shape[1] != test.shape[1]:
+ raise ValueError("ann-benchmarks train/test matrices must be 2D with equal dimensions")
+
+ full_vector_count = int(train.shape[0])
+ full_query_count = int(test.shape[0])
+ vector_count = min(vector_limit or full_vector_count, full_vector_count)
+ query_count = min(query_limit or full_query_count, full_query_count)
+ dimension = int(train.shape[1])
+ source_distance = hdf5.attrs.get("distance")
+ if isinstance(source_distance, bytes):
+ source_distance = source_distance.decode(errors="replace")
+ source_distance = str(source_distance) if source_distance is not None else None
+ expected_metric = {"angular": "cosine", "euclidean": "l2"}.get(source_distance)
+ if expected_metric is not None and metric != expected_metric:
+ raise ValueError(
+ f"dataset distance={source_distance!r} requires --metric {expected_metric} "
+ "for its provided ground truth"
+ )
+
+ has_usable_ground_truth = (
+ "neighbors" in hdf5
+ and vector_count == full_vector_count
+ and len(hdf5["neighbors"].shape) == 2
+ and int(hdf5["neighbors"].shape[0]) >= query_count
+ )
+ ground_truth_width = int(hdf5["neighbors"].shape[1]) if has_usable_ground_truth else 0
+ dataset_name = _safe_dataset_name(source.stem)
+ dataset_id = (
+ f"ann-{dataset_name}-{source_digest[:12]}-n{vector_count}-q{query_count}-{metric}"
+ )
+ dataset_dir = root / "datasets" / dataset_id
+ dataset_path = dataset_dir / "base.npy"
+ query_path = dataset_dir / "queries.npy"
+ ground_truth_path = dataset_dir / "ground_truth.npy"
+ metadata_path = dataset_dir / "metadata.json"
+ expected_metadata = {
+ "format_version": 1,
+ "dataset_kind": "ann-benchmarks-hdf5",
+ "dataset_name": dataset_name,
+ "source_sha256": source_digest,
+ "source_size_bytes": source.stat().st_size,
+ "source_distance": source_distance,
+ "full_vector_count": full_vector_count,
+ "full_query_count": full_query_count,
+ "vector_count": vector_count,
+ "query_count": query_count,
+ "dimension": dimension,
+ "metric": metric,
+ "dtype": "float32",
+ "normalized": metric == "cosine",
+ "ground_truth_width": ground_truth_width,
+ }
+
+ expected_files = [dataset_path, query_path]
+ if has_usable_ground_truth:
+ expected_files.append(ground_truth_path)
+ if not force and metadata_path.exists() and all(path.exists() for path in expected_files):
+ try:
+ if json.loads(metadata_path.read_text()) == expected_metadata:
+ return DatasetFiles(
+ dataset=dataset_path,
+ queries=query_path,
+ metadata=metadata_path,
+ generated_seconds=0.0,
+ reused=True,
+ ground_truth=(ground_truth_path if has_usable_ground_truth else None),
+ )
+ except (OSError, json.JSONDecodeError):
+ pass
+
+ dataset_dir.mkdir(parents=True, exist_ok=True)
+ dataset = np.lib.format.open_memmap(
+ dataset_path,
+ mode="w+",
+ dtype=np.float32,
+ shape=(vector_count, dimension),
+ )
+ _copy_float_matrix(
+ train,
+ dataset,
+ chunk_size=generation_chunk_size,
+ normalize=metric == "cosine",
+ )
+ del dataset
+
+ queries = np.lib.format.open_memmap(
+ query_path,
+ mode="w+",
+ dtype=np.float32,
+ shape=(query_count, dimension),
+ )
+ _copy_float_matrix(
+ test,
+ queries,
+ chunk_size=generation_chunk_size,
+ normalize=metric == "cosine",
+ )
+ del queries
+
+ if has_usable_ground_truth:
+ ground_truth = np.lib.format.open_memmap(
+ ground_truth_path,
+ mode="w+",
+ dtype=np.int64,
+ shape=(query_count, ground_truth_width),
+ )
+ for start in range(0, query_count, generation_chunk_size):
+ stop = min(start + generation_chunk_size, query_count)
+ ground_truth[start:stop] = np.asarray(hdf5["neighbors"][start:stop], dtype=np.int64)
+ ground_truth.flush()
+ del ground_truth
+
+ metadata_path.write_text(json.dumps(expected_metadata, indent=2, sort_keys=True) + "\n")
+ return DatasetFiles(
+ dataset=dataset_path,
+ queries=query_path,
+ metadata=metadata_path,
+ generated_seconds=time.perf_counter() - started,
+ reused=False,
+ ground_truth=(ground_truth_path if has_usable_ground_truth else None),
+ )
+
+
+def prepare_dataset(
+ root: Path,
+ *,
+ vector_count: int,
+ dimension: int,
+ query_count: int,
+ metric: str,
+ seed: int,
+ generation_chunk_size: int,
+ force: bool,
+) -> DatasetFiles:
+ dataset_id = f"random-n{vector_count}-d{dimension}-q{query_count}-{metric}-s{seed}"
+ dataset_dir = root / "datasets" / dataset_id
+ dataset_path = dataset_dir / "base.npy"
+ query_path = dataset_dir / "queries.npy"
+ metadata_path = dataset_dir / "metadata.json"
+ expected_metadata = {
+ "format_version": 1,
+ "generator": "numpy.default_rng.standard_normal",
+ "vector_count": vector_count,
+ "dimension": dimension,
+ "query_count": query_count,
+ "metric": metric,
+ "seed": seed,
+ "dtype": "float32",
+ "normalized": metric == "cosine",
+ }
+
+ if not force and dataset_path.exists() and query_path.exists() and metadata_path.exists():
+ try:
+ if json.loads(metadata_path.read_text()) == expected_metadata:
+ return DatasetFiles(
+ dataset=dataset_path,
+ queries=query_path,
+ metadata=metadata_path,
+ generated_seconds=0.0,
+ reused=True,
+ )
+ except (OSError, json.JSONDecodeError):
+ pass
+
+ dataset_dir.mkdir(parents=True, exist_ok=True)
+ started = time.perf_counter()
+ rng = np.random.default_rng(seed)
+ dataset = np.lib.format.open_memmap(
+ dataset_path,
+ mode="w+",
+ dtype=np.float32,
+ shape=(vector_count, dimension),
+ )
+ for start in range(0, vector_count, generation_chunk_size):
+ stop = min(start + generation_chunk_size, vector_count)
+ chunk = rng.standard_normal((stop - start, dimension)).astype(np.float32)
+ if metric == "cosine":
+ normalize_rows(chunk)
+ dataset[start:stop] = chunk
+ dataset.flush()
+ del dataset
+
+ queries = rng.standard_normal((query_count, dimension)).astype(np.float32)
+ if metric == "cosine":
+ normalize_rows(queries)
+ np.save(query_path, queries, allow_pickle=False)
+ metadata_path.write_text(json.dumps(expected_metadata, indent=2, sort_keys=True) + "\n")
+ return DatasetFiles(
+ dataset=dataset_path,
+ queries=query_path,
+ metadata=metadata_path,
+ generated_seconds=time.perf_counter() - started,
+ reused=False,
+ )
+
+
+class Backend(Protocol):
+ name: str
+
+ def build(self, dataset: np.ndarray) -> None: ...
+
+ def search(self, queries: np.ndarray, k: int) -> tuple[np.ndarray, np.ndarray]: ...
+
+ def gpu_memory_used_bytes(self) -> int | None: ...
+
+ def close(self) -> None: ...
+
+
+class NativeFlatBackend:
+ name = "native"
+
+ def __init__(self, dimension: int, metric: str, ingest_batch_size: int):
+ self.dimension = dimension
+ self.metric = metric
+ self.ingest_batch_size = ingest_batch_size
+ self.index: LocalIndex | None = None
+
+ def build(self, dataset: np.ndarray) -> None:
+ collection_meta = create_collection_meta(
+ "",
+ {
+ "CollectionName": "cuvs_index_benchmark",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "int64", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": self.dimension},
+ ],
+ },
+ )
+ index_meta = create_index_meta(
+ collection_meta,
+ user_meta={
+ "IndexName": "default",
+ "VectorIndex": {
+ "IndexType": "flat",
+ # Inputs are normalized once by the dataset generator.
+ "Distance": "ip" if self.metric == "cosine" else "l2",
+ },
+ "ScalarIndex": [],
+ },
+ )
+ config = index_meta.get_build_index_dict()
+ config["VectorIndex"]["ElementCount"] = 0
+ config["VectorIndex"]["MaxElementCount"] = int(dataset.shape[0])
+ self.index = LocalIndex(json.dumps(config), index_meta)
+
+ for start in range(0, dataset.shape[0], self.ingest_batch_size):
+ stop = min(start + self.ingest_batch_size, dataset.shape[0])
+ records = [
+ DeltaRecord(
+ type=DeltaRecord.Type.UPSERT,
+ label=start + offset,
+ vector=row.tolist(),
+ )
+ for offset, row in enumerate(np.asarray(dataset[start:stop]))
+ ]
+ self.index.upsert_data(records)
+
+ def search(self, queries: np.ndarray, k: int) -> tuple[np.ndarray, np.ndarray]:
+ if self.index is None:
+ raise RuntimeError("Native index has not been built")
+ all_neighbors: list[list[int]] = []
+ all_scores: list[list[float]] = []
+ for query in queries:
+ labels, scores = self.index.search(query.tolist(), k, None, [], [])
+ all_neighbors.append(labels)
+ all_scores.append(scores)
+ return np.asarray(all_neighbors, dtype=np.int64), np.asarray(all_scores, dtype=np.float32)
+
+ def gpu_memory_used_bytes(self) -> int | None:
+ return None
+
+ def close(self) -> None:
+ if self.index is not None:
+ self.index.drop()
+ self.index = None
+ gc.collect()
+
+
+class CuVSBackend:
+ def __init__(
+ self,
+ algorithm: str,
+ metric: str,
+ build_params: dict[str, Any],
+ search_params: dict[str, Any],
+ ):
+ import cupy as cp
+ from cuvs.neighbors import brute_force, cagra
+
+ if cp.cuda.runtime.getDeviceCount() < 1:
+ raise RuntimeError("cuVS benchmark requires a visible CUDA device")
+ self.cp = cp
+ self.brute_force = brute_force
+ self.cagra = cagra
+ self.algorithm = algorithm
+ self.metric = "inner_product" if metric == "cosine" else "sqeuclidean"
+ self.build_params = dict(build_params)
+ self.search_params = dict(search_params)
+ self.dataset = None
+ self.index = None
+ self.name = f"cuvs_{algorithm}"
+
+ def set_search_params(self, search_params: dict[str, Any]) -> None:
+ self.search_params = dict(search_params)
+
+ def build(self, dataset: np.ndarray) -> None:
+ self.dataset = self.cp.asarray(dataset, dtype=self.cp.float32)
+ if self.algorithm == "brute_force":
+ self.index = self.brute_force.build(self.dataset, metric=self.metric)
+ else:
+ params = self.cagra.IndexParams(metric=self.metric, **self.build_params)
+ self.index = self.cagra.build(params, self.dataset)
+ self.cp.cuda.Stream.null.synchronize()
+
+ def search(self, queries: np.ndarray, k: int) -> tuple[np.ndarray, np.ndarray]:
+ if self.index is None:
+ raise RuntimeError("cuVS index has not been built")
+ device_queries = self.cp.asarray(queries, dtype=self.cp.float32)
+ if self.algorithm == "brute_force":
+ distances, neighbors = self.brute_force.search(self.index, device_queries, k)
+ else:
+ search_params = dict(self.search_params)
+ configured_itopk = int(search_params.get("itopk_size", 64))
+ minimum_itopk = ((k + 31) // 32) * 32
+ search_params["itopk_size"] = max(configured_itopk, minimum_itopk)
+ params = self.cagra.SearchParams(**search_params)
+ distances, neighbors = self.cagra.search(params, self.index, device_queries, k)
+ # Host copies synchronize the GPU and make the timing end-to-end.
+ host_neighbors = self.cp.asnumpy(neighbors).astype(np.int64, copy=False)
+ host_distances = self.cp.asnumpy(distances).astype(np.float32, copy=False)
+ return host_neighbors, host_distances
+
+ def gpu_memory_used_bytes(self) -> int | None:
+ free, total = self.cp.cuda.runtime.memGetInfo()
+ return int(total - free)
+
+ def close(self) -> None:
+ self.index = None
+ self.dataset = None
+ gc.collect()
+ self.cp.get_default_memory_pool().free_all_blocks()
+ self.cp.get_default_pinned_memory_pool().free_all_blocks()
+ self.cp.cuda.Stream.null.synchronize()
+
+
+def batches(values: np.ndarray, batch_size: int) -> Iterable[np.ndarray]:
+ for start in range(0, values.shape[0], batch_size):
+ yield values[start : start + batch_size]
+
+
+def run_search(
+ backend: Backend,
+ queries: np.ndarray,
+ *,
+ k: int,
+ batch_size: int,
+ warmup_batches: int,
+ repetitions: int,
+) -> tuple[np.ndarray, dict[str, Any]]:
+ if queries.shape[0] == 0:
+ raise ValueError("At least one query is required")
+ warmup = queries[: min(queries.shape[0], batch_size)]
+ for _ in range(warmup_batches):
+ backend.search(warmup, k)
+
+ neighbors: list[np.ndarray] = []
+ batch_latency_ms: list[float] = []
+ query_counts: list[int] = []
+ for repetition in range(repetitions):
+ for query_batch in batches(queries, batch_size):
+ started = time.perf_counter()
+ batch_neighbors, _ = backend.search(query_batch, k)
+ elapsed_ms = (time.perf_counter() - started) * 1000.0
+ if repetition == 0:
+ neighbors.append(batch_neighbors)
+ batch_latency_ms.append(elapsed_ms)
+ query_counts.append(query_batch.shape[0])
+
+ total_seconds = sum(batch_latency_ms) / 1000.0
+ timed_query_count = int(queries.shape[0]) * repetitions
+ # Weight percentile samples by the number of queries in each batch. This
+ # prevents a final short batch from receiving the same percentile weight
+ # as a full batch (for example, 16 queries versus 128).
+ per_query_latency_ms = [
+ latency / count
+ for latency, count in zip(batch_latency_ms, query_counts, strict=True)
+ for _ in range(count)
+ ]
+ summary = {
+ "unique_query_count": int(queries.shape[0]),
+ "timed_query_count": timed_query_count,
+ "repetitions": repetitions,
+ "batch_size": batch_size,
+ "batch_count": len(batch_latency_ms),
+ "warmup_batches": warmup_batches,
+ "total_seconds": total_seconds,
+ "qps": timed_query_count / total_seconds if total_seconds else 0.0,
+ "batch_latency_ms": {
+ "p50": percentile(batch_latency_ms, 0.50),
+ "p95": percentile(batch_latency_ms, 0.95),
+ "p99": percentile(batch_latency_ms, 0.99),
+ "mean": statistics.fmean(batch_latency_ms),
+ },
+ "per_query_latency_ms": {
+ "p50": percentile(per_query_latency_ms, 0.50),
+ "p95": percentile(per_query_latency_ms, 0.95),
+ "p99": percentile(per_query_latency_ms, 0.99),
+ "mean": statistics.fmean(per_query_latency_ms),
+ },
+ "raw_batch_latency_ms": batch_latency_ms,
+ }
+ return np.concatenate(neighbors, axis=0), summary
+
+
+def parse_json_object(value: str, option: str) -> dict[str, Any]:
+ try:
+ parsed = json.loads(value)
+ except json.JSONDecodeError as exc:
+ raise argparse.ArgumentTypeError(f"{option} must be valid JSON: {exc}") from exc
+ if not isinstance(parsed, dict):
+ raise argparse.ArgumentTypeError(f"{option} must be a JSON object")
+ return parsed
+
+
+def parse_positive_int_list(value: str, option: str) -> list[int]:
+ try:
+ values = [int(item.strip()) for item in value.split(",") if item.strip()]
+ except ValueError as exc:
+ raise argparse.ArgumentTypeError(
+ f"{option} must be a comma-separated list of integers"
+ ) from exc
+ if not values or any(item <= 0 for item in values):
+ raise argparse.ArgumentTypeError(f"{option} values must be positive")
+ if len(values) != len(set(values)):
+ raise argparse.ArgumentTypeError(f"{option} cannot contain duplicates")
+ return values
+
+
+def cagra_search_variants(args: argparse.Namespace) -> list[dict[str, Any]]:
+ minimum_itopk = ((args.k + 31) // 32) * 32
+ itopk_sizes = args.cagra_itopk_sizes or [int(args.cagra_search_params.get("itopk_size", 64))]
+ configured_width = args.cagra_search_params.get("search_width")
+ search_widths: list[int | None] = args.cagra_search_widths or [
+ int(configured_width) if configured_width is not None else None
+ ]
+ variants = []
+ for search_width in search_widths:
+ for itopk_size in itopk_sizes:
+ params = dict(args.cagra_search_params)
+ params["itopk_size"] = max(itopk_size, minimum_itopk)
+ if search_width is not None:
+ params["search_width"] = search_width
+ variants.append(params)
+ return variants
+
+
+def runtime_metadata() -> dict[str, Any]:
+ metadata: dict[str, Any] = {
+ "timestamp": utc_now(),
+ "platform": platform.platform(),
+ "python": sys.version,
+ "numpy": np.__version__,
+ "cpu_count": os.cpu_count(),
+ "cpu_affinity_count": (
+ len(os.sched_getaffinity(0)) if hasattr(os, "sched_getaffinity") else None
+ ),
+ "cpu_model": cpu_model(),
+ }
+ try:
+ revision = subprocess.run(
+ ["git", "rev-parse", "HEAD"],
+ cwd=REPO_ROOT,
+ check=True,
+ capture_output=True,
+ text=True,
+ )
+ status = subprocess.run(
+ ["git", "status", "--porcelain"],
+ cwd=REPO_ROOT,
+ check=True,
+ capture_output=True,
+ text=True,
+ )
+ metadata["git_revision"] = revision.stdout.strip()
+ metadata["git_dirty"] = bool(status.stdout.strip())
+ except (OSError, subprocess.SubprocessError):
+ metadata["git_revision"] = None
+ metadata["git_dirty"] = None
+ try:
+ import cupy as cp
+ import cuvs
+
+ device = cp.cuda.Device()
+ properties = cp.cuda.runtime.getDeviceProperties(device.id)
+ name = properties.get("name", "unknown")
+ if isinstance(name, bytes):
+ name = name.decode(errors="replace")
+ metadata["gpu"] = {
+ "device_id": device.id,
+ "name": name,
+ "total_memory_bytes": int(properties.get("totalGlobalMem", 0)),
+ "cuda_driver_api_version": int(cp.cuda.runtime.driverGetVersion()),
+ "cuda_runtime_version": int(cp.cuda.runtime.runtimeGetVersion()),
+ }
+ metadata["cupy"] = cp.__version__
+ metadata["cuvs"] = getattr(cuvs, "__version__", "unknown")
+ except Exception as exc:
+ metadata["gpu"] = None
+ metadata["gpu_probe_error"] = str(exc)
+ return metadata
+
+
+def make_backend(name: str, args: argparse.Namespace) -> Backend:
+ if name == "native":
+ return NativeFlatBackend(args.dimension, args.metric, args.native_ingest_batch_size)
+ if name == "cuvs_brute_force":
+ return CuVSBackend("brute_force", args.metric, {}, {})
+ if name == "cuvs_cagra":
+ return CuVSBackend(
+ "cagra",
+ args.metric,
+ args.cagra_build_params,
+ args.cagra_search_params,
+ )
+ raise ValueError(f"Unsupported backend: {name}")
+
+
+def print_summary(results: Sequence[dict[str, Any]]) -> None:
+ print(
+ "\nbackend build_s first_q_ms p50_ms p95_ms qps recall"
+ )
+ print("---------------------------- -------- ---------- ------- ------- -------- -------")
+ for result in results:
+ search = result["search"]
+ label = result["backend"]
+ if result.get("cagra_search_params"):
+ itopk_size = result["cagra_search_params"].get("itopk_size")
+ search_width = result["cagra_search_params"].get("search_width", "auto")
+ label = f"{label}[i={itopk_size},w={search_width}]"
+ print(
+ f"{label:<28} "
+ f"{result['build_seconds']:>8.3f} "
+ f"{result['first_search_per_query_ms']:>10.3f} "
+ f"{search['per_query_latency_ms']['p50']:>7.3f} "
+ f"{search['per_query_latency_ms']['p95']:>7.3f} "
+ f"{search['qps']:>8.1f} "
+ f"{result.get('recall_at_k', 1.0):>7.4f}"
+ )
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--backends",
+ default="native,cuvs_brute_force,cuvs_cagra",
+ help=f"Comma-separated backends: {','.join(SUPPORTED_BACKENDS)}",
+ )
+ parser.add_argument("--vector-count", type=int, default=10_000)
+ parser.add_argument("--dimension", type=int, default=128)
+ parser.add_argument("--query-count", type=int, default=100)
+ parser.add_argument("--k", type=int, default=10)
+ parser.add_argument("--metric", choices=("cosine", "l2"), default="cosine")
+ parser.add_argument(
+ "--ann-benchmarks-hdf5",
+ type=Path,
+ help=(
+ "Use train/test/neighbors from an ann-benchmarks HDF5 file instead of "
+ "generating random vectors"
+ ),
+ )
+ parser.add_argument(
+ "--ann-vector-limit",
+ type=int,
+ help="Use only the first N public-dataset vectors; disables supplied ground truth",
+ )
+ parser.add_argument(
+ "--ann-query-limit",
+ type=int,
+ help="Use only the first N public-dataset queries",
+ )
+ parser.add_argument("--query-batch-size", type=int, default=1)
+ parser.add_argument("--warmup-batches", type=int, default=10)
+ parser.add_argument("--search-repetitions", type=int, default=1)
+ parser.add_argument("--seed", type=int, default=42)
+ parser.add_argument("--data-root", type=Path, default=Path("/tmp/openviking-cuvs-benchmark"))
+ parser.add_argument("--output", type=Path)
+ parser.add_argument("--force-generate", action="store_true")
+ parser.add_argument(
+ "--no-preload-dataset",
+ action="store_true",
+ help="Do not read the full memory-mapped dataset before backend build timing",
+ )
+ parser.add_argument("--generation-chunk-size", type=int, default=16_384)
+ parser.add_argument("--native-ingest-batch-size", type=int, default=2_048)
+ parser.add_argument(
+ "--cagra-build-params",
+ type=lambda value: parse_json_object(value, "--cagra-build-params"),
+ default={"graph_degree": 32, "intermediate_graph_degree": 64},
+ )
+ parser.add_argument(
+ "--cagra-search-params",
+ type=lambda value: parse_json_object(value, "--cagra-search-params"),
+ default={"itopk_size": 64},
+ )
+ parser.add_argument(
+ "--cagra-itopk-sizes",
+ type=lambda value: parse_positive_int_list(value, "--cagra-itopk-sizes"),
+ help=(
+ "Comma-separated itopk_size sweep. CAGRA is built once and searched once per "
+ "value; other --cagra-search-params are shared"
+ ),
+ )
+ parser.add_argument(
+ "--cagra-search-widths",
+ type=lambda value: parse_positive_int_list(value, "--cagra-search-widths"),
+ help=(
+ "Comma-separated search_width sweep. Combined with --cagra-itopk-sizes "
+ "as a Cartesian product while sharing one CAGRA build"
+ ),
+ )
+ return parser
+
+
+def validate_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> list[str]:
+ for name in (
+ "vector_count",
+ "dimension",
+ "query_count",
+ "k",
+ "query_batch_size",
+ "generation_chunk_size",
+ "native_ingest_batch_size",
+ "search_repetitions",
+ ):
+ if getattr(args, name) <= 0:
+ parser.error(f"--{name.replace('_', '-')} must be positive")
+ if args.ann_benchmarks_hdf5 is None and args.k > args.vector_count:
+ parser.error("--k cannot exceed --vector-count")
+ for name in ("ann_vector_limit", "ann_query_limit"):
+ value = getattr(args, name)
+ if value is not None and value <= 0:
+ parser.error(f"--{name.replace('_', '-')} must be positive")
+ if args.ann_benchmarks_hdf5 is None and (
+ args.ann_vector_limit is not None or args.ann_query_limit is not None
+ ):
+ parser.error("--ann-vector-limit/--ann-query-limit require --ann-benchmarks-hdf5")
+ backends = [item.strip() for item in args.backends.split(",") if item.strip()]
+ unknown = sorted(set(backends).difference(SUPPORTED_BACKENDS))
+ if unknown:
+ parser.error(f"Unsupported backends: {', '.join(unknown)}")
+ if len(backends) != len(set(backends)):
+ parser.error("--backends cannot contain duplicates")
+ return backends
+
+
+def main() -> None:
+ parser = build_parser()
+ args = parser.parse_args()
+ backends = validate_args(parser, args)
+ # Run an exact backend first so approximate results always have a reference.
+ backends.sort(key=lambda name: (name not in EXACT_BACKENDS, name))
+
+ if args.ann_benchmarks_hdf5 is not None:
+ files = prepare_ann_benchmarks_dataset(
+ args.data_root,
+ source=args.ann_benchmarks_hdf5,
+ metric=args.metric,
+ vector_limit=args.ann_vector_limit,
+ query_limit=args.ann_query_limit,
+ generation_chunk_size=args.generation_chunk_size,
+ force=args.force_generate,
+ )
+ else:
+ files = prepare_dataset(
+ args.data_root,
+ vector_count=args.vector_count,
+ dimension=args.dimension,
+ query_count=args.query_count,
+ metric=args.metric,
+ seed=args.seed,
+ generation_chunk_size=args.generation_chunk_size,
+ force=args.force_generate,
+ )
+ dataset = np.load(files.dataset, mmap_mode="r", allow_pickle=False)
+ queries = np.load(files.queries, mmap_mode="r", allow_pickle=False)
+ dataset_metadata = json.loads(files.metadata.read_text())
+ args.dimension = int(dataset.shape[1])
+ if args.k > dataset.shape[0]:
+ parser.error(f"--k cannot exceed dataset vector count ({dataset.shape[0]})")
+
+ reference_neighbors: np.ndarray | None = None
+ reference_backend: str | None = None
+ if files.ground_truth is not None:
+ supplied_ground_truth = np.load(files.ground_truth, mmap_mode="r", allow_pickle=False)
+ if supplied_ground_truth.shape[0] != queries.shape[0]:
+ parser.error("supplied ground truth query count does not match the query matrix")
+ if args.k > supplied_ground_truth.shape[1]:
+ parser.error(
+ f"--k cannot exceed supplied ground truth width ({supplied_ground_truth.shape[1]})"
+ )
+ reference_neighbors = supplied_ground_truth[:, : args.k]
+ reference_backend = "ann-benchmarks_ground_truth"
+ if (
+ "cuvs_cagra" in backends
+ and reference_neighbors is None
+ and not set(backends).intersection(EXACT_BACKENDS)
+ ):
+ parser.error(
+ "CAGRA requires native/cuvs_brute_force or a full ann-benchmarks dataset "
+ "with supplied ground truth"
+ )
+
+ cagra_variants = cagra_search_variants(args)
+ variant_keys = [json.dumps(value, sort_keys=True) for value in cagra_variants]
+ if len(variant_keys) != len(set(variant_keys)):
+ parser.error("CAGRA search sweep contains duplicate effective parameter sets")
+
+ preload_seconds = 0.0
+ preload_checksum = None
+ if not args.no_preload_dataset:
+ preload_seconds, preload_checksum = preload_dataset(dataset, args.generation_chunk_size)
+ result_document: dict[str, Any] = {
+ "format_version": 2,
+ "runtime": runtime_metadata(),
+ "dataset": {
+ "path": str(files.dataset.relative_to(args.data_root)),
+ "query_path": str(files.queries.relative_to(args.data_root)),
+ "metadata_path": str(files.metadata.relative_to(args.data_root)),
+ "ground_truth_path": (
+ str(files.ground_truth.relative_to(args.data_root))
+ if files.ground_truth is not None
+ else None
+ ),
+ "generated_seconds": files.generated_seconds,
+ "preload_seconds": preload_seconds,
+ "preload_checksum": preload_checksum,
+ "reused": files.reused,
+ "kind": dataset_metadata.get("dataset_kind", "random"),
+ "name": dataset_metadata.get("dataset_name"),
+ "source_sha256": dataset_metadata.get("source_sha256"),
+ "source_distance": dataset_metadata.get("source_distance"),
+ "vector_count": int(dataset.shape[0]),
+ "dimension": int(dataset.shape[1]),
+ "query_count": int(queries.shape[0]),
+ "metric": args.metric,
+ "seed": args.seed if args.ann_benchmarks_hdf5 is None else None,
+ },
+ "parameters": {
+ "k": args.k,
+ "query_batch_size": args.query_batch_size,
+ "warmup_batches": args.warmup_batches,
+ "search_repetitions": args.search_repetitions,
+ "native_ingest_batch_size": args.native_ingest_batch_size,
+ "cagra_build_params": args.cagra_build_params,
+ "cagra_search_params": args.cagra_search_params,
+ "cagra_itopk_sizes": args.cagra_itopk_sizes,
+ "cagra_search_widths": args.cagra_search_widths,
+ },
+ "results": [],
+ }
+
+ for backend_name in backends:
+ print(
+ f"Building {backend_name} for {dataset.shape[0]} x {dataset.shape[1]} ...",
+ flush=True,
+ )
+ backend = make_backend(backend_name, args)
+ rss_before = current_rss_bytes()
+ gpu_before = backend.gpu_memory_used_bytes()
+ build_started = time.perf_counter()
+ try:
+ backend.build(dataset)
+ build_seconds = time.perf_counter() - build_started
+ rss_after = current_rss_bytes()
+ gpu_after = backend.gpu_memory_used_bytes()
+
+ search_variants = cagra_variants if backend_name == "cuvs_cagra" else [None]
+ for variant_index, search_params in enumerate(search_variants):
+ if search_params is not None:
+ if not isinstance(backend, CuVSBackend):
+ raise TypeError("CAGRA search parameters require a cuVS backend")
+ backend.set_search_params(search_params)
+
+ first_query_count = min(args.query_batch_size, queries.shape[0])
+ first_started = time.perf_counter()
+ backend.search(queries[:first_query_count], args.k)
+ first_search_batch_ms = (time.perf_counter() - first_started) * 1000.0
+
+ neighbors, search_summary = run_search(
+ backend,
+ queries,
+ k=args.k,
+ batch_size=args.query_batch_size,
+ warmup_batches=args.warmup_batches,
+ repetitions=args.search_repetitions,
+ )
+ result = {
+ "backend": backend_name,
+ "build_seconds": build_seconds,
+ "build_shared_across_variants": len(search_variants) > 1,
+ "search_variant_index": variant_index,
+ "first_search_batch_ms": first_search_batch_ms,
+ "first_search_per_query_ms": first_search_batch_ms / first_query_count,
+ "rss_before_bytes": rss_before,
+ "rss_after_build_bytes": rss_after,
+ "rss_delta_bytes": (
+ rss_after - rss_before
+ if rss_before is not None and rss_after is not None
+ else None
+ ),
+ "gpu_used_before_bytes": gpu_before,
+ "gpu_used_after_build_bytes": gpu_after,
+ "gpu_used_delta_bytes": (
+ gpu_after - gpu_before
+ if gpu_before is not None and gpu_after is not None
+ else None
+ ),
+ "cagra_search_params": search_params,
+ "search": search_summary,
+ }
+ if reference_neighbors is None and backend_name in EXACT_BACKENDS:
+ reference_neighbors = neighbors
+ reference_backend = backend_name
+ result["recall_at_k"] = 1.0
+ elif reference_neighbors is not None:
+ result["recall_at_k"] = recall_at_k(neighbors, reference_neighbors, args.k)
+ result["ground_truth_backend"] = reference_backend
+ result_document["results"].append(result)
+ finally:
+ backend.close()
+
+ output = args.output
+ if output is None:
+ result_dir = args.data_root / "results"
+ result_dir.mkdir(parents=True, exist_ok=True)
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+ output = result_dir / (
+ f"index-n{dataset.shape[0]}-d{dataset.shape[1]}-q{queries.shape[0]}-"
+ f"b{args.query_batch_size}-{stamp}.json"
+ )
+ output.parent.mkdir(parents=True, exist_ok=True)
+ output.write_text(json.dumps(result_document, indent=2, sort_keys=True) + "\n")
+ print_summary(result_document["results"])
+ print(f"\nWrote {output}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/benchmark/cuvs/run_service_concurrency_benchmark.py b/benchmark/cuvs/run_service_concurrency_benchmark.py
new file mode 100644
index 000000000..947e18673
--- /dev/null
+++ b/benchmark/cuvs/run_service_concurrency_benchmark.py
@@ -0,0 +1,585 @@
+#!/usr/bin/env python3
+"""Benchmark OpenViking's async vector-service facade under concurrency.
+
+This is the pre-embedding service layer: requests go through
+VikingVectorIndexBackend and its asyncio.to_thread adapter, but use precomputed
+query vectors so embedding and HTTP do not obscure vector-search scheduling.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import gc
+import json
+import os
+import shutil
+import statistics
+import sys
+import tempfile
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+import numpy as np
+
+BENCHMARK_DIR = Path(__file__).resolve().parent
+if str(BENCHMARK_DIR) not in sys.path:
+ sys.path.insert(0, str(BENCHMARK_DIR))
+
+from run_collection_benchmark import parse_positive_int_list # noqa: E402
+from run_index_benchmark import percentile, prepare_dataset, runtime_metadata # noqa: E402
+
+from openviking.server.identity import RequestContext, Role # noqa: E402
+from openviking.storage.viking_vector_index_backend import ( # noqa: E402
+ VikingVectorIndexBackend,
+)
+from openviking_cli.session.user_id import UserIdentifier # noqa: E402
+from openviking_cli.utils.config.vectordb_config import ( # noqa: E402
+ CuVSConfig,
+ VectorDBBackendConfig,
+)
+
+SUPPORTED_BACKENDS = ("native", "cuvs_brute_force")
+ACCOUNT_ID = "benchmark"
+
+
+def collection_schema(collection_name: str, dimension: int) -> dict[str, Any]:
+ return {
+ "CollectionName": collection_name,
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": dimension},
+ {"FieldName": "account_id", "FieldType": "string"},
+ {"FieldName": "uniform_bucket", "FieldType": "int64"},
+ {"FieldName": "row_number", "FieldType": "int64"},
+ ],
+ "ScalarIndex": ["account_id", "uniform_bucket", "row_number"],
+ }
+
+
+def make_record(row_index: int, vector: Sequence[float]) -> dict[str, Any]:
+ return {
+ "id": f"record-{row_index}",
+ "vector": list(vector),
+ "account_id": ACCOUNT_ID,
+ "uniform_bucket": row_index % 1000,
+ "row_number": row_index,
+ }
+
+
+def make_config(
+ backend: str,
+ *,
+ project_path: Path,
+ collection_name: str,
+ dimension: int,
+ filter_cache_size: int,
+) -> VectorDBBackendConfig:
+ common = {
+ "name": collection_name,
+ "path": str(project_path),
+ "index_name": "default",
+ "distance_metric": "cosine",
+ "dimension": dimension,
+ "sparse_weight": 0.0,
+ }
+ if backend == "native":
+ return VectorDBBackendConfig(backend="local", **common)
+ if backend == "cuvs_brute_force":
+ return VectorDBBackendConfig(
+ backend="cuvs",
+ cuvs=CuVSConfig(
+ algorithm="brute_force",
+ fallback_to_native=False,
+ filter_cache_size=filter_cache_size,
+ ),
+ **common,
+ )
+ raise ValueError(f"Unsupported backend: {backend}")
+
+
+def concurrent_summary(
+ latencies_ms: Sequence[float],
+ *,
+ wall_seconds: float,
+ request_count: int,
+ success_count: int,
+ error_count: int,
+) -> dict[str, Any]:
+ return {
+ "request_count": request_count,
+ "success_count": success_count,
+ "error_count": error_count,
+ "wall_seconds": wall_seconds,
+ "qps": success_count / wall_seconds if wall_seconds else 0.0,
+ "latency_ms": {
+ "mean": statistics.fmean(latencies_ms) if latencies_ms else 0.0,
+ "p50": percentile(latencies_ms, 0.50),
+ "p95": percentile(latencies_ms, 0.95),
+ "p99": percentile(latencies_ms, 0.99),
+ "max": max(latencies_ms, default=0.0),
+ },
+ "raw_latency_ms": list(latencies_ms),
+ }
+
+
+async def run_request_set(
+ manager: Any,
+ ctx: RequestContext,
+ queries: np.ndarray,
+ *,
+ concurrency: int,
+ request_count: int,
+ k: int,
+ filter_factory: Callable[[int], dict[str, Any] | None],
+) -> dict[str, Any]:
+ semaphore = asyncio.Semaphore(concurrency)
+ start_event = asyncio.Event()
+ query_lists = [row.tolist() for row in queries]
+
+ async def one_request(request_index: int) -> tuple[float, str | None]:
+ await start_event.wait()
+ async with semaphore:
+ started = time.perf_counter()
+ try:
+ records = await manager.query(
+ query_vector=query_lists[request_index % len(query_lists)],
+ filter=filter_factory(request_index),
+ limit=k,
+ output_fields=["id"],
+ ctx=ctx,
+ )
+ latency_ms = (time.perf_counter() - started) * 1000.0
+ if len(records) != k:
+ return latency_ms, f"expected {k} results, received {len(records)}"
+ return latency_ms, None
+ except Exception as exc:
+ latency_ms = (time.perf_counter() - started) * 1000.0
+ return latency_ms, f"{type(exc).__name__}: {exc}"
+
+ tasks = [asyncio.create_task(one_request(index)) for index in range(request_count)]
+ await asyncio.sleep(0)
+ wall_started = time.perf_counter()
+ start_event.set()
+ outcomes = await asyncio.gather(*tasks)
+ wall_seconds = time.perf_counter() - wall_started
+ latencies = [latency for latency, _ in outcomes]
+ errors = [error for _, error in outcomes if error is not None]
+ result = concurrent_summary(
+ latencies,
+ wall_seconds=wall_seconds,
+ request_count=request_count,
+ success_count=request_count - len(errors),
+ error_count=len(errors),
+ )
+ result["errors"] = errors[:10]
+ return result
+
+
+def uniform_filter(selectivity: float) -> dict[str, Any]:
+ upper_bound = max(1, int(1000 * selectivity))
+ return {"op": "range", "field": "uniform_bucket", "lt": upper_bound}
+
+
+def unique_filter(request_index: int, vector_count: int, salt: int) -> dict[str, Any]:
+ width = max(10, min(100, vector_count))
+ span = max(1, vector_count - width + 1)
+ start = ((request_index + salt) * 997) % span
+ return {
+ "op": "range",
+ "field": "row_number",
+ "gte": start,
+ "lt": start + width,
+ }
+
+
+async def ingest_dataset(
+ manager: VikingVectorIndexBackend,
+ dataset: np.ndarray,
+ *,
+ batch_size: int,
+) -> dict[str, Any]:
+ # Benchmark setup uses the shared adapter's batch API. Timed requests below
+ # go through the public async service facade.
+ adapter = manager._shared_adapter
+ started = time.perf_counter()
+ for start in range(0, dataset.shape[0], batch_size):
+ stop = min(start + batch_size, dataset.shape[0])
+ records = [make_record(index, dataset[index].tolist()) for index in range(start, stop)]
+ await asyncio.to_thread(adapter.upsert, records)
+ total_seconds = time.perf_counter() - started
+ return {
+ "total_seconds": total_seconds,
+ "records_per_second": dataset.shape[0] / total_seconds if total_seconds else 0.0,
+ }
+
+
+async def warm_query(
+ manager: VikingVectorIndexBackend,
+ ctx: RequestContext,
+ query: Sequence[float],
+ *,
+ filter: dict[str, Any] | None,
+ k: int,
+) -> float:
+ started = time.perf_counter()
+ records = await manager.query(
+ query_vector=list(query),
+ filter=filter,
+ limit=k,
+ output_fields=["id"],
+ ctx=ctx,
+ )
+ if len(records) != k:
+ raise RuntimeError(f"Warm query returned {len(records)} records, expected {k}")
+ return (time.perf_counter() - started) * 1000.0
+
+
+async def run_cached_scenario(
+ manager: VikingVectorIndexBackend,
+ ctx: RequestContext,
+ queries: np.ndarray,
+ *,
+ name: str,
+ filter: dict[str, Any] | None,
+ concurrency_levels: Sequence[int],
+ request_count: int,
+ k: int,
+) -> dict[str, Any]:
+ initial_filter_ms = await warm_query(manager, ctx, queries[0], filter=filter, k=k)
+ results = []
+ for concurrency in concurrency_levels:
+ await warm_query(manager, ctx, queries[0], filter=filter, k=k)
+ result = await run_request_set(
+ manager,
+ ctx,
+ queries,
+ concurrency=concurrency,
+ request_count=request_count,
+ k=k,
+ filter_factory=lambda _index, value=filter: value,
+ )
+ result["concurrency"] = concurrency
+ results.append(result)
+ return {
+ "name": name,
+ "filter_mode": "cached",
+ "filter": filter,
+ "initial_filter_query_ms": initial_filter_ms,
+ "results": results,
+ }
+
+
+async def run_unique_filter_scenario(
+ manager: VikingVectorIndexBackend,
+ ctx: RequestContext,
+ queries: np.ndarray,
+ *,
+ vector_count: int,
+ concurrency_levels: Sequence[int],
+ request_count: int,
+ k: int,
+) -> dict[str, Any]:
+ results = []
+ for matrix_index, concurrency in enumerate(concurrency_levels):
+ salt = (matrix_index + 1) * 10_000
+ result = await run_request_set(
+ manager,
+ ctx,
+ queries,
+ concurrency=concurrency,
+ request_count=request_count,
+ k=k,
+ filter_factory=lambda index, s=salt: unique_filter(index, vector_count, s),
+ )
+ result["concurrency"] = concurrency
+ results.append(result)
+ return {
+ "name": "unique_filter",
+ "filter_mode": "new_per_request",
+ "candidate_window": max(10, min(100, vector_count)),
+ "results": results,
+ }
+
+
+async def run_post_mutation_scenario(
+ manager: VikingVectorIndexBackend,
+ ctx: RequestContext,
+ dataset: np.ndarray,
+ queries: np.ndarray,
+ *,
+ concurrency_levels: Sequence[int],
+ k: int,
+) -> dict[str, Any]:
+ results = []
+ for matrix_index, concurrency in enumerate(concurrency_levels):
+ row_index = matrix_index % dataset.shape[0]
+ record = make_record(row_index, queries[matrix_index % len(queries)].tolist())
+ write_started = time.perf_counter()
+ record_id = await manager.upsert(record, ctx=ctx)
+ write_ms = (time.perf_counter() - write_started) * 1000.0
+ if not record_id:
+ raise RuntimeError("Post-mutation upsert failed")
+ result = await run_request_set(
+ manager,
+ ctx,
+ queries,
+ concurrency=concurrency,
+ request_count=concurrency,
+ k=k,
+ filter_factory=lambda _index: None,
+ )
+ result["concurrency"] = concurrency
+ result["write_ms"] = write_ms
+ results.append(result)
+ return {
+ "name": "post_mutation_burst",
+ "filter_mode": "tenant_filter_after_cache_invalidation",
+ "results": results,
+ }
+
+
+async def run_backend(
+ backend: str,
+ dataset: np.ndarray,
+ queries: np.ndarray,
+ *,
+ run_root: Path,
+ ingest_batch_size: int,
+ filter_cache_size: int,
+ concurrency_levels: Sequence[int],
+ cached_request_count: int,
+ unique_request_count: int,
+ k: int,
+) -> dict[str, Any]:
+ collection_name = f"service_benchmark_{backend}"
+ config = make_config(
+ backend,
+ project_path=run_root / backend,
+ collection_name=collection_name,
+ dimension=dataset.shape[1],
+ filter_cache_size=filter_cache_size,
+ )
+ manager = VikingVectorIndexBackend(config)
+ ctx = RequestContext(user=UserIdentifier(ACCOUNT_ID, "user"), role=Role.USER)
+ try:
+ created = await manager.create_collection(
+ collection_name,
+ collection_schema(collection_name, dataset.shape[1]),
+ )
+ if not created:
+ raise RuntimeError(f"Collection already exists for backend {backend}")
+ ingest = await ingest_dataset(manager, dataset, batch_size=ingest_batch_size)
+ record_count = await manager.count(ctx=ctx)
+ if record_count != dataset.shape[0]:
+ raise RuntimeError(
+ f"Collection count mismatch for {backend}: {record_count} != {dataset.shape[0]}"
+ )
+
+ scenarios = [
+ await run_cached_scenario(
+ manager,
+ ctx,
+ queries,
+ name="tenant_cached",
+ filter=None,
+ concurrency_levels=concurrency_levels,
+ request_count=cached_request_count,
+ k=k,
+ ),
+ await run_cached_scenario(
+ manager,
+ ctx,
+ queries,
+ name="tenant_uniform_10pct_cached",
+ filter=uniform_filter(0.10),
+ concurrency_levels=concurrency_levels,
+ request_count=cached_request_count,
+ k=k,
+ ),
+ await run_unique_filter_scenario(
+ manager,
+ ctx,
+ queries,
+ vector_count=dataset.shape[0],
+ concurrency_levels=concurrency_levels,
+ request_count=unique_request_count,
+ k=k,
+ ),
+ await run_post_mutation_scenario(
+ manager,
+ ctx,
+ dataset,
+ queries,
+ concurrency_levels=concurrency_levels,
+ k=k,
+ ),
+ ]
+ return {
+ "backend": backend,
+ "ingest": ingest,
+ "record_count": record_count,
+ "scenarios": scenarios,
+ }
+ finally:
+ await manager.close()
+ gc.collect()
+
+
+def print_summary(results: Sequence[dict[str, Any]]) -> None:
+ print(
+ "\nbackend scenario conc p50_ms p99_ms qps errors"
+ )
+ print(
+ "---------------------- ------------------------------- ---- ---------- ---------- -------- ------"
+ )
+ for backend_result in results:
+ for scenario in backend_result["scenarios"]:
+ for result in scenario["results"]:
+ latency = result["latency_ms"]
+ print(
+ f"{backend_result['backend']:<22} {scenario['name']:<31} "
+ f"{result['concurrency']:>4} {latency['p50']:>10.3f} "
+ f"{latency['p99']:>10.3f} {result['qps']:>8.1f} "
+ f"{result['error_count']:>6}"
+ )
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--backends", default="native,cuvs_brute_force")
+ parser.add_argument("--vector-count", type=int, default=10_000)
+ parser.add_argument("--dimension", type=int, default=128)
+ parser.add_argument("--query-count", type=int, default=64)
+ parser.add_argument("--k", type=int, default=10)
+ parser.add_argument("--seed", type=int, default=42)
+ parser.add_argument("--ingest-batch-size", type=int, default=256)
+ parser.add_argument("--filter-cache-size", type=int, default=16)
+ parser.add_argument(
+ "--concurrency",
+ type=lambda value: parse_positive_int_list(value, "--concurrency"),
+ default=[1, 4, 16, 32, 64],
+ )
+ parser.add_argument("--cached-request-count", type=int, default=200)
+ parser.add_argument("--unique-request-count", type=int, default=32)
+ parser.add_argument("--data-root", type=Path, default=Path("/tmp/openviking-cuvs-benchmark"))
+ parser.add_argument("--output", type=Path)
+ parser.add_argument("--keep-collections", action="store_true")
+ return parser
+
+
+def validate_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> list[str]:
+ for name in (
+ "vector_count",
+ "dimension",
+ "query_count",
+ "k",
+ "ingest_batch_size",
+ "cached_request_count",
+ "unique_request_count",
+ ):
+ if getattr(args, name) <= 0:
+ parser.error(f"--{name.replace('_', '-')} must be positive")
+ if args.k > args.vector_count:
+ parser.error("--k cannot exceed --vector-count")
+ if args.filter_cache_size < 0:
+ parser.error("--filter-cache-size cannot be negative")
+ backends = [item.strip() for item in args.backends.split(",") if item.strip()]
+ if not backends:
+ parser.error("--backends cannot be empty")
+ unknown = sorted(set(backends).difference(SUPPORTED_BACKENDS))
+ if unknown:
+ parser.error(f"Unsupported backends: {', '.join(unknown)}")
+ if len(backends) != len(set(backends)):
+ parser.error("--backends cannot contain duplicates")
+ return backends
+
+
+async def async_main(args: argparse.Namespace, backends: Sequence[str]) -> dict[str, Any]:
+ files = prepare_dataset(
+ args.data_root,
+ vector_count=args.vector_count,
+ dimension=args.dimension,
+ query_count=args.query_count,
+ metric="cosine",
+ seed=args.seed,
+ generation_chunk_size=16_384,
+ force=False,
+ )
+ dataset = np.load(files.dataset, mmap_mode="r", allow_pickle=False)
+ queries = np.load(files.queries, mmap_mode="r", allow_pickle=False)
+ collection_root = args.data_root / "service-runs"
+ collection_root.mkdir(parents=True, exist_ok=True)
+ run_root = Path(tempfile.mkdtemp(prefix="run-", dir=collection_root))
+ results = []
+ try:
+ for backend in sorted(backends, key=SUPPORTED_BACKENDS.index):
+ print(f"Running service concurrency benchmark for {backend} ...", flush=True)
+ results.append(
+ await run_backend(
+ backend,
+ dataset,
+ queries,
+ run_root=run_root,
+ ingest_batch_size=args.ingest_batch_size,
+ filter_cache_size=args.filter_cache_size,
+ concurrency_levels=args.concurrency,
+ cached_request_count=args.cached_request_count,
+ unique_request_count=args.unique_request_count,
+ k=args.k,
+ )
+ )
+ return {
+ "format_version": 1,
+ "runtime": runtime_metadata(),
+ "dataset": {
+ "kind": "random",
+ "vector_count": int(dataset.shape[0]),
+ "dimension": int(dataset.shape[1]),
+ "query_count": int(queries.shape[0]),
+ "metric": "cosine",
+ "seed": args.seed,
+ "reused": files.reused,
+ "generated_seconds": files.generated_seconds,
+ },
+ "parameters": {
+ "k": args.k,
+ "ingest_batch_size": args.ingest_batch_size,
+ "filter_cache_size": args.filter_cache_size,
+ "concurrency": args.concurrency,
+ "cached_request_count": args.cached_request_count,
+ "unique_request_count": args.unique_request_count,
+ "asyncio_default_thread_pool_limit": min(32, (os.cpu_count() or 1) + 4),
+ },
+ "results": results,
+ }
+ finally:
+ if not args.keep_collections:
+ shutil.rmtree(run_root, ignore_errors=True)
+
+
+def main() -> None:
+ parser = build_parser()
+ args = parser.parse_args()
+ backends = validate_args(parser, args)
+ output_document = asyncio.run(async_main(args, backends))
+ output = args.output
+ if output is None:
+ result_dir = args.data_root / "results"
+ result_dir.mkdir(parents=True, exist_ok=True)
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+ dataset = output_document["dataset"]
+ output = result_dir / (
+ f"service-n{dataset['vector_count']}-d{dataset['dimension']}-"
+ f"q{dataset['query_count']}-{stamp}.json"
+ )
+ output.parent.mkdir(parents=True, exist_ok=True)
+ output.write_text(json.dumps(output_document, indent=2, sort_keys=True) + "\n")
+ print_summary(output_document["results"])
+ print(f"\nWrote {output}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/benchmark/cuvs/summarize_collection_runs.py b/benchmark/cuvs/summarize_collection_runs.py
new file mode 100644
index 000000000..15017f20a
--- /dev/null
+++ b/benchmark/cuvs/summarize_collection_runs.py
@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Aggregate independent OpenViking collection benchmark processes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, Sequence
+
+BENCHMARK_DIR = Path(__file__).resolve().parent
+if str(BENCHMARK_DIR) not in sys.path:
+ sys.path.insert(0, str(BENCHMARK_DIR))
+
+from summarize_index_runs import canonical, metric_summary, nested_value # noqa: E402
+
+DATASET_FIELDS = ("kind", "vector_count", "dimension", "query_count", "metric", "seed")
+BACKEND_METRICS = {
+ "ingest_seconds": ("ingest", "total_seconds"),
+ "ingest_records_per_second": ("ingest", "records_per_second"),
+ "rss_ingest_delta_bytes": ("rss_ingest_delta_bytes",),
+ "gpu_search_delta_bytes": ("gpu_search_delta_bytes",),
+}
+PREBUILD_SELECTIVE_METRICS = {
+ "latency_ms": ("latency_ms",),
+ "result_count": ("result_count",),
+ "gpu_delta_bytes": ("gpu_delta_bytes",),
+}
+SEARCH_METRICS = {
+ "first_query_ms": ("first_query_ms",),
+ "warm_p50_ms": ("search", "latency_ms", "p50"),
+ "warm_p95_ms": ("search", "latency_ms", "p95"),
+ "warm_p99_ms": ("search", "latency_ms", "p99"),
+ "qps": ("search", "qps"),
+ "recall_at_k": ("recall_at_k",),
+}
+UPDATE_METRICS = {
+ "write_seconds": ("write_wall_seconds",),
+ "next_query_ms": ("next_query_ms",),
+ "warm_query_ms": ("warm_query_ms",),
+}
+DELETE_METRICS = {
+ "write_seconds": ("write_seconds",),
+ "next_query_ms": ("next_query_ms",),
+ "warm_query_ms": ("warm_query_ms",),
+}
+RESTART_METRICS = {
+ "close_seconds": ("close_seconds",),
+ "adapter_construct_seconds": ("adapter_construct_seconds",),
+ "first_query_ms": ("first_query_ms",),
+ "warm_query_ms": ("warm_query_ms",),
+}
+BACKEND_ORDER = {"native": 0, "cuvs_brute_force": 1, "auto_cuvs": 2}
+
+
+def dataset_signature(document: dict[str, Any]) -> dict[str, Any]:
+ dataset = document.get("dataset")
+ if not isinstance(dataset, dict):
+ raise ValueError("Result document is missing dataset metadata")
+ return {field: dataset.get(field) for field in DATASET_FIELDS}
+
+
+def load_result(path: Path) -> dict[str, Any]:
+ try:
+ document = json.loads(path.read_text())
+ except (OSError, json.JSONDecodeError) as exc:
+ raise ValueError(f"Cannot read benchmark result {path}: {exc}") from exc
+ if document.get("format_version") != 1:
+ raise ValueError(f"Unsupported collection result format in {path}")
+ if not isinstance(document.get("parameters"), dict):
+ raise ValueError(f"Result document {path} is missing parameters")
+ if not isinstance(document.get("results"), list) or not document["results"]:
+ raise ValueError(f"Result document {path} has no backend results")
+ return document
+
+
+def keyed_results(document: dict[str, Any], path: Path) -> dict[str, dict[str, Any]]:
+ keyed: dict[str, dict[str, Any]] = {}
+ for result in document["results"]:
+ backend = result.get("backend")
+ if not isinstance(backend, str) or not backend:
+ raise ValueError(f"Every result in {path} requires a non-empty backend")
+ if backend in keyed:
+ raise ValueError(f"Duplicate backend in {path}: {backend}")
+ keyed[backend] = result
+ return keyed
+
+
+def summarize_metrics(
+ documents: Sequence[dict[str, Any]], paths: dict[str, tuple[str, ...]]
+) -> dict[str, dict[str, float | int | None]]:
+ return {
+ name: metric_summary(nested_value(document, path) for document in documents)
+ for name, path in paths.items()
+ }
+
+
+def summarize_backend(backend: str, variants: Sequence[dict[str, Any]]) -> dict[str, Any]:
+ prebuild_entries = [variant.get("prebuild_selective_query") for variant in variants]
+ prebuild_selective_query = None
+ if any(entry is not None for entry in prebuild_entries):
+ if any(entry is None for entry in prebuild_entries):
+ raise ValueError(f"Prebuild selective-query coverage differs for backend {backend}")
+ entries = [entry for entry in prebuild_entries if entry is not None]
+ reference = entries[0]
+ metadata = {
+ "name": reference.get("name"),
+ "filter": reference.get("filter"),
+ "distribution": reference.get("distribution"),
+ "target_selectivity": reference.get("target_selectivity"),
+ }
+ if any(
+ {
+ "name": entry.get("name"),
+ "filter": entry.get("filter"),
+ "distribution": entry.get("distribution"),
+ "target_selectivity": entry.get("target_selectivity"),
+ }
+ != metadata
+ for entry in entries[1:]
+ ):
+ raise ValueError(f"Prebuild selective-query metadata differs for backend {backend}")
+ prebuild_selective_query = {
+ **metadata,
+ "metrics": summarize_metrics(entries, PREBUILD_SELECTIVE_METRICS),
+ }
+
+ search_maps = [{item["name"]: item for item in variant["searches"]} for variant in variants]
+ search_names = list(search_maps[0])
+ for search_map in search_maps[1:]:
+ if list(search_map) != search_names:
+ raise ValueError(f"Search scenarios differ for backend {backend}")
+
+ searches = []
+ for name in search_names:
+ entries = [search_map[name] for search_map in search_maps]
+ reference = entries[0]
+ metadata = {
+ "filter": reference.get("filter"),
+ "distribution": reference.get("distribution"),
+ "target_selectivity": reference.get("target_selectivity"),
+ }
+ if any(
+ {
+ "filter": entry.get("filter"),
+ "distribution": entry.get("distribution"),
+ "target_selectivity": entry.get("target_selectivity"),
+ }
+ != metadata
+ for entry in entries[1:]
+ ):
+ raise ValueError(f"Search scenario metadata differs for {backend}/{name}")
+ searches.append(
+ {"name": name, **metadata, "metrics": summarize_metrics(entries, SEARCH_METRICS)}
+ )
+
+ update_maps = [
+ {int(item["count"]): item for item in variant["lifecycle"]["updates"]}
+ for variant in variants
+ ]
+ update_counts = list(update_maps[0])
+ if any(list(update_map) != update_counts for update_map in update_maps[1:]):
+ raise ValueError(f"Mutation sizes differ for backend {backend}")
+ updates = [
+ {
+ "count": count,
+ "metrics": summarize_metrics(
+ [update_map[count] for update_map in update_maps], UPDATE_METRICS
+ ),
+ }
+ for count in update_counts
+ ]
+ return {
+ "backend": backend,
+ "metrics": summarize_metrics(variants, BACKEND_METRICS),
+ "prebuild_selective_query": prebuild_selective_query,
+ "searches": searches,
+ "lifecycle": {
+ "updates": updates,
+ "delete": {
+ "metrics": summarize_metrics(
+ [variant["lifecycle"]["delete"] for variant in variants], DELETE_METRICS
+ )
+ },
+ "restart": {
+ "metrics": summarize_metrics(
+ [variant["lifecycle"]["restart"] for variant in variants],
+ RESTART_METRICS,
+ )
+ },
+ },
+ }
+
+
+def summarize_files(paths: Sequence[Path]) -> dict[str, Any]:
+ if len(paths) < 2:
+ raise ValueError("At least two independent result files are required")
+ if len({path.resolve() for path in paths}) != len(paths):
+ raise ValueError("Independent result files cannot be repeated")
+
+ loaded = [(path, load_result(path)) for path in paths]
+ reference_dataset = dataset_signature(loaded[0][1])
+ reference_parameters = loaded[0][1]["parameters"]
+ grouped: dict[str, list[dict[str, Any]]] = defaultdict(list)
+ reference_backends: set[str] | None = None
+ runs = []
+ timestamps: set[str] = set()
+
+ for path, document in loaded:
+ if dataset_signature(document) != reference_dataset:
+ raise ValueError(f"Dataset metadata differs in {path}")
+ if document["parameters"] != reference_parameters:
+ raise ValueError(f"Benchmark parameters differ in {path}")
+ results = keyed_results(document, path)
+ if reference_backends is None:
+ reference_backends = set(results)
+ elif set(results) != reference_backends:
+ raise ValueError(f"Backends differ in {path}")
+ for backend, result in results.items():
+ grouped[backend].append(result)
+
+ runtime = document.get("runtime", {})
+ timestamp = runtime.get("timestamp")
+ if not isinstance(timestamp, str) or not timestamp:
+ raise ValueError(f"Result document {path} is missing a runtime timestamp")
+ if timestamp in timestamps:
+ raise ValueError(f"Duplicate process timestamp in {path}")
+ timestamps.add(timestamp)
+ runs.append(
+ {
+ "source": path.name,
+ "timestamp": timestamp,
+ "git_revision": runtime.get("git_revision"),
+ "git_dirty": runtime.get("git_dirty"),
+ "gpu_name": (runtime.get("gpu") or {}).get("name"),
+ "cpu_model": runtime.get("cpu_model"),
+ "cuvs": runtime.get("cuvs"),
+ "cupy": runtime.get("cupy"),
+ }
+ )
+
+ results = [
+ summarize_backend(backend, variants)
+ for backend, variants in sorted(
+ grouped.items(), key=lambda item: (BACKEND_ORDER.get(item[0], 99), item[0])
+ )
+ ]
+ runtime_fields = ("git_revision", "git_dirty", "gpu_name", "cpu_model", "cuvs", "cupy")
+ return {
+ "format_version": 1,
+ "run_count": len(loaded),
+ "dataset": reference_dataset,
+ "parameters": reference_parameters,
+ "runtime_consistency": {
+ field: [json.loads(value) for value in sorted({canonical(run[field]) for run in runs})]
+ for field in runtime_fields
+ },
+ "runs": runs,
+ "results": results,
+ }
+
+
+def format_median_mad(metric: dict[str, Any], precision: int) -> str:
+ if metric["median"] is None:
+ return "n/a"
+ return f"{metric['median']:.{precision}f} +/- {metric['mad']:.{precision}f}"
+
+
+def print_summary(summary: dict[str, Any]) -> None:
+ print(f"Independent runs: {summary['run_count']}")
+ for result in summary["results"]:
+ prebuild = result.get("prebuild_selective_query")
+ if prebuild is not None:
+ metrics = prebuild["metrics"]
+ print(
+ f"\n{result['backend']} prebuild selective query: "
+ f"latency {format_median_mad(metrics['latency_ms'], 3)} ms, "
+ f"GPU delta {format_median_mad(metrics['gpu_delta_bytes'], 0)} bytes"
+ )
+ print("\nbackend scenario p50_ms med+/-MAD qps med+/-MAD")
+ print("---------------------- -------------------- ------------------ -----------------")
+ for result in summary["results"]:
+ for search in result["searches"]:
+ metrics = search["metrics"]
+ print(
+ f"{result['backend']:<22} {search['name']:<20} "
+ f"{format_median_mad(metrics['warm_p50_ms'], 3):>18} "
+ f"{format_median_mad(metrics['qps'], 1):>17}"
+ )
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("inputs", nargs="+", type=Path, help="Independent result JSON files")
+ parser.add_argument("--output", type=Path, help="Write the aggregate JSON document")
+ return parser
+
+
+def main() -> None:
+ args = build_parser().parse_args()
+ try:
+ summary = summarize_files(args.inputs)
+ except ValueError as exc:
+ raise SystemExit(str(exc)) from exc
+ if args.output is not None:
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(json.dumps(summary, indent=2, sort_keys=True) + "\n")
+ print_summary(summary)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/benchmark/cuvs/summarize_index_runs.py b/benchmark/cuvs/summarize_index_runs.py
new file mode 100644
index 000000000..e8cc280c9
--- /dev/null
+++ b/benchmark/cuvs/summarize_index_runs.py
@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Aggregate independent cuVS index benchmark processes.
+
+The index harness reports within-process latency distributions. This helper
+combines several result files without treating their raw batches as one run,
+so process-level medians and median absolute deviations remain visible.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+DATASET_FIELDS = (
+ "kind",
+ "name",
+ "source_sha256",
+ "vector_count",
+ "dimension",
+ "query_count",
+ "metric",
+ "seed",
+)
+
+METRIC_PATHS = {
+ "build_seconds": ("build_seconds",),
+ "first_search_per_query_ms": ("first_search_per_query_ms",),
+ "warm_p50_ms": ("search", "per_query_latency_ms", "p50"),
+ "warm_p95_ms": ("search", "per_query_latency_ms", "p95"),
+ "warm_p99_ms": ("search", "per_query_latency_ms", "p99"),
+ "qps": ("search", "qps"),
+ "recall_at_k": ("recall_at_k",),
+ "rss_delta_bytes": ("rss_delta_bytes",),
+ "gpu_used_delta_bytes": ("gpu_used_delta_bytes",),
+}
+
+BACKEND_ORDER = {"native": 0, "cuvs_brute_force": 1, "cuvs_cagra": 2}
+
+
+def canonical(value: Any) -> str:
+ return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def nested_value(document: dict[str, Any], path: Sequence[str]) -> float | None:
+ value: Any = document
+ for part in path:
+ if not isinstance(value, dict) or part not in value:
+ return None
+ value = value[part]
+ if value is None:
+ return None
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ raise ValueError(f"Metric {'.'.join(path)} is not numeric")
+ return float(value)
+
+
+def metric_summary(values: Iterable[float | None]) -> dict[str, float | int | None]:
+ present = [value for value in values if value is not None]
+ if not present:
+ return {"count": 0, "median": None, "mad": None, "min": None, "max": None}
+ median = statistics.median(present)
+ absolute_deviations = [abs(value - median) for value in present]
+ return {
+ "count": len(present),
+ "median": median,
+ "mad": statistics.median(absolute_deviations),
+ "min": min(present),
+ "max": max(present),
+ }
+
+
+def variant_key(result: dict[str, Any]) -> tuple[str, str]:
+ backend = result.get("backend")
+ if not isinstance(backend, str) or not backend:
+ raise ValueError("Every result requires a non-empty backend")
+ search_params = result.get("cagra_search_params")
+ return backend, canonical(search_params)
+
+
+def variant_sort_key(key: tuple[str, str]) -> tuple[Any, ...]:
+ backend, encoded_search_params = key
+ search_params = json.loads(encoded_search_params) or {}
+ return (
+ BACKEND_ORDER.get(backend, len(BACKEND_ORDER)),
+ backend,
+ search_params.get("itopk_size", 0),
+ search_params.get("search_width", 0),
+ encoded_search_params,
+ )
+
+
+def dataset_signature(document: dict[str, Any]) -> dict[str, Any]:
+ dataset = document.get("dataset")
+ if not isinstance(dataset, dict):
+ raise ValueError("Result document is missing dataset metadata")
+ return {field: dataset.get(field) for field in DATASET_FIELDS}
+
+
+def load_result(path: Path) -> dict[str, Any]:
+ try:
+ document = json.loads(path.read_text())
+ except (OSError, json.JSONDecodeError) as exc:
+ raise ValueError(f"Cannot read benchmark result {path}: {exc}") from exc
+ if document.get("format_version") != 2:
+ raise ValueError(f"Unsupported result format in {path}")
+ if not isinstance(document.get("parameters"), dict):
+ raise ValueError(f"Result document {path} is missing parameters")
+ if not isinstance(document.get("results"), list) or not document["results"]:
+ raise ValueError(f"Result document {path} has no backend results")
+ return document
+
+
+def summarize_files(paths: Sequence[Path]) -> dict[str, Any]:
+ if len(paths) < 2:
+ raise ValueError("At least two independent result files are required")
+ if len({path.resolve() for path in paths}) != len(paths):
+ raise ValueError("Independent result files cannot be repeated")
+
+ documents = [(path, load_result(path)) for path in paths]
+ reference_dataset = dataset_signature(documents[0][1])
+ reference_parameters = documents[0][1]["parameters"]
+ reference_variants: set[tuple[str, str]] | None = None
+ grouped_results: dict[tuple[str, str], list[dict[str, Any]]] = defaultdict(list)
+ runs: list[dict[str, Any]] = []
+ run_timestamps: set[str] = set()
+
+ for path, document in documents:
+ if dataset_signature(document) != reference_dataset:
+ raise ValueError(f"Dataset metadata differs in {path}")
+ if document["parameters"] != reference_parameters:
+ raise ValueError(f"Benchmark parameters differ in {path}")
+
+ current_variants: set[tuple[str, str]] = set()
+ for result in document["results"]:
+ key = variant_key(result)
+ if key in current_variants:
+ raise ValueError(f"Duplicate backend/search variant in {path}: {key[0]}")
+ current_variants.add(key)
+ grouped_results[key].append(result)
+ if reference_variants is None:
+ reference_variants = current_variants
+ elif current_variants != reference_variants:
+ raise ValueError(f"Backend/search variants differ in {path}")
+
+ runtime = document.get("runtime", {})
+ timestamp = runtime.get("timestamp")
+ if not isinstance(timestamp, str) or not timestamp:
+ raise ValueError(f"Result document {path} is missing a runtime timestamp")
+ if timestamp in run_timestamps:
+ raise ValueError(f"Duplicate process timestamp in {path}")
+ run_timestamps.add(timestamp)
+ runs.append(
+ {
+ "source": path.name,
+ "timestamp": timestamp,
+ "git_revision": runtime.get("git_revision"),
+ "git_dirty": runtime.get("git_dirty"),
+ "gpu_name": (runtime.get("gpu") or {}).get("name"),
+ "cpu_model": runtime.get("cpu_model"),
+ "cuvs": runtime.get("cuvs"),
+ "cupy": runtime.get("cupy"),
+ }
+ )
+
+ results = []
+ for (backend, encoded_search_params), variants in sorted(
+ grouped_results.items(), key=lambda item: variant_sort_key(item[0])
+ ):
+ results.append(
+ {
+ "backend": backend,
+ "cagra_search_params": json.loads(encoded_search_params),
+ "metrics": {
+ name: metric_summary(nested_value(result, path) for result in variants)
+ for name, path in METRIC_PATHS.items()
+ },
+ }
+ )
+
+ runtime_values = {
+ field: sorted({canonical(run.get(field)) for run in runs})
+ for field in ("git_revision", "git_dirty", "gpu_name", "cpu_model", "cuvs", "cupy")
+ }
+ return {
+ "format_version": 1,
+ "run_count": len(documents),
+ "dataset": reference_dataset,
+ "parameters": reference_parameters,
+ "runtime_consistency": {
+ field: [json.loads(value) for value in values]
+ for field, values in runtime_values.items()
+ },
+ "runs": runs,
+ "results": results,
+ }
+
+
+def result_label(result: dict[str, Any]) -> str:
+ label = result["backend"]
+ search_params = result.get("cagra_search_params")
+ if search_params:
+ itopk_size = search_params.get("itopk_size", "auto")
+ search_width = search_params.get("search_width", "auto")
+ label = f"{label}[i={itopk_size},w={search_width}]"
+ return label
+
+
+def format_median_mad(metric: dict[str, Any], precision: int) -> str:
+ if metric["median"] is None:
+ return "n/a"
+ return f"{metric['median']:.{precision}f} +/- {metric['mad']:.{precision}f}"
+
+
+def print_summary(summary: dict[str, Any]) -> None:
+ print(f"Independent runs: {summary['run_count']}")
+ print(
+ "\nbackend build_s med+/-MAD first_ms med+/-MAD "
+ "p50_ms med+/-MAD qps med+/-MAD recall med+/-MAD"
+ )
+ print(
+ "---------------------------- ----------------- ------------------ "
+ "------------------ --------------- ----------------"
+ )
+ for result in summary["results"]:
+ metrics = result["metrics"]
+ print(
+ f"{result_label(result):<28} "
+ f"{format_median_mad(metrics['build_seconds'], 3):>17} "
+ f"{format_median_mad(metrics['first_search_per_query_ms'], 3):>18} "
+ f"{format_median_mad(metrics['warm_p50_ms'], 3):>18} "
+ f"{format_median_mad(metrics['qps'], 1):>15} "
+ f"{format_median_mad(metrics['recall_at_k'], 4):>16}"
+ )
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("inputs", nargs="+", type=Path, help="Independent result JSON files")
+ parser.add_argument("--output", type=Path, help="Write the aggregate JSON document")
+ return parser
+
+
+def main() -> None:
+ args = build_parser().parse_args()
+ try:
+ summary = summarize_files(args.inputs)
+ except ValueError as exc:
+ raise SystemExit(str(exc)) from exc
+ if args.output is not None:
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(json.dumps(summary, indent=2, sort_keys=True) + "\n")
+ print_summary(summary)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/benchmark/cuvs/summarize_service_runs.py b/benchmark/cuvs/summarize_service_runs.py
new file mode 100644
index 000000000..77a545b90
--- /dev/null
+++ b/benchmark/cuvs/summarize_service_runs.py
@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Aggregate independent async vector-service benchmark processes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, Sequence
+
+BENCHMARK_DIR = Path(__file__).resolve().parent
+if str(BENCHMARK_DIR) not in sys.path:
+ sys.path.insert(0, str(BENCHMARK_DIR))
+
+from summarize_index_runs import canonical, metric_summary, nested_value # noqa: E402
+
+DATASET_FIELDS = ("kind", "vector_count", "dimension", "query_count", "metric", "seed")
+BACKEND_METRICS = {
+ "ingest_seconds": ("ingest", "total_seconds"),
+ "ingest_records_per_second": ("ingest", "records_per_second"),
+}
+RESULT_METRICS = {
+ "wall_seconds": ("wall_seconds",),
+ "qps": ("qps",),
+ "error_count": ("error_count",),
+ "p50_ms": ("latency_ms", "p50"),
+ "p95_ms": ("latency_ms", "p95"),
+ "p99_ms": ("latency_ms", "p99"),
+ "max_ms": ("latency_ms", "max"),
+ "write_ms": ("write_ms",),
+}
+BACKEND_ORDER = {"native": 0, "cuvs_brute_force": 1}
+
+
+def dataset_signature(document: dict[str, Any]) -> dict[str, Any]:
+ dataset = document.get("dataset")
+ if not isinstance(dataset, dict):
+ raise ValueError("Result document is missing dataset metadata")
+ return {field: dataset.get(field) for field in DATASET_FIELDS}
+
+
+def load_result(path: Path) -> dict[str, Any]:
+ try:
+ document = json.loads(path.read_text())
+ except (OSError, json.JSONDecodeError) as exc:
+ raise ValueError(f"Cannot read benchmark result {path}: {exc}") from exc
+ if document.get("format_version") != 1:
+ raise ValueError(f"Unsupported service result format in {path}")
+ if not isinstance(document.get("parameters"), dict):
+ raise ValueError(f"Result document {path} is missing parameters")
+ if not isinstance(document.get("results"), list) or not document["results"]:
+ raise ValueError(f"Result document {path} has no backend results")
+ return document
+
+
+def summarize_metrics(
+ documents: Sequence[dict[str, Any]], paths: dict[str, tuple[str, ...]]
+) -> dict[str, dict[str, float | int | None]]:
+ return {
+ name: metric_summary(nested_value(document, path) for document in documents)
+ for name, path in paths.items()
+ }
+
+
+def keyed_backends(document: dict[str, Any], path: Path) -> dict[str, dict[str, Any]]:
+ keyed: dict[str, dict[str, Any]] = {}
+ for result in document["results"]:
+ backend = result.get("backend")
+ if not isinstance(backend, str) or not backend:
+ raise ValueError(f"Every result in {path} requires a non-empty backend")
+ if backend in keyed:
+ raise ValueError(f"Duplicate backend in {path}: {backend}")
+ keyed[backend] = result
+ return keyed
+
+
+def scenario_metadata(scenario: dict[str, Any]) -> dict[str, Any]:
+ return {
+ key: scenario.get(key)
+ for key in ("filter_mode", "filter", "candidate_window")
+ if key in scenario
+ }
+
+
+def summarize_backend(backend: str, variants: Sequence[dict[str, Any]]) -> dict[str, Any]:
+ scenario_maps = [
+ {scenario["name"]: scenario for scenario in variant["scenarios"]} for variant in variants
+ ]
+ scenario_names = list(scenario_maps[0])
+ if any(list(scenario_map) != scenario_names for scenario_map in scenario_maps[1:]):
+ raise ValueError(f"Scenarios differ for backend {backend}")
+
+ scenarios = []
+ for name in scenario_names:
+ entries = [scenario_map[name] for scenario_map in scenario_maps]
+ metadata = scenario_metadata(entries[0])
+ if any(scenario_metadata(entry) != metadata for entry in entries[1:]):
+ raise ValueError(f"Scenario metadata differs for {backend}/{name}")
+ result_maps = [
+ {int(result["concurrency"]): result for result in entry["results"]} for entry in entries
+ ]
+ concurrency_levels = list(result_maps[0])
+ if any(list(result_map) != concurrency_levels for result_map in result_maps[1:]):
+ raise ValueError(f"Concurrency levels differ for {backend}/{name}")
+ scenario_summary = {
+ "name": name,
+ **metadata,
+ "results": [
+ {
+ "concurrency": concurrency,
+ "metrics": summarize_metrics(
+ [result_map[concurrency] for result_map in result_maps],
+ RESULT_METRICS,
+ ),
+ }
+ for concurrency in concurrency_levels
+ ],
+ }
+ initial_values = [entry.get("initial_filter_query_ms") for entry in entries]
+ if any(value is not None for value in initial_values):
+ scenario_summary["initial_filter_query_ms"] = metric_summary(initial_values)
+ scenarios.append(scenario_summary)
+ return {
+ "backend": backend,
+ "metrics": summarize_metrics(variants, BACKEND_METRICS),
+ "scenarios": scenarios,
+ }
+
+
+def summarize_files(paths: Sequence[Path]) -> dict[str, Any]:
+ if len(paths) < 2:
+ raise ValueError("At least two independent result files are required")
+ if len({path.resolve() for path in paths}) != len(paths):
+ raise ValueError("Independent result files cannot be repeated")
+
+ loaded = [(path, load_result(path)) for path in paths]
+ reference_dataset = dataset_signature(loaded[0][1])
+ reference_parameters = loaded[0][1]["parameters"]
+ reference_backends: set[str] | None = None
+ grouped: dict[str, list[dict[str, Any]]] = defaultdict(list)
+ runs = []
+ timestamps: set[str] = set()
+
+ for path, document in loaded:
+ if dataset_signature(document) != reference_dataset:
+ raise ValueError(f"Dataset metadata differs in {path}")
+ if document["parameters"] != reference_parameters:
+ raise ValueError(f"Benchmark parameters differ in {path}")
+ backends = keyed_backends(document, path)
+ if reference_backends is None:
+ reference_backends = set(backends)
+ elif set(backends) != reference_backends:
+ raise ValueError(f"Backends differ in {path}")
+ for backend, result in backends.items():
+ grouped[backend].append(result)
+
+ runtime = document.get("runtime", {})
+ timestamp = runtime.get("timestamp")
+ if not isinstance(timestamp, str) or not timestamp:
+ raise ValueError(f"Result document {path} is missing a runtime timestamp")
+ if timestamp in timestamps:
+ raise ValueError(f"Duplicate process timestamp in {path}")
+ timestamps.add(timestamp)
+ runs.append(
+ {
+ "source": path.name,
+ "timestamp": timestamp,
+ "git_revision": runtime.get("git_revision"),
+ "git_dirty": runtime.get("git_dirty"),
+ "gpu_name": (runtime.get("gpu") or {}).get("name"),
+ "cpu_model": runtime.get("cpu_model"),
+ "cuvs": runtime.get("cuvs"),
+ "cupy": runtime.get("cupy"),
+ }
+ )
+
+ results = [
+ summarize_backend(backend, variants)
+ for backend, variants in sorted(
+ grouped.items(), key=lambda item: (BACKEND_ORDER.get(item[0], 99), item[0])
+ )
+ ]
+ runtime_fields = ("git_revision", "git_dirty", "gpu_name", "cpu_model", "cuvs", "cupy")
+ return {
+ "format_version": 1,
+ "run_count": len(loaded),
+ "dataset": reference_dataset,
+ "parameters": reference_parameters,
+ "runtime_consistency": {
+ field: [json.loads(value) for value in sorted({canonical(run[field]) for run in runs})]
+ for field in runtime_fields
+ },
+ "runs": runs,
+ "results": results,
+ }
+
+
+def format_median_mad(metric: dict[str, Any], precision: int) -> str:
+ if metric["median"] is None:
+ return "n/a"
+ return f"{metric['median']:.{precision}f} +/- {metric['mad']:.{precision}f}"
+
+
+def print_summary(summary: dict[str, Any]) -> None:
+ print(f"Independent runs: {summary['run_count']}")
+ print(
+ "\nbackend scenario conc p50_ms med+/-MAD p99_ms med+/-MAD qps med+/-MAD"
+ )
+ print(
+ "---------------------- ------------------------------- ---- ------------------ ------------------ -----------------"
+ )
+ for backend in summary["results"]:
+ for scenario in backend["scenarios"]:
+ for result in scenario["results"]:
+ metrics = result["metrics"]
+ print(
+ f"{backend['backend']:<22} {scenario['name']:<31} "
+ f"{result['concurrency']:>4} "
+ f"{format_median_mad(metrics['p50_ms'], 3):>18} "
+ f"{format_median_mad(metrics['p99_ms'], 3):>18} "
+ f"{format_median_mad(metrics['qps'], 1):>17}"
+ )
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("inputs", nargs="+", type=Path, help="Independent result JSON files")
+ parser.add_argument("--output", type=Path, help="Write the aggregate JSON document")
+ return parser
+
+
+def main() -> None:
+ args = build_parser().parse_args()
+ try:
+ summary = summarize_files(args.inputs)
+ except ValueError as exc:
+ raise SystemExit(str(exc)) from exc
+ if args.output is not None:
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(json.dumps(summary, indent=2, sort_keys=True) + "\n")
+ print_summary(summary)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docker/cuvs-dev/Dockerfile b/docker/cuvs-dev/Dockerfile
new file mode 100644
index 000000000..533901f68
--- /dev/null
+++ b/docker/cuvs-dev/Dockerfile
@@ -0,0 +1,83 @@
+# syntax=docker/dockerfile:1.9
+
+FROM python:3.12-slim-bookworm
+
+ARG CUVS_PACKAGE="cuvs-cu13==26.6.0"
+ARG CUPY_PACKAGE="cupy-cuda13x[ctk]==14.1.1"
+
+RUN apt-get update \
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+ build-essential \
+ ca-certificates \
+ cmake \
+ git \
+ && rm -rf /var/lib/apt/lists/*
+
+# Keep Python and accelerator dependencies independent from the source layers.
+# Python-only OpenViking changes therefore reuse this relatively expensive
+# cuVS/CuPy installation.
+RUN --mount=type=cache,target=/root/.cache/pip \
+ python -m pip install --upgrade pip setuptools wheel \
+ && python -m pip install \
+ --extra-index-url https://pypi.nvidia.com \
+ "${CUVS_PACKAGE}" \
+ "${CUPY_PACKAGE}" \
+ "apscheduler>=3.11,<4" \
+ "h5py>=3.12,<4" \
+ "pydantic>=2,<3" \
+ "pytest>=8,<9" \
+ "pytest-asyncio>=0.24,<2" \
+ "pyyaml>=6,<7" \
+ "requests>=2.31,<3" \
+ "xxhash>=3,<4"
+
+# Pyxis/Enroot does not run the NVIDIA container-toolkit hook that normally
+# discovers CUDA libraries installed by Python wheels. Register both the
+# nvidia/*/lib directories and RAPIDS lib64 directories with the dynamic
+# loader so cuVS works the same way under Docker and Pyxis.
+RUN find /usr/local/lib/python*/site-packages/nvidia \
+ -type d -name lib -print \
+ > /etc/ld.so.conf.d/python-nvidia-wheels.conf \
+ && find /usr/local/lib/python*/site-packages \
+ -maxdepth 2 -type d -name lib64 -print \
+ >> /etc/ld.so.conf.d/python-nvidia-wheels.conf \
+ && ldconfig
+
+WORKDIR /opt/openviking
+
+# Compile the native VectorDB engine before copying the Python worktree. This
+# layer is invalidated only by C++ or third-party source changes.
+COPY src/ src/
+COPY third_party/ third_party/
+RUN cmake \
+ -S /opt/openviking/src \
+ -B /tmp/openviking-engine-build \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DOV_PY_OUTPUT_DIR=/opt/openviking-native-engine \
+ -DOV_PY_EXT_SUFFIX=.abi3.so \
+ -DOV_X86_BUILD_VARIANTS='sse3;avx2;avx512' \
+ && cmake --build /tmp/openviking-engine-build --config Release -j"$(nproc)" \
+ && test -n "$(find /opt/openviking-native-engine -name '*.so' -print -quit)" \
+ && rm -rf /tmp/openviking-engine-build
+
+# Source changes in the Python integration layer are cheap to rebuild. A copy
+# of the native engine is also retained for injection into mounted worktrees.
+COPY openviking/ openviking/
+COPY openviking_cli/ openviking_cli/
+RUN --mount=type=cache,target=/root/.cache/pip \
+ python -m pip install \
+ "json-repair>=0.25" \
+ "loguru>=0.7,<1" \
+ "volcengine>=1.0.216"
+COPY examples/cuvs_smoke.py /opt/openviking-cuvs/cuvs_smoke.py
+COPY benchmark/cuvs/ /opt/openviking-cuvs-benchmark/
+COPY docker/cuvs-dev/entrypoint.sh /usr/local/bin/openviking-cuvs-dev
+RUN cp -a /opt/openviking-native-engine/. \
+ /opt/openviking/openviking/storage/vectordb/engine/ \
+ && chmod +x /usr/local/bin/openviking-cuvs-dev \
+ && python -c "import cupy; from cuvs.neighbors import brute_force, cagra; import openviking.storage.vectordb.engine; print('cuVS development image import check passed')"
+
+ENV PYTHONPATH="/opt/openviking"
+
+ENTRYPOINT ["/usr/local/bin/openviking-cuvs-dev"]
+CMD ["bash"]
diff --git a/docker/cuvs-dev/README.md b/docker/cuvs-dev/README.md
new file mode 100644
index 000000000..9c61a61ac
--- /dev/null
+++ b/docker/cuvs-dev/README.md
@@ -0,0 +1,77 @@
+# cuVS development image
+
+This lightweight image contains cuVS, CuPy, the OpenViking local VectorDB
+native engine, and the minimal Python dependencies needed by the cuVS smoke
+and integration tests. It deliberately excludes the server, bot, Web UI, and
+unrelated ingestion dependencies. It does not encode any cluster-specific
+configuration.
+
+Build it from the repository root:
+
+```bash
+docker build \
+ -f docker/cuvs-dev/Dockerfile \
+ -t openviking-cuvs:dev \
+ .
+```
+
+The defaults track CUDA 13 packages. Build a CUDA 12 variant for systems whose
+driver/runtime policy requires it:
+
+```bash
+docker build \
+ --build-arg CUVS_PACKAGE=cuvs-cu12==26.6.0 \
+ --build-arg 'CUPY_PACKAGE=cupy-cuda12x[ctk]==14.1.1' \
+ -f docker/cuvs-dev/Dockerfile \
+ -t openviking-cuvs:dev-cu12 \
+ .
+```
+
+Run the baked smoke test:
+
+```bash
+docker run --rm --gpus all openviking-cuvs:dev \
+ python /opt/openviking-cuvs/cuvs_smoke.py
+```
+
+Exercise CAGRA with the same image:
+
+```bash
+docker run --rm --gpus all openviking-cuvs:dev \
+ python /opt/openviking-cuvs/cuvs_smoke.py --algorithm cagra
+```
+
+For Python-only iteration, mount a worktree and point
+`OPENVIKING_SOURCE_DIR` at it. The entrypoint copies the prebuilt native
+engine into the mounted tree before running the command:
+
+```bash
+docker run --rm --gpus all \
+ -v "$PWD:/workspace/OpenViking" \
+ -e OPENVIKING_SOURCE_DIR=/workspace/OpenViking \
+ openviking-cuvs:dev \
+ python examples/cuvs_smoke.py
+```
+
+The dependency, native-engine, and Python-source layers are separate. Normal
+changes to the Python cuVS integration reuse the dependency and C++ build
+layers. Recompile the native layer only when `src/` or `third_party/` changes.
+
+For an Enroot/Pyxis environment, export the already-built Docker image once to
+a shared SquashFS file:
+
+```bash
+docker/cuvs-dev/export-sqsh.sh \
+ openviking-cuvs:dev \
+ /shared/images/openviking-cuvs-dev.sqsh
+```
+
+Set both `NVIDIA_VISIBLE_DEVICES` and `NVIDIA_DRIVER_CAPABILITIES` before
+launching the SquashFS image, and explicitly pass them through when the Pyxis
+configuration does not inherit host variables. This triggers the NVIDIA hook
+that injects `libcuda` and the allocated devices:
+
+```bash
+export NVIDIA_VISIBLE_DEVICES=all
+export NVIDIA_DRIVER_CAPABILITIES=compute,utility
+```
diff --git a/docker/cuvs-dev/entrypoint.sh b/docker/cuvs-dev/entrypoint.sh
new file mode 100644
index 000000000..01c5a3b89
--- /dev/null
+++ b/docker/cuvs-dev/entrypoint.sh
@@ -0,0 +1,18 @@
+#!/bin/sh
+set -eu
+
+# A mounted worktree can reuse the native extension baked into the image.
+# Python modules are then imported from the worktree, while the expensive C++
+# engine build remains stable until its sources actually change.
+if [ -n "${OPENVIKING_SOURCE_DIR:-}" ]; then
+ engine_dir="${OPENVIKING_SOURCE_DIR}/openviking/storage/vectordb/engine"
+ if [ ! -d "${engine_dir}" ]; then
+ echo "OPENVIKING_SOURCE_DIR is not an OpenViking worktree: ${OPENVIKING_SOURCE_DIR}" >&2
+ exit 2
+ fi
+ cp -a /opt/openviking-native-engine/. "${engine_dir}/"
+ export PYTHONPATH="${OPENVIKING_SOURCE_DIR}${PYTHONPATH:+:${PYTHONPATH}}"
+ cd "${OPENVIKING_SOURCE_DIR}"
+fi
+
+exec "$@"
diff --git a/docker/cuvs-dev/export-sqsh.sh b/docker/cuvs-dev/export-sqsh.sh
new file mode 100755
index 000000000..f2314d851
--- /dev/null
+++ b/docker/cuvs-dev/export-sqsh.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+set -eu
+
+image=${1:-openviking-cuvs:dev}
+output=${2:-openviking-cuvs-dev.sqsh}
+
+if [ -e "${output}" ]; then
+ echo "Output already exists: ${output}" >&2
+ exit 2
+fi
+
+exec enroot import -o "${output}" "dockerd://${image}"
diff --git a/docs/design/openviking-cuvs-benchmark-plan.md b/docs/design/openviking-cuvs-benchmark-plan.md
new file mode 100644
index 000000000..5f125f447
--- /dev/null
+++ b/docs/design/openviking-cuvs-benchmark-plan.md
@@ -0,0 +1,229 @@
+# OpenViking cuVS benchmark plan
+
+相关文档:[集成计划](./openviking-cuvs-integration-plan.md)、
+[初步结果](../../benchmark/cuvs/PRELIMINARY_RESULTS.md)。
+
+## 目标
+
+本 benchmark 不追求单个“最高 QPS”数字,而是回答四个对集成决策更有用的问题:
+
+1. 在精确检索下,cuVS brute-force 相比 OpenViking native flat 的延迟和吞吐拐点在哪里?
+2. 在相同 Recall@K 下,CAGRA 能提供多少延迟、吞吐和容量收益?
+3. 标量过滤、Python 调用和记录回表后,GPU 优势还剩多少?
+4. 当前延迟重建策略对冷启动和写后首查造成多大代价?
+
+cuVS 官方建议从 build time、search quality 和 search performance 三个维度比较向量索引;
+本方案沿用这个原则,并增加 OpenViking 集成层与 mutation lifecycle 的测量。
+
+参考:
+
+- [cuVS: comparing vector search index performance](https://docs.rapids.ai/api/cuvs/stable/getting_started/)
+- [cuVS Bench](https://docs.rapids.ai/api/cuvs/stable/cuvs_bench/)
+
+## 被测后端
+
+| 名称 | OpenViking 配置 | 作用 |
+| --- | --- | --- |
+| Native exact | `backend=local`, `IndexType=flat` | CPU flat 基线;精确性相对于其实际存储表示定义 |
+| cuVS exact | `backend=cuvs`, `algorithm=brute_force` | GPU 在其 float32 表示上的精确检索 |
+| cuVS ANN | `backend=cuvs`, `algorithm=cagra` | 在固定 Recall@K 下比较 ANN 性能 |
+
+可以使用 `cuvs-bench` 的 HNSWlib 或其他算法作为算法级参考,但不能把它们当作
+OpenViking 端到端基线,因为它们没有经过相同的过滤、label mapping 和记录回表路径。
+
+### Dtype 与非侵入性原则
+
+cuVS 是 opt-in dense-search sidecar,不修改默认 backend,也不改变 native CPU
+索引的默认 `int8` 量化。当前 cuVS GPU shadow 使用 `float32`。因此:
+
+- L1 index-only harness 显式形成 float32 CPU / float32 GPU 对比,用于隔离 kernel;
+- L2/L3 保留真实应用默认,即 native int8 / cuVS float32,并同时报告 Recall@K;
+- L2/L3 不能表述为等 dtype、等内存或完全相同数值语义的比较;
+- native fallback 始终继续使用原有 int8 CPU index,启用 cuVS 不触发迁移或重写。
+
+低精度 GPU 路线分开评估:先增加 cuVS float16 dataset/query,与 float32 ground
+truth 比较 Recall@K、延迟和显存;随后再评估 CAGRA int8 或 VPQ。native 的逐向量
+scale int8 不能直接映射到 cuVS brute-force,若要求数值兼容,需要自定义 int8
+distance/top-k 或候选召回后按 scale rerank,不能用简单 cast 代替。
+
+## 与 agent-memory benchmark 的关系
+
+OpenViking 仓库已经包含多类 benchmark,它们可以作为 cuVS 集成的质量与端到端 guardrail:
+
+| 仓库目录 | 主要问题 | 在 cuVS 评测中的用途 |
+| --- | --- | --- |
+| `benchmark/locomo/` | 长期对话记忆、跨 session QA | memory quality 回归;比较 local exact、cuVS exact、CAGRA |
+| `benchmark/longmemeval/openviking/` | 信息提取、多 session/时间推理、更新与拒答 | 首选的长期记忆质量 benchmark |
+| `benchmark/RAG/` | LoCoMo、Qasper、FinanceBench、SyllabusQA | 检查通用 RAG 质量和领域差异 |
+| `benchmark/tau2/llm/` | memory 对 agent tool-task success 的贡献 | 端到端任务收益,不用于隔离 vector-search 性能 |
+| `benchmark/custom/session_contention_benchmark.py` | Server 混合负载的 QPS、延迟、错误率和积压 | 扩展为 `local`/`cuvs` backend matrix,测真实服务退化 |
+
+这些质量 benchmark 不能替代 ANN benchmark。LoCoMo 只有少量长对话,LongMemEval-S 也以
+500 个问题和每题有限 session 为主;单个 user 的向量规模通常不足以让 GPU 展现优势。它们最适合
+验证“替换后端后答案质量不下降”,而不是证明最大 QPS。
+
+领域内建议优先考虑以下公开 benchmark:
+
+1. [LoCoMo(ACL 2024)](https://aclanthology.org/2024.acl-long.747/):使用广泛,覆盖长期对话
+ QA、事件总结和多模态对话;适合作为兼容性基线。
+2. [LongMemEval(ICLR 2025)](https://github.com/xiaowu0162/LongMemEval):覆盖信息提取、
+ multi-session reasoning、时间推理、knowledge update 和 abstention;官方 harness 同时支持
+ retrieval 与 QA 评测,适合做主要 memory-quality 结果。
+3. [MemBench(Findings of ACL 2025)](https://aclanthology.org/2025.findings-acl.989/):同时考虑
+ factual/reflective memory、participation/observation 场景,以及 accuracy、recall、capacity、
+ temporal efficiency,适合补充系统容量与效率。
+4. [MemoryAgentBench(ICLR 2026)](https://github.com/HUST-AI-HYZ/MemoryAgentBench):覆盖
+ accurate retrieval、test-time learning、long-range understanding 和 conflict resolution,适合
+ 评估更广义的 agent memory 能力。
+5. [LongMemEval-V2](https://github.com/xiaowu0162/LongMemEval-V2):面向 agent trajectory memory,
+ 最大 haystack 达到约 1.15 亿 token,并同时考察 answer accuracy 和 query latency;它是后续
+ 展示“大规模 agent memory + cuVS”价值最匹配的公开方向。
+
+推荐最终报告采用三张相互独立的 scoreboard:
+
+- **Vector index performance**:本方案的 L1/L2,展示 latency、QPS、recall、build 和 memory。
+- **Memory quality**:LongMemEval 为主、LoCoMo 为辅,固定 embedder、reader、judge、top-k 和
+ context budget,只改变 vector backend。
+- **Agent task utility**:TAU-2 或 MemoryAgentBench,比较 no-memory、native-memory 和
+ cuVS-memory 的任务成功率与总成本。
+
+为了让公开 memory benchmark 达到能够体现 GPU 的规模,不应简单复制相同 memory。建议使用
+LongMemEval 的可扩展 filler sessions、LongMemEval-V2 trajectory haystack,或者独立的真实噪声
+corpus,把总索引扩展到 100K/1M/5M/10M,同时保留原题 evidence 作为 retrieval ground truth。
+
+## 三层 benchmark
+
+### L1:索引层
+
+只测 native flat、cuVS brute-force 和 CAGRA 的 build/search,不包含 embedding、HTTP、
+持久化写入和结果回表。这一层最容易解释 GPU kernel 与算法本身的收益。
+
+测量:
+
+- build wall time,其中单独记录 host-to-device transfer;
+- warm search 的 p50、p95、p99 和 QPS;
+- Recall@10、Recall@100;
+- peak host RSS、peak GPU memory 和 index size。
+
+### L2:OpenViking collection 层
+
+通过 `search_by_vector()` 发起查询,包含 Python adapter、filter translation、label mapping
+和记录回表,但使用预先生成的 query vectors,避免 embedding 服务掩盖检索差异。
+
+这一层应作为当前 feature integration 的主要结果,因为它测量了用户实际经过的代码路径。
+
+### L3:服务层
+
+通过 OpenViking server 发起请求,分别报告:
+
+- vector-ready 请求:客户端直接提供 query vector;
+- full retrieval 请求:包含 embedding 和其他业务处理。
+
+full retrieval 只用于判断向量检索在总延迟中的占比,不用于证明 cuVS kernel 的加速比。
+
+## 数据集矩阵
+
+先跑能够代表 OpenViking 的 synthetic workload,再用公开 ANN 数据集交叉验证。
+
+| 维度 | 建议取值 | 说明 |
+| --- | --- | --- |
+| Vector count | 10K、100K、1M、5M、10M | 用来找到 GPU break-even point |
+| Dimension | 128、768、1024 | 128 对齐 SIFT;768/1024 接近常见 embedding |
+| Metric | cosine/IP,补充 L2 | cosine 在两端使用相同的 L2 normalization |
+| K | 10、100 | 同时覆盖常见 retrieval 与较大候选集 |
+| Query batch | 1、8、32、128、512 | 区分低延迟与吞吐场景 |
+
+公开数据集优先使用 cuVS Bench 已支持且带 ground truth 的数据:
+
+- SIFT-1M,128D,L2;
+- GloVe-1.1M,100D,angular;
+- Deep-10M,96D,angular;
+- Wiki-all 1M/10M,768D,用于更接近 RAG embedding 的场景。
+
+## 公平性与正确性
+
+- 同一份 base vectors、query vectors、metric、K 和 normalization 输入所有后端。
+- 用 native exact 或 cuVS brute-force 生成 ground truth;精确后端必须达到 Recall@K = 1.0。
+- CAGRA 只在固定 recall bucket 下比较,例如 Recall@10 >= 0.95 和 >= 0.99。
+- CAGRA 参数至少扫描:`graph_degree={32,64}`、
+ `intermediate_graph_degree={64,96}`、`itopk_size={32,64,128}`。
+- 固定 CPU threads、NUMA placement 和 GPU 数量,并在结果中记录硬件、软件版本和配置。
+- 每组先 warm up,再至少执行 10K queries;重复五轮,报告中位数与离散程度。
+- cold build、cold first query 和 warm steady state 分开报告。
+
+## 过滤 benchmark
+
+过滤会影响 CAGRA 的搜索路径,也是本集成区别于裸 cuVS benchmark 的关键部分。
+
+每个规模测试以下 selectivity:100%、10%、1%、0.1%,并包含两种分布:
+
+- uniform:符合条件的 label 在数据集中均匀分布;
+- clustered/skewed:符合条件的数据集中在少数类别或路径前缀。
+
+每个过滤场景重新生成 filtered ground truth,同时报告 Recall@K、p95 和 QPS。不能用未过滤
+ground truth 计算 recall。
+
+## 生命周期 benchmark
+
+当前实现保留 host shadow,并在 upsert/delete 后把 GPU index 标脏;下一次查询执行批量重建。
+因此必须独立测量:
+
+- 首次建库时间;
+- 进程重启后的 rehydrate + rebuild 时间;
+- 1、100、10K 和 1% 数据变更后的 write latency;
+- 从 write 返回到下一次成功查询的总时间;
+- rebuild 期间的 peak host/GPU memory。
+
+这个结果决定延迟重建适合的 workload 边界。steady-state search 图不能把 rebuild 时间平均掉,
+否则会对写密集 workload 产生误导。
+
+## 当前集成的吞吐限制
+
+当前 Python integration 一次只提交一个 query,并在一次 GPU search 期间持有 index lock;同时
+每次调用都会创建 query device array 并把结果同步回 host。因此:
+
+- batch > 1 的 L1 结果代表 cuVS 的能力上限,不等同于当前 OpenViking API 的吞吐;
+- L2/L3 必须以 batch=1 为主,并明确记录并发请求是否被 lock 串行化;
+- 如果 L1 与 L2 差距明显,下一阶段优先实现 persistent device buffers、CUDA streams 或
+ dynamic batching,再评估最大吞吐。
+
+## 主要图表
+
+1. p50/p95 latency vs vector count:native exact 对比 cuVS exact,展示 break-even point。
+2. QPS vs Recall@10 frontier:CAGRA 参数扫描结果,并标出 0.95/0.99 recall bucket。
+3. build/rebuild/first-query time vs vector count:展示冷启动和延迟重建代价。
+4. p95/QPS vs filter selectivity:分别展示 uniform 和 skewed filter。
+5. host RSS/GPU memory vs vector count:说明容量上限和 host shadow 成本。
+
+## 第一阶段最小矩阵
+
+先用较小但足以观察趋势的矩阵建立可重复 harness:
+
+- synthetic 1024D cosine,100K/1M/5M vectors;
+- K=10,batch=1 和 128;
+- native exact、cuVS exact、CAGRA;
+- CAGRA Recall@10 >= 0.95 和 >= 0.99;
+- 无过滤、1% uniform filter;
+- 记录 build、warm p50/p95/p99、QPS、recall、host RSS 和 GPU memory;
+- 额外执行一次 100-record update,记录 write + next-query rebuild latency。
+
+第一阶段结束后再决定是否下载 10M/100M 公开数据集,避免在 harness 尚未稳定时消耗大量
+存储和 GPU 时间。
+
+## 建议的实现结构
+
+```text
+benchmark/cuvs/
+├── README.md
+├── generate_dataset.py
+├── run_index_benchmark.py
+├── run_collection_benchmark.py
+├── configs/
+│ ├── smoke.yaml
+│ └── scale.yaml
+└── plot_results.py
+```
+
+每次运行输出一个自描述 JSON/JSONL 文件,至少包含 git revision、backend、algorithm、全部参数、
+dataset hash、hardware metadata、软件版本、raw latency samples 和 summary。图表必须能够只依赖
+这些结果文件离线重建。
diff --git a/docs/design/openviking-cuvs-integration-plan.md b/docs/design/openviking-cuvs-integration-plan.md
new file mode 100644
index 000000000..d82c673d3
--- /dev/null
+++ b/docs/design/openviking-cuvs-integration-plan.md
@@ -0,0 +1,493 @@
+# OpenViking × cuVS 集成计划
+
+> 状态:功能集成与第一轮向量索引验证已完成,后续进入数据面性能化阶段。
+> 原则:cuVS 是可选的 dense-search sidecar,不改变 OpenViking 默认 CPU 行为。
+> 相关文档:[benchmark 计划](./openviking-cuvs-benchmark-plan.md)、[初步结果](../../benchmark/cuvs/PRELIMINARY_RESULTS.md)、[用户指南(中文)](../zh/guides/16-cuvs.md)、[User guide (English)](../en/guides/16-cuvs.md)。
+
+## 1. 目标
+
+本集成只替换 OpenViking 本地 VectorDB 的 dense vector search 执行器,继续复用现有的:
+
+- 权威记录存储和持久化恢复;
+- scalar/path index 与过滤 DSL;
+- sparse/hybrid retrieval;
+- sort、aggregate、label mapping 和结果回表;
+- upsert、delete 和 collection 生命周期。
+
+当前阶段需要做到:
+
+1. 通过显式配置启用 cuVS,不改变上层检索 API 和默认 `local` 行为;
+2. pure dense query 能进入 cuVS brute-force 或 CAGRA;
+3. cosine、inner product 和 L2 的返回分数保持现有接口语义;
+4. scalar、URI/path 和组合过滤复用 native 语义,并作为 cuVS 前置过滤;
+5. upsert、delete、重启恢复后结果正确;
+6. 显存不足或 GPU 不可用时,auto 模式安全保留 native 路径;
+7. 用可复现 benchmark 量化适用规模、过滤选择性、显存和 lifecycle 成本。
+
+## 2. 非目标
+
+本阶段不做以下扩展:
+
+- 不把 cuVS 变成独立的完整数据库后端;
+- 不移除或改写 OpenViking 原生 dense index;
+- 不改变 native CPU index 的默认 int8 量化;
+- 不把 cuVS 序列化文件作为权威持久化格式;
+- 不实现多 GPU、跨机分片或共享 GPU 资源池;
+- 不在功能版中承诺写密集 workload 的低延迟;
+- 不用未过滤 top-k 后置过滤代替正确的 prefilter;
+- 不把 CAGRA 的 ANN 结果描述为精确检索。
+
+## 3. 核心决策
+
+| 决策 | 选择 | 原因 |
+| --- | --- | --- |
+| 集成位置 | `LocalIndex.search()` 的 pure dense 分支 | 边界小,可复用 Store、恢复、过滤和回表 |
+| 权威状态 | Local Store | GPU index 可随时由当前记录重建 |
+| 默认算法 | cuVS brute-force | 适合功能对齐和 exact ground truth |
+| ANN 算法 | CAGRA,显式开启 | 必须结合 Recall@K、延迟、build time 和显存评估 |
+| mutation | host shadow 标脏,下一次查询全量重建 | 首先保证 upsert/delete 语义正确 |
+| 过滤 | native bitmap 投影为 cuVS row bitset | 复用既有 DSL 和 scalar/path index,不重复实现语义 |
+| 持久化 | 不持久化 cuVS index | 避免绑定 GPU、CUDA/cuVS 版本和序列化兼容性 |
+| 默认 CPU dtype | 保持现有 per-vector-scale int8 | cuVS opt-in 不能改变未启用用户的行为 |
+| GPU dtype | 当前使用 float32 shadow | 先建立正确性和性能基线;低精度作为独立能力评估 |
+
+## 4. 总体架构
+
+```mermaid
+flowchart TD
+ API[OpenViking API / Service] --> Adapter[VectorDB Adapter]
+ Adapter --> Collection[LocalCollection]
+
+ Collection --> Store[(Local Store<br/>single source of truth)]
+ Collection --> LocalIndex[LocalIndex]
+
+ LocalIndex --> Native[Native IndexEngine<br/>dense / scalar / sparse / sort / aggregate]
+ LocalIndex --> Shadow[CuVSDenseIndex<br/>host shadow / dirty state / label map]
+
+ Native --> Bridge[Native filter bitmap bridge]
+ Bridge -->|packed uint32 words| Shadow
+ Shadow --> GPU[cuVS + CuPy / CUDA<br/>brute-force / CAGRA / prefilter]
+
+ Store -. restart recovery .-> Native
+ Store -. candidate reload .-> Shadow
+```
+
+一句话概括:OpenViking 管数据、生命周期和查询语义,cuVS 管 GPU dense top-k;两者通过 label layout 和 native filter bitmap 对接。
+
+### 4.1 组件职责
+
+| 组件 | 职责 | 当前状态 |
+| --- | --- | --- |
+| `VectorDBBackendConfig` / `CuVSConfig` | backend、算法、显存预算、路由阈值和 CAGRA 参数校验 | 已实现 |
+| `CuVSCollectionAdapter` | 复用 local adapter,注入 cuVS dense-search 配置 | 已实现 |
+| `LocalCollection` | schema、Store、delta、恢复和结果回表 | 复用原生 |
+| `LocalIndex` | pure dense 路由、跨后端 mutation 一致性和 native fallback | 已扩展 |
+| `CuVSDenseIndex` | host shadow、dirty lifecycle、label map、bitset cache 和 GPU index | 已实现 |
+| `_CuVSRuntime` | 延迟导入 CuPy/cuVS,调用 brute-force/CAGRA build/search | 已实现 |
+| Native `IndexEngine` | 完整 native 能力和 filter bitmap 生成 | 已扩展 bitmap bridge |
+| ABI3 backend | 暴露 filter layout 注册与 bitmap projection | 已实现 |
+| `StoreManager` | 权威记录、向量和字段存储 | 复用原生 |
+
+### 4.2 数据所有权
+
+| 状态 | 是否权威 | 生命周期 |
+| --- | --- | --- |
+| Local Store | 是 | 持久化,恢复从这里开始 |
+| Native index | 否 | 由 snapshot + delta 维护,承担完整本地能力 |
+| cuVS host shadow | 否 | 按 label 保存 dense vector 和重建所需记录 |
+| cuVS GPU index | 否 | 首次查询或 dirty 后构建,进程退出即丢弃 |
+| Device filter cache | 否 | LRU 缓存,mutation 时清空 |
+
+OpenViking 主键按现有规则映射为 `uint64 label`。cuVS 返回 dataset row id,`CuVSDenseIndex` 再通过构建时的 label 数组映射回 OpenViking label,最后由 Collection 回表得到完整记录。
+
+## 5. 核心链路
+
+### 5.1 Upsert / delete
+
+```mermaid
+sequenceDiagram
+ participant C as LocalCollection
+ participant N as Native IndexEngine
+ participant G as CuVSDenseIndex
+ participant S as Local Store
+
+ C->>S: 写入权威记录 / delta
+ C->>N: upsert 或 delete
+ N->>N: 更新 native index 并清空 filter layout
+ C->>G: 更新 host shadow
+ G->>G: dirty=true,清空 filter cache
+ Note over G: 下一次 GPU 查询同步重建 index
+```
+
+`LocalIndex` 使用跨后端重入锁覆盖 native mutation 和 cuVS shadow mutation,避免查询获得新 native bitmap 却使用旧 GPU row layout。当前 mutation 后不增量修改 CAGRA,而是标脏并在下一次 dense 查询全量重建。
+
+### 5.2 Dense query
+
+```mermaid
+flowchart TD
+ Q[LocalIndex.search] --> Pure{有 dense vector<br/>且无 sparse terms?}
+ Pure -->|否| N[Native search]
+ Pure -->|是| Ready{cuVS 已配置且可用?}
+ Ready -->|否| N
+ Ready -->|是| Dirty{GPU index dirty?}
+ Dirty -->|是| Admit{auto 显存预算允许?}
+ Admit -->|否| N
+ Admit -->|是| Build[批量构建 GPU index<br/>注册 label layout]
+ Dirty -->|否| Filter
+ Build --> Filter{存在 filter?}
+ Filter -->|否| GPU[cuVS top-k]
+ Filter -->|是| Bitmap[native scalar/path bitmap<br/>投影为 cuVS row bitset]
+ Bitmap --> Route{auto 模式且候选数<br/>低于 native 阈值?}
+ Route -->|是| N
+ Route -->|否| GPU
+ GPU --> Map[row id → label → record]
+```
+
+显式 `backend=cuvs` 对支持的 pure dense query 固定使用 GPU,并在初始化或运行错误时 fail-fast。`auto_cuvs` 才执行显存准入和候选数路由。
+
+### 5.3 Filter bitmap bridge
+
+过滤路径不再扫描全部 Python records:
+
+1. GPU rebuild 后调用 `set_filter_layout(ordered_labels)`;
+2. native engine 将每个 cuVS row 预映射到 native logical offset;
+3. 查询时 native filter parser 与 scalar/path index 计算原生 bitmap;
+4. `evaluate_filter(dsl)` 按已注册 layout 投影,返回 packed `uint32` words 和 eligible count;
+5. cuVS 将 words 复制到 device,并通过 `filters.from_bitset()` 构造 prefilter;
+6. 相同 filter 复用 device bitset;mutation 同时使 layout 和 cache 失效。
+
+该 bridge 继承 native 对以下能力的处理:
+
+- `and`、`or`;
+- `must`、`must_not`;
+- `contains`;
+- `range`、`range_out`;
+- URI/path prefix 和 depth;
+- `date_time`、`geo_point` 等 native 字段转换语义。
+
+bitmap 在 CPU 上生成是有意选择。native scalar/path index 已经维护了对应结构;把 URI DSL 解析、Trie 遍历和 bitmap union 搬到 GPU 会引入额外索引副本、同步和 kernel launch,而当前主要收益来自 GPU distance/top-k。只有 profiling 表明 bitmap 生成成为主要瓶颈时,才评估 GPU 化。
+
+### 5.4 Restart recovery
+
+1. 读取 collection 和 index metadata;
+2. 恢复 native snapshot 并 replay delta;
+3. 从 Store 读取当前 candidates;
+4. 恢复 cuVS host shadow,但不立即构建 GPU index;
+5. 第一次 pure dense query 按配置执行显存准入和 lazy build。
+
+cuVS index 文件未来可以作为带严格版本约束的 cache,但不能成为事实来源。
+
+## 6. 查询路由策略
+
+### 6.1 能力路由
+
+| 查询类型 | 执行路径 |
+| --- | --- |
+| pure dense,无 filter | cuVS 或 auto/native |
+| pure dense + scalar/path filter | native bitmap → cuVS prefilter,或 auto 路由 native recall |
+| sparse / hybrid | native |
+| scalar sort / aggregate | native |
+| 空数据集 / filter 无候选 | 返回空结果 |
+
+不采用 post-filter。先取未过滤 top-k 再过滤,无法保证高选择性过滤后的结果数量和真实 top-k;无限 over-fetch 也不能提供稳定正确性。
+
+### 6.2 Auto mode
+
+auto 模式包含两层决策:
+
+1. **Build admission**:根据空闲显存和保守峰值估算决定是否构建 GPU index;
+2. **Per-query routing**:根据 native bitmap 返回的 eligible count 决定 filtered query 走 CPU 还是 GPU。
+
+当前默认阈值:
+
+| 配置 | 默认值 | 含义 |
+| --- | ---: | --- |
+| `auto_filter_native_threshold` | 2000 | 普通过滤候选数不超过该值时走 native recall |
+| `auto_path_filter_native_threshold` | 200 | URI/path 过滤使用的更保守阈值 |
+
+URI/path 使用更低阈值,是因为宽路径需要 native Trie traversal 和 subtree bitmap union;这个成本会先于 GPU search 发生。阈值设为 `0` 可关闭对应 native 路由。阈值是当前测量得到的默认值,不是跨硬件、维度和 workload 的常数。
+
+native fallback 在跨后端 GPU 锁外执行,以保留 native engine 原有的共享读并发。
+
+## 7. Dtype 与数值语义
+
+### 7.1 当前边界
+
+- native collection 默认保持 per-vector-scale int8;
+- cuVS host/device shadow 当前为 float32;
+- 启用 cuVS 不迁移、不重写 native index metadata;
+- native fallback 始终使用原有 CPU representation;
+- auto 模式可能按 query 在两种 representation 间路由。
+
+因此:
+
+- index-only exact benchmark 可显式使用 FP32 CPU / FP32 GPU 隔离 kernel;
+- collection/service benchmark 必须说明是 native int8 / cuVS float32;
+- 结果必须同时报告 Recall@K、显存和 host memory,不能声称 equal-dtype 或 equal-memory;
+- 要求固定 numerical representation 的应用应选择显式 backend,或关闭 native 候选路由。
+
+### 7.2 低精度路线
+
+低精度 GPU 存储作为显式新能力实现,不做隐式 cast:
+
+1. 先支持可配置的 float16 dataset/query;
+2. 以 float32 brute-force 为 ground truth,测 Recall@K、延迟、吞吐和显存;
+3. 再评估 CAGRA int8 或 VPQ;
+4. native scaled-int8 若要求数值兼容,需要 scale-aware distance/top-k 或候选 rerank,不能直接 cast 成普通 int8。
+
+## 8. 显存准入
+
+当前保守估算包含:
+
+- float32 vector payload:`N * dimension * 4`;
+- CAGRA retained graph:约 `N * graph_degree * 4`;
+- CAGRA build intermediate graph:约 `N * intermediate_graph_degree * 4`;
+- device filter cache:每个 bitset 约 `N / 8`;
+- 默认 `2.0` safety factor;
+- 默认保留 1 GiB 空闲显存。
+
+若预算不足,auto 模式本次查询走 native,并保留 dirty 状态供后续查询重试。显式 `backend=cuvs` 不经过该 gate。估算不是硬保证,allocator、build algorithm、batch 和并发 workload 都可能改变实际 peak;已准入后的 allocation failure 仍会在 auto 模式回退 native。
+
+## 9. 配置
+
+### 9.1 显式 cuVS backend
+
+```json
+{
+ "storage": {
+ "vectordb": {
+ "backend": "cuvs",
+ "distance_metric": "cosine",
+ "cuvs": {
+ "algorithm": "brute_force",
+ "fallback_to_native": true
+ }
+ }
+ }
+}
+```
+
+### 9.2 CAGRA
+
+```json
+{
+ "storage": {
+ "vectordb": {
+ "backend": "cuvs",
+ "cuvs": {
+ "algorithm": "cagra",
+ "build_params": {
+ "graph_degree": 64,
+ "intermediate_graph_degree": 128,
+ "build_algo": "nn_descent"
+ },
+ "search_params": {
+ "itopk_size": 64,
+ "search_width": 1
+ },
+ "fallback_to_native": true
+ }
+ }
+ }
+}
+```
+
+### 9.3 保留 local 默认并自动启用
+
+```json
+{
+ "storage": {
+ "vectordb": {
+ "backend": "local",
+ "cuvs": {
+ "auto_enable": true,
+ "algorithm": "brute_force",
+ "auto_memory_reserve_mb": 1024,
+ "auto_memory_safety_factor": 2.0,
+ "auto_filter_native_threshold": 2000,
+ "auto_path_filter_native_threshold": 200,
+ "filter_cache_size": 16
+ }
+ }
+ }
+}
+```
+
+### 9.4 配置语义
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `algorithm` | `brute_force` | `brute_force` exact 或 `cagra` ANN |
+| `build_params` | `{}` | 传给 CAGRA `IndexParams` |
+| `search_params` | `{}` | 传给 CAGRA `SearchParams` |
+| `fallback_to_native` | `true` | sparse/hybrid 等非 cuVS dense top-k 能力使用 native |
+| `auto_enable` | `false` | 在 `backend=local` 下按空闲显存自动启用 |
+| `auto_memory_reserve_mb` | `1024` | auto admission 后保留的显存 |
+| `auto_memory_safety_factor` | `2.0` | 已知 allocation 的峰值安全系数 |
+| `auto_filter_native_threshold` | `2000` | auto 普通过滤 native 路由阈值 |
+| `auto_path_filter_native_threshold` | `200` | auto URI/path native 路由阈值 |
+| `filter_cache_size` | `16` | device bitset 或 native 路由决策的 LRU 大小 |
+
+依赖安装方式和 CUDA 12/13 wheel 选择见中英文用户指南,不在本计划中复制易过期的版本命令。
+
+## 10. 一致性、并发与错误策略
+
+### 10.1 当前保证
+
+- 顺序 upsert/delete 返回后,下一次 GPU dense query 会先重建,提供 read-after-write;
+- native mutation、cuVS shadow mutation、layout 注册和 GPU search 由跨后端锁协调;
+- GPU search 在单个 index 内当前串行化;
+- native fallback 不持有 GPU 锁,可以继续并发读取;
+- Store 是最终事实来源,重启后派生状态会重新收敛。
+
+### 10.2 错误矩阵
+
+| 场景 | 显式 `backend=cuvs` | Auto mode |
+| --- | --- | --- |
+| cuVS/CuPy 缺失或无 CUDA device | 初始化失败 | 保留 native |
+| 向量维度错误 | 显式报错 | 显式报错 |
+| 显存预算不足 | 不适用预算 gate | 本次查询 native,后续重试 |
+| GPU allocation failure | 异常上抛 | 释放资源并回退 native |
+| GPU build/search 其他异常 | 异常上抛 | 异常上抛 |
+| sparse/hybrid | `fallback_to_native=true` 时 native | native |
+| 空数据集 / filter 无候选 | 空结果 | 空结果 |
+
+### 10.3 已知事务窗口
+
+写链路仍跨 Store、native index 和 cuVS shadow。若进程在中间退出,重启会从 Store 收敛;若进程不退出且 shadow mutation 抛错,内存派生状态可能暂时分叉。后续可用统一 mutation journal、失败后强制 reload,或构建新 snapshot 后原子交换封闭窗口。
+
+## 11. 当前限制
+
+| 限制 | 影响 | 后续方向 |
+| --- | --- | --- |
+| 每次 mutation 后整体重建 | 写后首查和 build 为 O(N) | base + delta、阈值重建、后台 build、原子切换 |
+| host shadow 保存完整 dense vectors | Store/native/GPU 之外增加 host memory | 连续 buffer、共享内存、减少 Python object |
+| 单 index GPU lock | 并发请求转化为排队延迟 | immutable GPU snapshot、CUDA streams、micro-batching |
+| Python/CuPy 数据面 | 对象构造、复制和同步有固定开销 | 先 profiling,再决定是否下沉 C++ cuVS C API |
+| 重启后 lazy rebuild | 大 collection 的首次查询延迟高 | 后台预热、版本化派生 cache |
+| native dense 与 GPU shadow 并存 | CPU 内存和写放大 | 覆盖率和回退策略稳定后再评估裁剪 |
+| CPU int8 / GPU float32 | 数值和内存语义不同 | 明确报告 dtype、Recall@K 和两侧 memory |
+| auto admission 是估算 | 实际 peak 随 allocator 和 workload 波动 | telemetry、校准 safety factor、OOM fallback |
+| 路由阈值来自当前 workload | 不能直接泛化 | 按规模、维度、filter type 做自适应或离线调参 |
+
+## 12. 实施阶段
+
+### Phase 0:功能集成 — 已完成
+
+- cuVS backend 与 local adapter 复用;
+- brute-force / CAGRA;
+- host shadow 与 lazy dirty rebuild;
+- native bitmap bridge 与 cuVS prefilter;
+- memory-aware auto admission;
+- filtered-query candidate routing;
+- mutation、delete、restart 和错误路径测试;
+- 中英文用户文档和 smoke example。
+
+### Phase 1:向量索引与 collection benchmark — 进行中
+
+- 公共 ANN dataset 的 FP32 exact 和 CAGRA recall frontier;
+- 100K/1M、768D/1024D exact scaling;
+- collection-level filter selectivity;
+- first filter、cached filter 和 URI subtree 成本;
+- retained VRAM、build、restart 和 mutation rebuild。
+
+完整矩阵与已有数据分别记录在 benchmark 计划和初步结果文档中。
+
+### Phase 2:数据面并发与 lifecycle 优化
+
+优先级顺序:
+
+1. 将可搜索 GPU index 变成 immutable snapshot;
+2. build 新 snapshot 时继续服务旧 snapshot;
+3. 完成后原子交换,并延迟回收旧资源;
+4. 合并连续 mutation,避免每次写后重复重建;
+5. 评估 CUDA streams、persistent query buffers 和 micro-batching;
+6. 补充 build queue、fallback reason、eligible count、VRAM 和 latency telemetry。
+
+### Phase 3:容量与低精度
+
+- float16 brute-force 的 recall/latency/VRAM;
+- CAGRA int8 或 VPQ frontier;
+- 大 collection 的 host shadow 内存优化;
+- 根据 benchmark 决定 CAGRA 启用规模和参数策略。
+
+### Phase 4:更深层集成 — 按收益决定
+
+只有 Python/CuPy 数据面被证明是主要瓶颈时,才评估:
+
+- cuVS C API 接入 native C++ engine;
+- 共享 CUDA resource、stream 和 memory pool;
+- 多 GPU、分片和 collection 资源隔离;
+- 受 GPU/CUDA/cuVS 版本约束的持久化派生 cache。
+
+## 13. 验收标准
+
+### 13.1 功能正确性
+
+- brute-force 和 CAGRA 在真实 GPU runtime 上可构建、查询和重建;
+- cosine/IP/L2 的 score mapping 符合 OpenViking 接口;
+- scalar + URI 组合过滤结果不越权;
+- arbitrary cuVS row order 能正确映射 native bitmap;
+- upsert 后新值可检索、delete 后旧值不可检索;
+- persistent collection reopen 后可以由 Store 恢复并重建;
+- explicit/auto backend 的失败策略符合错误矩阵;
+- 默认 `backend=local` 和 native dtype 不受影响。
+
+### 13.2 性能报告
+
+每组结果至少包括:
+
+- dataset、dimension、N、metric、K 和 query batch;
+- native/GPU dtype 与 normalization;
+- build time、cold first query、warm p50/p95/p99 和 QPS;
+- Recall@K;
+- host RSS、retained VRAM,能测量时增加 peak VRAM;
+- filter 类型、selectivity、eligible count 和 route;
+- mutation size、write latency 与 next-query rebuild latency;
+- 硬件和公开软件版本。
+
+### 13.3 当前验证状态
+
+- 目标 VectorDB 单元/集成测试通过;
+- stable-ABI loader 测试通过;
+- standalone C++ engine bitmap projection 测试通过;
+- brute-force/CAGRA GPU smoke 覆盖组合过滤、update、delete 和 rebuild;
+- Python lint、C++ syntax 和 diff check 通过;
+- 提交前扫描 staged/committed diff,不允许包含凭据、私钥或非公开环境标识。
+
+## 14. 代码映射
+
+| 文件 | 职责 |
+| --- | --- |
+| `openviking/storage/vectordb/index/cuvs_index.py` | runtime、host shadow、native bitmap 消费、cache、build/search 和 score mapping |
+| `openviking/storage/vectordb/index/local_index.py` | dense 路由、跨后端 mutation lock、native fallback |
+| `openviking/storage/vectordb/collection/local_collection.py` | 传递配置,恢复时注入当前 candidates |
+| `openviking/storage/vectordb_adapters/local_adapter.py` | cuVS adapter 与 auto 配置 |
+| `openviking/storage/vectordb_adapters/factory.py` | 注册 `backend=cuvs` |
+| `openviking_cli/utils/config/vectordb_config.py` | 强类型 cuVS 配置 |
+| `src/index/detail/index_manager_impl.cpp` | label layout 与 native bitmap projection |
+| `src/abi3_engine_backend.cpp` | filter bridge 的稳定 Python ABI |
+| `examples/cuvs_smoke.py` | 真实 GPU 最小功能验证 |
+| `benchmark/cuvs/` | index、collection、service benchmark 与结果汇总 |
+| `tests/vectordb/test_cuvs_index.py` | cuVS index、filter cache、路由和错误测试 |
+| `tests/vectordb/test_cuvs_collection.py` | collection、auto mode、mutation 和恢复集成测试 |
+| `tests/engine/test_index_engine.cpp` | native bitmap 的外部 row-order projection 测试 |
+
+## 15. 待评审问题
+
+1. 目标 workload 的向量维度、单 collection 规模、collection 数量和更新比例是什么?
+2. tenant/URI filter 的真实选择性分布和重复率是什么?
+3. 生产目标更重视单请求 P95,还是多请求 aggregate throughput?
+4. CAGRA 可以接受的 Recall@K、build time 和最低启用规模是什么?
+5. 写后查询是否允许读取旧 GPU snapshot,还是必须同步等待最新 snapshot?
+6. 多 collection 是否共享 CUDA stream/memory pool,如何设置隔离与显存限额?
+7. native dense 副本需要永久保留,还是在 cuVS 覆盖率稳定后允许按配置裁剪?
+
+## 16. 参考资料
+
+- [OpenViking](https://github.com/volcengine/OpenViking)
+- [NVIDIA RAPIDS cuVS](https://github.com/rapidsai/cuvs)
+- [cuVS Getting Started](https://docs.rapids.ai/api/cuvs/stable/getting_started/)
+- [cuVS brute-force Python API](https://docs.rapids.ai/api/cuvs/stable/python_api/neighbors_brute_force/)
+- [cuVS CAGRA Python API](https://docs.rapids.ai/api/cuvs/stable/python_api/neighbors_cagra/)
+- [cuVS filtering](https://docs.rapids.ai/api/cuvs/stable/filtering/)
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 72b47a97b..67a4080a3 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1209,7 +1209,7 @@ Vector database storage configuration
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
-| `backend` | str | VectorDB backend type: 'local' (file-based), 'http' (remote service), 'volcengine' (cloud VikingDB), 'vikingdb' (private deployment), 'qdrant', or 'opengauss' | "local" |
+| `backend` | str | VectorDB backend type: 'local' (file-based), 'http' (remote service), 'volcengine' (cloud VikingDB), 'vikingdb' (private deployment), 'cuvs' (local storage + GPU dense search), 'qdrant', or 'opengauss' | "local" |
| `name` | str | VectorDB collection name | "context" |
| `url` | str | Remote service URL for 'http' type (e.g., 'http://localhost:5000') | null |
| `project_name` | str | Project name (alias project) | "default" |
@@ -1218,6 +1218,7 @@ Vector database storage configuration
| `sparse_weight` | float | Sparse weight for hybrid vector search, only effective when using hybrid index | 0.0 |
| `volcengine` | object | 'volcengine' type VikingDB configuration | - |
| `vikingdb` | object | 'vikingdb' type private deployment configuration | - |
+| `cuvs` | object | NVIDIA cuVS configuration for the 'cuvs' backend and the opt-in memory-aware auto mode on 'local'; see the [cuVS guide](./16-cuvs.md) | - |
| `qdrant` | object | 'qdrant' type Qdrant configuration | - |
| `opengauss` | object | 'opengauss' native vector backend configuration | - |
diff --git a/docs/en/guides/16-cuvs.md b/docs/en/guides/16-cuvs.md
new file mode 100644
index 000000000..5fbca6ace
--- /dev/null
+++ b/docs/en/guides/16-cuvs.md
@@ -0,0 +1,151 @@
+# NVIDIA cuVS dense search backend
+
+The `cuvs` backend keeps OpenViking's embedded record store, scalar indexes, sparse retrieval, and recovery logic, while executing dense vector search with NVIDIA cuVS. cuVS 26.06 Python wheels require Python 3.11 or newer.
+
+Install the package matching the host CUDA major version:
+
+```bash
+# CUDA 12
+pip install -e .
+pip install cuvs-cu12 'cupy-cuda12x[ctk]' --extra-index-url=https://pypi.nvidia.com
+
+# CUDA 13
+pip install -e .
+pip install cuvs-cu13 'cupy-cuda13x[ctk]' --extra-index-url=https://pypi.nvidia.com
+```
+
+Start with exact brute-force search:
+
+```json
+{
+ "storage": {
+ "workspace": "/data/openviking",
+ "vectordb": {
+ "backend": "cuvs",
+ "distance_metric": "cosine",
+ "cuvs": {
+ "algorithm": "brute_force",
+ "fallback_to_native": true,
+ "filter_cache_size": 16
+ }
+ }
+ }
+}
+```
+
+Set `algorithm` to `cagra` for approximate graph search. `build_params` and `search_params` are passed to cuVS `cagra.IndexParams` and `cagra.SearchParams` respectively.
+
+### Memory-aware auto mode
+
+Keep `backend` set to `local` and enable `cuvs.auto_enable` to use otherwise
+idle GPU memory without changing the default behavior for other installations:
+
+```json
+{
+ "storage": {
+ "vectordb": {
+ "backend": "local",
+ "cuvs": {
+ "auto_enable": true,
+ "algorithm": "brute_force",
+ "auto_memory_reserve_mb": 1024,
+ "auto_memory_safety_factor": 2.0,
+ "auto_filter_native_threshold": 2000,
+ "auto_path_filter_native_threshold": 200
+ }
+ }
+ }
+}
+```
+
+Before each lazy build or rebuild, auto mode reads free device memory and
+estimates the float32 vector payload, CAGRA graph and intermediate graph when
+applicable, and the configured filter-bitset cache. It multiplies those known
+allocations by `auto_memory_safety_factor` and then preserves
+`auto_memory_reserve_mb`. If the estimate does not fit, or cuVS/GPU discovery
+is unavailable, that query uses the unchanged native index. The cuVS index
+remains dirty so a later query can retry after GPU memory becomes available.
+An allocation failure after admission also falls back to native. Explicit
+`backend: "cuvs"` retains fail-fast behavior and does not use this gate.
+Auto mode also uses the eligible count returned by the native scalar index for
+latency-aware filtered-query routing. Filters with at most
+`auto_filter_native_threshold` candidates use native vector recall; path
+filters use the lower `auto_path_filter_native_threshold` because URI Trie and
+bitmap construction can dominate wider subtrees. The defaults are 2,000 and
+200 candidates respectively, and either value can be set to zero to disable
+that route. These crossover values are hardware- and workload-dependent.
+Explicit `backend: "cuvs"` continues to use cuVS for supported dense queries.
+
+## GPU memory footprint
+
+The current GPU shadow is float32, so brute-force's dominant retained payload
+is `N * dimension * 4` bytes. CAGRA additionally retains approximately
+`N * graph_degree * 4` bytes for the graph and can require an intermediate
+`N * intermediate_graph_degree * 4` bytes while building. Each cached filter
+bitset costs approximately `ceil(N / 32) * 4` bytes.
+
+Prior index-only runs measured the following `cudaMemGetInfo` deltas from just
+before to just after build; each value is the median of five clean processes:
+
+| Dataset | cuVS algorithm | Measured GPU delta |
+| --- | --- | ---: |
+| 100K x 768D | brute-force | 294 MiB |
+| 1M x 768D | brute-force | 2.9 GiB |
+| 100K x 1024D | brute-force | 392 MiB |
+| 1M x 1024D | brute-force | 3.9 GiB |
+| 1,183,514 x 100D | brute-force | 452 MiB |
+| 1,183,514 x 100D | CAGRA | 872 MiB |
+
+These are retained-build deltas rather than sampled peak VRAM. Allocator
+state, cuVS version, CAGRA parameters, query batch size, and concurrent GPU
+workloads can increase the peak. The delta also excludes the approximately
+327 MiB CUDA runtime/context baseline observed before build in these processes.
+This is why auto mode initializes the runtime first, reads the remaining free
+memory, and then applies a conservative safety factor and independent reserve
+rather than admitting from the vector payload alone.
+
+## Data type and native-index behavior
+
+Enabling cuVS does not change OpenViking's default backend or rewrite the
+native CPU index. The normal collection metadata remains
+`VectorIndex.Quant=int8`, so native fallback searches keep the existing
+per-vector-scale int8 quantization. In parallel, the current cuVS runtime keeps
+its GPU shadow in float32 because the cuVS Python brute-force API accepts
+float32/float16 rather than OpenViking's scaled int8 record format.
+
+The two dense paths therefore do not have equal memory or numerical semantics:
+native results are exact within the quantized CPU representation, while cuVS
+brute-force is exact over the retained float32 vectors. Small score or neighbor
+ordering differences are expected. Benchmarks must report the two data types
+and include Recall@K instead of presenting the comparison as equal-dtype or
+equal-memory. This separation is intentional for the initial opt-in
+integration and leaves existing CPU behavior unchanged. In auto mode, the
+filter candidate thresholds can select either representation per query, so
+applications that require one fixed numerical representation should use an
+explicit backend or disable the native-routing thresholds.
+
+Lower-precision GPU storage is a follow-up rather than an implicit cast. The
+first candidate is configurable float16 for both the cuVS dataset and queries,
+with Recall@K measured against float32. Native-compatible int8 requires a
+separate design because OpenViking uses a per-vector scale, while cuVS
+brute-force does not accept that scaled-int8 representation. CAGRA int8 or PQ
+compression must likewise be evaluated as approximate modes with an explicit
+recall/latency/memory frontier.
+
+The integration rebuilds the GPU index lazily after an upsert or delete. On
+each rebuild it registers the cuVS label order with the native engine once.
+The first use of a scalar or URI filter then reuses OpenViking's native
+scalar/path index and projects its bitmap into cuVS row order; it does not scan
+all host-side records in Python. `filter_cache_size` retains the resulting
+device bitsets and routing decisions and invalidates them on mutation.
+Sparse/hybrid queries fall back to OpenViking's native local index when
+`fallback_to_native` is enabled. The canonical vectors remain in the local
+store and repopulate cuVS after restart.
+
+The `[ctk]` CuPy extra installs the CUDA toolkit headers required by the cuVS
+Python interop path, even when the host provides a CUDA driver but no toolkit.
+
+After installation, run `python examples/cuvs_smoke.py` for an exact
+GPU-backed write and filtered-search check, or
+`python examples/cuvs_smoke.py --algorithm cagra` to exercise the graph index.
+Neither command requires an embedding or VLM service.
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 5836af4da..bfe108078 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1181,7 +1181,7 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
-| `backend` | str | VectorDB 后端类型: 'local'(基于文件), 'http'(远程服务), 'volcengine'(云上 VikingDB), 'vikingdb'(私有部署), 'qdrant' 或 'opengauss' | "local" |
+| `backend` | str | VectorDB 后端类型: 'local'(基于文件), 'http'(远程服务), 'volcengine'(云上 VikingDB), 'vikingdb'(私有部署), 'cuvs'(本地存储 + GPU dense search), 'qdrant' 或 'opengauss' | "local" |
| `name` | str | VectorDB 的集合名称 | "context" |
| `url` | str | 'http' 类型的远程服务 URL(例如 'http://localhost:5000') | null |
| `project_name` | str | 项目名称(别名 project) | "default" |
@@ -1190,6 +1190,7 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系
| `sparse_weight` | float | 混合向量搜索的稀疏权重,仅在使用混合索引时生效 | 0.0 |
| `volcengine` | object | 'volcengine' 类型的 VikingDB 配置 | - |
| `vikingdb` | object | 'vikingdb' 类型的私有部署配置 | - |
+| `cuvs` | object | NVIDIA cuVS 配置,也用于在 'local' 下显式开启显存感知自动模式,参见 [cuVS 使用指南](./16-cuvs.md) | - |
| `qdrant` | object | 'qdrant' 类型的 Qdrant 配置 | - |
| `opengauss` | object | 'opengauss' 原生向量后端配置 | - |
diff --git a/docs/zh/guides/16-cuvs.md b/docs/zh/guides/16-cuvs.md
new file mode 100644
index 000000000..feadfa74f
--- /dev/null
+++ b/docs/zh/guides/16-cuvs.md
@@ -0,0 +1,229 @@
+# 使用 NVIDIA cuVS 进行本地向量检索
+
+OpenViking 的 `cuvs` 后端保留本地后端的记录持久化、标量索引、稀疏检索和故障恢复,只把 dense vector search 交给 NVIDIA cuVS。这样可以先验证 GPU 检索链路,而不需要重新实现一个完整的向量数据库。
+
+## 环境要求
+
+- Linux x86_64 或 aarch64
+- 可见的 NVIDIA GPU;cuVS 26.06 预编译包要求 Ampere 或更新架构
+- CUDA 12.2+;安装与本机 CUDA 大版本匹配的 Python 包
+- Python 3.11+(cuVS 26.06 的 Python wheel 要求)
+
+CUDA 12:
+
+```bash
+pip install -e .
+pip install cuvs-cu12 'cupy-cuda12x[ctk]' --extra-index-url=https://pypi.nvidia.com
+```
+
+CUDA 13:
+
+```bash
+pip install -e .
+pip install cuvs-cu13 'cupy-cuda13x[ctk]' --extra-index-url=https://pypi.nvidia.com
+```
+
+CuPy 的 `[ctk]` extra 会安装 cuVS Python 互操作路径所需的 CUDA toolkit
+headers;即使宿主机已有 CUDA driver、但没有完整 toolkit,也建议保留该 extra。
+
+## 配置
+
+先用 `brute_force` 跑通精确检索:
+
+```json
+{
+ "storage": {
+ "workspace": "/data/openviking",
+ "vectordb": {
+ "backend": "cuvs",
+ "distance_metric": "cosine",
+ "cuvs": {
+ "algorithm": "brute_force",
+ "fallback_to_native": true,
+ "filter_cache_size": 16
+ }
+ }
+ }
+}
+```
+
+数据量增大后可以切换到 CAGRA,并直接传入 cuVS 的构建与查询参数:
+
+```json
+{
+ "storage": {
+ "vectordb": {
+ "backend": "cuvs",
+ "cuvs": {
+ "algorithm": "cagra",
+ "build_params": {
+ "graph_degree": 64,
+ "intermediate_graph_degree": 128,
+ "build_algo": "nn_descent"
+ },
+ "search_params": {
+ "itopk_size": 64,
+ "search_width": 1
+ }
+ }
+ }
+ }
+}
+```
+
+### 显存感知自动模式
+
+如果希望保留 `local` 为默认 backend、只在 GPU 有足够空闲显存时自动启用 cuVS,
+可以打开以下开关:
+
+```json
+{
+ "storage": {
+ "vectordb": {
+ "backend": "local",
+ "cuvs": {
+ "auto_enable": true,
+ "algorithm": "brute_force",
+ "auto_memory_reserve_mb": 1024,
+ "auto_memory_safety_factor": 2.0,
+ "auto_filter_native_threshold": 2000,
+ "auto_path_filter_native_threshold": 200
+ }
+ }
+ }
+}
+```
+
+每次 lazy build/rebuild 前,auto 模式会读取当前空闲显存,并估算 float32 vector
+payload、CAGRA graph/intermediate graph(如适用)和 filter-bitset cache,再乘以
+`auto_memory_safety_factor`,同时保留 `auto_memory_reserve_mb`。如果预算不足,
+或者 cuVS/GPU 不可用,本次查询继续使用未改变的 native index;cuVS index 保持
+dirty,后续查询会在显存释放后重新尝试。通过 admission 后若仍遇到 GPU allocation
+failure,也会回退 native。显式配置 `backend: "cuvs"` 时仍保持 fail-fast,不经过
+这层自动判断。
+
+auto 模式还会使用 native scalar index 返回的候选数做 filtered query 延迟路由:
+候选数不超过 `auto_filter_native_threshold` 时使用 native vector recall;路径过滤
+采用更低的 `auto_path_filter_native_threshold`,因为宽 URI 子树的 Trie 遍历和
+bitmap union 本身可能占主要开销。默认阈值分别为 2,000 和 200,设为 0 可关闭
+对应路由。阈值与硬件、维度和工作负载有关。显式 `backend: "cuvs"` 对支持的
+dense query 仍固定使用 cuVS。
+
+## GPU 显存占用
+
+当前 GPU shadow 是 float32,因此 brute-force 的主要常驻 payload 为
+`N * dimension * 4` bytes。CAGRA 还需要约 `N * graph_degree * 4` bytes
+保存 graph,构建期间可能需要 `N * intermediate_graph_degree * 4` bytes 的
+intermediate graph。每个缓存 filter bitset 约占 `ceil(N / 32) * 4` bytes。
+
+之前的 index-only 测试使用 `cudaMemGetInfo` 记录 build 前后的显存增量;下表每项
+均为 5 个干净进程的中位数:
+
+| 数据集 | cuVS 算法 | 实测 GPU 增量 |
+| --- | --- | ---: |
+| 100K x 768D | brute-force | 294 MiB |
+| 1M x 768D | brute-force | 2.9 GiB |
+| 100K x 1024D | brute-force | 392 MiB |
+| 1M x 1024D | brute-force | 3.9 GiB |
+| 1,183,514 x 100D | brute-force | 452 MiB |
+| 1,183,514 x 100D | CAGRA | 872 MiB |
+
+这些数值是 build 完成后的常驻增量,不是采样得到的 peak VRAM。allocator 状态、
+cuVS 版本、CAGRA 参数、query batch 和并行 GPU workload 都可能进一步提高峰值;
+它们也不包含这些进程在 build 前观测到的约 327 MiB CUDA runtime/context 基线。
+因此 auto 模式会先初始化 runtime、读取剩余空闲显存,再应用保守 safety factor
+和独立 reserve,而不会只按 vector payload 准入。
+
+距离语义与原本的 OpenViking 本地后端保持一致:cosine 会先做 L2 归一化再执行 inner product;L2 的返回分数仍为 `1 - squared_l2`,分数越大越相似。
+
+## 数据类型与原生索引行为
+
+启用 cuVS 不会改变 OpenViking 的默认后端,也不会重写原生 CPU 索引。正常的
+collection metadata 仍为 `VectorIndex.Quant=int8`,因此 native fallback
+继续使用现有的、带逐向量 scale 的 int8 量化。与此同时,当前 cuVS runtime
+在 GPU 上保留 float32 shadow,因为 cuVS Python brute-force API 支持
+float32/float16,但不能直接表示 OpenViking 的 scaled-int8 record 格式。
+
+所以两条 dense search 路径不是等内存、等数值语义的比较:native 是在 CPU
+量化表示上的精确检索,cuVS brute-force 是在保留的 float32 向量上的精确检索,
+两者可能出现少量 score 或 neighbor ordering 差异。Benchmark 必须同时报告
+两边的数据类型和 Recall@K,不能将结果描述为 equal-dtype 或 equal-memory。
+这是首版 opt-in 集成的有意边界,现有 CPU 行为保持不变。auto 模式会根据 filter
+候选阈值在两种表示之间选择;要求固定数值表示的应用应使用显式 backend,或将
+native 路由阈值设为 0。
+
+GPU 低精度存储作为后续显式能力实现,不做隐式 cast。第一步可以让 cuVS dataset
+与 query 可配置为 float16,并以 float32 为 ground truth 测 Recall@K。与 native
+兼容的 int8 需要单独设计,因为 OpenViking 使用逐向量 scale,而 cuVS
+brute-force 不能直接接收这种 scaled-int8 表示。CAGRA int8 或 PQ compression
+也应作为近似模式,单独报告 recall/latency/memory frontier。
+
+## 最小功能验证
+
+仓库提供的 smoke test 不依赖 embedding 或 VLM 服务:
+
+```bash
+python examples/cuvs_smoke.py
+
+# 验证 CAGRA 图索引
+python examples/cuvs_smoke.py --algorithm cagra
+```
+
+核心调用方式如下:
+
+```python
+from openviking.storage.vectordb.collection.local_collection import (
+ get_or_create_local_collection,
+)
+
+collection = get_or_create_local_collection(
+ meta_data={
+ "CollectionName": "cuvs_smoke",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ {"FieldName": "account_id", "FieldType": "string"},
+ {"FieldName": "uri", "FieldType": "path"},
+ ],
+ },
+ config={
+ "dense_search": {
+ "backend": "cuvs",
+ "algorithm": "brute_force",
+ "fallback_to_native": True,
+ }
+ },
+)
+collection.create_index(
+ "default",
+ {
+ "IndexName": "default",
+ "VectorIndex": {"IndexType": "flat", "Distance": "cosine"},
+ "ScalarIndex": ["account_id", "uri"],
+ },
+)
+collection.upsert_data(
+ [
+ {"id": "a", "vector": [1, 0, 0, 0], "account_id": "demo", "uri": "/docs/a"},
+ {"id": "b", "vector": [0, 1, 0, 0], "account_id": "demo", "uri": "/docs/b"},
+ ]
+)
+result = collection.search_by_vector(
+ "default",
+ dense_vector=[1, 0, 0, 0],
+ limit=2,
+ filters={"op": "must", "field": "account_id", "conds": ["demo"]},
+)
+assert [item.id for item in result.data] == ["a", "b"]
+collection.close()
+```
+
+## 当前阶段的限制
+
+- cuVS 只接管 pure dense search;sparse/hybrid query 在 `fallback_to_native=true` 时走原生本地索引。
+- local 集成通过 native scalar/path index 生成 prefilter,因此继承原生 DSL、`date_time`、`geo_point` 和 path depth 的过滤语义,而不是在 Python 重复实现。
+- 每次 GPU rebuild 会向 native engine 注册一次 cuVS label 顺序。新过滤条件直接复用 native scalar/path index 的 bitmap,再投影为 cuVS row bitset,不再用 Python 扫描所有 host-side records。
+- `filter_cache_size` 会保留最近使用的 GPU bitset 或 native 路由决策,并在数据更新时失效。
+- 每次 upsert/delete 后会在下一次查询时重建 GPU 索引。这保证了首版更新语义正确,但不适合写密集负载。
+- cuVS 索引不作为权威持久化数据;进程重启时会从 OpenViking 本地 store 重建,因此不受 cuVS 跨版本序列化格式变化影响。
+- `brute_force` 适合功能对齐和 ground truth;CAGRA 的 graph/search 参数需要在后续结合召回率、QPS、延迟和显存进行调优。
diff --git a/examples/cuvs_smoke.py b/examples/cuvs_smoke.py
new file mode 100644
index 000000000..362b6f89b
--- /dev/null
+++ b/examples/cuvs_smoke.py
@@ -0,0 +1,124 @@
+"""Minimal GPU smoke test for OpenViking's cuVS dense-search backend."""
+
+import argparse
+
+from openviking.storage.vectordb.collection.local_collection import (
+ get_or_create_local_collection,
+)
+
+
+def main(algorithm: str) -> None:
+ collection = get_or_create_local_collection(
+ meta_data={
+ "CollectionName": "cuvs_smoke",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ {"FieldName": "account_id", "FieldType": "string"},
+ {"FieldName": "uri", "FieldType": "path"},
+ ],
+ },
+ config={
+ "dense_search": {
+ "backend": "cuvs",
+ "algorithm": algorithm,
+ "fallback_to_native": True,
+ "build_params": (
+ {"graph_degree": 16, "intermediate_graph_degree": 32}
+ if algorithm == "cagra"
+ else {}
+ ),
+ "search_params": {"itopk_size": 64} if algorithm == "cagra" else {},
+ }
+ },
+ )
+ try:
+ collection.create_index(
+ "default",
+ {
+ "IndexName": "default",
+ "VectorIndex": {"IndexType": "flat", "Distance": "cosine"},
+ "ScalarIndex": ["account_id", "uri"],
+ },
+ )
+ records = [
+ {
+ "id": "a",
+ "vector": [1, 0, 0, 0],
+ "account_id": "demo",
+ "uri": "/docs/a",
+ },
+ {
+ "id": "b",
+ "vector": [0, 1, 0, 0],
+ "account_id": "demo",
+ "uri": "/docs/b",
+ },
+ ]
+ if algorithm == "cagra":
+ # CAGRA is a graph index and needs more than a two-point toy dataset.
+ # Filler records are excluded by the scalar prefilter below.
+ records.extend(
+ {
+ "id": f"filler-{index}",
+ "vector": [0, 0, 1, index / 128],
+ "account_id": "filler",
+ "uri": f"/fillers/{index}",
+ }
+ for index in range(128)
+ )
+ collection.upsert_data(records)
+ demo_filter = {
+ "op": "and",
+ "conds": [
+ {"op": "must", "field": "account_id", "conds": ["demo"]},
+ {
+ "op": "must",
+ "field": "uri",
+ "conds": ["/docs"],
+ "para": "-d=-1",
+ },
+ ],
+ }
+ result = collection.search_by_vector(
+ "default",
+ dense_vector=[1, 0, 0, 0],
+ limit=2,
+ filters=demo_filter,
+ )
+ ids = [item.id for item in result.data]
+ assert ids == ["a", "b"], ids
+
+ collection.update_data(
+ [
+ {
+ "id": "b",
+ "vector": [2, 0, 0, 0],
+ "account_id": "demo",
+ "uri": "/docs/b",
+ }
+ ]
+ )
+ collection.delete_data(["a"])
+ result = collection.search_by_vector(
+ "default",
+ dense_vector=[1, 0, 0, 0],
+ limit=2,
+ filters=demo_filter,
+ )
+ ids_after_mutation = [item.id for item in result.data]
+ assert ids_after_mutation == ["b"], ids_after_mutation
+ print(f"cuVS {algorithm} smoke test passed:", ids, "->", ids_after_mutation)
+ finally:
+ collection.close()
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser()
+ parser.add_argument(
+ "--algorithm",
+ choices=("brute_force", "cagra"),
+ default="brute_force",
+ )
+ args = parser.parse_args()
+ main(args.algorithm)
diff --git a/openviking/storage/vectordb/collection/local_collection.py b/openviking/storage/vectordb/collection/local_collection.py
index 8b271e411..64940177b 100644
--- a/openviking/storage/vectordb/collection/local_collection.py
+++ b/openviking/storage/vectordb/collection/local_collection.py
@@ -134,6 +134,7 @@ class LocalCollection(ICollection):
ENV_INDEX_MAINTENANCE_SECONDS,
DEFAULT_INDEX_MAINTENANCE_SECONDS,
)
+ self.dense_search_config = dict((config or {}).get("dense_search", {}))
self.store_mgr: Optional[StoreManager] = store_mgr
self.data_processor = DataProcessor(
@@ -911,6 +912,7 @@ class VolatileCollection(LocalCollection):
name=index_name,
meta=meta,
cands_list=cands_list,
+ dense_search_config=self.dense_search_config,
)
return index
@@ -944,6 +946,9 @@ class PersistCollection(LocalCollection):
pass
if index_count > 0:
logger.info("Recovering %d index(es) from %s", index_count, self.index_dir)
+ recovery_candidates = (
+ self.store_mgr.get_all_cands_data() if self.store_mgr is not None else []
+ )
for folder in os.listdir(self.index_dir):
try:
index_dir = safe_join(self.index_dir, folder)
@@ -975,7 +980,12 @@ class PersistCollection(LocalCollection):
# all data from the delta log (CandidateData) regardless of when that data was created.
# If we used the default (current time), the index would ignore older data in the log.
index = PersistentIndex(
- name=index_name, path=self.index_dir, meta=meta, initial_timestamp=0
+ name=index_name,
+ path=self.index_dir,
+ meta=meta,
+ cands_list=recovery_candidates,
+ initial_timestamp=0,
+ dense_search_config=self.dense_search_config,
)
newest_version = index.get_newest_version()
if not self.store_mgr:
@@ -1130,6 +1140,7 @@ class PersistCollection(LocalCollection):
meta=meta,
cands_list=cands_list,
force_rebuild=force_rebuild,
+ dense_search_config=self.dense_search_config,
)
return index
diff --git a/openviking/storage/vectordb/engine/_python_api.py b/openviking/storage/vectordb/engine/_python_api.py
index 549aec11d..d24f95097 100644
--- a/openviking/storage/vectordb/engine/_python_api.py
+++ b/openviking/storage/vectordb/engine/_python_api.py
@@ -347,6 +347,26 @@ class SearchResult:
)
+class FilterResult:
+ __slots__ = ("eligible_count", "bitset_words")
+
+ def __init__(
+ self,
+ *,
+ eligible_count: int = 0,
+ bitset_words: list[int] | None = None,
+ ):
+ self.eligible_count = eligible_count
+ self.bitset_words = bitset_words or []
+
+ @classmethod
+ def from_backend(cls, payload: dict[str, Any]) -> "FilterResult":
+ return cls(
+ eligible_count=int(payload.get("eligible_count", 0)),
+ bitset_words=[int(word) for word in payload.get("bitset_words", [])],
+ )
+
+
class StateResult:
__slots__ = ("update_timestamp", "element_count")
@@ -439,6 +459,14 @@ def build_abi3_exports(backend: Any) -> dict[str, Any]:
def search(self, req: SearchRequest) -> SearchResult:
return SearchResult.from_backend(self._backend._index_engine_search(self._handle, req))
+ def set_filter_layout(self, ordered_labels: list[int]) -> int:
+ return int(self._backend._index_engine_set_filter_layout(self._handle, ordered_labels))
+
+ def evaluate_filter(self, dsl: str) -> FilterResult:
+ return FilterResult.from_backend(
+ self._backend._index_engine_evaluate_filter(self._handle, dsl)
+ )
+
def dump(self, path: str) -> int:
return int(self._backend._index_engine_dump(self._handle, path))
@@ -490,6 +518,7 @@ def build_abi3_exports(backend: Any) -> dict[str, Any]:
"DeleteDataRequest": DeleteDataRequest,
"SearchRequest": SearchRequest,
"SearchResult": SearchResult,
+ "FilterResult": FilterResult,
"StateResult": StateResult,
"StorageOp": StorageOp,
"IndexEngine": IndexEngine,
diff --git a/openviking/storage/vectordb/index/cuvs_index.py b/openviking/storage/vectordb/index/cuvs_index.py
new file mode 100644
index 000000000..14bea8817
--- /dev/null
+++ b/openviking/storage/vectordb/index/cuvs_index.py
@@ -0,0 +1,796 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""cuVS-backed dense vector search for the embedded VectorDB.
+
+cuVS is an index library rather than a complete vector database. This module
+therefore owns only the dense vectors and their label mapping. OpenViking's
+existing local engine remains responsible for durable records, scalar indexes,
+sparse retrieval, and crash recovery.
+
+The first implementation deliberately favors correctness and simple lifecycle
+semantics: upserts and deletes update a host-side snapshot and invalidate the
+GPU index. The next search rebuilds the cuVS index in one batch. This makes
+all OpenViking mutations work with both brute-force and CAGRA even though cuVS
+does not expose the same update/delete contract for every index type.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import re
+import threading
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from openviking.storage.vectordb.store.data import CandidateData, DeltaRecord
+
+logger = logging.getLogger(__name__)
+
+
+class CuVSUnavailableError(RuntimeError):
+ """Raised when the configured cuVS runtime cannot be used."""
+
+
+class CuVSMemoryBudgetError(RuntimeError):
+ """Raised when auto mode cannot safely admit a cuVS index into free VRAM."""
+
+
+class CuVSNativeRouteError(RuntimeError):
+ """Raised when auto mode predicts that a filtered native search is cheaper."""
+
+
+class UnsupportedCuVSFilterError(ValueError):
+ """Raised when a filter cannot be translated to a cuVS prefilter."""
+
+
+@dataclass(frozen=True)
+class CuVSMemoryEstimate:
+ """Conservative GPU-memory estimate used only for auto-admission."""
+
+ vector_bytes: int
+ graph_bytes: int
+ build_graph_bytes: int
+ filter_cache_bytes: int
+ estimated_peak_bytes: int
+
+
+def estimate_cuvs_memory(
+ *,
+ vector_count: int,
+ dimension: int,
+ algorithm: str,
+ build_params: Mapping[str, Any],
+ filter_cache_size: int,
+ safety_factor: float,
+) -> CuVSMemoryEstimate:
+ """Estimate peak VRAM without changing the explicit cuVS backend behavior.
+
+ The estimate accounts for the float32 dataset, retained and intermediate
+ CAGRA graphs, and the configured number of cached filter bitsets. cuVS and
+ allocator workspaces vary by release and build algorithm, so the configured
+ safety factor intentionally covers the remaining uncertainty.
+ """
+
+ vector_count = max(0, int(vector_count))
+ dimension = max(0, int(dimension))
+ safety_factor = float(safety_factor)
+ if safety_factor < 1.0:
+ raise ValueError("cuVS auto memory safety factor must be at least 1.0")
+
+ vector_bytes = vector_count * dimension * 4
+ graph_bytes = 0
+ build_graph_bytes = 0
+ if algorithm == "cagra":
+ graph_degree = max(0, int(build_params.get("graph_degree", 64)))
+ intermediate_graph_degree = max(0, int(build_params.get("intermediate_graph_degree", 128)))
+ graph_bytes = vector_count * graph_degree * 4
+ build_graph_bytes = vector_count * intermediate_graph_degree * 4
+
+ filter_word_count = (vector_count + 31) // 32
+ filter_cache_bytes = filter_word_count * 4 * max(0, int(filter_cache_size))
+ known_peak_bytes = vector_bytes + graph_bytes + build_graph_bytes + filter_cache_bytes
+ estimated_peak_bytes = math.ceil(known_peak_bytes * safety_factor)
+ return CuVSMemoryEstimate(
+ vector_bytes=vector_bytes,
+ graph_bytes=graph_bytes,
+ build_graph_bytes=build_graph_bytes,
+ filter_cache_bytes=filter_cache_bytes,
+ estimated_peak_bytes=estimated_peak_bytes,
+ )
+
+
+def _normalize(vector: Sequence[float]) -> List[float]:
+ norm = math.sqrt(sum(float(value) * float(value) for value in vector))
+ if norm == 0:
+ return [float(value) for value in vector]
+ return [float(value) / norm for value in vector]
+
+
+def _normalize_path(value: str) -> str:
+ stripped = value.strip()
+ return stripped if stripped.startswith("/") else f"/{stripped}"
+
+
+def _path_matches(value: Any, expected: Any, depth: Optional[int]) -> bool:
+ if not isinstance(value, str) or not isinstance(expected, str):
+ return False
+ value_path = _normalize_path(value).rstrip("/") or "/"
+ expected_path = _normalize_path(expected).rstrip("/") or "/"
+ if value_path == expected_path:
+ relative_depth = 0
+ elif expected_path == "/":
+ relative_depth = len([part for part in value_path.split("/") if part])
+ elif value_path.startswith(expected_path + "/"):
+ suffix = value_path[len(expected_path) + 1 :]
+ relative_depth = len([part for part in suffix.split("/") if part])
+ else:
+ return False
+
+ if depth is None or depth < 0:
+ return True
+ return relative_depth <= depth
+
+
+def _parse_depth(para: Any) -> Optional[int]:
+ if para in (None, ""):
+ return None
+ if not isinstance(para, str):
+ raise UnsupportedCuVSFilterError(f"Unsupported path filter parameter: {para!r}")
+ match = re.fullmatch(r"\s*-d=(-?\d+)\s*", para)
+ if not match:
+ raise UnsupportedCuVSFilterError(f"Unsupported path filter parameter: {para!r}")
+ return int(match.group(1))
+
+
+def _value_matches(value: Any, conditions: Sequence[Any]) -> bool:
+ if isinstance(value, list):
+ return any(condition in value for condition in conditions)
+ return value in conditions
+
+
+def _contains(value: Any, substring: Any) -> bool:
+ if not isinstance(substring, str):
+ return False
+ if isinstance(value, str):
+ return substring in value
+ if isinstance(value, list):
+ return any(substring in item for item in value if isinstance(item, str))
+ return False
+
+
+def _in_range(value: Any, node: Mapping[str, Any]) -> bool:
+ if value is None:
+ return False
+ try:
+ if node.get("gt") is not None and not value > node["gt"]:
+ return False
+ if node.get("gte") is not None and not value >= node["gte"]:
+ return False
+ if node.get("lt") is not None and not value < node["lt"]:
+ return False
+ if node.get("lte") is not None and not value <= node["lte"]:
+ return False
+ except TypeError:
+ return False
+ return True
+
+
+def _filter_uses_field_type(
+ node: Optional[Mapping[str, Any]],
+ field_types: Mapping[str, str],
+ expected_type: str,
+) -> bool:
+ if not node or not isinstance(node, Mapping):
+ return False
+ nested = node.get("filter")
+ if isinstance(nested, Mapping) and _filter_uses_field_type(nested, field_types, expected_type):
+ return True
+ field = node.get("field")
+ if isinstance(field, str) and str(field_types.get(field, "")).lower() == expected_type:
+ return True
+ children = node.get("conds")
+ if isinstance(children, list):
+ return any(
+ _filter_uses_field_type(child, field_types, expected_type)
+ for child in children
+ if isinstance(child, Mapping)
+ )
+ return False
+
+
+def matches_filter(
+ fields: Mapping[str, Any],
+ node: Optional[Mapping[str, Any]],
+ field_types: Mapping[str, str],
+) -> bool:
+ """Evaluate the scalar-filter subset supported by the cuVS backend.
+
+ The supported DSL is the one emitted by ``CollectionAdapter`` for normal
+ OpenViking search: ``and``, ``or``, ``must``, ``must_not``, ``contains``,
+ ``range``, ``range_out``, and path depth parameters. Unsupported nodes are
+ rejected so the caller can safely fall back to the native local engine.
+ """
+
+ if not node:
+ return True
+ if not isinstance(node, Mapping):
+ raise UnsupportedCuVSFilterError(f"Filter node must be an object: {node!r}")
+ if "filter" in node and len(node) == 1:
+ nested = node.get("filter")
+ if nested is None:
+ return True
+ if not isinstance(nested, Mapping):
+ raise UnsupportedCuVSFilterError("The filter wrapper must contain an object")
+ return matches_filter(fields, nested, field_types)
+
+ op = str(node.get("op", "")).lower()
+ if op in {"and", "or"}:
+ children = node.get("conds", [])
+ if not isinstance(children, list):
+ raise UnsupportedCuVSFilterError(f"{op} filter conds must be a list")
+ results = [matches_filter(fields, child, field_types) for child in children]
+ return all(results) if op == "and" else any(results)
+
+ field = node.get("field")
+ if not isinstance(field, str):
+ raise UnsupportedCuVSFilterError(f"Filter field must be a string: {node!r}")
+ field_type = str(field_types.get(field, "")).lower()
+ if field_type in {"date_time", "geo_point"}:
+ # Those fields require OpenViking's type conversion logic. Falling back
+ # avoids subtly different results for timezone and geo comparisons.
+ raise UnsupportedCuVSFilterError(f"cuVS prefilter does not support {field_type} fields")
+ value = fields.get(field)
+
+ if op in {"must", "must_not"}:
+ conditions = node.get("conds", [])
+ if not isinstance(conditions, list):
+ raise UnsupportedCuVSFilterError(f"{op} filter conds must be a list")
+ if field_type == "path":
+ depth = _parse_depth(node.get("para"))
+ matched = any(_path_matches(value, condition, depth) for condition in conditions)
+ else:
+ if node.get("para") not in (None, ""):
+ raise UnsupportedCuVSFilterError(
+ f"Filter parameters are only supported for path fields: {node!r}"
+ )
+ matched = _value_matches(value, conditions)
+ return matched if op == "must" else not matched
+
+ if op == "contains":
+ return _contains(value, node.get("substring"))
+ if op == "range":
+ return _in_range(value, node)
+ if op == "range_out":
+ return not _in_range(value, node)
+
+ raise UnsupportedCuVSFilterError(f"Unsupported cuVS filter operation: {op!r}")
+
+
+class _CuVSRuntime:
+ """Small adapter around the public cuVS Python API."""
+
+ def __init__(
+ self,
+ algorithm: str,
+ metric: str,
+ build_params: Mapping[str, Any],
+ search_params: Mapping[str, Any],
+ ):
+ try:
+ import cupy as cp
+ from cuvs.neighbors import brute_force, cagra, filters
+
+ device_count = cp.cuda.runtime.getDeviceCount()
+ except Exception as exc:
+ raise CuVSUnavailableError(
+ "cuVS backend requires Python 3.11+, a CUDA-capable NVIDIA GPU, and the "
+ "matching cuvs-cu12 or cuvs-cu13 Python package"
+ ) from exc
+ if device_count < 1:
+ raise CuVSUnavailableError("cuVS backend requires at least one visible CUDA device")
+
+ self.cp = cp
+ self.brute_force = brute_force
+ self.cagra = cagra
+ self.filters = filters
+ self.algorithm = algorithm
+ self.metric = metric
+ self.build_params = dict(build_params)
+ self.search_params = dict(search_params)
+ self.dataset = None
+
+ def memory_info(self) -> Tuple[int, int]:
+ free_bytes, total_bytes = self.cp.cuda.runtime.memGetInfo()
+ return int(free_bytes), int(total_bytes)
+
+ def release_index(self) -> None:
+ self.dataset = None
+ try:
+ self.cp.get_default_memory_pool().free_all_blocks()
+ except Exception:
+ logger.debug("Could not release unused CuPy memory-pool blocks", exc_info=True)
+
+ def is_out_of_memory(self, exc: Exception) -> bool:
+ out_of_memory_type = getattr(self.cp.cuda.memory, "OutOfMemoryError", ())
+ if out_of_memory_type and isinstance(exc, out_of_memory_type):
+ return True
+ message = str(exc).lower()
+ return any(
+ marker in message for marker in ("out of memory", "memory allocation", "bad_alloc")
+ )
+
+ def build(self, dataset: Sequence[Sequence[float]]):
+ self.dataset = self.cp.asarray(dataset, dtype=self.cp.float32)
+ if self.algorithm == "brute_force":
+ return self.brute_force.build(self.dataset, metric=self.metric)
+ params = self.cagra.IndexParams(metric=self.metric, **self.build_params)
+ return self.cagra.build(params, self.dataset)
+
+ def _prefilter(self, mask: Sequence[bool]):
+ return self.filters.from_bitset(self.prepare_filter(mask))
+
+ def prepare_filter(self, mask: Sequence[bool]):
+ """Pack a host mask once and retain its device allocation for reuse."""
+
+ word_count = (len(mask) + 31) // 32
+ words = [0] * word_count
+ for index, included in enumerate(mask):
+ if included:
+ words[index // 32] |= 1 << (index % 32)
+ return self.cp.asarray(words, dtype=self.cp.uint32)
+
+ def prepare_filter_words(self, words: Sequence[int]):
+ """Copy an already packed native filter bitmap to the device."""
+
+ return self.cp.asarray(words, dtype=self.cp.uint32)
+
+ def search(
+ self,
+ index: Any,
+ query: Sequence[float],
+ limit: int,
+ mask: Optional[Any],
+ ) -> Tuple[List[int], List[float]]:
+ queries = self.cp.asarray([query], dtype=self.cp.float32)
+ if mask is None:
+ prefilter = None
+ elif isinstance(mask, self.cp.ndarray) and mask.dtype == self.cp.uint32:
+ prefilter = self.filters.from_bitset(mask)
+ else:
+ prefilter = self._prefilter(mask)
+ if self.algorithm == "brute_force":
+ distances, neighbors = self.brute_force.search(
+ index, queries, limit, prefilter=prefilter
+ )
+ else:
+ search_params = dict(self.search_params)
+ configured_itopk = int(search_params.get("itopk_size", 64))
+ minimum_itopk = ((limit + 31) // 32) * 32
+ search_params["itopk_size"] = max(configured_itopk, minimum_itopk)
+ params = self.cagra.SearchParams(**search_params)
+ distances, neighbors = self.cagra.search(
+ params, index, queries, limit, filter=prefilter
+ )
+ host_neighbors = self.cp.asnumpy(neighbors)[0].tolist()
+ host_distances = self.cp.asnumpy(distances)[0].tolist()
+ return [int(item) for item in host_neighbors], [float(item) for item in host_distances]
+
+ def close(self) -> None:
+ self.release_index()
+
+
+@dataclass(frozen=True)
+class _Record:
+ vector: Tuple[float, ...]
+ fields: Mapping[str, Any]
+
+
+@dataclass(frozen=True)
+class _CachedFilter:
+ prepared: Any
+ eligible_count: int
+ route_native: bool = False
+ native_threshold: int = 0
+
+
+@dataclass(frozen=True)
+class _ResolvedNativeFilter:
+ bitset_words: Tuple[int, ...]
+ eligible_count: int
+ route_native: bool
+ native_threshold: int
+
+
+class CuVSDenseIndex:
+ """Mutable OpenViking label space backed by a lazily rebuilt cuVS index."""
+
+ _SUPPORTED_ALGORITHMS = {"brute_force", "cagra"}
+
+ def __init__(
+ self,
+ *,
+ dimension: int,
+ distance: str,
+ normalize_vectors: bool,
+ field_types: Mapping[str, str],
+ config: Mapping[str, Any],
+ runtime: Optional[Any] = None,
+ auto_memory: bool = False,
+ ):
+ self.dimension = int(dimension)
+ self.distance = distance.lower()
+ self.normalize_vectors = bool(normalize_vectors)
+ self.field_types = dict(field_types)
+ self.auto_memory = bool(auto_memory)
+ self.algorithm = str(config.get("algorithm", "brute_force")).lower()
+ if self.algorithm not in self._SUPPORTED_ALGORITHMS:
+ raise ValueError(
+ f"Unsupported cuVS algorithm {self.algorithm!r}; "
+ f"choose one of {sorted(self._SUPPORTED_ALGORITHMS)}"
+ )
+ if self.distance not in {"ip", "l2"}:
+ raise ValueError(f"Unsupported OpenViking distance for cuVS: {self.distance!r}")
+
+ self.fallback_to_native = bool(config.get("fallback_to_native", True))
+ self.filter_cache_size = int(config.get("filter_cache_size", 16))
+ if self.filter_cache_size < 0:
+ raise ValueError("cuVS filter_cache_size cannot be negative")
+ self.auto_memory_reserve_bytes = (
+ int(config.get("auto_memory_reserve_mb", 1024)) * 1024 * 1024
+ )
+ if self.auto_memory_reserve_bytes < 0:
+ raise ValueError("cuVS auto memory reserve cannot be negative")
+ self.auto_memory_safety_factor = float(config.get("auto_memory_safety_factor", 2.0))
+ if self.auto_memory_safety_factor < 1.0:
+ raise ValueError("cuVS auto memory safety factor must be at least 1.0")
+ self.auto_filter_native_threshold = int(config.get("auto_filter_native_threshold", 2000))
+ if self.auto_filter_native_threshold < 0:
+ raise ValueError("cuVS auto filter native threshold cannot be negative")
+ self.auto_path_filter_native_threshold = int(
+ config.get("auto_path_filter_native_threshold", 200)
+ )
+ if self.auto_path_filter_native_threshold < 0:
+ raise ValueError("cuVS auto path filter native threshold cannot be negative")
+ self._metric = "inner_product" if self.distance == "ip" else "sqeuclidean"
+ build_params = dict(config.get("build_params", {}))
+ search_params = dict(config.get("search_params", {}))
+ self._build_params = build_params
+ if "metric" in build_params:
+ raise ValueError(
+ "Set the cuVS metric through storage.vectordb.distance_metric, "
+ "not cuvs.build_params.metric"
+ )
+ if self.algorithm == "brute_force" and (build_params or search_params):
+ raise ValueError("cuVS build_params/search_params are only valid for CAGRA")
+ self._runtime = runtime or _CuVSRuntime(
+ self.algorithm,
+ self._metric,
+ build_params,
+ search_params,
+ )
+ self._records: Dict[int, _Record] = {}
+ self._labels: List[int] = []
+ self._index: Any = None
+ self._dirty = True
+ self._filter_cache: OrderedDict[str, _CachedFilter] = OrderedDict()
+ self._lock = threading.RLock()
+ logger.info(
+ "Initialized cuVS dense index: algorithm=%s metric=%s dimension=%d",
+ self.algorithm,
+ self._metric,
+ self.dimension,
+ )
+
+ @property
+ def size(self) -> int:
+ with self._lock:
+ return len(self._records)
+
+ def _prepare_vector(self, vector: Sequence[float]) -> Tuple[float, ...]:
+ if len(vector) != self.dimension:
+ raise ValueError(
+ f"cuVS vector dimension mismatch: expected {self.dimension}, got {len(vector)}"
+ )
+ prepared = _normalize(vector) if self.normalize_vectors else [float(v) for v in vector]
+ return tuple(prepared)
+
+ @staticmethod
+ def _parse_fields(value: str) -> Mapping[str, Any]:
+ if not value:
+ return {}
+ try:
+ parsed = json.loads(value)
+ except (TypeError, json.JSONDecodeError):
+ return {}
+ return parsed if isinstance(parsed, dict) else {}
+
+ def add_candidates(self, candidates: Iterable[CandidateData]) -> None:
+ with self._lock:
+ for candidate in candidates:
+ if not candidate.vector:
+ continue
+ self._records[int(candidate.label)] = _Record(
+ vector=self._prepare_vector(candidate.vector),
+ fields=self._parse_fields(candidate.fields),
+ )
+ self._invalidate()
+
+ def upsert(self, records: Iterable[DeltaRecord]) -> None:
+ with self._lock:
+ changed = False
+ for record in records:
+ if not record.vector:
+ continue
+ self._records[int(record.label)] = _Record(
+ vector=self._prepare_vector(record.vector),
+ fields=self._parse_fields(record.fields),
+ )
+ changed = True
+ if changed:
+ self._invalidate()
+
+ def delete(self, records: Iterable[DeltaRecord]) -> None:
+ with self._lock:
+ changed = False
+ for record in records:
+ if self._records.pop(int(record.label), None) is not None:
+ changed = True
+ if changed:
+ self._invalidate()
+
+ def _invalidate(self) -> None:
+ self._dirty = True
+ self._filter_cache.clear()
+
+ @staticmethod
+ def _filter_cache_key(filters: Mapping[str, Any]) -> Optional[str]:
+ try:
+ return json.dumps(filters, sort_keys=True, separators=(",", ":"))
+ except (TypeError, ValueError):
+ return None
+
+ def _get_cached_filter(self, cache_key: Optional[str]) -> Optional[_CachedFilter]:
+ if cache_key is None:
+ return None
+ cached = self._filter_cache.pop(cache_key, None)
+ if cached is not None:
+ self._filter_cache[cache_key] = cached
+ return cached
+
+ def _cache_filter(self, cache_key: Optional[str], cached: _CachedFilter) -> None:
+ if cache_key is None or self.filter_cache_size <= 0:
+ return
+ self._filter_cache[cache_key] = cached
+ while len(self._filter_cache) > self.filter_cache_size:
+ self._filter_cache.popitem(last=False)
+
+ def _resolve_native_filter(
+ self,
+ filters: Mapping[str, Any],
+ native_filter_resolver: Callable[[Mapping[str, Any]], Tuple[Sequence[int], int]],
+ ) -> _ResolvedNativeFilter:
+ words, eligible_count = native_filter_resolver(filters)
+ native_threshold = (
+ self.auto_path_filter_native_threshold
+ if _filter_uses_field_type(filters, self.field_types, "path")
+ else self.auto_filter_native_threshold
+ )
+ route_native = (
+ self.auto_memory and native_threshold > 0 and eligible_count <= native_threshold
+ )
+ return _ResolvedNativeFilter(
+ bitset_words=tuple(int(word) for word in words),
+ eligible_count=int(eligible_count),
+ route_native=route_native,
+ native_threshold=native_threshold,
+ )
+
+ def _prepare_filter(
+ self,
+ filters: Mapping[str, Any],
+ native_filter_resolver: Optional[
+ Callable[[Mapping[str, Any]], Tuple[Sequence[int], int]]
+ ] = None,
+ resolved_native_filter: Optional[_ResolvedNativeFilter] = None,
+ ) -> _CachedFilter:
+ cache_key = self._filter_cache_key(filters)
+ cached = self._get_cached_filter(cache_key)
+ if cached is not None:
+ return cached
+
+ if native_filter_resolver is not None:
+ resolved = resolved_native_filter or self._resolve_native_filter(
+ filters, native_filter_resolver
+ )
+ eligible_count = resolved.eligible_count
+ native_threshold = resolved.native_threshold
+ route_native = resolved.route_native
+ if route_native:
+ prepared = None
+ else:
+ prepare_filter_words = getattr(self._runtime, "prepare_filter_words", None)
+ if prepare_filter_words is not None:
+ prepared = prepare_filter_words(resolved.bitset_words)
+ else:
+ prepared = tuple(
+ bool(resolved.bitset_words[row // 32] & (1 << (row % 32)))
+ for row in range(len(self._labels))
+ )
+ else:
+ mask = [
+ matches_filter(self._records[label].fields, filters, self.field_types)
+ for label in self._labels
+ ]
+ prepare_filter = getattr(self._runtime, "prepare_filter", None)
+ prepared = prepare_filter(mask) if prepare_filter is not None else tuple(mask)
+ eligible_count = sum(mask)
+ route_native = False
+ native_threshold = 0
+ cached = _CachedFilter(
+ prepared=prepared,
+ eligible_count=eligible_count,
+ route_native=route_native,
+ native_threshold=native_threshold,
+ )
+ self._cache_filter(cache_key, cached)
+ return cached
+
+ def _rebuild_if_needed(
+ self,
+ native_filter_layout_registrar: Optional[Callable[[Sequence[int]], None]] = None,
+ *,
+ filter_layout_is_current: bool = False,
+ ) -> None:
+ if not self._dirty:
+ return
+ self._labels = list(self._records)
+ if not self._labels:
+ self._index = None
+ self._dirty = False
+ return
+ if self.auto_memory:
+ self._index = None
+ release_index = getattr(self._runtime, "release_index", None)
+ if release_index is not None:
+ release_index()
+ estimate = estimate_cuvs_memory(
+ vector_count=len(self._labels),
+ dimension=self.dimension,
+ algorithm=self.algorithm,
+ build_params=self._build_params,
+ filter_cache_size=self.filter_cache_size,
+ safety_factor=self.auto_memory_safety_factor,
+ )
+ try:
+ free_bytes, total_bytes = self._runtime.memory_info()
+ except Exception as exc:
+ raise CuVSMemoryBudgetError(
+ "cuVS auto mode could not read free GPU memory"
+ ) from exc
+ usable_bytes = max(0, free_bytes - self.auto_memory_reserve_bytes)
+ if estimate.estimated_peak_bytes > usable_bytes:
+ raise CuVSMemoryBudgetError(
+ "cuVS auto mode kept native search because the estimated GPU peak "
+ f"({estimate.estimated_peak_bytes} bytes) exceeds the usable free "
+ f"memory ({usable_bytes} of {total_bytes} bytes after reserve)"
+ )
+ dataset = [self._records[label].vector for label in self._labels]
+ self._index = None
+ try:
+ self._index = self._runtime.build(dataset)
+ except Exception as exc:
+ is_out_of_memory = getattr(self._runtime, "is_out_of_memory", None)
+ if self.auto_memory and is_out_of_memory is not None and is_out_of_memory(exc):
+ release_index = getattr(self._runtime, "release_index", None)
+ if release_index is not None:
+ release_index()
+ raise CuVSMemoryBudgetError(
+ "cuVS auto mode fell back to native search after a GPU allocation failure"
+ ) from exc
+ raise
+ if native_filter_layout_registrar is not None and not filter_layout_is_current:
+ native_filter_layout_registrar(self._labels)
+ self._dirty = False
+ logger.info("Built cuVS %s index with %d vectors", self.algorithm, len(self._labels))
+
+ def search(
+ self,
+ query_vector: Sequence[float],
+ limit: int,
+ filters: Optional[Mapping[str, Any]],
+ native_filter_resolver: Optional[
+ Callable[[Mapping[str, Any]], Tuple[Sequence[int], int]]
+ ] = None,
+ native_filter_layout_registrar: Optional[Callable[[Sequence[int]], None]] = None,
+ ) -> Tuple[List[int], List[float]]:
+ if limit <= 0:
+ return [], []
+ query = self._prepare_vector(query_vector)
+ with self._lock:
+ cached_filter: Optional[_CachedFilter] = None
+ resolved_native_filter: Optional[_ResolvedNativeFilter] = None
+ filter_layout_is_current = False
+
+ # Auto mode decides whether a selective filter should remain native
+ # before paying GPU admission or rebuild costs. A dirty native
+ # layout is refreshed against the pending cuVS row order only; the
+ # live GPU row mapping is not changed until a build actually runs.
+ if filters and self.auto_memory and native_filter_resolver is not None:
+ cache_key = self._filter_cache_key(filters)
+ cached_filter = self._get_cached_filter(cache_key)
+ if cached_filter is None:
+ if self._dirty and native_filter_layout_registrar is not None:
+ native_filter_layout_registrar(list(self._records))
+ filter_layout_is_current = True
+ resolved_native_filter = self._resolve_native_filter(
+ filters, native_filter_resolver
+ )
+ if (
+ resolved_native_filter.route_native
+ or resolved_native_filter.eligible_count == 0
+ ):
+ cached_filter = _CachedFilter(
+ prepared=None,
+ eligible_count=resolved_native_filter.eligible_count,
+ route_native=resolved_native_filter.route_native,
+ native_threshold=resolved_native_filter.native_threshold,
+ )
+ self._cache_filter(cache_key, cached_filter)
+
+ if cached_filter is not None:
+ if cached_filter.eligible_count == 0:
+ return [], []
+ if cached_filter.route_native:
+ raise CuVSNativeRouteError(
+ "cuVS auto mode routed a selective filter to native search "
+ f"({cached_filter.eligible_count} candidates <= "
+ f"{cached_filter.native_threshold})"
+ )
+
+ self._rebuild_if_needed(
+ native_filter_layout_registrar,
+ filter_layout_is_current=filter_layout_is_current,
+ )
+ if self._index is None:
+ return [], []
+
+ mask: Optional[Any] = None
+ if filters:
+ cached_filter = cached_filter or self._prepare_filter(
+ filters,
+ native_filter_resolver,
+ resolved_native_filter,
+ )
+ mask = cached_filter.prepared
+ eligible_count = cached_filter.eligible_count
+ if eligible_count == 0:
+ return [], []
+ if cached_filter.route_native:
+ raise CuVSNativeRouteError(
+ "cuVS auto mode routed a selective filter to native search "
+ f"({eligible_count} candidates <= "
+ f"{cached_filter.native_threshold})"
+ )
+ result_limit = min(limit, eligible_count)
+ else:
+ result_limit = min(limit, len(self._labels))
+
+ offsets, distances = self._runtime.search(self._index, query, result_limit, mask)
+ labels: List[int] = []
+ scores: List[float] = []
+ for offset, distance in zip(offsets, distances, strict=True):
+ if offset < 0 or offset >= len(self._labels):
+ continue
+ labels.append(self._labels[offset])
+ scores.append(1.0 - distance if self.distance == "l2" else distance)
+ return labels, scores
+
+ def close(self) -> None:
+ with self._lock:
+ self._index = None
+ self._labels = []
+ self._filter_cache.clear()
+ self._runtime.close()
diff --git a/openviking/storage/vectordb/index/local_index.py b/openviking/storage/vectordb/index/local_index.py
index a4493db23..7804f136f 100644
--- a/openviking/storage/vectordb/index/local_index.py
+++ b/openviking/storage/vectordb/index/local_index.py
@@ -4,11 +4,19 @@ import json
import math
import os
import shutil
+import threading
import time
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple, Union
import openviking.storage.vectordb.engine as engine
+from openviking.storage.vectordb.index.cuvs_index import (
+ CuVSDenseIndex,
+ CuVSMemoryBudgetError,
+ CuVSNativeRouteError,
+ CuVSUnavailableError,
+ UnsupportedCuVSFilterError,
+)
from openviking.storage.vectordb.index.index import IIndex
from openviking.storage.vectordb.store.data import CandidateData, DeltaRecord
from openviking.storage.vectordb.utils.constants import IndexFileMarkers
@@ -178,6 +186,23 @@ class IndexEngineProxy:
state_result = self.index_engine.get_state()
return state_result.data_count
+ def set_filter_layout(self, ordered_labels: List[int]) -> None:
+ """Register the dense-index row order with the native scalar engine."""
+
+ if not self.index_engine:
+ raise RuntimeError("Index engine not initialized")
+ result = self.index_engine.set_filter_layout(ordered_labels)
+ if result != 0:
+ raise RuntimeError("Failed to register native scalar filter layout")
+
+ def evaluate_filter(self, filters: Dict[str, Any]) -> Tuple[List[int], int]:
+ """Evaluate a native scalar filter in the registered dense-index row order."""
+
+ if not self.index_engine:
+ raise RuntimeError("Index engine not initialized")
+ result = self.index_engine.evaluate_filter(json.dumps(filters))
+ return result.bitset_words, result.eligible_count
+
def drop(self):
"""Release the index engine resources.
@@ -204,7 +229,13 @@ class LocalIndex(IIndex):
meta: Index metadata including configuration and schema
"""
- def __init__(self, index_path_or_json: str, meta: Any):
+ def __init__(
+ self,
+ index_path_or_json: str,
+ meta: Any,
+ dense_search_config: Optional[Dict[str, Any]] = None,
+ initial_candidates: Optional[List[CandidateData]] = None,
+ ):
"""Initialize a local index instance.
Args:
@@ -218,6 +249,33 @@ class LocalIndex(IIndex):
)
self.meta = meta
self.field_type_converter = DataProcessor(self.meta.collection_meta.fields_dict)
+ self.dense_search: Optional[CuVSDenseIndex] = None
+ self._dense_search_lock = threading.RLock()
+ self._auto_cuvs = False
+ dense_search_config = dict(dense_search_config or {})
+ dense_search_backend = dense_search_config.get("backend")
+ if dense_search_backend in {"cuvs", "auto_cuvs"}:
+ self._auto_cuvs = dense_search_backend == "auto_cuvs"
+ vector_meta = meta.inner_meta.get("VectorIndex", {})
+ field_types = {
+ name: DataProcessor.normalize_field_type(field_meta.get("FieldType", ""))
+ for name, field_meta in meta.collection_meta.fields_dict.items()
+ }
+ try:
+ self.dense_search = CuVSDenseIndex(
+ dimension=vector_meta.get("Dimension", meta.collection_meta.vector_dim),
+ distance=vector_meta.get("Distance", "ip"),
+ normalize_vectors=vector_meta.get("NormalizeVector", False),
+ field_types=field_types,
+ config=dense_search_config,
+ auto_memory=self._auto_cuvs,
+ )
+ self.dense_search.add_candidates(initial_candidates or [])
+ except CuVSUnavailableError:
+ if not self._auto_cuvs:
+ raise
+ logger.info("cuVS auto mode unavailable; keeping native dense search")
+ self.dense_search = None
def update(
self,
@@ -237,11 +295,21 @@ class LocalIndex(IIndex):
return self.meta.get_meta_data()
def upsert_data(self, delta_list: List[DeltaRecord]):
- if self.engine_proxy:
+ if self.dense_search:
+ with self._dense_search_lock:
+ if self.engine_proxy:
+ self.engine_proxy.upsert_data(self._convert_delta_list_for_index(delta_list))
+ self.dense_search.upsert(delta_list)
+ elif self.engine_proxy:
self.engine_proxy.upsert_data(self._convert_delta_list_for_index(delta_list))
def delete_data(self, delta_list: List[DeltaRecord]):
- if self.engine_proxy:
+ if self.dense_search:
+ with self._dense_search_lock:
+ if self.engine_proxy:
+ self.engine_proxy.delete_data(self._convert_delta_list_for_index(delta_list))
+ self.dense_search.delete(delta_list)
+ elif self.engine_proxy:
self.engine_proxy.delete_data(self._convert_delta_list_for_index(delta_list))
def search(
@@ -263,6 +331,33 @@ class LocalIndex(IIndex):
if self.field_type_converter and filters is not None:
filters = self.field_type_converter.convert_filter_for_index(filters)
+
+ if self.dense_search and query_vector:
+ with self._dense_search_lock:
+ if not sparse_raw_terms and not sparse_values:
+ try:
+ return self.dense_search.search(
+ query_vector,
+ limit,
+ filters,
+ self.engine_proxy.evaluate_filter,
+ self.engine_proxy.set_filter_layout,
+ )
+ except CuVSMemoryBudgetError as exc:
+ if not self._auto_cuvs:
+ raise
+ logger.debug("cuVS auto mode kept native dense search: %s", exc)
+ except CuVSNativeRouteError as exc:
+ logger.debug("cuVS auto mode selected native dense search: %s", exc)
+ except UnsupportedCuVSFilterError as exc:
+ if not self.dense_search.fallback_to_native:
+ raise
+ logger.debug("Falling back to native dense search: %s", exc)
+ elif not self.dense_search.fallback_to_native:
+ raise ValueError(
+ "cuVS dense search does not support OpenViking sparse/hybrid queries"
+ )
+
return self.engine_proxy.search(
query_vector, limit, filters, sparse_raw_terms, sparse_values
)
@@ -310,9 +405,15 @@ class LocalIndex(IIndex):
return agg_data
def close(self):
+ if self.dense_search:
+ self.dense_search.close()
+ self.dense_search = None
return None
def drop(self):
+ if self.dense_search:
+ self.dense_search.close()
+ self.dense_search = None
if self.engine_proxy:
self.engine_proxy.drop()
self.meta = None
@@ -402,7 +503,13 @@ class VolatileIndex(LocalIndex):
meta: Index metadata and configuration
"""
- def __init__(self, name: str, meta: Any, cands_list: Optional[List[CandidateData]] = None):
+ def __init__(
+ self,
+ name: str,
+ meta: Any,
+ cands_list: Optional[List[CandidateData]] = None,
+ dense_search_config: Optional[Dict[str, Any]] = None,
+ ):
"""Initialize a volatile (in-memory) index.
Creates a new in-memory index and populates it with the initial dataset.
@@ -427,7 +534,12 @@ class VolatileIndex(LocalIndex):
index_config_dict["UpdateTimeStamp"] = version_int
index_config_json = json.dumps(index_config_dict)
- super().__init__(index_config_json, meta)
+ super().__init__(
+ index_config_json,
+ meta,
+ dense_search_config=dense_search_config,
+ initial_candidates=cands_list,
+ )
self.engine_proxy.add_data(self._convert_candidate_list_for_index(cands_list))
def need_rebuild(self) -> bool:
@@ -493,6 +605,7 @@ class PersistentIndex(LocalIndex):
cands_list: Optional[List[CandidateData]] = None,
force_rebuild: bool = False,
initial_timestamp: Optional[int] = None,
+ dense_search_config: Optional[Dict[str, Any]] = None,
):
"""Initialize a persistent index with versioning support.
@@ -537,7 +650,12 @@ class PersistentIndex(LocalIndex):
self.now_version = str(newest_version)
index_path = str(safe_join(self.version_dir, self.now_version))
- super().__init__(index_path, meta)
+ super().__init__(
+ index_path,
+ meta,
+ dense_search_config=dense_search_config,
+ initial_candidates=cands_list,
+ )
# Remove scheduling logic, unified scheduling by collection layer
def _create_new_index(
diff --git a/openviking/storage/vectordb_adapters/__init__.py b/openviking/storage/vectordb_adapters/__init__.py
index 1c75683f4..bb33a3a36 100644
--- a/openviking/storage/vectordb_adapters/__init__.py
+++ b/openviking/storage/vectordb_adapters/__init__.py
@@ -5,7 +5,7 @@
from .base import CollectionAdapter
from .factory import create_collection_adapter
from .http_adapter import HttpCollectionAdapter
-from .local_adapter import LocalCollectionAdapter
+from .local_adapter import CuVSCollectionAdapter, LocalCollectionAdapter
from .opengauss_adapter import OpenGaussCollectionAdapter
from .qdrant_adapter import QdrantCollectionAdapter
from .vikingdb_private_adapter import VikingDBPrivateCollectionAdapter
@@ -14,6 +14,7 @@ from .volcengine_adapter import VolcengineCollectionAdapter
__all__ = [
"CollectionAdapter",
"LocalCollectionAdapter",
+ "CuVSCollectionAdapter",
"HttpCollectionAdapter",
"OpenGaussCollectionAdapter",
"QdrantCollectionAdapter",
diff --git a/openviking/storage/vectordb_adapters/factory.py b/openviking/storage/vectordb_adapters/factory.py
index f35d1a78f..24e570e6c 100644
--- a/openviking/storage/vectordb_adapters/factory.py
+++ b/openviking/storage/vectordb_adapters/factory.py
@@ -8,7 +8,7 @@ import importlib
from .base import CollectionAdapter
from .http_adapter import HttpCollectionAdapter
-from .local_adapter import LocalCollectionAdapter
+from .local_adapter import CuVSCollectionAdapter, LocalCollectionAdapter
from .opengauss_adapter import OpenGaussCollectionAdapter
from .qdrant_adapter import QdrantCollectionAdapter
from .vikingdb_private_adapter import VikingDBPrivateCollectionAdapter
@@ -16,6 +16,7 @@ from .volcengine_adapter import VolcengineCollectionAdapter
_ADAPTER_REGISTRY: dict[str, type[CollectionAdapter]] = {
"local": LocalCollectionAdapter,
+ "cuvs": CuVSCollectionAdapter,
"http": HttpCollectionAdapter,
"opengauss": OpenGaussCollectionAdapter,
"qdrant": QdrantCollectionAdapter,
diff --git a/openviking/storage/vectordb_adapters/local_adapter.py b/openviking/storage/vectordb_adapters/local_adapter.py
index 4bef6eb95..3fb069603 100644
--- a/openviking/storage/vectordb_adapters/local_adapter.py
+++ b/openviking/storage/vectordb_adapters/local_adapter.py
@@ -6,7 +6,7 @@ from __future__ import annotations
import os
from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
from openviking.storage.vectordb.collection.collection import Collection
from openviking.storage.vectordb.collection.local_collection import get_or_create_local_collection
@@ -19,20 +19,37 @@ class LocalCollectionAdapter(CollectionAdapter):
DEFAULT_LOCAL_PROJECT_NAME = "vectordb"
- def __init__(self, collection_name: str, project_path: str, index_name: str):
+ def __init__(
+ self,
+ collection_name: str,
+ project_path: str,
+ index_name: str,
+ collection_config: Optional[Dict[str, Any]] = None,
+ ):
super().__init__(collection_name=collection_name, index_name=index_name)
self.mode = "local"
self._project_path = project_path
+ self._collection_config = dict(collection_config or {})
@classmethod
def from_config(cls, config: Any):
project_path = (
str(Path(config.path) / cls.DEFAULT_LOCAL_PROJECT_NAME) if config.path else ""
)
+ collection_config: Dict[str, Any] = {}
+ cuvs_config = getattr(config, "cuvs", None)
+ if cuvs_config is not None and getattr(cuvs_config, "auto_enable", False):
+ collection_config = {
+ "dense_search": {
+ "backend": "auto_cuvs",
+ **cuvs_config.model_dump(),
+ }
+ }
return cls(
collection_name=config.name or "context",
project_path=project_path,
index_name=config.index_name or "default",
+ collection_config=collection_config,
)
def _collection_path(self) -> str:
@@ -48,15 +65,58 @@ class LocalCollectionAdapter(CollectionAdapter):
return
meta_path = os.path.join(collection_path, "collection_meta.json")
if os.path.exists(meta_path):
- self._collection = get_or_create_local_collection(path=collection_path)
+ self._collection = get_or_create_local_collection(
+ path=collection_path, config=self._collection_config
+ )
def _create_backend_collection(self, meta: Dict[str, Any]) -> Collection:
collection_path = self._collection_path()
if collection_path:
os.makedirs(collection_path, exist_ok=True)
- return get_or_create_local_collection(meta_data=meta, path=collection_path)
+ return get_or_create_local_collection(
+ meta_data=meta,
+ path=collection_path,
+ config=self._collection_config,
+ )
def update_data(self, data_list: List[Dict[str, Any]]):
collection = self.get_collection()
result = collection.update_data(data_list)
return list(result.ids or [])
+
+
+class CuVSCollectionAdapter(LocalCollectionAdapter):
+ """Embedded OpenViking storage with dense search executed by NVIDIA cuVS."""
+
+ def __init__(
+ self,
+ collection_name: str,
+ project_path: str,
+ index_name: str,
+ cuvs_config: Dict[str, Any],
+ ):
+ super().__init__(
+ collection_name=collection_name,
+ project_path=project_path,
+ index_name=index_name,
+ collection_config={
+ "dense_search": {
+ "backend": "cuvs",
+ **cuvs_config,
+ }
+ },
+ )
+ self.mode = "cuvs"
+
+ @classmethod
+ def from_config(cls, config: Any):
+ project_path = (
+ str(Path(config.path) / cls.DEFAULT_LOCAL_PROJECT_NAME) if config.path else ""
+ )
+ cuvs_config = config.cuvs.model_dump() if config.cuvs is not None else {}
+ return cls(
+ collection_name=config.name or "context",
+ project_path=project_path,
+ index_name=config.index_name or "default",
+ cuvs_config=cuvs_config,
+ )
diff --git a/openviking_cli/utils/config/vectordb_config.py b/openviking_cli/utils/config/vectordb_config.py
index 87773553c..36d97e441 100644
--- a/openviking_cli/utils/config/vectordb_config.py
+++ b/openviking_cli/utils/config/vectordb_config.py
@@ -1,6 +1,6 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Literal, Optional
from pydantic import BaseModel, Field, model_validator
@@ -76,6 +76,81 @@ class QdrantConfig(BaseModel):
model_config = {"extra": "forbid"}
+class CuVSConfig(BaseModel):
+ """Configuration for GPU dense-vector search through NVIDIA cuVS."""
+
+ algorithm: Literal["brute_force", "cagra"] = Field(
+ default="brute_force",
+ description=(
+ "cuVS index algorithm. Start with brute_force for functional validation; "
+ "use cagra for approximate search at larger scale."
+ ),
+ )
+ build_params: Dict[str, Any] = Field(
+ default_factory=dict,
+ description="Additional keyword arguments passed to cuVS CAGRA IndexParams.",
+ )
+ search_params: Dict[str, Any] = Field(
+ default_factory=dict,
+ description="Additional keyword arguments passed to cuVS CAGRA SearchParams.",
+ )
+ fallback_to_native: bool = Field(
+ default=True,
+ description=(
+ "Use OpenViking's native local index for sparse/hybrid search or other "
+ "operations outside cuVS dense top-k."
+ ),
+ )
+ auto_enable: bool = Field(
+ default=False,
+ description=(
+ "When the VectorDB backend is 'local', automatically use cuVS dense search "
+ "only when a visible GPU has enough free memory. The default is disabled."
+ ),
+ )
+ auto_memory_reserve_mb: int = Field(
+ default=1024,
+ ge=0,
+ description=("Free GPU memory kept outside the cuVS auto-admission budget, in MiB."),
+ )
+ auto_memory_safety_factor: float = Field(
+ default=2.0,
+ ge=1.0,
+ description=(
+ "Multiplier applied to the estimated cuVS vector, graph, build, and filter "
+ "memory before auto-enabling GPU search."
+ ),
+ )
+ auto_filter_native_threshold: int = Field(
+ default=2000,
+ ge=0,
+ description=(
+ "In cuVS auto mode, route filtered queries with at most this many "
+ "eligible vectors to the native index. Set to zero to disable "
+ "latency-aware filter routing."
+ ),
+ )
+ auto_path_filter_native_threshold: int = Field(
+ default=200,
+ ge=0,
+ description=(
+ "In cuVS auto mode, use this lower native-routing threshold for path "
+ "filters, whose native Trie/bitmap construction cost can dominate wider "
+ "subtree queries. Set to zero to keep all path filters on cuVS."
+ ),
+ )
+ filter_cache_size: int = Field(
+ default=16,
+ ge=0,
+ description=(
+ "Maximum number of repeated scalar-filter bitsets retained on the GPU. "
+ "Set to zero to disable caching."
+ ),
+ )
+
+ model_config = {"extra": "forbid"}
+
+
_OPENGAUSS_MODES = {"standalone", "distributed"}
@@ -137,7 +212,7 @@ class VectorDBBackendConfig(BaseModel):
backend: str = Field(
default="local",
description=(
- "VectorDB backend type: 'local', 'http', "
+ "VectorDB backend type: 'local', 'cuvs', 'http', "
"'volcengine' (AK/SK signed or API key data-plane only), "
"'vikingdb' (private deployment), 'qdrant', or 'opengauss'"
),
@@ -198,6 +273,11 @@ class VectorDBBackendConfig(BaseModel):
description="Qdrant configuration for 'qdrant' type",
)
+ cuvs: Optional[CuVSConfig] = Field(
+ default_factory=CuVSConfig,
+ description="NVIDIA cuVS dense-vector search configuration for the 'cuvs' backend",
+ )
+
opengauss: Optional[OpenGaussConfig] = Field(
default_factory=OpenGaussConfig,
description="openGauss configuration for 'opengauss' type",
@@ -213,7 +293,15 @@ class VectorDBBackendConfig(BaseModel):
@model_validator(mode="after")
def validate_config(self):
"""Validate configuration completeness and consistency"""
- standard_backends = ["local", "http", "volcengine", "vikingdb", "qdrant", "opengauss"]
+ standard_backends = [
+ "local",
+ "cuvs",
+ "http",
+ "volcengine",
+ "vikingdb",
+ "qdrant",
+ "opengauss",
+ ]
# Allow custom backend classes (containing dot) without standard validation
if "." in self.backend:
@@ -226,7 +314,7 @@ class VectorDBBackendConfig(BaseModel):
"or a valid Python class path."
)
- if self.backend == "local":
+ if self.backend in {"local", "cuvs"}:
pass
elif self.backend == "http":
diff --git a/src/abi3_engine_backend.cpp b/src/abi3_engine_backend.cpp
index 0d20df171..9dd76e635 100644
--- a/src/abi3_engine_backend.cpp
+++ b/src/abi3_engine_backend.cpp
@@ -241,6 +241,31 @@ bool py_to_int64_vector(PyObject* obj, std::vector<int64_t>* out) {
return true;
}
+bool py_to_uint64_vector(PyObject* obj, std::vector<uint64_t>* out) {
+ const Py_ssize_t size = PySequence_Size(obj);
+ if (size < 0) {
+ raise_type_error("Expected a sequence of unsigned integers");
+ return false;
+ }
+
+ out->clear();
+ out->reserve(static_cast<size_t>(size));
+ for (Py_ssize_t i = 0; i < size; ++i) {
+ PyObject* item = PySequence_GetItem(obj, i);
+ if (item == nullptr) {
+ return false;
+ }
+ uint64_t value = 0;
+ const bool ok = py_to_uint64(item, &value);
+ Py_DECREF(item);
+ if (!ok) {
+ return false;
+ }
+ out->push_back(value);
+ }
+ return true;
+}
+
PyObject* float_vector_to_py(const std::vector<float>& values) {
PyObject* list = PyList_New(static_cast<Py_ssize_t>(values.size()));
if (list == nullptr) {
@@ -292,6 +317,22 @@ PyObject* uint64_vector_to_py(const std::vector<uint64_t>& values) {
return list;
}
+PyObject* uint32_vector_to_py(const std::vector<uint32_t>& values) {
+ PyObject* list = PyList_New(static_cast<Py_ssize_t>(values.size()));
+ if (list == nullptr) {
+ return nullptr;
+ }
+ for (Py_ssize_t i = 0; i < static_cast<Py_ssize_t>(values.size()); ++i) {
+ PyObject* item = PyLong_FromUnsignedLong(values[static_cast<size_t>(i)]);
+ if (item == nullptr) {
+ Py_DECREF(list);
+ return nullptr;
+ }
+ PyList_SetItem(list, i, item);
+ }
+ return list;
+}
+
PyObject* value_to_py(const vdb::Value& value, vdb::FieldType field_type) {
switch (field_type) {
case vdb::FieldType::INT64:
@@ -1109,6 +1150,29 @@ PyObject* build_search_result(const vdb::SearchResult& result) {
return payload;
}
+PyObject* build_filter_result(const vdb::FilterResult& result) {
+ PyObject* payload = PyDict_New();
+ if (payload == nullptr) {
+ return nullptr;
+ }
+
+ PyObject* eligible_count =
+ PyLong_FromUnsignedLongLong(result.eligible_count);
+ PyObject* bitset_words = uint32_vector_to_py(result.bitset_words);
+ if (eligible_count == nullptr || bitset_words == nullptr) {
+ Py_XDECREF(eligible_count);
+ Py_XDECREF(bitset_words);
+ Py_DECREF(payload);
+ return nullptr;
+ }
+
+ PyDict_SetItemString(payload, "eligible_count", eligible_count);
+ PyDict_SetItemString(payload, "bitset_words", bitset_words);
+ Py_DECREF(eligible_count);
+ Py_DECREF(bitset_words);
+ return payload;
+}
+
PyObject* build_state_result(const vdb::StateResult& result) {
PyObject* payload = PyDict_New();
if (payload == nullptr) {
@@ -1250,6 +1314,55 @@ PyObject* py_index_engine_search(PyObject*, PyObject* args) {
}
}
+PyObject* py_index_engine_set_filter_layout(PyObject*, PyObject* args) {
+ PyObject* capsule = nullptr;
+ PyObject* labels_obj = nullptr;
+ if (!PyArg_ParseTuple(args, "OO", &capsule, &labels_obj)) {
+ return nullptr;
+ }
+
+ auto* engine = capsule_to_ptr<vdb::IndexEngine>(capsule, kIndexCapsuleName);
+ if (engine == nullptr) {
+ return nullptr;
+ }
+
+ std::vector<uint64_t> ordered_labels;
+ if (!py_to_uint64_vector(labels_obj, &ordered_labels)) {
+ return nullptr;
+ }
+
+ try {
+ const int result = call_without_gil(
+ [&]() { return engine->set_filter_layout(ordered_labels); });
+ return PyLong_FromLong(result);
+ } catch (const std::exception& exc) {
+ raise_runtime_error(exc.what());
+ return nullptr;
+ }
+}
+
+PyObject* py_index_engine_evaluate_filter(PyObject*, PyObject* args) {
+ PyObject* capsule = nullptr;
+ const char* dsl = nullptr;
+ if (!PyArg_ParseTuple(args, "Os", &capsule, &dsl)) {
+ return nullptr;
+ }
+
+ auto* engine = capsule_to_ptr<vdb::IndexEngine>(capsule, kIndexCapsuleName);
+ if (engine == nullptr) {
+ return nullptr;
+ }
+
+ try {
+ const vdb::FilterResult result =
+ call_without_gil([&]() { return engine->evaluate_filter(dsl); });
+ return build_filter_result(result);
+ } catch (const std::exception& exc) {
+ raise_runtime_error(exc.what());
+ return nullptr;
+ }
+}
+
PyObject* py_index_engine_dump(PyObject*, PyObject* args) {
PyObject* capsule = nullptr;
const char* path = nullptr;
@@ -1536,6 +1649,10 @@ PyMethodDef kModuleMethods[] = {
"Delete data from the index engine."},
{"_index_engine_search", py_index_engine_search, METH_VARARGS,
"Search the index engine."},
+ {"_index_engine_set_filter_layout", py_index_engine_set_filter_layout,
+ METH_VARARGS, "Register an external label order for scalar filters."},
+ {"_index_engine_evaluate_filter", py_index_engine_evaluate_filter,
+ METH_VARARGS, "Evaluate a scalar filter in an external label order."},
{"_index_engine_dump", py_index_engine_dump, METH_VARARGS,
"Dump index state to disk."},
{"_index_engine_get_state", py_index_engine_get_state, METH_VARARGS,
diff --git a/src/index/common_structs.h b/src/index/common_structs.h
index 2c0fd5e69..bba5334c4 100644
--- a/src/index/common_structs.h
+++ b/src/index/common_structs.h
@@ -38,6 +38,15 @@ struct SearchResult {
std::string extra_json;
};
+// A filter bitmap projected into an external row order. Bit i in
+// bitset_words corresponds to ordered_labels[i] supplied by the caller.
+// This keeps native logical offsets private while allowing an external dense
+// index (for example, cuVS) to reuse the native scalar-index semantics.
+struct FilterResult {
+ uint64_t eligible_count = 0;
+ std::vector<uint32_t> bitset_words;
+};
+
struct StateResult {
uint64_t update_timestamp = 0;
uint64_t element_count = 0;
diff --git a/src/index/detail/index_manager_impl.cpp b/src/index/detail/index_manager_impl.cpp
index 68bc6385a..4bb991a11 100644
--- a/src/index/detail/index_manager_impl.cpp
+++ b/src/index/detail/index_manager_impl.cpp
@@ -4,6 +4,7 @@
#include <stdexcept>
#include <memory>
#include <chrono>
+#include <limits>
#include <thread>
#include "spdlog/spdlog.h"
#include "common/ann_utils.h"
@@ -203,6 +204,55 @@ int IndexManagerImpl::search(const SearchRequest& req, SearchResult& result) {
return ret;
}
+int IndexManagerImpl::set_filter_layout(
+ const std::vector<uint64_t>& ordered_labels) {
+ std::unique_lock<std::shared_mutex> lock(rw_mutex_);
+ filter_layout_offsets_.clear();
+ filter_layout_offsets_.reserve(ordered_labels.size());
+ for (const uint64_t label : ordered_labels) {
+ const int offset = vector_index_->get_offset_by_label(label);
+ filter_layout_offsets_.push_back(
+ offset >= 0 ? static_cast<uint32_t>(offset)
+ : std::numeric_limits<uint32_t>::max());
+ }
+ return 0;
+}
+
+int IndexManagerImpl::evaluate_filter(const std::string& dsl,
+ FilterResult& result) {
+ SearchContext ctx;
+ if (int ret = parse_dsl_query(dsl, ctx); ret != 0) {
+ SPDLOG_ERROR("IndexManagerImpl::evaluate_filter [{}] parse failed", dsl);
+ return ret;
+ }
+
+ std::shared_lock<std::shared_mutex> lock(rw_mutex_);
+ BitmapPtr bitmap = nullptr;
+ if (ctx.filter_op) {
+ bitmap = calculate_filter_bitmap(ctx, dsl);
+ if (!bitmap) {
+ SPDLOG_DEBUG(
+ "IndexManagerImpl::evaluate_filter calculate_filter_bitmap returned null");
+ return -1;
+ }
+ }
+
+ result.eligible_count = 0;
+ result.bitset_words.assign((filter_layout_offsets_.size() + 31) / 32, 0);
+ for (size_t row = 0; row < filter_layout_offsets_.size(); ++row) {
+ const uint32_t offset = filter_layout_offsets_[row];
+ const bool eligible = offset != std::numeric_limits<uint32_t>::max() &&
+ (!bitmap || bitmap->Isset(offset));
+ if (!eligible) {
+ continue;
+ }
+ result.bitset_words[row / 32] |=
+ static_cast<uint32_t>(1U << (row % 32));
+ ++result.eligible_count;
+ }
+ return 0;
+}
+
BitmapPtr IndexManagerImpl::calculate_filter_bitmap(const SearchContext& ctx,
const std::string& dsl) {
auto bitmap = ctx.filter_op->calc_bitmap(scalar_index_->get_field_sets(),
@@ -313,6 +363,7 @@ int IndexManagerImpl::add_data(const std::vector<AddDataRequest>& data_list) {
parsed_old_fields_list[i]);
}
if (has_update) {
+ filter_layout_offsets_.clear();
auto duration = std::chrono::system_clock::now().time_since_epoch();
manager_meta_->update_timestamp =
std::chrono::duration_cast<std::chrono::nanoseconds>(duration).count();
@@ -355,6 +406,7 @@ int IndexManagerImpl::delete_data(
vector_index_->stream_delete_data(data.label);
}
if (has_update) {
+ filter_layout_offsets_.clear();
auto duration = std::chrono::system_clock::now().time_since_epoch();
manager_meta_->update_timestamp =
std::chrono::duration_cast<std::chrono::nanoseconds>(duration).count();
diff --git a/src/index/detail/index_manager_impl.h b/src/index/detail/index_manager_impl.h
index d7b64019e..b288100c2 100644
--- a/src/index/detail/index_manager_impl.h
+++ b/src/index/detail/index_manager_impl.h
@@ -29,6 +29,12 @@ class IndexManagerImpl : public IndexManager {
int search(const SearchRequest& req, SearchResult& result) override;
+ int set_filter_layout(
+ const std::vector<uint64_t>& ordered_labels) override;
+
+ int evaluate_filter(const std::string& dsl,
+ FilterResult& result) override;
+
int add_data(const std::vector<AddDataRequest>& data_list) override;
int delete_data(const std::vector<DeleteDataRequest>& data_list) override;
@@ -59,6 +65,7 @@ class IndexManagerImpl : public IndexManager {
std::shared_ptr<ManagerMeta> manager_meta_;
std::shared_ptr<ScalarIndex> scalar_index_;
std::shared_ptr<VectorIndexAdapter> vector_index_;
+ std::vector<uint32_t> filter_layout_offsets_;
};
-} // namespace vectordb
\ No newline at end of file
+} // namespace vectordb
diff --git a/src/index/index_engine.cpp b/src/index/index_engine.cpp
index 7a5fd8c2c..a26e190c4 100644
--- a/src/index/index_engine.cpp
+++ b/src/index/index_engine.cpp
@@ -3,6 +3,7 @@
#include "index_engine.h"
#include "index/detail/index_manager_impl.h"
#include "index/detail/fields_dict.h"
+#include <stdexcept>
#include <unistd.h>
namespace vectordb {
@@ -17,6 +18,20 @@ SearchResult IndexEngine::search(const SearchRequest& req) {
return result;
}
+int IndexEngine::set_filter_layout(
+ const std::vector<uint64_t>& ordered_labels) {
+ return impl_->set_filter_layout(ordered_labels);
+}
+
+FilterResult IndexEngine::evaluate_filter(const std::string& dsl) {
+ FilterResult result;
+ const int ret = impl_->evaluate_filter(dsl, result);
+ if (ret != 0) {
+ throw std::runtime_error("Failed to evaluate native scalar filter");
+ }
+ return result;
+}
+
int IndexEngine::add_data(const std::vector<AddDataRequest>& data_list) {
return impl_->add_data(data_list);
}
@@ -35,4 +50,4 @@ StateResult IndexEngine::get_state() {
return state_result;
}
-} // namespace vectordb
\ No newline at end of file
+} // namespace vectordb
diff --git a/src/index/index_engine.h b/src/index/index_engine.h
index 55d130db0..45a654fc6 100644
--- a/src/index/index_engine.h
+++ b/src/index/index_engine.h
@@ -24,6 +24,10 @@ class IndexEngine {
SearchResult search(const SearchRequest& req);
+ int set_filter_layout(const std::vector<uint64_t>& ordered_labels);
+
+ FilterResult evaluate_filter(const std::string& dsl);
+
int64_t dump(const std::string& dir);
StateResult get_state();
@@ -32,4 +36,4 @@ class IndexEngine {
std::shared_ptr<IndexManager> impl_ = nullptr;
};
-} // namespace vectordb
\ No newline at end of file
+} // namespace vectordb
diff --git a/src/index/index_manager.h b/src/index/index_manager.h
index 3da13ad99..20a61cc2b 100644
--- a/src/index/index_manager.h
+++ b/src/index/index_manager.h
@@ -14,6 +14,12 @@ class IndexManager {
virtual int search(const SearchRequest& req, SearchResult& result) = 0;
+ virtual int set_filter_layout(
+ const std::vector<uint64_t>& ordered_labels) = 0;
+
+ virtual int evaluate_filter(const std::string& dsl,
+ FilterResult& result) = 0;
+
virtual int add_data(const std::vector<AddDataRequest>& data_list) = 0;
virtual int delete_data(const std::vector<DeleteDataRequest>& data_list) = 0;
@@ -22,4 +28,4 @@ class IndexManager {
virtual int get_state(StateResult& state_result) = 0;
};
-} // namespace vectordb
\ No newline at end of file
+} // namespace vectordb
diff --git a/tests/benchmark/test_cuvs_collection_benchmark.py b/tests/benchmark/test_cuvs_collection_benchmark.py
new file mode 100644
index 000000000..152b12c1a
--- /dev/null
+++ b/tests/benchmark/test_cuvs_collection_benchmark.py
@@ -0,0 +1,143 @@
+import importlib.util
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+MODULE_PATH = (
+ Path(__file__).resolve().parents[2] / "benchmark" / "cuvs" / "run_collection_benchmark.py"
+)
+SPEC = importlib.util.spec_from_file_location("run_cuvs_collection_benchmark", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+benchmark = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = benchmark
+SPEC.loader.exec_module(benchmark)
+
+
+def test_filter_scenarios_cover_scalar_and_path_selectivity():
+ scenarios = benchmark.filter_scenarios()
+
+ assert [scenario.name for scenario in scenarios] == [
+ "unfiltered",
+ "uniform_10pct",
+ "uniform_1pct",
+ "uniform_0_1pct",
+ "clustered_10pct",
+ "clustered_1pct",
+ "clustered_0_1pct",
+ "path_10pct",
+ "path_1pct",
+ "path_0_1pct",
+ ]
+ assert [scenario.selectivity for scenario in scenarios] == [
+ 1.0,
+ 0.1,
+ 0.01,
+ 0.001,
+ 0.1,
+ 0.01,
+ 0.001,
+ 0.1,
+ 0.01,
+ 0.001,
+ ]
+ assert [scenario.distribution for scenario in scenarios[-3:]] == ["path"] * 3
+ assert [scenario.filter["conds"][0] for scenario in scenarios[-3:]] == [
+ "/docs/g0",
+ "/docs/g0/h0",
+ "/docs/g0/h0/i0",
+ ]
+ assert all(scenario.filter["para"] == "-d=-1" for scenario in scenarios[-3:])
+
+
+def test_scalar_fields_have_expected_uniform_and_clustered_counts():
+ vector_count = 10_000
+ values = [benchmark.scalar_fields(index, vector_count) for index in range(vector_count)]
+
+ assert sum(uniform < 10 for uniform, _ in values) == 100
+ assert sum(clustered < 10 for _, clustered in values) == 100
+ assert [clustered for _, clustered in values[:10]] == [0] * 10
+ assert [uniform for uniform, _ in values[:10]] == list(range(10))
+
+
+def test_prebuild_selective_scenario_respects_native_threshold():
+ scenario = benchmark.prebuild_selective_scenario(100_000, 2_000)
+
+ assert scenario is not None
+ assert scenario.name == "prebuild_selective_0_1pct"
+ assert scenario.filter == {
+ "op": "must",
+ "field": "uniform_bucket",
+ "conds": [0],
+ }
+ assert scenario.selectivity == 0.001
+ assert benchmark.prebuild_selective_scenario(100_000, 99) is None
+ assert benchmark.prebuild_selective_scenario(100_000, 0) is None
+
+
+def test_recall_at_k_handles_short_filtered_results():
+ actual = [[3, 2], [], [9, 1, 4]]
+ expected = [[2, 3], [], [9, 8, 7]]
+
+ assert benchmark.recall_at_k(actual, expected, 3) == pytest.approx((1.0 + 1.0 + 1 / 3) / 3)
+
+
+def test_run_search_scenario_times_adapter_path_and_preserves_ids():
+ class FakeAdapter:
+ def __init__(self):
+ self.calls = []
+
+ def query(self, *, query_vector, filter, limit, output_fields):
+ self.calls.append((query_vector, filter, limit, output_fields))
+ return [{"id": int(query_vector[0]) + 1}]
+
+ adapter = FakeAdapter()
+ queries = np.asarray([[0.0, 1.0], [1.0, 0.0]], dtype=np.float32)
+ scenario = benchmark.FilterScenario(
+ "filtered",
+ {"op": "range", "field": "uniform_bucket", "lt": 10},
+ "uniform",
+ 0.01,
+ )
+
+ result = benchmark.run_search_scenario(
+ adapter,
+ queries,
+ scenario=scenario,
+ k=10,
+ warmup_queries=2,
+ )
+
+ assert result["neighbors"] == [[1], [2]]
+ assert result["search"]["query_count"] == 2
+ assert result["search"]["qps"] > 0
+ assert len(adapter.calls) == 5
+ assert all(call[1] == scenario.filter for call in adapter.calls)
+
+
+def test_run_single_query_scenario_records_latency_and_result_count(monkeypatch):
+ class FakeAdapter:
+ def query(self, *, query_vector, filter, limit, output_fields):
+ assert query_vector == [1.0, 0.0]
+ assert filter["conds"] == [0]
+ assert limit == 10
+ assert output_fields == ["id"]
+ return [{"id": 1}]
+
+ gpu_samples = iter([100, 104])
+ monkeypatch.setattr(benchmark, "gpu_memory_used_bytes", lambda: next(gpu_samples))
+ scenario = benchmark.prebuild_selective_scenario(100_000, 2_000)
+ assert scenario is not None
+
+ result = benchmark.run_single_query_scenario(
+ FakeAdapter(),
+ [1.0, 0.0],
+ scenario=scenario,
+ k=10,
+ )
+
+ assert result["name"] == "prebuild_selective_0_1pct"
+ assert result["result_count"] == 1
+ assert result["latency_ms"] >= 0
+ assert result["gpu_delta_bytes"] == 4
diff --git a/tests/benchmark/test_cuvs_collection_summary.py b/tests/benchmark/test_cuvs_collection_summary.py
new file mode 100644
index 000000000..0f7f8fa01
--- /dev/null
+++ b/tests/benchmark/test_cuvs_collection_summary.py
@@ -0,0 +1,146 @@
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+MODULE_PATH = (
+ Path(__file__).resolve().parents[2] / "benchmark" / "cuvs" / "summarize_collection_runs.py"
+)
+SPEC = importlib.util.spec_from_file_location("summarize_cuvs_collection_runs", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+summary_module = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = summary_module
+SPEC.loader.exec_module(summary_module)
+
+
+def result_document(*, qps, p50, timestamp="run-1", dimension=8):
+ return {
+ "format_version": 1,
+ "runtime": {
+ "timestamp": timestamp,
+ "git_revision": "abc123",
+ "git_dirty": False,
+ "gpu": {"name": "test-gpu"},
+ "cpu_model": "test-cpu",
+ "cuvs": "1.0",
+ "cupy": "2.0",
+ },
+ "dataset": {
+ "kind": "random",
+ "vector_count": 100,
+ "dimension": dimension,
+ "query_count": 10,
+ "metric": "cosine",
+ "seed": 42,
+ },
+ "parameters": {"k": 10, "mutation_sizes": [1]},
+ "results": [
+ {
+ "backend": "cuvs_brute_force",
+ "ingest": {"total_seconds": 2.0, "records_per_second": 50.0},
+ "rss_ingest_delta_bytes": 1000,
+ "gpu_search_delta_bytes": 2000,
+ "searches": [
+ {
+ "name": "unfiltered",
+ "filter": None,
+ "distribution": "none",
+ "target_selectivity": 1.0,
+ "first_query_ms": 20.0,
+ "recall_at_k": 1.0,
+ "search": {
+ "qps": qps,
+ "latency_ms": {"p50": p50, "p95": p50 * 2, "p99": p50 * 3},
+ },
+ }
+ ],
+ "lifecycle": {
+ "updates": [
+ {
+ "count": 1,
+ "write_wall_seconds": 0.1,
+ "next_query_ms": 30.0,
+ "warm_query_ms": 1.0,
+ }
+ ],
+ "delete": {
+ "write_seconds": 0.1,
+ "next_query_ms": 30.0,
+ "warm_query_ms": 1.0,
+ },
+ "restart": {
+ "close_seconds": 0.1,
+ "adapter_construct_seconds": 0.01,
+ "first_query_ms": 40.0,
+ "warm_query_ms": 1.0,
+ },
+ },
+ }
+ ],
+ }
+
+
+def write_result(path, document):
+ path.write_text(json.dumps(document))
+ return path
+
+
+def test_summarize_collection_runs_reports_process_median_and_mad(tmp_path):
+ documents = [
+ result_document(qps=100, p50=1.0, timestamp="run-1"),
+ result_document(qps=110, p50=1.2, timestamp="run-2"),
+ result_document(qps=300, p50=1.1, timestamp="run-3"),
+ ]
+ for document, latency_ms in zip(documents, (2.0, 2.4, 8.0), strict=True):
+ document["results"][0]["prebuild_selective_query"] = {
+ "name": "prebuild_selective_0_1pct",
+ "filter": {"op": "must", "field": "uniform_bucket", "conds": [0]},
+ "distribution": "uniform",
+ "target_selectivity": 0.001,
+ "latency_ms": latency_ms,
+ "result_count": 10,
+ "gpu_delta_bytes": 0,
+ }
+ paths = [
+ write_result(tmp_path / f"run-{index}.json", document)
+ for index, document in enumerate(documents, start=1)
+ ]
+
+ summary = summary_module.summarize_files(paths)
+
+ assert summary["run_count"] == 3
+ assert str(tmp_path) not in json.dumps(summary)
+ result = summary["results"][0]
+ assert result["backend"] == "cuvs_brute_force"
+ assert result["prebuild_selective_query"]["metrics"]["latency_ms"]["median"] == 2.4
+ assert result["prebuild_selective_query"]["metrics"]["latency_ms"]["mad"] == pytest.approx(0.4)
+ assert result["searches"][0]["metrics"]["qps"]["median"] == 110
+ assert result["searches"][0]["metrics"]["qps"]["mad"] == 10
+ assert result["searches"][0]["metrics"]["warm_p50_ms"]["median"] == pytest.approx(1.1)
+ assert result["lifecycle"]["updates"][0]["metrics"]["next_query_ms"]["median"] == 30
+
+
+def test_summarize_collection_runs_rejects_mismatched_dataset(tmp_path):
+ paths = [
+ write_result(tmp_path / "run-1.json", result_document(qps=100, p50=1.0, timestamp="run-1")),
+ write_result(
+ tmp_path / "run-2.json",
+ result_document(qps=110, p50=1.2, timestamp="run-2", dimension=16),
+ ),
+ ]
+
+ with pytest.raises(ValueError, match="Dataset metadata differs"):
+ summary_module.summarize_files(paths)
+
+
+def test_summarize_collection_runs_rejects_duplicate_process(tmp_path):
+ document = result_document(qps=100, p50=1.0, timestamp="same-run")
+ paths = [
+ write_result(tmp_path / "run-1.json", document),
+ write_result(tmp_path / "renamed-run-1.json", document),
+ ]
+
+ with pytest.raises(ValueError, match="Duplicate process timestamp"):
+ summary_module.summarize_files(paths)
diff --git a/tests/benchmark/test_cuvs_index_benchmark.py b/tests/benchmark/test_cuvs_index_benchmark.py
new file mode 100644
index 000000000..ced860a84
--- /dev/null
+++ b/tests/benchmark/test_cuvs_index_benchmark.py
@@ -0,0 +1,150 @@
+import importlib.util
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+MODULE_PATH = Path(__file__).resolve().parents[2] / "benchmark" / "cuvs" / "run_index_benchmark.py"
+SPEC = importlib.util.spec_from_file_location("run_cuvs_index_benchmark", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+benchmark = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = benchmark
+SPEC.loader.exec_module(benchmark)
+
+
+def test_percentile_interpolates_and_recall_ignores_order():
+ assert benchmark.percentile([1.0, 2.0, 3.0, 4.0], 0.5) == pytest.approx(2.5)
+ actual = np.asarray([[2, 1, 8], [4, 5, 6]])
+ expected = np.asarray([[1, 2, 3], [4, 7, 8]])
+ assert benchmark.recall_at_k(actual, expected, 3) == pytest.approx(0.5)
+
+
+def test_prepare_dataset_is_normalized_deterministic_and_reusable(tmp_path):
+ arguments = {
+ "vector_count": 32,
+ "dimension": 8,
+ "query_count": 5,
+ "metric": "cosine",
+ "seed": 7,
+ "generation_chunk_size": 11,
+ "force": False,
+ }
+ first = benchmark.prepare_dataset(tmp_path, **arguments)
+ dataset = np.load(first.dataset, mmap_mode="r", allow_pickle=False)
+ queries = np.load(first.queries, mmap_mode="r", allow_pickle=False)
+
+ assert first.reused is False
+ assert dataset.shape == (32, 8)
+ assert queries.shape == (5, 8)
+ np.testing.assert_allclose(np.linalg.norm(dataset, axis=1), 1.0, atol=1e-5)
+ np.testing.assert_allclose(np.linalg.norm(queries, axis=1), 1.0, atol=1e-5)
+
+ second = benchmark.prepare_dataset(tmp_path, **arguments)
+ assert second.reused is True
+ assert second.generated_seconds == 0.0
+ np.testing.assert_array_equal(dataset, np.load(second.dataset, allow_pickle=False))
+
+
+def test_prepare_ann_benchmarks_dataset_converts_normalizes_and_reuses(tmp_path):
+ h5py = pytest.importorskip("h5py")
+ source = tmp_path / "tiny-angular.hdf5"
+ with h5py.File(source, "w") as hdf5:
+ hdf5.attrs["distance"] = "angular"
+ hdf5.create_dataset(
+ "train",
+ data=np.asarray([[3.0, 4.0], [1.0, 0.0], [0.0, 2.0]], dtype=np.float32),
+ )
+ hdf5.create_dataset(
+ "test",
+ data=np.asarray([[6.0, 8.0], [2.0, 0.0]], dtype=np.float32),
+ )
+ hdf5.create_dataset("neighbors", data=np.asarray([[0, 1], [1, 0]], dtype=np.int32))
+
+ arguments = {
+ "source": source,
+ "metric": "cosine",
+ "vector_limit": None,
+ "query_limit": 1,
+ "generation_chunk_size": 2,
+ "force": False,
+ }
+ first = benchmark.prepare_ann_benchmarks_dataset(tmp_path / "data", **arguments)
+ dataset = np.load(first.dataset, mmap_mode="r", allow_pickle=False)
+ queries = np.load(first.queries, mmap_mode="r", allow_pickle=False)
+ ground_truth = np.load(first.ground_truth, mmap_mode="r", allow_pickle=False)
+
+ assert first.reused is False
+ assert dataset.shape == (3, 2)
+ assert queries.shape == (1, 2)
+ np.testing.assert_allclose(np.linalg.norm(dataset, axis=1), 1.0, atol=1e-6)
+ np.testing.assert_allclose(np.linalg.norm(queries, axis=1), 1.0, atol=1e-6)
+ np.testing.assert_array_equal(ground_truth, np.asarray([[0, 1]]))
+ metadata = first.metadata.read_text()
+ assert str(source) not in metadata
+ assert '"source_sha256"' in metadata
+
+ second = benchmark.prepare_ann_benchmarks_dataset(tmp_path / "data", **arguments)
+ assert second.reused is True
+ assert second.generated_seconds == 0.0
+
+
+def test_cagra_itopk_sweep_preserves_shared_search_params():
+ parser = benchmark.build_parser()
+ args = parser.parse_args(
+ [
+ "--cagra-search-params",
+ '{"search_width":2}',
+ "--cagra-itopk-sizes",
+ "32,64,128",
+ ]
+ )
+
+ assert benchmark.cagra_search_variants(args) == [
+ {"search_width": 2, "itopk_size": 32},
+ {"search_width": 2, "itopk_size": 64},
+ {"search_width": 2, "itopk_size": 128},
+ ]
+
+
+def test_cagra_itopk_and_search_width_sweeps_form_cartesian_product():
+ parser = benchmark.build_parser()
+ args = parser.parse_args(
+ [
+ "--cagra-itopk-sizes",
+ "64,128",
+ "--cagra-search-widths",
+ "1,4",
+ ]
+ )
+
+ assert benchmark.cagra_search_variants(args) == [
+ {"itopk_size": 64, "search_width": 1},
+ {"itopk_size": 128, "search_width": 1},
+ {"itopk_size": 64, "search_width": 4},
+ {"itopk_size": 128, "search_width": 4},
+ ]
+
+
+def test_run_search_records_batches_and_preserves_query_order():
+ class FakeBackend:
+ def search(self, queries, k):
+ labels = np.repeat(queries[:, :1].astype(np.int64), k, axis=1)
+ return labels, np.zeros_like(labels, dtype=np.float32)
+
+ queries = np.arange(5, dtype=np.float32).reshape(5, 1)
+ neighbors, summary = benchmark.run_search(
+ FakeBackend(),
+ queries,
+ k=2,
+ batch_size=2,
+ warmup_batches=1,
+ repetitions=2,
+ )
+
+ np.testing.assert_array_equal(neighbors[:, 0], np.arange(5))
+ assert summary["unique_query_count"] == 5
+ assert summary["timed_query_count"] == 10
+ assert summary["batch_count"] == 6
+ assert len(summary["raw_batch_latency_ms"]) == 6
+ assert summary["qps"] > 0
diff --git a/tests/benchmark/test_cuvs_index_summary.py b/tests/benchmark/test_cuvs_index_summary.py
new file mode 100644
index 000000000..834d4c41a
--- /dev/null
+++ b/tests/benchmark/test_cuvs_index_summary.py
@@ -0,0 +1,139 @@
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+MODULE_PATH = Path(__file__).resolve().parents[2] / "benchmark" / "cuvs" / "summarize_index_runs.py"
+SPEC = importlib.util.spec_from_file_location("summarize_cuvs_index_runs", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+summary_module = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = summary_module
+SPEC.loader.exec_module(summary_module)
+
+
+def result_document(*, qps, p50, build, dataset_name="public", itopk=512):
+ return {
+ "format_version": 2,
+ "runtime": {
+ "timestamp": f"run-{qps}",
+ "git_revision": "abc123",
+ "git_dirty": False,
+ "gpu": {"name": "test-gpu"},
+ "cpu_model": "test-cpu",
+ "cuvs": "1.0",
+ "cupy": "2.0",
+ },
+ "dataset": {
+ "kind": "ann-benchmarks-hdf5",
+ "name": dataset_name,
+ "source_sha256": "deadbeef",
+ "vector_count": 100,
+ "dimension": 8,
+ "query_count": 10,
+ "metric": "cosine",
+ "seed": None,
+ },
+ "parameters": {"k": 10, "query_batch_size": 1},
+ "results": [
+ {
+ "backend": "cuvs_cagra",
+ "cagra_search_params": {"itopk_size": itopk},
+ "build_seconds": build,
+ "first_search_per_query_ms": p50 * 10,
+ "recall_at_k": 0.99,
+ "rss_delta_bytes": 1000,
+ "gpu_used_delta_bytes": 2000,
+ "search": {
+ "qps": qps,
+ "per_query_latency_ms": {"p50": p50, "p95": p50 * 2, "p99": p50 * 3},
+ },
+ }
+ ],
+ }
+
+
+def write_result(path, document):
+ path.write_text(json.dumps(document))
+ return path
+
+
+def test_summarize_files_reports_process_median_and_mad(tmp_path):
+ paths = [
+ write_result(tmp_path / "run-1.json", result_document(qps=100, p50=1.0, build=3.0)),
+ write_result(tmp_path / "run-2.json", result_document(qps=110, p50=1.2, build=2.0)),
+ write_result(tmp_path / "run-3.json", result_document(qps=300, p50=1.1, build=4.0)),
+ ]
+
+ summary = summary_module.summarize_files(paths)
+
+ assert summary["run_count"] == 3
+ assert summary["runs"][0]["source"] == "run-1.json"
+ assert str(tmp_path) not in json.dumps(summary)
+ result = summary["results"][0]
+ assert result["cagra_search_params"] == {"itopk_size": 512}
+ assert result["metrics"]["qps"]["median"] == 110
+ assert result["metrics"]["qps"]["mad"] == 10
+ assert result["metrics"]["warm_p50_ms"]["median"] == pytest.approx(1.1)
+ assert result["metrics"]["warm_p50_ms"]["mad"] == pytest.approx(0.1)
+
+
+def test_variant_sort_key_orders_backends_and_numeric_itopk():
+ keys = [
+ ("cuvs_cagra", summary_module.canonical({"itopk_size": 2048})),
+ ("cuvs_brute_force", summary_module.canonical(None)),
+ ("cuvs_cagra", summary_module.canonical({"itopk_size": 512})),
+ ("native", summary_module.canonical(None)),
+ ]
+
+ assert sorted(keys, key=summary_module.variant_sort_key) == [
+ ("native", "null"),
+ ("cuvs_brute_force", "null"),
+ ("cuvs_cagra", '{"itopk_size":512}'),
+ ("cuvs_cagra", '{"itopk_size":2048}'),
+ ]
+
+
+def test_summarize_files_rejects_mismatched_dataset(tmp_path):
+ paths = [
+ write_result(tmp_path / "run-1.json", result_document(qps=100, p50=1.0, build=3.0)),
+ write_result(
+ tmp_path / "run-2.json",
+ result_document(qps=110, p50=1.2, build=2.0, dataset_name="different"),
+ ),
+ ]
+
+ with pytest.raises(ValueError, match="Dataset metadata differs"):
+ summary_module.summarize_files(paths)
+
+
+def test_summarize_files_rejects_mismatched_variants(tmp_path):
+ paths = [
+ write_result(tmp_path / "run-1.json", result_document(qps=100, p50=1.0, build=3.0)),
+ write_result(
+ tmp_path / "run-2.json",
+ result_document(qps=110, p50=1.2, build=2.0, itopk=2048),
+ ),
+ ]
+
+ with pytest.raises(ValueError, match="Backend/search variants differ"):
+ summary_module.summarize_files(paths)
+
+
+def test_summarize_files_rejects_repeated_path(tmp_path):
+ path = write_result(tmp_path / "run-1.json", result_document(qps=100, p50=1.0, build=3.0))
+
+ with pytest.raises(ValueError, match="cannot be repeated"):
+ summary_module.summarize_files([path, path])
+
+
+def test_summarize_files_rejects_renamed_duplicate_process(tmp_path):
+ document = result_document(qps=100, p50=1.0, build=3.0)
+ paths = [
+ write_result(tmp_path / "run-1.json", document),
+ write_result(tmp_path / "renamed-run-1.json", document),
+ ]
+
+ with pytest.raises(ValueError, match="Duplicate process timestamp"):
+ summary_module.summarize_files(paths)
diff --git a/tests/benchmark/test_cuvs_service_concurrency_benchmark.py b/tests/benchmark/test_cuvs_service_concurrency_benchmark.py
new file mode 100644
index 000000000..ac7d80d43
--- /dev/null
+++ b/tests/benchmark/test_cuvs_service_concurrency_benchmark.py
@@ -0,0 +1,65 @@
+import importlib.util
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+MODULE_PATH = (
+ Path(__file__).resolve().parents[2]
+ / "benchmark"
+ / "cuvs"
+ / "run_service_concurrency_benchmark.py"
+)
+SPEC = importlib.util.spec_from_file_location("run_cuvs_service_concurrency_benchmark", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+benchmark = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = benchmark
+SPEC.loader.exec_module(benchmark)
+
+
+def test_unique_filters_are_distinct_and_keep_enough_candidates():
+ filters = [benchmark.unique_filter(index, 100_000, 10_000) for index in range(32)]
+
+ assert len({(item["gte"], item["lt"]) for item in filters}) == 32
+ assert all(item["lt"] - item["gte"] == 100 for item in filters)
+ assert all(0 <= item["gte"] < item["lt"] <= 100_000 for item in filters)
+
+
+def test_service_record_contains_tenant_and_filter_fields():
+ record = benchmark.make_record(1001, [1.0, 0.0])
+
+ assert record == {
+ "id": "record-1001",
+ "vector": [1.0, 0.0],
+ "account_id": "benchmark",
+ "uniform_bucket": 1,
+ "row_number": 1001,
+ }
+
+
+async def test_run_request_set_reports_concurrent_successes():
+ class FakeManager:
+ async def query(self, **_kwargs):
+ return [{"id": str(index)} for index in range(10)]
+
+ ctx = benchmark.RequestContext(
+ user=benchmark.UserIdentifier("benchmark", "user"),
+ role=benchmark.Role.USER,
+ )
+ result = await benchmark.run_request_set(
+ FakeManager(),
+ ctx,
+ np.asarray([[1.0, 0.0], [0.0, 1.0]], dtype=np.float32),
+ concurrency=4,
+ request_count=12,
+ k=10,
+ filter_factory=lambda _index: None,
+ )
+
+ assert result["request_count"] == 12
+ assert result["success_count"] == 12
+ assert result["error_count"] == 0
+ assert result["qps"] > 0
+ assert len(result["raw_latency_ms"]) == 12
diff --git a/tests/benchmark/test_cuvs_service_summary.py b/tests/benchmark/test_cuvs_service_summary.py
new file mode 100644
index 000000000..c1166988a
--- /dev/null
+++ b/tests/benchmark/test_cuvs_service_summary.py
@@ -0,0 +1,113 @@
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+MODULE_PATH = (
+ Path(__file__).resolve().parents[2] / "benchmark" / "cuvs" / "summarize_service_runs.py"
+)
+SPEC = importlib.util.spec_from_file_location("summarize_cuvs_service_runs", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+summary_module = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = summary_module
+SPEC.loader.exec_module(summary_module)
+
+
+def result_document(*, qps, p50, timestamp="run-1", dimension=8):
+ return {
+ "format_version": 1,
+ "runtime": {
+ "timestamp": timestamp,
+ "git_revision": "abc123",
+ "git_dirty": False,
+ "gpu": {"name": "test-gpu"},
+ "cpu_model": "test-cpu",
+ "cuvs": "1.0",
+ "cupy": "2.0",
+ },
+ "dataset": {
+ "kind": "random",
+ "vector_count": 100,
+ "dimension": dimension,
+ "query_count": 10,
+ "metric": "cosine",
+ "seed": 42,
+ },
+ "parameters": {"k": 10, "concurrency": [4]},
+ "results": [
+ {
+ "backend": "cuvs_brute_force",
+ "ingest": {"total_seconds": 2.0, "records_per_second": 50.0},
+ "scenarios": [
+ {
+ "name": "tenant_cached",
+ "filter_mode": "cached",
+ "filter": None,
+ "initial_filter_query_ms": 20.0,
+ "results": [
+ {
+ "concurrency": 4,
+ "wall_seconds": 1.0,
+ "qps": qps,
+ "error_count": 0,
+ "latency_ms": {
+ "p50": p50,
+ "p95": p50 * 2,
+ "p99": p50 * 3,
+ "max": p50 * 4,
+ },
+ }
+ ],
+ }
+ ],
+ }
+ ],
+ }
+
+
+def write_result(path, document):
+ path.write_text(json.dumps(document))
+ return path
+
+
+def test_summarize_service_runs_reports_process_median_and_mad(tmp_path):
+ paths = [
+ write_result(tmp_path / "run-1.json", result_document(qps=100, p50=1.0, timestamp="run-1")),
+ write_result(tmp_path / "run-2.json", result_document(qps=110, p50=1.2, timestamp="run-2")),
+ write_result(tmp_path / "run-3.json", result_document(qps=300, p50=1.1, timestamp="run-3")),
+ ]
+
+ summary = summary_module.summarize_files(paths)
+
+ assert summary["run_count"] == 3
+ assert str(tmp_path) not in json.dumps(summary)
+ result = summary["results"][0]["scenarios"][0]["results"][0]
+ assert result["metrics"]["qps"]["median"] == 110
+ assert result["metrics"]["qps"]["mad"] == 10
+ assert result["metrics"]["p50_ms"]["median"] == pytest.approx(1.1)
+
+
+def test_summarize_service_runs_rejects_mismatched_dataset(tmp_path):
+ paths = [
+ write_result(tmp_path / "run-1.json", result_document(qps=100, p50=1.0, timestamp="run-1")),
+ write_result(
+ tmp_path / "run-2.json",
+ result_document(qps=110, p50=1.2, timestamp="run-2", dimension=16),
+ ),
+ ]
+
+ with pytest.raises(ValueError, match="Dataset metadata differs"):
+ summary_module.summarize_files(paths)
+
+
+def test_summarize_service_runs_rejects_duplicate_process(tmp_path):
+ document = result_document(qps=100, p50=1.0, timestamp="same-run")
+ paths = [
+ write_result(tmp_path / "run-1.json", document),
+ write_result(tmp_path / "renamed-run-1.json", document),
+ ]
+
+ with pytest.raises(ValueError, match="Duplicate process timestamp"):
+ summary_module.summarize_files(paths)
diff --git a/tests/engine/CMakeLists.txt b/tests/engine/CMakeLists.txt
index 4461cfca2..3b4ead42b 100644
--- a/tests/engine/CMakeLists.txt
+++ b/tests/engine/CMakeLists.txt
@@ -12,6 +12,13 @@ include_directories(${CMAKE_SOURCE_DIR}/../../third_party/spdlog-1.14.1/include)
find_package(Threads REQUIRED)
+if(NOT TARGET engine_impl)
+ add_subdirectory(
+ ${CMAKE_CURRENT_LIST_DIR}/../../src
+ ${CMAKE_CURRENT_BINARY_DIR}/openviking_cpp
+ )
+endif()
+
add_executable(test_common
test_common.cpp
${CMAKE_SOURCE_DIR}/../../src/common/log_utils.cpp
@@ -25,10 +32,6 @@ add_executable(test_index_engine
test_index_engine.cpp
)
-if(NOT TARGET engine_impl)
- message(FATAL_ERROR "engine_impl compatibility target was not created")
-endif()
-
target_link_libraries(test_index_engine PRIVATE
engine_impl
Threads::Threads
diff --git a/tests/engine/test_index_engine.cpp b/tests/engine/test_index_engine.cpp
index a590c6cae..c839ef9c3 100644
--- a/tests/engine/test_index_engine.cpp
+++ b/tests/engine/test_index_engine.cpp
@@ -28,16 +28,22 @@ void test_basic_workflow() {
// 1. Initialization (Using JSON config)
std::string config = R"({
- "vector_index": {
- "type": "flat",
- "dim": 4,
- "metric": "l2"
+ "CollectionName": "engine_test",
+ "IndexName": "default",
+ "VectorIndex": {
+ "IndexType": "flat",
+ "ElementCount": 0,
+ "MaxElementCount": 2,
+ "Dimension": 4,
+ "Distance": "l2",
+ "Quant": "float"
},
- "scalar_index": {
- "title": "string",
- "count": "int64",
- "price": "float32"
- }
+ "ScalarIndex": [
+ {"FieldName": "title", "FieldType": "string"},
+ {"FieldName": "count", "FieldType": "int64"},
+ {"FieldName": "price", "FieldType": "float32"},
+ {"FieldName": "uri", "FieldType": "path"}
+ ]
})";
IndexEngine engine(config);
@@ -52,13 +58,15 @@ void test_basic_workflow() {
AddDataRequest req1;
req1.label = 1001;
req1.vector = {0.1, 0.1, 0.1, 0.1};
- req1.fields_str = R"({"title": "apple", "count": 10, "price": 5.5})";
+ req1.fields_str =
+ R"({"title": "apple", "count": 10, "price": 5.5, "uri": "/docs/one"})";
add_reqs.push_back(req1);
AddDataRequest req2;
req2.label = 1002;
req2.vector = {0.2, 0.2, 0.2, 0.2};
- req2.fields_str = R"({"title": "banana", "count": 20, "price": 3.0})";
+ req2.fields_str =
+ R"({"title": "banana", "count": 20, "price": 3.0, "uri": "/other/two"})";
add_reqs.push_back(req2);
int ret = engine.add_data(add_reqs);
@@ -82,11 +90,28 @@ void test_basic_workflow() {
exit(1);
}
+ // Native scalar filters can be projected into any external row order. This
+ // is the bridge used by external dense indexes such as cuVS.
+ if (engine.set_filter_layout({1002, 9999, 1001}) != 0) {
+ SPDLOG_ERROR("Filter layout registration failed");
+ exit(1);
+ }
+ FilterResult filter_res = engine.evaluate_filter(
+ R"({"op":"must","field":"uri","conds":["/docs"],"para":"-d=-1"})");
+ if (filter_res.eligible_count != 1 || filter_res.bitset_words.size() != 1 ||
+ filter_res.bitset_words[0] != 4U) {
+ SPDLOG_ERROR(
+ "Filter projection failed: count={}, words={}, first_word={}",
+ filter_res.eligible_count, filter_res.bitset_words.size(),
+ filter_res.bitset_words.empty() ? 0 : filter_res.bitset_words[0]);
+ exit(1);
+ }
+
// 4. Delete Data
std::vector<DeleteDataRequest> del_reqs(1);
del_reqs[0].label = 1001;
del_reqs[0].old_fields_str =
- R"({"title": "apple", "count": 10, "price": 5.5})";
+ R"({"title": "apple", "count": 10, "price": 5.5, "uri": "/docs/one"})";
ret = engine.delete_data(del_reqs);
if (ret != 0) {
@@ -118,7 +143,7 @@ void test_basic_workflow() {
}
int main() {
- init_logging("INFO", "stdout");
+ init_logging("INFO", "stdout", "[%Y-%m-%d %H:%M:%S.%e] [%l] %v");
test_basic_workflow();
return 0;
}
diff --git a/tests/misc/test_vectordb_engine_loader.py b/tests/misc/test_vectordb_engine_loader.py
index 79a6e6a43..2b4123cab 100644
--- a/tests/misc/test_vectordb_engine_loader.py
+++ b/tests/misc/test_vectordb_engine_loader.py
@@ -246,6 +246,13 @@ def test_engine_loader_wraps_abi3_backend_with_python_api(monkeypatch):
"extra_json": '{"ok":true}',
}
),
+ _index_engine_set_filter_layout=lambda handle, labels: (
+ calls.append(("set_filter_layout", handle, labels)) or 0
+ ),
+ _index_engine_evaluate_filter=lambda handle, dsl: (
+ calls.append(("evaluate_filter", handle, dsl))
+ or {"eligible_count": 1, "bitset_words": [4]}
+ ),
_index_engine_dump=lambda handle, path: calls.append(("dump", handle, path)) or 11,
_index_engine_get_state=lambda handle: (
calls.append(("get_state", handle)) or {"update_timestamp": 123, "element_count": 7}
@@ -311,6 +318,11 @@ def test_engine_loader_wraps_abi3_backend_with_python_api(monkeypatch):
assert result.scores == [0.9, 0.8]
assert result.extra_json == '{"ok":true}'
+ assert index.set_filter_layout([202, 999, 101]) == 0
+ filter_result = index.evaluate_filter('{"op":"must"}')
+ assert filter_result.eligible_count == 1
+ assert filter_result.bitset_words == [4]
+
state = index.get_state()
assert state.update_timestamp == 123
assert state.element_count == 7
diff --git a/tests/vectordb/test_cuvs_collection.py b/tests/vectordb/test_cuvs_collection.py
new file mode 100644
index 000000000..983a9f6b1
--- /dev/null
+++ b/tests/vectordb/test_cuvs_collection.py
@@ -0,0 +1,396 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from openviking.storage.vectordb.collection.local_collection import (
+ get_or_create_local_collection,
+)
+from openviking.storage.vectordb.index import cuvs_index
+
+
+class FakeCuVSRuntime:
+ def __init__(self, metric):
+ self.metric = metric
+ self.search_count = 0
+
+ def build(self, dataset):
+ return [list(vector) for vector in dataset]
+
+ def search(self, index, query, limit, mask):
+ self.search_count += 1
+ rows = []
+ for offset, vector in enumerate(index):
+ if mask is not None and not mask[offset]:
+ continue
+ if self.metric == "sqeuclidean":
+ distance = sum(
+ (left - right) ** 2 for left, right in zip(query, vector, strict=True)
+ )
+ key = distance
+ else:
+ distance = sum(left * right for left, right in zip(query, vector, strict=True))
+ key = -distance
+ rows.append((key, offset, distance))
+ rows.sort()
+ rows = rows[:limit]
+ return [row[1] for row in rows], [row[2] for row in rows]
+
+ def close(self):
+ pass
+
+
+class MemoryAwareFakeCuVSRuntime(FakeCuVSRuntime):
+ def __init__(self, metric, free_memory_bytes):
+ super().__init__(metric)
+ self.free_memory_bytes = free_memory_bytes
+ self.build_count = 0
+
+ def build(self, dataset):
+ self.build_count += 1
+ return super().build(dataset)
+
+ def memory_info(self):
+ return self.free_memory_bytes, 1 << 40
+
+ def release_index(self):
+ pass
+
+ @staticmethod
+ def is_out_of_memory(_exc):
+ return False
+
+
+def patch_cuvs_runtime(monkeypatch):
+ monkeypatch.setattr(
+ cuvs_index,
+ "_CuVSRuntime",
+ lambda algorithm, metric, build_params, search_params: FakeCuVSRuntime(metric),
+ )
+
+
+def test_local_collection_routes_dense_search_to_cuvs(monkeypatch):
+ patch_cuvs_runtime(monkeypatch)
+ collection = get_or_create_local_collection(
+ meta_data={
+ "CollectionName": "cuvs_integration",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ {"FieldName": "account_id", "FieldType": "string"},
+ {"FieldName": "rank", "FieldType": "int64"},
+ {"FieldName": "created_at", "FieldType": "date_time"},
+ {"FieldName": "uri", "FieldType": "path"},
+ ],
+ },
+ config={
+ "dense_search": {
+ "backend": "cuvs",
+ "algorithm": "brute_force",
+ }
+ },
+ )
+ try:
+ collection.create_index(
+ "default",
+ {
+ "IndexName": "default",
+ "VectorIndex": {"IndexType": "flat", "Distance": "cosine"},
+ "ScalarIndex": ["account_id", "rank", "created_at", "uri"],
+ },
+ )
+ collection.upsert_data(
+ [
+ {
+ "id": "first",
+ "vector": [1, 0, 0, 0],
+ "account_id": "a",
+ "rank": 3,
+ "created_at": "2026-07-02T00:00:00Z",
+ "uri": "/docs/one",
+ },
+ {
+ "id": "second",
+ "vector": [0, 1, 0, 0],
+ "account_id": "a",
+ "rank": 2,
+ "created_at": "2026-07-01T00:00:00Z",
+ "uri": "/docs/deep/two",
+ },
+ {
+ "id": "hidden",
+ "vector": [1, 0, 0, 0],
+ "account_id": "b",
+ "rank": 1,
+ "created_at": "2026-06-01T00:00:00Z",
+ "uri": "/other/hidden",
+ },
+ ]
+ )
+
+ result = collection.search_by_vector(
+ "default",
+ dense_vector=[1, 0, 0, 0],
+ limit=3,
+ filters={"op": "must", "field": "account_id", "conds": ["a"]},
+ )
+ assert [item.id for item in result.data] == ["first", "second"]
+
+ result = collection.search_by_vector(
+ "default",
+ dense_vector=[1, 0, 0, 0],
+ limit=3,
+ filters={
+ "op": "must",
+ "field": "uri",
+ "conds": ["/docs"],
+ "para": "-d=-1",
+ },
+ )
+ assert [item.id for item in result.data] == ["first", "second"]
+
+ # date_time conversion is deliberately delegated to the native engine.
+ result = collection.search_by_vector(
+ "default",
+ dense_vector=[1, 0, 0, 0],
+ limit=3,
+ filters={
+ "op": "and",
+ "conds": [
+ {"op": "must", "field": "account_id", "conds": ["a"]},
+ {
+ "op": "range",
+ "field": "created_at",
+ "gte": "2026-07-02T00:00:00Z",
+ },
+ ],
+ },
+ )
+ assert [item.id for item in result.data] == ["first"]
+ assert len(collection.search_by_scalar("default", "rank", limit=3).data) == 3
+
+ collection.update_data(
+ [
+ {
+ "id": "second",
+ "vector": [2, 0, 0, 0],
+ "account_id": "a",
+ "rank": 2,
+ }
+ ]
+ )
+ collection.delete_data(["first"])
+ result = collection.search_by_vector("default", dense_vector=[1, 0, 0, 0], limit=3)
+ assert [item.id for item in result.data] == ["second", "hidden"]
+ finally:
+ collection.close()
+
+
+def test_persistent_collection_rehydrates_cuvs_from_local_store(monkeypatch, tmp_path):
+ patch_cuvs_runtime(monkeypatch)
+ path = str(tmp_path / "cuvs-persistent")
+ config = {"dense_search": {"backend": "cuvs", "algorithm": "brute_force"}}
+ collection = get_or_create_local_collection(
+ meta_data={
+ "CollectionName": "cuvs_persistent",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ {"FieldName": "account_id", "FieldType": "string"},
+ ],
+ },
+ path=path,
+ config=config,
+ )
+ collection.create_index(
+ "default",
+ {
+ "IndexName": "default",
+ "VectorIndex": {"IndexType": "flat", "Distance": "cosine"},
+ "ScalarIndex": ["account_id"],
+ },
+ )
+ collection.upsert_data([{"id": "persisted", "vector": [1, 0, 0, 0], "account_id": "a"}])
+ collection.close()
+
+ reopened = get_or_create_local_collection(path=path, config=config)
+ try:
+ result = reopened.search_by_vector("default", dense_vector=[1, 0, 0, 0], limit=1)
+ assert [item.id for item in result.data] == ["persisted"]
+ finally:
+ reopened.close()
+
+
+def test_auto_cuvs_falls_back_then_retries_when_memory_is_available(monkeypatch):
+ runtimes = []
+
+ def make_runtime(_algorithm, metric, _build_params, _search_params):
+ runtime = MemoryAwareFakeCuVSRuntime(metric, free_memory_bytes=31)
+ runtimes.append(runtime)
+ return runtime
+
+ monkeypatch.setattr(cuvs_index, "_CuVSRuntime", make_runtime)
+ collection = get_or_create_local_collection(
+ meta_data={
+ "CollectionName": "auto_cuvs_integration",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ {"FieldName": "account_id", "FieldType": "string"},
+ ],
+ },
+ config={
+ "dense_search": {
+ "backend": "auto_cuvs",
+ "algorithm": "brute_force",
+ "filter_cache_size": 0,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ }
+ },
+ )
+ try:
+ collection.create_index(
+ "default",
+ {
+ "IndexName": "default",
+ "VectorIndex": {"IndexType": "flat", "Distance": "cosine"},
+ "ScalarIndex": ["account_id"],
+ },
+ )
+ collection.upsert_data(
+ [
+ {
+ "id": "first",
+ "vector": [1.0, 0.0, 0.0, 0.0],
+ "account_id": "a",
+ },
+ {
+ "id": "second",
+ "vector": [0.0, 1.0, 0.0, 0.0],
+ "account_id": "b",
+ },
+ ]
+ )
+
+ result = collection.search_by_vector("default", dense_vector=[1.0, 0.0, 0.0, 0.0], limit=1)
+ assert [item.id for item in result.data] == ["first"]
+ assert runtimes[0].build_count == 0
+
+ runtimes[0].free_memory_bytes = 32
+ result = collection.search_by_vector("default", dense_vector=[1.0, 0.0, 0.0, 0.0], limit=1)
+ assert [item.id for item in result.data] == ["first"]
+ assert runtimes[0].build_count == 1
+
+ result = collection.search_by_vector(
+ "default",
+ dense_vector=[1.0, 0.0, 0.0, 0.0],
+ limit=1,
+ filters={"op": "must", "field": "account_id", "conds": ["a"]},
+ )
+ assert [item.id for item in result.data] == ["first"]
+ # The selective filtered query uses native search in auto mode.
+ assert runtimes[0].search_count == 1
+ finally:
+ collection.close()
+
+
+def test_auto_cuvs_selective_first_query_skips_gpu_build(monkeypatch):
+ runtimes = []
+
+ def make_runtime(_algorithm, metric, _build_params, _search_params):
+ runtime = MemoryAwareFakeCuVSRuntime(metric, free_memory_bytes=32)
+ runtimes.append(runtime)
+ return runtime
+
+ monkeypatch.setattr(cuvs_index, "_CuVSRuntime", make_runtime)
+ collection = get_or_create_local_collection(
+ meta_data={
+ "CollectionName": "auto_cuvs_selective_first",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ {"FieldName": "account_id", "FieldType": "string"},
+ ],
+ },
+ config={
+ "dense_search": {
+ "backend": "auto_cuvs",
+ "algorithm": "brute_force",
+ "filter_cache_size": 0,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ "auto_filter_native_threshold": 1,
+ }
+ },
+ )
+ try:
+ collection.create_index(
+ "default",
+ {
+ "IndexName": "default",
+ "VectorIndex": {"IndexType": "flat", "Distance": "cosine"},
+ "ScalarIndex": ["account_id"],
+ },
+ )
+ collection.upsert_data(
+ [
+ {
+ "id": "first",
+ "vector": [1.0, 0.0, 0.0, 0.0],
+ "account_id": "a",
+ },
+ {
+ "id": "second",
+ "vector": [0.0, 1.0, 0.0, 0.0],
+ "account_id": "b",
+ },
+ ]
+ )
+
+ result = collection.search_by_vector(
+ "default",
+ dense_vector=[1.0, 0.0, 0.0, 0.0],
+ limit=1,
+ filters={"op": "must", "field": "account_id", "conds": ["a"]},
+ )
+ assert [item.id for item in result.data] == ["first"]
+ assert runtimes[0].build_count == 0
+ assert runtimes[0].search_count == 0
+
+ result = collection.search_by_vector("default", dense_vector=[1.0, 0.0, 0.0, 0.0], limit=1)
+ assert [item.id for item in result.data] == ["first"]
+ assert runtimes[0].build_count == 1
+ assert runtimes[0].search_count == 1
+ finally:
+ collection.close()
+
+
+def test_auto_cuvs_keeps_native_when_runtime_is_unavailable(monkeypatch):
+ def unavailable_runtime(*_args, **_kwargs):
+ raise cuvs_index.CuVSUnavailableError("unavailable for test")
+
+ monkeypatch.setattr(cuvs_index, "_CuVSRuntime", unavailable_runtime)
+ collection = get_or_create_local_collection(
+ meta_data={
+ "CollectionName": "auto_cuvs_unavailable",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ ],
+ },
+ config={"dense_search": {"backend": "auto_cuvs"}},
+ )
+ try:
+ index = collection.create_index(
+ "default",
+ {
+ "IndexName": "default",
+ "VectorIndex": {"IndexType": "flat", "Distance": "cosine"},
+ },
+ )
+ assert index.dense_search is None
+
+ collection.upsert_data([{"id": "native", "vector": [1.0, 0.0, 0.0, 0.0]}])
+ result = collection.search_by_vector("default", dense_vector=[1.0, 0.0, 0.0, 0.0], limit=1)
+ assert [item.id for item in result.data] == ["native"]
+ finally:
+ collection.close()
diff --git a/tests/vectordb/test_cuvs_config.py b/tests/vectordb/test_cuvs_config.py
new file mode 100644
index 000000000..fbc10b095
--- /dev/null
+++ b/tests/vectordb/test_cuvs_config.py
@@ -0,0 +1,84 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+from pydantic import ValidationError
+
+from openviking.storage.vectordb_adapters.local_adapter import (
+ CuVSCollectionAdapter,
+ LocalCollectionAdapter,
+)
+from openviking_cli.utils.config.vectordb_config import CuVSConfig, VectorDBBackendConfig
+
+
+def test_cuvs_filter_cache_defaults_and_disable_value():
+ assert CuVSConfig().filter_cache_size == 16
+ assert CuVSConfig(filter_cache_size=0).filter_cache_size == 0
+
+
+def test_cuvs_filter_cache_rejects_negative_size():
+ with pytest.raises(ValidationError, match="filter_cache_size"):
+ CuVSConfig(filter_cache_size=-1)
+
+
+def test_cuvs_auto_mode_is_opt_in_and_validates_memory_guardrails():
+ config = CuVSConfig()
+ assert config.auto_enable is False
+ assert config.auto_memory_reserve_mb == 1024
+ assert config.auto_memory_safety_factor == 2.0
+ assert config.auto_filter_native_threshold == 2000
+ assert config.auto_path_filter_native_threshold == 200
+
+ with pytest.raises(ValidationError, match="auto_memory_reserve_mb"):
+ CuVSConfig(auto_memory_reserve_mb=-1)
+ with pytest.raises(ValidationError, match="auto_memory_safety_factor"):
+ CuVSConfig(auto_memory_safety_factor=0.5)
+ with pytest.raises(ValidationError, match="auto_filter_native_threshold"):
+ CuVSConfig(auto_filter_native_threshold=-1)
+ with pytest.raises(ValidationError, match="auto_path_filter_native_threshold"):
+ CuVSConfig(auto_path_filter_native_threshold=-1)
+
+
+def test_local_adapter_only_passes_auto_cuvs_config_when_enabled():
+ default_adapter = LocalCollectionAdapter.from_config(VectorDBBackendConfig(backend="local"))
+ assert default_adapter.mode == "local"
+ assert default_adapter._collection_config == {}
+
+ auto_adapter = LocalCollectionAdapter.from_config(
+ VectorDBBackendConfig(
+ backend="local",
+ cuvs={
+ "auto_enable": True,
+ "auto_memory_reserve_mb": 512,
+ "auto_memory_safety_factor": 1.5,
+ "auto_filter_native_threshold": 1000,
+ "auto_path_filter_native_threshold": 100,
+ },
+ )
+ )
+ dense_search = auto_adapter._collection_config["dense_search"]
+ assert auto_adapter.mode == "local"
+ assert dense_search["backend"] == "auto_cuvs"
+ assert dense_search["auto_enable"] is True
+ assert dense_search["auto_memory_reserve_mb"] == 512
+ assert dense_search["auto_memory_safety_factor"] == 1.5
+ assert dense_search["auto_filter_native_threshold"] == 1000
+ assert dense_search["auto_path_filter_native_threshold"] == 100
+
+
+def test_cuvs_adapter_preserves_native_int8_index_default():
+ native = LocalCollectionAdapter("context", "", "default")
+ cuvs = CuVSCollectionAdapter("context", "", "default", {})
+ arguments = {
+ "index_name": "default",
+ "distance": "cosine",
+ "use_sparse": False,
+ "sparse_weight": 0.0,
+ "scalar_index_fields": [],
+ }
+
+ native_meta = native.build_default_index_meta(**arguments)
+ cuvs_meta = cuvs.build_default_index_meta(**arguments)
+
+ assert native_meta["VectorIndex"]["Quant"] == "int8"
+ assert cuvs_meta["VectorIndex"]["Quant"] == "int8"
diff --git a/tests/vectordb/test_cuvs_index.py b/tests/vectordb/test_cuvs_index.py
new file mode 100644
index 000000000..0aa7dacfb
--- /dev/null
+++ b/tests/vectordb/test_cuvs_index.py
@@ -0,0 +1,578 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.storage.vectordb.index.cuvs_index import (
+ CuVSDenseIndex,
+ CuVSMemoryBudgetError,
+ CuVSNativeRouteError,
+ CuVSUnavailableError,
+ UnsupportedCuVSFilterError,
+ estimate_cuvs_memory,
+ matches_filter,
+)
+from openviking.storage.vectordb.store.data import CandidateData, DeltaRecord
+
+
+class FakeCuVSRuntime:
+ """CPU implementation of the tiny runtime boundary used by unit tests."""
+
+ def __init__(self, metric="inner_product"):
+ self.metric = metric
+ self.dataset = []
+ self.build_count = 0
+ self.prepare_filter_count = 0
+ self.closed = False
+ self.free_memory_bytes = 1 << 60
+ self.total_memory_bytes = 1 << 60
+ self.release_count = 0
+
+ def build(self, dataset):
+ self.dataset = [list(vector) for vector in dataset]
+ self.build_count += 1
+ return self.dataset
+
+ def search(self, index, query, limit, mask):
+ rows = []
+ for offset, vector in enumerate(index):
+ if mask is not None and not mask[offset]:
+ continue
+ if self.metric == "sqeuclidean":
+ distance = sum(
+ (left - right) ** 2 for left, right in zip(query, vector, strict=True)
+ )
+ sort_key = distance
+ else:
+ distance = sum(left * right for left, right in zip(query, vector, strict=True))
+ sort_key = -distance
+ rows.append((sort_key, offset, distance))
+ rows.sort()
+ selected = rows[:limit]
+ return [row[1] for row in selected], [row[2] for row in selected]
+
+ def prepare_filter(self, mask):
+ self.prepare_filter_count += 1
+ return tuple(mask)
+
+ def memory_info(self):
+ return self.free_memory_bytes, self.total_memory_bytes
+
+ def release_index(self):
+ self.dataset = []
+ self.release_count += 1
+
+ @staticmethod
+ def is_out_of_memory(_exc):
+ return False
+
+ def close(self):
+ self.closed = True
+
+
+def candidate(label, vector, **fields):
+ import json
+
+ return CandidateData(label=label, vector=vector, fields=json.dumps(fields))
+
+
+def delta(label, vector, **fields):
+ import json
+
+ return DeltaRecord(label=label, vector=vector, fields=json.dumps(fields))
+
+
+def test_cuvs_dense_search_handles_filter_upsert_delete_and_lazy_rebuild():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=True,
+ field_types={"account_id": "string", "uri": "path"},
+ config={"algorithm": "brute_force"},
+ runtime=runtime,
+ )
+ index.add_candidates(
+ [
+ candidate(10, [1.0, 0.0], account_id="a", uri="/docs/one"),
+ candidate(20, [0.8, 0.2], account_id="a", uri="/docs/deep/two"),
+ candidate(30, [0.0, 1.0], account_id="b", uri="/other/three"),
+ ]
+ )
+
+ labels, scores = index.search(
+ [10.0, 0.0],
+ 10,
+ {
+ "op": "and",
+ "conds": [
+ {"op": "must", "field": "account_id", "conds": ["a"]},
+ {"op": "must", "field": "uri", "conds": ["/docs"], "para": "-d=1"},
+ ],
+ },
+ )
+ assert labels == [10]
+ assert scores == [1.0]
+ assert runtime.build_count == 1
+
+ # Repeated reads reuse the GPU index; a mutation invalidates it exactly once.
+ assert index.search([1.0, 0.0], 1, None)[0] == [10]
+ assert runtime.build_count == 1
+ index.upsert([delta(30, [2.0, 0.0], account_id="a", uri="/docs/three")])
+ assert index.search([1.0, 0.0], 3, None)[0] == [10, 30, 20]
+ assert runtime.build_count == 2
+ index.delete([DeltaRecord(label=10)])
+ assert index.search([1.0, 0.0], 3, None)[0] == [30, 20]
+ assert runtime.build_count == 3
+
+
+def test_cuvs_l2_scores_match_openviking_score_convention():
+ runtime = FakeCuVSRuntime(metric="sqeuclidean")
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="l2",
+ normalize_vectors=False,
+ field_types={},
+ config={},
+ runtime=runtime,
+ )
+ index.add_candidates([candidate(1, [0.0, 0.0]), candidate(2, [2.0, 0.0])])
+
+ labels, scores = index.search([1.0, 0.0], 2, None)
+ assert labels == [1, 2]
+ assert scores == [0.0, 0.0] # OpenViking exposes 1 - squared-L2.
+
+
+def test_cuvs_memory_estimate_accounts_for_fp32_graphs_and_filter_cache():
+ estimate = estimate_cuvs_memory(
+ vector_count=1_000_000,
+ dimension=768,
+ algorithm="cagra",
+ build_params={"graph_degree": 64, "intermediate_graph_degree": 128},
+ filter_cache_size=16,
+ safety_factor=2.0,
+ )
+
+ assert estimate.vector_bytes == 1_000_000 * 768 * 4
+ assert estimate.graph_bytes == 1_000_000 * 64 * 4
+ assert estimate.build_graph_bytes == 1_000_000 * 128 * 4
+ assert estimate.filter_cache_bytes == ((1_000_000 + 31) // 32) * 4 * 16
+ assert estimate.estimated_peak_bytes == 2 * (
+ estimate.vector_bytes
+ + estimate.graph_bytes
+ + estimate.build_graph_bytes
+ + estimate.filter_cache_bytes
+ )
+
+
+def test_auto_cuvs_retries_after_gpu_memory_becomes_available():
+ runtime = FakeCuVSRuntime()
+ runtime.free_memory_bytes = 15
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={},
+ config={
+ "algorithm": "brute_force",
+ "filter_cache_size": 0,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ },
+ runtime=runtime,
+ auto_memory=True,
+ )
+ index.add_candidates([candidate(1, [1.0, 0.0]), candidate(2, [0.0, 1.0])])
+
+ with pytest.raises(CuVSMemoryBudgetError, match="estimated GPU peak"):
+ index.search([1.0, 0.0], 1, None)
+ assert runtime.build_count == 0
+
+ runtime.free_memory_bytes = 16
+ assert index.search([1.0, 0.0], 1, None)[0] == [1]
+ assert runtime.build_count == 1
+ assert runtime.release_count == 2
+
+
+def test_auto_cuvs_converts_gpu_allocation_failure_to_native_fallback_signal():
+ class OutOfMemoryRuntime(FakeCuVSRuntime):
+ def build(self, _dataset):
+ raise RuntimeError("out of memory")
+
+ @staticmethod
+ def is_out_of_memory(_exc):
+ return True
+
+ runtime = OutOfMemoryRuntime()
+ index = CuVSDenseIndex(
+ dimension=4,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={},
+ config={
+ "filter_cache_size": 0,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ },
+ runtime=runtime,
+ auto_memory=True,
+ )
+ index.add_candidates([candidate(1, [1.0, 0.0, 0.0, 0.0])])
+
+ with pytest.raises(CuVSMemoryBudgetError, match="allocation failure"):
+ index.search([1.0, 0.0, 0.0, 0.0], 1, None)
+ assert runtime.release_count == 2
+
+
+def test_filter_cache_reuses_prepared_mask_and_invalidates_on_mutation():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"account_id": "string"},
+ config={"filter_cache_size": 2},
+ runtime=runtime,
+ )
+ index.add_candidates(
+ [
+ candidate(1, [1.0, 0.0], account_id="a"),
+ candidate(2, [0.0, 1.0], account_id="b"),
+ ]
+ )
+ filter_a = {"op": "must", "field": "account_id", "conds": ["a"]}
+
+ assert index.search([1.0, 0.0], 1, filter_a)[0] == [1]
+ assert index.search([1.0, 0.0], 1, filter_a)[0] == [1]
+ assert runtime.prepare_filter_count == 1
+
+ index.upsert([delta(2, [0.0, 1.0], account_id="a")])
+ assert index.search([0.0, 1.0], 1, filter_a)[0] == [2]
+ assert runtime.prepare_filter_count == 2
+
+ index.delete([DeltaRecord(label=1)])
+ assert index.search([1.0, 0.0], 2, filter_a)[0] == [2]
+ assert runtime.prepare_filter_count == 3
+
+
+def test_native_filter_resolver_projects_bitset_in_cuvs_row_order():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"account_id": "string"},
+ config={"filter_cache_size": 2},
+ runtime=runtime,
+ )
+ index.add_candidates(
+ [
+ candidate(30, [0.0, 1.0], account_id="b"),
+ candidate(10, [1.0, 0.0], account_id="a"),
+ candidate(20, [0.5, 0.5], account_id="a"),
+ ]
+ )
+ calls = []
+
+ def register(ordered_labels):
+ calls.append(("register", list(ordered_labels)))
+
+ def resolve(filters):
+ calls.append(("resolve", filters))
+ # Rows 1 and 2 are eligible in the cuVS dataset order above.
+ return [0b110], 2
+
+ filter_a = {"op": "must", "field": "account_id", "conds": ["a"]}
+ assert index.search([1.0, 0.0], 3, filter_a, resolve, register)[0] == [10, 20]
+ assert index.search([1.0, 0.0], 3, filter_a, resolve, register)[0] == [10, 20]
+ assert calls == [("register", [30, 10, 20]), ("resolve", filter_a)]
+ # Native packed words bypass the Python predicate/mask packer.
+ assert runtime.prepare_filter_count == 0
+
+
+def test_auto_mode_caches_native_route_for_selective_filter():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"account_id": "string"},
+ config={
+ "auto_filter_native_threshold": 1,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ },
+ runtime=runtime,
+ auto_memory=True,
+ )
+ index.add_candidates(
+ [
+ candidate(10, [1.0, 0.0], account_id="a"),
+ candidate(20, [0.0, 1.0], account_id="b"),
+ ]
+ )
+ calls = []
+
+ def register(ordered_labels):
+ calls.append(("register", list(ordered_labels)))
+
+ def resolve(filters):
+ calls.append(("resolve", filters))
+ return [0b01], 1
+
+ filter_a = {"op": "must", "field": "account_id", "conds": ["a"]}
+ for _ in range(2):
+ with pytest.raises(CuVSNativeRouteError, match="1 candidates"):
+ index.search([1.0, 0.0], 1, filter_a, resolve, register)
+
+ assert calls == [("register", [10, 20]), ("resolve", filter_a)]
+ # Selectivity is decided before GPU admission/build, even while dirty.
+ assert runtime.build_count == 0
+ assert runtime.release_count == 0
+ assert runtime.prepare_filter_count == 0
+
+
+def test_auto_mode_selective_filter_skips_rebuild_after_mutation():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"account_id": "string"},
+ config={
+ "auto_filter_native_threshold": 1,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ },
+ runtime=runtime,
+ auto_memory=True,
+ )
+ index.add_candidates(
+ [
+ candidate(10, [1.0, 0.0], account_id="a"),
+ candidate(20, [0.0, 1.0], account_id="b"),
+ ]
+ )
+ registered_layouts = []
+
+ def register(ordered_labels):
+ registered_layouts.append(list(ordered_labels))
+
+ assert index.search([1.0, 0.0], 1, None, None, register)[0] == [10]
+ assert runtime.build_count == 1
+
+ index.upsert([delta(20, [2.0, 0.0], account_id="b")])
+
+ def resolve(_filters):
+ return [0b10], 1
+
+ filter_b = {"op": "must", "field": "account_id", "conds": ["b"]}
+ with pytest.raises(CuVSNativeRouteError, match="1 candidates"):
+ index.search([1.0, 0.0], 1, filter_b, resolve, register)
+
+ # The stale GPU snapshot is not rebuilt for a query routed to native.
+ assert runtime.build_count == 1
+ assert registered_layouts == [[10, 20], [10, 20]]
+
+ # The next GPU-routed query still observes dirty state and rebuilds once.
+ assert index.search([1.0, 0.0], 1, None, None, register)[0] == [20]
+ assert runtime.build_count == 2
+
+
+def test_auto_mode_empty_filter_result_skips_initial_gpu_build():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"account_id": "string"},
+ config={
+ "auto_filter_native_threshold": 1,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ },
+ runtime=runtime,
+ auto_memory=True,
+ )
+ index.add_candidates([candidate(10, [1.0, 0.0], account_id="a")])
+
+ assert index.search(
+ [1.0, 0.0],
+ 1,
+ {"op": "must", "field": "account_id", "conds": ["missing"]},
+ lambda _filters: ([0], 0),
+ lambda _labels: None,
+ ) == ([], [])
+ assert runtime.build_count == 0
+ assert runtime.release_count == 0
+
+
+def test_auto_mode_wide_filter_reuses_preflight_bitmap_after_build():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"account_id": "string"},
+ config={
+ "auto_filter_native_threshold": 1,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ },
+ runtime=runtime,
+ auto_memory=True,
+ )
+ index.add_candidates(
+ [
+ candidate(10, [1.0, 0.0], account_id="a"),
+ candidate(20, [0.0, 1.0], account_id="a"),
+ ]
+ )
+ resolve_count = 0
+
+ def resolve(_filters):
+ nonlocal resolve_count
+ resolve_count += 1
+ return [0b11], 2
+
+ labels, _ = index.search(
+ [1.0, 0.0],
+ 2,
+ {"op": "must", "field": "account_id", "conds": ["a"]},
+ resolve,
+ lambda _labels: None,
+ )
+ assert labels == [10, 20]
+ assert resolve_count == 1
+ assert runtime.build_count == 1
+
+
+def test_auto_mode_uses_lower_native_threshold_for_path_filters():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"uri": "path"},
+ config={
+ "auto_filter_native_threshold": 2,
+ "auto_path_filter_native_threshold": 0,
+ "auto_memory_reserve_mb": 0,
+ "auto_memory_safety_factor": 1.0,
+ },
+ runtime=runtime,
+ auto_memory=True,
+ )
+ index.add_candidates(
+ [
+ candidate(10, [1.0, 0.0], uri="/docs/one"),
+ candidate(20, [0.0, 1.0], uri="/other/two"),
+ ]
+ )
+
+ def resolve(_filters):
+ return [0b01], 1
+
+ path_filter = {
+ "op": "must",
+ "field": "uri",
+ "conds": ["/docs"],
+ "para": "-d=-1",
+ }
+ assert index.search([1.0, 0.0], 1, path_filter, resolve, lambda _labels: None)[0] == [10]
+
+
+def test_filter_cache_uses_lru_bound():
+ runtime = FakeCuVSRuntime()
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={"account_id": "string"},
+ config={"filter_cache_size": 1},
+ runtime=runtime,
+ )
+ index.add_candidates(
+ [
+ candidate(1, [1.0, 0.0], account_id="a"),
+ candidate(2, [0.0, 1.0], account_id="b"),
+ ]
+ )
+ filter_a = {"op": "must", "field": "account_id", "conds": ["a"]}
+ filter_b = {"op": "must", "field": "account_id", "conds": ["b"]}
+
+ index.search([1.0, 0.0], 1, filter_a)
+ index.search([0.0, 1.0], 1, filter_b)
+ index.search([1.0, 0.0], 1, filter_a)
+
+ assert runtime.prepare_filter_count == 3
+
+
+def test_filter_evaluator_covers_lists_ranges_contains_and_path_depth():
+ fields = {
+ "tags": ["a", "b"],
+ "count": 7,
+ "title": "cuVS integration",
+ "uri": "docs/deep/item",
+ }
+ field_types = {
+ "tags": "list<string>",
+ "count": "int64",
+ "title": "string",
+ "uri": "path",
+ }
+ node = {
+ "op": "and",
+ "conds": [
+ {"op": "must", "field": "tags", "conds": ["b"]},
+ {"op": "range", "field": "count", "gte": 5, "lt": 10},
+ {"op": "contains", "field": "title", "substring": "cuVS"},
+ {"op": "must", "field": "uri", "conds": ["/docs"], "para": "-d=2"},
+ ],
+ }
+ assert matches_filter(fields, node, field_types)
+ node["conds"][-1]["para"] = "-d=1"
+ assert not matches_filter(fields, node, field_types)
+
+
+def test_filter_evaluator_rejects_type_sensitive_filters_for_native_fallback():
+ with pytest.raises(UnsupportedCuVSFilterError):
+ matches_filter(
+ {"created_at": "2026-07-02T00:00:00Z"},
+ {"op": "range", "field": "created_at", "gte": "2026-07-01T00:00:00Z"},
+ {"created_at": "date_time"},
+ )
+
+
+def test_dimension_mismatch_is_reported_before_runtime_call():
+ index = CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={},
+ config={},
+ runtime=FakeCuVSRuntime(),
+ )
+ with pytest.raises(ValueError, match="dimension mismatch"):
+ index.add_candidates([candidate(1, [1.0, 2.0, 3.0])])
+
+
+def test_missing_cuvs_runtime_has_actionable_error(monkeypatch):
+ import builtins
+
+ real_import = builtins.__import__
+
+ def import_without_cupy(name, *args, **kwargs):
+ if name == "cupy":
+ raise ImportError("blocked for test")
+ return real_import(name, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "__import__", import_without_cupy)
+ with pytest.raises(CuVSUnavailableError, match="cuvs-cu12 or cuvs-cu13"):
+ CuVSDenseIndex(
+ dimension=2,
+ distance="ip",
+ normalize_vectors=False,
+ field_types={},
+ config={},
+ )