π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
vecdb: prune reverse links to a slack below the cap outside duplicate neighborhoods
laurenspriem559d42a96c62
diff --git a/rust/crates/ml/src/vecdb/graph.rs b/rust/crates/ml/src/vecdb/graph.rsindex 5e9d6ce52d..de57bccf48 100644--- a/rust/crates/ml/src/vecdb/graph.rs+++ b/rust/crates/ml/src/vecdb/graph.rs@@ -10,6 +10,7 @@ const LEVEL_ZERO_NEIGHBOR_CAP: usize = 2 * M;const UPPER_LEVEL_NEIGHBOR_CAP: usize = M;const EF_CONSTRUCTION: usize = 96;const SELECTION_WINDOW_FACTOR: usize = 2;+const REVERSE_PRUNE_SLACK: usize = 4;const EF_SEARCH_UPPER: usize = 1;const EF_SEARCH_FLOOR_SMALL: usize = 72;const EF_SEARCH_FLOOR_LARGE: usize = 56;@@ -43,6 +44,17 @@ fn neighbor_cap(level: usize) -> usize {}}+fn reverse_prune_target(cap: usize, sorted_by_distance: &[Scored]) -> usize {+ let holds_equal_distances = sorted_by_distance+ .windows(2)+ .any(|pair| pair[0].distance == pair[1].distance);+ if holds_equal_distances {+ cap+ } else {+ cap.saturating_sub(REVERSE_PRUNE_SLACK).max(1)+ }+}+fn select_neighbors(arena: &VectorArena,candidates: &[Scored],@@ -543,7 +555,8 @@ impl Graph {}scored[..count].sort_unstable();let mut kept = [0u32; LEVEL_ZERO_NEIGHBOR_CAP];- let kept_count = select_neighbors(arena, &scored[..count], cap, &mut kept);+ let target = reverse_prune_target(cap, &scored[..count]);+ let kept_count = select_neighbors(arena, &scored[..count], target, &mut kept);self.write_level_list(slot, level, &kept[..kept_count]);}@@ -999,9 +1012,9 @@ mod tests {use std::f32::consts::FRAC_1_SQRT_2;use std::sync::LazyLock;- use super::super::StorageKind;use super::super::arena::UpsertOutcome;use super::super::test_support::{assert_identical_graphs, stale_downward_edge_exists};+ use super::super::{DistanceMetric, StorageKind};use super::*;const FIXTURE_DIMS: usize = 16;@@ -1141,17 +1154,84 @@ mod tests {}const DUPLICATE_GROUP_SEED: u64 = 0x1DEA_0000;+ const PEAKY_GROUP_SEED: u64 = 0x9EA4_0000;+ const PEAKY_TAIL: f32 = 0.04;+ const BACKGROUND_SEED: u64 = 0x8AC0_0000;+ const JITTER_SEED: u64 = 0x71E7_0000;fn build_duplicate_groups(groups: usize, per_group: usize) -> (VectorArena, Graph) {- let mut arena = VectorArena::new(16).unwrap();+ build_duplicate_groups_with(+ 16,+ StorageKind::F32,+ DistanceMetric::InnerProduct,+ groups,+ per_group,+ )+ }++ fn build_duplicate_groups_with(+ dims: usize,+ storage: StorageKind,+ metric: DistanceMetric,+ groups: usize,+ per_group: usize,+ ) -> (VectorArena, Graph) {+ build_groups(dims, storage, metric, groups, per_group, |group, _| {+ group_center(group, dims)+ })+ }++ fn build_groups(+ dims: usize,+ storage: StorageKind,+ metric: DistanceMetric,+ groups: usize,+ per_group: usize,+ member: impl Fn(usize, usize) -> Vec<f32>,+ ) -> (VectorArena, Graph) {+ let mut arena = VectorArena::with_metric(dims, storage, metric).unwrap();for index in 0..groups * per_group {- let vector = seeded_unit_vector(DUPLICATE_GROUP_SEED + (index / per_group) as u64, 16);+ let vector = member(index / per_group, index % per_group);arena.upsert(&format!("key-{index}"), &vector).unwrap();}let graph = Graph::rebuild(&arena);(arena, graph)}+ fn group_center(group: usize, dims: usize) -> Vec<f32> {+ seeded_unit_vector(DUPLICATE_GROUP_SEED + group as u64, dims)+ }++ fn scaled(values: &[f32], factor: f32) -> Vec<f32> {+ values.iter().map(|value| value * factor).collect()+ }++ fn peaky_unit_vector(group: usize, dims: usize) -> Vec<f32> {+ let mut state = PEAKY_GROUP_SEED + group as u64;+ let mut values: Vec<f32> = (0..dims)+ .map(|_| {+ if splitmix64(&mut state).is_multiple_of(2) {+ PEAKY_TAIL+ } else {+ -PEAKY_TAIL+ }+ })+ .collect();+ values[group % dims] = 1.0;+ normalized(values)+ }++ fn jittered(center: &[f32], seed: u64, spread: f32) -> Vec<f32> {+ let noise = seeded_unit_vector(seed, center.len());+ normalized(+ center+ .iter()+ .zip(&noise)+ .map(|(center, noise)| center + spread * noise)+ .collect(),+ )+ }+fn group_of(arena: &VectorArena, key: &str, per_group: usize) -> usize {arena.slot_of_key(key).unwrap() as usize / per_group}@@ -1173,6 +1253,18 @@ mod tests {}}+ fn assert_leading_group_members(+ arena: &VectorArena,+ found: &[Match],+ count: usize,+ group: usize,+ per_group: usize,+ ) {+ for hit in &found[..count] {+ assert_eq!(group_of(arena, &hit.key, per_group), group, "{}", hit.key);+ }+ }+fn params(limit: Option<usize>, max_distance: Option<f32>, exact: bool) -> SearchParams {SearchParams {limit,@@ -1549,6 +1641,238 @@ mod tests {assert_leading_group(&arena, &found, 100, nearest, 400);}+ #[test]+ fn duplicate_groups_near_the_neighbor_cap_stay_whole_at_production_dims() {+ for storage in [StorageKind::F32, StorageKind::I8] {+ for metric in [DistanceMetric::Cosine, DistanceMetric::InnerProduct] {+ for (groups, per_group, limit) in [(4, 40, 60), (8, 40, 60), (4, 80, 100)] {+ let (arena, graph) =+ build_duplicate_groups_with(512, storage, metric, groups, per_group);+ let query = arena.pack_query(&group_center(0, 512)).unwrap();+ let found = search(+ &graph,+ &arena,+ &query,+ ¶ms(Some(limit), None, false),+ None,+ );+ assert_eq!(found.len(), limit);+ assert_sorted(&found);+ assert_leading_group(&arena, &found, per_group, 0, per_group);+ }+ }+ }+ }++ #[test]+ fn duplicate_groups_of_peaky_vectors_stay_whole_in_int8() {+ for metric in [DistanceMetric::Cosine, DistanceMetric::InnerProduct] {+ for (groups, per_group, limit) in [(4, 40, 60), (8, 40, 60), (4, 80, 10), (4, 80, 80)] {+ let (arena, graph) = build_groups(+ 512,+ StorageKind::I8,+ metric,+ groups,+ per_group,+ |group, _| peaky_unit_vector(group, 512),+ );+ let query = arena.pack_query(&peaky_unit_vector(0, 512)).unwrap();+ let found = search(+ &graph,+ &arena,+ &query,+ ¶ms(Some(limit), None, false),+ None,+ );+ assert_eq!(found.len(), limit);+ assert_sorted(&found);+ assert_leading_group(&arena, &found, per_group.min(limit), 0, per_group);+ }+ }+ }++ #[test]+ fn duplicate_groups_stored_below_unit_norm_stay_whole() {+ for storage in [StorageKind::F32, StorageKind::I8] {+ for (groups, per_group, limit) in [(4, 40, 60), (8, 40, 60), (4, 80, 100)] {+ let (arena, graph) = build_groups(+ 512,+ storage,+ DistanceMetric::InnerProduct,+ groups,+ per_group,+ |group, _| scaled(&group_center(group, 512), 0.5),+ );+ let query = arena+ .pack_query(&scaled(&group_center(0, 512), 0.5))+ .unwrap();+ let found = search(+ &graph,+ &arena,+ &query,+ ¶ms(Some(limit), None, false),+ None,+ );+ assert_eq!(found.len(), limit);+ assert_sorted(&found);+ assert_leading_group(&arena, &found, per_group, 0, per_group);+ }+ }+ }++ #[test]+ fn a_duplicate_burst_at_the_neighbor_cap_survives_background_and_churn() {+ const BURST: usize = LEVEL_ZERO_NEIGHBOR_CAP;+ const BACKGROUND: usize = 2000;+ for metric in [DistanceMetric::Cosine, DistanceMetric::InnerProduct] {+ let duplicate = group_center(0, 512);+ let mut arena = VectorArena::with_metric(512, StorageKind::I8, metric).unwrap();+ let mut graph = Graph::new();+ for index in 0..BACKGROUND {+ apply_upsert(+ &mut arena,+ &mut graph,+ &format!("background-{index}"),+ &seeded_unit_vector(BACKGROUND_SEED + index as u64, 512),+ );+ }+ for index in 0..BURST {+ apply_upsert(+ &mut arena,+ &mut graph,+ &format!("duplicate-{index}"),+ &duplicate,+ );+ }+ let query = arena.pack_query(&duplicate).unwrap();+ assert_whole_burst(&graph, &arena, &query, BURST);+ for index in (0..BURST).step_by(2) {+ let key = format!("duplicate-{index}");+ assert!(arena.remove(&key).is_some());+ apply_upsert(&mut arena, &mut graph, &key, &duplicate);+ }+ assert_whole_burst(&graph, &arena, &query, BURST);+ }+ }++ fn assert_whole_burst(graph: &Graph, arena: &VectorArena, query: &PackedQuery, burst: usize) {+ let found = search(graph, arena, query, ¶ms(Some(burst), None, false), None);+ let members = found+ .iter()+ .filter(|hit| hit.key.starts_with("duplicate-"))+ .count();+ assert_eq!(members, burst, "{members} of {burst} burst members");+ }++ #[test]+ fn link_back_fills_to_the_cap_only_beside_equal_distances() {+ let cap = LEVEL_ZERO_NEIGHBOR_CAP;+ for (twins, expected) in [(false, cap - REVERSE_PRUNE_SLACK), (true, cap)] {+ let mut arena = VectorArena::new(16).unwrap();+ for index in 0..=cap + 1 {+ let source = if twins && index == 2 { 1 } else { index };+ let vector = seeded_unit_vector(0x11B0_0000 + source as u64, 16);+ arena.upsert(&format!("key-{index}"), &vector).unwrap();+ }+ let mut graph = Graph::rebuild(&arena);+ let full: Vec<u32> = (1..=cap as u32).collect();+ graph.write_level_list(0, 0, &full);+ graph.link_back(0, 0, cap as u32 + 1, cap, &arena);+ assert_eq!(graph.level_neighbors(0, 0).len(), expected);+ }+ }++ #[test]+ fn jittered_groups_near_the_neighbor_cap_stay_whole() {+ for storage in [StorageKind::F32, StorageKind::I8] {+ for spread in [1e-3, 1e-5, 1e-6] {+ let (arena, graph) = build_groups(+ 512,+ storage,+ DistanceMetric::Cosine,+ 4,+ 80,+ |group, member| {+ jittered(+ &group_center(group, 512),+ JITTER_SEED + (group * 80 + member) as u64,+ spread,+ )+ },+ );+ let query = arena.pack_query(&group_center(0, 512)).unwrap();+ let found = search(+ &graph,+ &arena,+ &query,+ ¶ms(Some(100), None, false),+ None,+ );+ assert_eq!(found.len(), 100);+ assert_sorted(&found);+ assert_leading_group_members(&arena, &found, 80, 0, 80);+ }+ }+ }++ fn scored_at(distances: &[f32]) -> Vec<Scored> {+ distances+ .iter()+ .enumerate()+ .map(|(slot, &distance)| Scored {+ distance,+ slot: slot as u32,+ })+ .collect()+ }++ #[test]+ fn reverse_prune_target_keeps_the_full_cap_only_on_equal_distances() {+ let tied = scored_at(&[0.2, 0.4, 0.4, 0.9]);+ let tied_far = scored_at(&[0.2, 0.4, 0.9, 0.9]);+ let apart = scored_at(&[0.2, 0.4, 0.400_001, 0.9]);+ assert_eq!(+ reverse_prune_target(LEVEL_ZERO_NEIGHBOR_CAP, &tied),+ LEVEL_ZERO_NEIGHBOR_CAP+ );+ assert_eq!(+ reverse_prune_target(LEVEL_ZERO_NEIGHBOR_CAP, &tied_far),+ LEVEL_ZERO_NEIGHBOR_CAP+ );+ assert_eq!(+ reverse_prune_target(LEVEL_ZERO_NEIGHBOR_CAP, &apart),+ LEVEL_ZERO_NEIGHBOR_CAP - REVERSE_PRUNE_SLACK+ );+ assert_eq!(+ reverse_prune_target(UPPER_LEVEL_NEIGHBOR_CAP, &[]),+ UPPER_LEVEL_NEIGHBOR_CAP - REVERSE_PRUNE_SLACK+ );+ for cap in 1..=REVERSE_PRUNE_SLACK {+ assert_eq!(reverse_prune_target(cap, &apart), 1);+ }+ }++ #[test]+ fn reverse_pruning_leaves_slack_below_the_level_zero_cap() {+ let (arena, graph) = build_fixture(4000, 16, 0x51AC_0000);+ let lengths: Vec<usize> = arena+ .live_slots()+ .map(|slot| graph.level_neighbors(slot, 0).len())+ .collect();+ let full = lengths+ .iter()+ .filter(|&&len| len == LEVEL_ZERO_NEIGHBOR_CAP)+ .count();+ let mean = lengths.iter().sum::<usize>() as f64 / lengths.len() as f64;+ assert!(lengths.iter().all(|&len| len <= LEVEL_ZERO_NEIGHBOR_CAP));+ assert!(mean < 31.0, "mean level-zero degree {mean}");+ assert!(+ full * 2 < lengths.len(),+ "{full} full lists of {}",+ lengths.len()+ );+ }+#[test]fn cold_search_fills_across_duplicate_groups() {let (arena, graph) = build_duplicate_groups(4, 80);