113 lines
4.3 KiB
Markdown
113 lines
4.3 KiB
Markdown
# `:vector-index-ksqlite` — ANN-индекс поверх SQLite (brute-force)
|
|
|
|
## Что это
|
|
|
|
KMP-реализация `MutableVectorIndexStore` поверх
|
|
[ksqlite](https://github.com/caffeine-mgn/ksqlite). Persistence
|
|
"бесплатно" — обычная SQLite БД.
|
|
|
|
Стратегия поиска: **brute-force cosine similarity**. Один `SELECT`
|
|
всех записей → декодирование BLOB → cosine sim в Kotlin → sort desc →
|
|
топ-K. Просто, KMP-совместимо, **без** sqlite-vec extension.
|
|
|
|
Используется как persistent ANN-индекс для small-to-medium датасетов
|
|
(≤10K записей на embedding ~512d). Для больших — переезжать на
|
|
`:vector-index-jvector` или sqlite-vec.
|
|
|
|
## Где используется
|
|
|
|
Standalone-агентом, когда нужна persistence embeddings и масштаб не
|
|
превышает ~10K записей. Прямо сейчас модуль **не подключён** в
|
|
`:standalone` — это API-готовый компонент, ждущий интеграции.
|
|
|
|
## Что внутри
|
|
|
|
```kotlin
|
|
class KsqliteVectorIndexStore private constructor(
|
|
override val dimension: Int,
|
|
connection: SQLiteConnection,
|
|
ownsConnection: Boolean,
|
|
) : MutableVectorIndexStore {
|
|
|
|
constructor(dimension: Int, path: String)
|
|
constructor(dimension: Int, connection: SQLiteConnection)
|
|
|
|
override suspend fun getSize(): Long
|
|
override suspend fun add(id: String?, embedding: FloatArray, payload: String?): VectorIndex
|
|
override suspend fun delete(id: String): Boolean
|
|
override suspend fun clear(): Long
|
|
override suspend fun search(embedding: FloatArray, limit: Int): List<VectorSearchResult>
|
|
override fun close()
|
|
|
|
companion object {
|
|
fun memory(dimension: Int, name: String? = null): KsqliteVectorIndexStore
|
|
}
|
|
}
|
|
```
|
|
|
|
**Lifecycle:**
|
|
- `(dimension, path)` — открывает файловое соединение, мигрирует,
|
|
закрывает в `close()`.
|
|
- `(dimension, connection)` — внешнее соединение (shared bundle);
|
|
store НЕ закрывает его.
|
|
- `memory(dimension, name)` — in-memory, мигрирует, закрывает.
|
|
|
|
**Schema:** единственная таблица `vector_index (id TEXT PRIMARY KEY,
|
|
dimension INTEGER, embedding BLOB, payload TEXT)`. Embedding хранится
|
|
как raw float32 little-endian через ручной `FloatArray.toLittleEndianBytes()` /
|
|
`ByteArray.toFloatArray()` (hand-rolled в commonMain — без
|
|
`java.nio.ByteBuffer`).
|
|
|
|
**Миграции:** `PRAGMA user_version` + `BEGIN`/`COMMIT`. Идемпотентен.
|
|
|
|
**UUID:** `kotlin.uuid.Uuid.random()` (commonMain-safe, не JVM-only
|
|
`java.util.UUID`).
|
|
|
|
## Цели сборки
|
|
|
|
**Только:** `jvm()`, `linuxX64()`, `linuxArm64()`, `mingwX64()` —
|
|
ksqlite 0.1.2 публикует нативные бинари только для этих 4 целей
|
|
(плюс 4 Android NDK). Нет macOS/iOS — для Apple использовать
|
|
`:vector-index-jvector`.
|
|
|
|
## Как подключить
|
|
|
|
```kotlin
|
|
dependencies {
|
|
implementation("pw.binom.agentik:vector-index-ksqlite:0.1.0")
|
|
implementation("pw.binom.agentik:vector-index-api:0.1.0")
|
|
}
|
|
|
|
val store = KsqliteVectorIndexStore(dimension = 768, path = "~/.agentik/vectors.db")
|
|
store.add(id = "doc-1", embedding = embeddingOf("hello"), payload = """{"src":"chat"}""")
|
|
val top = store.search(embedding = queryEmbedding, limit = 10)
|
|
store.close()
|
|
```
|
|
|
|
## Тесты
|
|
|
|
```
|
|
./gradlew :vector-index-ksqlite:jvmTest
|
|
```
|
|
|
|
Покрывают: explicit/auto id, duplicate throws, delete+idempotency,
|
|
clear, top-K sort, payload round-trip, BLOB bit-exact round-trip
|
|
(FloatArray<->BLOB encoding), schema migration idempotency.
|
|
|
|
## Зависимости
|
|
|
|
- `pw.binom.db:ksqlite:0.1.2`
|
|
- `pw.binom.agentik:vector-index-api`
|
|
- `kotlinx-coroutines-core`
|
|
|
|
## Чего здесь НЕТ
|
|
|
|
- ANN на стороне SQL — нет sqlite-vec. Brute-force в Kotlin.
|
|
- Фильтрации в `search()` — чистый ANN.
|
|
- Apple targets (см. выше).
|
|
|
|
## Текущий статус
|
|
|
|
Реализация готова, тесты зелёные. Интеграция в `:standalone`
|
|
отложена до момента, когда понадобится.
|