Векторная ML СУБД

https://gitverse.ru/nicktretyakov1/vectorDBML

t.me/oneRustnoqRust

Для чего нужна данная статья? :

Создать векторную СУБД для задач поиска по семантическому сходству и для добавления векторов и поиска ближайших векторов с использованием евклидовой метрики. С условной компиляцией для Python-интеграции, GPU-бэкендов и распределённого обучения.

Зачем Вам это уметь? :

• Хранение нескольких метрик: можно выбирать между евклидовой и косинусной метрикой.
• Индексация: чтобы запрашивать ближайший вектор по индексу. Это может пригодиться для более сложных структур данных (например, KD-деревья или другие структуры для поиска ближайших соседей).

Структура проекта (модули)

• lib.rs: Фасад crate.Re-export публичного API (VectorDB, VectorDBConfig, BuiltInMetric).
  Prelude для удобного импорта.
  Conditional mod python + pub mod py.
  
• config.rs: Конфигурация (Builder Pattern).VectorDBConfig — immutable структура.
  new() + with_* цепочечные методы.
  init() — фабричный метод для VectorDB (pub(crate)).
  
• metrics.rs: Метрики (Strategy + Factory).BuiltInMetric enum (публичный).
  DistanceComputer трейт (dyn).
  Euclidean/Cosine реализации (broadcasting ops).
  create_computer — фабрика.
  
• processors.rs: Препроцессоры (Strategy).VectorProcessor трейт (dyn).
  L2Normalizer (tensor broadcasting + epsilon).
  IdentityProcessor (zero-cost).
  
• storage/:traits.rs: supertraits VectorRepository + NearestNeighborSearcher.
  in_memory.rs: brute-force Vec<Tensor<B, 1>> + batch_tensor stack.
  mod.rs: только pub(crate) mod.
  
• core.rs: Основная VectorDB (композиция).Приватные поля: repository (dyn NearestNeighborSearcher), processor (dyn VectorProcessor), computer (dyn DistanceComputer).
  new() фабрика через config.
  add_vector, search_nearest, set_metric (runtime замена метрики).
  
• pipeline/ (если добавлен):traits.rs/components.rs: трейты DataLoader, Embedder, IndexBuilder, InferenceEngine, Evaluator.
  builder.rs/pipeline.rs: билдер + SemanticSearchPipeline (композиция компонентов).
  
• python.rs: PyO3 обёртка (conditional).PyVectorDB — тонкая обёртка над VectorDB<NdArray>.
  new/add_vector/search_nearest — безопасный FFI (Vec<f64> → f32 tensor).
  
• main.rs: Демонстрация (conditional backend, добавление 10k векторов, поиск, смена метрики).

Как работает ядро (VectorDB)

1. Инициализация:VectorDBConfig::new(dim).with_*() → config.
   
   config.init(&device) → VectorDB::new():repository = InMemoryRepository (brute-force).
   processor = L2Normalizer или Identity.
   computer = Euclidean или Cosine (фабрика).
   
2. add_vector:processor.process(vector) → нормализованный тензор.
   repository.add() → push в Vec + to_device + assert dim.
   
3. search_nearest:query.to_device().
   batch = repository.batch_tensor() (stack всех векторов).
   distances = computer.compute_batch_distances(batch, query) (пакетно на GPU).
   sort_with_indices → топ-k (id, distance).
   
4. set_metric: Runtime замена computer (Strategy swap).

GPU: B = Wgpu или tch::Cuda — все тензоры на GPU, ops в kernels (cuBLAS/wgpu compute shaders).

Расширяемость и параллелизм

• Новый backend: impl Backend для Burn или новый dyn GpuBackend.
• Новая метрика: impl DistanceComputer + match в фабрике.
• Новое хранилище: impl VectorRepository + NearestNeighborSearcher.
• Пайплайн: композиция loader → embedder → indexer → inference.

Параллелизм: Burn (GPU), Rayon (ndarray), Polars lazy (CPU), gRPC (distributed).

src/python.rs

Этот файл реализует PyO3-обёртку для экспорта основной структуры VectorDB (из core.rs) в Python как нативное расширение.

1. Условная компиляция и импорты (Open-Closed + Single Responsibility)

• Как работает: Весь модуль компилируется только при включённой фиче "python" (в Cargo.toml). Это следует Open-Closed Principle: добавление Python-интеграции не ломает чистый Rust-крейт.
• Импорты:pyo3::prelude::* — макросы для экспорта классов/модулей.
  Burn NdArray backend (CPU, f32) — выбран для Python (простота, нет GPU-драйверов в Python обычно).
  Crate-интерфейс: конфиг, метрика, VectorDB — Dependency Inversion: обёртка зависит от абстракций crate, а не от реализации.
  

2. PyVectorDB — обёртка-класс (Liskov Substitution + Encapsulation)

• Как работает: Это Python-класс VectorDB (имя через name = "VectorDB").Поле inner — полная инкапсуляция: настоящая VectorDB<NdArray> скрыта от Python (приватное).
  Liskov Substitution: PyVectorDB ведёт себя как VectorDB (делегирует все вызовы inner).
  
• SOLID: Interface Segregation — Python видит только нужные методы (new, add_vector, search_nearest).

3. #[pymethods] — Python-методы (Strategy Pattern + Builder)

• new: Builder-подобный конструктор.Опциональные параметры → fluent в Python (VectorDB(dim=512, metric="cosine")).
  Валидация метрики → PyError.
  Strategy Pattern: метрика через enum (runtime выбор в Rust).
  
• add_vector / search_nearest:Vec<f64> из Python → Vec<f32> (NdArray f32).
  Tensor::from_floats — zero-copy где возможно.
  Делегирование в inner → Composition over Inheritance.
  
• SOLID: Dependency Inversion (зависит от VectorDB абстракции), Single Responsibility (только FFI).

4. #[pymodule] — экспорт модуля

• Как работает: Регистрация модуля encapsulated_vector_db в Python.При import encapsulated_vector_db → класс VectorDB доступен.
  

Общая работа

• Компиляция: maturin develop --features python → wheel с нативным расширением.
• Параллелизм: Наследуется от Burn NdArray (rayon внутри для CPU).
• Безопасность: Все ошибки → PyError, память управляется Rust (no leaks).