feat(migrations): HNSW index for 1024-dim embeddings (bge-m3)
Upstream's 000002 only adds HNSW partial indexes for dim=3584 (OpenAI text-embedding-3-large) and dim=798. Any deployment binding bge-m3 (the default local embedder · 1024 dim · what localhub-embedder ships) falls back to a sequential scan of the entire embeddings table on every vector query. Functionally correct, but ~100-500ms per query depending on KB size · dominates p50 latency on chat/agent paths. Add a partial HNSW index targeting dim=1024 with the same expression and opclass as the other two (embedding::halfvec(1024) halfvec_cosine_ops). Matches the SearchEmbedding query in repository.go verbatim so the planner picks it up automatically. Local measurement on a 63k-row embeddings table (Robustel_Support KB): before · seq scan: ~100-500ms per vector query (varies) after · index scan: ~28-30ms CONCURRENTLY is skipped because plpgsql DO blocks open an implicit transaction and CREATE INDEX CONCURRENTLY cannot run inside one. On fresh installs the embeddings table is empty so this is instant. For production backfill the operator should build the index manually using CONCURRENTLY first; the IF NOT EXISTS guard then makes this migration a no-op. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
-- Down migration: drop the 1024-dim HNSW partial index added in 000044.
|
||||
DROP INDEX IF EXISTS embeddings_embedding_idx_1024;
|
||||
@@ -0,0 +1,39 @@
|
||||
-- Migration 000044: HNSW index for bge-m3 / 1024-dim embeddings
|
||||
--
|
||||
-- Upstream's 000002 only created HNSW partial indexes for dim=3584 (OpenAI
|
||||
-- text-embedding-3-large) and dim=798. Both queries fall through to a
|
||||
-- sequential scan on the 1024-dim halfvec column when the bound embedder
|
||||
-- is bge-m3 — which is the default for any on-device deployment using
|
||||
-- localhub-embedder.
|
||||
--
|
||||
-- Symptom: vector recall stays "correct but slow" (seq scan of all rows in
|
||||
-- the embeddings table per query, ~100-500ms by KB size). Downstream agents
|
||||
-- that probe latency-sensitive endpoints assumed degradation.
|
||||
--
|
||||
-- Fix: same partial-index pattern, dim=1024. Matches the exact expression
|
||||
-- used in repository.go SearchEmbedding query (embedding::halfvec(1024) <=>
|
||||
-- $1::halfvec(1024)) so the planner picks it up automatically.
|
||||
--
|
||||
-- Note: CONCURRENTLY is not used here because plpgsql DO blocks open an
|
||||
-- implicit transaction and CREATE INDEX CONCURRENTLY can't run inside one.
|
||||
-- For a fresh install this is a no-op (empty table); for production
|
||||
-- backfill the operator should build the index manually using
|
||||
-- CREATE INDEX CONCURRENTLY before applying this migration, then this
|
||||
-- block becomes idempotent via IF NOT EXISTS.
|
||||
|
||||
DO $$
|
||||
BEGIN
|
||||
IF EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector') THEN
|
||||
IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'embeddings_embedding_idx_1024' OR indexname LIKE 'embeddings_embedding%1024%') THEN
|
||||
CREATE INDEX embeddings_embedding_idx_1024 ON embeddings
|
||||
USING hnsw ((embedding::halfvec(1024)) halfvec_cosine_ops)
|
||||
WITH (m = 16, ef_construction = 64)
|
||||
WHERE (dimension = 1024);
|
||||
RAISE NOTICE '[Migration 000044] Created HNSW index for dimension 1024 (bge-m3)';
|
||||
ELSE
|
||||
RAISE NOTICE '[Migration 000044] HNSW index for dimension 1024 already exists';
|
||||
END IF;
|
||||
ELSE
|
||||
RAISE NOTICE '[Migration 000044] pgvector extension not installed · skipping';
|
||||
END IF;
|
||||
END $$;
|
||||
Reference in New Issue
Block a user