Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 40 additions & 10 deletions core/src/autotune.rs
Original file line number Diff line number Diff line change
Expand Up @@ -148,14 +148,22 @@ pub fn infer_ivf_nprobe(
top_k: usize,
matching_count: Option<usize>,
) -> io::Result<usize> {
infer_ivf_nprobe_with_filter_expansion_cap(nlist, vector_count, top_k, matching_count, None)
infer_ivf_nprobe_with_limits(
nlist,
vector_count,
top_k,
matching_count,
DEFAULT_IVF_MIN_NPROBE,
None,
)
}

pub(crate) fn infer_ivf_nprobe_with_filter_expansion_cap(
pub(crate) fn infer_ivf_nprobe_with_limits(
nlist: usize,
vector_count: usize,
top_k: usize,
matching_count: Option<usize>,
min_nprobe: usize,
max_initial_filter_expansion_factor: Option<usize>,
) -> io::Result<usize> {
if nlist == 0 {
Expand All @@ -173,7 +181,7 @@ pub(crate) fn infer_ivf_nprobe_with_filter_expansion_cap(
.checked_mul(DEFAULT_IVF_CANDIDATES_PER_RESULT)
.ok_or_else(|| invalid_input("automatic nprobe candidate count overflows usize"))?;
let candidate_lists = candidate_rows.div_ceil(average_list_rows);
let mut nprobe = DEFAULT_IVF_MIN_NPROBE
let mut nprobe = min_nprobe
.max(nlist.div_ceil(DEFAULT_IVF_LIST_FRACTION))
.max(candidate_lists)
.min(nlist);
Expand Down Expand Up @@ -433,33 +441,55 @@ mod tests {
#[test]
fn automatic_nprobe_caps_initial_filter_expansion() {
assert_eq!(
infer_ivf_nprobe_with_filter_expansion_cap(256, 2_560_000, 3, Some(256_000), Some(4))
.unwrap(),
infer_ivf_nprobe_with_limits(
256,
2_560_000,
3,
Some(256_000),
DEFAULT_IVF_MIN_NPROBE,
Some(4)
)
.unwrap(),
64
);
}

#[test]
fn automatic_nprobe_filter_expansion_cap_preserves_bounds() {
assert_eq!(
infer_ivf_nprobe_with_filter_expansion_cap(256, 2_560_000, 3, Some(256_000), Some(1))
.unwrap(),
infer_ivf_nprobe_with_limits(
256,
2_560_000,
3,
Some(256_000),
DEFAULT_IVF_MIN_NPROBE,
Some(1)
)
.unwrap(),
16
);
assert_eq!(
infer_ivf_nprobe(256, 2_560_000, 3, Some(256_000)).unwrap(),
160
);
assert_eq!(
infer_ivf_nprobe_with_filter_expansion_cap(256, 2_560_000, 3, Some(5_120_000), Some(4))
.unwrap(),
infer_ivf_nprobe_with_limits(
256,
2_560_000,
3,
Some(5_120_000),
DEFAULT_IVF_MIN_NPROBE,
Some(4)
)
.unwrap(),
16
);
assert!(infer_ivf_nprobe_with_filter_expansion_cap(
assert!(infer_ivf_nprobe_with_limits(
256,
2_560_000,
3,
Some(256_000),
DEFAULT_IVF_MIN_NPROBE,
Some(0)
)
.is_err());
Expand Down
21 changes: 19 additions & 2 deletions core/src/index.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@

use crate::autotune::{
default_training_vector_count, diskann_build_preset, infer_diskann_l_search, infer_ivf_nlist,
infer_ivf_nprobe_with_filter_expansion_cap, infer_rq_bits, DiskAnnBuildPreset, TuningObjective,
infer_ivf_nprobe_with_limits, infer_rq_bits, DiskAnnBuildPreset, TuningObjective,
DEFAULT_IVF_MIN_NPROBE,
};
use crate::diskann::{
diskann_training_sample_limit, validate_diskann_format_configuration,
Expand Down Expand Up @@ -1243,13 +1244,29 @@ impl VectorSearchParams {
nlist: usize,
vector_count: usize,
matching_count: Option<usize>,
) -> io::Result<usize> {
self.resolve_ivf_nprobe_with_min(
nlist,
vector_count,
matching_count,
DEFAULT_IVF_MIN_NPROBE,
)
}

fn resolve_ivf_nprobe_with_min(
self,
nlist: usize,
vector_count: usize,
matching_count: Option<usize>,
min_nprobe: usize,
) -> io::Result<usize> {
match self.search_width {
SearchWidth::Auto => infer_ivf_nprobe_with_filter_expansion_cap(
SearchWidth::Auto => infer_ivf_nprobe_with_limits(
nlist,
vector_count,
self.top_k,
matching_count,
min_nprobe,
self.max_initial_filter_expansion_factor,
),
SearchWidth::IvfNProbe if self.width > 0 => Ok(self.width.min(nlist)),
Expand Down
52 changes: 50 additions & 2 deletions core/src/index/router.rs
Original file line number Diff line number Diff line change
Expand Up @@ -106,15 +106,21 @@ impl CentroidRouter {
})
}

/// Resolve outer routing with the same automatic width policy as ordinary IVF search.
/// Resolve the outer shard count, allowing small routers to prune whole files.
pub fn resolve_nprobe(
&self,
params: VectorSearchParams,
total_vectors: usize,
matching_vectors: Option<usize>,
) -> io::Result<usize> {
params.validate()?;
params.resolve_ivf_nprobe(self.nlist(), total_vectors, matching_vectors)
let nlist = self.nlist();
let min_nprobe = match nlist {
4 => 3,
8 => 4,
_ => DEFAULT_IVF_MIN_NPROBE,
};
params.resolve_ivf_nprobe_with_min(nlist, total_vectors, matching_vectors, min_nprobe)
}

fn routing_vector<'a>(&self, query: &'a [f32]) -> io::Result<Cow<'a, [f32]>> {
Expand Down Expand Up @@ -183,6 +189,48 @@ impl CentroidRouter {
mod tests {
use super::*;

#[test]
fn outer_routing_uses_small_floors_before_candidate_and_filter_expansion() {
let auto = VectorSearchParams::automatic(10);
for (nlist, expected) in [
(3, 3),
(4, 3),
(5, 5),
(7, 7),
(8, 4),
(9, 8),
(16, 8),
(256, 16),
] {
let router = CentroidRouter::from_centers(1, MetricType::L2, vec![0.; nlist]).unwrap();
assert_eq!(router.resolve_nprobe(auto, 25_000, None).unwrap(), expected);
}
for (nlist, filtered, large_k) in [(4, 4, 4), (8, 5, 7)] {
let router = CentroidRouter::from_centers(1, MetricType::L2, vec![0.; nlist]).unwrap();
assert_eq!(
router.resolve_nprobe(auto, 25_000, Some(20_000)).unwrap(),
filtered
);
assert_eq!(
router
.resolve_nprobe(VectorSearchParams::automatic(5_000), 25_000, None)
.unwrap(),
large_k
);
assert_eq!(
router.resolve_nprobe(auto, 25_000, Some(500)).unwrap(),
nlist
);
assert_eq!(
router
.resolve_nprobe(VectorSearchParams::new(10, 1), 25_000, Some(500))
.unwrap(),
1
);
assert_eq!(auto.resolve_ivf_nprobe(nlist, 25_000, None).unwrap(), nlist);
}
}

#[test]
fn router_payload_is_independent_of_shard_type_and_rejects_corruption() {
// Frozen routing format: two 2D cosine centers, including a tie on [1, 1].
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,11 @@ public synchronized int[] findNearestCentroids(float[] query, int nprobe) {
return VectorIndexNative.findNearestCentroids(requireOpen(), query, nprobe);
}

/** A matchingVectors value of -1 means no row-ID filter. */
/**
* Resolves the initial number of shards to probe. Automatic routing starts at three shards for
* four centers and four shards for eight centers. Top-K and filter selectivity can increase
* the width. Pass -1 for matchingVectors when there is no row-ID filter.
*/
public synchronized int resolveNprobe(
VectorSearchParams params, long totalVectors, long matchingVectors) {
if (params == null) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,9 @@ static void run() {
float[] query = Arrays.copyOf(rows, 4);
int selected = router.assignCentroid(query);
check(router.findNearestCentroids(query, 1)[0] == selected, "routing consistency");
VectorSearchParams automatic = VectorSearchParams.automatic(10);
check(router.resolveNprobe(automatic, 256, -1) == 3, "automatic outer width");
check(router.resolveNprobe(automatic, 256, 128) == 4, "filtered outer width");
check(router.resolveNprobe(VectorSearchParams.ivf(1, 2), 256, -1) == 2, "outer width");
long[] ids = new long[256];
float[] vectors = new float[rows.length];
Expand Down
Loading