@statewalker/db-sqlite-index 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +289 -2
- package/dist/ngram.d.mts +93 -0
- package/dist/ngram.d.mts.map +1 -0
- package/dist/ngram.mjs +616 -0
- package/dist/ngram.mjs.map +1 -0
- package/dist/prefix-CTeW1EwH.mjs +7 -0
- package/dist/prefix-CTeW1EwH.mjs.map +1 -0
- package/dist/vector.d.mts +103 -0
- package/dist/vector.d.mts.map +1 -0
- package/dist/vector.mjs +1062 -0
- package/dist/vector.mjs.map +1 -0
- package/package.json +63 -3
- package/src/ngram/do-smoke.ts +46 -0
- package/src/ngram/fold.test.ts +50 -0
- package/src/ngram/fold.ts +21 -0
- package/src/ngram/fts5-backend.ts +55 -0
- package/src/ngram/index.ts +12 -0
- package/src/ngram/json-chunks.test.ts +23 -0
- package/src/ngram/json-chunks.ts +23 -0
- package/src/ngram/ngram-store.test.ts +291 -0
- package/src/ngram/ngram-store.ts +184 -0
- package/src/ngram/plan-query.test.ts +141 -0
- package/src/ngram/plan-query.ts +42 -0
- package/src/ngram/postings-backend.ts +53 -0
- package/src/ngram/regex-literals.ts +359 -0
- package/src/ngram/trigrams.test.ts +28 -0
- package/src/ngram/trigrams.ts +25 -0
- package/src/prefix.ts +2 -0
- package/src/vector/auto-compact.test.ts +28 -0
- package/src/vector/do-smoke.ts +39 -0
- package/src/vector/index.ts +9 -0
- package/src/vector/kmeans.ts +131 -0
- package/src/vector/math.ts +178 -0
- package/src/vector/segment.test.ts +61 -0
- package/src/vector/segment.ts +256 -0
- package/src/vector/sql-segment-store.ts +218 -0
- package/src/vector/test-fixtures.ts +64 -0
- package/src/vector/types.ts +30 -0
- package/src/vector/vector-index.test.ts +105 -0
- package/src/vector/vector-index.ts +586 -0
- package/src/vector/vector-lifecycle.test.ts +171 -0
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import type { Metric } from "./types.js";
|
|
2
|
+
|
|
3
|
+
export function normalize(v: Float32Array): Float32Array {
|
|
4
|
+
let n = 0;
|
|
5
|
+
for (let i = 0; i < v.length; i++) n += v[i] * v[i];
|
|
6
|
+
n = Math.sqrt(n);
|
|
7
|
+
const out = new Float32Array(v.length);
|
|
8
|
+
if (n === 0) return out;
|
|
9
|
+
for (let i = 0; i < v.length; i++) out[i] = v[i] / n;
|
|
10
|
+
return out;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** Vectors are stored pre-normalized for cosine, so cosine reduces to dot. */
|
|
14
|
+
export function prepare(v: ArrayLike<number>, dims: number, metric: Metric): Float32Array {
|
|
15
|
+
if (v.length !== dims) throw new Error(`vector-index: expected ${dims} dims, got ${v.length}`);
|
|
16
|
+
const f = v instanceof Float32Array ? v : Float32Array.from(v);
|
|
17
|
+
for (let i = 0; i < f.length; i++) {
|
|
18
|
+
if (!Number.isFinite(f[i])) throw new Error("vector-index: vector contains a non-finite value");
|
|
19
|
+
}
|
|
20
|
+
return metric === "cosine" ? normalize(f) : f.slice();
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Distance between two float vectors at offsets; lower is closer. */
|
|
24
|
+
export function distance(
|
|
25
|
+
metric: Metric,
|
|
26
|
+
a: Float32Array,
|
|
27
|
+
ao: number,
|
|
28
|
+
b: Float32Array,
|
|
29
|
+
bo: number,
|
|
30
|
+
d: number,
|
|
31
|
+
): number {
|
|
32
|
+
if (metric === "l2") {
|
|
33
|
+
let s = 0;
|
|
34
|
+
for (let i = 0; i < d; i++) {
|
|
35
|
+
const x = a[ao + i] - b[bo + i];
|
|
36
|
+
s += x * x;
|
|
37
|
+
}
|
|
38
|
+
return s;
|
|
39
|
+
}
|
|
40
|
+
let s = 0;
|
|
41
|
+
for (let i = 0; i < d; i++) s += a[ao + i] * b[bo + i];
|
|
42
|
+
return metric === "cosine" ? 1 - s : -s;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
// ------------------------------------------------------------ int8
|
|
46
|
+
|
|
47
|
+
/** Symmetric per-vector int8: x ≈ q * scale / 127. Returns the scale. */
|
|
48
|
+
export function quantizeInt8(v: Float32Array, vo: number, d: number, out: Int8Array, oo: number) {
|
|
49
|
+
let max = 0;
|
|
50
|
+
for (let i = 0; i < d; i++) max = Math.max(max, Math.abs(v[vo + i]));
|
|
51
|
+
const inv = max === 0 ? 0 : 127 / max;
|
|
52
|
+
for (let i = 0; i < d; i++) out[oo + i] = Math.round(v[vo + i] * inv);
|
|
53
|
+
return max;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Distance between a float query and an int8-coded vector. */
|
|
57
|
+
export function distanceInt8(
|
|
58
|
+
metric: Metric,
|
|
59
|
+
q: Float32Array,
|
|
60
|
+
codes: Int8Array,
|
|
61
|
+
co: number,
|
|
62
|
+
scale: number,
|
|
63
|
+
d: number,
|
|
64
|
+
): number {
|
|
65
|
+
const f = scale / 127;
|
|
66
|
+
if (metric === "l2") {
|
|
67
|
+
let s = 0;
|
|
68
|
+
for (let i = 0; i < d; i++) {
|
|
69
|
+
const x = q[i] - codes[co + i] * f;
|
|
70
|
+
s += x * x;
|
|
71
|
+
}
|
|
72
|
+
return s;
|
|
73
|
+
}
|
|
74
|
+
let s = 0;
|
|
75
|
+
for (let i = 0; i < d; i++) s += q[i] * codes[co + i];
|
|
76
|
+
s *= f;
|
|
77
|
+
return metric === "cosine" ? 1 - s : -s;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// ------------------------------------------------------------ 1-bit
|
|
81
|
+
|
|
82
|
+
export const wordsFor = (d: number) => (d + 31) >>> 5;
|
|
83
|
+
|
|
84
|
+
/** Sign bits of (v - centroid): residual binarization, meaningful for every metric. */
|
|
85
|
+
export function residualBits(
|
|
86
|
+
v: Float32Array,
|
|
87
|
+
vo: number,
|
|
88
|
+
c: Float32Array,
|
|
89
|
+
co: number,
|
|
90
|
+
d: number,
|
|
91
|
+
out: Uint32Array,
|
|
92
|
+
oo: number,
|
|
93
|
+
) {
|
|
94
|
+
const w = wordsFor(d);
|
|
95
|
+
out.fill(0, oo, oo + w);
|
|
96
|
+
for (let i = 0; i < d; i++) {
|
|
97
|
+
if (v[vo + i] > c[co + i]) out[oo + (i >>> 5)] |= 1 << (i & 31);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export function hamming(a: Uint32Array, b: Uint32Array, bo: number, w: number): number {
|
|
102
|
+
let n = 0;
|
|
103
|
+
for (let i = 0; i < w; i++) {
|
|
104
|
+
let x = a[i] ^ b[bo + i];
|
|
105
|
+
x -= (x >>> 1) & 0x55555555;
|
|
106
|
+
x = (x & 0x33333333) + ((x >>> 2) & 0x33333333);
|
|
107
|
+
n += Math.imul((x + (x >>> 4)) & 0x0f0f0f0f, 0x01010101) >>> 24;
|
|
108
|
+
}
|
|
109
|
+
return n;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// ------------------------------------------------------------ top-k
|
|
113
|
+
|
|
114
|
+
/** Keeps the `k` smallest scores. A binary max-heap over parallel arrays. */
|
|
115
|
+
export class TopK<T> {
|
|
116
|
+
readonly #k: number;
|
|
117
|
+
readonly #scores: number[] = [];
|
|
118
|
+
readonly #items: T[] = [];
|
|
119
|
+
|
|
120
|
+
constructor(k: number) {
|
|
121
|
+
this.#k = Math.max(0, k);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
get size() {
|
|
125
|
+
return this.#scores.length;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** The score a new item must beat, or Infinity while not full. */
|
|
129
|
+
get bound() {
|
|
130
|
+
return this.#scores.length < this.#k ? Number.POSITIVE_INFINITY : this.#scores[0];
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
push(score: number, item: T) {
|
|
134
|
+
if (this.#k === 0) return;
|
|
135
|
+
const s = this.#scores;
|
|
136
|
+
const it = this.#items;
|
|
137
|
+
if (s.length < this.#k) {
|
|
138
|
+
s.push(score);
|
|
139
|
+
it.push(item);
|
|
140
|
+
let i = s.length - 1;
|
|
141
|
+
while (i > 0) {
|
|
142
|
+
const p = (i - 1) >> 1;
|
|
143
|
+
if (s[p] >= s[i]) break;
|
|
144
|
+
this.#swap(i, p);
|
|
145
|
+
i = p;
|
|
146
|
+
}
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
if (score >= s[0]) return;
|
|
150
|
+
s[0] = score;
|
|
151
|
+
it[0] = item;
|
|
152
|
+
let i = 0;
|
|
153
|
+
for (;;) {
|
|
154
|
+
const l = 2 * i + 1;
|
|
155
|
+
const r = l + 1;
|
|
156
|
+
let m = i;
|
|
157
|
+
if (l < s.length && s[l] > s[m]) m = l;
|
|
158
|
+
if (r < s.length && s[r] > s[m]) m = r;
|
|
159
|
+
if (m === i) break;
|
|
160
|
+
this.#swap(i, m);
|
|
161
|
+
i = m;
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** Ascending by score. */
|
|
166
|
+
sorted(): { score: number; item: T }[] {
|
|
167
|
+
return this.#scores
|
|
168
|
+
.map((score, i) => ({ score, item: this.#items[i] }))
|
|
169
|
+
.sort((a, b) => a.score - b.score);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
#swap(i: number, j: number) {
|
|
173
|
+
const s = this.#scores;
|
|
174
|
+
const it = this.#items;
|
|
175
|
+
[s[i], s[j]] = [s[j], s[i]];
|
|
176
|
+
[it[i], it[j]] = [it[j], it[i]];
|
|
177
|
+
}
|
|
178
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { mulberry32 } from "./kmeans.js";
|
|
3
|
+
import { prepare } from "./math.js";
|
|
4
|
+
import { buildSegment, MIN_TRAIN, parseList, SegmentIndex } from "./segment.js";
|
|
5
|
+
|
|
6
|
+
const D = 32;
|
|
7
|
+
|
|
8
|
+
function clustered(n: number, seed: number): { ids: Float64Array; vectors: Float32Array } {
|
|
9
|
+
const r = mulberry32(seed);
|
|
10
|
+
const centers = Array.from({ length: 20 }, () =>
|
|
11
|
+
Float32Array.from({ length: D }, () => r() * 2 - 1),
|
|
12
|
+
);
|
|
13
|
+
const vectors = new Float32Array(n * D);
|
|
14
|
+
for (let i = 0; i < n; i++) {
|
|
15
|
+
const c = centers[Math.floor(r() * centers.length)] as Float32Array;
|
|
16
|
+
vectors.set(
|
|
17
|
+
prepare(
|
|
18
|
+
c.map((x) => x + (r() - 0.5) * 0.6),
|
|
19
|
+
D,
|
|
20
|
+
"cosine",
|
|
21
|
+
),
|
|
22
|
+
i * D,
|
|
23
|
+
);
|
|
24
|
+
}
|
|
25
|
+
return { ids: Float64Array.from({ length: n }, (_, i) => i + 1), vectors };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
describe("segment codec", () => {
|
|
29
|
+
it("is one flat list below MIN_TRAIN and several lists from MIN_TRAIN on", () => {
|
|
30
|
+
const small = clustered(MIN_TRAIN - 1, 1);
|
|
31
|
+
const large = clustered(MIN_TRAIN, 1);
|
|
32
|
+
expect(buildSegment({ dims: D, metric: "cosine", ...small }).nlist).toBe(1);
|
|
33
|
+
expect(buildSegment({ dims: D, metric: "cosine", ...large }).nlist).toBeGreaterThan(1);
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
it("keeps every row exactly once, and a stored vector ranks itself first", () => {
|
|
37
|
+
const { ids, vectors } = clustered(3000, 2);
|
|
38
|
+
const built = buildSegment({ dims: D, metric: "cosine", ids, vectors });
|
|
39
|
+
const seg = new SegmentIndex(1, D, "cosine", built.centroids, built.counts);
|
|
40
|
+
const lists = built.lists.map((bytes, c) => parseList(bytes, built.counts[c] as number, D));
|
|
41
|
+
|
|
42
|
+
const seen = lists.flatMap((l) => Array.from(l.ids)).sort((a, b) => a - b);
|
|
43
|
+
expect(seen).toEqual(Array.from(ids));
|
|
44
|
+
|
|
45
|
+
const q = vectors.subarray(0, D);
|
|
46
|
+
let best = { id: -1, d: Number.POSITIVE_INFINITY };
|
|
47
|
+
for (const c of seg.probe(q, seg.nlist)) {
|
|
48
|
+
const data = lists[c];
|
|
49
|
+
if (!data) continue;
|
|
50
|
+
for (const cand of seg.filterList(q, c, data, 50)) {
|
|
51
|
+
const d = seg.scoreInt8(q, data, cand.row);
|
|
52
|
+
if (d < best.d) best = { id: cand.id, d };
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
expect(best.id).toBe(1);
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
it("rejects a list block of the wrong size", () => {
|
|
59
|
+
expect(() => parseList(new Uint8Array(10), 3, D)).toThrow(/list block has 10 bytes/);
|
|
60
|
+
});
|
|
61
|
+
});
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
import { kmeans, nearest } from "./kmeans.js";
|
|
2
|
+
import {
|
|
3
|
+
distance,
|
|
4
|
+
distanceInt8,
|
|
5
|
+
hamming,
|
|
6
|
+
quantizeInt8,
|
|
7
|
+
residualBits,
|
|
8
|
+
TopK,
|
|
9
|
+
wordsFor,
|
|
10
|
+
} from "./math.js";
|
|
11
|
+
import type { Metric } from "./types.js";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* An IVF segment as storage-neutral parts. This module does no I/O; a store
|
|
15
|
+
* decides where the parts live.
|
|
16
|
+
*
|
|
17
|
+
* per list: a centroid f32[dims] and a row count
|
|
18
|
+
* per list, the searchable block (little-endian, each section padded to 8 bytes):
|
|
19
|
+
* ids f64[count] | bits u32[count × words] | rnorm f32[count] | cdot f32[count]
|
|
20
|
+
* scales f32[count] | codes i8[count × dims]
|
|
21
|
+
* per list, the float block f32[count × dims] (exact re-rank, lossless merge, read-back)
|
|
22
|
+
*
|
|
23
|
+
* bits = signs of the residual r = x - c (c = the list centroid)
|
|
24
|
+
* rnorm = |r|, cdot = c·r. With them the 1-bit stage estimates the real
|
|
25
|
+
* metric, RaBitQ-style: r_q·r ≈ |r_q| |r| cos(π · hamming / dims).
|
|
26
|
+
*/
|
|
27
|
+
const align8 = (n: number) => (n + 7) & ~7;
|
|
28
|
+
|
|
29
|
+
export interface ListLayout {
|
|
30
|
+
count: number;
|
|
31
|
+
idsAt: number;
|
|
32
|
+
bitsAt: number;
|
|
33
|
+
rnormAt: number;
|
|
34
|
+
cdotAt: number;
|
|
35
|
+
scalesAt: number;
|
|
36
|
+
codesAt: number;
|
|
37
|
+
/** Bytes of the searchable block. */
|
|
38
|
+
length: number;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export function listLayout(count: number, dims: number): ListLayout {
|
|
42
|
+
const w = wordsFor(dims);
|
|
43
|
+
const idsAt = 0;
|
|
44
|
+
const bitsAt = align8(idsAt + 8 * count);
|
|
45
|
+
const rnormAt = align8(bitsAt + 4 * w * count);
|
|
46
|
+
const cdotAt = align8(rnormAt + 4 * count);
|
|
47
|
+
const scalesAt = align8(cdotAt + 4 * count);
|
|
48
|
+
const codesAt = align8(scalesAt + 4 * count);
|
|
49
|
+
const length = align8(codesAt + dims * count);
|
|
50
|
+
return { count, idsAt, bitsAt, rnormAt, cdotAt, scalesAt, codesAt, length };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// ------------------------------------------------------------------ build
|
|
54
|
+
|
|
55
|
+
export interface BuildInput {
|
|
56
|
+
dims: number;
|
|
57
|
+
metric: Metric;
|
|
58
|
+
ids: Float64Array;
|
|
59
|
+
/** n × dims, already prepared (normalized for cosine). */
|
|
60
|
+
vectors: Float32Array;
|
|
61
|
+
nlist?: number;
|
|
62
|
+
seed?: number;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export interface BuiltSegment {
|
|
66
|
+
nlist: number;
|
|
67
|
+
counts: Uint32Array;
|
|
68
|
+
/** nlist × dims */
|
|
69
|
+
centroids: Float32Array;
|
|
70
|
+
/** Searchable block per list. */
|
|
71
|
+
lists: Uint8Array[];
|
|
72
|
+
/** Float32 block per list. */
|
|
73
|
+
floats: Uint8Array[];
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** Below this size a segment is a single flat list: training would not pay off. */
|
|
77
|
+
export const MIN_TRAIN = 2048;
|
|
78
|
+
|
|
79
|
+
export function defaultNlist(n: number) {
|
|
80
|
+
if (n < MIN_TRAIN) return 1;
|
|
81
|
+
return Math.max(1, Math.min(1024, Math.round(Math.sqrt(n))));
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function buildSegment(input: BuildInput): BuiltSegment {
|
|
85
|
+
const { dims: d, metric, ids, vectors } = input;
|
|
86
|
+
const n = ids.length;
|
|
87
|
+
const nlist = Math.max(1, Math.min(input.nlist ?? defaultNlist(n), Math.max(1, n)));
|
|
88
|
+
|
|
89
|
+
let centroids: Float32Array;
|
|
90
|
+
if (nlist === 1) {
|
|
91
|
+
centroids = new Float32Array(d);
|
|
92
|
+
for (let i = 0; i < n; i++) for (let j = 0; j < d; j++) centroids[j] += vectors[i * d + j];
|
|
93
|
+
if (n > 0) for (let j = 0; j < d; j++) centroids[j] /= n;
|
|
94
|
+
} else {
|
|
95
|
+
centroids = kmeans(vectors, n, d, nlist, metric, { seed: input.seed });
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const assign = new Uint32Array(n);
|
|
99
|
+
const counts = new Uint32Array(nlist);
|
|
100
|
+
for (let i = 0; i < n; i++) {
|
|
101
|
+
const c = nlist === 1 ? 0 : nearest(metric, vectors, i * d, centroids, nlist, d);
|
|
102
|
+
assign[i] = c;
|
|
103
|
+
counts[c]++;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const w = wordsFor(d);
|
|
107
|
+
const layouts = Array.from(counts, (count) => listLayout(count, d));
|
|
108
|
+
const lists = layouts.map((l) => new Uint8Array(l.length));
|
|
109
|
+
const floats = Array.from(counts, (count) => new Uint8Array(4 * count * d));
|
|
110
|
+
const views = layouts.map((l, c) => {
|
|
111
|
+
const buf = lists[c].buffer;
|
|
112
|
+
return {
|
|
113
|
+
ids: new Float64Array(buf, l.idsAt, l.count),
|
|
114
|
+
bits: new Uint32Array(buf, l.bitsAt, l.count * w),
|
|
115
|
+
rnorm: new Float32Array(buf, l.rnormAt, l.count),
|
|
116
|
+
cdot: new Float32Array(buf, l.cdotAt, l.count),
|
|
117
|
+
scales: new Float32Array(buf, l.scalesAt, l.count),
|
|
118
|
+
codes: new Int8Array(buf, l.codesAt, l.count * d),
|
|
119
|
+
floats: new Float32Array(floats[c].buffer, 0, l.count * d),
|
|
120
|
+
};
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
const fill = new Uint32Array(nlist);
|
|
124
|
+
for (let i = 0; i < n; i++) {
|
|
125
|
+
const c = assign[i];
|
|
126
|
+
const j = fill[c]++;
|
|
127
|
+
const v = views[c];
|
|
128
|
+
v.ids[j] = ids[i];
|
|
129
|
+
residualBits(vectors, i * d, centroids, c * d, d, v.bits, j * w);
|
|
130
|
+
const [rn, cd] = residualStats(vectors, i * d, centroids, c * d, d);
|
|
131
|
+
v.rnorm[j] = rn;
|
|
132
|
+
v.cdot[j] = cd;
|
|
133
|
+
v.scales[j] = quantizeInt8(vectors, i * d, d, v.codes, j * d);
|
|
134
|
+
v.floats.set(vectors.subarray(i * d, i * d + d), j * d);
|
|
135
|
+
}
|
|
136
|
+
return { nlist, counts, centroids, lists, floats };
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** [|x - c|, c·(x - c)] */
|
|
140
|
+
function residualStats(x: Float32Array, xo: number, c: Float32Array, co: number, d: number) {
|
|
141
|
+
let nn = 0;
|
|
142
|
+
let cd = 0;
|
|
143
|
+
for (let i = 0; i < d; i++) {
|
|
144
|
+
const r = x[xo + i] - c[co + i];
|
|
145
|
+
nn += r * r;
|
|
146
|
+
cd += c[co + i] * r;
|
|
147
|
+
}
|
|
148
|
+
return [Math.sqrt(nn), cd];
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
// ------------------------------------------------------------------ read
|
|
152
|
+
|
|
153
|
+
export interface ListData {
|
|
154
|
+
ids: Float64Array;
|
|
155
|
+
bits: Uint32Array;
|
|
156
|
+
rnorm: Float32Array;
|
|
157
|
+
cdot: Float32Array;
|
|
158
|
+
scales: Float32Array;
|
|
159
|
+
codes: Int8Array;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Typed views over a searchable block (copied only when it does not start at offset 0). */
|
|
163
|
+
export function parseList(bytes: Uint8Array, count: number, dims: number): ListData {
|
|
164
|
+
const l = listLayout(count, dims);
|
|
165
|
+
if (bytes.byteLength !== l.length) {
|
|
166
|
+
throw new Error(`vector-index: list block has ${bytes.byteLength} bytes, expected ${l.length}`);
|
|
167
|
+
}
|
|
168
|
+
const buf = bytes.byteOffset === 0 ? bytes.buffer : bytes.slice().buffer;
|
|
169
|
+
const w = wordsFor(dims);
|
|
170
|
+
return {
|
|
171
|
+
ids: new Float64Array(buf, l.idsAt, count),
|
|
172
|
+
bits: new Uint32Array(buf, l.bitsAt, count * w),
|
|
173
|
+
rnorm: new Float32Array(buf, l.rnormAt, count),
|
|
174
|
+
cdot: new Float32Array(buf, l.cdotAt, count),
|
|
175
|
+
scales: new Float32Array(buf, l.scalesAt, count),
|
|
176
|
+
codes: new Int8Array(buf, l.codesAt, count * dims),
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
export interface Candidate {
|
|
181
|
+
list: number;
|
|
182
|
+
row: number;
|
|
183
|
+
id: number;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** The in-memory part of a segment: centroids and list sizes. List blocks are fetched by the caller. */
|
|
187
|
+
export class SegmentIndex {
|
|
188
|
+
constructor(
|
|
189
|
+
readonly gen: number,
|
|
190
|
+
readonly dims: number,
|
|
191
|
+
readonly metric: Metric,
|
|
192
|
+
readonly centroids: Float32Array,
|
|
193
|
+
readonly counts: Uint32Array,
|
|
194
|
+
) {}
|
|
195
|
+
|
|
196
|
+
get nlist() {
|
|
197
|
+
return this.counts.length;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** The `nprobe` non-empty lists whose centroids are closest to the query. */
|
|
201
|
+
probe(query: Float32Array, nprobe: number): number[] {
|
|
202
|
+
const m: Metric = this.metric === "l2" ? "l2" : "dot";
|
|
203
|
+
const top = new TopK<number>(Math.min(nprobe, this.nlist));
|
|
204
|
+
for (let c = 0; c < this.nlist; c++) {
|
|
205
|
+
if (this.counts[c] === 0) continue;
|
|
206
|
+
top.push(distance(m, query, 0, this.centroids, c * this.dims, this.dims), c);
|
|
207
|
+
}
|
|
208
|
+
return top.sorted().map((e) => e.item);
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* Stage 1: the `limit` rows of a list with the best estimated distance, from
|
|
213
|
+
* residual sign bits plus the stored residual norm and centroid projection.
|
|
214
|
+
*/
|
|
215
|
+
filterList(
|
|
216
|
+
query: Float32Array,
|
|
217
|
+
c: number,
|
|
218
|
+
data: ListData,
|
|
219
|
+
limit: number,
|
|
220
|
+
keep?: (id: number) => boolean,
|
|
221
|
+
): Candidate[] {
|
|
222
|
+
const d = this.dims;
|
|
223
|
+
const w = wordsFor(d);
|
|
224
|
+
const co = c * d;
|
|
225
|
+
const qb = new Uint32Array(w);
|
|
226
|
+
residualBits(query, 0, this.centroids, co, d, qb, 0);
|
|
227
|
+
const [qn, qcd] = residualStats(query, 0, this.centroids, co, d);
|
|
228
|
+
let cc = 0;
|
|
229
|
+
for (let i = 0; i < d; i++) cc += this.centroids[co + i] * this.centroids[co + i];
|
|
230
|
+
const qc = cc + qcd; // q·c
|
|
231
|
+
const angle = Math.PI / d;
|
|
232
|
+
const l2 = this.metric === "l2";
|
|
233
|
+
const top = new TopK<Candidate>(limit);
|
|
234
|
+
for (let r = 0; r < data.ids.length; r++) {
|
|
235
|
+
const id = data.ids[r];
|
|
236
|
+
if (keep && !keep(id)) continue;
|
|
237
|
+
const rr = qn * data.rnorm[r] * Math.cos(angle * hamming(qb, data.bits, r * w, w));
|
|
238
|
+
// q·x = q·c + c·r_x + r_q·r_x ; |q-x|² = |r_q|² + |r_x|² - 2 r_q·r_x
|
|
239
|
+
const est = l2 ? qn * qn + data.rnorm[r] * data.rnorm[r] - 2 * rr : -(qc + data.cdot[r] + rr);
|
|
240
|
+
if (est < top.bound) top.push(est, { list: c, row: r, id });
|
|
241
|
+
}
|
|
242
|
+
return top.sorted().map((e) => e.item);
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** Stage 2: approximate distance from the int8 codes. */
|
|
246
|
+
scoreInt8(query: Float32Array, data: ListData, row: number): number {
|
|
247
|
+
return distanceInt8(
|
|
248
|
+
this.metric,
|
|
249
|
+
query,
|
|
250
|
+
data.codes,
|
|
251
|
+
row * this.dims,
|
|
252
|
+
data.scales[row],
|
|
253
|
+
this.dims,
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
import type { Db } from "@statewalker/db-api";
|
|
2
|
+
import { type BuiltSegment, type ListData, parseList, SegmentIndex } from "./segment.js";
|
|
3
|
+
import { float32Bytes, type Metric, toFloat32 } from "./types.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Largest BLOB written in one row. Durable Object SQLite rejects values over
|
|
7
|
+
* ~2 MB ("string or blob too big"); 1 MiB leaves headroom.
|
|
8
|
+
*/
|
|
9
|
+
export const PART_BYTES = 1024 * 1024;
|
|
10
|
+
|
|
11
|
+
export interface SegmentRef {
|
|
12
|
+
gen: number;
|
|
13
|
+
count: number;
|
|
14
|
+
nlist: number;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Segment rows: one centroid row per list, and each list's searchable and
|
|
19
|
+
* float32 blocks split into parts. Reads go through an LRU cache: a
|
|
20
|
+
* generation is immutable, so cached blocks never go stale.
|
|
21
|
+
*/
|
|
22
|
+
export class SqlSegmentStore {
|
|
23
|
+
readonly #db: Db;
|
|
24
|
+
readonly #dims: number;
|
|
25
|
+
readonly #t: { centroids: string; seg: string; f32: string };
|
|
26
|
+
readonly #cache: Lru<ListData | Float32Array>;
|
|
27
|
+
|
|
28
|
+
constructor(db: Db, prefix: string, dims: number, cacheBytes = 64 * 1024 * 1024) {
|
|
29
|
+
this.#db = db;
|
|
30
|
+
this.#dims = dims;
|
|
31
|
+
this.#t = { centroids: `${prefix}centroids`, seg: `${prefix}seg`, f32: `${prefix}f32` };
|
|
32
|
+
this.#cache = new Lru(cacheBytes);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
schema(): string[] {
|
|
36
|
+
const { centroids, seg, f32 } = this.#t;
|
|
37
|
+
return [
|
|
38
|
+
`CREATE TABLE IF NOT EXISTS ${centroids}(gen INTEGER, list INTEGER, count INTEGER NOT NULL,
|
|
39
|
+
centroid BLOB NOT NULL, PRIMARY KEY (gen, list)) WITHOUT ROWID`,
|
|
40
|
+
`CREATE TABLE IF NOT EXISTS ${seg}(gen INTEGER, list INTEGER, part INTEGER,
|
|
41
|
+
bytes BLOB NOT NULL, PRIMARY KEY (gen, list, part)) WITHOUT ROWID`,
|
|
42
|
+
`CREATE TABLE IF NOT EXISTS ${f32}(gen INTEGER, list INTEGER, part INTEGER,
|
|
43
|
+
bytes BLOB NOT NULL, PRIMARY KEY (gen, list, part)) WITHOUT ROWID`,
|
|
44
|
+
];
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Writes every row of a built segment. Call inside `inTransaction`. */
|
|
48
|
+
async write(tx: Db, gen: number, built: BuiltSegment): Promise<void> {
|
|
49
|
+
const d = this.#dims;
|
|
50
|
+
for (let c = 0; c < built.nlist; c++) {
|
|
51
|
+
await tx.query(
|
|
52
|
+
`INSERT INTO ${this.#t.centroids}(gen, list, count, centroid) VALUES (?, ?, ?, ?)`,
|
|
53
|
+
[gen, c, built.counts[c], float32Bytes(built.centroids.subarray(c * d, (c + 1) * d))],
|
|
54
|
+
);
|
|
55
|
+
await writeParts(tx, this.#t.seg, gen, c, built.lists[c] as Uint8Array);
|
|
56
|
+
await writeParts(tx, this.#t.f32, gen, c, built.floats[c] as Uint8Array);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Loads the in-memory part (centroids, list sizes) of a committed segment. */
|
|
61
|
+
async open(ref: SegmentRef, metric: Metric): Promise<SegmentIndex> {
|
|
62
|
+
const d = this.#dims;
|
|
63
|
+
const rows = await this.#db.query<{ list: number; count: number; centroid: Uint8Array }>(
|
|
64
|
+
`SELECT list, count, centroid FROM ${this.#t.centroids} WHERE gen = ? ORDER BY list`,
|
|
65
|
+
[ref.gen],
|
|
66
|
+
);
|
|
67
|
+
if (rows.length !== ref.nlist) {
|
|
68
|
+
throw new Error(
|
|
69
|
+
`vector-index: segment ${ref.gen} has ${rows.length} lists, expected ${ref.nlist}`,
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
const centroids = new Float32Array(ref.nlist * d);
|
|
73
|
+
const counts = new Uint32Array(ref.nlist);
|
|
74
|
+
for (const r of rows) {
|
|
75
|
+
const c = Number(r.list);
|
|
76
|
+
centroids.set(toFloat32(r.centroid), c * d);
|
|
77
|
+
counts[c] = Number(r.count);
|
|
78
|
+
}
|
|
79
|
+
return new SegmentIndex(ref.gen, d, metric, centroids, counts);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Searchable blocks of lists `cs`: cached ones from memory, the rest in one query. */
|
|
83
|
+
async lists(seg: SegmentIndex, cs: number[]): Promise<ListData[]> {
|
|
84
|
+
const out = new Map<number, ListData>();
|
|
85
|
+
const missing: number[] = [];
|
|
86
|
+
for (const c of cs) {
|
|
87
|
+
const hit = this.#cache.get(`s:${seg.gen}:${c}`) as ListData | undefined;
|
|
88
|
+
if (hit) out.set(c, hit);
|
|
89
|
+
else missing.push(c);
|
|
90
|
+
}
|
|
91
|
+
if (missing.length > 0) {
|
|
92
|
+
const blocks = await readParts(this.#db, this.#t.seg, seg.gen, missing);
|
|
93
|
+
for (const c of missing) {
|
|
94
|
+
const bytes = blocks.get(c) ?? new Uint8Array(0);
|
|
95
|
+
const data = parseList(bytes, seg.counts[c] as number, this.#dims);
|
|
96
|
+
this.#cache.set(`s:${seg.gen}:${c}`, data, bytes.byteLength);
|
|
97
|
+
out.set(c, data);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return cs.map((c) => out.get(c) as ListData);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** Every float32 vector of list `c` (count × dims). */
|
|
104
|
+
async floats(seg: SegmentIndex, c: number): Promise<Float32Array> {
|
|
105
|
+
const key = `f:${seg.gen}:${c}`;
|
|
106
|
+
const hit = this.#cache.get(key) as Float32Array | undefined;
|
|
107
|
+
if (hit) return hit;
|
|
108
|
+
const blocks = await readParts(this.#db, this.#t.f32, seg.gen, [c]);
|
|
109
|
+
const floats = toFloat32(blocks.get(c) ?? new Uint8Array(0));
|
|
110
|
+
this.#cache.set(key, floats, floats.byteLength);
|
|
111
|
+
return floats;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** Deletes the rows of `gens`. Call inside `inTransaction`. */
|
|
115
|
+
async drop(tx: Db, gens: number[]): Promise<void> {
|
|
116
|
+
const json = JSON.stringify(gens);
|
|
117
|
+
for (const table of Object.values(this.#t)) {
|
|
118
|
+
await tx.query(`DELETE FROM ${table} WHERE gen IN (SELECT value FROM json_each(?))`, [json]);
|
|
119
|
+
}
|
|
120
|
+
for (const gen of gens) this.#cache.deletePrefix(`s:${gen}:`, `f:${gen}:`);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Deletes rows of every generation not in `live` (left by a crash before a reap). */
|
|
124
|
+
async sweep(tx: Db, live: number[]): Promise<void> {
|
|
125
|
+
const json = JSON.stringify(live);
|
|
126
|
+
for (const table of Object.values(this.#t)) {
|
|
127
|
+
await tx.query(`DELETE FROM ${table} WHERE gen NOT IN (SELECT value FROM json_each(?))`, [
|
|
128
|
+
json,
|
|
129
|
+
]);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
async function writeParts(tx: Db, table: string, gen: number, list: number, bytes: Uint8Array) {
|
|
135
|
+
for (let part = 0, at = 0; at < bytes.byteLength; part++, at += PART_BYTES) {
|
|
136
|
+
await tx.query(`INSERT INTO ${table}(gen, list, part, bytes) VALUES (?, ?, ?, ?)`, [
|
|
137
|
+
gen,
|
|
138
|
+
list,
|
|
139
|
+
part,
|
|
140
|
+
bytes.slice(at, at + PART_BYTES),
|
|
141
|
+
]);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** The joined parts of each list in `lists`, as fresh arrays starting at offset 0. */
|
|
146
|
+
async function readParts(
|
|
147
|
+
db: Db,
|
|
148
|
+
table: string,
|
|
149
|
+
gen: number,
|
|
150
|
+
lists: number[],
|
|
151
|
+
): Promise<Map<number, Uint8Array>> {
|
|
152
|
+
const rows = await db.query<{ list: number; bytes: Uint8Array }>(
|
|
153
|
+
`SELECT list, bytes FROM ${table}
|
|
154
|
+
WHERE gen = ? AND list IN (SELECT value FROM json_each(?)) ORDER BY list, part`,
|
|
155
|
+
[gen, JSON.stringify(lists)],
|
|
156
|
+
);
|
|
157
|
+
const parts = new Map<number, Uint8Array[]>();
|
|
158
|
+
for (const r of rows) {
|
|
159
|
+
const list = Number(r.list);
|
|
160
|
+
const acc = parts.get(list) ?? [];
|
|
161
|
+
acc.push(r.bytes);
|
|
162
|
+
parts.set(list, acc);
|
|
163
|
+
}
|
|
164
|
+
const out = new Map<number, Uint8Array>();
|
|
165
|
+
for (const [list, ps] of parts) {
|
|
166
|
+
const joined = new Uint8Array(ps.reduce((n, p) => n + p.byteLength, 0));
|
|
167
|
+
let at = 0;
|
|
168
|
+
for (const p of ps) {
|
|
169
|
+
joined.set(p, at);
|
|
170
|
+
at += p.byteLength;
|
|
171
|
+
}
|
|
172
|
+
out.set(list, joined);
|
|
173
|
+
}
|
|
174
|
+
return out;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** Byte-budgeted LRU; Map order is LRU order (re-inserted on every hit). */
|
|
178
|
+
class Lru<V> {
|
|
179
|
+
readonly #max: number;
|
|
180
|
+
readonly #map = new Map<string, { value: V; size: number }>();
|
|
181
|
+
#bytes = 0;
|
|
182
|
+
|
|
183
|
+
constructor(maxBytes: number) {
|
|
184
|
+
this.#max = maxBytes;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
get(key: string): V | undefined {
|
|
188
|
+
const e = this.#map.get(key);
|
|
189
|
+
if (!e) return undefined;
|
|
190
|
+
this.#map.delete(key);
|
|
191
|
+
this.#map.set(key, e);
|
|
192
|
+
return e.value;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
set(key: string, value: V, size: number) {
|
|
196
|
+
const old = this.#map.get(key);
|
|
197
|
+
if (old) {
|
|
198
|
+
this.#map.delete(key);
|
|
199
|
+
this.#bytes -= old.size;
|
|
200
|
+
}
|
|
201
|
+
this.#map.set(key, { value, size });
|
|
202
|
+
this.#bytes += size;
|
|
203
|
+
for (const [k, e] of this.#map) {
|
|
204
|
+
if (this.#bytes <= this.#max) break;
|
|
205
|
+
this.#map.delete(k);
|
|
206
|
+
this.#bytes -= e.size;
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
deletePrefix(...prefixes: string[]) {
|
|
211
|
+
for (const [k, e] of this.#map) {
|
|
212
|
+
if (prefixes.some((p) => k.startsWith(p))) {
|
|
213
|
+
this.#map.delete(k);
|
|
214
|
+
this.#bytes -= e.size;
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
}
|