Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat: add cuVS vector search backend (#2974)
Yuanqing ZHAO39c778c953f5
diff --git a/benchmark/cuvs/PRELIMINARY_RESULTS.md b/benchmark/cuvs/PRELIMINARY_RESULTS.mdnew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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/Dockerfilenew file mode 100644index 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.mdnew file mode 100644index 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.shnew file mode 100644index 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.shnew file mode 100755index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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_mgrself.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):passif 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 indexdiff --git a/openviking/storage/vectordb/engine/_python_api.py b/openviking/storage/vectordb/engine/_python_api.pyindex 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.pynew file mode 100644index 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.pyindex a4493db23..7804f136f 100644--- a/openviking/storage/vectordb/index/local_index.py+++ b/openviking/storage/vectordb/index/local_index.py@@ -4,11 +4,19 @@ import jsonimport mathimport osimport shutil+import threadingimport timefrom pathlib import Pathfrom typing import Any, Dict, List, Optional, Tuple, Unionimport 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 IIndexfrom openviking.storage.vectordb.store.data import CandidateData, DeltaRecordfrom 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 = metaself.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 = Nonedef 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_datadef close(self):+ if self.dense_search:+ self.dense_search.close()+ self.dense_search = Nonereturn Nonedef drop(self):+ if self.dense_search:+ self.dense_search.close()+ self.dense_search = Noneif 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_intindex_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 layerdef _create_new_index(diff --git a/openviking/storage/vectordb_adapters/__init__.py b/openviking/storage/vectordb_adapters/__init__.pyindex 1c75683f4..bb33a3a36 100644--- a/openviking/storage/vectordb_adapters/__init__.py+++ b/openviking/storage/vectordb_adapters/__init__.py@@ -5,7 +5,7 @@from .base import CollectionAdapterfrom .factory import create_collection_adapterfrom .http_adapter import HttpCollectionAdapter-from .local_adapter import LocalCollectionAdapter+from .local_adapter import CuVSCollectionAdapter, LocalCollectionAdapterfrom .opengauss_adapter import OpenGaussCollectionAdapterfrom .qdrant_adapter import QdrantCollectionAdapterfrom .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.pyindex f35d1a78f..24e570e6c 100644--- a/openviking/storage/vectordb_adapters/factory.py+++ b/openviking/storage/vectordb_adapters/factory.py@@ -8,7 +8,7 @@ import importlibfrom .base import CollectionAdapterfrom .http_adapter import HttpCollectionAdapter-from .local_adapter import LocalCollectionAdapter+from .local_adapter import CuVSCollectionAdapter, LocalCollectionAdapterfrom .opengauss_adapter import OpenGaussCollectionAdapterfrom .qdrant_adapter import QdrantCollectionAdapterfrom .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.pyindex 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 annotationsimport osfrom pathlib import Path-from typing import Any, Dict, List+from typing import Any, Dict, List, Optionalfrom openviking.storage.vectordb.collection.collection import Collectionfrom 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 {})@classmethoddef 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):returnmeta_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.pyindex 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, Optionalfrom 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 validationif "." 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"}:passelif self.backend == "http":diff --git a/src/abi3_engine_backend.cpp b/src/abi3_engine_backend.cppindex 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.hindex 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.cppindex 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.hindex 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 vectordbdiff --git a/src/index/index_engine.cpp b/src/index/index_engine.cppindex 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 vectordbdiff --git a/src/index/index_engine.h b/src/index/index_engine.hindex 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 vectordbdiff --git a/src/index/index_manager.h b/src/index/index_manager.hindex 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 vectordbdiff --git a/tests/benchmark/test_cuvs_collection_benchmark.py b/tests/benchmark/test_cuvs_collection_benchmark.pynew file mode 100644index 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"] == 4diff --git a/tests/benchmark/test_cuvs_collection_summary.py b/tests/benchmark/test_cuvs_collection_summary.pynew file mode 100644index 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.pynew file mode 100644index 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"] > 0diff --git a/tests/benchmark/test_cuvs_index_summary.py b/tests/benchmark/test_cuvs_index_summary.pynew file mode 100644index 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.pynew file mode 100644index 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"]) == 12diff --git a/tests/benchmark/test_cuvs_service_summary.py b/tests/benchmark/test_cuvs_service_summary.pynew file mode 100644index 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.txtindex 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_commontest_common.cpp${CMAKE_SOURCE_DIR}/../../src/common/log_utils.cpp@@ -25,10 +32,6 @@ add_executable(test_index_enginetest_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 PRIVATEengine_implThreads::Threadsdiff --git a/tests/engine/test_index_engine.cpp b/tests/engine/test_index_engine.cppindex 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 Datastd::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.pyindex 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 == 123assert state.element_count == 7diff --git a/tests/vectordb/test_cuvs_collection.py b/tests/vectordb/test_cuvs_collection.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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={},+ )