75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
# `:vector-index-api` — общий интерфейс ANN-индекса
|
|
|
|
## Что это
|
|
|
|
Pure-API модуль: интерфейсы и data-классы, общие для любых бэкендов
|
|
ANN-поиска (approximate nearest neighbor). Никаких реализаций и
|
|
платформенных зависимостей — только контракт.
|
|
|
|
Используется как стабильный API-фасад между кодом, который хочет
|
|
искать по embeddings, и реализациями (JVector, ksqlite, sqlite-vec,
|
|
inmemory, ...). При замене бэкенда вызывающий код не меняется.
|
|
|
|
## Где используется
|
|
|
|
Реализации:
|
|
|
|
- `:vector-index-jvector` — JVM-only ANN поверх JVector (Datadog).
|
|
RAM-only. Самый быстрый для больших датасетов.
|
|
- `:vector-index-ksqlite` — KMP brute-force cosine в SQLite. Подходит
|
|
для ≤10K записей, имеет persistence "бесплатно".
|
|
|
|
## Что внутри
|
|
|
|
```kotlin
|
|
interface VectorIndexStore : AutoCloseable {
|
|
val dimension: Int
|
|
suspend fun getSize(): Long
|
|
suspend fun search(embedding: FloatArray, limit: Int): List<VectorSearchResult>
|
|
}
|
|
|
|
interface MutableVectorIndexStore : VectorIndexStore {
|
|
suspend fun add(id: String?, embedding: FloatArray, payload: String?): VectorIndex
|
|
suspend fun delete(id: String): Boolean
|
|
suspend fun clear(): Long
|
|
}
|
|
|
|
class VectorIndex(val id: String, val embedding: FloatArray, val payload: String?)
|
|
// equals/hashCode/toString переопределены руками (FloatArray не работает
|
|
// корректно в data class).
|
|
|
|
data class VectorSearchResult(val index: VectorIndex, val score: Float)
|
|
|
|
class VectorIndexAlreadyExistsException : Exception()
|
|
```
|
|
|
|
**Конвенции:**
|
|
- `id: String?` в `add()` — если `null`, реализация генерирует сама
|
|
(формат на усмотрении реализации).
|
|
- `payload: String?` — opaque строка, реализация хранит как есть и не
|
|
интерпретирует.
|
|
- `dimension` фиксируется на уровне индекса и проверяется при `add()` /
|
|
`search()`.
|
|
- Все мутации и чтения — `suspend` для совместимости с нативной
|
|
блокировкой в JNI/JVector и I/O в ksqlite.
|
|
- `search()` возвращает топ-K, отсортированный по убыванию score.
|
|
- `close()` обязателен (наследуется от `AutoCloseable`).
|
|
|
|
## Цели сборки
|
|
|
|
KMP (все 9): jvm + linuxX64/Arm64 + macosX64/Arm64 + iosX64/Arm64/
|
|
SimulatorArm64 + mingwX64. Pure-Kotlin stdlib + `kotlinx-coroutines-core`,
|
|
никаких нативных зависимостей — поэтому собирается везде.
|
|
|
|
## Текущий статус
|
|
|
|
API стабилизирован. Реализации покрывают JVM и KMP-without-Apple.
|
|
|
|
## Чего здесь НЕТ
|
|
|
|
- Никакой сериализации (`@Serializable`) — типы транспортируются
|
|
через интерфейсы, не через JSON.
|
|
- Никаких auto-generated id правил — реализации решают сами.
|
|
- Никаких фильтров на `search()` — чистый ANN без predicate push-down
|
|
(если нужен фильтр, делать на стороне вызывающего кода после `search`).
|