remdb 0.3.1

嵌入式内存数据库
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
use crate::platform::memset;
use crate::types::{DistanceType, VectorMetadata};
use crate::{RemDbError, Result};
use alloc::vec::Vec;
use core::cmp::Ordering;
use core::ptr::NonNull;

/// 简单的XorShift随机数生成器(用于baremetal环境)
#[cfg(not(feature = "std"))]
struct XorShiftRng {
    state: u64,
}

#[cfg(not(feature = "std"))]
impl XorShiftRng {
    fn new(seed: u64) -> Self {
        XorShiftRng {
            state: if seed == 0 { 0x123456789abcdef } else { seed },
        }
    }

    fn next_u64(&mut self) -> u64 {
        let mut x = self.state;
        x ^= x << 13;
        x ^= x >> 7;
        x ^= x << 17;
        self.state = x;
        x
    }

    fn next_f64(&mut self) -> f64 {
        (self.next_u64() as f64) / (u64::MAX as f64)
    }
}

/// HNSW节点结构
#[repr(C)]
pub struct HNSWNode {
    /// 向量在存储中的偏移量
    pub vector_offset: usize,
    /// 记录ID
    pub record_id: u16,
    /// 每层的邻居节点数量
    pub neighbor_counts: Vec<u8>,
    /// 邻居节点列表(按层组织)
    pub neighbors: Vec<NonNull<HNSWNode>>,
}

impl HNSWNode {
    /// 创建新的HNSW节点
    pub unsafe fn new(vector_offset: usize, record_id: u16, max_level: usize) -> Self {
        let mut neighbor_counts = Vec::with_capacity(max_level + 1);
        for _ in 0..=max_level {
            neighbor_counts.push(0);
        }
        // 预填充邻居数组:每层最多32个邻居,用NonNull::dangling()作为占位符
        // 实际写入时add_neighbor_at_level会覆盖对应位置,读取时只访问已写入的范围
        let neighbors = alloc::vec![NonNull::dangling(); (max_level + 1) * 32];

        HNSWNode {
            vector_offset,
            record_id,
            neighbor_counts,
            neighbors,
        }
    }

    /// 获取节点在指定层的邻居列表
    pub unsafe fn get_neighbors_at_level(&self, level: usize) -> &[NonNull<HNSWNode>] {
        let start_offset = level * 32; // 每层最多32个邻居
        let count = match self.neighbor_counts.get(level) {
            Some(&c) => c as usize,
            None => return &[],
        };
        let end = start_offset + count;
        if end > self.neighbors.len() {
            return &[];
        }
        &self.neighbors[start_offset..end]
    }

    /// 添加邻居节点到指定层
    pub unsafe fn add_neighbor_at_level(
        &mut self,
        level: usize,
        neighbor: NonNull<HNSWNode>,
    ) -> Result<()> {
        let start_offset = level * 32;
        let count = match self.neighbor_counts.get(level) {
            Some(&c) => c as usize,
            None => return Err(RemDbError::OutOfMemory),
        };

        if count >= 32 {
            return Err(RemDbError::OutOfMemory);
        }

        let idx = start_offset + count;
        if idx >= self.neighbors.len() {
            return Err(RemDbError::OutOfMemory);
        }

        self.neighbors[idx] = neighbor;
        self.neighbor_counts[level] += 1;

        Ok(())
    }
}

/// HNSW索引结构
pub struct HNSWIndex {
    /// 向量元数据
    pub meta: VectorMetadata,
    /// 向量数据存储
    pub vectors: *mut f32,
    /// 最大层数
    pub max_level: usize,
    /// 当前插入点
    pub enter_point: Option<NonNull<HNSWNode>>,
    /// 每层的入口节点
    pub layer_enter_points: Vec<Option<NonNull<HNSWNode>>>,
    /// 节点池
    pub nodes: NonNull<HNSWNode>,
    /// 空闲节点列表
    pub free_nodes: Option<NonNull<HNSWNode>>,
    /// 最大节点数量
    pub max_nodes: usize,
    /// 当前节点数量
    pub node_count: usize,
    /// 自旋锁
    pub lock: u32,
}

impl HNSWIndex {
    /// 创建新的HNSW索引
    pub unsafe fn new(
        meta: VectorMetadata,
        vectors: *mut f32,
        memory_start: *mut u8,
        max_nodes: usize,
    ) -> Result<Self> {
        // 计算最大层数
        let max_level = if max_nodes > 0 {
            (max_nodes as f64).ln() as usize
        } else {
            0
        };

        // 初始化节点池
        let nodes = NonNull::new_unchecked(memory_start as *mut HNSWNode);

        // 初始化空闲节点链表
        // 注意:insert不使用free_nodes,它总是追加到nodes[node_count];
        // 这里仍然用ptr::write初始化每个节点,确保池内存有效
        // (delete会使用free_nodes将被删除节点放回空闲列表)
        let mut free_nodes = None;
        for i in (0..max_nodes).rev() {
            let node_ptr = nodes.as_ptr().add(i);
            // 用ptr::write将初始化好的节点写入池内存
            let node = HNSWNode::new(0, 0, max_level);
            core::ptr::write(node_ptr, node);
            free_nodes = Some(NonNull::new_unchecked(node_ptr));
        }

        // 初始化层入口节点
        let mut layer_enter_points = Vec::with_capacity(max_level + 1);
        for _ in 0..=max_level {
            layer_enter_points.push(None);
        }

        Ok(HNSWIndex {
            meta,
            vectors,
            max_level,
            enter_point: None,
            layer_enter_points,
            nodes,
            free_nodes,
            max_nodes,
            node_count: 0,
            lock: 0,
        })
    }

    /// 计算两个向量之间的距离
    unsafe fn calculate_distance(&self, vec1: *const f32, vec2: *const f32) -> f32 {
        match self.meta.distance_type {
            DistanceType::L2 => {
                // L2距离(欧几里得距离)
                let mut sum = 0.0;
                for i in 0..self.meta.dimension {
                    let diff = *vec1.add(i as usize) - *vec2.add(i as usize);
                    sum += diff * diff;
                }
                sum.sqrt()
            }
            DistanceType::InnerProduct => {
                // 内积
                let mut sum = 0.0;
                for i in 0..self.meta.dimension {
                    sum += *vec1.add(i as usize) * *vec2.add(i as usize);
                }
                -sum // 返回负数,因为内积越大相似度越高
            }
            DistanceType::Cosine => {
                // 余弦相似度
                let mut dot = 0.0;
                let mut norm1 = 0.0;
                let mut norm2 = 0.0;

                for i in 0..self.meta.dimension {
                    let v1 = *vec1.add(i as usize);
                    let v2 = *vec2.add(i as usize);
                    dot += v1 * v2;
                    norm1 += v1 * v1;
                    norm2 += v2 * v2;
                }

                let norm1 = norm1.sqrt();
                let norm2 = norm2.sqrt();

                if norm1 == 0.0 || norm2 == 0.0 {
                    -1.0 // 相似度最低
                } else {
                    -(dot / (norm1 * norm2)) // 返回负数,因为余弦相似度越大相似度越高
                }
            }
        }
    }

    /// 生成随机层号
    fn generate_random_level(&self) -> usize {
        let mut level = 0;
        let p = 0.5; // 层概率衰减因子
        #[cfg(feature = "std")]
        while level < self.max_level && rand::random::<f64>() < p {
            level += 1;
        }

        #[cfg(not(feature = "std"))]
        // 简单的伪随机数生成器(用于baremetal环境)
        {
            // 使用当前时间作为种子
            let seed = core::time::Instant::now().elapsed().as_nanos() as u64;
            let mut rng = XorShiftRng::new(seed);
            while level < self.max_level && rng.next_f64() < p {
                level += 1;
            }
        }

        level
    }

    /// 保存HNSW索引到文件
    #[cfg(feature = "std")]
    pub fn save<W: std::io::Write>(&self, writer: &mut W) -> Result<()> {

        // 保存向量元数据参数
        // 写入hnsw_m
        writer
            .write_all(&self.meta.hnsw_m.to_le_bytes())
            .map_err(|_| RemDbError::FileIoError)?;
        // 写入hnsw_ef_construction
        writer
            .write_all(&self.meta.hnsw_ef_construction.to_le_bytes())
            .map_err(|_| RemDbError::FileIoError)?;
        // 写入hnsw_ef_search
        writer
            .write_all(&self.meta.hnsw_ef_search.to_le_bytes())
            .map_err(|_| RemDbError::FileIoError)?;

        // 保存HNSW索引元数据
        // 写入最大层数
        writer
            .write_all(&self.max_level.to_le_bytes())
            .map_err(|_| RemDbError::FileIoError)?;
        // 写入当前节点数量
        writer
            .write_all(&self.node_count.to_le_bytes())
            .map_err(|_| RemDbError::FileIoError)?;

        // 保存入口点
        let enter_point_offset = match self.enter_point {
            Some(point) => {
                let offset = unsafe { point.as_ptr().offset_from(self.nodes.as_ptr()) } as usize;
                offset
            }
            None => usize::MAX,
        };
        writer
            .write_all(&enter_point_offset.to_le_bytes())
            .map_err(|_| RemDbError::FileIoError)?;

        // 保存每层入口节点
        writer
            .write_all(&self.layer_enter_points.len().to_le_bytes())
            .map_err(|_| RemDbError::FileIoError)?;
        for &point in &self.layer_enter_points {
            let offset = match point {
                Some(p) => {
                    let offset = unsafe { p.as_ptr().offset_from(self.nodes.as_ptr()) } as usize;
                    offset
                }
                None => usize::MAX,
            };
            writer
                .write_all(&offset.to_le_bytes())
                .map_err(|_| RemDbError::FileIoError)?;
        }

        // 保存节点数据
        for i in 0..self.node_count {
            let node_ptr = unsafe { self.nodes.as_ptr().add(i) };
            let node = unsafe { &*node_ptr };

            // 写入向量偏移量
            writer
                .write_all(&node.vector_offset.to_le_bytes())
                .map_err(|_| RemDbError::FileIoError)?;
            // 写入记录ID
            writer
                .write_all(&node.record_id.to_le_bytes())
                .map_err(|_| RemDbError::FileIoError)?;

            // 写入邻居数量
            writer
                .write_all(&node.neighbor_counts.len().to_le_bytes())
                .map_err(|_| RemDbError::FileIoError)?;
            for &count in &node.neighbor_counts {
                writer
                    .write_all(&count.to_le_bytes())
                    .map_err(|_| RemDbError::FileIoError)?;
            }

            // 写入邻居节点
            for &neighbor in &node.neighbors {
                let offset = unsafe { neighbor.as_ptr().offset_from(self.nodes.as_ptr()) } as usize;
                writer
                    .write_all(&offset.to_le_bytes())
                    .map_err(|_| RemDbError::FileIoError)?;
            }
        }

        Ok(())
    }

    /// 从文件加载HNSW索引
    #[cfg(feature = "std")]
    pub unsafe fn load<R: std::io::Read>(
        mut meta: VectorMetadata,
        vectors: *mut f32,
        memory_start: *mut u8,
        max_nodes: usize,
        reader: &mut R,
    ) -> Result<Self> {

        // 读取向量元数据参数
        // 读取hnsw_m
        let mut m_bytes = [0u8; 1];
        reader
            .read_exact(&mut m_bytes)
            .map_err(|_| RemDbError::FileIoError)?;
        meta.hnsw_m = m_bytes[0];

        // 读取hnsw_ef_construction
        let mut efc_bytes = [0u8; 4];
        reader
            .read_exact(&mut efc_bytes)
            .map_err(|_| RemDbError::FileIoError)?;
        meta.hnsw_ef_construction = u32::from_le_bytes(efc_bytes);

        // 读取hnsw_ef_search
        let mut efs_bytes = [0u8; 4];
        reader
            .read_exact(&mut efs_bytes)
            .map_err(|_| RemDbError::FileIoError)?;
        meta.hnsw_ef_search = u32::from_le_bytes(efs_bytes);

        // 读取HNSW索引元数据
        // 读取最大层数
        let mut max_level_bytes = [0u8; 8];
        reader
            .read_exact(&mut max_level_bytes)
            .map_err(|_| RemDbError::FileIoError)?;
        let max_level = usize::from_le_bytes(max_level_bytes);

        // 读取当前节点数量
        let mut node_count_bytes = [0u8; 8];
        reader
            .read_exact(&mut node_count_bytes)
            .map_err(|_| RemDbError::FileIoError)?;
        let node_count = usize::from_le_bytes(node_count_bytes);

        // 初始化节点池
        let _node_size = core::mem::size_of::<HNSWNode>();
        let nodes = NonNull::new_unchecked(memory_start as *mut HNSWNode);

        // 读取入口点
        let mut enter_point_offset_bytes = [0u8; 8];
        reader
            .read_exact(&mut enter_point_offset_bytes)
            .map_err(|_| RemDbError::FileIoError)?;
        let enter_point_offset = usize::from_le_bytes(enter_point_offset_bytes);
        let enter_point = if enter_point_offset == usize::MAX {
            None
        } else {
            Some(NonNull::new_unchecked(
                nodes.as_ptr().add(enter_point_offset),
            ))
        };

        // 读取每层入口节点
        let mut layer_enter_points_len_bytes = [0u8; 8];
        reader
            .read_exact(&mut layer_enter_points_len_bytes)
            .map_err(|_| RemDbError::FileIoError)?;
        let layer_enter_points_len = usize::from_le_bytes(layer_enter_points_len_bytes);

        let mut layer_enter_points = Vec::with_capacity(layer_enter_points_len);
        for _ in 0..layer_enter_points_len {
            let mut offset_bytes = [0u8; 8];
            reader
                .read_exact(&mut offset_bytes)
                .map_err(|_| RemDbError::FileIoError)?;
            let offset = usize::from_le_bytes(offset_bytes);
            let point = if offset == usize::MAX {
                None
            } else {
                Some(NonNull::new_unchecked(nodes.as_ptr().add(offset)))
            };
            layer_enter_points.push(point);
        }

        // 读取节点数据
        for i in 0..node_count {
            let node_ptr = nodes.as_ptr().add(i);

            // 读取向量偏移量
            let mut vector_offset_bytes = [0u8; 8];
            reader
                .read_exact(&mut vector_offset_bytes)
                .map_err(|_| RemDbError::FileIoError)?;
            let vector_offset = usize::from_le_bytes(vector_offset_bytes);

            // 读取记录ID
            let mut record_id_bytes = [0u8; 2];
            reader
                .read_exact(&mut record_id_bytes)
                .map_err(|_| RemDbError::FileIoError)?;
            let record_id = u16::from_le_bytes(record_id_bytes);

            // 读取邻居数量
            let mut neighbor_counts_len_bytes = [0u8; 8];
            reader
                .read_exact(&mut neighbor_counts_len_bytes)
                .map_err(|_| RemDbError::FileIoError)?;
            let neighbor_counts_len = usize::from_le_bytes(neighbor_counts_len_bytes);

            let mut neighbor_counts = Vec::with_capacity(neighbor_counts_len);
            for _ in 0..neighbor_counts_len {
                let mut count_bytes = [0u8; 1];
                reader
                    .read_exact(&mut count_bytes)
                    .map_err(|_| RemDbError::FileIoError)?;
                neighbor_counts.push(count_bytes[0]);
            }

            // 读取邻居节点
            let total_neighbors = neighbor_counts.iter().sum::<u8>() as usize;
            let mut neighbors = Vec::with_capacity(total_neighbors);
            for _ in 0..total_neighbors {
                let mut offset_bytes = [0u8; 8];
                reader
                    .read_exact(&mut offset_bytes)
                    .map_err(|_| RemDbError::FileIoError)?;
                let offset = usize::from_le_bytes(offset_bytes);
                let neighbor = NonNull::new_unchecked(nodes.as_ptr().add(offset));
                neighbors.push(neighbor);
            }

            // 构建节点
            let node = HNSWNode {
                vector_offset,
                record_id,
                neighbor_counts,
                neighbors,
            };

            // 写入节点
            *node_ptr = node;
        }

        Ok(HNSWIndex {
            meta,
            vectors,
            max_level,
            enter_point,
            layer_enter_points,
            nodes,
            free_nodes: None, // 加载时不需要空闲节点列表
            max_nodes,
            node_count,
            lock: 0,
        })
    }

    /// 搜索最近邻(单个层)
    unsafe fn search_layer(
        &self,
        query_vec: *const f32,
        entry_point: NonNull<HNSWNode>,
        ef: usize,
        level: usize,
    ) -> Vec<(f32, NonNull<HNSWNode>)> {
        let mut visited = Vec::new();
        let mut candidates = Vec::new();
        let mut results = Vec::new();

        // 添加迭代限制防止无限循环
        const MAX_ITERATIONS: usize = 10000;
        let mut iteration_count = 0;

        // 初始化
        let entry_node = entry_point.as_ref();
        let entry_vec = self.vectors.add(entry_node.vector_offset);
        let distance = self.calculate_distance(query_vec, entry_vec);
        candidates.push((distance, entry_point));
        results.push((distance, entry_point));
        // 入口点必须标记为已访问,否则双向边回到入口点时会被重复加入结果
        visited.push(entry_point);
        while let Some((current_dist, current_node)) = candidates.pop() {
            iteration_count += 1;
            if iteration_count > MAX_ITERATIONS {
                // 达到最大迭代次数,返回当前结果
                #[cfg(feature = "log")]
                crate::log::warn!(
                    "HNSW search_layer reached max iterations, graph may be malformed"
                );
                break;
            }

            // 更新结果列表
            if results.len() < ef || current_dist < results.last().map(|r| r.0).unwrap_or(f32::MAX)
            {
                // 获取当前节点的邻居
                let neighbors = current_node.as_ref().get_neighbors_at_level(level);
                for &neighbor in neighbors {
                    if !visited.contains(&neighbor) {
                        visited.push(neighbor);
                        let neighbor_node = neighbor.as_ref();
                        let neighbor_vec = self.vectors.add(neighbor_node.vector_offset);
                        let neighbor_dist = self.calculate_distance(query_vec, neighbor_vec);
                        if results.len() < ef
                            || neighbor_dist < results.last().map(|r| r.0).unwrap_or(f32::MAX)
                        {
                            candidates.push((neighbor_dist, neighbor));
                            results.push((neighbor_dist, neighbor));
                            // 按距离排序并限制结果数量
                            results
                                .sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(Ordering::Equal));
                            if results.len() > ef {
                                results.pop();
                            }
                        }
                    }
                }
            }
        }

        results
    }

    /// 搜索最近邻(所有层)
    pub unsafe fn search(&self, query_vec: *const f32, _k: usize) -> Result<Vec<(f32, u16)>> {
        if self.enter_point.is_none() {
            return Err(RemDbError::RecordNotFound);
        }

        let mut current_point = self.enter_point.ok_or(RemDbError::InvalidState)?;
        let mut current_level = self.max_level;

        // 从上到下遍历各层
        while current_level > 0 {
            let results = self.search_layer(query_vec, current_point, 1, current_level);
            if let Some(&(_dist, point)) = results.get(0) {
                current_point = point;
            }
            current_level -= 1;
        }

        // 在最底层进行精确搜索
        let results = self.search_layer(
            query_vec,
            current_point,
            self.meta.hnsw_ef_search as usize,
            0,
        );
        // 转换为记录ID和距离
        let mut final_results = Vec::new();
        for (distance, node) in results {
            final_results.push((distance, node.as_ref().record_id));
        }

        Ok(final_results)
    }

    /// 插入新节点
    pub unsafe fn insert(&mut self, vector_offset: usize, record_id: u16) -> Result<()> {
        // 获取向量数据
        let vec_ptr = self.vectors.add(vector_offset);
        // 生成随机层号
        let new_level = self.generate_random_level();
        // 在节点池中分配一个槽位
        if self.node_count >= self.max_nodes {
            return Err(RemDbError::OutOfMemory);
        }
        let node_ptr = self.nodes.as_ptr().add(self.node_count);
        // 立即将节点写入池中(避免后续操作中指向栈变量的悬垂指针)
        core::ptr::write(
            node_ptr,
            HNSWNode::new(vector_offset, record_id, self.max_level),
        );
        let pool_node = NonNull::new_unchecked(node_ptr);

        // 搜索路径(entry_point需要mut,因为我们在while循环中可能需要更新它)
        let mut entry_point = match self.enter_point {
            Some(point) => point,
            None => {
                // 第一个节点
                self.enter_point = Some(pool_node);
                for i in 0..=new_level {
                    if let Some(ep) = self.layer_enter_points.get_mut(i) {
                        *ep = Some(pool_node);
                    }
                }
                self.node_count += 1;
                return Ok(());
            }
        };

        let mut current_level = self.max_level;
        // 从上到下搜索插入位置
        while current_level > new_level {
            let results = self.search_layer(vec_ptr, entry_point, 1, current_level);
            if let Some(&(_dist, point)) = results.get(0) {
                entry_point = point;
            }
            current_level -= 1;
        }

        // 在各层插入节点
        while current_level <= new_level {
            // 搜索当前层的最近邻
            let ef_construction = self.meta.hnsw_ef_construction as usize;
            let neighbors = self.search_layer(vec_ptr, entry_point, ef_construction, current_level);
            // 选择M个最近邻
            let m = self.meta.hnsw_m as usize;
            let selected_neighbors = neighbors
                .iter()
                .take(m)
                .map(|&(_d, n)| n)
                .collect::<Vec<_>>();
            // 将新节点连接到选中的邻居
            let node_mut = &mut *node_ptr; // 池中节点的可变引用
            for &neighbor in &selected_neighbors {
                node_mut.add_neighbor_at_level(current_level, neighbor)?;
                // 双向连接:使用池中节点的稳定指针(NonNull),而非栈变量
                let neighbor_ptr = neighbor.as_ptr();
                let neighbor_mut = &mut *neighbor_ptr;
                neighbor_mut.add_neighbor_at_level(current_level, pool_node)?;
            }

            // 更新层入口点
            let current_ep = self.layer_enter_points.get_mut(current_level);
            if let Some(ep) = current_ep {
                if ep.is_none() {
                    *ep = Some(pool_node);
                }
            }

            current_level += 1;
        }

        // 节点已写入池中,只需增加计数
        self.node_count += 1;

        // 更新全局入口点
        if new_level >= self.max_level {
            self.enter_point = Some(pool_node);
        }

        Ok(())
    }

    /// 删除节点
    pub unsafe fn delete(&mut self, vector_offset: usize) -> Result<()> {
        // 查找要删除的节点
        let mut target_node = None;
        let mut target_node_idx = None;
        for i in 0..self.node_count {
            let node_ptr = self.nodes.as_ptr().add(i);
            // SAFETY: node_ptr is a valid pointer
            let node = unsafe { &*node_ptr };
            if node.vector_offset == vector_offset {
                target_node = Some(NonNull::new_unchecked(node_ptr));
                target_node_idx = Some(i);
                break;
            }
        }

        if let Some(target_node) = target_node {
            // 1. 更新图结构,移除指向该节点的连接
            // 遍历所有节点,移除对目标节点的引用
            for i in 0..self.node_count {
                let node_ptr = self.nodes.as_ptr().add(i);
                // SAFETY: node_ptr is a valid pointer
                let node = unsafe { &mut *node_ptr };

                // 遍历每层
                for level in 0..=self.max_level {
                    // 获取当前层的邻居列表(使用边界检查)
                    let start_offset = level * 32;
                    let count = match node.neighbor_counts.get(level) {
                        Some(&c) => c as usize,
                        None => continue,
                    };

                    // 确保start_offset + count不超过neighbors长度
                    let end = start_offset + count;
                    if end > node.neighbors.len() {
                        continue;
                    }

                    // 查找并移除目标节点
                    let mut new_neighbors = Vec::new();
                    let mut new_count = 0;

                    for j in 0..count {
                        let idx = start_offset + j;
                        let neighbor = match node.neighbors.get(idx) {
                            Some(&n) => n,
                            None => continue,
                        };
                        if neighbor != target_node {
                            new_neighbors.push(neighbor);
                            new_count += 1;
                        }
                    }

                    // 更新邻居列表
                    if new_count < count {
                        // 复制新邻居列表
                        for (j, &neighbor) in new_neighbors.iter().enumerate() {
                            let idx = start_offset + j;
                            if idx < node.neighbors.len() {
                                node.neighbors[idx] = neighbor;
                            }
                        }
                        // 更新邻居数量
                        if let Some(nc) = node.neighbor_counts.get_mut(level) {
                            *nc = new_count as u8;
                        }
                    }
                }
            }

            // 2. 清空节点数据
            memset(
                target_node.as_ptr() as *mut u8,
                0,
                core::mem::size_of::<HNSWNode>(),
            );

            // 3. 更新空闲节点列表
            let mut node = target_node;
            node.as_mut().neighbors.clear();
            node.as_mut().neighbor_counts.clear();
            let _next_free = self.free_nodes;
            self.free_nodes = Some(node);

            Ok(())
        } else {
            Err(RemDbError::RecordNotFound)
        }
    }
}